archastro.platform.v1.resources.agents
1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. 2# This file is auto-generated by @archastro/sdk-generator. Do not edit. 3# Content hash: 84e4708f4187 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 WorkingMemoryEntry, 34 WorkingMemoryEntryListResponse, 35) 36from ...types.threads import Thread 37from ...types.workflows import WorkflowWorkItemClaim, WorkflowWorkItemList 38 39 40class AgentAgentComputerCreateInputAclAddItem(TypedDict, total=False): 41 actions: Required[list[str]] 42 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 43 principal: str | None 44 '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"`.' 45 principal_type: Required[str] 46 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 47 48 49class AgentAgentComputerCreateInputAclGrantsItem(TypedDict, total=False): 50 actions: Required[list[str]] 51 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 52 principal: str | None 53 '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"`.' 54 principal_type: Required[str] 55 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 56 57 58class AgentAgentComputerCreateInputAclRemoveItem(TypedDict, total=False): 59 principal: str | None 60 '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"`.' 61 principal_type: Required[str] 62 'The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 63 64 65class AgentAgentComputerCreateInputAcl(TypedDict, total=False): 66 add: list[AgentAgentComputerCreateInputAclAddItem] | None 67 "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`." 68 grants: list[AgentAgentComputerCreateInputAclGrantsItem] | None 69 "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`." 70 remove: list[AgentAgentComputerCreateInputAclRemoveItem] | None 71 "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`." 72 73 74class AgentAgentComputerCreateInput(TypedDict, total=False): 75 "Provision a computer for an agent" 76 77 acl: AgentAgentComputerCreateInputAcl | None 78 "Initial access control list." 79 config: dict[str, Any] | None 80 "Provider-specific configuration for the computer. Supported keys vary by provider. A top-level `provider` takes precedence over `config.provider`." 81 lookup_key: str | None 82 "Stable, user-defined key for this computer. Must be unique within the app. Use it to look up the computer without storing its ID." 83 metadata: dict[str, Any] | None 84 "Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads." 85 name: Required[str] 86 "Human-readable display name for the computer." 87 provider: str | None 88 'Compute backend for the computer: `"sprites"` (Fly Sprites, the default), `"vercel"` (Vercel Sandbox) or `"e2b"` (E2B). Folded into `config.provider`.' 89 region: str | None 90 'Region in which to provision the computer, e.g. `"iad"`. Defaults to `"iad"` when omitted.' 91 92 93class AgentAgentEnvVarCreateInput(TypedDict, total=False): 94 "Create an agent environment variable" 95 96 description: str | None 97 "Optional human-readable note describing what the variable is used for." 98 key: Required[str] 99 "Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent." 100 value: Required[str] 101 "Plaintext secret value to store. The value is encrypted at rest and never returned in full." 102 103 104class AgentAgentInstallationCreateInputIntegration(TypedDict, total=False): 105 access_token: str | None 106 "OAuth access token or static API key used by `oauth` providers to authenticate requests on behalf of the user." 107 installation_id: str | None 108 "External installation identifier used by `app_installation` providers, e.g. a GitHub App installation ID or a Slack team ID." 109 metadata: dict[str, Any] | None 110 'Arbitrary provider-specific metadata, e.g. `{"bot_user_id": "U012AB3CD"}` for Slack. Stored alongside the integration and made available to connector logic.' 111 refresh_token: str | None 112 "OAuth refresh token used to obtain a new `access_token` when the current one expires. Omit for providers that do not issue refresh tokens." 113 workspace_key: str | None 114 "Provider-specific workspace or team identifier, e.g. a Slack workspace slug. Used to scope the integration to a particular workspace." 115 116 117class AgentAgentInstallationCreateInput(TypedDict, total=False): 118 "Create an installation" 119 120 config: dict[str, Any] | None 121 "Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration." 122 integration: AgentAgentInstallationCreateInputIntegration | None 123 "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`." 124 kind: Required[str] 125 '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.' 126 lookup_key: str | None 127 "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." 128 shared_integration: str | None 129 "ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with `integration`." 130 131 132AgentAgentToolCreateInput = TypedDict( 133 "AgentAgentToolCreateInput", 134 { 135 "async": bool | None, 136 "builtin_tool_config": dict[str, Any] | None, 137 "builtin_tool_key": str | None, 138 "config": str | None, 139 "description": str | None, 140 "handler_type": str | None, 141 "kind": Required[str], # Tool kind. One of `"builtin"` or `"custom"`. 142 "lookup_key": str | None, 143 "metadata": dict[str, Any] | None, 144 "name": str | None, # Display name for the tool. Required when `kind` is `"custom"`. 145 "name_prefix": str | None, 146 "parameters": dict[str, Any] | None, 147 "status": str | None, 148 }, 149 total=False, 150) 151""" 152Create an agent tool 153 154Attributes: 155 async: When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools. 156 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. 157 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. 158 config: Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools. 159 description: Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to `"custom"` tools. 160 handler_type: Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools. 161 kind: Tool kind. One of `"builtin"` or `"custom"`. 162 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. 163 metadata: Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform. 164 name: Display name for the tool. Required when `kind` is `"custom"`. 165 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. 166 parameters: JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to `"custom"` tools. 167 status: Initial status of the tool. One of `"draft"` or `"active"`. Defaults to `"draft"` when omitted. 168""" 169 170 171class AgentWorkingMemoryUpdateInput(TypedDict, total=False): 172 "Update a working memory entry" 173 174 expires_at: datetime | None 175 "New expiry for the entry (ISO 8601). Pass `null` to remove the expiry so the entry never expires. Omit to keep the current expiry." 176 value: str | None 177 "Replacement string value to store under the entry's key. Maximum 65,536 characters." 178 179 180class AgentWorkItemClaimInput(TypedDict, total=False): 181 "Claim or resume workflow work for an agent" 182 183 execution: str | None 184 "Optional durable execution ID filter." 185 lease_owner: Required[str] 186 "Caller-generated random UUID lease token." 187 lease_seconds: int | None 188 "Lease duration from 15 through 3600 seconds. Defaults to 300." 189 work_item: str | None 190 "Saved work item ID to resume or reclaim." 191 192 193class AgentCreateInputAclAddItem(TypedDict, total=False): 194 actions: Required[list[str]] 195 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 196 principal: str | None 197 '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"`.' 198 principal_type: Required[str] 199 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 200 201 202class AgentCreateInputAclGrantsItem(TypedDict, total=False): 203 actions: Required[list[str]] 204 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 205 principal: str | None 206 '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"`.' 207 principal_type: Required[str] 208 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 209 210 211class AgentCreateInputAclRemoveItem(TypedDict, total=False): 212 principal: str | None 213 '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"`.' 214 principal_type: Required[str] 215 'The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 216 217 218class AgentCreateInputAcl(TypedDict, total=False): 219 add: list[AgentCreateInputAclAddItem] | None 220 "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`." 221 grants: list[AgentCreateInputAclGrantsItem] | None 222 "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`." 223 remove: list[AgentCreateInputAclRemoveItem] | None 224 "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`." 225 226 227class AgentCreateInputProfilePicture(TypedDict): 228 data: str 229 "Base64-encoded binary content of the image." 230 filename: str 231 "Original filename of the image, e.g. `avatar.png`." 232 mime_type: str 233 "MIME type of the image, e.g. `image/png` or `image/jpeg`." 234 235 236class AgentCreateInputTemplateBundleConfigsItem(TypedDict, total=False): 237 content: Required[str] 238 "Full text content of the configuration file." 239 content_type: str | None 240 'MIME type of the configuration content, e.g. `"application/x-yaml"` or `"application/json"`. `null` if not specified.' 241 relative_path: Required[str] 242 "Bundle-relative path to this config file. The path determines the config kind and its storage identity within the installation." 243 244 245class AgentCreateInputTemplateBundleSetupActionsItem(TypedDict, total=False): 246 depends_on: list[str] | None 247 "List of other setup action identifiers that must be completed before this action becomes actionable." 248 description: str | None 249 "Markdown-formatted instructions or context shown beneath the checklist item. `null` if not provided." 250 kind: Required[str] 251 '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).' 252 params: dict[str, Any] | None 253 '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`.' 254 required: bool | None 255 "When `true`, this action must be completed before the checklist progress bar reaches 100%. Defaults to `true`." 256 sort_order: int | None 257 "Numeric sort position controlling the display order of this action in the checklist. Defaults to `0` when not specified." 258 title: Required[str] 259 "Short human-readable label displayed in the setup checklist." 260 verify_config: dict[str, Any] | None 261 '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.' 262 263 264class AgentCreateInputTemplateBundleSkillsItemFilesItem(TypedDict, total=False): 265 content: Required[str] 266 "Full text content of the file." 267 content_type: str | None 268 "MIME type of the file content. Defaults to a value inferred from the file extension when omitted." 269 relative_path: Required[str] 270 'Path of this file relative to the skill folder root, e.g. `"skills/my-skill/helpers.md"`.' 271 272 273class AgentCreateInputTemplateBundleSkillsItem(TypedDict, total=False): 274 content: Required[str] 275 "Full text content of the `SKILL.md` file." 276 content_type: str | None 277 "MIME type of the `SKILL.md` content. Defaults to `text/markdown` when omitted." 278 files: list[AgentCreateInputTemplateBundleSkillsItemFilesItem] | None 279 "Additional files nested inside the skill folder, each with its own path and content." 280 relative_path: Required[str] 281 'Bundle-relative path to the skill root, which must end in `/SKILL.md` (e.g. `"skills/my-skill/SKILL.md"`).' 282 283 284class AgentCreateInputTemplateBundleTemplate(TypedDict, total=False): 285 content: Required[str] 286 "Full text content of the agent template file, typically a YAML document." 287 content_type: str | None 288 "MIME type of the template content. Defaults to `application/x-yaml` when omitted." 289 relative_path: Required[str] 290 'Bundle-relative path to the template file, used to derive its storage identity (e.g. `"agent.yaml"`).' 291 292 293class AgentCreateInputTemplateBundle(TypedDict, total=False): 294 configs: list[AgentCreateInputTemplateBundleConfigsItem] | None 295 "Additional configuration resources (scripts, model configs, routine templates) referenced by `config_ref` entries in the template." 296 lookup_key_suffix: str | None 297 "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." 298 setup_actions: list[AgentCreateInputTemplateBundleSetupActionsItem] | None 299 "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." 300 skills: list[AgentCreateInputTemplateBundleSkillsItem] | None 301 "Skill bundles referenced by the template. Each entry includes the skill root and any supporting files." 302 template: Required[AgentCreateInputTemplateBundleTemplate] 303 "The agent template definition to install, including its path and raw content." 304 305 306class AgentCreateInput(TypedDict, total=False): 307 "Create an agent" 308 309 acl: AgentCreateInputAcl | None 310 "Access control list controlling which users, teams, or orgs can read or manage this agent." 311 description: str | None 312 "Human-readable description of what the agent does." 313 email: str | None 314 "Email address assigned to the agent. Used as the agent's contact identity." 315 identity: str | None 316 "System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn." 317 lookup_key: str | None 318 "Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org." 319 metadata: dict[str, Any] | None 320 "Arbitrary key-value map stored on the agent. Not interpreted by the platform." 321 model: str | None 322 "Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model." 323 name: str | None 324 "Display name for the agent. Required when neither `template` nor `template_bundle` is provided." 325 org: str | None 326 "Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`." 327 originator: str | None 328 "Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug." 329 phone_number: str | None 330 "Phone number assigned to the agent in E.164 format, e.g. `+15550001234`." 331 profile_picture: AgentCreateInputProfilePicture | None 332 "Profile picture to attach to the agent. All three subfields are required when this object is present." 333 team: str | None 334 "Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`." 335 template: str | None 336 "ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`." 337 template_bundle: AgentCreateInputTemplateBundle | None 338 "Self-contained install bundle containing an AgentTemplate plus all referenced skills and configs. The entire bundle is committed atomically. Mutually exclusive with `template`." 339 user: str | None 340 "User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`." 341 342 343class AgentUpdateInputAclAddItem(TypedDict, total=False): 344 actions: Required[list[str]] 345 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 346 principal: str | None 347 '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"`.' 348 principal_type: Required[str] 349 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 350 351 352class AgentUpdateInputAclGrantsItem(TypedDict, total=False): 353 actions: Required[list[str]] 354 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 355 principal: str | None 356 '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"`.' 357 principal_type: Required[str] 358 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 359 360 361class AgentUpdateInputAclRemoveItem(TypedDict, total=False): 362 principal: str | None 363 '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"`.' 364 principal_type: Required[str] 365 'The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 366 367 368class AgentUpdateInputAcl(TypedDict, total=False): 369 add: list[AgentUpdateInputAclAddItem] | None 370 "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`." 371 grants: list[AgentUpdateInputAclGrantsItem] | None 372 "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`." 373 remove: list[AgentUpdateInputAclRemoveItem] | None 374 "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`." 375 376 377class AgentUpdateInputProfilePicture(TypedDict): 378 data: str 379 "Base64-encoded binary content of the image." 380 filename: str 381 "Original filename of the image, e.g. `avatar.png`." 382 mime_type: str 383 "MIME type of the image, e.g. `image/png` or `image/jpeg`." 384 385 386class AgentUpdateInput(TypedDict, total=False): 387 "Update an agent" 388 389 acl: AgentUpdateInputAcl | None 390 "Replacement access control list. Fully replaces the existing ACL." 391 description: str | None 392 "New description of what the agent does. Pass an empty string to clear it." 393 email: str | None 394 "New email address for the agent." 395 identity: str | None 396 "Replacement identity system-prompt string describing who the agent is." 397 lookup_key: str | None 398 "New `lookup_key` slug. Must be unique within the owning app or org." 399 metadata: dict[str, Any] | None 400 "Replacement key-value metadata map. The entire map is replaced, not merged." 401 model: str | None 402 "New default AI model identifier, e.g. `claude-sonnet-4-5`. Pass an empty string to clear the agent's default model." 403 name: str | None 404 "New display name for the agent." 405 org: str | None 406 "Organization ID (`org_...`) to transfer ownership to." 407 originator: str | None 408 "Replacement originator label identifying the source or author of the agent." 409 phone_number: str | None 410 "New phone number for the agent in E.164 format, e.g. `+15550001234`." 411 profile_picture: AgentUpdateInputProfilePicture | None 412 "Replacement profile picture. All three subfields are required when this object is present." 413 team: str | None 414 "Team ID (`team_...`) to transfer ownership to." 415 user: str | None 416 "User ID (`usr_...`) to transfer ownership to." 417 418 419class AgentAgentRoutinesInputAclAddItem(TypedDict, total=False): 420 actions: Required[list[str]] 421 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 422 principal: str | None 423 '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"`.' 424 principal_type: Required[str] 425 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 426 427 428class AgentAgentRoutinesInputAclGrantsItem(TypedDict, total=False): 429 actions: Required[list[str]] 430 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 431 principal: str | None 432 '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"`.' 433 principal_type: Required[str] 434 'The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 435 436 437class AgentAgentRoutinesInputAclRemoveItem(TypedDict, total=False): 438 principal: str | None 439 '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"`.' 440 principal_type: Required[str] 441 'The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.' 442 443 444class AgentAgentRoutinesInputAcl(TypedDict, total=False): 445 add: list[AgentAgentRoutinesInputAclAddItem] | None 446 "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`." 447 grants: list[AgentAgentRoutinesInputAclGrantsItem] | None 448 "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`." 449 remove: list[AgentAgentRoutinesInputAclRemoveItem] | None 450 "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`." 451 452 453class AgentAgentRoutinesInputMessagePolicy(TypedDict, total=False): 454 recipients: list[str] | None 455 "Required and non-empty for private visibility. Sources are additive. Routine owner includes the agent owner and optional user co-owner." 456 visibility: str | None 457 "Message visibility. One of `default` or `private`." 458 459 460class AgentAgentRoutinesInputPresetConfigLlm(TypedDict, total=False): 461 model: str | None 462 'Provider-prefixed model identifier for this routine or step, e.g. `"openrouter/anthropic/claude-sonnet-latest"`. When omitted, the agent\'s default model is used.' 463 464 465class AgentAgentRoutinesInputPresetConfig(TypedDict, total=False): 466 instructions: str | None 467 "Custom task or behavior instructions for the preset (max 10,000 chars)." 468 llm: AgentAgentRoutinesInputPresetConfigLlm | None 469 "LLM invocation settings (e.g. a `model` override for this routine/step)." 470 session_mode: str | None 471 "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`)." 472 session_scope: str | None 473 "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`." 474 structured_message_template_ids: list[str] | None 475 "IDs of structured message templates that constrain the agent's responses to predefined structured formats." 476 477 478class AgentAgentRoutinesInputStepsItemPresetConfigLlm(TypedDict, total=False): 479 model: str | None 480 'Provider-prefixed model identifier for this routine or step, e.g. `"openrouter/anthropic/claude-sonnet-latest"`. When omitted, the agent\'s default model is used.' 481 482 483class AgentAgentRoutinesInputStepsItemPresetConfig(TypedDict, total=False): 484 instructions: str | None 485 "Custom task or behavior instructions for the preset (max 10,000 chars)." 486 llm: AgentAgentRoutinesInputStepsItemPresetConfigLlm | None 487 "LLM invocation settings (e.g. a `model` override for this routine/step)." 488 session_mode: str | None 489 "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`)." 490 session_scope: str | None 491 "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`." 492 structured_message_template_ids: list[str] | None 493 "IDs of structured message templates that constrain the agent's responses to predefined structured formats." 494 495 496class AgentAgentRoutinesInputStepsItem(TypedDict, total=False): 497 config: str | None 498 '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.' 499 handler_type: Required[str] 500 'Execution handler for this step. One of `"preset"`, `"script"`, or `"workflow_graph"`.' 501 inputs: dict[str, Any] | None 502 "Optional key-value map binding outputs from prior steps to this step's input variables." 503 name: str | None 504 "Optional label for this step. Must be unique within the chain when provided." 505 on_error: str | None 506 'Error handling policy for this step. One of `"halt"` (default), `"continue"`, or `"retry"`.' 507 output_key: str | None 508 "Key under which this step's result is stored and addressable by downstream steps. Defaults to `name` when omitted." 509 preset_config: AgentAgentRoutinesInputStepsItemPresetConfig | None 510 "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." 511 preset_name: str | None 512 'Name of the preset to invoke. Required when `handler_type` is `"preset"`.' 513 script: str | None 514 'Inline script source code to execute. Used when `handler_type` is `"script"` and no `config` is provided.' 515 516 517class AgentAgentRoutinesInput(TypedDict, total=False): 518 "Create a routine" 519 520 acl: AgentAgentRoutinesInputAcl | None 521 "Access control list governing who can read or manage this routine." 522 config: str | None 523 'Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`.' 524 description: str | None 525 "Optional human-readable description of what this routine does." 526 event_config: dict[str, Any] | None 527 '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"`).' 528 event_type: str | None 529 "Event type that triggers this routine. Deprecated use `event_config` instead." 530 handler_type: Required[str] 531 'Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`.' 532 lookup_key: str | None 533 "Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app." 534 message_policy: AgentAgentRoutinesInputMessagePolicy | None 535 "Visibility and explicit recipient selection for messages emitted by the routine." 536 metadata: dict[str, Any] | None 537 "Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform." 538 name: Required[str] 539 "Human-readable display name for the routine." 540 preset_config: AgentAgentRoutinesInputPresetConfig | None 541 'Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`.' 542 preset_name: str | None 543 'Name of the registered preset to use. Required when `handler_type` is `"preset"`.' 544 schedule: str | None 545 'Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour.' 546 script: str | None 547 'Inline script source. Required when `handler_type` is `"script"`.' 548 status: str | None 549 'Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`.' 550 steps: list[AgentAgentRoutinesInputStepsItem] | None 551 '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`.' 552 trigger_context: str | None 553 'Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`.' 554 user: str | None 555 "Optional co-owner user ID (`usr_...`). When set, that user shares authority over this routine (view/modify/delete) without needing to administer the parent agent. Must be supplied explicitly the caller's identity is never auto-stamped as co-owner." 556 557 558class AgentSearchInput(TypedDict, total=False): 559 "Search an agent's knowledge base" 560 561 max_results: int | None 562 "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`." 563 min_similarity: float | None 564 'Cosine-similarity floor for the vector leg, 0.0-1.0, applied to both chunk and document results. Candidates below it are discarded before ranking, so a high value trades recall for precision. Pass `0.0` to disable the floor when a missed match costs more than a weak one note that with no floor every query returns results, so an empty response can no longer be read as "no match". Omit to use the default.' 565 mode: str | None 566 'Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`.' 567 query: Required[str] 568 "Natural-language search query used to retrieve relevant knowledge items." 569 recency_days: int | None 570 "When set, restricts results to items indexed within the last N days." 571 source_types: list[str] | None 572 'Exact source-type slugs filtering both chunks and documents, e.g. `["knowledge/documents"]` for authored documents or `["thread/messages"]` for conversation memory. Omit or pass an empty array to include all source types.' 573 574 575class AgentThreadsInputThreadMembersItem(TypedDict): 576 id: str 577 "Public user (`usr_...`) or agent (`agt_...`) ID matching `type`." 578 type: Literal["user", "agent"] 579 "Member kind. Use `user` for a user ID or `agent` for an agent ID." 580 581 582class AgentThreadsInputThreadProfilePicture(TypedDict, total=False): 583 data: str | None 584 "Base64-encoded image bytes." 585 filename: str | None 586 "Original filename of the uploaded image, used for display and content-type inference." 587 mime_type: str | None 588 'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`.' 589 590 591class AgentThreadsInputThreadSettings(TypedDict, total=False): 592 agent_enabled: bool | None 593 "Whether the AI agent is active for this thread. `true` enables AI responses; `false` disables them. Defaults to `true` when settings have not been explicitly configured. `null` when a client explicitly cleared the setting." 594 595 596class AgentThreadsInputThread(TypedDict, total=False): 597 create_legacy_agent: bool | None 598 "When `true`, provisions a legacy chat agent alongside the thread. Only needed for integrations that depend on the pre-v2 agent model." 599 description: str | None 600 "Optional longer description of the thread's purpose. `null` if not provided." 601 is_unlisted: bool | None 602 "When `true`, the thread is hidden from the default thread list and accessible only by direct link or ID." 603 key: str | None 604 "Client-assigned unique key for idempotent creation or later lookup. Must be unique within the owning organization." 605 kind: Literal["personal", "feed"] | None 606 "Optional behavioral subtype. `personal` is accepted only for a user-owned thread and limits membership to that user and agents currently owned by them. `feed` is accepted for any owner and renders the thread as a post feed: message lists return top-level posts with their newest replies inline, and agent responses attach to the root post. Mirror kinds remain server-derived and cannot be selected by callers." 607 members: list[AgentThreadsInputThreadMembersItem] | None 608 "Users and agents to add atomically when the thread is created. Each target must pass the same authorization rules as a post-creation member add. Slack mirror threads reject non-empty caller-supplied rosters because their membership is sync-owned." 609 metadata: dict[str, Any] | None 610 "Arbitrary key-value pairs stored alongside the thread. Values must be strings or numbers." 611 muted: bool | None 612 "When `true`, push and in-app notifications for this thread are suppressed for the creating user." 613 org_id: str | None 614 "ID of the organization to create the thread under. Defaults to the authenticated user's primary organization when omitted." 615 profile_picture: AgentThreadsInputThreadProfilePicture | None 616 "Optional profile image for the thread, provided as a base64-encoded payload." 617 settings: AgentThreadsInputThreadSettings | None 618 "Configuration overrides for the thread, such as AI model selection and context window settings." 619 slug: str | None 620 "Optional URL-safe identifier. Derived from the title when omitted and unique within the thread owner." 621 title: str | None 622 "Display name for the thread. `null` if omitted, which causes the thread to be untitled." 623 visibility: Literal["team", "restricted", "private", "org"] | None 624 "Thread visibility. A team-owned thread with members must explicitly use `restricted` or `private`. User- and agent-owned threads with members default to `private` and reject every other value. `org` is only valid on an organization-owned thread with no team, user, or agent owner." 625 626 627class AgentThreadsInput(TypedDict, total=False): 628 "Create a thread for an agent" 629 630 skip_welcome_message: bool | None 631 "When `true`, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to `false`." 632 thread: Required[AgentThreadsInputThread] 633 "Attributes for the new thread. See ThreadCreateParams for available fields." 634 635 636class AgentUpgradeInput(TypedDict, total=False): 637 "Upgrade an agent from an AgentTemplate" 638 639 description: str | None 640 "Instance-specific description override. Pins this value so the template upgrade does not overwrite it." 641 dry_run: bool | None 642 "When `true`, computes and returns the full upgrade diff without persisting any changes. Use with `expected_review_fingerprint` to guard the live apply." 643 email: str | None 644 "Instance-specific email address override. Pins this value so the template upgrade does not overwrite it." 645 expected_review_fingerprint: str | None 646 "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." 647 identity: str | None 648 "Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it." 649 metadata: dict[str, Any] | None 650 "Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it." 651 mode: Literal["reapply", "replace"] | None 652 'Upgrade mode. `"reapply"` (default) refreshes the agent\'s tracked template; `"replace"` moves the agent to a different template (requires `template`).' 653 model: str | None 654 "Instance-specific default model override. Pins this value so the template upgrade does not overwrite it. Pass an empty string to clear the model." 655 name: str | None 656 "Instance-specific name override. Pins this value so the template upgrade does not overwrite it." 657 originator: str | None 658 "Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it." 659 phone_number: str | None 660 "Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it." 661 template: str | None 662 'ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode.' 663 664 665class ScheduleListResponseDataItem(BaseModel): 666 agent: str | None = Field( 667 default=None, description="ID of the agent that owns this schedule (`agi_...`)." 668 ) 669 app: str | None = Field( 670 default=None, description="ID of the application the schedule belongs to (`dap_...`)." 671 ) 672 created_at: datetime | None = Field( 673 default=None, description="When the schedule was created (ISO 8601)." 674 ) 675 cron_expression: str | None = Field( 676 default=None, 677 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.', 678 ) 679 id: str = Field(..., description="Schedule ID (`asc_...`).") 680 instructions: str | None = Field( 681 default=None, 682 description="The task description the agent will execute when this schedule fires.", 683 ) 684 last_run_at: datetime | None = Field( 685 default=None, 686 description="UTC datetime of the most recent successful execution. `null` if the schedule has never run.", 687 ) 688 max_runs: int | None = Field( 689 default=None, 690 description='Maximum number of times a recurring schedule may fire before automatically transitioning to `"completed"`. `null` means no limit.', 691 ) 692 metadata: dict[str, Any] | None = Field( 693 default=None, 694 description="Arbitrary key-value pairs attached to the schedule by the agent. Not interpreted by the platform.", 695 ) 696 next_run_at: datetime | None = Field( 697 default=None, 698 description="UTC datetime of the next planned execution. `null` if the schedule has completed, been cancelled, or has not yet been computed.", 699 ) 700 run_count: int | None = Field( 701 default=None, description="Total number of times this schedule has fired." 702 ) 703 schedule_type: str | None = Field( 704 default=None, 705 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.', 706 ) 707 scheduled_at: datetime | None = Field( 708 default=None, 709 description='The exact UTC datetime at which a one-time schedule fires. Present only when `schedule_type` is `"once"`. `null` for recurring schedules.', 710 ) 711 status: str | None = Field( 712 default=None, 713 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).', 714 ) 715 thread: str | None = Field( 716 default=None, 717 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.", 718 ) 719 timezone: str | None = Field( 720 default=None, 721 description='IANA timezone name used to interpret the cron expression or `scheduled_at` (e.g. `"America/New_York"`). Defaults to `"Etc/UTC"`.', 722 ) 723 updated_at: datetime | None = Field( 724 default=None, description="When the schedule was last modified (ISO 8601)." 725 ) 726 727 728class ScheduleListResponse(BaseModel): 729 """ 730 Successful response 731 """ 732 733 data: list[ScheduleListResponseDataItem] | None = Field( 734 default=None, description="Array of agent schedule objects matching the query." 735 ) 736 737 738class AgentSearchResponse(BaseModel): 739 """ 740 Successful response 741 """ 742 743 data: list[dict[str, Any] | dict[str, Any]] = Field( 744 ..., 745 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.', 746 ) 747 748 749class AgentSelfSolutionResponse(BaseModel): 750 """ 751 Successful response 752 """ 753 754 lookup_key: str 755 solution_id: str 756 solution_version: str 757 758 759class AsyncAgentAgentComputerResource: 760 def __init__(self, http: HttpClient): 761 self._http = http 762 763 async def list(self, agent: str) -> AgentComputerListResponse: 764 """ 765 List computers 766 Returns all computers belonging to the authenticated app, ordered by creation 767 time descending. Pass `agent` to scope the results to a single agent's 768 computers. When `agent` is omitted, computers for all agents in the app are 769 returned. 770 Requires an app-scoped API key. If the specified agent does not exist or does 771 not belong to the app, the endpoint returns 404. 772 773 Args: 774 agent: Agent IDs (`agi_...`). When provided, only computers belonging to these agents are returned. Multiple values are OR'd. 775 776 Returns: 777 Object containing a `data` array of computer records. 778 """ 779 return await self._http.request( 780 f"/api/v1/agents/{agent}/agent_computers", 781 response_type=AgentComputerListResponse, 782 ) 783 784 async def create(self, agent: str, input: AgentAgentComputerCreateInput) -> AgentComputer: 785 """ 786 Provision a computer for an agent 787 Creates and provisions a new computer resource associated with the specified 788 agent. The computer is allocated in the requested region (defaulting to `iad`) 789 and its status transitions from `provisioning` to `running` once it is ready. 790 Requires an app-scoped API key. The agent identified by `agent` must belong 791 to the same app. Supplying a `lookup_key` lets you retrieve this computer 792 later without storing its ID the key must be unique within the app. 793 794 Args: 795 agent: Agent IDs (`agi_...`). When provided, only computers belonging to these agents are returned. Multiple values are OR'd. 796 input: Request body. 797 input.acl: Initial access control list. 798 input.config: Provider-specific configuration for the computer. Supported keys vary by provider. A top-level `provider` takes precedence over `config.provider`. 799 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. 800 input.metadata: Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads. 801 input.name: Human-readable display name for the computer. 802 input.provider: Compute backend for the computer: `"sprites"` (Fly Sprites, the default), `"vercel"` (Vercel Sandbox) or `"e2b"` (E2B). Folded into `config.provider`. 803 input.region: Region in which to provision the computer, e.g. `"iad"`. Defaults to `"iad"` when omitted. 804 805 Returns: 806 The newly provisioned computer. 807 """ 808 return await self._http.request( 809 f"/api/v1/agents/{agent}/agent_computers", 810 method="POST", 811 body=input, 812 response_type=AgentComputer, 813 ) 814 815 816class AsyncAgentAgentEnvVarResource: 817 def __init__(self, http: HttpClient): 818 self._http = http 819 820 async def list(self, agent: str) -> AgentEnvVarMaskedList: 821 """ 822 List an agent's environment variables 823 Returns all environment variables defined for the specified agent. Variable 824 values are always masked in the response; only the last four characters are 825 visible. To inspect a specific variable, use the retrieve endpoint. 826 The authenticated user must have access to the agent's parent app. Pass the 827 app scope via the `app` parameter when calling with an API key that is scoped 828 to a specific app. Results are returned in an unordered flat list. 829 830 Args: 831 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 832 833 Returns: 834 List of environment variables for the agent, with values masked. 835 """ 836 return await self._http.request( 837 f"/api/v1/agents/{agent}/agent_env_vars", 838 response_type=AgentEnvVarMaskedList, 839 ) 840 841 async def create(self, agent: str, input: AgentAgentEnvVarCreateInput) -> AgentEnvVarMasked: 842 """ 843 Create an agent environment variable 844 Creates a new environment variable for the specified agent. The variable is 845 stored securely and the plaintext `value` is never returned after creation; 846 subsequent reads return a masked representation showing only the last four 847 characters. 848 The authenticated user must have access to the agent's parent app. Pass the 849 app scope via the `app` parameter when calling with an API key that is scoped 850 to a specific app. Each `key` must be unique within the agent; attempting to 851 create a duplicate key returns a validation error. 852 853 Args: 854 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 855 input: Request body. 856 input.description: Optional human-readable note describing what the variable is used for. 857 input.key: Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent. 858 input.value: Plaintext secret value to store. The value is encrypted at rest and never returned in full. 859 860 Returns: 861 The newly created environment variable with its value masked. 862 """ 863 return await self._http.request( 864 f"/api/v1/agents/{agent}/agent_env_vars", 865 method="POST", 866 body=input, 867 response_type=AgentEnvVarMasked, 868 ) 869 870 871class AsyncAgentAgentInstallationResource: 872 def __init__(self, http: HttpClient): 873 self._http = http 874 875 async def list(self, agent: str) -> InstallationListResponse: 876 """ 877 List installations for an agent 878 Returns all installations belonging to the specified agent, across all kinds and 879 states. Use this endpoint to inspect which external services and enablement channels 880 an agent is connected to. 881 Results are scoped to the authenticated app and are returned in an unordered array. 882 To list installations across all agents in an app, use the top-level List 883 Installations endpoint instead. The caller must have app scope for the app that 884 owns the agent. 885 886 Args: 887 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 888 889 Returns: 890 The list of installations for the specified agent. 891 """ 892 return await self._http.request( 893 f"/api/v1/agents/{agent}/agent_installations", 894 response_type=InstallationListResponse, 895 ) 896 897 async def create(self, agent: str, input: AgentAgentInstallationCreateInput) -> Installation: 898 """ 899 Create an installation 900 Creates a new installation for an agent, connecting it to an external service or 901 enablement channel via the specified `kind`. The installation begins in a pending 902 state unless an integration is supplied at creation time, in which case it is 903 activated immediately. 904 Supply `shared_integration` to bind an existing org- or app-level integration, or 905 supply `integration` to create a new integration inline and activate the installation 906 in a single request. Supplying both fields returns 422. 907 Use `lookup_key` to assign a stable identifier you can reference later in knowledge 908 search `source_refs`. The key must be unique within the app, org, and sandbox 909 combination. The caller must have app scope for the app that owns the agent. 910 911 Args: 912 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 913 input: Request body. 914 input.config: Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration. 915 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`. 916 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. 917 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. 918 input.shared_integration: ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with `integration`. 919 920 Returns: 921 The newly created installation. 922 """ 923 return await self._http.request( 924 f"/api/v1/agents/{agent}/agent_installations", 925 method="POST", 926 body=input, 927 response_type=Installation, 928 ) 929 930 async def kinds(self, agent: str) -> InstallationKindListResponse: 931 """ 932 List available installation kinds 933 Returns the publicly available installation kinds supported by the API. Use the 934 returned `kind` values when calling the Create Installation endpoint. 935 The list is platform-wide and does not vary by agent. The `agent` parameter is 936 accepted for future per-agent filtering but is currently unused. The caller must 937 have app scope to call this endpoint. 938 939 Args: 940 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 941 942 Returns: 943 The list of publicly available installation kinds. 944 """ 945 return await self._http.request( 946 f"/api/v1/agents/{agent}/agent_installations/kinds", 947 response_type=InstallationKindListResponse, 948 ) 949 950 951class AsyncAgentAgentToolResource: 952 def __init__(self, http: HttpClient): 953 self._http = http 954 955 async def list(self, agent: str, *, kind: str | None = None) -> AgentToolListResponse: 956 """ 957 List agent tools 958 Returns all tools for the authenticated app, optionally filtered by agent 959 or tool kind. Both explicitly created tools and tools derived from connected 960 integrations (installation-sourced tools) are included in the response. 961 Installation-sourced tools appear with `source: "installation"` and 962 `status: "active"`. They are synthesized at request time from connected 963 integrations and do not have a persistent tool ID of the `atl_...` form; 964 their `id` is a composite of the installation ID and server tool type. 965 Use the `agent` filter to retrieve tools for a specific agent. Supplying an 966 `agent` ID that does not belong to the authenticated app returns 404. 967 Requires app scope. 968 969 Args: 970 agent: Filter results to tools belonging to these agents (`agi_...`). Omit to return tools across all agents in the app. Multiple values are OR'd. 971 kind: Filter by tool kind. One of `"builtin"` or `"custom"`. Omit to return tools of all kinds. 972 973 Returns: 974 List of tools matching the supplied filters. 975 """ 976 query: dict[str, object] = {} 977 if kind is not None: 978 query["kind"] = kind 979 return await self._http.request( 980 f"/api/v1/agents/{agent}/agent_tools", 981 query=query, 982 response_type=AgentToolListResponse, 983 ) 984 985 async def create(self, agent: str, input: AgentAgentToolCreateInput) -> AgentTool: 986 """ 987 Create an agent tool 988 Creates a new tool and attaches it to the specified agent. Tools can be 989 either `"builtin"` (a platform-provided capability identified by 990 `builtin_tool_key`) or `"custom"` (a caller-defined tool with its own name, 991 description, parameter schema, and handler). 992 New tools are created in `"draft"` status by default unless `status: 993 "active"` is explicitly supplied. Draft tools are not exposed to the LLM 994 during agent runs; call the activate endpoint to promote them. 995 For built-in tools that support multiple instances per agent (those whose 996 catalog entry has a `multi_instance_mode`), supply `name_prefix` to 997 namespace the LLM-facing tool names. Requires app scope. 998 999 Args: 1000 agent: Filter results to tools belonging to these agents (`agi_...`). Omit to return tools across all agents in the app. Multiple values are OR'd. 1001 input: Request body. 1002 input.async: When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools. 1003 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. 1004 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. 1005 input.config: Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools. 1006 input.description: Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to `"custom"` tools. 1007 input.handler_type: Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools. 1008 input.kind: Tool kind. One of `"builtin"` or `"custom"`. 1009 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. 1010 input.metadata: Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform. 1011 input.name: Display name for the tool. Required when `kind` is `"custom"`. 1012 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. 1013 input.parameters: JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to `"custom"` tools. 1014 input.status: Initial status of the tool. One of `"draft"` or `"active"`. Defaults to `"draft"` when omitted. 1015 1016 Returns: 1017 The newly created tool. 1018 """ 1019 return await self._http.request( 1020 f"/api/v1/agents/{agent}/agent_tools", 1021 method="POST", 1022 body=input, 1023 response_type=AgentTool, 1024 ) 1025 1026 1027class AsyncAgentWorkingMemoryResource: 1028 def __init__(self, http: HttpClient): 1029 self._http = http 1030 1031 async def list( 1032 self, 1033 agent: str, 1034 *, 1035 page: int | None = None, 1036 page_size: int | None = None, 1037 search: str | None = None, 1038 ) -> WorkingMemoryEntryListResponse: 1039 """ 1040 List working memory entries for an agent 1041 Returns a paginated list of working memory entries belonging to the specified 1042 agent. Entries are key-value pairs the agent stores for context between 1043 interactions. Results are ordered by creation time descending (newest first) 1044 and can be filtered with a substring search against the key name. 1045 Requires an app-scoped API key. The authenticated caller must have access to 1046 the app the agent belongs to. Returns 403 if the key is not app-scoped, and 1047 404 if the agent does not exist within the accessible scope. 1048 1049 Args: 1050 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 1051 page: Page number to retrieve, starting at 1. Defaults to 1. 1052 page_size: Number of entries to return per page. Defaults to 25. 1053 search: Substring filter applied to entry keys (case-insensitive). Omit to return all keys. 1054 1055 Returns: 1056 Paginated list of working memory entries for the agent. 1057 """ 1058 query: dict[str, object] = {} 1059 if page is not None: 1060 query["page"] = page 1061 if page_size is not None: 1062 query["page_size"] = page_size 1063 if search is not None: 1064 query["search"] = search 1065 return await self._http.request( 1066 f"/api/v1/agents/{agent}/agent_working_memory", 1067 query=query, 1068 response_type=WorkingMemoryEntryListResponse, 1069 ) 1070 1071 async def delete(self, agent: str, entry: str) -> None: 1072 """ 1073 Delete a working memory entry 1074 Permanently deletes a working memory entry from the agent. This action is 1075 irreversible. Expired entries can also be deleted they are hidden from 1076 list results but persist until overwritten or deleted. 1077 Requires an app-scoped API key. The authenticated caller must be able to 1078 modify the agent that owns the entry. Returns 403 if the key is not 1079 app-scoped or the caller lacks modify access, and 404 if the agent or entry 1080 does not exist within the accessible scope. 1081 1082 Args: 1083 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 1084 entry: Working memory entry ID (`amm_...`) to delete. 1085 1086 Returns: 1087 Empty body. Returns HTTP 204 on success. 1088 """ 1089 await self._http.request( 1090 f"/api/v1/agents/{agent}/agent_working_memory/{entry}", 1091 method="DELETE", 1092 ) 1093 1094 async def update( 1095 self, agent: str, entry: str, input: AgentWorkingMemoryUpdateInput 1096 ) -> WorkingMemoryEntry: 1097 """ 1098 Update a working memory entry 1099 Updates the value and/or expiry of an existing working memory entry. Only 1100 the fields you supply are changed; omitted fields retain their current 1101 values. The entry `key` cannot be changed after creation delete the entry 1102 and let the agent (or a future create call) write a new one instead. 1103 Pass `expires_at` as `null` to remove the expiry so the entry no longer 1104 expires. Expired entries can still be updated; they stay hidden from list 1105 results until their expiry is in the future again. 1106 Requires an app-scoped API key. The authenticated caller must be able to 1107 modify the agent that owns the entry. Returns 403 if the key is not 1108 app-scoped or the caller lacks modify access, and 404 if the agent or entry 1109 does not exist within the accessible scope. 1110 1111 Args: 1112 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 1113 entry: Working memory entry ID (`amm_...`) to update. 1114 input: Request body. 1115 input.expires_at: New expiry for the entry (ISO 8601). Pass `null` to remove the expiry so the entry never expires. Omit to keep the current expiry. 1116 input.value: Replacement string value to store under the entry's key. Maximum 65,536 characters. 1117 1118 Returns: 1119 The updated working memory entry. 1120 """ 1121 return await self._http.request( 1122 f"/api/v1/agents/{agent}/agent_working_memory/{entry}", 1123 method="PATCH", 1124 body=input, 1125 response_type=WorkingMemoryEntry, 1126 ) 1127 1128 1129class AsyncScheduleResource: 1130 def __init__(self, http: HttpClient): 1131 self._http = http 1132 1133 async def list(self, agent: str, *, status: str | None = None) -> ScheduleListResponse: 1134 """ 1135 List schedules for an agent 1136 Returns all schedules belonging to the specified agent in any status. Use the 1137 `status` parameter to narrow results to a single lifecycle state. 1138 Requires an app-scoped API key. The agent must belong to the app identified 1139 by the key. 1140 1141 Args: 1142 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 1143 status: Filter results by schedule status. One of `"active"`, `"paused"`, `"completed"`, `"cancelled"`, or `"expired"`. Omit to return schedules in all statuses. 1144 1145 Returns: 1146 Successful response 1147 """ 1148 query: dict[str, object] = {} 1149 if status is not None: 1150 query["status"] = status 1151 return await self._http.request( 1152 f"/api/v1/agents/{agent}/schedules", 1153 query=query, 1154 response_type=ScheduleListResponse, 1155 ) 1156 1157 async def get(self, agent: str, schedule: str) -> AgentSchedule: 1158 """ 1159 Retrieve a schedule 1160 Returns a single schedule belonging to the specified agent. Use this endpoint 1161 to fetch the current state, next run time, and configuration of an individual 1162 schedule. 1163 Requires an app-scoped API key. Both the agent and the schedule must belong 1164 to the app identified by the key. Returns 404 if the schedule does not exist 1165 or belongs to a different agent. 1166 1167 Args: 1168 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 1169 schedule: Schedule ID (`asc_...`). The schedule to retrieve. 1170 1171 Returns: 1172 The requested agent schedule. 1173 """ 1174 return await self._http.request( 1175 f"/api/v1/agents/{agent}/schedules/{schedule}", 1176 response_type=AgentSchedule, 1177 ) 1178 1179 1180class AsyncAgentWorkItemResource: 1181 def __init__(self, http: HttpClient): 1182 self._http = http 1183 1184 async def list( 1185 self, 1186 agent: str, 1187 *, 1188 execution: str | None = None, 1189 limit: int | None = None, 1190 after_cursor: str | None = None, 1191 ) -> WorkflowWorkItemList: 1192 """ 1193 List active workflow work available to the viewer 1194 Lists queued, claimed, and running external work yielded by durable workflows. 1195 The top-level collection includes work for every agent the viewer can execute; 1196 the agent-nested collection limits results to that agent. This discovery 1197 response never includes lease tokens. Use the agent claim endpoint to acquire 1198 new work or resume a saved lease. 1199 1200 Args: 1201 agent: Agent ID or lookup key injected by the nested route. 1202 execution: Optional durable execution ID filter. 1203 limit: Maximum work items per page. Defaults to 50; maximum is 100. 1204 after_cursor: Opaque cursor for the next page of older queued work. 1205 1206 Returns: 1207 Successful response 1208 """ 1209 query: dict[str, object] = {} 1210 if execution is not None: 1211 query["execution"] = execution 1212 if limit is not None: 1213 query["limit"] = limit 1214 if after_cursor is not None: 1215 query["after_cursor"] = after_cursor 1216 return await self._http.request( 1217 f"/api/v1/agents/{agent}/work_items", 1218 query=query, 1219 response_type=WorkflowWorkItemList, 1220 ) 1221 1222 async def claim(self, agent: str, input: AgentWorkItemClaimInput) -> WorkflowWorkItemClaim: 1223 """ 1224 Claim or resume workflow work for an agent 1225 Atomically claims the oldest queued or lease-expired item. To resume after a 1226 harness restart, pass both the saved `work_item` and the same `lease_owner`; 1227 the server refreshes that active lease without incrementing its attempt. 1228 Returns `data: null` when no eligible item exists, including when another 1229 lease owns the explicitly requested item. 1230 1231 Args: 1232 agent: Agent ID or lookup key injected by the nested route. 1233 input: Request body. 1234 input.execution: Optional durable execution ID filter. 1235 input.lease_owner: Caller-generated random UUID lease token. 1236 input.lease_seconds: Lease duration from 15 through 3600 seconds. Defaults to 300. 1237 input.work_item: Saved work item ID to resume or reclaim. 1238 1239 Returns: 1240 Successful response 1241 """ 1242 return await self._http.request( 1243 f"/api/v1/agents/{agent}/work_items/claim", 1244 method="POST", 1245 body=input, 1246 response_type=WorkflowWorkItemClaim, 1247 ) 1248 1249 1250class AsyncAgentResource: 1251 def __init__(self, http: HttpClient): 1252 self._http = http 1253 self.agent_computers = AsyncAgentAgentComputerResource(http) 1254 self.agent_env_vars = AsyncAgentAgentEnvVarResource(http) 1255 self.agent_installations = AsyncAgentAgentInstallationResource(http) 1256 self.agent_tools = AsyncAgentAgentToolResource(http) 1257 self.agent_working_memory = AsyncAgentWorkingMemoryResource(http) 1258 self.schedules = AsyncScheduleResource(http) 1259 self.work_items = AsyncAgentWorkItemResource(http) 1260 1261 async def list( 1262 self, 1263 *, 1264 page: int | None = None, 1265 page_size: int | None = None, 1266 search: str | None = None, 1267 user: str | None = None, 1268 org_id: str | None = None, 1269 template_config: str | None = None, 1270 solution_config: builtins.list[str] | None = None, 1271 ) -> AgentListResponse: 1272 """ 1273 List agents 1274 Returns a paginated list of agents visible to the authenticated caller. Results are 1275 ordered by creation time descending. 1276 Use `search` to filter by name, org, team, or owner fields. Use `user` or `org_id` 1277 to scope the list to a specific owner. Use `template_config` to find agents whose 1278 last applied template matches a given config ID. Use `solution_config` to find 1279 agents whose last applied template was imported as part of any of the given 1280 Solution config IDs. 1281 Pagination is page-based: pass `page` and `page_size` to navigate through large 1282 result sets. When called under a developer app scope, only agents belonging to that 1283 app are returned. 1284 1285 Args: 1286 page: Page number to retrieve, 1-indexed. Defaults to `1`. 1287 page_size: Number of agents to return per page. Defaults to `25`. 1288 search: Free-text search string matched against the agent name, org, team, and owner fields. 1289 user: User ID (`usr_...`) to filter by. Returns only agents owned by this user. 1290 org_id: Organization ID (`org_...`) to filter by. Returns only agents owned by this org. 1291 template_config: Config ID (`cfg_...`) or `lookup_key` of an AgentTemplate. Returns only agents whose last applied template matches. 1292 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. 1293 1294 Returns: 1295 Paginated list of agents matching the supplied filters. 1296 """ 1297 query: dict[str, object] = {} 1298 if page is not None: 1299 query["page"] = page 1300 if page_size is not None: 1301 query["page_size"] = page_size 1302 if search is not None: 1303 query["search"] = search 1304 if user is not None: 1305 query["user"] = user 1306 if org_id is not None: 1307 query["org_id"] = org_id 1308 if template_config is not None: 1309 query["template_config"] = template_config 1310 if solution_config is not None: 1311 query["solution_config"] = solution_config 1312 return await self._http.request( 1313 "/api/v1/agents", 1314 query=query, 1315 response_type=AgentListResponse, 1316 ) 1317 1318 async def create(self, input: AgentCreateInput) -> AgentCreateResponse: 1319 """ 1320 Create an agent 1321 Creates a new agent. Supports two mutually exclusive provisioning modes. 1322 **Template mode** pass `template` with the ID or `lookup_key` of an existing 1323 AgentTemplate config. The agent's tools, routines, skills, and installations are 1324 provisioned from that template's `config_ref` entries. 1325 **Bundle mode** pass `template_bundle` with a self-contained install payload 1326 (AgentTemplate body plus every skill, script, and config it references). The entire 1327 bundle commits in a single transaction; any failure rolls back the whole install and 1328 the response includes `installed_configs[]` one entry per persisted config. 1329 Pass exactly one of `template` or `template_bundle`. If neither is supplied, `name` 1330 is required and a blank agent is created. Requires authentication; when called under 1331 a developer app scope (`/developer/apps/:app/...`), the caller must hold the app scope 1332 for the target app. 1333 1334 Args: 1335 input: Request body. 1336 input.acl: Access control list controlling which users, teams, or orgs can read or manage this agent. 1337 input.description: Human-readable description of what the agent does. 1338 input.email: Email address assigned to the agent. Used as the agent's contact identity. 1339 input.identity: System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn. 1340 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. 1341 input.metadata: Arbitrary key-value map stored on the agent. Not interpreted by the platform. 1342 input.model: Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model. 1343 input.name: Display name for the agent. Required when neither `template` nor `template_bundle` is provided. 1344 input.org: Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`. 1345 input.originator: Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug. 1346 input.phone_number: Phone number assigned to the agent in E.164 format, e.g. `+15550001234`. 1347 input.profile_picture: Profile picture to attach to the agent. All three subfields are required when this object is present. 1348 input.team: Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`. 1349 input.template: ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`. 1350 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`. 1351 input.user: User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`. 1352 1353 Returns: 1354 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. 1355 """ 1356 return await self._http.request( 1357 "/api/v1/agents", 1358 method="POST", 1359 body=input, 1360 response_type=AgentCreateResponse, 1361 ) 1362 1363 async def delete(self, agent: str) -> None: 1364 """ 1365 Delete an agent 1366 Permanently deletes an agent and all of its associated resources. This action cannot 1367 be undone. 1368 The authenticated caller must own the agent or hold sufficient permissions within its 1369 owning org or team. When called under a developer app scope, the caller must hold the 1370 app scope for the target app. 1371 1372 Args: 1373 agent: ID (`agi_...`) or `lookup_key` of the agent to delete. 1374 1375 Returns: 1376 Empty body. Returns HTTP 204 on success. 1377 """ 1378 await self._http.request(f"/api/v1/agents/{agent}", method="DELETE") 1379 1380 async def get(self, agent: str) -> Agent: 1381 """ 1382 Retrieve an agent 1383 Returns the agent identified by ID or `lookup_key`. The authenticated caller must 1384 own the agent or hold sufficient permissions within its owning org or team. 1385 When called under a developer app scope, the agent must belong to that app. Use the 1386 list endpoint to retrieve many agents at once. 1387 1388 Args: 1389 agent: ID (`agi_...`) or `lookup_key` of the agent to retrieve. 1390 1391 Returns: 1392 The requested agent. 1393 """ 1394 return await self._http.request(f"/api/v1/agents/{agent}", response_type=Agent) 1395 1396 async def update(self, agent: str, input: AgentUpdateInput) -> Agent: 1397 """ 1398 Update an agent 1399 Updates one or more fields on an existing agent. Only the fields you supply are 1400 changed; omitted fields retain their current values. 1401 To clear the agent's default model, pass `model` as an empty string. The 1402 authenticated caller must own the agent or hold write permissions within its owning 1403 org or team. When called under a developer app scope, the caller must hold the app 1404 scope for the target app. 1405 1406 Args: 1407 agent: ID (`agi_...`) or `lookup_key` of the agent to update. 1408 input: Request body. 1409 input.acl: Replacement access control list. Fully replaces the existing ACL. 1410 input.description: New description of what the agent does. Pass an empty string to clear it. 1411 input.email: New email address for the agent. 1412 input.identity: Replacement identity system-prompt string describing who the agent is. 1413 input.lookup_key: New `lookup_key` slug. Must be unique within the owning app or org. 1414 input.metadata: Replacement key-value metadata map. The entire map is replaced, not merged. 1415 input.model: New default AI model identifier, e.g. `claude-sonnet-4-5`. Pass an empty string to clear the agent's default model. 1416 input.name: New display name for the agent. 1417 input.org: Organization ID (`org_...`) to transfer ownership to. 1418 input.originator: Replacement originator label identifying the source or author of the agent. 1419 input.phone_number: New phone number for the agent in E.164 format, e.g. `+15550001234`. 1420 input.profile_picture: Replacement profile picture. All three subfields are required when this object is present. 1421 input.team: Team ID (`team_...`) to transfer ownership to. 1422 input.user: User ID (`usr_...`) to transfer ownership to. 1423 1424 Returns: 1425 The updated agent with all current field values. 1426 """ 1427 return await self._http.request( 1428 f"/api/v1/agents/{agent}", 1429 method="PATCH", 1430 body=input, 1431 response_type=Agent, 1432 ) 1433 1434 async def agent_health_actions( 1435 self, 1436 agent: str, 1437 *, 1438 source: builtins.list[str] | None = None, 1439 status: builtins.list[str] | None = None, 1440 kind: builtins.list[str] | None = None, 1441 ) -> HealthActionListResponse: 1442 """ 1443 List health actions for an agent 1444 Returns all health actions associated with a given agent. Health actions 1445 represent required or recommended steps such as setting environment 1446 variables, completing OAuth installations, or running custom verifiers 1447 that an agent needs to reach a healthy state. 1448 Results are not paginated; the full list for the agent is returned. Use 1449 the `source`, `status`, and `kind` filters to narrow results to the 1450 subset your UI or workflow needs. Multiple values for the same filter 1451 are treated as OR (e.g. passing two statuses returns actions matching 1452 either). The caller must be authenticated and scoped to the app that 1453 owns the agent. 1454 1455 Args: 1456 agent: Agent ID (`agt_...`) or lookup key of the agent whose health actions you want to list. 1457 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. 1458 status: Filter results to actions in one or more statuses. Accepted values: `"pending"`, `"completed"`, `"skipped"`, and `"degraded"`. Omit to return actions in all statuses. 1459 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. 1460 1461 Returns: 1462 Object containing a `data` array of health action objects for the specified agent. 1463 """ 1464 query: dict[str, object] = {} 1465 if source is not None: 1466 query["source"] = source 1467 if status is not None: 1468 query["status"] = status 1469 if kind is not None: 1470 query["kind"] = kind 1471 return await self._http.request( 1472 f"/api/v1/agents/{agent}/agent_health_actions", 1473 query=query, 1474 response_type=HealthActionListResponse, 1475 ) 1476 1477 async def agent_routines(self, agent: str, input: AgentAgentRoutinesInput) -> AgentRoutine: 1478 """ 1479 Create a routine 1480 Creates a new routine and attaches it to the specified agent. Routines define 1481 how an agent responds to events or a cron schedule; the `handler_type` controls 1482 which execution model is used. 1483 The routine is created in `"draft"` status by default. To start processing 1484 events immediately, either pass `status: "active"` or call the activate 1485 endpoint after creation. Scheduled routines must run no more frequently than 1486 once per hour. Requires app scope. 1487 1488 Args: 1489 agent: Agent ID (`agt_...`) that this routine will be attached to. 1490 input: Request body. 1491 input.acl: Access control list governing who can read or manage this routine. 1492 input.config: Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`. 1493 input.description: Optional human-readable description of what this routine does. 1494 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"`). 1495 input.event_type: Event type that triggers this routine. Deprecated use `event_config` instead. 1496 input.handler_type: Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`. 1497 input.lookup_key: Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app. 1498 input.message_policy: Visibility and explicit recipient selection for messages emitted by the routine. 1499 input.metadata: Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform. 1500 input.name: Human-readable display name for the routine. 1501 input.preset_config: Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`. 1502 input.preset_name: Name of the registered preset to use. Required when `handler_type` is `"preset"`. 1503 input.schedule: Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour. 1504 input.script: Inline script source. Required when `handler_type` is `"script"`. 1505 input.status: Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`. 1506 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`. 1507 input.trigger_context: Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`. 1508 input.user: Optional co-owner user ID (`usr_...`). When set, that user shares authority over this routine (view/modify/delete) without needing to administer the parent agent. Must be supplied explicitly the caller's identity is never auto-stamped as co-owner. 1509 1510 Returns: 1511 The newly created routine. 1512 """ 1513 return await self._http.request( 1514 f"/api/v1/agents/{agent}/agent_routines", 1515 method="POST", 1516 body=input, 1517 response_type=AgentRoutine, 1518 ) 1519 1520 async def export(self, agent: str, *, remove_identity: bool | None = None) -> AgentExport: 1521 """ 1522 Export an agent as an AgentTemplate 1523 Reconstructs an AgentTemplate config from a deployed agent and all of its 1524 sub-resources (tools, routines, skills, installations). Returns the template 1525 definition together with every dependent config file (scripts, workflows, skills, 1526 schemas) and their raw content, producing a fully self-contained export bundle. 1527 Use this endpoint to snapshot an agent's current configuration for backup, 1528 migration, or to seed a new Solution template. Pass `remove_identity: true` to 1529 strip instance-specific fields (email, phone number) before export. 1530 The authenticated caller must own the agent or hold sufficient permissions within 1531 its owning org or team. When called under a developer app scope, the caller must 1532 hold the app scope for the target app. 1533 1534 Args: 1535 agent: ID (`agi_...`) or `lookup_key` of the agent to export. 1536 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. 1537 1538 Returns: 1539 Export bundle containing the reconstructed AgentTemplate and all dependent config files with their raw content. 1540 """ 1541 query: dict[str, object] = {} 1542 if remove_identity is not None: 1543 query["remove_identity"] = remove_identity 1544 return await self._http.request( 1545 f"/api/v1/agents/{agent}/export", 1546 query=query, 1547 response_type=AgentExport, 1548 ) 1549 1550 async def health(self, agent: str) -> AgentHealth: 1551 """ 1552 Retrieve an agent's health profile 1553 Returns an aggregate health profile for the specified agent, including an overall 1554 status, a numeric health score, recent activity metrics, and a list of recommended 1555 remediation actions. 1556 The health check is computed on demand at request time. The `checked_at` timestamp 1557 in the response reflects when the evaluation ran. Use this endpoint to surface 1558 diagnostics about tool availability, model configuration, and runtime activity in 1559 dashboards or monitoring workflows. 1560 The authenticated caller must own the agent or hold sufficient permissions within 1561 its owning org or team. When called under a developer app scope, the caller must 1562 hold the app scope for the target app. 1563 1564 Args: 1565 agent: ID (`agi_...`) or `lookup_key` of the agent to evaluate. 1566 1567 Returns: 1568 Aggregate health profile for the agent, including status, score, activity metrics, and recommended actions. 1569 """ 1570 return await self._http.request(f"/api/v1/agents/{agent}/health", response_type=AgentHealth) 1571 1572 async def search(self, agent: str, input: AgentSearchInput) -> AgentSearchResponse: 1573 """ 1574 Search an agent's knowledge base 1575 Performs a semantic search over an agent's knowledge base and returns a ranked, 1576 `kind`-discriminated list of matching items. 1577 Threads are automatically indexed as conversational memory, including prior agent 1578 answers. A match is not necessarily independent source evidence. Result `type` 1579 identifies the source: `thread/messages` is conversation memory; use `source_types` 1580 with the desired corpus slugs (for example `knowledge/documents`) to exclude it. 1581 `kind` describes storage granularity, not whether the content is conversation memory. 1582 Two item kinds may appear in `data`: 1583 - `"chunk"` chunk-level results from the agent's context store. Present for all agents. 1584 - `"document"` document-level results. Present only when the agent has an active 1585 `archastro/knowledge` installation. 1586 Results from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to 1587 be comparable across kinds, then merged into a single ranked list. On a relevance tie, 1588 chunks appear before documents. The total number of results is capped at `max_results` 1589 across both kinds. 1590 Use `mode` to choose the retrieval strategy: `"hybrid"` (default) combines vector and 1591 full-text search; `"vector"` and `"fulltext"` select each strategy independently. 1592 1593 Args: 1594 agent: ID (`agi_...`) or `lookup_key` of the agent whose knowledge base to search. 1595 input: Request body. 1596 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`. 1597 input.min_similarity: Cosine-similarity floor for the vector leg, 0.0-1.0, applied to both chunk and document results. Candidates below it are discarded before ranking, so a high value trades recall for precision. Pass `0.0` to disable the floor when a missed match costs more than a weak one note that with no floor every query returns results, so an empty response can no longer be read as "no match". Omit to use the default. 1598 input.mode: Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`. 1599 input.query: Natural-language search query used to retrieve relevant knowledge items. 1600 input.recency_days: When set, restricts results to items indexed within the last N days. 1601 input.source_types: Exact source-type slugs filtering both chunks and documents, e.g. `["knowledge/documents"]` for authored documents or `["thread/messages"]` for conversation memory. Omit or pass an empty array to include all source types. 1602 1603 Returns: 1604 Successful response 1605 """ 1606 return await self._http.request( 1607 f"/api/v1/agents/{agent}/search", 1608 method="POST", 1609 body=input, 1610 response_type=AgentSearchResponse, 1611 ) 1612 1613 async def self_solution(self, agent: str) -> AgentSelfSolutionResponse: 1614 """ 1615 Ensure an agent's private self-solution 1616 Lazily snapshots an authorized agent into its single private, versioned Solution. 1617 1618 Args: 1619 agent: Agent ID or lookup key. 1620 1621 Returns: 1622 Successful response 1623 """ 1624 return await self._http.request( 1625 f"/api/v1/agents/{agent}/self_solution", 1626 response_type=AgentSelfSolutionResponse, 1627 ) 1628 1629 async def threads(self, agent: str, input: AgentThreadsInput) -> Thread: 1630 """ 1631 Create a thread for an agent 1632 Creates a new thread owned by the specified agent. The thread is scoped to the 1633 agent's identity and is immediately available for messaging. 1634 The authenticated caller must have access to the agent's parent app. If your 1635 API key is scoped to a specific app, pass that app's ID via the `app` parameter. 1636 Attempting to create a thread for an agent you cannot access returns 404. 1637 By default the platform may send an automatic welcome message into the new 1638 thread. Pass `skip_welcome_message: true` to suppress this behavior. 1639 1640 Args: 1641 agent: Agent ID (`agt_...`). The thread will be owned by this agent. 1642 input: Request body. 1643 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to `false`. 1644 input.thread: Attributes for the new thread. See ThreadCreateParams for available fields. 1645 1646 Returns: 1647 The newly created thread. 1648 """ 1649 return await self._http.request( 1650 f"/api/v1/agents/{agent}/threads", 1651 method="POST", 1652 body=input, 1653 response_type=Thread, 1654 ) 1655 1656 async def upgrade(self, agent: str, input: AgentUpgradeInput) -> AgentUpgradeResponse: 1657 """ 1658 Upgrade an agent from an AgentTemplate 1659 Upgrades an existing agent by reconciling it against an AgentTemplate from a 1660 Solution. Supports two modes: 1661 - `"reapply"` (default) re-applies the agent's currently tracked template, 1662 picking up any changes the template author has made since the last apply. 1663 - `"replace"` moves the agent to a different template. `template` is required 1664 in this mode. 1665 Set `dry_run: true` to compute and return the full upgrade diff (adds, updates, 1666 removes, noops) without writing any changes. The response includes a 1667 `review_fingerprint` you can pass back via `expected_review_fingerprint` on the 1668 live apply to guard against the diff changing between review and execution. 1669 Safe overrides (`name`, `description`, `email`, `phone_number`, `metadata`, 1670 `identity`, `originator`, `model`) let you pin instance-specific values that 1671 should not be overwritten by the template during the upgrade. 1672 The authenticated caller must own the agent or hold write permissions within its 1673 owning org or team. When called under a developer app scope, the caller must hold 1674 the app scope for the target app. 1675 1676 Args: 1677 agent: ID (`agi_...`) or `lookup_key` of the agent to upgrade. 1678 input: Request body. 1679 input.description: Instance-specific description override. Pins this value so the template upgrade does not overwrite it. 1680 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. 1681 input.email: Instance-specific email address override. Pins this value so the template upgrade does not overwrite it. 1682 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. 1683 input.identity: Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it. 1684 input.metadata: Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it. 1685 input.mode: Upgrade mode. `"reapply"` (default) refreshes the agent's tracked template; `"replace"` moves the agent to a different template (requires `template`). 1686 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. 1687 input.name: Instance-specific name override. Pins this value so the template upgrade does not overwrite it. 1688 input.originator: Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it. 1689 input.phone_number: Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it. 1690 input.template: ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode. 1691 1692 Returns: 1693 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. 1694 """ 1695 return await self._http.request( 1696 f"/api/v1/agents/{agent}/upgrade", 1697 method="POST", 1698 body=input, 1699 response_type=AgentUpgradeResponse, 1700 ) 1701 1702 1703class AgentAgentComputerResource: 1704 def __init__(self, http: SyncHttpClient): 1705 self._http = http 1706 1707 def list(self, agent: str) -> AgentComputerListResponse: 1708 """ 1709 List computers 1710 Returns all computers belonging to the authenticated app, ordered by creation 1711 time descending. Pass `agent` to scope the results to a single agent's 1712 computers. When `agent` is omitted, computers for all agents in the app are 1713 returned. 1714 Requires an app-scoped API key. If the specified agent does not exist or does 1715 not belong to the app, the endpoint returns 404. 1716 1717 Args: 1718 agent: Agent IDs (`agi_...`). When provided, only computers belonging to these agents are returned. Multiple values are OR'd. 1719 1720 Returns: 1721 Object containing a `data` array of computer records. 1722 """ 1723 return self._http.request( 1724 f"/api/v1/agents/{agent}/agent_computers", 1725 response_type=AgentComputerListResponse, 1726 ) 1727 1728 def create(self, agent: str, input: AgentAgentComputerCreateInput) -> AgentComputer: 1729 """ 1730 Provision a computer for an agent 1731 Creates and provisions a new computer resource associated with the specified 1732 agent. The computer is allocated in the requested region (defaulting to `iad`) 1733 and its status transitions from `provisioning` to `running` once it is ready. 1734 Requires an app-scoped API key. The agent identified by `agent` must belong 1735 to the same app. Supplying a `lookup_key` lets you retrieve this computer 1736 later without storing its ID the key must be unique within the app. 1737 1738 Args: 1739 agent: Agent IDs (`agi_...`). When provided, only computers belonging to these agents are returned. Multiple values are OR'd. 1740 input: Request body. 1741 input.acl: Initial access control list. 1742 input.config: Provider-specific configuration for the computer. Supported keys vary by provider. A top-level `provider` takes precedence over `config.provider`. 1743 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. 1744 input.metadata: Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads. 1745 input.name: Human-readable display name for the computer. 1746 input.provider: Compute backend for the computer: `"sprites"` (Fly Sprites, the default), `"vercel"` (Vercel Sandbox) or `"e2b"` (E2B). Folded into `config.provider`. 1747 input.region: Region in which to provision the computer, e.g. `"iad"`. Defaults to `"iad"` when omitted. 1748 1749 Returns: 1750 The newly provisioned computer. 1751 """ 1752 return self._http.request( 1753 f"/api/v1/agents/{agent}/agent_computers", 1754 method="POST", 1755 body=input, 1756 response_type=AgentComputer, 1757 ) 1758 1759 1760class AgentAgentEnvVarResource: 1761 def __init__(self, http: SyncHttpClient): 1762 self._http = http 1763 1764 def list(self, agent: str) -> AgentEnvVarMaskedList: 1765 """ 1766 List an agent's environment variables 1767 Returns all environment variables defined for the specified agent. Variable 1768 values are always masked in the response; only the last four characters are 1769 visible. To inspect a specific variable, use the retrieve endpoint. 1770 The authenticated user must have access to the agent's parent app. Pass the 1771 app scope via the `app` parameter when calling with an API key that is scoped 1772 to a specific app. Results are returned in an unordered flat list. 1773 1774 Args: 1775 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 1776 1777 Returns: 1778 List of environment variables for the agent, with values masked. 1779 """ 1780 return self._http.request( 1781 f"/api/v1/agents/{agent}/agent_env_vars", 1782 response_type=AgentEnvVarMaskedList, 1783 ) 1784 1785 def create(self, agent: str, input: AgentAgentEnvVarCreateInput) -> AgentEnvVarMasked: 1786 """ 1787 Create an agent environment variable 1788 Creates a new environment variable for the specified agent. The variable is 1789 stored securely and the plaintext `value` is never returned after creation; 1790 subsequent reads return a masked representation showing only the last four 1791 characters. 1792 The authenticated user must have access to the agent's parent app. Pass the 1793 app scope via the `app` parameter when calling with an API key that is scoped 1794 to a specific app. Each `key` must be unique within the agent; attempting to 1795 create a duplicate key returns a validation error. 1796 1797 Args: 1798 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 1799 input: Request body. 1800 input.description: Optional human-readable note describing what the variable is used for. 1801 input.key: Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent. 1802 input.value: Plaintext secret value to store. The value is encrypted at rest and never returned in full. 1803 1804 Returns: 1805 The newly created environment variable with its value masked. 1806 """ 1807 return self._http.request( 1808 f"/api/v1/agents/{agent}/agent_env_vars", 1809 method="POST", 1810 body=input, 1811 response_type=AgentEnvVarMasked, 1812 ) 1813 1814 1815class AgentAgentInstallationResource: 1816 def __init__(self, http: SyncHttpClient): 1817 self._http = http 1818 1819 def list(self, agent: str) -> InstallationListResponse: 1820 """ 1821 List installations for an agent 1822 Returns all installations belonging to the specified agent, across all kinds and 1823 states. Use this endpoint to inspect which external services and enablement channels 1824 an agent is connected to. 1825 Results are scoped to the authenticated app and are returned in an unordered array. 1826 To list installations across all agents in an app, use the top-level List 1827 Installations endpoint instead. The caller must have app scope for the app that 1828 owns the agent. 1829 1830 Args: 1831 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 1832 1833 Returns: 1834 The list of installations for the specified agent. 1835 """ 1836 return self._http.request( 1837 f"/api/v1/agents/{agent}/agent_installations", 1838 response_type=InstallationListResponse, 1839 ) 1840 1841 def create(self, agent: str, input: AgentAgentInstallationCreateInput) -> Installation: 1842 """ 1843 Create an installation 1844 Creates a new installation for an agent, connecting it to an external service or 1845 enablement channel via the specified `kind`. The installation begins in a pending 1846 state unless an integration is supplied at creation time, in which case it is 1847 activated immediately. 1848 Supply `shared_integration` to bind an existing org- or app-level integration, or 1849 supply `integration` to create a new integration inline and activate the installation 1850 in a single request. Supplying both fields returns 422. 1851 Use `lookup_key` to assign a stable identifier you can reference later in knowledge 1852 search `source_refs`. The key must be unique within the app, org, and sandbox 1853 combination. The caller must have app scope for the app that owns the agent. 1854 1855 Args: 1856 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 1857 input: Request body. 1858 input.config: Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration. 1859 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`. 1860 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. 1861 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. 1862 input.shared_integration: ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with `integration`. 1863 1864 Returns: 1865 The newly created installation. 1866 """ 1867 return self._http.request( 1868 f"/api/v1/agents/{agent}/agent_installations", 1869 method="POST", 1870 body=input, 1871 response_type=Installation, 1872 ) 1873 1874 def kinds(self, agent: str) -> InstallationKindListResponse: 1875 """ 1876 List available installation kinds 1877 Returns the publicly available installation kinds supported by the API. Use the 1878 returned `kind` values when calling the Create Installation endpoint. 1879 The list is platform-wide and does not vary by agent. The `agent` parameter is 1880 accepted for future per-agent filtering but is currently unused. The caller must 1881 have app scope to call this endpoint. 1882 1883 Args: 1884 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 1885 1886 Returns: 1887 The list of publicly available installation kinds. 1888 """ 1889 return self._http.request( 1890 f"/api/v1/agents/{agent}/agent_installations/kinds", 1891 response_type=InstallationKindListResponse, 1892 ) 1893 1894 1895class AgentAgentToolResource: 1896 def __init__(self, http: SyncHttpClient): 1897 self._http = http 1898 1899 def list(self, agent: str, *, kind: str | None = None) -> AgentToolListResponse: 1900 """ 1901 List agent tools 1902 Returns all tools for the authenticated app, optionally filtered by agent 1903 or tool kind. Both explicitly created tools and tools derived from connected 1904 integrations (installation-sourced tools) are included in the response. 1905 Installation-sourced tools appear with `source: "installation"` and 1906 `status: "active"`. They are synthesized at request time from connected 1907 integrations and do not have a persistent tool ID of the `atl_...` form; 1908 their `id` is a composite of the installation ID and server tool type. 1909 Use the `agent` filter to retrieve tools for a specific agent. Supplying an 1910 `agent` ID that does not belong to the authenticated app returns 404. 1911 Requires app scope. 1912 1913 Args: 1914 agent: Filter results to tools belonging to these agents (`agi_...`). Omit to return tools across all agents in the app. Multiple values are OR'd. 1915 kind: Filter by tool kind. One of `"builtin"` or `"custom"`. Omit to return tools of all kinds. 1916 1917 Returns: 1918 List of tools matching the supplied filters. 1919 """ 1920 query: dict[str, object] = {} 1921 if kind is not None: 1922 query["kind"] = kind 1923 return self._http.request( 1924 f"/api/v1/agents/{agent}/agent_tools", 1925 query=query, 1926 response_type=AgentToolListResponse, 1927 ) 1928 1929 def create(self, agent: str, input: AgentAgentToolCreateInput) -> AgentTool: 1930 """ 1931 Create an agent tool 1932 Creates a new tool and attaches it to the specified agent. Tools can be 1933 either `"builtin"` (a platform-provided capability identified by 1934 `builtin_tool_key`) or `"custom"` (a caller-defined tool with its own name, 1935 description, parameter schema, and handler). 1936 New tools are created in `"draft"` status by default unless `status: 1937 "active"` is explicitly supplied. Draft tools are not exposed to the LLM 1938 during agent runs; call the activate endpoint to promote them. 1939 For built-in tools that support multiple instances per agent (those whose 1940 catalog entry has a `multi_instance_mode`), supply `name_prefix` to 1941 namespace the LLM-facing tool names. Requires app scope. 1942 1943 Args: 1944 agent: Filter results to tools belonging to these agents (`agi_...`). Omit to return tools across all agents in the app. Multiple values are OR'd. 1945 input: Request body. 1946 input.async: When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools. 1947 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. 1948 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. 1949 input.config: Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools. 1950 input.description: Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to `"custom"` tools. 1951 input.handler_type: Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools. 1952 input.kind: Tool kind. One of `"builtin"` or `"custom"`. 1953 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. 1954 input.metadata: Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform. 1955 input.name: Display name for the tool. Required when `kind` is `"custom"`. 1956 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. 1957 input.parameters: JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to `"custom"` tools. 1958 input.status: Initial status of the tool. One of `"draft"` or `"active"`. Defaults to `"draft"` when omitted. 1959 1960 Returns: 1961 The newly created tool. 1962 """ 1963 return self._http.request( 1964 f"/api/v1/agents/{agent}/agent_tools", 1965 method="POST", 1966 body=input, 1967 response_type=AgentTool, 1968 ) 1969 1970 1971class AgentWorkingMemoryResource: 1972 def __init__(self, http: SyncHttpClient): 1973 self._http = http 1974 1975 def list( 1976 self, 1977 agent: str, 1978 *, 1979 page: int | None = None, 1980 page_size: int | None = None, 1981 search: str | None = None, 1982 ) -> WorkingMemoryEntryListResponse: 1983 """ 1984 List working memory entries for an agent 1985 Returns a paginated list of working memory entries belonging to the specified 1986 agent. Entries are key-value pairs the agent stores for context between 1987 interactions. Results are ordered by creation time descending (newest first) 1988 and can be filtered with a substring search against the key name. 1989 Requires an app-scoped API key. The authenticated caller must have access to 1990 the app the agent belongs to. Returns 403 if the key is not app-scoped, and 1991 404 if the agent does not exist within the accessible scope. 1992 1993 Args: 1994 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 1995 page: Page number to retrieve, starting at 1. Defaults to 1. 1996 page_size: Number of entries to return per page. Defaults to 25. 1997 search: Substring filter applied to entry keys (case-insensitive). Omit to return all keys. 1998 1999 Returns: 2000 Paginated list of working memory entries for the agent. 2001 """ 2002 query: dict[str, object] = {} 2003 if page is not None: 2004 query["page"] = page 2005 if page_size is not None: 2006 query["page_size"] = page_size 2007 if search is not None: 2008 query["search"] = search 2009 return self._http.request( 2010 f"/api/v1/agents/{agent}/agent_working_memory", 2011 query=query, 2012 response_type=WorkingMemoryEntryListResponse, 2013 ) 2014 2015 def delete(self, agent: str, entry: str) -> None: 2016 """ 2017 Delete a working memory entry 2018 Permanently deletes a working memory entry from the agent. This action is 2019 irreversible. Expired entries can also be deleted they are hidden from 2020 list results but persist until overwritten or deleted. 2021 Requires an app-scoped API key. The authenticated caller must be able to 2022 modify the agent that owns the entry. Returns 403 if the key is not 2023 app-scoped or the caller lacks modify access, and 404 if the agent or entry 2024 does not exist within the accessible scope. 2025 2026 Args: 2027 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 2028 entry: Working memory entry ID (`amm_...`) to delete. 2029 2030 Returns: 2031 Empty body. Returns HTTP 204 on success. 2032 """ 2033 self._http.request(f"/api/v1/agents/{agent}/agent_working_memory/{entry}", method="DELETE") 2034 2035 def update( 2036 self, agent: str, entry: str, input: AgentWorkingMemoryUpdateInput 2037 ) -> WorkingMemoryEntry: 2038 """ 2039 Update a working memory entry 2040 Updates the value and/or expiry of an existing working memory entry. Only 2041 the fields you supply are changed; omitted fields retain their current 2042 values. The entry `key` cannot be changed after creation delete the entry 2043 and let the agent (or a future create call) write a new one instead. 2044 Pass `expires_at` as `null` to remove the expiry so the entry no longer 2045 expires. Expired entries can still be updated; they stay hidden from list 2046 results until their expiry is in the future again. 2047 Requires an app-scoped API key. The authenticated caller must be able to 2048 modify the agent that owns the entry. Returns 403 if the key is not 2049 app-scoped or the caller lacks modify access, and 404 if the agent or entry 2050 does not exist within the accessible scope. 2051 2052 Args: 2053 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 2054 entry: Working memory entry ID (`amm_...`) to update. 2055 input: Request body. 2056 input.expires_at: New expiry for the entry (ISO 8601). Pass `null` to remove the expiry so the entry never expires. Omit to keep the current expiry. 2057 input.value: Replacement string value to store under the entry's key. Maximum 65,536 characters. 2058 2059 Returns: 2060 The updated working memory entry. 2061 """ 2062 return self._http.request( 2063 f"/api/v1/agents/{agent}/agent_working_memory/{entry}", 2064 method="PATCH", 2065 body=input, 2066 response_type=WorkingMemoryEntry, 2067 ) 2068 2069 2070class ScheduleResource: 2071 def __init__(self, http: SyncHttpClient): 2072 self._http = http 2073 2074 def list(self, agent: str, *, status: str | None = None) -> ScheduleListResponse: 2075 """ 2076 List schedules for an agent 2077 Returns all schedules belonging to the specified agent in any status. Use the 2078 `status` parameter to narrow results to a single lifecycle state. 2079 Requires an app-scoped API key. The agent must belong to the app identified 2080 by the key. 2081 2082 Args: 2083 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 2084 status: Filter results by schedule status. One of `"active"`, `"paused"`, `"completed"`, `"cancelled"`, or `"expired"`. Omit to return schedules in all statuses. 2085 2086 Returns: 2087 Successful response 2088 """ 2089 query: dict[str, object] = {} 2090 if status is not None: 2091 query["status"] = status 2092 return self._http.request( 2093 f"/api/v1/agents/{agent}/schedules", 2094 query=query, 2095 response_type=ScheduleListResponse, 2096 ) 2097 2098 def get(self, agent: str, schedule: str) -> AgentSchedule: 2099 """ 2100 Retrieve a schedule 2101 Returns a single schedule belonging to the specified agent. Use this endpoint 2102 to fetch the current state, next run time, and configuration of an individual 2103 schedule. 2104 Requires an app-scoped API key. Both the agent and the schedule must belong 2105 to the app identified by the key. Returns 404 if the schedule does not exist 2106 or belongs to a different agent. 2107 2108 Args: 2109 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 2110 schedule: Schedule ID (`asc_...`). The schedule to retrieve. 2111 2112 Returns: 2113 The requested agent schedule. 2114 """ 2115 return self._http.request( 2116 f"/api/v1/agents/{agent}/schedules/{schedule}", 2117 response_type=AgentSchedule, 2118 ) 2119 2120 2121class AgentWorkItemResource: 2122 def __init__(self, http: SyncHttpClient): 2123 self._http = http 2124 2125 def list( 2126 self, 2127 agent: str, 2128 *, 2129 execution: str | None = None, 2130 limit: int | None = None, 2131 after_cursor: str | None = None, 2132 ) -> WorkflowWorkItemList: 2133 """ 2134 List active workflow work available to the viewer 2135 Lists queued, claimed, and running external work yielded by durable workflows. 2136 The top-level collection includes work for every agent the viewer can execute; 2137 the agent-nested collection limits results to that agent. This discovery 2138 response never includes lease tokens. Use the agent claim endpoint to acquire 2139 new work or resume a saved lease. 2140 2141 Args: 2142 agent: Agent ID or lookup key injected by the nested route. 2143 execution: Optional durable execution ID filter. 2144 limit: Maximum work items per page. Defaults to 50; maximum is 100. 2145 after_cursor: Opaque cursor for the next page of older queued work. 2146 2147 Returns: 2148 Successful response 2149 """ 2150 query: dict[str, object] = {} 2151 if execution is not None: 2152 query["execution"] = execution 2153 if limit is not None: 2154 query["limit"] = limit 2155 if after_cursor is not None: 2156 query["after_cursor"] = after_cursor 2157 return self._http.request( 2158 f"/api/v1/agents/{agent}/work_items", 2159 query=query, 2160 response_type=WorkflowWorkItemList, 2161 ) 2162 2163 def claim(self, agent: str, input: AgentWorkItemClaimInput) -> WorkflowWorkItemClaim: 2164 """ 2165 Claim or resume workflow work for an agent 2166 Atomically claims the oldest queued or lease-expired item. To resume after a 2167 harness restart, pass both the saved `work_item` and the same `lease_owner`; 2168 the server refreshes that active lease without incrementing its attempt. 2169 Returns `data: null` when no eligible item exists, including when another 2170 lease owns the explicitly requested item. 2171 2172 Args: 2173 agent: Agent ID or lookup key injected by the nested route. 2174 input: Request body. 2175 input.execution: Optional durable execution ID filter. 2176 input.lease_owner: Caller-generated random UUID lease token. 2177 input.lease_seconds: Lease duration from 15 through 3600 seconds. Defaults to 300. 2178 input.work_item: Saved work item ID to resume or reclaim. 2179 2180 Returns: 2181 Successful response 2182 """ 2183 return self._http.request( 2184 f"/api/v1/agents/{agent}/work_items/claim", 2185 method="POST", 2186 body=input, 2187 response_type=WorkflowWorkItemClaim, 2188 ) 2189 2190 2191class AgentResource: 2192 def __init__(self, http: SyncHttpClient): 2193 self._http = http 2194 self.agent_computers = AgentAgentComputerResource(http) 2195 self.agent_env_vars = AgentAgentEnvVarResource(http) 2196 self.agent_installations = AgentAgentInstallationResource(http) 2197 self.agent_tools = AgentAgentToolResource(http) 2198 self.agent_working_memory = AgentWorkingMemoryResource(http) 2199 self.schedules = ScheduleResource(http) 2200 self.work_items = AgentWorkItemResource(http) 2201 2202 def list( 2203 self, 2204 *, 2205 page: int | None = None, 2206 page_size: int | None = None, 2207 search: str | None = None, 2208 user: str | None = None, 2209 org_id: str | None = None, 2210 template_config: str | None = None, 2211 solution_config: builtins.list[str] | None = None, 2212 ) -> AgentListResponse: 2213 """ 2214 List agents 2215 Returns a paginated list of agents visible to the authenticated caller. Results are 2216 ordered by creation time descending. 2217 Use `search` to filter by name, org, team, or owner fields. Use `user` or `org_id` 2218 to scope the list to a specific owner. Use `template_config` to find agents whose 2219 last applied template matches a given config ID. Use `solution_config` to find 2220 agents whose last applied template was imported as part of any of the given 2221 Solution config IDs. 2222 Pagination is page-based: pass `page` and `page_size` to navigate through large 2223 result sets. When called under a developer app scope, only agents belonging to that 2224 app are returned. 2225 2226 Args: 2227 page: Page number to retrieve, 1-indexed. Defaults to `1`. 2228 page_size: Number of agents to return per page. Defaults to `25`. 2229 search: Free-text search string matched against the agent name, org, team, and owner fields. 2230 user: User ID (`usr_...`) to filter by. Returns only agents owned by this user. 2231 org_id: Organization ID (`org_...`) to filter by. Returns only agents owned by this org. 2232 template_config: Config ID (`cfg_...`) or `lookup_key` of an AgentTemplate. Returns only agents whose last applied template matches. 2233 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. 2234 2235 Returns: 2236 Paginated list of agents matching the supplied filters. 2237 """ 2238 query: dict[str, object] = {} 2239 if page is not None: 2240 query["page"] = page 2241 if page_size is not None: 2242 query["page_size"] = page_size 2243 if search is not None: 2244 query["search"] = search 2245 if user is not None: 2246 query["user"] = user 2247 if org_id is not None: 2248 query["org_id"] = org_id 2249 if template_config is not None: 2250 query["template_config"] = template_config 2251 if solution_config is not None: 2252 query["solution_config"] = solution_config 2253 return self._http.request("/api/v1/agents", query=query, response_type=AgentListResponse) 2254 2255 def create(self, input: AgentCreateInput) -> AgentCreateResponse: 2256 """ 2257 Create an agent 2258 Creates a new agent. Supports two mutually exclusive provisioning modes. 2259 **Template mode** pass `template` with the ID or `lookup_key` of an existing 2260 AgentTemplate config. The agent's tools, routines, skills, and installations are 2261 provisioned from that template's `config_ref` entries. 2262 **Bundle mode** pass `template_bundle` with a self-contained install payload 2263 (AgentTemplate body plus every skill, script, and config it references). The entire 2264 bundle commits in a single transaction; any failure rolls back the whole install and 2265 the response includes `installed_configs[]` one entry per persisted config. 2266 Pass exactly one of `template` or `template_bundle`. If neither is supplied, `name` 2267 is required and a blank agent is created. Requires authentication; when called under 2268 a developer app scope (`/developer/apps/:app/...`), the caller must hold the app scope 2269 for the target app. 2270 2271 Args: 2272 input: Request body. 2273 input.acl: Access control list controlling which users, teams, or orgs can read or manage this agent. 2274 input.description: Human-readable description of what the agent does. 2275 input.email: Email address assigned to the agent. Used as the agent's contact identity. 2276 input.identity: System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn. 2277 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. 2278 input.metadata: Arbitrary key-value map stored on the agent. Not interpreted by the platform. 2279 input.model: Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model. 2280 input.name: Display name for the agent. Required when neither `template` nor `template_bundle` is provided. 2281 input.org: Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`. 2282 input.originator: Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug. 2283 input.phone_number: Phone number assigned to the agent in E.164 format, e.g. `+15550001234`. 2284 input.profile_picture: Profile picture to attach to the agent. All three subfields are required when this object is present. 2285 input.team: Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`. 2286 input.template: ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`. 2287 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`. 2288 input.user: User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`. 2289 2290 Returns: 2291 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. 2292 """ 2293 return self._http.request( 2294 "/api/v1/agents", 2295 method="POST", 2296 body=input, 2297 response_type=AgentCreateResponse, 2298 ) 2299 2300 def delete(self, agent: str) -> None: 2301 """ 2302 Delete an agent 2303 Permanently deletes an agent and all of its associated resources. This action cannot 2304 be undone. 2305 The authenticated caller must own the agent or hold sufficient permissions within its 2306 owning org or team. When called under a developer app scope, the caller must hold the 2307 app scope for the target app. 2308 2309 Args: 2310 agent: ID (`agi_...`) or `lookup_key` of the agent to delete. 2311 2312 Returns: 2313 Empty body. Returns HTTP 204 on success. 2314 """ 2315 self._http.request(f"/api/v1/agents/{agent}", method="DELETE") 2316 2317 def get(self, agent: str) -> Agent: 2318 """ 2319 Retrieve an agent 2320 Returns the agent identified by ID or `lookup_key`. The authenticated caller must 2321 own the agent or hold sufficient permissions within its owning org or team. 2322 When called under a developer app scope, the agent must belong to that app. Use the 2323 list endpoint to retrieve many agents at once. 2324 2325 Args: 2326 agent: ID (`agi_...`) or `lookup_key` of the agent to retrieve. 2327 2328 Returns: 2329 The requested agent. 2330 """ 2331 return self._http.request(f"/api/v1/agents/{agent}", response_type=Agent) 2332 2333 def update(self, agent: str, input: AgentUpdateInput) -> Agent: 2334 """ 2335 Update an agent 2336 Updates one or more fields on an existing agent. Only the fields you supply are 2337 changed; omitted fields retain their current values. 2338 To clear the agent's default model, pass `model` as an empty string. The 2339 authenticated caller must own the agent or hold write permissions within its owning 2340 org or team. When called under a developer app scope, the caller must hold the app 2341 scope for the target app. 2342 2343 Args: 2344 agent: ID (`agi_...`) or `lookup_key` of the agent to update. 2345 input: Request body. 2346 input.acl: Replacement access control list. Fully replaces the existing ACL. 2347 input.description: New description of what the agent does. Pass an empty string to clear it. 2348 input.email: New email address for the agent. 2349 input.identity: Replacement identity system-prompt string describing who the agent is. 2350 input.lookup_key: New `lookup_key` slug. Must be unique within the owning app or org. 2351 input.metadata: Replacement key-value metadata map. The entire map is replaced, not merged. 2352 input.model: New default AI model identifier, e.g. `claude-sonnet-4-5`. Pass an empty string to clear the agent's default model. 2353 input.name: New display name for the agent. 2354 input.org: Organization ID (`org_...`) to transfer ownership to. 2355 input.originator: Replacement originator label identifying the source or author of the agent. 2356 input.phone_number: New phone number for the agent in E.164 format, e.g. `+15550001234`. 2357 input.profile_picture: Replacement profile picture. All three subfields are required when this object is present. 2358 input.team: Team ID (`team_...`) to transfer ownership to. 2359 input.user: User ID (`usr_...`) to transfer ownership to. 2360 2361 Returns: 2362 The updated agent with all current field values. 2363 """ 2364 return self._http.request( 2365 f"/api/v1/agents/{agent}", 2366 method="PATCH", 2367 body=input, 2368 response_type=Agent, 2369 ) 2370 2371 def agent_health_actions( 2372 self, 2373 agent: str, 2374 *, 2375 source: builtins.list[str] | None = None, 2376 status: builtins.list[str] | None = None, 2377 kind: builtins.list[str] | None = None, 2378 ) -> HealthActionListResponse: 2379 """ 2380 List health actions for an agent 2381 Returns all health actions associated with a given agent. Health actions 2382 represent required or recommended steps such as setting environment 2383 variables, completing OAuth installations, or running custom verifiers 2384 that an agent needs to reach a healthy state. 2385 Results are not paginated; the full list for the agent is returned. Use 2386 the `source`, `status`, and `kind` filters to narrow results to the 2387 subset your UI or workflow needs. Multiple values for the same filter 2388 are treated as OR (e.g. passing two statuses returns actions matching 2389 either). The caller must be authenticated and scoped to the app that 2390 owns the agent. 2391 2392 Args: 2393 agent: Agent ID (`agt_...`) or lookup key of the agent whose health actions you want to list. 2394 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. 2395 status: Filter results to actions in one or more statuses. Accepted values: `"pending"`, `"completed"`, `"skipped"`, and `"degraded"`. Omit to return actions in all statuses. 2396 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. 2397 2398 Returns: 2399 Object containing a `data` array of health action objects for the specified agent. 2400 """ 2401 query: dict[str, object] = {} 2402 if source is not None: 2403 query["source"] = source 2404 if status is not None: 2405 query["status"] = status 2406 if kind is not None: 2407 query["kind"] = kind 2408 return self._http.request( 2409 f"/api/v1/agents/{agent}/agent_health_actions", 2410 query=query, 2411 response_type=HealthActionListResponse, 2412 ) 2413 2414 def agent_routines(self, agent: str, input: AgentAgentRoutinesInput) -> AgentRoutine: 2415 """ 2416 Create a routine 2417 Creates a new routine and attaches it to the specified agent. Routines define 2418 how an agent responds to events or a cron schedule; the `handler_type` controls 2419 which execution model is used. 2420 The routine is created in `"draft"` status by default. To start processing 2421 events immediately, either pass `status: "active"` or call the activate 2422 endpoint after creation. Scheduled routines must run no more frequently than 2423 once per hour. Requires app scope. 2424 2425 Args: 2426 agent: Agent ID (`agt_...`) that this routine will be attached to. 2427 input: Request body. 2428 input.acl: Access control list governing who can read or manage this routine. 2429 input.config: Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`. 2430 input.description: Optional human-readable description of what this routine does. 2431 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"`). 2432 input.event_type: Event type that triggers this routine. Deprecated use `event_config` instead. 2433 input.handler_type: Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`. 2434 input.lookup_key: Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app. 2435 input.message_policy: Visibility and explicit recipient selection for messages emitted by the routine. 2436 input.metadata: Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform. 2437 input.name: Human-readable display name for the routine. 2438 input.preset_config: Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`. 2439 input.preset_name: Name of the registered preset to use. Required when `handler_type` is `"preset"`. 2440 input.schedule: Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour. 2441 input.script: Inline script source. Required when `handler_type` is `"script"`. 2442 input.status: Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`. 2443 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`. 2444 input.trigger_context: Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`. 2445 input.user: Optional co-owner user ID (`usr_...`). When set, that user shares authority over this routine (view/modify/delete) without needing to administer the parent agent. Must be supplied explicitly the caller's identity is never auto-stamped as co-owner. 2446 2447 Returns: 2448 The newly created routine. 2449 """ 2450 return self._http.request( 2451 f"/api/v1/agents/{agent}/agent_routines", 2452 method="POST", 2453 body=input, 2454 response_type=AgentRoutine, 2455 ) 2456 2457 def export(self, agent: str, *, remove_identity: bool | None = None) -> AgentExport: 2458 """ 2459 Export an agent as an AgentTemplate 2460 Reconstructs an AgentTemplate config from a deployed agent and all of its 2461 sub-resources (tools, routines, skills, installations). Returns the template 2462 definition together with every dependent config file (scripts, workflows, skills, 2463 schemas) and their raw content, producing a fully self-contained export bundle. 2464 Use this endpoint to snapshot an agent's current configuration for backup, 2465 migration, or to seed a new Solution template. Pass `remove_identity: true` to 2466 strip instance-specific fields (email, phone number) before export. 2467 The authenticated caller must own the agent or hold sufficient permissions within 2468 its owning org or team. When called under a developer app scope, the caller must 2469 hold the app scope for the target app. 2470 2471 Args: 2472 agent: ID (`agi_...`) or `lookup_key` of the agent to export. 2473 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. 2474 2475 Returns: 2476 Export bundle containing the reconstructed AgentTemplate and all dependent config files with their raw content. 2477 """ 2478 query: dict[str, object] = {} 2479 if remove_identity is not None: 2480 query["remove_identity"] = remove_identity 2481 return self._http.request( 2482 f"/api/v1/agents/{agent}/export", 2483 query=query, 2484 response_type=AgentExport, 2485 ) 2486 2487 def health(self, agent: str) -> AgentHealth: 2488 """ 2489 Retrieve an agent's health profile 2490 Returns an aggregate health profile for the specified agent, including an overall 2491 status, a numeric health score, recent activity metrics, and a list of recommended 2492 remediation actions. 2493 The health check is computed on demand at request time. The `checked_at` timestamp 2494 in the response reflects when the evaluation ran. Use this endpoint to surface 2495 diagnostics about tool availability, model configuration, and runtime activity in 2496 dashboards or monitoring workflows. 2497 The authenticated caller must own the agent or hold sufficient permissions within 2498 its owning org or team. When called under a developer app scope, the caller must 2499 hold the app scope for the target app. 2500 2501 Args: 2502 agent: ID (`agi_...`) or `lookup_key` of the agent to evaluate. 2503 2504 Returns: 2505 Aggregate health profile for the agent, including status, score, activity metrics, and recommended actions. 2506 """ 2507 return self._http.request(f"/api/v1/agents/{agent}/health", response_type=AgentHealth) 2508 2509 def search(self, agent: str, input: AgentSearchInput) -> AgentSearchResponse: 2510 """ 2511 Search an agent's knowledge base 2512 Performs a semantic search over an agent's knowledge base and returns a ranked, 2513 `kind`-discriminated list of matching items. 2514 Threads are automatically indexed as conversational memory, including prior agent 2515 answers. A match is not necessarily independent source evidence. Result `type` 2516 identifies the source: `thread/messages` is conversation memory; use `source_types` 2517 with the desired corpus slugs (for example `knowledge/documents`) to exclude it. 2518 `kind` describes storage granularity, not whether the content is conversation memory. 2519 Two item kinds may appear in `data`: 2520 - `"chunk"` chunk-level results from the agent's context store. Present for all agents. 2521 - `"document"` document-level results. Present only when the agent has an active 2522 `archastro/knowledge` installation. 2523 Results from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to 2524 be comparable across kinds, then merged into a single ranked list. On a relevance tie, 2525 chunks appear before documents. The total number of results is capped at `max_results` 2526 across both kinds. 2527 Use `mode` to choose the retrieval strategy: `"hybrid"` (default) combines vector and 2528 full-text search; `"vector"` and `"fulltext"` select each strategy independently. 2529 2530 Args: 2531 agent: ID (`agi_...`) or `lookup_key` of the agent whose knowledge base to search. 2532 input: Request body. 2533 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`. 2534 input.min_similarity: Cosine-similarity floor for the vector leg, 0.0-1.0, applied to both chunk and document results. Candidates below it are discarded before ranking, so a high value trades recall for precision. Pass `0.0` to disable the floor when a missed match costs more than a weak one note that with no floor every query returns results, so an empty response can no longer be read as "no match". Omit to use the default. 2535 input.mode: Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`. 2536 input.query: Natural-language search query used to retrieve relevant knowledge items. 2537 input.recency_days: When set, restricts results to items indexed within the last N days. 2538 input.source_types: Exact source-type slugs filtering both chunks and documents, e.g. `["knowledge/documents"]` for authored documents or `["thread/messages"]` for conversation memory. Omit or pass an empty array to include all source types. 2539 2540 Returns: 2541 Successful response 2542 """ 2543 return self._http.request( 2544 f"/api/v1/agents/{agent}/search", 2545 method="POST", 2546 body=input, 2547 response_type=AgentSearchResponse, 2548 ) 2549 2550 def self_solution(self, agent: str) -> AgentSelfSolutionResponse: 2551 """ 2552 Ensure an agent's private self-solution 2553 Lazily snapshots an authorized agent into its single private, versioned Solution. 2554 2555 Args: 2556 agent: Agent ID or lookup key. 2557 2558 Returns: 2559 Successful response 2560 """ 2561 return self._http.request( 2562 f"/api/v1/agents/{agent}/self_solution", 2563 response_type=AgentSelfSolutionResponse, 2564 ) 2565 2566 def threads(self, agent: str, input: AgentThreadsInput) -> Thread: 2567 """ 2568 Create a thread for an agent 2569 Creates a new thread owned by the specified agent. The thread is scoped to the 2570 agent's identity and is immediately available for messaging. 2571 The authenticated caller must have access to the agent's parent app. If your 2572 API key is scoped to a specific app, pass that app's ID via the `app` parameter. 2573 Attempting to create a thread for an agent you cannot access returns 404. 2574 By default the platform may send an automatic welcome message into the new 2575 thread. Pass `skip_welcome_message: true` to suppress this behavior. 2576 2577 Args: 2578 agent: Agent ID (`agt_...`). The thread will be owned by this agent. 2579 input: Request body. 2580 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to `false`. 2581 input.thread: Attributes for the new thread. See ThreadCreateParams for available fields. 2582 2583 Returns: 2584 The newly created thread. 2585 """ 2586 return self._http.request( 2587 f"/api/v1/agents/{agent}/threads", 2588 method="POST", 2589 body=input, 2590 response_type=Thread, 2591 ) 2592 2593 def upgrade(self, agent: str, input: AgentUpgradeInput) -> AgentUpgradeResponse: 2594 """ 2595 Upgrade an agent from an AgentTemplate 2596 Upgrades an existing agent by reconciling it against an AgentTemplate from a 2597 Solution. Supports two modes: 2598 - `"reapply"` (default) re-applies the agent's currently tracked template, 2599 picking up any changes the template author has made since the last apply. 2600 - `"replace"` moves the agent to a different template. `template` is required 2601 in this mode. 2602 Set `dry_run: true` to compute and return the full upgrade diff (adds, updates, 2603 removes, noops) without writing any changes. The response includes a 2604 `review_fingerprint` you can pass back via `expected_review_fingerprint` on the 2605 live apply to guard against the diff changing between review and execution. 2606 Safe overrides (`name`, `description`, `email`, `phone_number`, `metadata`, 2607 `identity`, `originator`, `model`) let you pin instance-specific values that 2608 should not be overwritten by the template during the upgrade. 2609 The authenticated caller must own the agent or hold write permissions within its 2610 owning org or team. When called under a developer app scope, the caller must hold 2611 the app scope for the target app. 2612 2613 Args: 2614 agent: ID (`agi_...`) or `lookup_key` of the agent to upgrade. 2615 input: Request body. 2616 input.description: Instance-specific description override. Pins this value so the template upgrade does not overwrite it. 2617 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. 2618 input.email: Instance-specific email address override. Pins this value so the template upgrade does not overwrite it. 2619 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. 2620 input.identity: Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it. 2621 input.metadata: Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it. 2622 input.mode: Upgrade mode. `"reapply"` (default) refreshes the agent's tracked template; `"replace"` moves the agent to a different template (requires `template`). 2623 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. 2624 input.name: Instance-specific name override. Pins this value so the template upgrade does not overwrite it. 2625 input.originator: Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it. 2626 input.phone_number: Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it. 2627 input.template: ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode. 2628 2629 Returns: 2630 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. 2631 """ 2632 return self._http.request( 2633 f"/api/v1/agents/{agent}/upgrade", 2634 method="POST", 2635 body=input, 2636 response_type=AgentUpgradeResponse, 2637 )
class
AgentAgentComputerCreateInputAclAddItem(typing.TypedDict):
41class AgentAgentComputerCreateInputAclAddItem(TypedDict, total=False): 42 actions: Required[list[str]] 43 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 44 principal: str | None 45 '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"`.' 46 principal_type: Required[str] 47 '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
AgentAgentComputerCreateInputAclGrantsItem(typing.TypedDict):
50class AgentAgentComputerCreateInputAclGrantsItem(TypedDict, total=False): 51 actions: Required[list[str]] 52 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 53 principal: str | None 54 '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"`.' 55 principal_type: Required[str] 56 '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
AgentAgentComputerCreateInputAclRemoveItem(typing.TypedDict):
59class AgentAgentComputerCreateInputAclRemoveItem(TypedDict, total=False): 60 principal: str | None 61 '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"`.' 62 principal_type: Required[str] 63 '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
AgentAgentComputerCreateInputAcl(typing.TypedDict):
66class AgentAgentComputerCreateInputAcl(TypedDict, total=False): 67 add: list[AgentAgentComputerCreateInputAclAddItem] | None 68 "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`." 69 grants: list[AgentAgentComputerCreateInputAclGrantsItem] | None 70 "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`." 71 remove: list[AgentAgentComputerCreateInputAclRemoveItem] | None 72 "Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`."
add: list[AgentAgentComputerCreateInputAclAddItem] | None
Patch mode: grants to add or merge into the existing list. Cannot be combined with grants.
grants: list[AgentAgentComputerCreateInputAclGrantsItem] | None
remove: list[AgentAgentComputerCreateInputAclRemoveItem] | None
Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with grants.
class
AgentAgentComputerCreateInput(typing.TypedDict):
75class AgentAgentComputerCreateInput(TypedDict, total=False): 76 "Provision a computer for an agent" 77 78 acl: AgentAgentComputerCreateInputAcl | None 79 "Initial access control list." 80 config: dict[str, Any] | None 81 "Provider-specific configuration for the computer. Supported keys vary by provider. A top-level `provider` takes precedence over `config.provider`." 82 lookup_key: str | None 83 "Stable, user-defined key for this computer. Must be unique within the app. Use it to look up the computer without storing its ID." 84 metadata: dict[str, Any] | None 85 "Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads." 86 name: Required[str] 87 "Human-readable display name for the computer." 88 provider: str | None 89 'Compute backend for the computer: `"sprites"` (Fly Sprites, the default), `"vercel"` (Vercel Sandbox) or `"e2b"` (E2B). Folded into `config.provider`.' 90 region: str | None 91 '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):
94class AgentAgentEnvVarCreateInput(TypedDict, total=False): 95 "Create an agent environment variable" 96 97 description: str | None 98 "Optional human-readable note describing what the variable is used for." 99 key: Required[str] 100 "Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent." 101 value: Required[str] 102 "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):
105class AgentAgentInstallationCreateInputIntegration(TypedDict, total=False): 106 access_token: str | None 107 "OAuth access token or static API key used by `oauth` providers to authenticate requests on behalf of the user." 108 installation_id: str | None 109 "External installation identifier used by `app_installation` providers, e.g. a GitHub App installation ID or a Slack team ID." 110 metadata: dict[str, Any] | None 111 'Arbitrary provider-specific metadata, e.g. `{"bot_user_id": "U012AB3CD"}` for Slack. Stored alongside the integration and made available to connector logic.' 112 refresh_token: str | None 113 "OAuth refresh token used to obtain a new `access_token` when the current one expires. Omit for providers that do not issue refresh tokens." 114 workspace_key: str | None 115 "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):
118class AgentAgentInstallationCreateInput(TypedDict, total=False): 119 "Create an installation" 120 121 config: dict[str, Any] | None 122 "Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration." 123 integration: AgentAgentInstallationCreateInputIntegration | None 124 "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`." 125 kind: Required[str] 126 '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.' 127 lookup_key: str | None 128 "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." 129 shared_integration: str | None 130 "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
AgentWorkingMemoryUpdateInput(typing.TypedDict):
172class AgentWorkingMemoryUpdateInput(TypedDict, total=False): 173 "Update a working memory entry" 174 175 expires_at: datetime | None 176 "New expiry for the entry (ISO 8601). Pass `null` to remove the expiry so the entry never expires. Omit to keep the current expiry." 177 value: str | None 178 "Replacement string value to store under the entry's key. Maximum 65,536 characters."
Update a working memory entry
class
AgentWorkItemClaimInput(typing.TypedDict):
181class AgentWorkItemClaimInput(TypedDict, total=False): 182 "Claim or resume workflow work for an agent" 183 184 execution: str | None 185 "Optional durable execution ID filter." 186 lease_owner: Required[str] 187 "Caller-generated random UUID lease token." 188 lease_seconds: int | None 189 "Lease duration from 15 through 3600 seconds. Defaults to 300." 190 work_item: str | None 191 "Saved work item ID to resume or reclaim."
Claim or resume workflow work for an agent
class
AgentCreateInputAclAddItem(typing.TypedDict):
194class AgentCreateInputAclAddItem(TypedDict, total=False): 195 actions: Required[list[str]] 196 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 197 principal: str | None 198 '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"`.' 199 principal_type: Required[str] 200 '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):
203class AgentCreateInputAclGrantsItem(TypedDict, total=False): 204 actions: Required[list[str]] 205 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 206 principal: str | None 207 '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"`.' 208 principal_type: Required[str] 209 '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):
212class AgentCreateInputAclRemoveItem(TypedDict, total=False): 213 principal: str | None 214 '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"`.' 215 principal_type: Required[str] 216 '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):
219class AgentCreateInputAcl(TypedDict, total=False): 220 add: list[AgentCreateInputAclAddItem] | None 221 "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`." 222 grants: list[AgentCreateInputAclGrantsItem] | None 223 "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`." 224 remove: list[AgentCreateInputAclRemoveItem] | None 225 "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):
237class AgentCreateInputTemplateBundleConfigsItem(TypedDict, total=False): 238 content: Required[str] 239 "Full text content of the configuration file." 240 content_type: str | None 241 'MIME type of the configuration content, e.g. `"application/x-yaml"` or `"application/json"`. `null` if not specified.' 242 relative_path: Required[str] 243 "Bundle-relative path to this config file. The path determines the config kind and its storage identity within the installation."
class
AgentCreateInputTemplateBundleSetupActionsItem(typing.TypedDict):
246class AgentCreateInputTemplateBundleSetupActionsItem(TypedDict, total=False): 247 depends_on: list[str] | None 248 "List of other setup action identifiers that must be completed before this action becomes actionable." 249 description: str | None 250 "Markdown-formatted instructions or context shown beneath the checklist item. `null` if not provided." 251 kind: Required[str] 252 '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).' 253 params: dict[str, Any] | None 254 '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`.' 255 required: bool | None 256 "When `true`, this action must be completed before the checklist progress bar reaches 100%. Defaults to `true`." 257 sort_order: int | None 258 "Numeric sort position controlling the display order of this action in the checklist. Defaults to `0` when not specified." 259 title: Required[str] 260 "Short human-readable label displayed in the setup checklist." 261 verify_config: dict[str, Any] | None 262 '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):
265class AgentCreateInputTemplateBundleSkillsItemFilesItem(TypedDict, total=False): 266 content: Required[str] 267 "Full text content of the file." 268 content_type: str | None 269 "MIME type of the file content. Defaults to a value inferred from the file extension when omitted." 270 relative_path: Required[str] 271 'Path of this file relative to the skill folder root, e.g. `"skills/my-skill/helpers.md"`.'
class
AgentCreateInputTemplateBundleSkillsItem(typing.TypedDict):
274class AgentCreateInputTemplateBundleSkillsItem(TypedDict, total=False): 275 content: Required[str] 276 "Full text content of the `SKILL.md` file." 277 content_type: str | None 278 "MIME type of the `SKILL.md` content. Defaults to `text/markdown` when omitted." 279 files: list[AgentCreateInputTemplateBundleSkillsItemFilesItem] | None 280 "Additional files nested inside the skill folder, each with its own path and content." 281 relative_path: Required[str] 282 '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):
285class AgentCreateInputTemplateBundleTemplate(TypedDict, total=False): 286 content: Required[str] 287 "Full text content of the agent template file, typically a YAML document." 288 content_type: str | None 289 "MIME type of the template content. Defaults to `application/x-yaml` when omitted." 290 relative_path: Required[str] 291 'Bundle-relative path to the template file, used to derive its storage identity (e.g. `"agent.yaml"`).'
class
AgentCreateInputTemplateBundle(typing.TypedDict):
294class AgentCreateInputTemplateBundle(TypedDict, total=False): 295 configs: list[AgentCreateInputTemplateBundleConfigsItem] | None 296 "Additional configuration resources (scripts, model configs, routine templates) referenced by `config_ref` entries in the template." 297 lookup_key_suffix: str | None 298 "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." 299 setup_actions: list[AgentCreateInputTemplateBundleSetupActionsItem] | None 300 "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." 301 skills: list[AgentCreateInputTemplateBundleSkillsItem] | None 302 "Skill bundles referenced by the template. Each entry includes the skill root and any supporting files." 303 template: Required[AgentCreateInputTemplateBundleTemplate] 304 "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):
307class AgentCreateInput(TypedDict, total=False): 308 "Create an agent" 309 310 acl: AgentCreateInputAcl | None 311 "Access control list controlling which users, teams, or orgs can read or manage this agent." 312 description: str | None 313 "Human-readable description of what the agent does." 314 email: str | None 315 "Email address assigned to the agent. Used as the agent's contact identity." 316 identity: str | None 317 "System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn." 318 lookup_key: str | None 319 "Stable, unique slug used to look up this agent by name instead of ID. Must be unique within the owning app or org." 320 metadata: dict[str, Any] | None 321 "Arbitrary key-value map stored on the agent. Not interpreted by the platform." 322 model: str | None 323 "Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model." 324 name: str | None 325 "Display name for the agent. Required when neither `template` nor `template_bundle` is provided." 326 org: str | None 327 "Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`." 328 originator: str | None 329 "Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug." 330 phone_number: str | None 331 "Phone number assigned to the agent in E.164 format, e.g. `+15550001234`." 332 profile_picture: AgentCreateInputProfilePicture | None 333 "Profile picture to attach to the agent. All three subfields are required when this object is present." 334 team: str | None 335 "Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`." 336 template: str | None 337 "ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`." 338 template_bundle: AgentCreateInputTemplateBundle | None 339 "Self-contained install bundle containing an AgentTemplate plus all referenced skills and configs. The entire bundle is committed atomically. Mutually exclusive with `template`." 340 user: str | None 341 "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):
344class AgentUpdateInputAclAddItem(TypedDict, total=False): 345 actions: Required[list[str]] 346 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 347 principal: str | None 348 '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"`.' 349 principal_type: Required[str] 350 '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):
353class AgentUpdateInputAclGrantsItem(TypedDict, total=False): 354 actions: Required[list[str]] 355 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 356 principal: str | None 357 '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"`.' 358 principal_type: Required[str] 359 '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):
362class AgentUpdateInputAclRemoveItem(TypedDict, total=False): 363 principal: str | None 364 '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"`.' 365 principal_type: Required[str] 366 '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):
369class AgentUpdateInputAcl(TypedDict, total=False): 370 add: list[AgentUpdateInputAclAddItem] | None 371 "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`." 372 grants: list[AgentUpdateInputAclGrantsItem] | None 373 "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`." 374 remove: list[AgentUpdateInputAclRemoveItem] | None 375 "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):
387class AgentUpdateInput(TypedDict, total=False): 388 "Update an agent" 389 390 acl: AgentUpdateInputAcl | None 391 "Replacement access control list. Fully replaces the existing ACL." 392 description: str | None 393 "New description of what the agent does. Pass an empty string to clear it." 394 email: str | None 395 "New email address for the agent." 396 identity: str | None 397 "Replacement identity system-prompt string describing who the agent is." 398 lookup_key: str | None 399 "New `lookup_key` slug. Must be unique within the owning app or org." 400 metadata: dict[str, Any] | None 401 "Replacement key-value metadata map. The entire map is replaced, not merged." 402 model: str | None 403 "New default AI model identifier, e.g. `claude-sonnet-4-5`. Pass an empty string to clear the agent's default model." 404 name: str | None 405 "New display name for the agent." 406 org: str | None 407 "Organization ID (`org_...`) to transfer ownership to." 408 originator: str | None 409 "Replacement originator label identifying the source or author of the agent." 410 phone_number: str | None 411 "New phone number for the agent in E.164 format, e.g. `+15550001234`." 412 profile_picture: AgentUpdateInputProfilePicture | None 413 "Replacement profile picture. All three subfields are required when this object is present." 414 team: str | None 415 "Team ID (`team_...`) to transfer ownership to." 416 user: str | None 417 "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):
420class AgentAgentRoutinesInputAclAddItem(TypedDict, total=False): 421 actions: Required[list[str]] 422 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 423 principal: str | None 424 '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"`.' 425 principal_type: Required[str] 426 '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):
429class AgentAgentRoutinesInputAclGrantsItem(TypedDict, total=False): 430 actions: Required[list[str]] 431 'Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.' 432 principal: str | None 433 '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"`.' 434 principal_type: Required[str] 435 '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):
438class AgentAgentRoutinesInputAclRemoveItem(TypedDict, total=False): 439 principal: str | None 440 '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"`.' 441 principal_type: Required[str] 442 '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):
445class AgentAgentRoutinesInputAcl(TypedDict, total=False): 446 add: list[AgentAgentRoutinesInputAclAddItem] | None 447 "Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`." 448 grants: list[AgentAgentRoutinesInputAclGrantsItem] | None 449 "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`." 450 remove: list[AgentAgentRoutinesInputAclRemoveItem] | None 451 "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
AgentAgentRoutinesInputMessagePolicy(typing.TypedDict):
454class AgentAgentRoutinesInputMessagePolicy(TypedDict, total=False): 455 recipients: list[str] | None 456 "Required and non-empty for private visibility. Sources are additive. Routine owner includes the agent owner and optional user co-owner." 457 visibility: str | None 458 "Message visibility. One of `default` or `private`."
class
AgentAgentRoutinesInputPresetConfigLlm(typing.TypedDict):
class
AgentAgentRoutinesInputPresetConfig(typing.TypedDict):
466class AgentAgentRoutinesInputPresetConfig(TypedDict, total=False): 467 instructions: str | None 468 "Custom task or behavior instructions for the preset (max 10,000 chars)." 469 llm: AgentAgentRoutinesInputPresetConfigLlm | None 470 "LLM invocation settings (e.g. a `model` override for this routine/step)." 471 session_mode: str | None 472 "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`)." 473 session_scope: str | None 474 "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`." 475 structured_message_template_ids: list[str] | None 476 "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):
484class AgentAgentRoutinesInputStepsItemPresetConfig(TypedDict, total=False): 485 instructions: str | None 486 "Custom task or behavior instructions for the preset (max 10,000 chars)." 487 llm: AgentAgentRoutinesInputStepsItemPresetConfigLlm | None 488 "LLM invocation settings (e.g. a `model` override for this routine/step)." 489 session_mode: str | None 490 "Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`)." 491 session_scope: str | None 492 "When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`." 493 structured_message_template_ids: list[str] | None 494 "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):
497class AgentAgentRoutinesInputStepsItem(TypedDict, total=False): 498 config: str | None 499 '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.' 500 handler_type: Required[str] 501 'Execution handler for this step. One of `"preset"`, `"script"`, or `"workflow_graph"`.' 502 inputs: dict[str, Any] | None 503 "Optional key-value map binding outputs from prior steps to this step's input variables." 504 name: str | None 505 "Optional label for this step. Must be unique within the chain when provided." 506 on_error: str | None 507 'Error handling policy for this step. One of `"halt"` (default), `"continue"`, or `"retry"`.' 508 output_key: str | None 509 "Key under which this step's result is stored and addressable by downstream steps. Defaults to `name` when omitted." 510 preset_config: AgentAgentRoutinesInputStepsItemPresetConfig | None 511 "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." 512 preset_name: str | None 513 'Name of the preset to invoke. Required when `handler_type` is `"preset"`.' 514 script: str | None 515 '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):
518class AgentAgentRoutinesInput(TypedDict, total=False): 519 "Create a routine" 520 521 acl: AgentAgentRoutinesInputAcl | None 522 "Access control list governing who can read or manage this routine." 523 config: str | None 524 'Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`.' 525 description: str | None 526 "Optional human-readable description of what this routine does." 527 event_config: dict[str, Any] | None 528 '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"`).' 529 event_type: str | None 530 "Event type that triggers this routine. Deprecated use `event_config` instead." 531 handler_type: Required[str] 532 'Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`.' 533 lookup_key: str | None 534 "Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app." 535 message_policy: AgentAgentRoutinesInputMessagePolicy | None 536 "Visibility and explicit recipient selection for messages emitted by the routine." 537 metadata: dict[str, Any] | None 538 "Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform." 539 name: Required[str] 540 "Human-readable display name for the routine." 541 preset_config: AgentAgentRoutinesInputPresetConfig | None 542 'Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`.' 543 preset_name: str | None 544 'Name of the registered preset to use. Required when `handler_type` is `"preset"`.' 545 schedule: str | None 546 'Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour.' 547 script: str | None 548 'Inline script source. Required when `handler_type` is `"script"`.' 549 status: str | None 550 'Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`.' 551 steps: list[AgentAgentRoutinesInputStepsItem] | None 552 '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`.' 553 trigger_context: str | None 554 'Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`.' 555 user: str | None 556 "Optional co-owner user ID (`usr_...`). When set, that user shares authority over this routine (view/modify/delete) without needing to administer the parent agent. Must be supplied explicitly the caller's identity is never auto-stamped as co-owner."
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.
message_policy: AgentAgentRoutinesInputMessagePolicy | None
Visibility and explicit recipient selection for messages emitted by the routine.
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):
559class AgentSearchInput(TypedDict, total=False): 560 "Search an agent's knowledge base" 561 562 max_results: int | None 563 "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`." 564 min_similarity: float | None 565 'Cosine-similarity floor for the vector leg, 0.0-1.0, applied to both chunk and document results. Candidates below it are discarded before ranking, so a high value trades recall for precision. Pass `0.0` to disable the floor when a missed match costs more than a weak one note that with no floor every query returns results, so an empty response can no longer be read as "no match". Omit to use the default.' 566 mode: str | None 567 'Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`.' 568 query: Required[str] 569 "Natural-language search query used to retrieve relevant knowledge items." 570 recency_days: int | None 571 "When set, restricts results to items indexed within the last N days." 572 source_types: list[str] | None 573 'Exact source-type slugs filtering both chunks and documents, e.g. `["knowledge/documents"]` for authored documents or `["thread/messages"]` for conversation memory. Omit or pass an empty array to include all source types.'
Search an agent's knowledge base
max_results: int | None
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.
min_similarity: float | None
Cosine-similarity floor for the vector leg, 0.0-1.0, applied to both chunk and document results. Candidates below it are discarded before ranking, so a high value trades recall for precision. Pass 0.0 to disable the floor when a missed match costs more than a weak one note that with no floor every query returns results, so an empty response can no longer be read as "no match". Omit to use the default.
class
AgentThreadsInputThreadMembersItem(typing.TypedDict):
class
AgentThreadsInputThreadProfilePicture(typing.TypedDict):
583class AgentThreadsInputThreadProfilePicture(TypedDict, total=False): 584 data: str | None 585 "Base64-encoded image bytes." 586 filename: str | None 587 "Original filename of the uploaded image, used for display and content-type inference." 588 mime_type: str | None 589 'MIME type of the image, e.g. `"image/png"` or `"image/jpeg"`.'
class
AgentThreadsInputThreadSettings(typing.TypedDict):
592class AgentThreadsInputThreadSettings(TypedDict, total=False): 593 agent_enabled: bool | None 594 "Whether the AI agent is active for this thread. `true` enables AI responses; `false` disables them. Defaults to `true` when settings have not been explicitly configured. `null` when a client explicitly cleared the setting."
class
AgentThreadsInputThread(typing.TypedDict):
597class AgentThreadsInputThread(TypedDict, total=False): 598 create_legacy_agent: bool | None 599 "When `true`, provisions a legacy chat agent alongside the thread. Only needed for integrations that depend on the pre-v2 agent model." 600 description: str | None 601 "Optional longer description of the thread's purpose. `null` if not provided." 602 is_unlisted: bool | None 603 "When `true`, the thread is hidden from the default thread list and accessible only by direct link or ID." 604 key: str | None 605 "Client-assigned unique key for idempotent creation or later lookup. Must be unique within the owning organization." 606 kind: Literal["personal", "feed"] | None 607 "Optional behavioral subtype. `personal` is accepted only for a user-owned thread and limits membership to that user and agents currently owned by them. `feed` is accepted for any owner and renders the thread as a post feed: message lists return top-level posts with their newest replies inline, and agent responses attach to the root post. Mirror kinds remain server-derived and cannot be selected by callers." 608 members: list[AgentThreadsInputThreadMembersItem] | None 609 "Users and agents to add atomically when the thread is created. Each target must pass the same authorization rules as a post-creation member add. Slack mirror threads reject non-empty caller-supplied rosters because their membership is sync-owned." 610 metadata: dict[str, Any] | None 611 "Arbitrary key-value pairs stored alongside the thread. Values must be strings or numbers." 612 muted: bool | None 613 "When `true`, push and in-app notifications for this thread are suppressed for the creating user." 614 org_id: str | None 615 "ID of the organization to create the thread under. Defaults to the authenticated user's primary organization when omitted." 616 profile_picture: AgentThreadsInputThreadProfilePicture | None 617 "Optional profile image for the thread, provided as a base64-encoded payload." 618 settings: AgentThreadsInputThreadSettings | None 619 "Configuration overrides for the thread, such as AI model selection and context window settings." 620 slug: str | None 621 "Optional URL-safe identifier. Derived from the title when omitted and unique within the thread owner." 622 title: str | None 623 "Display name for the thread. `null` if omitted, which causes the thread to be untitled." 624 visibility: Literal["team", "restricted", "private", "org"] | None 625 "Thread visibility. A team-owned thread with members must explicitly use `restricted` or `private`. User- and agent-owned threads with members default to `private` and reject every other value. `org` is only valid on an organization-owned thread with no team, user, or agent owner."
create_legacy_agent: bool | None
When true, provisions a legacy chat agent alongside the thread. Only needed for integrations that depend on the pre-v2 agent model.
is_unlisted: bool | None
When true, the thread is hidden from the default thread list and accessible only by direct link or ID.
key: str | None
Client-assigned unique key for idempotent creation or later lookup. Must be unique within the owning organization.
kind: Optional[Literal['personal', 'feed']]
Optional behavioral subtype. personal is accepted only for a user-owned thread and limits membership to that user and agents currently owned by them. feed is accepted for any owner and renders the thread as a post feed: message lists return top-level posts with their newest replies inline, and agent responses attach to the root post. Mirror kinds remain server-derived and cannot be selected by callers.
members: list[AgentThreadsInputThreadMembersItem] | None
Users and agents to add atomically when the thread is created. Each target must pass the same authorization rules as a post-creation member add. Slack mirror threads reject non-empty caller-supplied rosters because their membership is sync-owned.
metadata: dict[str, typing.Any] | None
Arbitrary key-value pairs stored alongside the thread. Values must be strings or numbers.
muted: bool | None
When true, push and in-app notifications for this thread are suppressed for the creating user.
org_id: str | None
ID of the organization to create the thread under. Defaults to the authenticated user's primary organization when omitted.
profile_picture: AgentThreadsInputThreadProfilePicture | None
Optional profile image for the thread, provided as a base64-encoded payload.
settings: AgentThreadsInputThreadSettings | None
Configuration overrides for the thread, such as AI model selection and context window settings.
slug: str | None
Optional URL-safe identifier. Derived from the title when omitted and unique within the thread owner.
title: str | None
Display name for the thread. null if omitted, which causes the thread to be untitled.
visibility: Optional[Literal['team', 'restricted', 'private', 'org']]
Thread visibility. A team-owned thread with members must explicitly use restricted or private. User- and agent-owned threads with members default to private and reject every other value. org is only valid on an organization-owned thread with no team, user, or agent owner.
class
AgentThreadsInput(typing.TypedDict):
628class AgentThreadsInput(TypedDict, total=False): 629 "Create a thread for an agent" 630 631 skip_welcome_message: bool | None 632 "When `true`, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to `false`." 633 thread: Required[AgentThreadsInputThread] 634 "Attributes for the new thread. See ThreadCreateParams for available fields."
Create a thread for an agent
skip_welcome_message: bool | None
When true, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to false.
thread: Required[AgentThreadsInputThread]
Attributes for the new thread. See ThreadCreateParams for available fields.
class
AgentUpgradeInput(typing.TypedDict):
637class AgentUpgradeInput(TypedDict, total=False): 638 "Upgrade an agent from an AgentTemplate" 639 640 description: str | None 641 "Instance-specific description override. Pins this value so the template upgrade does not overwrite it." 642 dry_run: bool | None 643 "When `true`, computes and returns the full upgrade diff without persisting any changes. Use with `expected_review_fingerprint` to guard the live apply." 644 email: str | None 645 "Instance-specific email address override. Pins this value so the template upgrade does not overwrite it." 646 expected_review_fingerprint: str | None 647 "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." 648 identity: str | None 649 "Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it." 650 metadata: dict[str, Any] | None 651 "Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it." 652 mode: Literal["reapply", "replace"] | None 653 'Upgrade mode. `"reapply"` (default) refreshes the agent\'s tracked template; `"replace"` moves the agent to a different template (requires `template`).' 654 model: str | None 655 "Instance-specific default model override. Pins this value so the template upgrade does not overwrite it. Pass an empty string to clear the model." 656 name: str | None 657 "Instance-specific name override. Pins this value so the template upgrade does not overwrite it." 658 originator: str | None 659 "Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it." 660 phone_number: str | None 661 "Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it." 662 template: str | None 663 'ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode.'
Upgrade an agent from an AgentTemplate
description: str | None
Instance-specific description override. Pins this value so the template upgrade does not overwrite it.
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):
666class ScheduleListResponseDataItem(BaseModel): 667 agent: str | None = Field( 668 default=None, description="ID of the agent that owns this schedule (`agi_...`)." 669 ) 670 app: str | None = Field( 671 default=None, description="ID of the application the schedule belongs to (`dap_...`)." 672 ) 673 created_at: datetime | None = Field( 674 default=None, description="When the schedule was created (ISO 8601)." 675 ) 676 cron_expression: str | None = Field( 677 default=None, 678 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.', 679 ) 680 id: str = Field(..., description="Schedule ID (`asc_...`).") 681 instructions: str | None = Field( 682 default=None, 683 description="The task description the agent will execute when this schedule fires.", 684 ) 685 last_run_at: datetime | None = Field( 686 default=None, 687 description="UTC datetime of the most recent successful execution. `null` if the schedule has never run.", 688 ) 689 max_runs: int | None = Field( 690 default=None, 691 description='Maximum number of times a recurring schedule may fire before automatically transitioning to `"completed"`. `null` means no limit.', 692 ) 693 metadata: dict[str, Any] | None = Field( 694 default=None, 695 description="Arbitrary key-value pairs attached to the schedule by the agent. Not interpreted by the platform.", 696 ) 697 next_run_at: datetime | None = Field( 698 default=None, 699 description="UTC datetime of the next planned execution. `null` if the schedule has completed, been cancelled, or has not yet been computed.", 700 ) 701 run_count: int | None = Field( 702 default=None, description="Total number of times this schedule has fired." 703 ) 704 schedule_type: str | None = Field( 705 default=None, 706 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.', 707 ) 708 scheduled_at: datetime | None = Field( 709 default=None, 710 description='The exact UTC datetime at which a one-time schedule fires. Present only when `schedule_type` is `"once"`. `null` for recurring schedules.', 711 ) 712 status: str | None = Field( 713 default=None, 714 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).', 715 ) 716 thread: str | None = Field( 717 default=None, 718 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.", 719 ) 720 timezone: str | None = Field( 721 default=None, 722 description='IANA timezone name used to interpret the cron expression or `scheduled_at` (e.g. `"America/New_York"`). Defaults to `"Etc/UTC"`.', 723 ) 724 updated_at: datetime | None = Field( 725 default=None, description="When the schedule was last modified (ISO 8601)." 726 )
!!! 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):
729class ScheduleListResponse(BaseModel): 730 """ 731 Successful response 732 """ 733 734 data: list[ScheduleListResponseDataItem] | None = Field( 735 default=None, description="Array of agent schedule objects matching the query." 736 )
Successful response
class
AgentSearchResponse(pydantic.main.BaseModel):
739class AgentSearchResponse(BaseModel): 740 """ 741 Successful response 742 """ 743 744 data: list[dict[str, Any] | dict[str, Any]] = Field( 745 ..., 746 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.', 747 )
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
AgentSelfSolutionResponse(pydantic.main.BaseModel):
750class AgentSelfSolutionResponse(BaseModel): 751 """ 752 Successful response 753 """ 754 755 lookup_key: str 756 solution_id: str 757 solution_version: str
Successful response
class
AsyncAgentAgentComputerResource:
760class AsyncAgentAgentComputerResource: 761 def __init__(self, http: HttpClient): 762 self._http = http 763 764 async def list(self, agent: str) -> AgentComputerListResponse: 765 """ 766 List computers 767 Returns all computers belonging to the authenticated app, ordered by creation 768 time descending. Pass `agent` to scope the results to a single agent's 769 computers. When `agent` is omitted, computers for all agents in the app are 770 returned. 771 Requires an app-scoped API key. If the specified agent does not exist or does 772 not belong to the app, the endpoint returns 404. 773 774 Args: 775 agent: Agent IDs (`agi_...`). When provided, only computers belonging to these agents are returned. Multiple values are OR'd. 776 777 Returns: 778 Object containing a `data` array of computer records. 779 """ 780 return await self._http.request( 781 f"/api/v1/agents/{agent}/agent_computers", 782 response_type=AgentComputerListResponse, 783 ) 784 785 async def create(self, agent: str, input: AgentAgentComputerCreateInput) -> AgentComputer: 786 """ 787 Provision a computer for an agent 788 Creates and provisions a new computer resource associated with the specified 789 agent. The computer is allocated in the requested region (defaulting to `iad`) 790 and its status transitions from `provisioning` to `running` once it is ready. 791 Requires an app-scoped API key. The agent identified by `agent` must belong 792 to the same app. Supplying a `lookup_key` lets you retrieve this computer 793 later without storing its ID the key must be unique within the app. 794 795 Args: 796 agent: Agent IDs (`agi_...`). When provided, only computers belonging to these agents are returned. Multiple values are OR'd. 797 input: Request body. 798 input.acl: Initial access control list. 799 input.config: Provider-specific configuration for the computer. Supported keys vary by provider. A top-level `provider` takes precedence over `config.provider`. 800 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. 801 input.metadata: Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads. 802 input.name: Human-readable display name for the computer. 803 input.provider: Compute backend for the computer: `"sprites"` (Fly Sprites, the default), `"vercel"` (Vercel Sandbox) or `"e2b"` (E2B). Folded into `config.provider`. 804 input.region: Region in which to provision the computer, e.g. `"iad"`. Defaults to `"iad"` when omitted. 805 806 Returns: 807 The newly provisioned computer. 808 """ 809 return await self._http.request( 810 f"/api/v1/agents/{agent}/agent_computers", 811 method="POST", 812 body=input, 813 response_type=AgentComputer, 814 )
AsyncAgentAgentComputerResource(http: archastro.platform.runtime.http_client.HttpClient)
764 async def list(self, agent: str) -> AgentComputerListResponse: 765 """ 766 List computers 767 Returns all computers belonging to the authenticated app, ordered by creation 768 time descending. Pass `agent` to scope the results to a single agent's 769 computers. When `agent` is omitted, computers for all agents in the app are 770 returned. 771 Requires an app-scoped API key. If the specified agent does not exist or does 772 not belong to the app, the endpoint returns 404. 773 774 Args: 775 agent: Agent IDs (`agi_...`). When provided, only computers belonging to these agents are returned. Multiple values are OR'd. 776 777 Returns: 778 Object containing a `data` array of computer records. 779 """ 780 return await self._http.request( 781 f"/api/v1/agents/{agent}/agent_computers", 782 response_type=AgentComputerListResponse, 783 )
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 IDs (
agi_...). When provided, only computers belonging to these agents are returned. Multiple values are OR'd.
Returns:
Object containing a
dataarray of computer records.
async def
create( self, agent: str, input: AgentAgentComputerCreateInput) -> archastro.platform.types.common.AgentComputer:
785 async def create(self, agent: str, input: AgentAgentComputerCreateInput) -> AgentComputer: 786 """ 787 Provision a computer for an agent 788 Creates and provisions a new computer resource associated with the specified 789 agent. The computer is allocated in the requested region (defaulting to `iad`) 790 and its status transitions from `provisioning` to `running` once it is ready. 791 Requires an app-scoped API key. The agent identified by `agent` must belong 792 to the same app. Supplying a `lookup_key` lets you retrieve this computer 793 later without storing its ID the key must be unique within the app. 794 795 Args: 796 agent: Agent IDs (`agi_...`). When provided, only computers belonging to these agents are returned. Multiple values are OR'd. 797 input: Request body. 798 input.acl: Initial access control list. 799 input.config: Provider-specific configuration for the computer. Supported keys vary by provider. A top-level `provider` takes precedence over `config.provider`. 800 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. 801 input.metadata: Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads. 802 input.name: Human-readable display name for the computer. 803 input.provider: Compute backend for the computer: `"sprites"` (Fly Sprites, the default), `"vercel"` (Vercel Sandbox) or `"e2b"` (E2B). Folded into `config.provider`. 804 input.region: Region in which to provision the computer, e.g. `"iad"`. Defaults to `"iad"` when omitted. 805 806 Returns: 807 The newly provisioned computer. 808 """ 809 return await self._http.request( 810 f"/api/v1/agents/{agent}/agent_computers", 811 method="POST", 812 body=input, 813 response_type=AgentComputer, 814 )
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 IDs (
agi_...). When provided, only computers belonging to these agents are returned. Multiple values are OR'd. - input: Request body.
- input.acl: Initial access control list.
- 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),"vercel"(Vercel Sandbox) or"e2b"(E2B). 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:
817class AsyncAgentAgentEnvVarResource: 818 def __init__(self, http: HttpClient): 819 self._http = http 820 821 async def list(self, agent: str) -> AgentEnvVarMaskedList: 822 """ 823 List an agent's environment variables 824 Returns all environment variables defined for the specified agent. Variable 825 values are always masked in the response; only the last four characters are 826 visible. To inspect a specific variable, use the retrieve endpoint. 827 The authenticated user must have access to the agent's parent app. Pass the 828 app scope via the `app` parameter when calling with an API key that is scoped 829 to a specific app. Results are returned in an unordered flat list. 830 831 Args: 832 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 833 834 Returns: 835 List of environment variables for the agent, with values masked. 836 """ 837 return await self._http.request( 838 f"/api/v1/agents/{agent}/agent_env_vars", 839 response_type=AgentEnvVarMaskedList, 840 ) 841 842 async def create(self, agent: str, input: AgentAgentEnvVarCreateInput) -> AgentEnvVarMasked: 843 """ 844 Create an agent environment variable 845 Creates a new environment variable for the specified agent. The variable is 846 stored securely and the plaintext `value` is never returned after creation; 847 subsequent reads return a masked representation showing only the last four 848 characters. 849 The authenticated user must have access to the agent's parent app. Pass the 850 app scope via the `app` parameter when calling with an API key that is scoped 851 to a specific app. Each `key` must be unique within the agent; attempting to 852 create a duplicate key returns a validation error. 853 854 Args: 855 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 856 input: Request body. 857 input.description: Optional human-readable note describing what the variable is used for. 858 input.key: Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent. 859 input.value: Plaintext secret value to store. The value is encrypted at rest and never returned in full. 860 861 Returns: 862 The newly created environment variable with its value masked. 863 """ 864 return await self._http.request( 865 f"/api/v1/agents/{agent}/agent_env_vars", 866 method="POST", 867 body=input, 868 response_type=AgentEnvVarMasked, 869 )
AsyncAgentAgentEnvVarResource(http: archastro.platform.runtime.http_client.HttpClient)
821 async def list(self, agent: str) -> AgentEnvVarMaskedList: 822 """ 823 List an agent's environment variables 824 Returns all environment variables defined for the specified agent. Variable 825 values are always masked in the response; only the last four characters are 826 visible. To inspect a specific variable, use the retrieve endpoint. 827 The authenticated user must have access to the agent's parent app. Pass the 828 app scope via the `app` parameter when calling with an API key that is scoped 829 to a specific app. Results are returned in an unordered flat list. 830 831 Args: 832 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 833 834 Returns: 835 List of environment variables for the agent, with values masked. 836 """ 837 return await self._http.request( 838 f"/api/v1/agents/{agent}/agent_env_vars", 839 response_type=AgentEnvVarMaskedList, 840 )
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:
842 async def create(self, agent: str, input: AgentAgentEnvVarCreateInput) -> AgentEnvVarMasked: 843 """ 844 Create an agent environment variable 845 Creates a new environment variable for the specified agent. The variable is 846 stored securely and the plaintext `value` is never returned after creation; 847 subsequent reads return a masked representation showing only the last four 848 characters. 849 The authenticated user must have access to the agent's parent app. Pass the 850 app scope via the `app` parameter when calling with an API key that is scoped 851 to a specific app. Each `key` must be unique within the agent; attempting to 852 create a duplicate key returns a validation error. 853 854 Args: 855 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 856 input: Request body. 857 input.description: Optional human-readable note describing what the variable is used for. 858 input.key: Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent. 859 input.value: Plaintext secret value to store. The value is encrypted at rest and never returned in full. 860 861 Returns: 862 The newly created environment variable with its value masked. 863 """ 864 return await self._http.request( 865 f"/api/v1/agents/{agent}/agent_env_vars", 866 method="POST", 867 body=input, 868 response_type=AgentEnvVarMasked, 869 )
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:
872class AsyncAgentAgentInstallationResource: 873 def __init__(self, http: HttpClient): 874 self._http = http 875 876 async def list(self, agent: str) -> InstallationListResponse: 877 """ 878 List installations for an agent 879 Returns all installations belonging to the specified agent, across all kinds and 880 states. Use this endpoint to inspect which external services and enablement channels 881 an agent is connected to. 882 Results are scoped to the authenticated app and are returned in an unordered array. 883 To list installations across all agents in an app, use the top-level List 884 Installations endpoint instead. The caller must have app scope for the app that 885 owns the agent. 886 887 Args: 888 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 889 890 Returns: 891 The list of installations for the specified agent. 892 """ 893 return await self._http.request( 894 f"/api/v1/agents/{agent}/agent_installations", 895 response_type=InstallationListResponse, 896 ) 897 898 async def create(self, agent: str, input: AgentAgentInstallationCreateInput) -> Installation: 899 """ 900 Create an installation 901 Creates a new installation for an agent, connecting it to an external service or 902 enablement channel via the specified `kind`. The installation begins in a pending 903 state unless an integration is supplied at creation time, in which case it is 904 activated immediately. 905 Supply `shared_integration` to bind an existing org- or app-level integration, or 906 supply `integration` to create a new integration inline and activate the installation 907 in a single request. Supplying both fields returns 422. 908 Use `lookup_key` to assign a stable identifier you can reference later in knowledge 909 search `source_refs`. The key must be unique within the app, org, and sandbox 910 combination. The caller must have app scope for the app that owns the agent. 911 912 Args: 913 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 914 input: Request body. 915 input.config: Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration. 916 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`. 917 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. 918 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. 919 input.shared_integration: ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with `integration`. 920 921 Returns: 922 The newly created installation. 923 """ 924 return await self._http.request( 925 f"/api/v1/agents/{agent}/agent_installations", 926 method="POST", 927 body=input, 928 response_type=Installation, 929 ) 930 931 async def kinds(self, agent: str) -> InstallationKindListResponse: 932 """ 933 List available installation kinds 934 Returns the publicly available installation kinds supported by the API. Use the 935 returned `kind` values when calling the Create Installation endpoint. 936 The list is platform-wide and does not vary by agent. The `agent` parameter is 937 accepted for future per-agent filtering but is currently unused. The caller must 938 have app scope to call this endpoint. 939 940 Args: 941 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 942 943 Returns: 944 The list of publicly available installation kinds. 945 """ 946 return await self._http.request( 947 f"/api/v1/agents/{agent}/agent_installations/kinds", 948 response_type=InstallationKindListResponse, 949 )
AsyncAgentAgentInstallationResource(http: archastro.platform.runtime.http_client.HttpClient)
876 async def list(self, agent: str) -> InstallationListResponse: 877 """ 878 List installations for an agent 879 Returns all installations belonging to the specified agent, across all kinds and 880 states. Use this endpoint to inspect which external services and enablement channels 881 an agent is connected to. 882 Results are scoped to the authenticated app and are returned in an unordered array. 883 To list installations across all agents in an app, use the top-level List 884 Installations endpoint instead. The caller must have app scope for the app that 885 owns the agent. 886 887 Args: 888 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 889 890 Returns: 891 The list of installations for the specified agent. 892 """ 893 return await self._http.request( 894 f"/api/v1/agents/{agent}/agent_installations", 895 response_type=InstallationListResponse, 896 )
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:
898 async def create(self, agent: str, input: AgentAgentInstallationCreateInput) -> Installation: 899 """ 900 Create an installation 901 Creates a new installation for an agent, connecting it to an external service or 902 enablement channel via the specified `kind`. The installation begins in a pending 903 state unless an integration is supplied at creation time, in which case it is 904 activated immediately. 905 Supply `shared_integration` to bind an existing org- or app-level integration, or 906 supply `integration` to create a new integration inline and activate the installation 907 in a single request. Supplying both fields returns 422. 908 Use `lookup_key` to assign a stable identifier you can reference later in knowledge 909 search `source_refs`. The key must be unique within the app, org, and sandbox 910 combination. The caller must have app scope for the app that owns the agent. 911 912 Args: 913 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 914 input: Request body. 915 input.config: Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration. 916 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`. 917 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. 918 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. 919 input.shared_integration: ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with `integration`. 920 921 Returns: 922 The newly created installation. 923 """ 924 return await self._http.request( 925 f"/api/v1/agents/{agent}/agent_installations", 926 method="POST", 927 body=input, 928 response_type=Installation, 929 )
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.
931 async def kinds(self, agent: str) -> InstallationKindListResponse: 932 """ 933 List available installation kinds 934 Returns the publicly available installation kinds supported by the API. Use the 935 returned `kind` values when calling the Create Installation endpoint. 936 The list is platform-wide and does not vary by agent. The `agent` parameter is 937 accepted for future per-agent filtering but is currently unused. The caller must 938 have app scope to call this endpoint. 939 940 Args: 941 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 942 943 Returns: 944 The list of publicly available installation kinds. 945 """ 946 return await self._http.request( 947 f"/api/v1/agents/{agent}/agent_installations/kinds", 948 response_type=InstallationKindListResponse, 949 )
List available installation kinds
Returns the publicly available installation kinds supported by the API. 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 publicly available installation kinds.
class
AsyncAgentAgentToolResource:
952class AsyncAgentAgentToolResource: 953 def __init__(self, http: HttpClient): 954 self._http = http 955 956 async def list(self, agent: str, *, kind: str | None = None) -> AgentToolListResponse: 957 """ 958 List agent tools 959 Returns all tools for the authenticated app, optionally filtered by agent 960 or tool kind. Both explicitly created tools and tools derived from connected 961 integrations (installation-sourced tools) are included in the response. 962 Installation-sourced tools appear with `source: "installation"` and 963 `status: "active"`. They are synthesized at request time from connected 964 integrations and do not have a persistent tool ID of the `atl_...` form; 965 their `id` is a composite of the installation ID and server tool type. 966 Use the `agent` filter to retrieve tools for a specific agent. Supplying an 967 `agent` ID that does not belong to the authenticated app returns 404. 968 Requires app scope. 969 970 Args: 971 agent: Filter results to tools belonging to these agents (`agi_...`). Omit to return tools across all agents in the app. Multiple values are OR'd. 972 kind: Filter by tool kind. One of `"builtin"` or `"custom"`. Omit to return tools of all kinds. 973 974 Returns: 975 List of tools matching the supplied filters. 976 """ 977 query: dict[str, object] = {} 978 if kind is not None: 979 query["kind"] = kind 980 return await self._http.request( 981 f"/api/v1/agents/{agent}/agent_tools", 982 query=query, 983 response_type=AgentToolListResponse, 984 ) 985 986 async def create(self, agent: str, input: AgentAgentToolCreateInput) -> AgentTool: 987 """ 988 Create an agent tool 989 Creates a new tool and attaches it to the specified agent. Tools can be 990 either `"builtin"` (a platform-provided capability identified by 991 `builtin_tool_key`) or `"custom"` (a caller-defined tool with its own name, 992 description, parameter schema, and handler). 993 New tools are created in `"draft"` status by default unless `status: 994 "active"` is explicitly supplied. Draft tools are not exposed to the LLM 995 during agent runs; call the activate endpoint to promote them. 996 For built-in tools that support multiple instances per agent (those whose 997 catalog entry has a `multi_instance_mode`), supply `name_prefix` to 998 namespace the LLM-facing tool names. Requires app scope. 999 1000 Args: 1001 agent: Filter results to tools belonging to these agents (`agi_...`). Omit to return tools across all agents in the app. Multiple values are OR'd. 1002 input: Request body. 1003 input.async: When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools. 1004 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. 1005 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. 1006 input.config: Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools. 1007 input.description: Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to `"custom"` tools. 1008 input.handler_type: Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools. 1009 input.kind: Tool kind. One of `"builtin"` or `"custom"`. 1010 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. 1011 input.metadata: Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform. 1012 input.name: Display name for the tool. Required when `kind` is `"custom"`. 1013 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. 1014 input.parameters: JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to `"custom"` tools. 1015 input.status: Initial status of the tool. One of `"draft"` or `"active"`. Defaults to `"draft"` when omitted. 1016 1017 Returns: 1018 The newly created tool. 1019 """ 1020 return await self._http.request( 1021 f"/api/v1/agents/{agent}/agent_tools", 1022 method="POST", 1023 body=input, 1024 response_type=AgentTool, 1025 )
AsyncAgentAgentToolResource(http: archastro.platform.runtime.http_client.HttpClient)
async def
list( self, agent: str, *, kind: str | None = None) -> archastro.platform.types.common.AgentToolListResponse:
956 async def list(self, agent: str, *, kind: str | None = None) -> AgentToolListResponse: 957 """ 958 List agent tools 959 Returns all tools for the authenticated app, optionally filtered by agent 960 or tool kind. Both explicitly created tools and tools derived from connected 961 integrations (installation-sourced tools) are included in the response. 962 Installation-sourced tools appear with `source: "installation"` and 963 `status: "active"`. They are synthesized at request time from connected 964 integrations and do not have a persistent tool ID of the `atl_...` form; 965 their `id` is a composite of the installation ID and server tool type. 966 Use the `agent` filter to retrieve tools for a specific agent. Supplying an 967 `agent` ID that does not belong to the authenticated app returns 404. 968 Requires app scope. 969 970 Args: 971 agent: Filter results to tools belonging to these agents (`agi_...`). Omit to return tools across all agents in the app. Multiple values are OR'd. 972 kind: Filter by tool kind. One of `"builtin"` or `"custom"`. Omit to return tools of all kinds. 973 974 Returns: 975 List of tools matching the supplied filters. 976 """ 977 query: dict[str, object] = {} 978 if kind is not None: 979 query["kind"] = kind 980 return await self._http.request( 981 f"/api/v1/agents/{agent}/agent_tools", 982 query=query, 983 response_type=AgentToolListResponse, 984 )
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 these agents (
agi_...). Omit to return tools across all agents in the app. Multiple values are OR'd. - 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:
986 async def create(self, agent: str, input: AgentAgentToolCreateInput) -> AgentTool: 987 """ 988 Create an agent tool 989 Creates a new tool and attaches it to the specified agent. Tools can be 990 either `"builtin"` (a platform-provided capability identified by 991 `builtin_tool_key`) or `"custom"` (a caller-defined tool with its own name, 992 description, parameter schema, and handler). 993 New tools are created in `"draft"` status by default unless `status: 994 "active"` is explicitly supplied. Draft tools are not exposed to the LLM 995 during agent runs; call the activate endpoint to promote them. 996 For built-in tools that support multiple instances per agent (those whose 997 catalog entry has a `multi_instance_mode`), supply `name_prefix` to 998 namespace the LLM-facing tool names. Requires app scope. 999 1000 Args: 1001 agent: Filter results to tools belonging to these agents (`agi_...`). Omit to return tools across all agents in the app. Multiple values are OR'd. 1002 input: Request body. 1003 input.async: When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools. 1004 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. 1005 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. 1006 input.config: Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools. 1007 input.description: Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to `"custom"` tools. 1008 input.handler_type: Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools. 1009 input.kind: Tool kind. One of `"builtin"` or `"custom"`. 1010 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. 1011 input.metadata: Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform. 1012 input.name: Display name for the tool. Required when `kind` is `"custom"`. 1013 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. 1014 input.parameters: JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to `"custom"` tools. 1015 input.status: Initial status of the tool. One of `"draft"` or `"active"`. Defaults to `"draft"` when omitted. 1016 1017 Returns: 1018 The newly created tool. 1019 """ 1020 return await self._http.request( 1021 f"/api/v1/agents/{agent}/agent_tools", 1022 method="POST", 1023 body=input, 1024 response_type=AgentTool, 1025 )
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 these agents (
agi_...). Omit to return tools across all agents in the app. Multiple values are OR'd. - 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
AsyncAgentWorkingMemoryResource:
1028class AsyncAgentWorkingMemoryResource: 1029 def __init__(self, http: HttpClient): 1030 self._http = http 1031 1032 async def list( 1033 self, 1034 agent: str, 1035 *, 1036 page: int | None = None, 1037 page_size: int | None = None, 1038 search: str | None = None, 1039 ) -> WorkingMemoryEntryListResponse: 1040 """ 1041 List working memory entries for an agent 1042 Returns a paginated list of working memory entries belonging to the specified 1043 agent. Entries are key-value pairs the agent stores for context between 1044 interactions. Results are ordered by creation time descending (newest first) 1045 and can be filtered with a substring search against the key name. 1046 Requires an app-scoped API key. The authenticated caller must have access to 1047 the app the agent belongs to. Returns 403 if the key is not app-scoped, and 1048 404 if the agent does not exist within the accessible scope. 1049 1050 Args: 1051 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 1052 page: Page number to retrieve, starting at 1. Defaults to 1. 1053 page_size: Number of entries to return per page. Defaults to 25. 1054 search: Substring filter applied to entry keys (case-insensitive). Omit to return all keys. 1055 1056 Returns: 1057 Paginated list of working memory entries for the agent. 1058 """ 1059 query: dict[str, object] = {} 1060 if page is not None: 1061 query["page"] = page 1062 if page_size is not None: 1063 query["page_size"] = page_size 1064 if search is not None: 1065 query["search"] = search 1066 return await self._http.request( 1067 f"/api/v1/agents/{agent}/agent_working_memory", 1068 query=query, 1069 response_type=WorkingMemoryEntryListResponse, 1070 ) 1071 1072 async def delete(self, agent: str, entry: str) -> None: 1073 """ 1074 Delete a working memory entry 1075 Permanently deletes a working memory entry from the agent. This action is 1076 irreversible. Expired entries can also be deleted they are hidden from 1077 list results but persist until overwritten or deleted. 1078 Requires an app-scoped API key. The authenticated caller must be able to 1079 modify the agent that owns the entry. Returns 403 if the key is not 1080 app-scoped or the caller lacks modify access, and 404 if the agent or entry 1081 does not exist within the accessible scope. 1082 1083 Args: 1084 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 1085 entry: Working memory entry ID (`amm_...`) to delete. 1086 1087 Returns: 1088 Empty body. Returns HTTP 204 on success. 1089 """ 1090 await self._http.request( 1091 f"/api/v1/agents/{agent}/agent_working_memory/{entry}", 1092 method="DELETE", 1093 ) 1094 1095 async def update( 1096 self, agent: str, entry: str, input: AgentWorkingMemoryUpdateInput 1097 ) -> WorkingMemoryEntry: 1098 """ 1099 Update a working memory entry 1100 Updates the value and/or expiry of an existing working memory entry. Only 1101 the fields you supply are changed; omitted fields retain their current 1102 values. The entry `key` cannot be changed after creation delete the entry 1103 and let the agent (or a future create call) write a new one instead. 1104 Pass `expires_at` as `null` to remove the expiry so the entry no longer 1105 expires. Expired entries can still be updated; they stay hidden from list 1106 results until their expiry is in the future again. 1107 Requires an app-scoped API key. The authenticated caller must be able to 1108 modify the agent that owns the entry. Returns 403 if the key is not 1109 app-scoped or the caller lacks modify access, and 404 if the agent or entry 1110 does not exist within the accessible scope. 1111 1112 Args: 1113 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 1114 entry: Working memory entry ID (`amm_...`) to update. 1115 input: Request body. 1116 input.expires_at: New expiry for the entry (ISO 8601). Pass `null` to remove the expiry so the entry never expires. Omit to keep the current expiry. 1117 input.value: Replacement string value to store under the entry's key. Maximum 65,536 characters. 1118 1119 Returns: 1120 The updated working memory entry. 1121 """ 1122 return await self._http.request( 1123 f"/api/v1/agents/{agent}/agent_working_memory/{entry}", 1124 method="PATCH", 1125 body=input, 1126 response_type=WorkingMemoryEntry, 1127 )
AsyncAgentWorkingMemoryResource(http: archastro.platform.runtime.http_client.HttpClient)
async def
list( self, agent: str, *, page: int | None = None, page_size: int | None = None, search: str | None = None) -> archastro.platform.types.common.WorkingMemoryEntryListResponse:
1032 async def list( 1033 self, 1034 agent: str, 1035 *, 1036 page: int | None = None, 1037 page_size: int | None = None, 1038 search: str | None = None, 1039 ) -> WorkingMemoryEntryListResponse: 1040 """ 1041 List working memory entries for an agent 1042 Returns a paginated list of working memory entries belonging to the specified 1043 agent. Entries are key-value pairs the agent stores for context between 1044 interactions. Results are ordered by creation time descending (newest first) 1045 and can be filtered with a substring search against the key name. 1046 Requires an app-scoped API key. The authenticated caller must have access to 1047 the app the agent belongs to. Returns 403 if the key is not app-scoped, and 1048 404 if the agent does not exist within the accessible scope. 1049 1050 Args: 1051 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 1052 page: Page number to retrieve, starting at 1. Defaults to 1. 1053 page_size: Number of entries to return per page. Defaults to 25. 1054 search: Substring filter applied to entry keys (case-insensitive). Omit to return all keys. 1055 1056 Returns: 1057 Paginated list of working memory entries for the agent. 1058 """ 1059 query: dict[str, object] = {} 1060 if page is not None: 1061 query["page"] = page 1062 if page_size is not None: 1063 query["page_size"] = page_size 1064 if search is not None: 1065 query["search"] = search 1066 return await self._http.request( 1067 f"/api/v1/agents/{agent}/agent_working_memory", 1068 query=query, 1069 response_type=WorkingMemoryEntryListResponse, 1070 )
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
delete(self, agent: str, entry: str) -> None:
1072 async def delete(self, agent: str, entry: str) -> None: 1073 """ 1074 Delete a working memory entry 1075 Permanently deletes a working memory entry from the agent. This action is 1076 irreversible. Expired entries can also be deleted they are hidden from 1077 list results but persist until overwritten or deleted. 1078 Requires an app-scoped API key. The authenticated caller must be able to 1079 modify the agent that owns the entry. Returns 403 if the key is not 1080 app-scoped or the caller lacks modify access, and 404 if the agent or entry 1081 does not exist within the accessible scope. 1082 1083 Args: 1084 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 1085 entry: Working memory entry ID (`amm_...`) to delete. 1086 1087 Returns: 1088 Empty body. Returns HTTP 204 on success. 1089 """ 1090 await self._http.request( 1091 f"/api/v1/agents/{agent}/agent_working_memory/{entry}", 1092 method="DELETE", 1093 )
Delete a working memory entry Permanently deletes a working memory entry from the agent. This action is irreversible. Expired entries can also be deleted they are hidden from list results but persist until overwritten or deleted. Requires an app-scoped API key. The authenticated caller must be able to modify the agent that owns the entry. Returns 403 if the key is not app-scoped or the caller lacks modify access, and 404 if the agent or entry does not exist within the accessible scope.
Arguments:
- agent: Agent ID (
agt_...) whose working memory entries to retrieve. - entry: Working memory entry ID (
amm_...) to delete.
Returns:
Empty body. Returns HTTP 204 on success.
async def
update( self, agent: str, entry: str, input: AgentWorkingMemoryUpdateInput) -> archastro.platform.types.common.WorkingMemoryEntry:
1095 async def update( 1096 self, agent: str, entry: str, input: AgentWorkingMemoryUpdateInput 1097 ) -> WorkingMemoryEntry: 1098 """ 1099 Update a working memory entry 1100 Updates the value and/or expiry of an existing working memory entry. Only 1101 the fields you supply are changed; omitted fields retain their current 1102 values. The entry `key` cannot be changed after creation delete the entry 1103 and let the agent (or a future create call) write a new one instead. 1104 Pass `expires_at` as `null` to remove the expiry so the entry no longer 1105 expires. Expired entries can still be updated; they stay hidden from list 1106 results until their expiry is in the future again. 1107 Requires an app-scoped API key. The authenticated caller must be able to 1108 modify the agent that owns the entry. Returns 403 if the key is not 1109 app-scoped or the caller lacks modify access, and 404 if the agent or entry 1110 does not exist within the accessible scope. 1111 1112 Args: 1113 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 1114 entry: Working memory entry ID (`amm_...`) to update. 1115 input: Request body. 1116 input.expires_at: New expiry for the entry (ISO 8601). Pass `null` to remove the expiry so the entry never expires. Omit to keep the current expiry. 1117 input.value: Replacement string value to store under the entry's key. Maximum 65,536 characters. 1118 1119 Returns: 1120 The updated working memory entry. 1121 """ 1122 return await self._http.request( 1123 f"/api/v1/agents/{agent}/agent_working_memory/{entry}", 1124 method="PATCH", 1125 body=input, 1126 response_type=WorkingMemoryEntry, 1127 )
Update a working memory entry
Updates the value and/or expiry of an existing working memory entry. Only
the fields you supply are changed; omitted fields retain their current
values. The entry key cannot be changed after creation delete the entry
and let the agent (or a future create call) write a new one instead.
Pass expires_at as null to remove the expiry so the entry no longer
expires. Expired entries can still be updated; they stay hidden from list
results until their expiry is in the future again.
Requires an app-scoped API key. The authenticated caller must be able to
modify the agent that owns the entry. Returns 403 if the key is not
app-scoped or the caller lacks modify access, and 404 if the agent or entry
does not exist within the accessible scope.
Arguments:
- agent: Agent ID (
agt_...) whose working memory entries to retrieve. - entry: Working memory entry ID (
amm_...) to update. - input: Request body.
- input.expires_at: New expiry for the entry (ISO 8601). Pass
nullto remove the expiry so the entry never expires. Omit to keep the current expiry. - input.value: Replacement string value to store under the entry's key. Maximum 65,536 characters.
Returns:
The updated working memory entry.
class
AsyncScheduleResource:
1130class AsyncScheduleResource: 1131 def __init__(self, http: HttpClient): 1132 self._http = http 1133 1134 async def list(self, agent: str, *, status: str | None = None) -> ScheduleListResponse: 1135 """ 1136 List schedules for an agent 1137 Returns all schedules belonging to the specified agent in any status. Use the 1138 `status` parameter to narrow results to a single lifecycle state. 1139 Requires an app-scoped API key. The agent must belong to the app identified 1140 by the key. 1141 1142 Args: 1143 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 1144 status: Filter results by schedule status. One of `"active"`, `"paused"`, `"completed"`, `"cancelled"`, or `"expired"`. Omit to return schedules in all statuses. 1145 1146 Returns: 1147 Successful response 1148 """ 1149 query: dict[str, object] = {} 1150 if status is not None: 1151 query["status"] = status 1152 return await self._http.request( 1153 f"/api/v1/agents/{agent}/schedules", 1154 query=query, 1155 response_type=ScheduleListResponse, 1156 ) 1157 1158 async def get(self, agent: str, schedule: str) -> AgentSchedule: 1159 """ 1160 Retrieve a schedule 1161 Returns a single schedule belonging to the specified agent. Use this endpoint 1162 to fetch the current state, next run time, and configuration of an individual 1163 schedule. 1164 Requires an app-scoped API key. Both the agent and the schedule must belong 1165 to the app identified by the key. Returns 404 if the schedule does not exist 1166 or belongs to a different agent. 1167 1168 Args: 1169 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 1170 schedule: Schedule ID (`asc_...`). The schedule to retrieve. 1171 1172 Returns: 1173 The requested agent schedule. 1174 """ 1175 return await self._http.request( 1176 f"/api/v1/agents/{agent}/schedules/{schedule}", 1177 response_type=AgentSchedule, 1178 )
AsyncScheduleResource(http: archastro.platform.runtime.http_client.HttpClient)
1134 async def list(self, agent: str, *, status: str | None = None) -> ScheduleListResponse: 1135 """ 1136 List schedules for an agent 1137 Returns all schedules belonging to the specified agent in any status. Use the 1138 `status` parameter to narrow results to a single lifecycle state. 1139 Requires an app-scoped API key. The agent must belong to the app identified 1140 by the key. 1141 1142 Args: 1143 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 1144 status: Filter results by schedule status. One of `"active"`, `"paused"`, `"completed"`, `"cancelled"`, or `"expired"`. Omit to return schedules in all statuses. 1145 1146 Returns: 1147 Successful response 1148 """ 1149 query: dict[str, object] = {} 1150 if status is not None: 1151 query["status"] = status 1152 return await self._http.request( 1153 f"/api/v1/agents/{agent}/schedules", 1154 query=query, 1155 response_type=ScheduleListResponse, 1156 )
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
1158 async def get(self, agent: str, schedule: str) -> AgentSchedule: 1159 """ 1160 Retrieve a schedule 1161 Returns a single schedule belonging to the specified agent. Use this endpoint 1162 to fetch the current state, next run time, and configuration of an individual 1163 schedule. 1164 Requires an app-scoped API key. Both the agent and the schedule must belong 1165 to the app identified by the key. Returns 404 if the schedule does not exist 1166 or belongs to a different agent. 1167 1168 Args: 1169 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 1170 schedule: Schedule ID (`asc_...`). The schedule to retrieve. 1171 1172 Returns: 1173 The requested agent schedule. 1174 """ 1175 return await self._http.request( 1176 f"/api/v1/agents/{agent}/schedules/{schedule}", 1177 response_type=AgentSchedule, 1178 )
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
AsyncAgentWorkItemResource:
1181class AsyncAgentWorkItemResource: 1182 def __init__(self, http: HttpClient): 1183 self._http = http 1184 1185 async def list( 1186 self, 1187 agent: str, 1188 *, 1189 execution: str | None = None, 1190 limit: int | None = None, 1191 after_cursor: str | None = None, 1192 ) -> WorkflowWorkItemList: 1193 """ 1194 List active workflow work available to the viewer 1195 Lists queued, claimed, and running external work yielded by durable workflows. 1196 The top-level collection includes work for every agent the viewer can execute; 1197 the agent-nested collection limits results to that agent. This discovery 1198 response never includes lease tokens. Use the agent claim endpoint to acquire 1199 new work or resume a saved lease. 1200 1201 Args: 1202 agent: Agent ID or lookup key injected by the nested route. 1203 execution: Optional durable execution ID filter. 1204 limit: Maximum work items per page. Defaults to 50; maximum is 100. 1205 after_cursor: Opaque cursor for the next page of older queued work. 1206 1207 Returns: 1208 Successful response 1209 """ 1210 query: dict[str, object] = {} 1211 if execution is not None: 1212 query["execution"] = execution 1213 if limit is not None: 1214 query["limit"] = limit 1215 if after_cursor is not None: 1216 query["after_cursor"] = after_cursor 1217 return await self._http.request( 1218 f"/api/v1/agents/{agent}/work_items", 1219 query=query, 1220 response_type=WorkflowWorkItemList, 1221 ) 1222 1223 async def claim(self, agent: str, input: AgentWorkItemClaimInput) -> WorkflowWorkItemClaim: 1224 """ 1225 Claim or resume workflow work for an agent 1226 Atomically claims the oldest queued or lease-expired item. To resume after a 1227 harness restart, pass both the saved `work_item` and the same `lease_owner`; 1228 the server refreshes that active lease without incrementing its attempt. 1229 Returns `data: null` when no eligible item exists, including when another 1230 lease owns the explicitly requested item. 1231 1232 Args: 1233 agent: Agent ID or lookup key injected by the nested route. 1234 input: Request body. 1235 input.execution: Optional durable execution ID filter. 1236 input.lease_owner: Caller-generated random UUID lease token. 1237 input.lease_seconds: Lease duration from 15 through 3600 seconds. Defaults to 300. 1238 input.work_item: Saved work item ID to resume or reclaim. 1239 1240 Returns: 1241 Successful response 1242 """ 1243 return await self._http.request( 1244 f"/api/v1/agents/{agent}/work_items/claim", 1245 method="POST", 1246 body=input, 1247 response_type=WorkflowWorkItemClaim, 1248 )
AsyncAgentWorkItemResource(http: archastro.platform.runtime.http_client.HttpClient)
async def
list( self, agent: str, *, execution: str | None = None, limit: int | None = None, after_cursor: str | None = None) -> archastro.platform.types.workflows.WorkflowWorkItemList:
1185 async def list( 1186 self, 1187 agent: str, 1188 *, 1189 execution: str | None = None, 1190 limit: int | None = None, 1191 after_cursor: str | None = None, 1192 ) -> WorkflowWorkItemList: 1193 """ 1194 List active workflow work available to the viewer 1195 Lists queued, claimed, and running external work yielded by durable workflows. 1196 The top-level collection includes work for every agent the viewer can execute; 1197 the agent-nested collection limits results to that agent. This discovery 1198 response never includes lease tokens. Use the agent claim endpoint to acquire 1199 new work or resume a saved lease. 1200 1201 Args: 1202 agent: Agent ID or lookup key injected by the nested route. 1203 execution: Optional durable execution ID filter. 1204 limit: Maximum work items per page. Defaults to 50; maximum is 100. 1205 after_cursor: Opaque cursor for the next page of older queued work. 1206 1207 Returns: 1208 Successful response 1209 """ 1210 query: dict[str, object] = {} 1211 if execution is not None: 1212 query["execution"] = execution 1213 if limit is not None: 1214 query["limit"] = limit 1215 if after_cursor is not None: 1216 query["after_cursor"] = after_cursor 1217 return await self._http.request( 1218 f"/api/v1/agents/{agent}/work_items", 1219 query=query, 1220 response_type=WorkflowWorkItemList, 1221 )
List active workflow work available to the viewer Lists queued, claimed, and running external work yielded by durable workflows. The top-level collection includes work for every agent the viewer can execute; the agent-nested collection limits results to that agent. This discovery response never includes lease tokens. Use the agent claim endpoint to acquire new work or resume a saved lease.
Arguments:
- agent: Agent ID or lookup key injected by the nested route.
- execution: Optional durable execution ID filter.
- limit: Maximum work items per page. Defaults to 50; maximum is 100.
- after_cursor: Opaque cursor for the next page of older queued work.
Returns:
Successful response
async def
claim( self, agent: str, input: AgentWorkItemClaimInput) -> archastro.platform.types.workflows.WorkflowWorkItemClaim:
1223 async def claim(self, agent: str, input: AgentWorkItemClaimInput) -> WorkflowWorkItemClaim: 1224 """ 1225 Claim or resume workflow work for an agent 1226 Atomically claims the oldest queued or lease-expired item. To resume after a 1227 harness restart, pass both the saved `work_item` and the same `lease_owner`; 1228 the server refreshes that active lease without incrementing its attempt. 1229 Returns `data: null` when no eligible item exists, including when another 1230 lease owns the explicitly requested item. 1231 1232 Args: 1233 agent: Agent ID or lookup key injected by the nested route. 1234 input: Request body. 1235 input.execution: Optional durable execution ID filter. 1236 input.lease_owner: Caller-generated random UUID lease token. 1237 input.lease_seconds: Lease duration from 15 through 3600 seconds. Defaults to 300. 1238 input.work_item: Saved work item ID to resume or reclaim. 1239 1240 Returns: 1241 Successful response 1242 """ 1243 return await self._http.request( 1244 f"/api/v1/agents/{agent}/work_items/claim", 1245 method="POST", 1246 body=input, 1247 response_type=WorkflowWorkItemClaim, 1248 )
Claim or resume workflow work for an agent
Atomically claims the oldest queued or lease-expired item. To resume after a
harness restart, pass both the saved work_item and the same lease_owner;
the server refreshes that active lease without incrementing its attempt.
Returns data: null when no eligible item exists, including when another
lease owns the explicitly requested item.
Arguments:
- agent: Agent ID or lookup key injected by the nested route.
- input: Request body.
- input.execution: Optional durable execution ID filter.
- input.lease_owner: Caller-generated random UUID lease token.
- input.lease_seconds: Lease duration from 15 through 3600 seconds. Defaults to 300.
- input.work_item: Saved work item ID to resume or reclaim.
Returns:
Successful response
class
AsyncAgentResource:
1251class AsyncAgentResource: 1252 def __init__(self, http: HttpClient): 1253 self._http = http 1254 self.agent_computers = AsyncAgentAgentComputerResource(http) 1255 self.agent_env_vars = AsyncAgentAgentEnvVarResource(http) 1256 self.agent_installations = AsyncAgentAgentInstallationResource(http) 1257 self.agent_tools = AsyncAgentAgentToolResource(http) 1258 self.agent_working_memory = AsyncAgentWorkingMemoryResource(http) 1259 self.schedules = AsyncScheduleResource(http) 1260 self.work_items = AsyncAgentWorkItemResource(http) 1261 1262 async def list( 1263 self, 1264 *, 1265 page: int | None = None, 1266 page_size: int | None = None, 1267 search: str | None = None, 1268 user: str | None = None, 1269 org_id: str | None = None, 1270 template_config: str | None = None, 1271 solution_config: builtins.list[str] | None = None, 1272 ) -> AgentListResponse: 1273 """ 1274 List agents 1275 Returns a paginated list of agents visible to the authenticated caller. Results are 1276 ordered by creation time descending. 1277 Use `search` to filter by name, org, team, or owner fields. Use `user` or `org_id` 1278 to scope the list to a specific owner. Use `template_config` to find agents whose 1279 last applied template matches a given config ID. Use `solution_config` to find 1280 agents whose last applied template was imported as part of any of the given 1281 Solution config IDs. 1282 Pagination is page-based: pass `page` and `page_size` to navigate through large 1283 result sets. When called under a developer app scope, only agents belonging to that 1284 app are returned. 1285 1286 Args: 1287 page: Page number to retrieve, 1-indexed. Defaults to `1`. 1288 page_size: Number of agents to return per page. Defaults to `25`. 1289 search: Free-text search string matched against the agent name, org, team, and owner fields. 1290 user: User ID (`usr_...`) to filter by. Returns only agents owned by this user. 1291 org_id: Organization ID (`org_...`) to filter by. Returns only agents owned by this org. 1292 template_config: Config ID (`cfg_...`) or `lookup_key` of an AgentTemplate. Returns only agents whose last applied template matches. 1293 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. 1294 1295 Returns: 1296 Paginated list of agents matching the supplied filters. 1297 """ 1298 query: dict[str, object] = {} 1299 if page is not None: 1300 query["page"] = page 1301 if page_size is not None: 1302 query["page_size"] = page_size 1303 if search is not None: 1304 query["search"] = search 1305 if user is not None: 1306 query["user"] = user 1307 if org_id is not None: 1308 query["org_id"] = org_id 1309 if template_config is not None: 1310 query["template_config"] = template_config 1311 if solution_config is not None: 1312 query["solution_config"] = solution_config 1313 return await self._http.request( 1314 "/api/v1/agents", 1315 query=query, 1316 response_type=AgentListResponse, 1317 ) 1318 1319 async def create(self, input: AgentCreateInput) -> AgentCreateResponse: 1320 """ 1321 Create an agent 1322 Creates a new agent. Supports two mutually exclusive provisioning modes. 1323 **Template mode** pass `template` with the ID or `lookup_key` of an existing 1324 AgentTemplate config. The agent's tools, routines, skills, and installations are 1325 provisioned from that template's `config_ref` entries. 1326 **Bundle mode** pass `template_bundle` with a self-contained install payload 1327 (AgentTemplate body plus every skill, script, and config it references). The entire 1328 bundle commits in a single transaction; any failure rolls back the whole install and 1329 the response includes `installed_configs[]` one entry per persisted config. 1330 Pass exactly one of `template` or `template_bundle`. If neither is supplied, `name` 1331 is required and a blank agent is created. Requires authentication; when called under 1332 a developer app scope (`/developer/apps/:app/...`), the caller must hold the app scope 1333 for the target app. 1334 1335 Args: 1336 input: Request body. 1337 input.acl: Access control list controlling which users, teams, or orgs can read or manage this agent. 1338 input.description: Human-readable description of what the agent does. 1339 input.email: Email address assigned to the agent. Used as the agent's contact identity. 1340 input.identity: System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn. 1341 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. 1342 input.metadata: Arbitrary key-value map stored on the agent. Not interpreted by the platform. 1343 input.model: Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model. 1344 input.name: Display name for the agent. Required when neither `template` nor `template_bundle` is provided. 1345 input.org: Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`. 1346 input.originator: Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug. 1347 input.phone_number: Phone number assigned to the agent in E.164 format, e.g. `+15550001234`. 1348 input.profile_picture: Profile picture to attach to the agent. All three subfields are required when this object is present. 1349 input.team: Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`. 1350 input.template: ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`. 1351 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`. 1352 input.user: User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`. 1353 1354 Returns: 1355 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. 1356 """ 1357 return await self._http.request( 1358 "/api/v1/agents", 1359 method="POST", 1360 body=input, 1361 response_type=AgentCreateResponse, 1362 ) 1363 1364 async def delete(self, agent: str) -> None: 1365 """ 1366 Delete an agent 1367 Permanently deletes an agent and all of its associated resources. This action cannot 1368 be undone. 1369 The authenticated caller must own the agent or hold sufficient permissions within its 1370 owning org or team. When called under a developer app scope, the caller must hold the 1371 app scope for the target app. 1372 1373 Args: 1374 agent: ID (`agi_...`) or `lookup_key` of the agent to delete. 1375 1376 Returns: 1377 Empty body. Returns HTTP 204 on success. 1378 """ 1379 await self._http.request(f"/api/v1/agents/{agent}", method="DELETE") 1380 1381 async def get(self, agent: str) -> Agent: 1382 """ 1383 Retrieve an agent 1384 Returns the agent identified by ID or `lookup_key`. The authenticated caller must 1385 own the agent or hold sufficient permissions within its owning org or team. 1386 When called under a developer app scope, the agent must belong to that app. Use the 1387 list endpoint to retrieve many agents at once. 1388 1389 Args: 1390 agent: ID (`agi_...`) or `lookup_key` of the agent to retrieve. 1391 1392 Returns: 1393 The requested agent. 1394 """ 1395 return await self._http.request(f"/api/v1/agents/{agent}", response_type=Agent) 1396 1397 async def update(self, agent: str, input: AgentUpdateInput) -> Agent: 1398 """ 1399 Update an agent 1400 Updates one or more fields on an existing agent. Only the fields you supply are 1401 changed; omitted fields retain their current values. 1402 To clear the agent's default model, pass `model` as an empty string. The 1403 authenticated caller must own the agent or hold write permissions within its owning 1404 org or team. When called under a developer app scope, the caller must hold the app 1405 scope for the target app. 1406 1407 Args: 1408 agent: ID (`agi_...`) or `lookup_key` of the agent to update. 1409 input: Request body. 1410 input.acl: Replacement access control list. Fully replaces the existing ACL. 1411 input.description: New description of what the agent does. Pass an empty string to clear it. 1412 input.email: New email address for the agent. 1413 input.identity: Replacement identity system-prompt string describing who the agent is. 1414 input.lookup_key: New `lookup_key` slug. Must be unique within the owning app or org. 1415 input.metadata: Replacement key-value metadata map. The entire map is replaced, not merged. 1416 input.model: New default AI model identifier, e.g. `claude-sonnet-4-5`. Pass an empty string to clear the agent's default model. 1417 input.name: New display name for the agent. 1418 input.org: Organization ID (`org_...`) to transfer ownership to. 1419 input.originator: Replacement originator label identifying the source or author of the agent. 1420 input.phone_number: New phone number for the agent in E.164 format, e.g. `+15550001234`. 1421 input.profile_picture: Replacement profile picture. All three subfields are required when this object is present. 1422 input.team: Team ID (`team_...`) to transfer ownership to. 1423 input.user: User ID (`usr_...`) to transfer ownership to. 1424 1425 Returns: 1426 The updated agent with all current field values. 1427 """ 1428 return await self._http.request( 1429 f"/api/v1/agents/{agent}", 1430 method="PATCH", 1431 body=input, 1432 response_type=Agent, 1433 ) 1434 1435 async def agent_health_actions( 1436 self, 1437 agent: str, 1438 *, 1439 source: builtins.list[str] | None = None, 1440 status: builtins.list[str] | None = None, 1441 kind: builtins.list[str] | None = None, 1442 ) -> HealthActionListResponse: 1443 """ 1444 List health actions for an agent 1445 Returns all health actions associated with a given agent. Health actions 1446 represent required or recommended steps such as setting environment 1447 variables, completing OAuth installations, or running custom verifiers 1448 that an agent needs to reach a healthy state. 1449 Results are not paginated; the full list for the agent is returned. Use 1450 the `source`, `status`, and `kind` filters to narrow results to the 1451 subset your UI or workflow needs. Multiple values for the same filter 1452 are treated as OR (e.g. passing two statuses returns actions matching 1453 either). The caller must be authenticated and scoped to the app that 1454 owns the agent. 1455 1456 Args: 1457 agent: Agent ID (`agt_...`) or lookup key of the agent whose health actions you want to list. 1458 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. 1459 status: Filter results to actions in one or more statuses. Accepted values: `"pending"`, `"completed"`, `"skipped"`, and `"degraded"`. Omit to return actions in all statuses. 1460 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. 1461 1462 Returns: 1463 Object containing a `data` array of health action objects for the specified agent. 1464 """ 1465 query: dict[str, object] = {} 1466 if source is not None: 1467 query["source"] = source 1468 if status is not None: 1469 query["status"] = status 1470 if kind is not None: 1471 query["kind"] = kind 1472 return await self._http.request( 1473 f"/api/v1/agents/{agent}/agent_health_actions", 1474 query=query, 1475 response_type=HealthActionListResponse, 1476 ) 1477 1478 async def agent_routines(self, agent: str, input: AgentAgentRoutinesInput) -> AgentRoutine: 1479 """ 1480 Create a routine 1481 Creates a new routine and attaches it to the specified agent. Routines define 1482 how an agent responds to events or a cron schedule; the `handler_type` controls 1483 which execution model is used. 1484 The routine is created in `"draft"` status by default. To start processing 1485 events immediately, either pass `status: "active"` or call the activate 1486 endpoint after creation. Scheduled routines must run no more frequently than 1487 once per hour. Requires app scope. 1488 1489 Args: 1490 agent: Agent ID (`agt_...`) that this routine will be attached to. 1491 input: Request body. 1492 input.acl: Access control list governing who can read or manage this routine. 1493 input.config: Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`. 1494 input.description: Optional human-readable description of what this routine does. 1495 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"`). 1496 input.event_type: Event type that triggers this routine. Deprecated use `event_config` instead. 1497 input.handler_type: Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`. 1498 input.lookup_key: Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app. 1499 input.message_policy: Visibility and explicit recipient selection for messages emitted by the routine. 1500 input.metadata: Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform. 1501 input.name: Human-readable display name for the routine. 1502 input.preset_config: Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`. 1503 input.preset_name: Name of the registered preset to use. Required when `handler_type` is `"preset"`. 1504 input.schedule: Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour. 1505 input.script: Inline script source. Required when `handler_type` is `"script"`. 1506 input.status: Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`. 1507 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`. 1508 input.trigger_context: Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`. 1509 input.user: Optional co-owner user ID (`usr_...`). When set, that user shares authority over this routine (view/modify/delete) without needing to administer the parent agent. Must be supplied explicitly the caller's identity is never auto-stamped as co-owner. 1510 1511 Returns: 1512 The newly created routine. 1513 """ 1514 return await self._http.request( 1515 f"/api/v1/agents/{agent}/agent_routines", 1516 method="POST", 1517 body=input, 1518 response_type=AgentRoutine, 1519 ) 1520 1521 async def export(self, agent: str, *, remove_identity: bool | None = None) -> AgentExport: 1522 """ 1523 Export an agent as an AgentTemplate 1524 Reconstructs an AgentTemplate config from a deployed agent and all of its 1525 sub-resources (tools, routines, skills, installations). Returns the template 1526 definition together with every dependent config file (scripts, workflows, skills, 1527 schemas) and their raw content, producing a fully self-contained export bundle. 1528 Use this endpoint to snapshot an agent's current configuration for backup, 1529 migration, or to seed a new Solution template. Pass `remove_identity: true` to 1530 strip instance-specific fields (email, phone number) before export. 1531 The authenticated caller must own the agent or hold sufficient permissions within 1532 its owning org or team. When called under a developer app scope, the caller must 1533 hold the app scope for the target app. 1534 1535 Args: 1536 agent: ID (`agi_...`) or `lookup_key` of the agent to export. 1537 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. 1538 1539 Returns: 1540 Export bundle containing the reconstructed AgentTemplate and all dependent config files with their raw content. 1541 """ 1542 query: dict[str, object] = {} 1543 if remove_identity is not None: 1544 query["remove_identity"] = remove_identity 1545 return await self._http.request( 1546 f"/api/v1/agents/{agent}/export", 1547 query=query, 1548 response_type=AgentExport, 1549 ) 1550 1551 async def health(self, agent: str) -> AgentHealth: 1552 """ 1553 Retrieve an agent's health profile 1554 Returns an aggregate health profile for the specified agent, including an overall 1555 status, a numeric health score, recent activity metrics, and a list of recommended 1556 remediation actions. 1557 The health check is computed on demand at request time. The `checked_at` timestamp 1558 in the response reflects when the evaluation ran. Use this endpoint to surface 1559 diagnostics about tool availability, model configuration, and runtime activity in 1560 dashboards or monitoring workflows. 1561 The authenticated caller must own the agent or hold sufficient permissions within 1562 its owning org or team. When called under a developer app scope, the caller must 1563 hold the app scope for the target app. 1564 1565 Args: 1566 agent: ID (`agi_...`) or `lookup_key` of the agent to evaluate. 1567 1568 Returns: 1569 Aggregate health profile for the agent, including status, score, activity metrics, and recommended actions. 1570 """ 1571 return await self._http.request(f"/api/v1/agents/{agent}/health", response_type=AgentHealth) 1572 1573 async def search(self, agent: str, input: AgentSearchInput) -> AgentSearchResponse: 1574 """ 1575 Search an agent's knowledge base 1576 Performs a semantic search over an agent's knowledge base and returns a ranked, 1577 `kind`-discriminated list of matching items. 1578 Threads are automatically indexed as conversational memory, including prior agent 1579 answers. A match is not necessarily independent source evidence. Result `type` 1580 identifies the source: `thread/messages` is conversation memory; use `source_types` 1581 with the desired corpus slugs (for example `knowledge/documents`) to exclude it. 1582 `kind` describes storage granularity, not whether the content is conversation memory. 1583 Two item kinds may appear in `data`: 1584 - `"chunk"` chunk-level results from the agent's context store. Present for all agents. 1585 - `"document"` document-level results. Present only when the agent has an active 1586 `archastro/knowledge` installation. 1587 Results from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to 1588 be comparable across kinds, then merged into a single ranked list. On a relevance tie, 1589 chunks appear before documents. The total number of results is capped at `max_results` 1590 across both kinds. 1591 Use `mode` to choose the retrieval strategy: `"hybrid"` (default) combines vector and 1592 full-text search; `"vector"` and `"fulltext"` select each strategy independently. 1593 1594 Args: 1595 agent: ID (`agi_...`) or `lookup_key` of the agent whose knowledge base to search. 1596 input: Request body. 1597 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`. 1598 input.min_similarity: Cosine-similarity floor for the vector leg, 0.0-1.0, applied to both chunk and document results. Candidates below it are discarded before ranking, so a high value trades recall for precision. Pass `0.0` to disable the floor when a missed match costs more than a weak one note that with no floor every query returns results, so an empty response can no longer be read as "no match". Omit to use the default. 1599 input.mode: Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`. 1600 input.query: Natural-language search query used to retrieve relevant knowledge items. 1601 input.recency_days: When set, restricts results to items indexed within the last N days. 1602 input.source_types: Exact source-type slugs filtering both chunks and documents, e.g. `["knowledge/documents"]` for authored documents or `["thread/messages"]` for conversation memory. Omit or pass an empty array to include all source types. 1603 1604 Returns: 1605 Successful response 1606 """ 1607 return await self._http.request( 1608 f"/api/v1/agents/{agent}/search", 1609 method="POST", 1610 body=input, 1611 response_type=AgentSearchResponse, 1612 ) 1613 1614 async def self_solution(self, agent: str) -> AgentSelfSolutionResponse: 1615 """ 1616 Ensure an agent's private self-solution 1617 Lazily snapshots an authorized agent into its single private, versioned Solution. 1618 1619 Args: 1620 agent: Agent ID or lookup key. 1621 1622 Returns: 1623 Successful response 1624 """ 1625 return await self._http.request( 1626 f"/api/v1/agents/{agent}/self_solution", 1627 response_type=AgentSelfSolutionResponse, 1628 ) 1629 1630 async def threads(self, agent: str, input: AgentThreadsInput) -> Thread: 1631 """ 1632 Create a thread for an agent 1633 Creates a new thread owned by the specified agent. The thread is scoped to the 1634 agent's identity and is immediately available for messaging. 1635 The authenticated caller must have access to the agent's parent app. If your 1636 API key is scoped to a specific app, pass that app's ID via the `app` parameter. 1637 Attempting to create a thread for an agent you cannot access returns 404. 1638 By default the platform may send an automatic welcome message into the new 1639 thread. Pass `skip_welcome_message: true` to suppress this behavior. 1640 1641 Args: 1642 agent: Agent ID (`agt_...`). The thread will be owned by this agent. 1643 input: Request body. 1644 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to `false`. 1645 input.thread: Attributes for the new thread. See ThreadCreateParams for available fields. 1646 1647 Returns: 1648 The newly created thread. 1649 """ 1650 return await self._http.request( 1651 f"/api/v1/agents/{agent}/threads", 1652 method="POST", 1653 body=input, 1654 response_type=Thread, 1655 ) 1656 1657 async def upgrade(self, agent: str, input: AgentUpgradeInput) -> AgentUpgradeResponse: 1658 """ 1659 Upgrade an agent from an AgentTemplate 1660 Upgrades an existing agent by reconciling it against an AgentTemplate from a 1661 Solution. Supports two modes: 1662 - `"reapply"` (default) re-applies the agent's currently tracked template, 1663 picking up any changes the template author has made since the last apply. 1664 - `"replace"` moves the agent to a different template. `template` is required 1665 in this mode. 1666 Set `dry_run: true` to compute and return the full upgrade diff (adds, updates, 1667 removes, noops) without writing any changes. The response includes a 1668 `review_fingerprint` you can pass back via `expected_review_fingerprint` on the 1669 live apply to guard against the diff changing between review and execution. 1670 Safe overrides (`name`, `description`, `email`, `phone_number`, `metadata`, 1671 `identity`, `originator`, `model`) let you pin instance-specific values that 1672 should not be overwritten by the template during the upgrade. 1673 The authenticated caller must own the agent or hold write permissions within its 1674 owning org or team. When called under a developer app scope, the caller must hold 1675 the app scope for the target app. 1676 1677 Args: 1678 agent: ID (`agi_...`) or `lookup_key` of the agent to upgrade. 1679 input: Request body. 1680 input.description: Instance-specific description override. Pins this value so the template upgrade does not overwrite it. 1681 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. 1682 input.email: Instance-specific email address override. Pins this value so the template upgrade does not overwrite it. 1683 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. 1684 input.identity: Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it. 1685 input.metadata: Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it. 1686 input.mode: Upgrade mode. `"reapply"` (default) refreshes the agent's tracked template; `"replace"` moves the agent to a different template (requires `template`). 1687 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. 1688 input.name: Instance-specific name override. Pins this value so the template upgrade does not overwrite it. 1689 input.originator: Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it. 1690 input.phone_number: Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it. 1691 input.template: ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode. 1692 1693 Returns: 1694 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. 1695 """ 1696 return await self._http.request( 1697 f"/api/v1/agents/{agent}/upgrade", 1698 method="POST", 1699 body=input, 1700 response_type=AgentUpgradeResponse, 1701 )
AsyncAgentResource(http: archastro.platform.runtime.http_client.HttpClient)
1252 def __init__(self, http: HttpClient): 1253 self._http = http 1254 self.agent_computers = AsyncAgentAgentComputerResource(http) 1255 self.agent_env_vars = AsyncAgentAgentEnvVarResource(http) 1256 self.agent_installations = AsyncAgentAgentInstallationResource(http) 1257 self.agent_tools = AsyncAgentAgentToolResource(http) 1258 self.agent_working_memory = AsyncAgentWorkingMemoryResource(http) 1259 self.schedules = AsyncScheduleResource(http) 1260 self.work_items = AsyncAgentWorkItemResource(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:
1262 async def list( 1263 self, 1264 *, 1265 page: int | None = None, 1266 page_size: int | None = None, 1267 search: str | None = None, 1268 user: str | None = None, 1269 org_id: str | None = None, 1270 template_config: str | None = None, 1271 solution_config: builtins.list[str] | None = None, 1272 ) -> AgentListResponse: 1273 """ 1274 List agents 1275 Returns a paginated list of agents visible to the authenticated caller. Results are 1276 ordered by creation time descending. 1277 Use `search` to filter by name, org, team, or owner fields. Use `user` or `org_id` 1278 to scope the list to a specific owner. Use `template_config` to find agents whose 1279 last applied template matches a given config ID. Use `solution_config` to find 1280 agents whose last applied template was imported as part of any of the given 1281 Solution config IDs. 1282 Pagination is page-based: pass `page` and `page_size` to navigate through large 1283 result sets. When called under a developer app scope, only agents belonging to that 1284 app are returned. 1285 1286 Args: 1287 page: Page number to retrieve, 1-indexed. Defaults to `1`. 1288 page_size: Number of agents to return per page. Defaults to `25`. 1289 search: Free-text search string matched against the agent name, org, team, and owner fields. 1290 user: User ID (`usr_...`) to filter by. Returns only agents owned by this user. 1291 org_id: Organization ID (`org_...`) to filter by. Returns only agents owned by this org. 1292 template_config: Config ID (`cfg_...`) or `lookup_key` of an AgentTemplate. Returns only agents whose last applied template matches. 1293 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. 1294 1295 Returns: 1296 Paginated list of agents matching the supplied filters. 1297 """ 1298 query: dict[str, object] = {} 1299 if page is not None: 1300 query["page"] = page 1301 if page_size is not None: 1302 query["page_size"] = page_size 1303 if search is not None: 1304 query["search"] = search 1305 if user is not None: 1306 query["user"] = user 1307 if org_id is not None: 1308 query["org_id"] = org_id 1309 if template_config is not None: 1310 query["template_config"] = template_config 1311 if solution_config is not None: 1312 query["solution_config"] = solution_config 1313 return await self._http.request( 1314 "/api/v1/agents", 1315 query=query, 1316 response_type=AgentListResponse, 1317 )
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:
1319 async def create(self, input: AgentCreateInput) -> AgentCreateResponse: 1320 """ 1321 Create an agent 1322 Creates a new agent. Supports two mutually exclusive provisioning modes. 1323 **Template mode** pass `template` with the ID or `lookup_key` of an existing 1324 AgentTemplate config. The agent's tools, routines, skills, and installations are 1325 provisioned from that template's `config_ref` entries. 1326 **Bundle mode** pass `template_bundle` with a self-contained install payload 1327 (AgentTemplate body plus every skill, script, and config it references). The entire 1328 bundle commits in a single transaction; any failure rolls back the whole install and 1329 the response includes `installed_configs[]` one entry per persisted config. 1330 Pass exactly one of `template` or `template_bundle`. If neither is supplied, `name` 1331 is required and a blank agent is created. Requires authentication; when called under 1332 a developer app scope (`/developer/apps/:app/...`), the caller must hold the app scope 1333 for the target app. 1334 1335 Args: 1336 input: Request body. 1337 input.acl: Access control list controlling which users, teams, or orgs can read or manage this agent. 1338 input.description: Human-readable description of what the agent does. 1339 input.email: Email address assigned to the agent. Used as the agent's contact identity. 1340 input.identity: System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn. 1341 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. 1342 input.metadata: Arbitrary key-value map stored on the agent. Not interpreted by the platform. 1343 input.model: Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model. 1344 input.name: Display name for the agent. Required when neither `template` nor `template_bundle` is provided. 1345 input.org: Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`. 1346 input.originator: Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug. 1347 input.phone_number: Phone number assigned to the agent in E.164 format, e.g. `+15550001234`. 1348 input.profile_picture: Profile picture to attach to the agent. All three subfields are required when this object is present. 1349 input.team: Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`. 1350 input.template: ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`. 1351 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`. 1352 input.user: User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`. 1353 1354 Returns: 1355 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. 1356 """ 1357 return await self._http.request( 1358 "/api/v1/agents", 1359 method="POST", 1360 body=input, 1361 response_type=AgentCreateResponse, 1362 )
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.description: Human-readable description of what the agent does.
- 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:
1364 async def delete(self, agent: str) -> None: 1365 """ 1366 Delete an agent 1367 Permanently deletes an agent and all of its associated resources. This action cannot 1368 be undone. 1369 The authenticated caller must own the agent or hold sufficient permissions within its 1370 owning org or team. When called under a developer app scope, the caller must hold the 1371 app scope for the target app. 1372 1373 Args: 1374 agent: ID (`agi_...`) or `lookup_key` of the agent to delete. 1375 1376 Returns: 1377 Empty body. Returns HTTP 204 on success. 1378 """ 1379 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.
1381 async def get(self, agent: str) -> Agent: 1382 """ 1383 Retrieve an agent 1384 Returns the agent identified by ID or `lookup_key`. The authenticated caller must 1385 own the agent or hold sufficient permissions within its owning org or team. 1386 When called under a developer app scope, the agent must belong to that app. Use the 1387 list endpoint to retrieve many agents at once. 1388 1389 Args: 1390 agent: ID (`agi_...`) or `lookup_key` of the agent to retrieve. 1391 1392 Returns: 1393 The requested agent. 1394 """ 1395 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:
1397 async def update(self, agent: str, input: AgentUpdateInput) -> Agent: 1398 """ 1399 Update an agent 1400 Updates one or more fields on an existing agent. Only the fields you supply are 1401 changed; omitted fields retain their current values. 1402 To clear the agent's default model, pass `model` as an empty string. The 1403 authenticated caller must own the agent or hold write permissions within its owning 1404 org or team. When called under a developer app scope, the caller must hold the app 1405 scope for the target app. 1406 1407 Args: 1408 agent: ID (`agi_...`) or `lookup_key` of the agent to update. 1409 input: Request body. 1410 input.acl: Replacement access control list. Fully replaces the existing ACL. 1411 input.description: New description of what the agent does. Pass an empty string to clear it. 1412 input.email: New email address for the agent. 1413 input.identity: Replacement identity system-prompt string describing who the agent is. 1414 input.lookup_key: New `lookup_key` slug. Must be unique within the owning app or org. 1415 input.metadata: Replacement key-value metadata map. The entire map is replaced, not merged. 1416 input.model: New default AI model identifier, e.g. `claude-sonnet-4-5`. Pass an empty string to clear the agent's default model. 1417 input.name: New display name for the agent. 1418 input.org: Organization ID (`org_...`) to transfer ownership to. 1419 input.originator: Replacement originator label identifying the source or author of the agent. 1420 input.phone_number: New phone number for the agent in E.164 format, e.g. `+15550001234`. 1421 input.profile_picture: Replacement profile picture. All three subfields are required when this object is present. 1422 input.team: Team ID (`team_...`) to transfer ownership to. 1423 input.user: User ID (`usr_...`) to transfer ownership to. 1424 1425 Returns: 1426 The updated agent with all current field values. 1427 """ 1428 return await self._http.request( 1429 f"/api/v1/agents/{agent}", 1430 method="PATCH", 1431 body=input, 1432 response_type=Agent, 1433 )
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.description: New description of what the agent does. Pass an empty string to clear it.
- 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:
1435 async def agent_health_actions( 1436 self, 1437 agent: str, 1438 *, 1439 source: builtins.list[str] | None = None, 1440 status: builtins.list[str] | None = None, 1441 kind: builtins.list[str] | None = None, 1442 ) -> HealthActionListResponse: 1443 """ 1444 List health actions for an agent 1445 Returns all health actions associated with a given agent. Health actions 1446 represent required or recommended steps such as setting environment 1447 variables, completing OAuth installations, or running custom verifiers 1448 that an agent needs to reach a healthy state. 1449 Results are not paginated; the full list for the agent is returned. Use 1450 the `source`, `status`, and `kind` filters to narrow results to the 1451 subset your UI or workflow needs. Multiple values for the same filter 1452 are treated as OR (e.g. passing two statuses returns actions matching 1453 either). The caller must be authenticated and scoped to the app that 1454 owns the agent. 1455 1456 Args: 1457 agent: Agent ID (`agt_...`) or lookup key of the agent whose health actions you want to list. 1458 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. 1459 status: Filter results to actions in one or more statuses. Accepted values: `"pending"`, `"completed"`, `"skipped"`, and `"degraded"`. Omit to return actions in all statuses. 1460 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. 1461 1462 Returns: 1463 Object containing a `data` array of health action objects for the specified agent. 1464 """ 1465 query: dict[str, object] = {} 1466 if source is not None: 1467 query["source"] = source 1468 if status is not None: 1469 query["status"] = status 1470 if kind is not None: 1471 query["kind"] = kind 1472 return await self._http.request( 1473 f"/api/v1/agents/{agent}/agent_health_actions", 1474 query=query, 1475 response_type=HealthActionListResponse, 1476 )
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:
1478 async def agent_routines(self, agent: str, input: AgentAgentRoutinesInput) -> AgentRoutine: 1479 """ 1480 Create a routine 1481 Creates a new routine and attaches it to the specified agent. Routines define 1482 how an agent responds to events or a cron schedule; the `handler_type` controls 1483 which execution model is used. 1484 The routine is created in `"draft"` status by default. To start processing 1485 events immediately, either pass `status: "active"` or call the activate 1486 endpoint after creation. Scheduled routines must run no more frequently than 1487 once per hour. Requires app scope. 1488 1489 Args: 1490 agent: Agent ID (`agt_...`) that this routine will be attached to. 1491 input: Request body. 1492 input.acl: Access control list governing who can read or manage this routine. 1493 input.config: Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`. 1494 input.description: Optional human-readable description of what this routine does. 1495 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"`). 1496 input.event_type: Event type that triggers this routine. Deprecated use `event_config` instead. 1497 input.handler_type: Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`. 1498 input.lookup_key: Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app. 1499 input.message_policy: Visibility and explicit recipient selection for messages emitted by the routine. 1500 input.metadata: Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform. 1501 input.name: Human-readable display name for the routine. 1502 input.preset_config: Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`. 1503 input.preset_name: Name of the registered preset to use. Required when `handler_type` is `"preset"`. 1504 input.schedule: Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour. 1505 input.script: Inline script source. Required when `handler_type` is `"script"`. 1506 input.status: Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`. 1507 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`. 1508 input.trigger_context: Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`. 1509 input.user: Optional co-owner user ID (`usr_...`). When set, that user shares authority over this routine (view/modify/delete) without needing to administer the parent agent. Must be supplied explicitly the caller's identity is never auto-stamped as co-owner. 1510 1511 Returns: 1512 The newly created routine. 1513 """ 1514 return await self._http.request( 1515 f"/api/v1/agents/{agent}/agent_routines", 1516 method="POST", 1517 body=input, 1518 response_type=AgentRoutine, 1519 )
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.message_policy: Visibility and explicit recipient selection for messages emitted by the routine.
- 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". - input.user: Optional co-owner user ID (
usr_...). When set, that user shares authority over this routine (view/modify/delete) without needing to administer the parent agent. Must be supplied explicitly the caller's identity is never auto-stamped as co-owner.
Returns:
The newly created routine.
async def
export( self, agent: str, *, remove_identity: bool | None = None) -> archastro.platform.types.common.AgentExport:
1521 async def export(self, agent: str, *, remove_identity: bool | None = None) -> AgentExport: 1522 """ 1523 Export an agent as an AgentTemplate 1524 Reconstructs an AgentTemplate config from a deployed agent and all of its 1525 sub-resources (tools, routines, skills, installations). Returns the template 1526 definition together with every dependent config file (scripts, workflows, skills, 1527 schemas) and their raw content, producing a fully self-contained export bundle. 1528 Use this endpoint to snapshot an agent's current configuration for backup, 1529 migration, or to seed a new Solution template. Pass `remove_identity: true` to 1530 strip instance-specific fields (email, phone number) before export. 1531 The authenticated caller must own the agent or hold sufficient permissions within 1532 its owning org or team. When called under a developer app scope, the caller must 1533 hold the app scope for the target app. 1534 1535 Args: 1536 agent: ID (`agi_...`) or `lookup_key` of the agent to export. 1537 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. 1538 1539 Returns: 1540 Export bundle containing the reconstructed AgentTemplate and all dependent config files with their raw content. 1541 """ 1542 query: dict[str, object] = {} 1543 if remove_identity is not None: 1544 query["remove_identity"] = remove_identity 1545 return await self._http.request( 1546 f"/api/v1/agents/{agent}/export", 1547 query=query, 1548 response_type=AgentExport, 1549 )
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.
1551 async def health(self, agent: str) -> AgentHealth: 1552 """ 1553 Retrieve an agent's health profile 1554 Returns an aggregate health profile for the specified agent, including an overall 1555 status, a numeric health score, recent activity metrics, and a list of recommended 1556 remediation actions. 1557 The health check is computed on demand at request time. The `checked_at` timestamp 1558 in the response reflects when the evaluation ran. Use this endpoint to surface 1559 diagnostics about tool availability, model configuration, and runtime activity in 1560 dashboards or monitoring workflows. 1561 The authenticated caller must own the agent or hold sufficient permissions within 1562 its owning org or team. When called under a developer app scope, the caller must 1563 hold the app scope for the target app. 1564 1565 Args: 1566 agent: ID (`agi_...`) or `lookup_key` of the agent to evaluate. 1567 1568 Returns: 1569 Aggregate health profile for the agent, including status, score, activity metrics, and recommended actions. 1570 """ 1571 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.
1573 async def search(self, agent: str, input: AgentSearchInput) -> AgentSearchResponse: 1574 """ 1575 Search an agent's knowledge base 1576 Performs a semantic search over an agent's knowledge base and returns a ranked, 1577 `kind`-discriminated list of matching items. 1578 Threads are automatically indexed as conversational memory, including prior agent 1579 answers. A match is not necessarily independent source evidence. Result `type` 1580 identifies the source: `thread/messages` is conversation memory; use `source_types` 1581 with the desired corpus slugs (for example `knowledge/documents`) to exclude it. 1582 `kind` describes storage granularity, not whether the content is conversation memory. 1583 Two item kinds may appear in `data`: 1584 - `"chunk"` chunk-level results from the agent's context store. Present for all agents. 1585 - `"document"` document-level results. Present only when the agent has an active 1586 `archastro/knowledge` installation. 1587 Results from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to 1588 be comparable across kinds, then merged into a single ranked list. On a relevance tie, 1589 chunks appear before documents. The total number of results is capped at `max_results` 1590 across both kinds. 1591 Use `mode` to choose the retrieval strategy: `"hybrid"` (default) combines vector and 1592 full-text search; `"vector"` and `"fulltext"` select each strategy independently. 1593 1594 Args: 1595 agent: ID (`agi_...`) or `lookup_key` of the agent whose knowledge base to search. 1596 input: Request body. 1597 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`. 1598 input.min_similarity: Cosine-similarity floor for the vector leg, 0.0-1.0, applied to both chunk and document results. Candidates below it are discarded before ranking, so a high value trades recall for precision. Pass `0.0` to disable the floor when a missed match costs more than a weak one note that with no floor every query returns results, so an empty response can no longer be read as "no match". Omit to use the default. 1599 input.mode: Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`. 1600 input.query: Natural-language search query used to retrieve relevant knowledge items. 1601 input.recency_days: When set, restricts results to items indexed within the last N days. 1602 input.source_types: Exact source-type slugs filtering both chunks and documents, e.g. `["knowledge/documents"]` for authored documents or `["thread/messages"]` for conversation memory. Omit or pass an empty array to include all source types. 1603 1604 Returns: 1605 Successful response 1606 """ 1607 return await self._http.request( 1608 f"/api/v1/agents/{agent}/search", 1609 method="POST", 1610 body=input, 1611 response_type=AgentSearchResponse, 1612 )
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.
Threads are automatically indexed as conversational memory, including prior agent
answers. A match is not necessarily independent source evidence. Result type
identifies the source: thread/messages is conversation memory; use source_types
with the desired corpus slugs (for example knowledge/documents) to exclude it.
kind describes storage granularity, not whether the content is conversation memory.
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.min_similarity: Cosine-similarity floor for the vector leg, 0.0-1.0, applied to both chunk and document results. Candidates below it are discarded before ranking, so a high value trades recall for precision. Pass
0.0to disable the floor when a missed match costs more than a weak one note that with no floor every query returns results, so an empty response can no longer be read as "no match". Omit to use the default. - 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: Exact source-type slugs filtering both chunks and documents, e.g.
["knowledge/documents"]for authored documents or["thread/messages"]for conversation memory. Omit or pass an empty array to include all source types.
Returns:
Successful response
1614 async def self_solution(self, agent: str) -> AgentSelfSolutionResponse: 1615 """ 1616 Ensure an agent's private self-solution 1617 Lazily snapshots an authorized agent into its single private, versioned Solution. 1618 1619 Args: 1620 agent: Agent ID or lookup key. 1621 1622 Returns: 1623 Successful response 1624 """ 1625 return await self._http.request( 1626 f"/api/v1/agents/{agent}/self_solution", 1627 response_type=AgentSelfSolutionResponse, 1628 )
Ensure an agent's private self-solution Lazily snapshots an authorized agent into its single private, versioned Solution.
Arguments:
- agent: Agent ID or lookup key.
Returns:
Successful response
async def
threads( self, agent: str, input: AgentThreadsInput) -> archastro.platform.types.threads.Thread:
1630 async def threads(self, agent: str, input: AgentThreadsInput) -> Thread: 1631 """ 1632 Create a thread for an agent 1633 Creates a new thread owned by the specified agent. The thread is scoped to the 1634 agent's identity and is immediately available for messaging. 1635 The authenticated caller must have access to the agent's parent app. If your 1636 API key is scoped to a specific app, pass that app's ID via the `app` parameter. 1637 Attempting to create a thread for an agent you cannot access returns 404. 1638 By default the platform may send an automatic welcome message into the new 1639 thread. Pass `skip_welcome_message: true` to suppress this behavior. 1640 1641 Args: 1642 agent: Agent ID (`agt_...`). The thread will be owned by this agent. 1643 input: Request body. 1644 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to `false`. 1645 input.thread: Attributes for the new thread. See ThreadCreateParams for available fields. 1646 1647 Returns: 1648 The newly created thread. 1649 """ 1650 return await self._http.request( 1651 f"/api/v1/agents/{agent}/threads", 1652 method="POST", 1653 body=input, 1654 response_type=Thread, 1655 )
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. See ThreadCreateParams for available fields.
Returns:
The newly created thread.
async def
upgrade( self, agent: str, input: AgentUpgradeInput) -> archastro.platform.types.common.AgentUpgradeResponse:
1657 async def upgrade(self, agent: str, input: AgentUpgradeInput) -> AgentUpgradeResponse: 1658 """ 1659 Upgrade an agent from an AgentTemplate 1660 Upgrades an existing agent by reconciling it against an AgentTemplate from a 1661 Solution. Supports two modes: 1662 - `"reapply"` (default) re-applies the agent's currently tracked template, 1663 picking up any changes the template author has made since the last apply. 1664 - `"replace"` moves the agent to a different template. `template` is required 1665 in this mode. 1666 Set `dry_run: true` to compute and return the full upgrade diff (adds, updates, 1667 removes, noops) without writing any changes. The response includes a 1668 `review_fingerprint` you can pass back via `expected_review_fingerprint` on the 1669 live apply to guard against the diff changing between review and execution. 1670 Safe overrides (`name`, `description`, `email`, `phone_number`, `metadata`, 1671 `identity`, `originator`, `model`) let you pin instance-specific values that 1672 should not be overwritten by the template during the upgrade. 1673 The authenticated caller must own the agent or hold write permissions within its 1674 owning org or team. When called under a developer app scope, the caller must hold 1675 the app scope for the target app. 1676 1677 Args: 1678 agent: ID (`agi_...`) or `lookup_key` of the agent to upgrade. 1679 input: Request body. 1680 input.description: Instance-specific description override. Pins this value so the template upgrade does not overwrite it. 1681 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. 1682 input.email: Instance-specific email address override. Pins this value so the template upgrade does not overwrite it. 1683 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. 1684 input.identity: Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it. 1685 input.metadata: Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it. 1686 input.mode: Upgrade mode. `"reapply"` (default) refreshes the agent's tracked template; `"replace"` moves the agent to a different template (requires `template`). 1687 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. 1688 input.name: Instance-specific name override. Pins this value so the template upgrade does not overwrite it. 1689 input.originator: Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it. 1690 input.phone_number: Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it. 1691 input.template: ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode. 1692 1693 Returns: 1694 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. 1695 """ 1696 return await self._http.request( 1697 f"/api/v1/agents/{agent}/upgrade", 1698 method="POST", 1699 body=input, 1700 response_type=AgentUpgradeResponse, 1701 )
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,description,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.description: Instance-specific description override. Pins this value so the template upgrade does not overwrite it.
- 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:
1704class AgentAgentComputerResource: 1705 def __init__(self, http: SyncHttpClient): 1706 self._http = http 1707 1708 def list(self, agent: str) -> AgentComputerListResponse: 1709 """ 1710 List computers 1711 Returns all computers belonging to the authenticated app, ordered by creation 1712 time descending. Pass `agent` to scope the results to a single agent's 1713 computers. When `agent` is omitted, computers for all agents in the app are 1714 returned. 1715 Requires an app-scoped API key. If the specified agent does not exist or does 1716 not belong to the app, the endpoint returns 404. 1717 1718 Args: 1719 agent: Agent IDs (`agi_...`). When provided, only computers belonging to these agents are returned. Multiple values are OR'd. 1720 1721 Returns: 1722 Object containing a `data` array of computer records. 1723 """ 1724 return self._http.request( 1725 f"/api/v1/agents/{agent}/agent_computers", 1726 response_type=AgentComputerListResponse, 1727 ) 1728 1729 def create(self, agent: str, input: AgentAgentComputerCreateInput) -> AgentComputer: 1730 """ 1731 Provision a computer for an agent 1732 Creates and provisions a new computer resource associated with the specified 1733 agent. The computer is allocated in the requested region (defaulting to `iad`) 1734 and its status transitions from `provisioning` to `running` once it is ready. 1735 Requires an app-scoped API key. The agent identified by `agent` must belong 1736 to the same app. Supplying a `lookup_key` lets you retrieve this computer 1737 later without storing its ID the key must be unique within the app. 1738 1739 Args: 1740 agent: Agent IDs (`agi_...`). When provided, only computers belonging to these agents are returned. Multiple values are OR'd. 1741 input: Request body. 1742 input.acl: Initial access control list. 1743 input.config: Provider-specific configuration for the computer. Supported keys vary by provider. A top-level `provider` takes precedence over `config.provider`. 1744 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. 1745 input.metadata: Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads. 1746 input.name: Human-readable display name for the computer. 1747 input.provider: Compute backend for the computer: `"sprites"` (Fly Sprites, the default), `"vercel"` (Vercel Sandbox) or `"e2b"` (E2B). Folded into `config.provider`. 1748 input.region: Region in which to provision the computer, e.g. `"iad"`. Defaults to `"iad"` when omitted. 1749 1750 Returns: 1751 The newly provisioned computer. 1752 """ 1753 return self._http.request( 1754 f"/api/v1/agents/{agent}/agent_computers", 1755 method="POST", 1756 body=input, 1757 response_type=AgentComputer, 1758 )
AgentAgentComputerResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
1708 def list(self, agent: str) -> AgentComputerListResponse: 1709 """ 1710 List computers 1711 Returns all computers belonging to the authenticated app, ordered by creation 1712 time descending. Pass `agent` to scope the results to a single agent's 1713 computers. When `agent` is omitted, computers for all agents in the app are 1714 returned. 1715 Requires an app-scoped API key. If the specified agent does not exist or does 1716 not belong to the app, the endpoint returns 404. 1717 1718 Args: 1719 agent: Agent IDs (`agi_...`). When provided, only computers belonging to these agents are returned. Multiple values are OR'd. 1720 1721 Returns: 1722 Object containing a `data` array of computer records. 1723 """ 1724 return self._http.request( 1725 f"/api/v1/agents/{agent}/agent_computers", 1726 response_type=AgentComputerListResponse, 1727 )
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 IDs (
agi_...). When provided, only computers belonging to these agents are returned. Multiple values are OR'd.
Returns:
Object containing a
dataarray of computer records.
def
create( self, agent: str, input: AgentAgentComputerCreateInput) -> archastro.platform.types.common.AgentComputer:
1729 def create(self, agent: str, input: AgentAgentComputerCreateInput) -> AgentComputer: 1730 """ 1731 Provision a computer for an agent 1732 Creates and provisions a new computer resource associated with the specified 1733 agent. The computer is allocated in the requested region (defaulting to `iad`) 1734 and its status transitions from `provisioning` to `running` once it is ready. 1735 Requires an app-scoped API key. The agent identified by `agent` must belong 1736 to the same app. Supplying a `lookup_key` lets you retrieve this computer 1737 later without storing its ID the key must be unique within the app. 1738 1739 Args: 1740 agent: Agent IDs (`agi_...`). When provided, only computers belonging to these agents are returned. Multiple values are OR'd. 1741 input: Request body. 1742 input.acl: Initial access control list. 1743 input.config: Provider-specific configuration for the computer. Supported keys vary by provider. A top-level `provider` takes precedence over `config.provider`. 1744 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. 1745 input.metadata: Arbitrary key-value metadata to attach to the computer. Not interpreted by the platform; returned as-is on all subsequent reads. 1746 input.name: Human-readable display name for the computer. 1747 input.provider: Compute backend for the computer: `"sprites"` (Fly Sprites, the default), `"vercel"` (Vercel Sandbox) or `"e2b"` (E2B). Folded into `config.provider`. 1748 input.region: Region in which to provision the computer, e.g. `"iad"`. Defaults to `"iad"` when omitted. 1749 1750 Returns: 1751 The newly provisioned computer. 1752 """ 1753 return self._http.request( 1754 f"/api/v1/agents/{agent}/agent_computers", 1755 method="POST", 1756 body=input, 1757 response_type=AgentComputer, 1758 )
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 IDs (
agi_...). When provided, only computers belonging to these agents are returned. Multiple values are OR'd. - input: Request body.
- input.acl: Initial access control list.
- 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),"vercel"(Vercel Sandbox) or"e2b"(E2B). 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:
1761class AgentAgentEnvVarResource: 1762 def __init__(self, http: SyncHttpClient): 1763 self._http = http 1764 1765 def list(self, agent: str) -> AgentEnvVarMaskedList: 1766 """ 1767 List an agent's environment variables 1768 Returns all environment variables defined for the specified agent. Variable 1769 values are always masked in the response; only the last four characters are 1770 visible. To inspect a specific variable, use the retrieve endpoint. 1771 The authenticated user must have access to the agent's parent app. Pass the 1772 app scope via the `app` parameter when calling with an API key that is scoped 1773 to a specific app. Results are returned in an unordered flat list. 1774 1775 Args: 1776 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 1777 1778 Returns: 1779 List of environment variables for the agent, with values masked. 1780 """ 1781 return self._http.request( 1782 f"/api/v1/agents/{agent}/agent_env_vars", 1783 response_type=AgentEnvVarMaskedList, 1784 ) 1785 1786 def create(self, agent: str, input: AgentAgentEnvVarCreateInput) -> AgentEnvVarMasked: 1787 """ 1788 Create an agent environment variable 1789 Creates a new environment variable for the specified agent. The variable is 1790 stored securely and the plaintext `value` is never returned after creation; 1791 subsequent reads return a masked representation showing only the last four 1792 characters. 1793 The authenticated user must have access to the agent's parent app. Pass the 1794 app scope via the `app` parameter when calling with an API key that is scoped 1795 to a specific app. Each `key` must be unique within the agent; attempting to 1796 create a duplicate key returns a validation error. 1797 1798 Args: 1799 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 1800 input: Request body. 1801 input.description: Optional human-readable note describing what the variable is used for. 1802 input.key: Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent. 1803 input.value: Plaintext secret value to store. The value is encrypted at rest and never returned in full. 1804 1805 Returns: 1806 The newly created environment variable with its value masked. 1807 """ 1808 return self._http.request( 1809 f"/api/v1/agents/{agent}/agent_env_vars", 1810 method="POST", 1811 body=input, 1812 response_type=AgentEnvVarMasked, 1813 )
AgentAgentEnvVarResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
1765 def list(self, agent: str) -> AgentEnvVarMaskedList: 1766 """ 1767 List an agent's environment variables 1768 Returns all environment variables defined for the specified agent. Variable 1769 values are always masked in the response; only the last four characters are 1770 visible. To inspect a specific variable, use the retrieve endpoint. 1771 The authenticated user must have access to the agent's parent app. Pass the 1772 app scope via the `app` parameter when calling with an API key that is scoped 1773 to a specific app. Results are returned in an unordered flat list. 1774 1775 Args: 1776 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 1777 1778 Returns: 1779 List of environment variables for the agent, with values masked. 1780 """ 1781 return self._http.request( 1782 f"/api/v1/agents/{agent}/agent_env_vars", 1783 response_type=AgentEnvVarMaskedList, 1784 )
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:
1786 def create(self, agent: str, input: AgentAgentEnvVarCreateInput) -> AgentEnvVarMasked: 1787 """ 1788 Create an agent environment variable 1789 Creates a new environment variable for the specified agent. The variable is 1790 stored securely and the plaintext `value` is never returned after creation; 1791 subsequent reads return a masked representation showing only the last four 1792 characters. 1793 The authenticated user must have access to the agent's parent app. Pass the 1794 app scope via the `app` parameter when calling with an API key that is scoped 1795 to a specific app. Each `key` must be unique within the agent; attempting to 1796 create a duplicate key returns a validation error. 1797 1798 Args: 1799 agent: Agent ID (`agt_...`). Returns environment variables belonging to this agent. 1800 input: Request body. 1801 input.description: Optional human-readable note describing what the variable is used for. 1802 input.key: Environment variable name, e.g. `WEBHOOK_SECRET`. Must be unique within the agent. 1803 input.value: Plaintext secret value to store. The value is encrypted at rest and never returned in full. 1804 1805 Returns: 1806 The newly created environment variable with its value masked. 1807 """ 1808 return self._http.request( 1809 f"/api/v1/agents/{agent}/agent_env_vars", 1810 method="POST", 1811 body=input, 1812 response_type=AgentEnvVarMasked, 1813 )
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:
1816class AgentAgentInstallationResource: 1817 def __init__(self, http: SyncHttpClient): 1818 self._http = http 1819 1820 def list(self, agent: str) -> InstallationListResponse: 1821 """ 1822 List installations for an agent 1823 Returns all installations belonging to the specified agent, across all kinds and 1824 states. Use this endpoint to inspect which external services and enablement channels 1825 an agent is connected to. 1826 Results are scoped to the authenticated app and are returned in an unordered array. 1827 To list installations across all agents in an app, use the top-level List 1828 Installations endpoint instead. The caller must have app scope for the app that 1829 owns the agent. 1830 1831 Args: 1832 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 1833 1834 Returns: 1835 The list of installations for the specified agent. 1836 """ 1837 return self._http.request( 1838 f"/api/v1/agents/{agent}/agent_installations", 1839 response_type=InstallationListResponse, 1840 ) 1841 1842 def create(self, agent: str, input: AgentAgentInstallationCreateInput) -> Installation: 1843 """ 1844 Create an installation 1845 Creates a new installation for an agent, connecting it to an external service or 1846 enablement channel via the specified `kind`. The installation begins in a pending 1847 state unless an integration is supplied at creation time, in which case it is 1848 activated immediately. 1849 Supply `shared_integration` to bind an existing org- or app-level integration, or 1850 supply `integration` to create a new integration inline and activate the installation 1851 in a single request. Supplying both fields returns 422. 1852 Use `lookup_key` to assign a stable identifier you can reference later in knowledge 1853 search `source_refs`. The key must be unique within the app, org, and sandbox 1854 combination. The caller must have app scope for the app that owns the agent. 1855 1856 Args: 1857 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 1858 input: Request body. 1859 input.config: Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration. 1860 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`. 1861 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. 1862 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. 1863 input.shared_integration: ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with `integration`. 1864 1865 Returns: 1866 The newly created installation. 1867 """ 1868 return self._http.request( 1869 f"/api/v1/agents/{agent}/agent_installations", 1870 method="POST", 1871 body=input, 1872 response_type=Installation, 1873 ) 1874 1875 def kinds(self, agent: str) -> InstallationKindListResponse: 1876 """ 1877 List available installation kinds 1878 Returns the publicly available installation kinds supported by the API. Use the 1879 returned `kind` values when calling the Create Installation endpoint. 1880 The list is platform-wide and does not vary by agent. The `agent` parameter is 1881 accepted for future per-agent filtering but is currently unused. The caller must 1882 have app scope to call this endpoint. 1883 1884 Args: 1885 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 1886 1887 Returns: 1888 The list of publicly available installation kinds. 1889 """ 1890 return self._http.request( 1891 f"/api/v1/agents/{agent}/agent_installations/kinds", 1892 response_type=InstallationKindListResponse, 1893 )
AgentAgentInstallationResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
1820 def list(self, agent: str) -> InstallationListResponse: 1821 """ 1822 List installations for an agent 1823 Returns all installations belonging to the specified agent, across all kinds and 1824 states. Use this endpoint to inspect which external services and enablement channels 1825 an agent is connected to. 1826 Results are scoped to the authenticated app and are returned in an unordered array. 1827 To list installations across all agents in an app, use the top-level List 1828 Installations endpoint instead. The caller must have app scope for the app that 1829 owns the agent. 1830 1831 Args: 1832 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 1833 1834 Returns: 1835 The list of installations for the specified agent. 1836 """ 1837 return self._http.request( 1838 f"/api/v1/agents/{agent}/agent_installations", 1839 response_type=InstallationListResponse, 1840 )
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:
1842 def create(self, agent: str, input: AgentAgentInstallationCreateInput) -> Installation: 1843 """ 1844 Create an installation 1845 Creates a new installation for an agent, connecting it to an external service or 1846 enablement channel via the specified `kind`. The installation begins in a pending 1847 state unless an integration is supplied at creation time, in which case it is 1848 activated immediately. 1849 Supply `shared_integration` to bind an existing org- or app-level integration, or 1850 supply `integration` to create a new integration inline and activate the installation 1851 in a single request. Supplying both fields returns 422. 1852 Use `lookup_key` to assign a stable identifier you can reference later in knowledge 1853 search `source_refs`. The key must be unique within the app, org, and sandbox 1854 combination. The caller must have app scope for the app that owns the agent. 1855 1856 Args: 1857 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 1858 input: Request body. 1859 input.config: Kind-specific configuration object. Shape varies by `kind`; omit if the kind requires no initial configuration. 1860 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`. 1861 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. 1862 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. 1863 input.shared_integration: ID of an existing shared org- or app-level integration to bind to this installation. Mutually exclusive with `integration`. 1864 1865 Returns: 1866 The newly created installation. 1867 """ 1868 return self._http.request( 1869 f"/api/v1/agents/{agent}/agent_installations", 1870 method="POST", 1871 body=input, 1872 response_type=Installation, 1873 )
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.
1875 def kinds(self, agent: str) -> InstallationKindListResponse: 1876 """ 1877 List available installation kinds 1878 Returns the publicly available installation kinds supported by the API. Use the 1879 returned `kind` values when calling the Create Installation endpoint. 1880 The list is platform-wide and does not vary by agent. The `agent` parameter is 1881 accepted for future per-agent filtering but is currently unused. The caller must 1882 have app scope to call this endpoint. 1883 1884 Args: 1885 agent: Agent ID (`agt_...`) whose installations you want to retrieve. 1886 1887 Returns: 1888 The list of publicly available installation kinds. 1889 """ 1890 return self._http.request( 1891 f"/api/v1/agents/{agent}/agent_installations/kinds", 1892 response_type=InstallationKindListResponse, 1893 )
List available installation kinds
Returns the publicly available installation kinds supported by the API. 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 publicly available installation kinds.
class
AgentAgentToolResource:
1896class AgentAgentToolResource: 1897 def __init__(self, http: SyncHttpClient): 1898 self._http = http 1899 1900 def list(self, agent: str, *, kind: str | None = None) -> AgentToolListResponse: 1901 """ 1902 List agent tools 1903 Returns all tools for the authenticated app, optionally filtered by agent 1904 or tool kind. Both explicitly created tools and tools derived from connected 1905 integrations (installation-sourced tools) are included in the response. 1906 Installation-sourced tools appear with `source: "installation"` and 1907 `status: "active"`. They are synthesized at request time from connected 1908 integrations and do not have a persistent tool ID of the `atl_...` form; 1909 their `id` is a composite of the installation ID and server tool type. 1910 Use the `agent` filter to retrieve tools for a specific agent. Supplying an 1911 `agent` ID that does not belong to the authenticated app returns 404. 1912 Requires app scope. 1913 1914 Args: 1915 agent: Filter results to tools belonging to these agents (`agi_...`). Omit to return tools across all agents in the app. Multiple values are OR'd. 1916 kind: Filter by tool kind. One of `"builtin"` or `"custom"`. Omit to return tools of all kinds. 1917 1918 Returns: 1919 List of tools matching the supplied filters. 1920 """ 1921 query: dict[str, object] = {} 1922 if kind is not None: 1923 query["kind"] = kind 1924 return self._http.request( 1925 f"/api/v1/agents/{agent}/agent_tools", 1926 query=query, 1927 response_type=AgentToolListResponse, 1928 ) 1929 1930 def create(self, agent: str, input: AgentAgentToolCreateInput) -> AgentTool: 1931 """ 1932 Create an agent tool 1933 Creates a new tool and attaches it to the specified agent. Tools can be 1934 either `"builtin"` (a platform-provided capability identified by 1935 `builtin_tool_key`) or `"custom"` (a caller-defined tool with its own name, 1936 description, parameter schema, and handler). 1937 New tools are created in `"draft"` status by default unless `status: 1938 "active"` is explicitly supplied. Draft tools are not exposed to the LLM 1939 during agent runs; call the activate endpoint to promote them. 1940 For built-in tools that support multiple instances per agent (those whose 1941 catalog entry has a `multi_instance_mode`), supply `name_prefix` to 1942 namespace the LLM-facing tool names. Requires app scope. 1943 1944 Args: 1945 agent: Filter results to tools belonging to these agents (`agi_...`). Omit to return tools across all agents in the app. Multiple values are OR'd. 1946 input: Request body. 1947 input.async: When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools. 1948 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. 1949 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. 1950 input.config: Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools. 1951 input.description: Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to `"custom"` tools. 1952 input.handler_type: Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools. 1953 input.kind: Tool kind. One of `"builtin"` or `"custom"`. 1954 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. 1955 input.metadata: Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform. 1956 input.name: Display name for the tool. Required when `kind` is `"custom"`. 1957 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. 1958 input.parameters: JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to `"custom"` tools. 1959 input.status: Initial status of the tool. One of `"draft"` or `"active"`. Defaults to `"draft"` when omitted. 1960 1961 Returns: 1962 The newly created tool. 1963 """ 1964 return self._http.request( 1965 f"/api/v1/agents/{agent}/agent_tools", 1966 method="POST", 1967 body=input, 1968 response_type=AgentTool, 1969 )
AgentAgentToolResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
def
list( self, agent: str, *, kind: str | None = None) -> archastro.platform.types.common.AgentToolListResponse:
1900 def list(self, agent: str, *, kind: str | None = None) -> AgentToolListResponse: 1901 """ 1902 List agent tools 1903 Returns all tools for the authenticated app, optionally filtered by agent 1904 or tool kind. Both explicitly created tools and tools derived from connected 1905 integrations (installation-sourced tools) are included in the response. 1906 Installation-sourced tools appear with `source: "installation"` and 1907 `status: "active"`. They are synthesized at request time from connected 1908 integrations and do not have a persistent tool ID of the `atl_...` form; 1909 their `id` is a composite of the installation ID and server tool type. 1910 Use the `agent` filter to retrieve tools for a specific agent. Supplying an 1911 `agent` ID that does not belong to the authenticated app returns 404. 1912 Requires app scope. 1913 1914 Args: 1915 agent: Filter results to tools belonging to these agents (`agi_...`). Omit to return tools across all agents in the app. Multiple values are OR'd. 1916 kind: Filter by tool kind. One of `"builtin"` or `"custom"`. Omit to return tools of all kinds. 1917 1918 Returns: 1919 List of tools matching the supplied filters. 1920 """ 1921 query: dict[str, object] = {} 1922 if kind is not None: 1923 query["kind"] = kind 1924 return self._http.request( 1925 f"/api/v1/agents/{agent}/agent_tools", 1926 query=query, 1927 response_type=AgentToolListResponse, 1928 )
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 these agents (
agi_...). Omit to return tools across all agents in the app. Multiple values are OR'd. - 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:
1930 def create(self, agent: str, input: AgentAgentToolCreateInput) -> AgentTool: 1931 """ 1932 Create an agent tool 1933 Creates a new tool and attaches it to the specified agent. Tools can be 1934 either `"builtin"` (a platform-provided capability identified by 1935 `builtin_tool_key`) or `"custom"` (a caller-defined tool with its own name, 1936 description, parameter schema, and handler). 1937 New tools are created in `"draft"` status by default unless `status: 1938 "active"` is explicitly supplied. Draft tools are not exposed to the LLM 1939 during agent runs; call the activate endpoint to promote them. 1940 For built-in tools that support multiple instances per agent (those whose 1941 catalog entry has a `multi_instance_mode`), supply `name_prefix` to 1942 namespace the LLM-facing tool names. Requires app scope. 1943 1944 Args: 1945 agent: Filter results to tools belonging to these agents (`agi_...`). Omit to return tools across all agents in the app. Multiple values are OR'd. 1946 input: Request body. 1947 input.async: When `true`, the tool executes asynchronously and the agent does not block waiting for a result. Applies to `"custom"` tools. 1948 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. 1949 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. 1950 input.config: Config ID (`cfg_...`) referencing the script or workflow graph that implements the tool handler. Applies to `"custom"` tools. 1951 input.description: Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to `"custom"` tools. 1952 input.handler_type: Execution handler for the tool. One of `"script"` or `"workflow_graph"`. Applies to `"custom"` tools. 1953 input.kind: Tool kind. One of `"builtin"` or `"custom"`. 1954 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. 1955 input.metadata: Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform. 1956 input.name: Display name for the tool. Required when `kind` is `"custom"`. 1957 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. 1958 input.parameters: JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to `"custom"` tools. 1959 input.status: Initial status of the tool. One of `"draft"` or `"active"`. Defaults to `"draft"` when omitted. 1960 1961 Returns: 1962 The newly created tool. 1963 """ 1964 return self._http.request( 1965 f"/api/v1/agents/{agent}/agent_tools", 1966 method="POST", 1967 body=input, 1968 response_type=AgentTool, 1969 )
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 these agents (
agi_...). Omit to return tools across all agents in the app. Multiple values are OR'd. - 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
AgentWorkingMemoryResource:
1972class AgentWorkingMemoryResource: 1973 def __init__(self, http: SyncHttpClient): 1974 self._http = http 1975 1976 def list( 1977 self, 1978 agent: str, 1979 *, 1980 page: int | None = None, 1981 page_size: int | None = None, 1982 search: str | None = None, 1983 ) -> WorkingMemoryEntryListResponse: 1984 """ 1985 List working memory entries for an agent 1986 Returns a paginated list of working memory entries belonging to the specified 1987 agent. Entries are key-value pairs the agent stores for context between 1988 interactions. Results are ordered by creation time descending (newest first) 1989 and can be filtered with a substring search against the key name. 1990 Requires an app-scoped API key. The authenticated caller must have access to 1991 the app the agent belongs to. Returns 403 if the key is not app-scoped, and 1992 404 if the agent does not exist within the accessible scope. 1993 1994 Args: 1995 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 1996 page: Page number to retrieve, starting at 1. Defaults to 1. 1997 page_size: Number of entries to return per page. Defaults to 25. 1998 search: Substring filter applied to entry keys (case-insensitive). Omit to return all keys. 1999 2000 Returns: 2001 Paginated list of working memory entries for the agent. 2002 """ 2003 query: dict[str, object] = {} 2004 if page is not None: 2005 query["page"] = page 2006 if page_size is not None: 2007 query["page_size"] = page_size 2008 if search is not None: 2009 query["search"] = search 2010 return self._http.request( 2011 f"/api/v1/agents/{agent}/agent_working_memory", 2012 query=query, 2013 response_type=WorkingMemoryEntryListResponse, 2014 ) 2015 2016 def delete(self, agent: str, entry: str) -> None: 2017 """ 2018 Delete a working memory entry 2019 Permanently deletes a working memory entry from the agent. This action is 2020 irreversible. Expired entries can also be deleted they are hidden from 2021 list results but persist until overwritten or deleted. 2022 Requires an app-scoped API key. The authenticated caller must be able to 2023 modify the agent that owns the entry. Returns 403 if the key is not 2024 app-scoped or the caller lacks modify access, and 404 if the agent or entry 2025 does not exist within the accessible scope. 2026 2027 Args: 2028 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 2029 entry: Working memory entry ID (`amm_...`) to delete. 2030 2031 Returns: 2032 Empty body. Returns HTTP 204 on success. 2033 """ 2034 self._http.request(f"/api/v1/agents/{agent}/agent_working_memory/{entry}", method="DELETE") 2035 2036 def update( 2037 self, agent: str, entry: str, input: AgentWorkingMemoryUpdateInput 2038 ) -> WorkingMemoryEntry: 2039 """ 2040 Update a working memory entry 2041 Updates the value and/or expiry of an existing working memory entry. Only 2042 the fields you supply are changed; omitted fields retain their current 2043 values. The entry `key` cannot be changed after creation delete the entry 2044 and let the agent (or a future create call) write a new one instead. 2045 Pass `expires_at` as `null` to remove the expiry so the entry no longer 2046 expires. Expired entries can still be updated; they stay hidden from list 2047 results until their expiry is in the future again. 2048 Requires an app-scoped API key. The authenticated caller must be able to 2049 modify the agent that owns the entry. Returns 403 if the key is not 2050 app-scoped or the caller lacks modify access, and 404 if the agent or entry 2051 does not exist within the accessible scope. 2052 2053 Args: 2054 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 2055 entry: Working memory entry ID (`amm_...`) to update. 2056 input: Request body. 2057 input.expires_at: New expiry for the entry (ISO 8601). Pass `null` to remove the expiry so the entry never expires. Omit to keep the current expiry. 2058 input.value: Replacement string value to store under the entry's key. Maximum 65,536 characters. 2059 2060 Returns: 2061 The updated working memory entry. 2062 """ 2063 return self._http.request( 2064 f"/api/v1/agents/{agent}/agent_working_memory/{entry}", 2065 method="PATCH", 2066 body=input, 2067 response_type=WorkingMemoryEntry, 2068 )
AgentWorkingMemoryResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
def
list( self, agent: str, *, page: int | None = None, page_size: int | None = None, search: str | None = None) -> archastro.platform.types.common.WorkingMemoryEntryListResponse:
1976 def list( 1977 self, 1978 agent: str, 1979 *, 1980 page: int | None = None, 1981 page_size: int | None = None, 1982 search: str | None = None, 1983 ) -> WorkingMemoryEntryListResponse: 1984 """ 1985 List working memory entries for an agent 1986 Returns a paginated list of working memory entries belonging to the specified 1987 agent. Entries are key-value pairs the agent stores for context between 1988 interactions. Results are ordered by creation time descending (newest first) 1989 and can be filtered with a substring search against the key name. 1990 Requires an app-scoped API key. The authenticated caller must have access to 1991 the app the agent belongs to. Returns 403 if the key is not app-scoped, and 1992 404 if the agent does not exist within the accessible scope. 1993 1994 Args: 1995 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 1996 page: Page number to retrieve, starting at 1. Defaults to 1. 1997 page_size: Number of entries to return per page. Defaults to 25. 1998 search: Substring filter applied to entry keys (case-insensitive). Omit to return all keys. 1999 2000 Returns: 2001 Paginated list of working memory entries for the agent. 2002 """ 2003 query: dict[str, object] = {} 2004 if page is not None: 2005 query["page"] = page 2006 if page_size is not None: 2007 query["page_size"] = page_size 2008 if search is not None: 2009 query["search"] = search 2010 return self._http.request( 2011 f"/api/v1/agents/{agent}/agent_working_memory", 2012 query=query, 2013 response_type=WorkingMemoryEntryListResponse, 2014 )
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
delete(self, agent: str, entry: str) -> None:
2016 def delete(self, agent: str, entry: str) -> None: 2017 """ 2018 Delete a working memory entry 2019 Permanently deletes a working memory entry from the agent. This action is 2020 irreversible. Expired entries can also be deleted they are hidden from 2021 list results but persist until overwritten or deleted. 2022 Requires an app-scoped API key. The authenticated caller must be able to 2023 modify the agent that owns the entry. Returns 403 if the key is not 2024 app-scoped or the caller lacks modify access, and 404 if the agent or entry 2025 does not exist within the accessible scope. 2026 2027 Args: 2028 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 2029 entry: Working memory entry ID (`amm_...`) to delete. 2030 2031 Returns: 2032 Empty body. Returns HTTP 204 on success. 2033 """ 2034 self._http.request(f"/api/v1/agents/{agent}/agent_working_memory/{entry}", method="DELETE")
Delete a working memory entry Permanently deletes a working memory entry from the agent. This action is irreversible. Expired entries can also be deleted they are hidden from list results but persist until overwritten or deleted. Requires an app-scoped API key. The authenticated caller must be able to modify the agent that owns the entry. Returns 403 if the key is not app-scoped or the caller lacks modify access, and 404 if the agent or entry does not exist within the accessible scope.
Arguments:
- agent: Agent ID (
agt_...) whose working memory entries to retrieve. - entry: Working memory entry ID (
amm_...) to delete.
Returns:
Empty body. Returns HTTP 204 on success.
def
update( self, agent: str, entry: str, input: AgentWorkingMemoryUpdateInput) -> archastro.platform.types.common.WorkingMemoryEntry:
2036 def update( 2037 self, agent: str, entry: str, input: AgentWorkingMemoryUpdateInput 2038 ) -> WorkingMemoryEntry: 2039 """ 2040 Update a working memory entry 2041 Updates the value and/or expiry of an existing working memory entry. Only 2042 the fields you supply are changed; omitted fields retain their current 2043 values. The entry `key` cannot be changed after creation delete the entry 2044 and let the agent (or a future create call) write a new one instead. 2045 Pass `expires_at` as `null` to remove the expiry so the entry no longer 2046 expires. Expired entries can still be updated; they stay hidden from list 2047 results until their expiry is in the future again. 2048 Requires an app-scoped API key. The authenticated caller must be able to 2049 modify the agent that owns the entry. Returns 403 if the key is not 2050 app-scoped or the caller lacks modify access, and 404 if the agent or entry 2051 does not exist within the accessible scope. 2052 2053 Args: 2054 agent: Agent ID (`agt_...`) whose working memory entries to retrieve. 2055 entry: Working memory entry ID (`amm_...`) to update. 2056 input: Request body. 2057 input.expires_at: New expiry for the entry (ISO 8601). Pass `null` to remove the expiry so the entry never expires. Omit to keep the current expiry. 2058 input.value: Replacement string value to store under the entry's key. Maximum 65,536 characters. 2059 2060 Returns: 2061 The updated working memory entry. 2062 """ 2063 return self._http.request( 2064 f"/api/v1/agents/{agent}/agent_working_memory/{entry}", 2065 method="PATCH", 2066 body=input, 2067 response_type=WorkingMemoryEntry, 2068 )
Update a working memory entry
Updates the value and/or expiry of an existing working memory entry. Only
the fields you supply are changed; omitted fields retain their current
values. The entry key cannot be changed after creation delete the entry
and let the agent (or a future create call) write a new one instead.
Pass expires_at as null to remove the expiry so the entry no longer
expires. Expired entries can still be updated; they stay hidden from list
results until their expiry is in the future again.
Requires an app-scoped API key. The authenticated caller must be able to
modify the agent that owns the entry. Returns 403 if the key is not
app-scoped or the caller lacks modify access, and 404 if the agent or entry
does not exist within the accessible scope.
Arguments:
- agent: Agent ID (
agt_...) whose working memory entries to retrieve. - entry: Working memory entry ID (
amm_...) to update. - input: Request body.
- input.expires_at: New expiry for the entry (ISO 8601). Pass
nullto remove the expiry so the entry never expires. Omit to keep the current expiry. - input.value: Replacement string value to store under the entry's key. Maximum 65,536 characters.
Returns:
The updated working memory entry.
class
ScheduleResource:
2071class ScheduleResource: 2072 def __init__(self, http: SyncHttpClient): 2073 self._http = http 2074 2075 def list(self, agent: str, *, status: str | None = None) -> ScheduleListResponse: 2076 """ 2077 List schedules for an agent 2078 Returns all schedules belonging to the specified agent in any status. Use the 2079 `status` parameter to narrow results to a single lifecycle state. 2080 Requires an app-scoped API key. The agent must belong to the app identified 2081 by the key. 2082 2083 Args: 2084 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 2085 status: Filter results by schedule status. One of `"active"`, `"paused"`, `"completed"`, `"cancelled"`, or `"expired"`. Omit to return schedules in all statuses. 2086 2087 Returns: 2088 Successful response 2089 """ 2090 query: dict[str, object] = {} 2091 if status is not None: 2092 query["status"] = status 2093 return self._http.request( 2094 f"/api/v1/agents/{agent}/schedules", 2095 query=query, 2096 response_type=ScheduleListResponse, 2097 ) 2098 2099 def get(self, agent: str, schedule: str) -> AgentSchedule: 2100 """ 2101 Retrieve a schedule 2102 Returns a single schedule belonging to the specified agent. Use this endpoint 2103 to fetch the current state, next run time, and configuration of an individual 2104 schedule. 2105 Requires an app-scoped API key. Both the agent and the schedule must belong 2106 to the app identified by the key. Returns 404 if the schedule does not exist 2107 or belongs to a different agent. 2108 2109 Args: 2110 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 2111 schedule: Schedule ID (`asc_...`). The schedule to retrieve. 2112 2113 Returns: 2114 The requested agent schedule. 2115 """ 2116 return self._http.request( 2117 f"/api/v1/agents/{agent}/schedules/{schedule}", 2118 response_type=AgentSchedule, 2119 )
ScheduleResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
2075 def list(self, agent: str, *, status: str | None = None) -> ScheduleListResponse: 2076 """ 2077 List schedules for an agent 2078 Returns all schedules belonging to the specified agent in any status. Use the 2079 `status` parameter to narrow results to a single lifecycle state. 2080 Requires an app-scoped API key. The agent must belong to the app identified 2081 by the key. 2082 2083 Args: 2084 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 2085 status: Filter results by schedule status. One of `"active"`, `"paused"`, `"completed"`, `"cancelled"`, or `"expired"`. Omit to return schedules in all statuses. 2086 2087 Returns: 2088 Successful response 2089 """ 2090 query: dict[str, object] = {} 2091 if status is not None: 2092 query["status"] = status 2093 return self._http.request( 2094 f"/api/v1/agents/{agent}/schedules", 2095 query=query, 2096 response_type=ScheduleListResponse, 2097 )
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
2099 def get(self, agent: str, schedule: str) -> AgentSchedule: 2100 """ 2101 Retrieve a schedule 2102 Returns a single schedule belonging to the specified agent. Use this endpoint 2103 to fetch the current state, next run time, and configuration of an individual 2104 schedule. 2105 Requires an app-scoped API key. Both the agent and the schedule must belong 2106 to the app identified by the key. Returns 404 if the schedule does not exist 2107 or belongs to a different agent. 2108 2109 Args: 2110 agent: Agent ID (`agi_...`). The agent whose schedules you want to retrieve. 2111 schedule: Schedule ID (`asc_...`). The schedule to retrieve. 2112 2113 Returns: 2114 The requested agent schedule. 2115 """ 2116 return self._http.request( 2117 f"/api/v1/agents/{agent}/schedules/{schedule}", 2118 response_type=AgentSchedule, 2119 )
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
AgentWorkItemResource:
2122class AgentWorkItemResource: 2123 def __init__(self, http: SyncHttpClient): 2124 self._http = http 2125 2126 def list( 2127 self, 2128 agent: str, 2129 *, 2130 execution: str | None = None, 2131 limit: int | None = None, 2132 after_cursor: str | None = None, 2133 ) -> WorkflowWorkItemList: 2134 """ 2135 List active workflow work available to the viewer 2136 Lists queued, claimed, and running external work yielded by durable workflows. 2137 The top-level collection includes work for every agent the viewer can execute; 2138 the agent-nested collection limits results to that agent. This discovery 2139 response never includes lease tokens. Use the agent claim endpoint to acquire 2140 new work or resume a saved lease. 2141 2142 Args: 2143 agent: Agent ID or lookup key injected by the nested route. 2144 execution: Optional durable execution ID filter. 2145 limit: Maximum work items per page. Defaults to 50; maximum is 100. 2146 after_cursor: Opaque cursor for the next page of older queued work. 2147 2148 Returns: 2149 Successful response 2150 """ 2151 query: dict[str, object] = {} 2152 if execution is not None: 2153 query["execution"] = execution 2154 if limit is not None: 2155 query["limit"] = limit 2156 if after_cursor is not None: 2157 query["after_cursor"] = after_cursor 2158 return self._http.request( 2159 f"/api/v1/agents/{agent}/work_items", 2160 query=query, 2161 response_type=WorkflowWorkItemList, 2162 ) 2163 2164 def claim(self, agent: str, input: AgentWorkItemClaimInput) -> WorkflowWorkItemClaim: 2165 """ 2166 Claim or resume workflow work for an agent 2167 Atomically claims the oldest queued or lease-expired item. To resume after a 2168 harness restart, pass both the saved `work_item` and the same `lease_owner`; 2169 the server refreshes that active lease without incrementing its attempt. 2170 Returns `data: null` when no eligible item exists, including when another 2171 lease owns the explicitly requested item. 2172 2173 Args: 2174 agent: Agent ID or lookup key injected by the nested route. 2175 input: Request body. 2176 input.execution: Optional durable execution ID filter. 2177 input.lease_owner: Caller-generated random UUID lease token. 2178 input.lease_seconds: Lease duration from 15 through 3600 seconds. Defaults to 300. 2179 input.work_item: Saved work item ID to resume or reclaim. 2180 2181 Returns: 2182 Successful response 2183 """ 2184 return self._http.request( 2185 f"/api/v1/agents/{agent}/work_items/claim", 2186 method="POST", 2187 body=input, 2188 response_type=WorkflowWorkItemClaim, 2189 )
AgentWorkItemResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
def
list( self, agent: str, *, execution: str | None = None, limit: int | None = None, after_cursor: str | None = None) -> archastro.platform.types.workflows.WorkflowWorkItemList:
2126 def list( 2127 self, 2128 agent: str, 2129 *, 2130 execution: str | None = None, 2131 limit: int | None = None, 2132 after_cursor: str | None = None, 2133 ) -> WorkflowWorkItemList: 2134 """ 2135 List active workflow work available to the viewer 2136 Lists queued, claimed, and running external work yielded by durable workflows. 2137 The top-level collection includes work for every agent the viewer can execute; 2138 the agent-nested collection limits results to that agent. This discovery 2139 response never includes lease tokens. Use the agent claim endpoint to acquire 2140 new work or resume a saved lease. 2141 2142 Args: 2143 agent: Agent ID or lookup key injected by the nested route. 2144 execution: Optional durable execution ID filter. 2145 limit: Maximum work items per page. Defaults to 50; maximum is 100. 2146 after_cursor: Opaque cursor for the next page of older queued work. 2147 2148 Returns: 2149 Successful response 2150 """ 2151 query: dict[str, object] = {} 2152 if execution is not None: 2153 query["execution"] = execution 2154 if limit is not None: 2155 query["limit"] = limit 2156 if after_cursor is not None: 2157 query["after_cursor"] = after_cursor 2158 return self._http.request( 2159 f"/api/v1/agents/{agent}/work_items", 2160 query=query, 2161 response_type=WorkflowWorkItemList, 2162 )
List active workflow work available to the viewer Lists queued, claimed, and running external work yielded by durable workflows. The top-level collection includes work for every agent the viewer can execute; the agent-nested collection limits results to that agent. This discovery response never includes lease tokens. Use the agent claim endpoint to acquire new work or resume a saved lease.
Arguments:
- agent: Agent ID or lookup key injected by the nested route.
- execution: Optional durable execution ID filter.
- limit: Maximum work items per page. Defaults to 50; maximum is 100.
- after_cursor: Opaque cursor for the next page of older queued work.
Returns:
Successful response
def
claim( self, agent: str, input: AgentWorkItemClaimInput) -> archastro.platform.types.workflows.WorkflowWorkItemClaim:
2164 def claim(self, agent: str, input: AgentWorkItemClaimInput) -> WorkflowWorkItemClaim: 2165 """ 2166 Claim or resume workflow work for an agent 2167 Atomically claims the oldest queued or lease-expired item. To resume after a 2168 harness restart, pass both the saved `work_item` and the same `lease_owner`; 2169 the server refreshes that active lease without incrementing its attempt. 2170 Returns `data: null` when no eligible item exists, including when another 2171 lease owns the explicitly requested item. 2172 2173 Args: 2174 agent: Agent ID or lookup key injected by the nested route. 2175 input: Request body. 2176 input.execution: Optional durable execution ID filter. 2177 input.lease_owner: Caller-generated random UUID lease token. 2178 input.lease_seconds: Lease duration from 15 through 3600 seconds. Defaults to 300. 2179 input.work_item: Saved work item ID to resume or reclaim. 2180 2181 Returns: 2182 Successful response 2183 """ 2184 return self._http.request( 2185 f"/api/v1/agents/{agent}/work_items/claim", 2186 method="POST", 2187 body=input, 2188 response_type=WorkflowWorkItemClaim, 2189 )
Claim or resume workflow work for an agent
Atomically claims the oldest queued or lease-expired item. To resume after a
harness restart, pass both the saved work_item and the same lease_owner;
the server refreshes that active lease without incrementing its attempt.
Returns data: null when no eligible item exists, including when another
lease owns the explicitly requested item.
Arguments:
- agent: Agent ID or lookup key injected by the nested route.
- input: Request body.
- input.execution: Optional durable execution ID filter.
- input.lease_owner: Caller-generated random UUID lease token.
- input.lease_seconds: Lease duration from 15 through 3600 seconds. Defaults to 300.
- input.work_item: Saved work item ID to resume or reclaim.
Returns:
Successful response
class
AgentResource:
2192class AgentResource: 2193 def __init__(self, http: SyncHttpClient): 2194 self._http = http 2195 self.agent_computers = AgentAgentComputerResource(http) 2196 self.agent_env_vars = AgentAgentEnvVarResource(http) 2197 self.agent_installations = AgentAgentInstallationResource(http) 2198 self.agent_tools = AgentAgentToolResource(http) 2199 self.agent_working_memory = AgentWorkingMemoryResource(http) 2200 self.schedules = ScheduleResource(http) 2201 self.work_items = AgentWorkItemResource(http) 2202 2203 def list( 2204 self, 2205 *, 2206 page: int | None = None, 2207 page_size: int | None = None, 2208 search: str | None = None, 2209 user: str | None = None, 2210 org_id: str | None = None, 2211 template_config: str | None = None, 2212 solution_config: builtins.list[str] | None = None, 2213 ) -> AgentListResponse: 2214 """ 2215 List agents 2216 Returns a paginated list of agents visible to the authenticated caller. Results are 2217 ordered by creation time descending. 2218 Use `search` to filter by name, org, team, or owner fields. Use `user` or `org_id` 2219 to scope the list to a specific owner. Use `template_config` to find agents whose 2220 last applied template matches a given config ID. Use `solution_config` to find 2221 agents whose last applied template was imported as part of any of the given 2222 Solution config IDs. 2223 Pagination is page-based: pass `page` and `page_size` to navigate through large 2224 result sets. When called under a developer app scope, only agents belonging to that 2225 app are returned. 2226 2227 Args: 2228 page: Page number to retrieve, 1-indexed. Defaults to `1`. 2229 page_size: Number of agents to return per page. Defaults to `25`. 2230 search: Free-text search string matched against the agent name, org, team, and owner fields. 2231 user: User ID (`usr_...`) to filter by. Returns only agents owned by this user. 2232 org_id: Organization ID (`org_...`) to filter by. Returns only agents owned by this org. 2233 template_config: Config ID (`cfg_...`) or `lookup_key` of an AgentTemplate. Returns only agents whose last applied template matches. 2234 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. 2235 2236 Returns: 2237 Paginated list of agents matching the supplied filters. 2238 """ 2239 query: dict[str, object] = {} 2240 if page is not None: 2241 query["page"] = page 2242 if page_size is not None: 2243 query["page_size"] = page_size 2244 if search is not None: 2245 query["search"] = search 2246 if user is not None: 2247 query["user"] = user 2248 if org_id is not None: 2249 query["org_id"] = org_id 2250 if template_config is not None: 2251 query["template_config"] = template_config 2252 if solution_config is not None: 2253 query["solution_config"] = solution_config 2254 return self._http.request("/api/v1/agents", query=query, response_type=AgentListResponse) 2255 2256 def create(self, input: AgentCreateInput) -> AgentCreateResponse: 2257 """ 2258 Create an agent 2259 Creates a new agent. Supports two mutually exclusive provisioning modes. 2260 **Template mode** pass `template` with the ID or `lookup_key` of an existing 2261 AgentTemplate config. The agent's tools, routines, skills, and installations are 2262 provisioned from that template's `config_ref` entries. 2263 **Bundle mode** pass `template_bundle` with a self-contained install payload 2264 (AgentTemplate body plus every skill, script, and config it references). The entire 2265 bundle commits in a single transaction; any failure rolls back the whole install and 2266 the response includes `installed_configs[]` one entry per persisted config. 2267 Pass exactly one of `template` or `template_bundle`. If neither is supplied, `name` 2268 is required and a blank agent is created. Requires authentication; when called under 2269 a developer app scope (`/developer/apps/:app/...`), the caller must hold the app scope 2270 for the target app. 2271 2272 Args: 2273 input: Request body. 2274 input.acl: Access control list controlling which users, teams, or orgs can read or manage this agent. 2275 input.description: Human-readable description of what the agent does. 2276 input.email: Email address assigned to the agent. Used as the agent's contact identity. 2277 input.identity: System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn. 2278 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. 2279 input.metadata: Arbitrary key-value map stored on the agent. Not interpreted by the platform. 2280 input.model: Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model. 2281 input.name: Display name for the agent. Required when neither `template` nor `template_bundle` is provided. 2282 input.org: Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`. 2283 input.originator: Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug. 2284 input.phone_number: Phone number assigned to the agent in E.164 format, e.g. `+15550001234`. 2285 input.profile_picture: Profile picture to attach to the agent. All three subfields are required when this object is present. 2286 input.team: Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`. 2287 input.template: ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`. 2288 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`. 2289 input.user: User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`. 2290 2291 Returns: 2292 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. 2293 """ 2294 return self._http.request( 2295 "/api/v1/agents", 2296 method="POST", 2297 body=input, 2298 response_type=AgentCreateResponse, 2299 ) 2300 2301 def delete(self, agent: str) -> None: 2302 """ 2303 Delete an agent 2304 Permanently deletes an agent and all of its associated resources. This action cannot 2305 be undone. 2306 The authenticated caller must own the agent or hold sufficient permissions within its 2307 owning org or team. When called under a developer app scope, the caller must hold the 2308 app scope for the target app. 2309 2310 Args: 2311 agent: ID (`agi_...`) or `lookup_key` of the agent to delete. 2312 2313 Returns: 2314 Empty body. Returns HTTP 204 on success. 2315 """ 2316 self._http.request(f"/api/v1/agents/{agent}", method="DELETE") 2317 2318 def get(self, agent: str) -> Agent: 2319 """ 2320 Retrieve an agent 2321 Returns the agent identified by ID or `lookup_key`. The authenticated caller must 2322 own the agent or hold sufficient permissions within its owning org or team. 2323 When called under a developer app scope, the agent must belong to that app. Use the 2324 list endpoint to retrieve many agents at once. 2325 2326 Args: 2327 agent: ID (`agi_...`) or `lookup_key` of the agent to retrieve. 2328 2329 Returns: 2330 The requested agent. 2331 """ 2332 return self._http.request(f"/api/v1/agents/{agent}", response_type=Agent) 2333 2334 def update(self, agent: str, input: AgentUpdateInput) -> Agent: 2335 """ 2336 Update an agent 2337 Updates one or more fields on an existing agent. Only the fields you supply are 2338 changed; omitted fields retain their current values. 2339 To clear the agent's default model, pass `model` as an empty string. The 2340 authenticated caller must own the agent or hold write permissions within its owning 2341 org or team. When called under a developer app scope, the caller must hold the app 2342 scope for the target app. 2343 2344 Args: 2345 agent: ID (`agi_...`) or `lookup_key` of the agent to update. 2346 input: Request body. 2347 input.acl: Replacement access control list. Fully replaces the existing ACL. 2348 input.description: New description of what the agent does. Pass an empty string to clear it. 2349 input.email: New email address for the agent. 2350 input.identity: Replacement identity system-prompt string describing who the agent is. 2351 input.lookup_key: New `lookup_key` slug. Must be unique within the owning app or org. 2352 input.metadata: Replacement key-value metadata map. The entire map is replaced, not merged. 2353 input.model: New default AI model identifier, e.g. `claude-sonnet-4-5`. Pass an empty string to clear the agent's default model. 2354 input.name: New display name for the agent. 2355 input.org: Organization ID (`org_...`) to transfer ownership to. 2356 input.originator: Replacement originator label identifying the source or author of the agent. 2357 input.phone_number: New phone number for the agent in E.164 format, e.g. `+15550001234`. 2358 input.profile_picture: Replacement profile picture. All three subfields are required when this object is present. 2359 input.team: Team ID (`team_...`) to transfer ownership to. 2360 input.user: User ID (`usr_...`) to transfer ownership to. 2361 2362 Returns: 2363 The updated agent with all current field values. 2364 """ 2365 return self._http.request( 2366 f"/api/v1/agents/{agent}", 2367 method="PATCH", 2368 body=input, 2369 response_type=Agent, 2370 ) 2371 2372 def agent_health_actions( 2373 self, 2374 agent: str, 2375 *, 2376 source: builtins.list[str] | None = None, 2377 status: builtins.list[str] | None = None, 2378 kind: builtins.list[str] | None = None, 2379 ) -> HealthActionListResponse: 2380 """ 2381 List health actions for an agent 2382 Returns all health actions associated with a given agent. Health actions 2383 represent required or recommended steps such as setting environment 2384 variables, completing OAuth installations, or running custom verifiers 2385 that an agent needs to reach a healthy state. 2386 Results are not paginated; the full list for the agent is returned. Use 2387 the `source`, `status`, and `kind` filters to narrow results to the 2388 subset your UI or workflow needs. Multiple values for the same filter 2389 are treated as OR (e.g. passing two statuses returns actions matching 2390 either). The caller must be authenticated and scoped to the app that 2391 owns the agent. 2392 2393 Args: 2394 agent: Agent ID (`agt_...`) or lookup key of the agent whose health actions you want to list. 2395 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. 2396 status: Filter results to actions in one or more statuses. Accepted values: `"pending"`, `"completed"`, `"skipped"`, and `"degraded"`. Omit to return actions in all statuses. 2397 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. 2398 2399 Returns: 2400 Object containing a `data` array of health action objects for the specified agent. 2401 """ 2402 query: dict[str, object] = {} 2403 if source is not None: 2404 query["source"] = source 2405 if status is not None: 2406 query["status"] = status 2407 if kind is not None: 2408 query["kind"] = kind 2409 return self._http.request( 2410 f"/api/v1/agents/{agent}/agent_health_actions", 2411 query=query, 2412 response_type=HealthActionListResponse, 2413 ) 2414 2415 def agent_routines(self, agent: str, input: AgentAgentRoutinesInput) -> AgentRoutine: 2416 """ 2417 Create a routine 2418 Creates a new routine and attaches it to the specified agent. Routines define 2419 how an agent responds to events or a cron schedule; the `handler_type` controls 2420 which execution model is used. 2421 The routine is created in `"draft"` status by default. To start processing 2422 events immediately, either pass `status: "active"` or call the activate 2423 endpoint after creation. Scheduled routines must run no more frequently than 2424 once per hour. Requires app scope. 2425 2426 Args: 2427 agent: Agent ID (`agt_...`) that this routine will be attached to. 2428 input: Request body. 2429 input.acl: Access control list governing who can read or manage this routine. 2430 input.config: Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`. 2431 input.description: Optional human-readable description of what this routine does. 2432 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"`). 2433 input.event_type: Event type that triggers this routine. Deprecated use `event_config` instead. 2434 input.handler_type: Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`. 2435 input.lookup_key: Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app. 2436 input.message_policy: Visibility and explicit recipient selection for messages emitted by the routine. 2437 input.metadata: Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform. 2438 input.name: Human-readable display name for the routine. 2439 input.preset_config: Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`. 2440 input.preset_name: Name of the registered preset to use. Required when `handler_type` is `"preset"`. 2441 input.schedule: Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour. 2442 input.script: Inline script source. Required when `handler_type` is `"script"`. 2443 input.status: Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`. 2444 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`. 2445 input.trigger_context: Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`. 2446 input.user: Optional co-owner user ID (`usr_...`). When set, that user shares authority over this routine (view/modify/delete) without needing to administer the parent agent. Must be supplied explicitly the caller's identity is never auto-stamped as co-owner. 2447 2448 Returns: 2449 The newly created routine. 2450 """ 2451 return self._http.request( 2452 f"/api/v1/agents/{agent}/agent_routines", 2453 method="POST", 2454 body=input, 2455 response_type=AgentRoutine, 2456 ) 2457 2458 def export(self, agent: str, *, remove_identity: bool | None = None) -> AgentExport: 2459 """ 2460 Export an agent as an AgentTemplate 2461 Reconstructs an AgentTemplate config from a deployed agent and all of its 2462 sub-resources (tools, routines, skills, installations). Returns the template 2463 definition together with every dependent config file (scripts, workflows, skills, 2464 schemas) and their raw content, producing a fully self-contained export bundle. 2465 Use this endpoint to snapshot an agent's current configuration for backup, 2466 migration, or to seed a new Solution template. Pass `remove_identity: true` to 2467 strip instance-specific fields (email, phone number) before export. 2468 The authenticated caller must own the agent or hold sufficient permissions within 2469 its owning org or team. When called under a developer app scope, the caller must 2470 hold the app scope for the target app. 2471 2472 Args: 2473 agent: ID (`agi_...`) or `lookup_key` of the agent to export. 2474 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. 2475 2476 Returns: 2477 Export bundle containing the reconstructed AgentTemplate and all dependent config files with their raw content. 2478 """ 2479 query: dict[str, object] = {} 2480 if remove_identity is not None: 2481 query["remove_identity"] = remove_identity 2482 return self._http.request( 2483 f"/api/v1/agents/{agent}/export", 2484 query=query, 2485 response_type=AgentExport, 2486 ) 2487 2488 def health(self, agent: str) -> AgentHealth: 2489 """ 2490 Retrieve an agent's health profile 2491 Returns an aggregate health profile for the specified agent, including an overall 2492 status, a numeric health score, recent activity metrics, and a list of recommended 2493 remediation actions. 2494 The health check is computed on demand at request time. The `checked_at` timestamp 2495 in the response reflects when the evaluation ran. Use this endpoint to surface 2496 diagnostics about tool availability, model configuration, and runtime activity in 2497 dashboards or monitoring workflows. 2498 The authenticated caller must own the agent or hold sufficient permissions within 2499 its owning org or team. When called under a developer app scope, the caller must 2500 hold the app scope for the target app. 2501 2502 Args: 2503 agent: ID (`agi_...`) or `lookup_key` of the agent to evaluate. 2504 2505 Returns: 2506 Aggregate health profile for the agent, including status, score, activity metrics, and recommended actions. 2507 """ 2508 return self._http.request(f"/api/v1/agents/{agent}/health", response_type=AgentHealth) 2509 2510 def search(self, agent: str, input: AgentSearchInput) -> AgentSearchResponse: 2511 """ 2512 Search an agent's knowledge base 2513 Performs a semantic search over an agent's knowledge base and returns a ranked, 2514 `kind`-discriminated list of matching items. 2515 Threads are automatically indexed as conversational memory, including prior agent 2516 answers. A match is not necessarily independent source evidence. Result `type` 2517 identifies the source: `thread/messages` is conversation memory; use `source_types` 2518 with the desired corpus slugs (for example `knowledge/documents`) to exclude it. 2519 `kind` describes storage granularity, not whether the content is conversation memory. 2520 Two item kinds may appear in `data`: 2521 - `"chunk"` chunk-level results from the agent's context store. Present for all agents. 2522 - `"document"` document-level results. Present only when the agent has an active 2523 `archastro/knowledge` installation. 2524 Results from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to 2525 be comparable across kinds, then merged into a single ranked list. On a relevance tie, 2526 chunks appear before documents. The total number of results is capped at `max_results` 2527 across both kinds. 2528 Use `mode` to choose the retrieval strategy: `"hybrid"` (default) combines vector and 2529 full-text search; `"vector"` and `"fulltext"` select each strategy independently. 2530 2531 Args: 2532 agent: ID (`agi_...`) or `lookup_key` of the agent whose knowledge base to search. 2533 input: Request body. 2534 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`. 2535 input.min_similarity: Cosine-similarity floor for the vector leg, 0.0-1.0, applied to both chunk and document results. Candidates below it are discarded before ranking, so a high value trades recall for precision. Pass `0.0` to disable the floor when a missed match costs more than a weak one note that with no floor every query returns results, so an empty response can no longer be read as "no match". Omit to use the default. 2536 input.mode: Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`. 2537 input.query: Natural-language search query used to retrieve relevant knowledge items. 2538 input.recency_days: When set, restricts results to items indexed within the last N days. 2539 input.source_types: Exact source-type slugs filtering both chunks and documents, e.g. `["knowledge/documents"]` for authored documents or `["thread/messages"]` for conversation memory. Omit or pass an empty array to include all source types. 2540 2541 Returns: 2542 Successful response 2543 """ 2544 return self._http.request( 2545 f"/api/v1/agents/{agent}/search", 2546 method="POST", 2547 body=input, 2548 response_type=AgentSearchResponse, 2549 ) 2550 2551 def self_solution(self, agent: str) -> AgentSelfSolutionResponse: 2552 """ 2553 Ensure an agent's private self-solution 2554 Lazily snapshots an authorized agent into its single private, versioned Solution. 2555 2556 Args: 2557 agent: Agent ID or lookup key. 2558 2559 Returns: 2560 Successful response 2561 """ 2562 return self._http.request( 2563 f"/api/v1/agents/{agent}/self_solution", 2564 response_type=AgentSelfSolutionResponse, 2565 ) 2566 2567 def threads(self, agent: str, input: AgentThreadsInput) -> Thread: 2568 """ 2569 Create a thread for an agent 2570 Creates a new thread owned by the specified agent. The thread is scoped to the 2571 agent's identity and is immediately available for messaging. 2572 The authenticated caller must have access to the agent's parent app. If your 2573 API key is scoped to a specific app, pass that app's ID via the `app` parameter. 2574 Attempting to create a thread for an agent you cannot access returns 404. 2575 By default the platform may send an automatic welcome message into the new 2576 thread. Pass `skip_welcome_message: true` to suppress this behavior. 2577 2578 Args: 2579 agent: Agent ID (`agt_...`). The thread will be owned by this agent. 2580 input: Request body. 2581 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to `false`. 2582 input.thread: Attributes for the new thread. See ThreadCreateParams for available fields. 2583 2584 Returns: 2585 The newly created thread. 2586 """ 2587 return self._http.request( 2588 f"/api/v1/agents/{agent}/threads", 2589 method="POST", 2590 body=input, 2591 response_type=Thread, 2592 ) 2593 2594 def upgrade(self, agent: str, input: AgentUpgradeInput) -> AgentUpgradeResponse: 2595 """ 2596 Upgrade an agent from an AgentTemplate 2597 Upgrades an existing agent by reconciling it against an AgentTemplate from a 2598 Solution. Supports two modes: 2599 - `"reapply"` (default) re-applies the agent's currently tracked template, 2600 picking up any changes the template author has made since the last apply. 2601 - `"replace"` moves the agent to a different template. `template` is required 2602 in this mode. 2603 Set `dry_run: true` to compute and return the full upgrade diff (adds, updates, 2604 removes, noops) without writing any changes. The response includes a 2605 `review_fingerprint` you can pass back via `expected_review_fingerprint` on the 2606 live apply to guard against the diff changing between review and execution. 2607 Safe overrides (`name`, `description`, `email`, `phone_number`, `metadata`, 2608 `identity`, `originator`, `model`) let you pin instance-specific values that 2609 should not be overwritten by the template during the upgrade. 2610 The authenticated caller must own the agent or hold write permissions within its 2611 owning org or team. When called under a developer app scope, the caller must hold 2612 the app scope for the target app. 2613 2614 Args: 2615 agent: ID (`agi_...`) or `lookup_key` of the agent to upgrade. 2616 input: Request body. 2617 input.description: Instance-specific description override. Pins this value so the template upgrade does not overwrite it. 2618 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. 2619 input.email: Instance-specific email address override. Pins this value so the template upgrade does not overwrite it. 2620 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. 2621 input.identity: Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it. 2622 input.metadata: Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it. 2623 input.mode: Upgrade mode. `"reapply"` (default) refreshes the agent's tracked template; `"replace"` moves the agent to a different template (requires `template`). 2624 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. 2625 input.name: Instance-specific name override. Pins this value so the template upgrade does not overwrite it. 2626 input.originator: Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it. 2627 input.phone_number: Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it. 2628 input.template: ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode. 2629 2630 Returns: 2631 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. 2632 """ 2633 return self._http.request( 2634 f"/api/v1/agents/{agent}/upgrade", 2635 method="POST", 2636 body=input, 2637 response_type=AgentUpgradeResponse, 2638 )
AgentResource(http: archastro.platform.runtime.http_client.SyncHttpClient)
2193 def __init__(self, http: SyncHttpClient): 2194 self._http = http 2195 self.agent_computers = AgentAgentComputerResource(http) 2196 self.agent_env_vars = AgentAgentEnvVarResource(http) 2197 self.agent_installations = AgentAgentInstallationResource(http) 2198 self.agent_tools = AgentAgentToolResource(http) 2199 self.agent_working_memory = AgentWorkingMemoryResource(http) 2200 self.schedules = ScheduleResource(http) 2201 self.work_items = AgentWorkItemResource(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:
2203 def list( 2204 self, 2205 *, 2206 page: int | None = None, 2207 page_size: int | None = None, 2208 search: str | None = None, 2209 user: str | None = None, 2210 org_id: str | None = None, 2211 template_config: str | None = None, 2212 solution_config: builtins.list[str] | None = None, 2213 ) -> AgentListResponse: 2214 """ 2215 List agents 2216 Returns a paginated list of agents visible to the authenticated caller. Results are 2217 ordered by creation time descending. 2218 Use `search` to filter by name, org, team, or owner fields. Use `user` or `org_id` 2219 to scope the list to a specific owner. Use `template_config` to find agents whose 2220 last applied template matches a given config ID. Use `solution_config` to find 2221 agents whose last applied template was imported as part of any of the given 2222 Solution config IDs. 2223 Pagination is page-based: pass `page` and `page_size` to navigate through large 2224 result sets. When called under a developer app scope, only agents belonging to that 2225 app are returned. 2226 2227 Args: 2228 page: Page number to retrieve, 1-indexed. Defaults to `1`. 2229 page_size: Number of agents to return per page. Defaults to `25`. 2230 search: Free-text search string matched against the agent name, org, team, and owner fields. 2231 user: User ID (`usr_...`) to filter by. Returns only agents owned by this user. 2232 org_id: Organization ID (`org_...`) to filter by. Returns only agents owned by this org. 2233 template_config: Config ID (`cfg_...`) or `lookup_key` of an AgentTemplate. Returns only agents whose last applied template matches. 2234 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. 2235 2236 Returns: 2237 Paginated list of agents matching the supplied filters. 2238 """ 2239 query: dict[str, object] = {} 2240 if page is not None: 2241 query["page"] = page 2242 if page_size is not None: 2243 query["page_size"] = page_size 2244 if search is not None: 2245 query["search"] = search 2246 if user is not None: 2247 query["user"] = user 2248 if org_id is not None: 2249 query["org_id"] = org_id 2250 if template_config is not None: 2251 query["template_config"] = template_config 2252 if solution_config is not None: 2253 query["solution_config"] = solution_config 2254 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.
2256 def create(self, input: AgentCreateInput) -> AgentCreateResponse: 2257 """ 2258 Create an agent 2259 Creates a new agent. Supports two mutually exclusive provisioning modes. 2260 **Template mode** pass `template` with the ID or `lookup_key` of an existing 2261 AgentTemplate config. The agent's tools, routines, skills, and installations are 2262 provisioned from that template's `config_ref` entries. 2263 **Bundle mode** pass `template_bundle` with a self-contained install payload 2264 (AgentTemplate body plus every skill, script, and config it references). The entire 2265 bundle commits in a single transaction; any failure rolls back the whole install and 2266 the response includes `installed_configs[]` one entry per persisted config. 2267 Pass exactly one of `template` or `template_bundle`. If neither is supplied, `name` 2268 is required and a blank agent is created. Requires authentication; when called under 2269 a developer app scope (`/developer/apps/:app/...`), the caller must hold the app scope 2270 for the target app. 2271 2272 Args: 2273 input: Request body. 2274 input.acl: Access control list controlling which users, teams, or orgs can read or manage this agent. 2275 input.description: Human-readable description of what the agent does. 2276 input.email: Email address assigned to the agent. Used as the agent's contact identity. 2277 input.identity: System-prompt identity string describing who the agent is. Passed verbatim to the model on each conversation turn. 2278 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. 2279 input.metadata: Arbitrary key-value map stored on the agent. Not interpreted by the platform. 2280 input.model: Default AI model identifier for this agent, e.g. `claude-sonnet-4-5`. Overridden per-request when the caller specifies a model. 2281 input.name: Display name for the agent. Required when neither `template` nor `template_bundle` is provided. 2282 input.org: Organization ID (`org_...`) that should own this agent. Mutually exclusive with `team` and `user`. 2283 input.originator: Free-form label identifying the source or author of the agent, e.g. a user ID, a deploy pipeline, or a slug. 2284 input.phone_number: Phone number assigned to the agent in E.164 format, e.g. `+15550001234`. 2285 input.profile_picture: Profile picture to attach to the agent. All three subfields are required when this object is present. 2286 input.team: Team ID (`team_...`) that should own this agent. Mutually exclusive with `org` and `user`. 2287 input.template: ID (`cfg_...`) or `lookup_key` of an existing AgentTemplate config to provision from. Mutually exclusive with `template_bundle`. 2288 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`. 2289 input.user: User ID (`usr_...`) that should own this agent. Mutually exclusive with `org` and `team`. 2290 2291 Returns: 2292 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. 2293 """ 2294 return self._http.request( 2295 "/api/v1/agents", 2296 method="POST", 2297 body=input, 2298 response_type=AgentCreateResponse, 2299 )
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.description: Human-readable description of what the agent does.
- 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:
2301 def delete(self, agent: str) -> None: 2302 """ 2303 Delete an agent 2304 Permanently deletes an agent and all of its associated resources. This action cannot 2305 be undone. 2306 The authenticated caller must own the agent or hold sufficient permissions within its 2307 owning org or team. When called under a developer app scope, the caller must hold the 2308 app scope for the target app. 2309 2310 Args: 2311 agent: ID (`agi_...`) or `lookup_key` of the agent to delete. 2312 2313 Returns: 2314 Empty body. Returns HTTP 204 on success. 2315 """ 2316 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.
2318 def get(self, agent: str) -> Agent: 2319 """ 2320 Retrieve an agent 2321 Returns the agent identified by ID or `lookup_key`. The authenticated caller must 2322 own the agent or hold sufficient permissions within its owning org or team. 2323 When called under a developer app scope, the agent must belong to that app. Use the 2324 list endpoint to retrieve many agents at once. 2325 2326 Args: 2327 agent: ID (`agi_...`) or `lookup_key` of the agent to retrieve. 2328 2329 Returns: 2330 The requested agent. 2331 """ 2332 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.
2334 def update(self, agent: str, input: AgentUpdateInput) -> Agent: 2335 """ 2336 Update an agent 2337 Updates one or more fields on an existing agent. Only the fields you supply are 2338 changed; omitted fields retain their current values. 2339 To clear the agent's default model, pass `model` as an empty string. The 2340 authenticated caller must own the agent or hold write permissions within its owning 2341 org or team. When called under a developer app scope, the caller must hold the app 2342 scope for the target app. 2343 2344 Args: 2345 agent: ID (`agi_...`) or `lookup_key` of the agent to update. 2346 input: Request body. 2347 input.acl: Replacement access control list. Fully replaces the existing ACL. 2348 input.description: New description of what the agent does. Pass an empty string to clear it. 2349 input.email: New email address for the agent. 2350 input.identity: Replacement identity system-prompt string describing who the agent is. 2351 input.lookup_key: New `lookup_key` slug. Must be unique within the owning app or org. 2352 input.metadata: Replacement key-value metadata map. The entire map is replaced, not merged. 2353 input.model: New default AI model identifier, e.g. `claude-sonnet-4-5`. Pass an empty string to clear the agent's default model. 2354 input.name: New display name for the agent. 2355 input.org: Organization ID (`org_...`) to transfer ownership to. 2356 input.originator: Replacement originator label identifying the source or author of the agent. 2357 input.phone_number: New phone number for the agent in E.164 format, e.g. `+15550001234`. 2358 input.profile_picture: Replacement profile picture. All three subfields are required when this object is present. 2359 input.team: Team ID (`team_...`) to transfer ownership to. 2360 input.user: User ID (`usr_...`) to transfer ownership to. 2361 2362 Returns: 2363 The updated agent with all current field values. 2364 """ 2365 return self._http.request( 2366 f"/api/v1/agents/{agent}", 2367 method="PATCH", 2368 body=input, 2369 response_type=Agent, 2370 )
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.description: New description of what the agent does. Pass an empty string to clear it.
- 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:
2372 def agent_health_actions( 2373 self, 2374 agent: str, 2375 *, 2376 source: builtins.list[str] | None = None, 2377 status: builtins.list[str] | None = None, 2378 kind: builtins.list[str] | None = None, 2379 ) -> HealthActionListResponse: 2380 """ 2381 List health actions for an agent 2382 Returns all health actions associated with a given agent. Health actions 2383 represent required or recommended steps such as setting environment 2384 variables, completing OAuth installations, or running custom verifiers 2385 that an agent needs to reach a healthy state. 2386 Results are not paginated; the full list for the agent is returned. Use 2387 the `source`, `status`, and `kind` filters to narrow results to the 2388 subset your UI or workflow needs. Multiple values for the same filter 2389 are treated as OR (e.g. passing two statuses returns actions matching 2390 either). The caller must be authenticated and scoped to the app that 2391 owns the agent. 2392 2393 Args: 2394 agent: Agent ID (`agt_...`) or lookup key of the agent whose health actions you want to list. 2395 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. 2396 status: Filter results to actions in one or more statuses. Accepted values: `"pending"`, `"completed"`, `"skipped"`, and `"degraded"`. Omit to return actions in all statuses. 2397 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. 2398 2399 Returns: 2400 Object containing a `data` array of health action objects for the specified agent. 2401 """ 2402 query: dict[str, object] = {} 2403 if source is not None: 2404 query["source"] = source 2405 if status is not None: 2406 query["status"] = status 2407 if kind is not None: 2408 query["kind"] = kind 2409 return self._http.request( 2410 f"/api/v1/agents/{agent}/agent_health_actions", 2411 query=query, 2412 response_type=HealthActionListResponse, 2413 )
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:
2415 def agent_routines(self, agent: str, input: AgentAgentRoutinesInput) -> AgentRoutine: 2416 """ 2417 Create a routine 2418 Creates a new routine and attaches it to the specified agent. Routines define 2419 how an agent responds to events or a cron schedule; the `handler_type` controls 2420 which execution model is used. 2421 The routine is created in `"draft"` status by default. To start processing 2422 events immediately, either pass `status: "active"` or call the activate 2423 endpoint after creation. Scheduled routines must run no more frequently than 2424 once per hour. Requires app scope. 2425 2426 Args: 2427 agent: Agent ID (`agt_...`) that this routine will be attached to. 2428 input: Request body. 2429 input.acl: Access control list governing who can read or manage this routine. 2430 input.config: Workflow config ID (`cfg_...`). Required when `handler_type` is `"workflow_graph"`. 2431 input.description: Optional human-readable description of what this routine does. 2432 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"`). 2433 input.event_type: Event type that triggers this routine. Deprecated use `event_config` instead. 2434 input.handler_type: Execution model for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`. 2435 input.lookup_key: Stable, unique key you assign to this routine for deterministic lookup. Must be unique within the app. 2436 input.message_policy: Visibility and explicit recipient selection for messages emitted by the routine. 2437 input.metadata: Arbitrary key-value metadata you can attach to the routine. Not interpreted by the platform. 2438 input.name: Human-readable display name for the routine. 2439 input.preset_config: Configuration passed to the preset at runtime. Used when `handler_type` is `"preset"`. 2440 input.preset_name: Name of the registered preset to use. Required when `handler_type` is `"preset"`. 2441 input.schedule: Cron expression for time-triggered routines (e.g. `"0 9 * * 1"`). Must not be more frequent than once per hour. 2442 input.script: Inline script source. Required when `handler_type` is `"script"`. 2443 input.status: Initial lifecycle status. One of `"draft"` or `"active"`. Defaults to `"draft"`. 2444 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`. 2445 input.trigger_context: Context in which the routine is triggered. One of `"chat_session"` or `"event"`. Defaults to `"event"`. 2446 input.user: Optional co-owner user ID (`usr_...`). When set, that user shares authority over this routine (view/modify/delete) without needing to administer the parent agent. Must be supplied explicitly the caller's identity is never auto-stamped as co-owner. 2447 2448 Returns: 2449 The newly created routine. 2450 """ 2451 return self._http.request( 2452 f"/api/v1/agents/{agent}/agent_routines", 2453 method="POST", 2454 body=input, 2455 response_type=AgentRoutine, 2456 )
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.message_policy: Visibility and explicit recipient selection for messages emitted by the routine.
- 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". - input.user: Optional co-owner user ID (
usr_...). When set, that user shares authority over this routine (view/modify/delete) without needing to administer the parent agent. Must be supplied explicitly the caller's identity is never auto-stamped as co-owner.
Returns:
The newly created routine.
def
export( self, agent: str, *, remove_identity: bool | None = None) -> archastro.platform.types.common.AgentExport:
2458 def export(self, agent: str, *, remove_identity: bool | None = None) -> AgentExport: 2459 """ 2460 Export an agent as an AgentTemplate 2461 Reconstructs an AgentTemplate config from a deployed agent and all of its 2462 sub-resources (tools, routines, skills, installations). Returns the template 2463 definition together with every dependent config file (scripts, workflows, skills, 2464 schemas) and their raw content, producing a fully self-contained export bundle. 2465 Use this endpoint to snapshot an agent's current configuration for backup, 2466 migration, or to seed a new Solution template. Pass `remove_identity: true` to 2467 strip instance-specific fields (email, phone number) before export. 2468 The authenticated caller must own the agent or hold sufficient permissions within 2469 its owning org or team. When called under a developer app scope, the caller must 2470 hold the app scope for the target app. 2471 2472 Args: 2473 agent: ID (`agi_...`) or `lookup_key` of the agent to export. 2474 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. 2475 2476 Returns: 2477 Export bundle containing the reconstructed AgentTemplate and all dependent config files with their raw content. 2478 """ 2479 query: dict[str, object] = {} 2480 if remove_identity is not None: 2481 query["remove_identity"] = remove_identity 2482 return self._http.request( 2483 f"/api/v1/agents/{agent}/export", 2484 query=query, 2485 response_type=AgentExport, 2486 )
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.
2488 def health(self, agent: str) -> AgentHealth: 2489 """ 2490 Retrieve an agent's health profile 2491 Returns an aggregate health profile for the specified agent, including an overall 2492 status, a numeric health score, recent activity metrics, and a list of recommended 2493 remediation actions. 2494 The health check is computed on demand at request time. The `checked_at` timestamp 2495 in the response reflects when the evaluation ran. Use this endpoint to surface 2496 diagnostics about tool availability, model configuration, and runtime activity in 2497 dashboards or monitoring workflows. 2498 The authenticated caller must own the agent or hold sufficient permissions within 2499 its owning org or team. When called under a developer app scope, the caller must 2500 hold the app scope for the target app. 2501 2502 Args: 2503 agent: ID (`agi_...`) or `lookup_key` of the agent to evaluate. 2504 2505 Returns: 2506 Aggregate health profile for the agent, including status, score, activity metrics, and recommended actions. 2507 """ 2508 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.
2510 def search(self, agent: str, input: AgentSearchInput) -> AgentSearchResponse: 2511 """ 2512 Search an agent's knowledge base 2513 Performs a semantic search over an agent's knowledge base and returns a ranked, 2514 `kind`-discriminated list of matching items. 2515 Threads are automatically indexed as conversational memory, including prior agent 2516 answers. A match is not necessarily independent source evidence. Result `type` 2517 identifies the source: `thread/messages` is conversation memory; use `source_types` 2518 with the desired corpus slugs (for example `knowledge/documents`) to exclude it. 2519 `kind` describes storage granularity, not whether the content is conversation memory. 2520 Two item kinds may appear in `data`: 2521 - `"chunk"` chunk-level results from the agent's context store. Present for all agents. 2522 - `"document"` document-level results. Present only when the agent has an active 2523 `archastro/knowledge` installation. 2524 Results from both kinds are scored with Reciprocal Rank Fusion (RRF), normalized to 2525 be comparable across kinds, then merged into a single ranked list. On a relevance tie, 2526 chunks appear before documents. The total number of results is capped at `max_results` 2527 across both kinds. 2528 Use `mode` to choose the retrieval strategy: `"hybrid"` (default) combines vector and 2529 full-text search; `"vector"` and `"fulltext"` select each strategy independently. 2530 2531 Args: 2532 agent: ID (`agi_...`) or `lookup_key` of the agent whose knowledge base to search. 2533 input: Request body. 2534 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`. 2535 input.min_similarity: Cosine-similarity floor for the vector leg, 0.0-1.0, applied to both chunk and document results. Candidates below it are discarded before ranking, so a high value trades recall for precision. Pass `0.0` to disable the floor when a missed match costs more than a weak one note that with no floor every query returns results, so an empty response can no longer be read as "no match". Omit to use the default. 2536 input.mode: Retrieval strategy. One of `"hybrid"` (default), `"vector"`, or `"fulltext"`. 2537 input.query: Natural-language search query used to retrieve relevant knowledge items. 2538 input.recency_days: When set, restricts results to items indexed within the last N days. 2539 input.source_types: Exact source-type slugs filtering both chunks and documents, e.g. `["knowledge/documents"]` for authored documents or `["thread/messages"]` for conversation memory. Omit or pass an empty array to include all source types. 2540 2541 Returns: 2542 Successful response 2543 """ 2544 return self._http.request( 2545 f"/api/v1/agents/{agent}/search", 2546 method="POST", 2547 body=input, 2548 response_type=AgentSearchResponse, 2549 )
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.
Threads are automatically indexed as conversational memory, including prior agent
answers. A match is not necessarily independent source evidence. Result type
identifies the source: thread/messages is conversation memory; use source_types
with the desired corpus slugs (for example knowledge/documents) to exclude it.
kind describes storage granularity, not whether the content is conversation memory.
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.min_similarity: Cosine-similarity floor for the vector leg, 0.0-1.0, applied to both chunk and document results. Candidates below it are discarded before ranking, so a high value trades recall for precision. Pass
0.0to disable the floor when a missed match costs more than a weak one note that with no floor every query returns results, so an empty response can no longer be read as "no match". Omit to use the default. - 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: Exact source-type slugs filtering both chunks and documents, e.g.
["knowledge/documents"]for authored documents or["thread/messages"]for conversation memory. Omit or pass an empty array to include all source types.
Returns:
Successful response
2551 def self_solution(self, agent: str) -> AgentSelfSolutionResponse: 2552 """ 2553 Ensure an agent's private self-solution 2554 Lazily snapshots an authorized agent into its single private, versioned Solution. 2555 2556 Args: 2557 agent: Agent ID or lookup key. 2558 2559 Returns: 2560 Successful response 2561 """ 2562 return self._http.request( 2563 f"/api/v1/agents/{agent}/self_solution", 2564 response_type=AgentSelfSolutionResponse, 2565 )
Ensure an agent's private self-solution Lazily snapshots an authorized agent into its single private, versioned Solution.
Arguments:
- agent: Agent ID or lookup key.
Returns:
Successful response
def
threads( self, agent: str, input: AgentThreadsInput) -> archastro.platform.types.threads.Thread:
2567 def threads(self, agent: str, input: AgentThreadsInput) -> Thread: 2568 """ 2569 Create a thread for an agent 2570 Creates a new thread owned by the specified agent. The thread is scoped to the 2571 agent's identity and is immediately available for messaging. 2572 The authenticated caller must have access to the agent's parent app. If your 2573 API key is scoped to a specific app, pass that app's ID via the `app` parameter. 2574 Attempting to create a thread for an agent you cannot access returns 404. 2575 By default the platform may send an automatic welcome message into the new 2576 thread. Pass `skip_welcome_message: true` to suppress this behavior. 2577 2578 Args: 2579 agent: Agent ID (`agt_...`). The thread will be owned by this agent. 2580 input: Request body. 2581 input.skip_welcome_message: When `true`, suppresses the automatic welcome message that the platform sends when a new thread is created. Defaults to `false`. 2582 input.thread: Attributes for the new thread. See ThreadCreateParams for available fields. 2583 2584 Returns: 2585 The newly created thread. 2586 """ 2587 return self._http.request( 2588 f"/api/v1/agents/{agent}/threads", 2589 method="POST", 2590 body=input, 2591 response_type=Thread, 2592 )
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. See ThreadCreateParams for available fields.
Returns:
The newly created thread.
def
upgrade( self, agent: str, input: AgentUpgradeInput) -> archastro.platform.types.common.AgentUpgradeResponse:
2594 def upgrade(self, agent: str, input: AgentUpgradeInput) -> AgentUpgradeResponse: 2595 """ 2596 Upgrade an agent from an AgentTemplate 2597 Upgrades an existing agent by reconciling it against an AgentTemplate from a 2598 Solution. Supports two modes: 2599 - `"reapply"` (default) re-applies the agent's currently tracked template, 2600 picking up any changes the template author has made since the last apply. 2601 - `"replace"` moves the agent to a different template. `template` is required 2602 in this mode. 2603 Set `dry_run: true` to compute and return the full upgrade diff (adds, updates, 2604 removes, noops) without writing any changes. The response includes a 2605 `review_fingerprint` you can pass back via `expected_review_fingerprint` on the 2606 live apply to guard against the diff changing between review and execution. 2607 Safe overrides (`name`, `description`, `email`, `phone_number`, `metadata`, 2608 `identity`, `originator`, `model`) let you pin instance-specific values that 2609 should not be overwritten by the template during the upgrade. 2610 The authenticated caller must own the agent or hold write permissions within its 2611 owning org or team. When called under a developer app scope, the caller must hold 2612 the app scope for the target app. 2613 2614 Args: 2615 agent: ID (`agi_...`) or `lookup_key` of the agent to upgrade. 2616 input: Request body. 2617 input.description: Instance-specific description override. Pins this value so the template upgrade does not overwrite it. 2618 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. 2619 input.email: Instance-specific email address override. Pins this value so the template upgrade does not overwrite it. 2620 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. 2621 input.identity: Instance-specific identity system-prompt override. Pins this value so the template upgrade does not overwrite it. 2622 input.metadata: Instance-specific metadata override. Pins this value so the template upgrade does not overwrite it. 2623 input.mode: Upgrade mode. `"reapply"` (default) refreshes the agent's tracked template; `"replace"` moves the agent to a different template (requires `template`). 2624 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. 2625 input.name: Instance-specific name override. Pins this value so the template upgrade does not overwrite it. 2626 input.originator: Instance-specific originator label override. Pins this value so the template upgrade does not overwrite it. 2627 input.phone_number: Instance-specific phone number override in E.164 format. Pins this value so the template upgrade does not overwrite it. 2628 input.template: ID (`cfg_...`) or `lookup_key` of the target AgentTemplate config. Optional in `"reapply"` mode; required in `"replace"` mode. 2629 2630 Returns: 2631 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. 2632 """ 2633 return self._http.request( 2634 f"/api/v1/agents/{agent}/upgrade", 2635 method="POST", 2636 body=input, 2637 response_type=AgentUpgradeResponse, 2638 )
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,description,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.description: Instance-specific description override. Pins this value so the template upgrade does not overwrite it.
- 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.