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