archastro.platform.types.common
1# Copyright (c) 2026 ArchAstro Inc. All Rights Reserved. 2# This file is auto-generated by @archastro/sdk-generator. Do not edit. 3# Content hash: dc1810989af9 4 5from datetime import datetime 6from typing import Any, Literal 7 8from pydantic import BaseModel, ConfigDict, Field 9 10from .config import Config 11from .image import ImageSource 12from .users import User 13 14 15class AclGrant(BaseModel): 16 """ 17 A single access-control grant that pairs a principal with the set of actions it is allowed to perform. 18 """ 19 20 actions: list[str] = Field( 21 ..., 22 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 23 ) 24 principal: str | None = Field( 25 default=None, 26 description='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"`.', 27 ) 28 principal_type: str = Field( 29 ..., 30 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 31 ) 32 33 34class AclRemoveTarget(BaseModel): 35 """ 36 Identifies a principal to be removed from an access-control list. 37 """ 38 39 principal: str | None = Field( 40 default=None, 41 description='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"`.', 42 ) 43 principal_type: str = Field( 44 ..., 45 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 46 ) 47 48 49class Acl(BaseModel): 50 """ 51 An access-control list payload that supports either full replacement or targeted patch operations on a resource's grants. 52 """ 53 54 add: list[AclGrant] | None = Field( 55 default=None, 56 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 57 ) 58 grants: list[AclGrant] | None = Field( 59 default=None, 60 description="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`.", 61 ) 62 remove: list[AclRemoveTarget] | None = Field( 63 default=None, 64 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 65 ) 66 67 68class ActivityFeedEntry(BaseModel): 69 """ 70 A single event record in an activity feed, capturing what happened, who caused it, and which resources were involved. 71 """ 72 73 agent: str | dict[str, Any] | None = Field( 74 default=None, 75 description="The agent that produced this event. Returns an agent ID (`agi_...`) by default, or an expanded agent object when the association is loaded. `null` if no agent is associated.", 76 ) 77 app: str | None = Field( 78 default=None, 79 description="ID of the application that produced this entry (`dap_...`). `null` if not scoped to an app.", 80 ) 81 attachments: list[dict[str, Any]] | None = Field( 82 default=None, 83 description='Array of attachment objects associated with this entry. Each attachment has a `type` field (e.g. `"file"`, `"task"`, `"artifact"`) and type-specific additional fields. Empty array when there are no attachments.', 84 ) 85 automation_run: str | None = Field( 86 default=None, 87 description="ID of the automation run that produced this entry (`atr_...`). `null` if not produced by an automation run.", 88 ) 89 content: str | None = Field( 90 default=None, 91 description="A longer explanation of the event rendered as Markdown. `null` if no additional content is available.", 92 ) 93 correlation_id: str | None = Field( 94 default=None, 95 description="An opaque string used to group related entries together. Entries sharing the same `correlation_id` belong to a single logical operation. `null` if not correlated.", 96 ) 97 created_at: datetime | None = Field( 98 default=None, description="When this activity feed entry was created (ISO 8601)." 99 ) 100 id: str = Field(..., description="Activity feed entry ID (`afe_...`).") 101 kind: str | None = Field( 102 default=None, 103 description='The type of event this entry represents, e.g. `"agent_step"` or `"tool_call"`. Determines how `title`, `content`, and `attachments` should be interpreted.', 104 ) 105 level: str | None = Field( 106 default=None, 107 description='Severity level of the event. One of `"info"`, `"warning"`, or `"error"`. `null` if no severity is set.', 108 ) 109 metadata: dict[str, Any] | None = Field( 110 default=None, 111 description="Arbitrary key-value metadata stored on this entry. Returns an empty object when no metadata is set.", 112 ) 113 org: str | None = Field( 114 default=None, 115 description="ID of the organization this entry belongs to (`org_...`). `null` if not org-scoped.", 116 ) 117 routine_run: str | None = Field( 118 default=None, 119 description="ID of the agent routine run that produced this entry (`arr_...`). `null` if not produced by a routine run.", 120 ) 121 sandbox: str | None = Field( 122 default=None, 123 description="Identifier of the sandbox environment this entry was generated in. `null` in production contexts.", 124 ) 125 session_record: str | None = Field( 126 default=None, 127 description="ID of the agent session record this entry belongs to (`ase_...`). `null` if not part of an agent session.", 128 ) 129 team: str | None = Field( 130 default=None, 131 description="ID of the team this entry is associated with (`tem_...`). `null` if not team-scoped.", 132 ) 133 thread: str | None = Field( 134 default=None, 135 description="ID of the thread this entry is associated with (`thr_...`). `null` if not linked to a thread.", 136 ) 137 title: str | None = Field( 138 default=None, 139 description="A one-line human-readable summary of the event. `null` if the entry has no title.", 140 ) 141 updated_at: datetime | None = Field( 142 default=None, description="When this activity feed entry was last modified (ISO 8601)." 143 ) 144 user: str | dict[str, Any] | None = Field( 145 default=None, 146 description="The user who triggered this event. Returns a user ID (`usr_...`) by default, or an expanded user object when the association is loaded. `null` if no user is associated.", 147 ) 148 149 150class ActivityFeedEntryListResponse(BaseModel): 151 """ 152 A paginated list of activity feed entries returned by a feed query, with cursors for navigating backward and forward through results. 153 """ 154 155 after_cursor: str | None = Field( 156 default=None, 157 description="Opaque cursor to pass as `after` to retrieve the next page of entries. `null` when this is the last page.", 158 ) 159 before_cursor: str | None = Field( 160 default=None, 161 description="Opaque cursor to pass as `before` to retrieve the previous page of entries. `null` when this is the first page.", 162 ) 163 entries: list[ActivityFeedEntry] = Field( 164 ..., 165 description="Array of activity feed entry objects for the current page, ordered by time descending.", 166 ) 167 has_more: bool = Field( 168 ..., 169 description="Whether additional entries exist beyond the current page. When `true`, use `after_cursor` to fetch the next page.", 170 ) 171 172 173class Actor(BaseModel): 174 """ 175 The entity that authored a message, either a human user or an agent. 176 """ 177 178 alias: str | None = Field( 179 default=None, 180 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 181 ) 182 id: str | None = Field( 183 default=None, 184 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 185 ) 186 name: str | None = Field( 187 default=None, 188 description="Display name of the actor shown in the UI. `null` if no name is set.", 189 ) 190 profile_picture: ImageSource | None = Field( 191 default=None, 192 description="Profile picture for the actor. `null` if the actor has no profile picture.", 193 ) 194 195 196class UpgradeTemplateSummary(BaseModel): 197 """ 198 Compact summary of an AgentTemplate config referenced by an agent upgrade or source-solution response. 199 """ 200 201 created_at: datetime | None = Field( 202 default=None, description="When this template config was created (ISO 8601)." 203 ) 204 description: str | None = Field( 205 default=None, 206 description="Description of the template from the config body. `null` if the current version has no `description` field.", 207 ) 208 display_name: str | None = Field( 209 default=None, 210 description="Human-readable display name from the config body. `null` if the current version has no `display_name` field.", 211 ) 212 id: str = Field(..., description="Template config ID (`cfg_...`).") 213 kind: str = Field( 214 ..., description='Config kind identifier for this template (e.g. `"agent_tool_template"`).' 215 ) 216 lookup_key: str | None = Field( 217 default=None, 218 description="Stable lookup key assigned to this template config. `null` if no lookup key is set.", 219 ) 220 name: str | None = Field( 221 default=None, 222 description="Template name as stored in the config body. `null` if the current version has no `name` field.", 223 ) 224 updated_at: datetime | None = Field( 225 default=None, description="When this template config was last modified (ISO 8601)." 226 ) 227 virtual_path: str | None = Field( 228 default=None, 229 description="Virtual filesystem path for this template config. `null` if not set.", 230 ) 231 232 233class InstalledConfigEntry(BaseModel): 234 """ 235 A slim summary of a single config record created during an agent install transaction. Returned as an entry in `AgentCreateResponse.installed_configs`. 236 """ 237 238 id: str = Field(..., description="ID of the persisted config record (`cfg_...`).") 239 key: str = Field( 240 ..., 241 description='Caller-supplied correlation key echoed back from the request. For top-level configs this is the original `lookup_key` (before any suffix is applied). For skill file children it is the composite `"<skill_lookup_key>:<relative_path>"` string, since file rows have no lookup_key of their own.', 242 ) 243 kind: str = Field( 244 ..., 245 description='Type of config that was created. One of `"Skill"`, `"File"`, `"Script"`, `"AgentTemplate"`, or `"Config"`.', 246 ) 247 lookup_key: str | None = Field( 248 default=None, 249 description="Stored `lookup_key` for this config after any suffix has been applied. `null` for `File` children inside a skill bundle, which are keyed by `(parent_id, relative_path)` rather than by `lookup_key`.", 250 ) 251 252 253class LLMConfig(BaseModel): 254 """ 255 LLM invocation settings for a routine or chain step. When present, overrides the agent-level model selection. 256 """ 257 258 model: str | None = Field( 259 default=None, 260 description='Model identifier to use for this routine or step, e.g. `"claude-sonnet-4-5"`. When omitted, the agent\'s default model is used.', 261 ) 262 263 264class PresetConfig(BaseModel): 265 """ 266 Configuration for a preset routine handler. Controls the agent's behavior, session persistence, and model selection for a given routine or chain step. 267 """ 268 269 instructions: str | None = Field( 270 default=None, 271 description="Custom task or behavior instructions for the preset (max 10,000 chars).", 272 ) 273 llm: LLMConfig | None = Field( 274 default=None, 275 description="LLM invocation settings (e.g. a `model` override for this routine/step).", 276 ) 277 session_mode: str | None = Field( 278 default=None, 279 description="Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`).", 280 ) 281 session_scope: str | None = Field( 282 default=None, 283 description="When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`.", 284 ) 285 structured_message_template_ids: list[str] | None = Field( 286 default=None, 287 description="IDs of structured message templates that constrain the agent's responses to predefined structured formats.", 288 ) 289 290 291class WorkerStatus(BaseModel): 292 """ 293 Execution state of the background worker processing a routine run. Reflects the current job status and retry progress. 294 """ 295 296 attempt: int = Field( 297 ..., 298 description="Number of times the worker has been attempted so far. `0` means the job has been enqueued but not yet started.", 299 ) 300 max_attempts: int = Field( 301 ..., 302 description='Maximum number of attempts the worker is allowed before the job is marked `"discarded"`.', 303 ) 304 status: str = Field( 305 ..., 306 description='Current execution state of the worker. One of `"queued"`, `"executing"`, `"retrying"`, `"completed"`, `"discarded"`, or `"cancelled"`.', 307 ) 308 309 310class MediaVariant(BaseModel): 311 """ 312 A processed variant of a media item, such as the original upload or a resized thumbnail, including a signed download URL resolved at request time. 313 """ 314 315 content_type: str | None = Field( 316 default=None, 317 description='MIME type of this variant\'s file (e.g., `"image/jpeg"`, `"video/mp4"`). `null` if the file is not loaded.', 318 ) 319 created_at: datetime | None = Field( 320 default=None, description="When this variant was created (ISO 8601)." 321 ) 322 file: str | None = Field( 323 default=None, 324 description="ID of the underlying storage file that backs this variant (`fil_...`).", 325 ) 326 filename: str | None = Field( 327 default=None, 328 description="Original filename of the uploaded file for this variant. `null` if the file is not loaded.", 329 ) 330 height: int | None = Field( 331 default=None, description="Height of this variant in pixels. `null` if not recorded." 332 ) 333 id: str = Field(..., description="Media variant ID (`mvr_...`).") 334 image_source: ImageSource | None = Field( 335 default=None, 336 description="Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types.", 337 ) 338 updated_at: datetime | None = Field( 339 default=None, description="When this variant was last updated (ISO 8601)." 340 ) 341 url: str | None = Field( 342 default=None, 343 description="Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", 344 ) 345 variant_key: str | None = Field( 346 default=None, 347 description='Identifier for this variant\'s processing tier. Common values include `"original"` (the unmodified upload) and `"thumbnail"` (a resized preview).', 348 ) 349 width: int | None = Field( 350 default=None, description="Width of this variant in pixels. `null` if not recorded." 351 ) 352 353 354class Attachment(BaseModel): 355 """ 356 A rich attachment associated with a message, such as a file, scraped link, artifact, task, media item, or inline action. 357 """ 358 359 content_type: str | None = Field( 360 default=None, 361 description='MIME type of the attached file, e.g. `"image/png"` or `"application/pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 362 ) 363 description: str | None = Field( 364 default=None, 365 description="Short description. The page meta-description for `scraped_link`, the artifact description for `artifact`, and the task description for `task` types. `null` on other types.", 366 ) 367 filename: str | None = Field( 368 default=None, 369 description='Original filename of the attached file, e.g. `"report.pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 370 ) 371 height: int | None = Field( 372 default=None, 373 description="Height in pixels of the media item. Present on `media` type only. `null` otherwise.", 374 ) 375 id: str = Field(..., description="Unique identifier for this attachment within the message.") 376 image_height: int | None = Field( 377 default=None, 378 description="Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 379 ) 380 image_source: ImageSource | None = Field( 381 default=None, 382 description="Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise.", 383 ) 384 image_url: str | None = Field( 385 default=None, 386 description="URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", 387 ) 388 image_width: int | None = Field( 389 default=None, 390 description="Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 391 ) 392 media_type: str | None = Field( 393 default=None, 394 description='The media category, e.g. `"video"` or `"audio"`. Present on `media` type only. `null` otherwise.', 395 ) 396 name: str | None = Field( 397 default=None, 398 description="Display name of the media item. Present on `media` type only. `null` otherwise.", 399 ) 400 object: dict[str, Any] | None = Field( 401 default=None, 402 description="The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. `null` on other types.", 403 ) 404 title: str | None = Field( 405 default=None, 406 description="Display title. The page title for `scraped_link`, the artifact name for `artifact`, and the task title for `task` types. `null` on other types.", 407 ) 408 type: str = Field( 409 ..., 410 description='The attachment type. One of `"file"`, `"scraped_link"`, `"artifact"`, `"task"`, `"media"`, or `"action"`. Determines which additional fields are present.', 411 ) 412 url: str | None = Field( 413 default=None, 414 description="URL to access the resource. A signed download URL for `file` and `artifact` types; the original URL for `scraped_link`; a media playback URL for `media`. `null` on `task` and `action` types.", 415 ) 416 variants: list[MediaVariant] | None = Field( 417 default=None, 418 description="Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", 419 ) 420 version: int | None = Field( 421 default=None, 422 description="Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", 423 ) 424 width: int | None = Field( 425 default=None, 426 description="Width in pixels of the media item. Present on `media` type only. `null` otherwise.", 427 ) 428 429 430class AuthTokens(BaseModel): 431 """ 432 Credential bundle returned after a successful authentication exchange. Contains the access token, refresh token, and the authenticated user. 433 """ 434 435 expires_in: int = Field( 436 ..., 437 description="Number of seconds until `token` expires. After this period, use `refresh_token` to obtain a new access token.", 438 ) 439 metadata: dict[str, Any] | None = Field( 440 default=None, 441 description="Optional auxiliary data associated with this authentication event, such as `onboarding_job_id` when the user is completing onboarding. `null` when no extra context is present.", 442 ) 443 refresh_token: str = Field( 444 ..., 445 description="Long-lived opaque refresh token. Use this to obtain a new access token when `token` expires.", 446 ) 447 token: str = Field( 448 ..., 449 description="Short-lived JWT access token. Include this value in the `Authorization: Bearer <token>` header for all authenticated API requests.", 450 ) 451 token_type: str = Field(..., description='Token scheme. Always `"Bearer"`.') 452 user: User = Field( 453 ..., 454 description="The user who authenticated. Contains the user's profile and account details.", 455 ) 456 457 458class BugReport(BaseModel): 459 """ 460 A bug report or freeform feedback submission from any ArchAstro client. Bug reports are write-only for the submitting user and are not returned by any public list or show endpoint. 461 """ 462 463 app: str | None = Field( 464 default=None, 465 description="App ID (`dap_...`) of the developer app through which the report was submitted.", 466 ) 467 client: str = Field( 468 ..., 469 description='The client application that submitted this report. One of `"agent_network_web"`, `"cli"`, or `"developer_portal"`.', 470 ) 471 client_version: str = Field( 472 ..., 473 description='Version string of the submitting client at the time of submission, e.g. `"1.4.2"`.', 474 ) 475 context: dict[str, Any] | None = Field( 476 default=None, 477 description="Optional free-form JSON object providing additional context captured by the client (e.g. viewport size, active route). `null` when no context was provided. Maximum 5 KB when serialized.", 478 ) 479 created_at: datetime | None = Field( 480 default=None, description="When the bug report was submitted (ISO 8601)." 481 ) 482 description: str = Field( 483 ..., 484 description="Freeform text describing the issue or feedback, as entered by the user. Up to 10,000 characters.", 485 ) 486 id: str = Field(..., description="Bug report ID (`bgr_...`).") 487 org: str | None = Field( 488 default=None, 489 description="Organization ID (`org_...`) scoping this report. `null` when the user's account is not part of an organization.", 490 ) 491 sandbox: str | None = Field( 492 default=None, 493 description="Sandbox ID (`dsb_...`) active at submission time. `null` when the report was not submitted from a sandbox context.", 494 ) 495 team: str | None = Field( 496 default=None, 497 description="Team ID (`tem_...`) of the team the submitting user belonged to at submission time. `null` when the user had no active team.", 498 ) 499 updated_at: datetime | None = Field( 500 default=None, description="When the bug report record was last modified (ISO 8601)." 501 ) 502 503 504class BuiltinTool(BaseModel): 505 """ 506 A single callable tool within a builtin tool catalog entry. Represents one discrete function an agent can invoke. 507 """ 508 509 description: str | None = Field( 510 default=None, 511 description="Human-readable explanation of what the tool does. Surfaced to the agent as part of tool selection context. `null` when no description has been defined.", 512 ) 513 name: str = Field( 514 ..., 515 description='Machine-readable name of the tool as it is registered with the agent runtime, e.g. `"web_search"` or `"github_create_issue"`.', 516 ) 517 518 519class BuiltinToolCatalogEntry(BaseModel): 520 """ 521 A catalog entry describing a category of platform-provided (builtin) tools that can be enabled for an agent. Each entry groups one or more individual tools under a shared key, label, and configuration schema. 522 """ 523 524 config_schema: dict[str, Any] | None = Field( 525 default=None, 526 description="JSON Schema object describing the configuration options for this tool category. Clients should use this schema to render and validate configuration forms before submitting. `null` when no configuration is needed.", 527 ) 528 description: str | None = Field( 529 default=None, 530 description="Short prose description of what this tool category does. Suitable for display in setup UIs. `null` when no description has been defined.", 531 ) 532 instruction: str | None = Field( 533 default=None, 534 description="Additional guidance surfaced to the agent at runtime when this tool category is enabled. `null` when no custom instruction is set.", 535 ) 536 key: str = Field( 537 ..., 538 description='Unique slug identifying this tool category, e.g. `"web_search"` or `"github"`.', 539 ) 540 label: str | None = Field( 541 default=None, 542 description='Human-readable display name for the tool category, e.g. `"Web Search"`. `null` when no label has been assigned.', 543 ) 544 multi_instance_mode: str | None = Field( 545 default=None, 546 description='Controls whether multiple instances of this tool category may be enabled simultaneously. `"namespaced"` multiple instances allowed; each must carry a `name_prefix` to distinguish them. `"passthrough"` multiple instances allowed without a `name_prefix`; names are derived from the underlying source. `null` single-instance only.', 547 ) 548 providers: list[str] | None = Field( 549 default=None, 550 description='List of integration provider slugs that can back this tool category, e.g. `["github", "gitlab"]`. Empty when the tool is provider-agnostic.', 551 ) 552 requires_integration: bool | None = Field( 553 default=None, 554 description="Whether enabling this tool category requires the user to connect a third-party integration. `true` means at least one active integration of the appropriate type must exist before the tool can be used.", 555 ) 556 server_tool_type: str | None = Field( 557 default=None, 558 description="Internal type identifier used by the platform server when registering these tools. `null` for client-side-only tool categories.", 559 ) 560 tools: list[BuiltinTool] | None = Field( 561 default=None, 562 description="Array of individual tool definitions included in this category. Each entry describes a single callable tool with its own name and description.", 563 ) 564 565 566class ChannelAck(BaseModel): 567 """ 568 Empty acknowledgement payload returned by channel message handlers that produce no data. The wire envelope is `{"status": "ok", "response": {}}`. 569 """ 570 571 pass 572 573 574class MessageReaction(BaseModel): 575 """ 576 A compact reaction record embedded in a message's `reactions` array, representing a single user's reaction to a message. 577 """ 578 579 payload: dict[str, Any] | None = Field( 580 default=None, 581 description='Type-specific reaction data. For `"emoji_reaction"` reactions, contains an `emoji` key with the Unicode emoji string (e.g., `" "`).', 582 ) 583 type: str = Field( 584 ..., 585 description='Reaction type identifier. Currently always `"emoji_reaction"` for emoji-based reactions.', 586 ) 587 user: str | None = Field( 588 default=None, description="Public ID of the user who added the reaction (`usr_...`)." 589 ) 590 591 592class Message(BaseModel): 593 """ 594 A chat message posted in a thread, including its content, author, attachments, reactions, and optional reply metadata. 595 """ 596 597 actors: list[Actor] | None = Field( 598 default=None, 599 description="Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry.", 600 ) 601 agent: str | None = Field( 602 default=None, 603 description="ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", 604 ) 605 agent_mode: Literal["cli", "embedded"] | None = Field( 606 default=None, 607 description="Local agent execution mode for this message. One of `cli`, `embedded`, or `null` when the message was not created by a local agent execution path.", 608 ) 609 attachments: list[Attachment] | None = Field( 610 default=None, 611 description="Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments.", 612 ) 613 branched_thread: str | None = Field( 614 default=None, 615 description="ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", 616 ) 617 content: str | None = Field( 618 default=None, 619 description="Text content of the message. `null` for messages that contain only attachments.", 620 ) 621 created_at: datetime | None = Field( 622 default=None, description="When the message was posted (ISO 8601)." 623 ) 624 has_replies: bool | None = Field( 625 default=None, 626 description="Whether this message has at least one reply. Only present when explicitly requested or computed by the server.", 627 ) 628 id: str = Field(..., description="Message ID (`msg_...`).") 629 idempotency_key: str | None = Field( 630 default=None, 631 description="Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", 632 ) 633 legacy_agent: str | None = Field( 634 default=None, 635 description="Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", 636 ) 637 metadata: dict[str, Any] | None = Field( 638 default=None, 639 description="Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set.", 640 ) 641 org: str | None = Field( 642 default=None, description="ID of the organization that owns this message (`org_...`)." 643 ) 644 reactions: list[MessageReaction] | None = Field( 645 default=None, 646 description="Emoji and other reactions added to this message by users. Empty array if no reactions have been added or the association is not preloaded.", 647 ) 648 rendering_mode: str | None = Field( 649 default=None, 650 description='Display hint for how the message should be rendered. One of `"reply"`, `"direct"`, or `"inline"`. `null` for user-authored messages, which are always rendered as standard replies.', 651 ) 652 replies: list[dict[str, Any]] | None = Field( 653 default=None, 654 description="Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message.", 655 ) 656 replies_after_cursor: str | None = Field( 657 default=None, 658 description="Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", 659 ) 660 replies_before_cursor: str | None = Field( 661 default=None, 662 description="Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", 663 ) 664 reply_count: int | None = Field( 665 default=None, 666 description="Total number of direct replies to this message. Only present when explicitly requested or computed by the server.", 667 ) 668 reply_to: dict[str, Any] | None = Field( 669 default=None, 670 description="The parent message this message is a reply to, expanded as a full message object when loaded. `null` if this is a top-level message or the association is not preloaded.", 671 ) 672 sandbox: str | None = Field( 673 default=None, 674 description="ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", 675 ) 676 team: str | None = Field( 677 default=None, 678 description="ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", 679 ) 680 thread: str | None = Field( 681 default=None, 682 description="ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", 683 ) 684 user: str | None = Field( 685 default=None, 686 description="The human user who sent this message. Returns a public ID string (`usr_...`) when the association is not preloaded, or an expanded user object when it is. `null` for messages sent by agents.", 687 ) 688 689 690class ComputerExecResult(BaseModel): 691 """ 692 The result of executing a shell command on an agent's computer environment. Contains the captured output and the process exit code. 693 """ 694 695 exit_code: int | None = Field( 696 default=None, 697 description="The UNIX exit code returned by the process. `0` indicates success; any non-zero value indicates an error. `null` if the process did not terminate normally.", 698 ) 699 output: str | None = Field( 700 default=None, 701 description="The combined stdout and stderr output produced by the command. `null` if the command produced no output.", 702 ) 703 704 705class ContextDocument(BaseModel): 706 """ 707 A context document stored within a context source. Carries metadata and size information only; retrieve the full text content via the `/content` endpoint. 708 """ 709 710 agent: str | None = Field( 711 default=None, 712 description="ID of the agent that owns this document (`agi_...`). `null` if owned by a user or team.", 713 ) 714 created_at: datetime | None = Field( 715 default=None, description="When the document was created (ISO 8601)." 716 ) 717 file: str | None = Field( 718 default=None, 719 description="ID of the backing storage file (`fil_...`) when the document is file-backed. `null` for inline documents.", 720 ) 721 id: str = Field(..., description="Context document ID (`cdo_...`).") 722 metadata: dict[str, Any] | None = Field( 723 default=None, 724 description="Arbitrary key-value metadata attached to the document. Shape varies by source type.", 725 ) 726 source: str | None = Field( 727 default=None, description="ID of the context source this document belongs to (`cso_...`)." 728 ) 729 team: str | None = Field( 730 default=None, 731 description="ID of the team that owns this document (`tem_...`). `null` if owned by a user or agent.", 732 ) 733 title: str | None = Field( 734 default=None, 735 description="Human-readable display title of the document. `null` if no title has been set.", 736 ) 737 total_lines: int | None = Field( 738 default=None, 739 description="Total number of lines in the document's text content. `0` if the document has no content.", 740 ) 741 total_size: int | None = Field( 742 default=None, 743 description="Total byte size of the document's text content. `0` if the document has no content.", 744 ) 745 updated_at: datetime | None = Field( 746 default=None, description="When the document was last modified (ISO 8601)." 747 ) 748 user: str | None = Field( 749 default=None, 750 description="ID of the user that owns this document (`usr_...`). `null` if owned by a team or agent.", 751 ) 752 753 754class ContextDocumentContent(BaseModel): 755 """ 756 The text content of a context document, optionally sliced by line or byte range. Includes totals and slice boundary fields for the requested unit. 757 """ 758 759 content: str = Field( 760 ..., 761 description="Text of the document. Contains the full content when no `offset`/`limit` was requested, or only the requested slice otherwise.", 762 ) 763 end_byte: int | None = Field( 764 default=None, 765 description='Zero-based exclusive index of the last byte in `content` (i.e. the slice covers bytes `start_byte..end_byte-1`). Populated only when `unit` is `"bytes"`; `null` otherwise.', 766 ) 767 end_line: int | None = Field( 768 default=None, 769 description='1-indexed line number of the last line included in `content` (i.e. the slice covers lines `start_line` through `end_line` inclusive). Populated only when `unit` is `"lines"`; `null` otherwise.', 770 ) 771 id: str = Field(..., description="Context document ID (`cdo_...`).") 772 limit: int | None = Field( 773 default=None, 774 description="The `limit` value echoed from the request. `null` when no limit was requested.", 775 ) 776 metadata: dict[str, Any] | None = Field( 777 default=None, 778 description="Arbitrary key-value metadata attached to the document, such as source URL or author. `null` if no metadata was recorded.", 779 ) 780 offset: int | None = Field( 781 default=None, 782 description="The `offset` value echoed from the request. `null` when no offset was requested.", 783 ) 784 start_byte: int | None = Field( 785 default=None, 786 description='Zero-based index of the first byte included in `content`. Populated only when `unit` is `"bytes"`; `null` otherwise.', 787 ) 788 start_line: int | None = Field( 789 default=None, 790 description='1-indexed line number of the first line included in `content`. Populated only when `unit` is `"lines"`; `null` otherwise.', 791 ) 792 title: str | None = Field( 793 default=None, 794 description="Human-readable display title of the document. `null` if the document has no title set.", 795 ) 796 total_lines: int = Field( 797 ..., 798 description="Total number of lines in the document's full content, regardless of any slice.", 799 ) 800 total_size: int = Field( 801 ..., description="Total byte size of the document's full content, regardless of any slice." 802 ) 803 unit: str | None = Field( 804 default=None, 805 description='Slice unit used when `offset` and `limit` were provided. One of `"lines"` (default) or `"bytes"`. `null` when no slice was requested.', 806 ) 807 808 809class ContextIngestion(BaseModel): 810 """ 811 A context ingestion job that processes a context source and populates its documents. Tracks status and timing from submission through completion or failure. 812 """ 813 814 agent: str | None = Field( 815 default=None, 816 description="ID of the agent that initiated this ingestion (`agi_...`). `null` if initiated by a user.", 817 ) 818 completed_at: datetime | None = Field( 819 default=None, 820 description="When the ingestion job finished, either successfully or with a failure. `null` if still in progress.", 821 ) 822 created_at: datetime | None = Field( 823 default=None, description="When the ingestion was submitted (ISO 8601)." 824 ) 825 error: dict[str, Any] | None = Field( 826 default=None, 827 description='Structured error details when the ingestion has `status: "failed"`. `null` for any other status.', 828 ) 829 id: str = Field(..., description="Context ingestion ID (`cig_...`).") 830 metadata: dict[str, Any] | None = Field( 831 default=None, 832 description="Arbitrary key-value metadata associated with this ingestion run. Shape is caller-defined.", 833 ) 834 source: str | None = Field( 835 default=None, 836 description="ID of the context source being ingested (`cso_...`). `null` if the source has been deleted.", 837 ) 838 started_at: datetime | None = Field( 839 default=None, 840 description="When the ingestion job began processing. `null` if the job is still pending.", 841 ) 842 status: str = Field( 843 ..., 844 description='Current processing status. One of `"pending"`, `"running"`, `"awaiting_callback"`, `"succeeded"`, or `"failed"`.', 845 ) 846 team: str | None = Field( 847 default=None, 848 description="ID of the team that owns this ingestion (`tem_...`). `null` if owned by a user or agent.", 849 ) 850 updated_at: datetime | None = Field( 851 default=None, description="When the ingestion record was last updated (ISO 8601)." 852 ) 853 user: str | None = Field( 854 default=None, 855 description="ID of the user that initiated this ingestion (`usr_...`). `null` if initiated by an agent.", 856 ) 857 858 859class CustomObject(BaseModel): 860 """ 861 A custom object belonging to an organization. Custom objects store arbitrary structured data defined by a schema type and are scoped to an org, team, or user. 862 """ 863 864 created_at: datetime | None = Field( 865 default=None, description="When the custom object was created (ISO 8601)." 866 ) 867 fields: dict[str, Any] | None = Field( 868 default=None, 869 description="Map of field names to their current values as defined by the object's schema type.", 870 ) 871 id: str = Field(..., description="Unique identifier for the custom object (`cobj_...`).") 872 org: str | None = Field( 873 default=None, description="ID of the organization this object belongs to (`org_...`)." 874 ) 875 row_key: str | None = Field( 876 default=None, 877 description="An optional stable key used to identify this object by a caller-controlled string rather than its generated ID. `null` if not set.", 878 ) 879 sandbox: str | None = Field( 880 default=None, 881 description="ID of the sandbox environment this object is scoped to (`dsb_...`). `null` for production objects.", 882 ) 883 schema_type: str | None = Field( 884 default=None, 885 description="The lookup key of the schema type that defines this object's field structure. `null` if the schema type has not been set.", 886 ) 887 team: str | None = Field( 888 default=None, 889 description="ID of the team that owns this object (`tem_...`). `null` if the object is not team-scoped.", 890 ) 891 updated_at: datetime | None = Field( 892 default=None, 893 description="When the custom object was last modified (ISO 8601). `null` if the object has never been updated after creation.", 894 ) 895 user: str | None = Field( 896 default=None, 897 description="ID of the user that owns this object (`usr_...`). `null` if the object is not user-scoped.", 898 ) 899 version: int | None = Field( 900 default=None, 901 description="Optimistic concurrency version of the object. Increments with each successful update; pass this value in write operations to detect conflicting changes.", 902 ) 903 904 905class CustomObjectListResponse(BaseModel): 906 """ 907 A paginated page of custom objects returned by a list operation. Use the pagination fields to navigate through result sets. 908 """ 909 910 data: list[CustomObject] = Field( 911 ..., description="Array of custom objects for the current page." 912 ) 913 has_next: bool = Field( 914 ..., 915 description="`true` if a subsequent page of results exists; `false` if this is the last page.", 916 ) 917 has_prev: bool = Field( 918 ..., 919 description="`true` if a preceding page of results exists; `false` if this is the first page.", 920 ) 921 page: int = Field(..., description="The current page number (1-indexed).") 922 page_size: int = Field(..., description="Maximum number of results returned per page.") 923 total_entries: int = Field( 924 ..., description="Total number of custom objects matching the query across all pages." 925 ) 926 total_pages: int = Field( 927 ..., description="Total number of pages available for the current query." 928 ) 929 930 931class CustomObjectUpdateFieldsResponse(BaseModel): 932 """ 933 Response returned after updating one or more fields on a custom object. Confirms the object that was modified and the field values that were applied. 934 """ 935 936 fields: dict[str, Any] = Field( 937 ..., 938 description="Map of field names to their new values as applied during the update. Only the fields that were included in the update request are present.", 939 ) 940 id: str = Field(..., description="ID of the custom object that was updated (`cobj_...`).") 941 942 943class DeviceAuthorizationResponse(BaseModel): 944 """ 945 The initial response from an OAuth 2.0 Device Authorization Grant request, containing the codes and URIs needed to complete device authentication. 946 """ 947 948 device_code: str = Field( 949 ..., 950 description="Opaque code identifying this device authorization session. Pass this value when polling the token endpoint; do not display it to the user.", 951 ) 952 expires_in: int = Field( 953 ..., 954 description="Number of seconds until the `device_code` and `user_code` expire. After expiry the user must restart the authorization flow.", 955 ) 956 interval: int = Field( 957 ..., 958 description="Minimum number of seconds to wait between polling attempts on the token endpoint. Polling more frequently will result in a `slow_down` error.", 959 ) 960 user_code: str = Field( 961 ..., 962 description="Short alphanumeric code the user must enter at `verification_uri` to authorize the device.", 963 ) 964 verification_uri: str = Field( 965 ..., 966 description="URL the user visits to enter the `user_code` and approve the authorization request.", 967 ) 968 verification_uri_complete: str = Field( 969 ..., 970 description="Full verification URL with the `user_code` pre-filled as a query parameter. Display this as a QR code or deep link to reduce manual entry.", 971 ) 972 973 974class DeviceAuthorizationStatusResponse(BaseModel): 975 """ 976 The result of a completed OAuth 2.0 Device Authorization flow, indicating whether the user approved or denied the device's access request. 977 """ 978 979 status: str = Field( 980 ..., 981 description='Outcome of the device authorization request. One of `"approved"` (the user granted access) or `"denied"` (the user rejected or cancelled the request).', 982 ) 983 984 985class AgentHealthAction(BaseModel): 986 """ 987 A single actionable item in an agent's health or setup checklist, carrying the structured data needed to render the item and deep-link to the resolution flow. 988 """ 989 990 agent: str | None = Field( 991 default=None, 992 description="ID of the agent this action is scoped to (`agt_...`). `null` for org-level actions.", 993 ) 994 app: str | None = Field( 995 default=None, 996 description="ID of the application this action is associated with (`app_...`). `null` when not app-scoped.", 997 ) 998 created_at: datetime | None = Field( 999 default=None, description="When this health action was first created (ISO 8601)." 1000 ) 1001 depends_on: list[str] | None = Field( 1002 default=None, 1003 description='IDs of other health actions that must reach `"completed"` status before this action can be started. Empty array when there are no dependencies.', 1004 ) 1005 description: str | None = Field( 1006 default=None, 1007 description="Longer Markdown-formatted explanation of what the action requires and why. `null` if not provided.", 1008 ) 1009 id: str = Field(..., description="Health action ID (`aha_...`).") 1010 kind: str = Field( 1011 ..., 1012 description='Category of action to take. One of `"env_var"` (set a secret), `"install"` (complete an agent installation, e.g. a GitHub App), `"custom"` (agent-defined step), or `"integration"` (authorize an OAuth-backed MCP server integration).', 1013 ) 1014 last_verified_at: datetime | None = Field( 1015 default=None, 1016 description="When the verifier last ran for this action (ISO 8601). `null` until the verifier has been invoked at least once.", 1017 ) 1018 last_verifier_message: str | None = Field( 1019 default=None, 1020 description="Human-readable output from the most recent verifier run. `null` if the verifier has not run yet.", 1021 ) 1022 org: str | None = Field( 1023 default=None, 1024 description="ID of the organization this action is associated with (`org_...`). `null` when not org-scoped.", 1025 ) 1026 params: dict[str, Any] | None = Field( 1027 default=None, 1028 description='Kind-specific structured data used to construct the deep-link for this action. For `"env_var"` actions includes `key` and `scope`; for `"install"` actions includes `installation_kind`; for `"integration"` actions includes `mcp_server_ref`, and when resolvable also includes `provider`, `integration_id` for OAuth handoff, and `connection_status` (`"connected"`, `"disconnected"`, or `"token_expired"`). Empty object `{}` when no additional parameters are needed.', 1029 ) 1030 required: bool = Field( 1031 ..., 1032 description="`true` if this action must be completed before the agent is considered fully operational and counts toward the blocking checklist progress bar.", 1033 ) 1034 sort_order: int = Field( 1035 ..., description="Display order within the same `source` group. Lower values appear first." 1036 ) 1037 source: str = Field( 1038 ..., 1039 description='Lifecycle stage that produced this action. One of `"setup"` (post-install checklist item) or `"health"` (probe-detected issue).', 1040 ) 1041 status: str = Field( 1042 ..., 1043 description='Current resolution state. One of `"pending"` (not yet completed), `"completed"` (resolved), `"skipped"` (dismissed by the user), or `"degraded"` (completed but the verifier is reporting a warning).', 1044 ) 1045 title: str = Field( 1046 ..., 1047 description="Short display label for this action, intended for use as a checklist item heading.", 1048 ) 1049 updated_at: datetime | None = Field( 1050 default=None, description="When this health action was last modified (ISO 8601)." 1051 ) 1052 verify_config: dict[str, Any] | None = Field( 1053 default=None, 1054 description="Configuration for the action's verifier step. Contains at minimum a `type` field that indicates which verification affordance to render. Server-internal fields are stripped before this is returned.", 1055 ) 1056 1057 1058class HealthActionListResponse(BaseModel): 1059 """ 1060 List response containing agent health actions for a given agent or organization. 1061 """ 1062 1063 data: list[AgentHealthAction] = Field( 1064 ..., 1065 description="Array of agent health action objects representing setup checklist items and probe-detected issues.", 1066 ) 1067 1068 1069class Installation(BaseModel): 1070 """ 1071 An installation representing a connection between an agent and an external service or enablement channel. Tracks configuration, lifecycle state, and any bound integration. 1072 """ 1073 1074 agent: str | None = Field( 1075 default=None, 1076 description="ID of the agent that owns this installation (`agi_...`). `null` if the installation has no agent owner.", 1077 ) 1078 config: dict[str, Any] | None = Field( 1079 default=None, 1080 description="Kind-specific configuration object for this installation. Shape depends on the `kind` value. `null` if the kind requires no configuration.", 1081 ) 1082 created_at: datetime | None = Field( 1083 default=None, description="When the installation was created (ISO 8601)." 1084 ) 1085 id: str = Field(..., description="Installation ID (`cin_...`).") 1086 kind: str | None = Field( 1087 default=None, 1088 description='Slug identifying the type of external service this installation connects to, e.g. `"enablement/github_app"` or `"integration/gmail"`. `null` if not set.', 1089 ) 1090 lookup_key: str | None = Field( 1091 default=None, 1092 description="Caller-assigned stable identifier for this installation, used to reference it in knowledge search `source_refs`. `null` if no lookup key was provided at creation time.", 1093 ) 1094 shared_integration: str | None = Field( 1095 default=None, 1096 description="ID of the shared org- or app-level integration bound to this installation (`int_...`). `null` if no integration has been bound.", 1097 ) 1098 state: str | None = Field( 1099 default=None, 1100 description='Current lifecycle state of the installation. One of `"pending"`, `"active"`, `"paused"`, or `"error"`. `"error"` indicates the installation was suspended due to a policy or compliance issue and requires attention.', 1101 ) 1102 status_payload: dict[str, Any] | None = Field( 1103 default=None, 1104 description="Provider-supplied status detail for this installation, set during activation or event processing. `null` if no status has been reported.", 1105 ) 1106 updated_at: datetime | None = Field( 1107 default=None, description="When the installation record was last updated (ISO 8601)." 1108 ) 1109 1110 1111class InstallationKind(BaseModel): 1112 """ 1113 A supported installation kind describing a category of external service or enablement channel an agent can be connected to. 1114 """ 1115 1116 accepts_sources: bool | None = Field( 1117 default=None, 1118 description="When `true`, sources can be attached to installations of this kind to supply additional context to the agent.", 1119 ) 1120 category: str | None = Field( 1121 default=None, 1122 description='Grouping category for UI display purposes, e.g. `"enablement"` or `"integration"`. `null` if uncategorized.', 1123 ) 1124 config_schema: dict[str, Any] | None = Field( 1125 default=None, 1126 description="JSON Schema object describing the shape of the `config` parameter accepted when creating or updating an installation of this kind. `null` if the kind accepts no configuration.", 1127 ) 1128 description: str | None = Field( 1129 default=None, 1130 description="Short prose description of what this kind connects to and how it is used. `null` if no description is defined.", 1131 ) 1132 kind: str = Field( 1133 ..., 1134 description='Unique slug identifying this installation kind, e.g. `"enablement/github_app"`, `"integration/gmail"`, or `"web/site"`. Pass this value as `kind` when creating an installation.', 1135 ) 1136 label: str | None = Field( 1137 default=None, 1138 description='Human-readable display name for this kind, e.g. `"GitHub App"`. `null` if the kind has no label defined.', 1139 ) 1140 provider: str | None = Field( 1141 default=None, 1142 description='Identifier of the external provider this kind connects to, e.g. `"github"` or `"slack"`. `null` for kinds with no specific provider.', 1143 ) 1144 requires_integration: bool | None = Field( 1145 default=None, 1146 description="When `true`, this kind requires an integration to be provided (either inline or via `shared_integration`) before the installation can be activated.", 1147 ) 1148 1149 1150class InstallationKindListResponse(BaseModel): 1151 """ 1152 List response containing all available installation kinds that can be used when configuring an agent installation. 1153 """ 1154 1155 data: list[InstallationKind] = Field( 1156 ..., 1157 description="Array of installation kind objects describing the available integration types and their configuration requirements.", 1158 ) 1159 1160 1161class InstallationListResponse(BaseModel): 1162 """ 1163 Paginated list response containing installation objects for an agent. 1164 """ 1165 1166 data: list[Installation] = Field( 1167 ..., description="Array of installation objects returned for the current page." 1168 ) 1169 1170 1171class InstallationSource(BaseModel): 1172 """ 1173 A source attached to an installation that supplies content for the agent's context. Sources are processed asynchronously after creation. 1174 """ 1175 1176 agent: str | None = Field( 1177 default=None, 1178 description="ID of the agent that owns this source (`agi_...`). `null` if the source is not agent-owned.", 1179 ) 1180 context_installation: str | None = Field( 1181 default=None, 1182 description="ID of the installation this source belongs to (`cin_...`). `null` if the source is not attached to an installation.", 1183 ) 1184 created_at: datetime | None = Field( 1185 default=None, description="When the source was created (ISO 8601)." 1186 ) 1187 id: str = Field(..., description="Source ID (`cso_...`).") 1188 metadata: dict[str, Any] | None = Field( 1189 default=None, 1190 description="Arbitrary key-value metadata associated with this source. Shape is caller-defined. `null` if no metadata was set.", 1191 ) 1192 parent_source: str | None = Field( 1193 default=None, 1194 description="ID of the parent source (`cso_...`) when this source was derived from another source. `null` for top-level sources.", 1195 ) 1196 payload: dict[str, Any] | None = Field( 1197 default=None, 1198 description="Type-specific payload provided when the source was created. The shape depends on the `type` value. `null` if no payload was supplied.", 1199 ) 1200 state: str | None = Field( 1201 default=None, 1202 description='Current lifecycle state of this source. One of `"active"` (ingestion running normally) or `"paused"` (ingestion suspended). Note that per-run ingestion progress is tracked separately and is not exposed on this field.', 1203 ) 1204 team: str | None = Field( 1205 default=None, 1206 description="ID of the team associated with this source (`tem_...`). `null` if the source has no team association.", 1207 ) 1208 thread: str | None = Field( 1209 default=None, 1210 description="ID of the conversation thread linked to this source (`thr_...`). `null` if the source is not thread-scoped.", 1211 ) 1212 type: str | None = Field( 1213 default=None, 1214 description='Slug identifying the kind of content this source provides, e.g. `"file/document"` or `"web/link"`. `null` if the type is not set.', 1215 ) 1216 updated_at: datetime | None = Field( 1217 default=None, description="When the source record was last updated (ISO 8601)." 1218 ) 1219 user: str | None = Field( 1220 default=None, 1221 description="ID of the user associated with this source (`usr_...`). `null` if the source has no user association.", 1222 ) 1223 1224 1225class InstallationSourceListResponse(BaseModel): 1226 """ 1227 Paginated list response containing installation source objects attached to an installation. 1228 """ 1229 1230 data: list[InstallationSource] = Field( 1231 ..., description="Array of installation source objects returned for the current page." 1232 ) 1233 1234 1235class KeyValueStorageEntry(BaseModel): 1236 """ 1237 A single key-value storage entry belonging to a user. Represents one key/value pair written to a user's isolated storage namespace within an app. 1238 """ 1239 1240 created_at: datetime | None = Field( 1241 default=None, 1242 description="When this storage entry was first created (ISO 8601). `null` if not yet persisted.", 1243 ) 1244 key: str = Field(..., description="The string key used to store and look up this entry.") 1245 updated_at: datetime | None = Field( 1246 default=None, 1247 description="When this storage entry was last updated (ISO 8601). `null` if not yet persisted.", 1248 ) 1249 user: str = Field(..., description="ID of the user who owns this storage entry (`usr_...`).") 1250 value: str = Field(..., description="The string value stored under `key` for this user.") 1251 1252 1253class KeyValueStorageEntryWithUser(BaseModel): 1254 """ 1255 A key-value storage entry enriched with owner information. Developer and server-to-server callers receive `user_email` and `user_name` populated; end-user (user-JWT) callers receive those fields as `null`. 1256 """ 1257 1258 created_at: datetime = Field( 1259 ..., description="When this storage entry was first created (ISO 8601)." 1260 ) 1261 key: str = Field(..., description="The string key used to store and look up this entry.") 1262 updated_at: datetime = Field( 1263 ..., description="When this storage entry was last updated (ISO 8601)." 1264 ) 1265 user: str = Field(..., description="ID of the user who owns this storage entry (`usr_...`).") 1266 user_email: str | None = Field( 1267 default=None, 1268 description="Email address of the owning user. `null` for end-user (user-JWT) callers; populated for developer and server-to-server callers.", 1269 ) 1270 user_name: str | None = Field( 1271 default=None, 1272 description="Display name of the owning user. `null` for end-user (user-JWT) callers; populated for developer and server-to-server callers.", 1273 ) 1274 value: str = Field(..., description="The string value stored under `key` for this user.") 1275 1276 1277class KeyValueStorageEntryPage(BaseModel): 1278 """ 1279 Paginated response envelope for the dual-mode key-value storage list endpoint. End-user (user-JWT) callers receive only `data`; developer and server-to-server callers also receive pagination metadata fields. 1280 """ 1281 1282 data: list[KeyValueStorageEntryWithUser] = Field( 1283 ..., description="Array of key-value storage entries for the current page." 1284 ) 1285 has_next: bool | None = Field( 1286 default=None, 1287 description="Whether a subsequent page exists. `false` when the current page is the last page. Present only for developer and server-to-server callers.", 1288 ) 1289 has_prev: bool | None = Field( 1290 default=None, 1291 description="Whether a preceding page exists. `false` when the current page is the first page. Present only for developer and server-to-server callers.", 1292 ) 1293 page: int | None = Field( 1294 default=None, 1295 description="Current page number (1-indexed). Present only for developer and server-to-server callers.", 1296 ) 1297 page_size: int | None = Field( 1298 default=None, 1299 description="Maximum number of results returned per page. Present only for developer and server-to-server callers.", 1300 ) 1301 total_entries: int | None = Field( 1302 default=None, 1303 description="Total number of storage entries matching the applied filters across all pages. Present only for developer and server-to-server callers.", 1304 ) 1305 total_pages: int | None = Field( 1306 default=None, 1307 description="Total number of pages available given the current `page_size`. Present only for developer and server-to-server callers.", 1308 ) 1309 1310 1311class KnowledgeSource(BaseModel): 1312 """ 1313 A knowledge source that ingests content into the knowledge base. Sources connect to external systems (e.g. Gmail, GitHub) and continuously or on-demand index items for search. 1314 """ 1315 1316 agent: str | None = Field( 1317 default=None, 1318 description="ID of the agent that owns this source (`agt_...`). `null` if owned by a human user or team.", 1319 ) 1320 context_installation: str | None = Field( 1321 default=None, 1322 description="ID of the context installation that provisioned this source (`cin_...`). `null` when the source was created directly rather than through an installation.", 1323 ) 1324 created_at: datetime | None = Field( 1325 default=None, description="When this knowledge source was created (ISO 8601)." 1326 ) 1327 id: str = Field(..., description="Knowledge source ID (`cso_...`).") 1328 metadata: dict[str, Any] | None = Field( 1329 default=None, 1330 description="Arbitrary key-value metadata attached to this source. Useful for storing caller-defined labels or references.", 1331 ) 1332 org: str | None = Field( 1333 default=None, 1334 description="ID of the organization this source belongs to (`org_...`). `null` if not scoped to an org.", 1335 ) 1336 parent_source: str | None = Field( 1337 default=None, 1338 description="ID of the parent knowledge source (`cso_...`) when this source was derived from another. `null` for top-level sources.", 1339 ) 1340 payload: dict[str, Any] | None = Field( 1341 default=None, 1342 description="Type-specific configuration object. The keys depend on the source `type`; see the create endpoint for the expected shape per type.", 1343 ) 1344 sandbox: str | None = Field( 1345 default=None, 1346 description="ID of the developer sandbox this source is scoped to (`sbx_...`). `null` outside sandbox contexts.", 1347 ) 1348 state: str = Field( 1349 ..., 1350 description='Current lifecycle state of the source. One of `"active"` (ingestion running normally) or `"paused"` (ingestion suspended).', 1351 ) 1352 team: str | None = Field( 1353 default=None, 1354 description="ID of the team that owns this source (`tea_...`). `null` if owned by a user, agent, or org.", 1355 ) 1356 thread: str | None = Field( 1357 default=None, 1358 description="ID of the chat thread this source is associated with (`thr_...`). `null` when not thread-scoped.", 1359 ) 1360 type: str = Field( 1361 ..., 1362 description='Source type identifier (e.g. `"gmail"`, `"github_activity"`). Determines the shape of `payload` and the ingestion behavior.', 1363 ) 1364 updated_at: datetime | None = Field( 1365 default=None, description="When this knowledge source was last modified (ISO 8601)." 1366 ) 1367 user: str | None = Field( 1368 default=None, 1369 description="ID of the user that owns this source (`usr_...`). `null` if owned by a team, agent, or org.", 1370 ) 1371 1372 1373class KnowledgeSourceKind(BaseModel): 1374 """ 1375 Describes a single knowledge source kind that can be created through the public API. Use the `type` value when creating a new knowledge source. 1376 """ 1377 1378 description: str | None = Field( 1379 default=None, 1380 description="Short description of what this source kind ingests and how it is used.", 1381 ) 1382 label: str | None = Field( 1383 default=None, 1384 description="Human-readable display name for this source kind, suitable for showing in a UI.", 1385 ) 1386 type: str = Field( 1387 ..., 1388 description='Machine-readable type identifier for this source kind (e.g. `"gmail"`, `"github_activity"`). Pass this value as `type` when creating a knowledge source.', 1389 ) 1390 1391 1392class KnowledgeSourceKindListResponse(BaseModel): 1393 """ 1394 List response containing the knowledge source kinds available for creation via the API. 1395 """ 1396 1397 data: list[KnowledgeSourceKind] = Field( 1398 ..., 1399 description="Array of knowledge source kind objects describing each creatable source type.", 1400 ) 1401 1402 1403class OAuthTokenResponse(BaseModel): 1404 """ 1405 A successful OAuth 2.0 token response. Issued by the token endpoint after a completed authorization or device-flow grant. 1406 """ 1407 1408 access_token: str = Field( 1409 ..., 1410 description="Bearer token used to authenticate API requests. Include this value in the `Authorization: Bearer <token>` header.", 1411 ) 1412 expires_in: int = Field(..., description="Number of seconds until the access token expires.") 1413 refresh_token: str | None = Field( 1414 default=None, 1415 description="Token that can be exchanged for a new access token once the current one expires. `null` if the grant type does not issue refresh tokens.", 1416 ) 1417 scope: str | None = Field( 1418 default=None, 1419 description="Space-separated list of scopes granted to the access token. `null` if scope was not included in the grant request.", 1420 ) 1421 token_type: str = Field(..., description='Token type. Always `"Bearer"`.') 1422 user: User | None = Field( 1423 default=None, 1424 description="The authenticated user associated with this token. `null` when the token is not tied to a specific user (e.g. client-credentials grants).", 1425 ) 1426 1427 1428class PaginatedReplies(BaseModel): 1429 """ 1430 A paginated list of reply messages for a thread. The reply array is returned directly, not nested inside a `data` wrapper. 1431 """ 1432 1433 after_cursor: str | None = Field( 1434 default=None, 1435 description="Opaque cursor to pass as the pagination cursor to retrieve the page of replies that follow this one. `null` when no further pages exist.", 1436 ) 1437 before_cursor: str | None = Field( 1438 default=None, 1439 description="Opaque cursor to pass as the pagination cursor to retrieve the page of replies that precede this one. `null` when no earlier pages exist.", 1440 ) 1441 has_more: bool | None = Field( 1442 default=None, description="Whether additional reply pages exist beyond the current page." 1443 ) 1444 replies: list[Message] = Field( 1445 ..., description="Array of reply message objects for the current page." 1446 ) 1447 total_count: int | None = Field( 1448 default=None, description="Total number of replies in the thread across all pages." 1449 ) 1450 1451 1452class RoutinePreset(BaseModel): 1453 """ 1454 A named preset that defines the execution model and constraints for a routine. Presets are shared definitions; individual routines reference a preset by name. 1455 """ 1456 1457 applicable_events: list[str] = Field( 1458 ..., 1459 description='Event types that routines using this preset may be triggered by. `["*"]` means the preset accepts any event type. Routines assigned to this preset will be rejected at creation time if their trigger event is not in this list.', 1460 ) 1461 chainable: bool = Field( 1462 ..., 1463 description="Whether routines using this preset can be composed as a step inside a chain routine. Presets with sessionable or asynchronous execution models are not chainable.", 1464 ) 1465 description: str = Field( 1466 ..., description="Human-readable description of what the preset does and when to use it." 1467 ) 1468 label: str = Field( 1469 ..., description="Human-readable display name for the preset, suitable for use in UIs." 1470 ) 1471 name: str = Field( 1472 ..., 1473 description='Stable machine identifier for the preset, e.g. `"do_task"`. Used when assigning a preset to a routine.', 1474 ) 1475 sessionable: bool = Field( 1476 ..., 1477 description="Whether routines using this preset maintain a persistent conversation session across invocations. Sessionable presets do not expose instruction or session-mode configuration on individual routines.", 1478 ) 1479 unique: bool = Field( 1480 ..., 1481 description="Whether at most one routine with this preset may exist per agent. Attempting to create a second routine with a unique preset on the same agent will be rejected.", 1482 ) 1483 1484 1485class SlackChannelBinding(BaseModel): 1486 """ 1487 A binding that connects a Slack channel to an ArchAstro team and one or more agents, enabling those agents to receive and respond to messages in that channel. 1488 """ 1489 1490 agents: list[str] | None = Field( 1491 default=None, 1492 description="IDs of the agents attached to this binding. Empty array when no agents are assigned.", 1493 ) 1494 channel: str | None = Field( 1495 default=None, description="Slack channel ID (e.g. `C01234ABCDE`) that this binding targets." 1496 ) 1497 customer_label: str | None = Field( 1498 default=None, 1499 description="Human-readable label identifying the customer, derived from the binding's embedded config. `null` when not set.", 1500 ) 1501 id: str = Field(..., description="Unique identifier for this Slack channel binding.") 1502 integration: str | None = Field( 1503 default=None, description="ID of the Slack integration that owns this binding." 1504 ) 1505 is_ext_shared_cached: bool | None = Field( 1506 default=None, 1507 description="Cached value of Slack's `is_ext_shared` flag for this channel. May be stale relative to Slack's current state.", 1508 ) 1509 team: str | None = Field( 1510 default=None, description="ID of the ArchAstro team this channel is bound to." 1511 ) 1512 1513 1514class SlackChannelBindingListResponse(BaseModel): 1515 """ 1516 Paginated list of Slack channel bindings for the requested integration or team. Use the `page` and `per_page` fields to navigate pages of results. 1517 """ 1518 1519 data: list[SlackChannelBinding] = Field( 1520 ..., description="Array of Slack channel binding objects for the current page." 1521 ) 1522 page: int = Field(..., description="Current page number (1-indexed).") 1523 per_page: int = Field(..., description="Maximum number of bindings returned per page.") 1524 total_count: int = Field( 1525 ..., 1526 description="Total number of Slack channel bindings matching the query across all pages.", 1527 ) 1528 total_pages: int = Field( 1529 ..., description="Total number of pages available at the current `per_page` size." 1530 ) 1531 1532 1533class StorageFile(BaseModel): 1534 """ 1535 A file stored in the platform's object storage, with metadata and a signed URL for downloading its contents. 1536 """ 1537 1538 content_type: str | None = Field( 1539 default=None, 1540 description='MIME type of the file, e.g. `"image/png"` or `"application/pdf"`.', 1541 ) 1542 created_at: datetime | None = Field( 1543 default=None, description="When the file was uploaded (ISO 8601)." 1544 ) 1545 filename: str | None = Field( 1546 default=None, description="Original filename as provided at upload time." 1547 ) 1548 id: str = Field(..., description="File ID (`fil_...`).") 1549 image_source: ImageSource | None = Field( 1550 default=None, 1551 description="Image display metadata. Present only when `content_type` is an image type; `null` otherwise.", 1552 ) 1553 org: str | None = Field( 1554 default=None, description="ID of the organization that owns this file (`org_...`)." 1555 ) 1556 sandbox: str | None = Field( 1557 default=None, 1558 description="ID of the sandbox this file is scoped to (`sbx_...`). `null` for files not associated with a sandbox.", 1559 ) 1560 size: int | None = Field(default=None, description="Size of the file in bytes.") 1561 updated_at: datetime | None = Field( 1562 default=None, description="When the file record was last modified (ISO 8601)." 1563 ) 1564 url: str | None = Field( 1565 default=None, 1566 description="Short-lived signed URL for downloading the file. `null` if a URL could not be generated.", 1567 ) 1568 1569 1570class ValidationResult(BaseModel): 1571 """ 1572 The result of a configuration validation check, indicating whether the config is valid and listing any errors or warnings. 1573 """ 1574 1575 errors: list[str] | None = Field( 1576 default=None, 1577 description="List of human-readable error messages describing why validation failed. Empty or absent when `valid` is `true`.", 1578 ) 1579 valid: bool = Field( 1580 ..., 1581 description="`true` if the configuration passed all validation checks, `false` if one or more errors were found.", 1582 ) 1583 warnings: list[str] | None = Field( 1584 default=None, 1585 description="List of human-readable warning messages emitted during validation. Warnings do not cause `valid` to be `false` but indicate potentially problematic configuration.", 1586 ) 1587 1588 1589class WorkingMemoryEntry(BaseModel): 1590 """ 1591 A key-value memory record stored for an agent, optionally scoped to a user. Memory entries persist across invocations and may carry an expiration time. 1592 """ 1593 1594 agent: str | None = Field( 1595 default=None, description="ID of the agent that owns this memory entry (`agt_...`)." 1596 ) 1597 created_at: datetime | None = Field( 1598 default=None, description="When this memory entry was first written (ISO 8601)." 1599 ) 1600 expires_at: datetime | None = Field( 1601 default=None, 1602 description="When this entry will be automatically deleted. `null` if the entry does not expire.", 1603 ) 1604 id: str = Field(..., description="Working memory entry ID (`amm_...`).") 1605 key: str | None = Field( 1606 default=None, 1607 description="The string key used to look up this memory entry within the agent's memory namespace.", 1608 ) 1609 updated_at: datetime | None = Field( 1610 default=None, description="When this memory entry was last modified (ISO 8601)." 1611 ) 1612 value: str | None = Field( 1613 default=None, 1614 description="The string value stored under `key`. May be any serialized content the agent wrote.", 1615 ) 1616 1617 1618class WorkingMemoryEntryListResponse(BaseModel): 1619 """ 1620 Paginated list of working memory entries stored for an agent. Includes page metadata to support sequential page traversal. 1621 """ 1622 1623 data: list[WorkingMemoryEntry] = Field( 1624 ..., description="Array of working memory entry objects for the current page." 1625 ) 1626 has_next: bool | None = Field( 1627 default=None, 1628 description="`true` if a subsequent page exists and can be fetched by incrementing the page number.", 1629 ) 1630 has_prev: bool | None = Field( 1631 default=None, 1632 description="`true` if a previous page exists and can be fetched by decrementing the page number.", 1633 ) 1634 page: int | None = Field(default=None, description="The current page number, starting at `1`.") 1635 page_size: int | None = Field( 1636 default=None, description="Maximum number of entries returned per page." 1637 ) 1638 total_entries: int | None = Field( 1639 default=None, 1640 description="Total number of working memory entries matching the query across all pages.", 1641 ) 1642 total_pages: int | None = Field( 1643 default=None, description="Total number of pages given the current `page_size`." 1644 ) 1645 1646 1647class SolutionTemplateSummary(BaseModel): 1648 """ 1649 Identity and display metadata for a single template bundled by a Solution, used to represent each wrapped or sibling template at template granularity. 1650 """ 1651 1652 description: str | None = Field( 1653 default=None, 1654 description="Short prose blurb from the template body's `description:` field. `null` when the body doesn't set one. Used as the card subhead in the Library carousel.", 1655 ) 1656 display_name: str | None = Field( 1657 default=None, 1658 description="Human-facing label from the template body's `display_name:` field. `null` when the body doesn't set one. Library carousels use this for the card title, falling back to a humanized `name`.", 1659 ) 1660 id: str | None = Field( 1661 default=None, 1662 description="Template config ID (`cfg_...`). `null` for inline-only templates.", 1663 ) 1664 kind: str = Field( 1665 ..., 1666 description="Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.", 1667 ) 1668 lookup_key: str | None = Field( 1669 default=None, 1670 description="Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", 1671 ) 1672 name: str | None = Field( 1673 default=None, 1674 description="Canonical name from the template body. For `AgentTemplate` this doubles as the human-facing label; for `AgentToolTemplate` it's the LLM-facing tool function identifier (snake_case); for `AgentRoutineTemplate` it's the routine identifier (kebab-case). Clients rendering carousels should prefer `display_name` and fall back to humanizing `name`.", 1675 ) 1676 readme_url: str | None = Field( 1677 default=None, 1678 description="Relative path to the public README endpoint with a signed token already embedded, scoped to this template's bundled markdown asset. `null` when the Solution body's `templates[].readme_path` is unset for this entry. Token expires in 1 hour refresh via `GET /api/v1/solutions/:solution`.", 1679 ) 1680 virtual_path: str | None = Field( 1681 default=None, 1682 description="Stable virtual path assigned to the template config. `null` when no virtual path was set.", 1683 ) 1684 1685 1686class SolutionSummary(BaseModel): 1687 """ 1688 A catalog entry for an imported Solution, including its display metadata, bundled templates, owner scopes, and any available upgrade information. 1689 """ 1690 1691 category_keys: list[str] | None = Field( 1692 default=None, 1693 description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", 1694 ) 1695 created_at: datetime | None = Field( 1696 default=None, description="When the Solution config was first imported (ISO 8601)." 1697 ) 1698 description: str | None = Field( 1699 default=None, 1700 description="Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. `null` when the Solution body does not set one.", 1701 ) 1702 id: str = Field(..., description="Solution config ID (`cfg_...`).") 1703 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 1704 latest_solution: str | None = Field( 1705 default=None, 1706 description="When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", 1707 ) 1708 latest_version: str | None = Field( 1709 default=None, 1710 description="When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", 1711 ) 1712 lookup_key: str | None = Field( 1713 default=None, 1714 description="The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", 1715 ) 1716 metadata: dict[str, Any] | None = Field( 1717 default=None, 1718 description="Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none.", 1719 ) 1720 name: str | None = Field( 1721 default=None, 1722 description="Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", 1723 ) 1724 org: str | None = Field( 1725 default=None, 1726 description="Organization ID (`org_...`) that owns this Solution config, when the Solution is scoped to a specific org. `null` for system-scope (app-level) Solutions.", 1727 ) 1728 org_logo: ImageSource | None = Field( 1729 default=None, 1730 description="Canonical image-source object for the resolved `org`'s logo, used as the principal category section glyph. Carries the signed `url` plus a `refresh_url`. `null` when `org_slug` is `null` or the org has no logo.", 1731 ) 1732 org_name: str | None = Field( 1733 default=None, 1734 description="Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", 1735 ) 1736 org_slug: str | None = Field( 1737 default=None, 1738 description="Resolved slug of the Solution body's `org` (the publishing organization), when set and it resolves to a real org visible to the viewer. When present this is the Solution's principal catalog category key clients group the Solution under this org ahead of `category_keys`. `null` when the body has no `org` or it doesn't resolve.", 1739 ) 1740 owners: list[str] = Field( 1741 ..., 1742 description='Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer\'s org scope).', 1743 ) 1744 readme_url: str | None = Field( 1745 default=None, 1746 description="Relative path to the public README endpoint with a signed token already embedded. `null` when the Solution has no README. Token expires in 1 hour refresh via `GET /api/v1/solutions/:solution`.", 1747 ) 1748 solution_id: str | None = Field( 1749 default=None, 1750 description="Stable UUID declared in the Solution body, used to identify the same logical Solution across multiple installed copies and owner scopes. `null` when the body omits it.", 1751 ) 1752 solution_version: str | None = Field( 1753 default=None, 1754 description='Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.', 1755 ) 1756 tag_keys: list[str] | None = Field( 1757 default=None, 1758 description="Freeform tag keys declared in the Solution body. An empty array when the body declares none.", 1759 ) 1760 template_kind: str | None = Field( 1761 default=None, 1762 description='Wrapped template kind `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.', 1763 ) 1764 templates: list[SolutionTemplateSummary] = Field( 1765 ..., 1766 description="Template configs bundled by this Solution, in declaration order the first entry is the deployable template the Solution wraps; the rest are sibling templates the wrapped template references.", 1767 ) 1768 updated_at: datetime | None = Field( 1769 default=None, description="When the Solution config was last modified (ISO 8601)." 1770 ) 1771 upgrade_available: bool = Field( 1772 ..., 1773 description="`true` when this Solution is installed at the viewer's org scope and the app-level system scope carries a higher `solution_version`. Always `false` for system-only rows.", 1774 ) 1775 virtual_path: str | None = Field( 1776 default=None, 1777 description="The stable virtual path assigned to this Solution config, used as the deduplication key when the same Solution appears under multiple owner scopes. `null` when unset.", 1778 ) 1779 1780 1781class AgentSourceSolution(BaseModel): 1782 """ 1783 Summary of the Solution and AgentTemplate that an agent was last provisioned from. 1784 Returned on single-agent responses; `null` for hand-built agents and agents whose tracked template or parent Solution has been deleted. 1785 """ 1786 1787 solution: SolutionSummary = Field( 1788 ..., 1789 description="Summary of the parent Solution, including `upgrade_available`, `latest_version`, and `latest_solution` when a newer system-scoped version is available for the agent's org-scoped Solution.", 1790 ) 1791 template: UpgradeTemplateSummary = Field( 1792 ..., 1793 description="Summary of the AgentTemplate config (`cfg_...`) the agent was last provisioned or updated from.", 1794 ) 1795 1796 1797class Agent(BaseModel): 1798 """ 1799 An AI agent that can be configured with tools, routines, and skills, and invoked to handle conversations or tasks. 1800 """ 1801 1802 acl: Acl | None = Field( 1803 default=None, 1804 description="Access control list for the agent. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied and the agent is accessible to all members of its scope.", 1805 ) 1806 app: str | None = Field( 1807 default=None, description="ID of the application that owns this agent (`dap_...`)." 1808 ) 1809 created_at: datetime | None = Field( 1810 default=None, description="When the agent was created (ISO 8601)." 1811 ) 1812 default_model: str | None = Field( 1813 default=None, 1814 description='Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `"claude-3-7-sonnet-latest"`).', 1815 ) 1816 email: str | None = Field( 1817 default=None, 1818 description="Email address provisioned for this agent. `null` if email delivery is not configured.", 1819 ) 1820 id: str = Field(..., description="Agent ID (`agi_...`).") 1821 identity: str | None = Field( 1822 default=None, 1823 description="System-level identity prompt that shapes the agent's persona and behavior.", 1824 ) 1825 last_applied_template_config: str | None = Field( 1826 default=None, 1827 description="ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", 1828 ) 1829 lookup_key: str | None = Field( 1830 default=None, 1831 description="Stable, user-defined identifier for this agent within the application. Unique per app.", 1832 ) 1833 metadata: dict[str, Any] | None = Field( 1834 default=None, 1835 description="Arbitrary key-value metadata attached to the agent. Not interpreted by the platform.", 1836 ) 1837 name: str | None = Field( 1838 default=None, description="Human-readable display name for the agent. `null` if not set." 1839 ) 1840 org: str | None = Field( 1841 default=None, 1842 description="ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", 1843 ) 1844 org_name: str | None = Field( 1845 default=None, 1846 description="Display name of the organization this agent belongs to. `null` when the agent is not org-scoped or when the org association was not preloaded.", 1847 ) 1848 originator: str | None = Field( 1849 default=None, 1850 description="Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", 1851 ) 1852 phone_number: str | None = Field( 1853 default=None, 1854 description="Phone number provisioned for this agent. `null` if SMS is not configured.", 1855 ) 1856 sandbox: str | None = Field( 1857 default=None, 1858 description="ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", 1859 ) 1860 source_solution: AgentSourceSolution | None = Field( 1861 default=None, 1862 description="Source Solution and AgentTemplate summary for agents provisioned from a Solution. Includes `upgrade_available`, `latest_version`, and `latest_solution` so you can render an upgrade badge without a separate dry-run call. `null` for hand-built agents and agents whose tracked template or parent Solution has been deleted. Populated only on single-agent GET responses, never on list endpoints.", 1863 ) 1864 team: str | None = Field( 1865 default=None, 1866 description="ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", 1867 ) 1868 template_upgrade_available: bool | None = Field( 1869 default=None, 1870 description="True when the agent's last-applied template version is behind the current version of its AgentTemplate config i.e. reapplying the template (a per-agent upgrade) would bring it newer Solution content. Self-clears once the agent is reapplied. Computed only on list endpoints; `null` on single-agent GET.", 1871 ) 1872 updated_at: datetime | None = Field( 1873 default=None, description="When the agent was last modified (ISO 8601)." 1874 ) 1875 user: str | None = Field( 1876 default=None, 1877 description="ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", 1878 ) 1879 1880 1881class AgentComputer(BaseModel): 1882 """ 1883 A cloud computer resource provisioned for an agent to use for browser and desktop automation tasks. 1884 """ 1885 1886 agent: str | None = Field( 1887 default=None, 1888 description="ID of the agent that owns this computer (`agi_...`). `null` if the computer is not yet assigned to an agent.", 1889 ) 1890 app: str | None = Field( 1891 default=None, description="ID of the app this computer belongs to (`dap_...`)." 1892 ) 1893 config: dict[str, Any] | None = Field( 1894 default=None, 1895 description="Provider-specific configuration key-value pairs for the computer. Structure depends on the underlying compute provider.", 1896 ) 1897 created_at: datetime | None = Field( 1898 default=None, description="When the computer was created (ISO 8601)." 1899 ) 1900 error_message: str | None = Field( 1901 default=None, 1902 description='Human-readable error description when `status` is `"error"`. `null` otherwise.', 1903 ) 1904 id: str = Field(..., description="Computer ID (`cmp_...`).") 1905 last_active_at: datetime | None = Field( 1906 default=None, 1907 description="When the computer last reported activity or received a command. `null` if the computer has never been active.", 1908 ) 1909 lookup_key: str | None = Field( 1910 default=None, 1911 description="Unique, stable identifier you assign to this computer within its app. `null` if not set.", 1912 ) 1913 metadata: dict[str, Any] | None = Field( 1914 default=None, 1915 description="Arbitrary key-value metadata you attached to the computer. `null` if none was provided.", 1916 ) 1917 name: str | None = Field( 1918 default=None, description="Human-readable display name for the computer. `null` if not set." 1919 ) 1920 provider: str | None = Field( 1921 default=None, 1922 description='Compute backend powering this computer: `"sprites"` (Fly Sprites) or `"vercel"` (Vercel Sandbox).', 1923 ) 1924 region: str | None = Field( 1925 default=None, 1926 description='Cloud region where the computer is hosted, e.g. `"us-east-1"`. `null` if not yet assigned or when the provider has no region concept (e.g. `"vercel"`).', 1927 ) 1928 sprite_url: str | None = Field( 1929 default=None, 1930 description="URL of the live screenshot sprite used to render a real-time preview of the computer's screen. `null` when no sprite is available.", 1931 ) 1932 status: str | None = Field( 1933 default=None, 1934 description='Current lifecycle state of the computer. Common values include `"provisioning"`, `"ready"`, `"error"`, and `"terminated"`.', 1935 ) 1936 updated_at: datetime | None = Field( 1937 default=None, description="When the computer record was last modified (ISO 8601)." 1938 ) 1939 1940 1941class AgentComputerListResponse(BaseModel): 1942 """ 1943 A list of agent computers returned by a list query. 1944 """ 1945 1946 data: list[AgentComputer] = Field( 1947 ..., description="Array of agent computer objects matching the query." 1948 ) 1949 1950 1951class AgentCreateResponse(BaseModel): 1952 """ 1953 The response returned by `POST /api/v1/agents`. Contains all agent fields plus an optional `installed_configs` array when a `template_bundle` was supplied in the request. 1954 """ 1955 1956 acl: Acl | None = Field( 1957 default=None, 1958 description="Access control list governing who can interact with this agent. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied.", 1959 ) 1960 app: str | None = Field( 1961 default=None, description="ID of the app this agent belongs to (`dap_...`)." 1962 ) 1963 created_at: datetime | None = Field( 1964 default=None, description="When the agent was created (ISO 8601)." 1965 ) 1966 default_model: str | None = Field( 1967 default=None, 1968 description='Default AI model the agent uses when no model is specified at runtime, e.g. `"claude-3-5-sonnet-20241022"`. `null` if not configured.', 1969 ) 1970 email: str | None = Field( 1971 default=None, 1972 description="Email address assigned to this agent for inbound email handling. `null` if not configured.", 1973 ) 1974 id: str = Field(..., description="Agent ID (`agi_...`).") 1975 identity: str | None = Field( 1976 default=None, 1977 description="System prompt or persona description that shapes the agent's behavior. `null` if not set.", 1978 ) 1979 installed_configs: list[InstalledConfigEntry] | None = Field( 1980 default=None, 1981 description="List of config records created as part of this request's `template_bundle` install. One entry per persisted config, sorted by `key`. Omitted entirely when the request did not include a `template_bundle`.", 1982 ) 1983 lookup_key: str | None = Field( 1984 default=None, 1985 description="Unique, stable identifier for the agent within its app. `null` if not set.", 1986 ) 1987 metadata: dict[str, Any] | None = Field( 1988 default=None, 1989 description="Arbitrary key-value metadata attached to the agent. `null` if none was provided.", 1990 ) 1991 name: str | None = Field( 1992 default=None, description="Human-readable display name for the agent. `null` if not set." 1993 ) 1994 org: str | None = Field( 1995 default=None, 1996 description="ID of the organization this agent belongs to (`org_...`). `null` for agents outside an org.", 1997 ) 1998 originator: str | None = Field( 1999 default=None, 2000 description="Free-form label identifying the source or author of the agent, e.g. a username or service name. `null` if not set.", 2001 ) 2002 phone_number: str | None = Field( 2003 default=None, 2004 description="Phone number assigned to this agent for inbound SMS or voice handling. `null` if not configured.", 2005 ) 2006 sandbox: str | None = Field( 2007 default=None, 2008 description="ID of the sandbox environment this agent is scoped to (`sbx_...`). `null` for agents not scoped to a sandbox.", 2009 ) 2010 team: str | None = Field( 2011 default=None, 2012 description="ID of the team that owns this agent (`tea_...`). `null` if owned by a user rather than a team.", 2013 ) 2014 updated_at: datetime | None = Field( 2015 default=None, description="When the agent record was last modified (ISO 8601)." 2016 ) 2017 user: str | None = Field( 2018 default=None, 2019 description="ID of the user that owns this agent (`usr_...`). `null` if owned by a team.", 2020 ) 2021 2022 2023class AgentEnvVarMasked(BaseModel): 2024 """ 2025 An agent environment variable with its secret value masked for safe display in list and show responses. 2026 """ 2027 2028 agent: str = Field( 2029 ..., description="ID of the agent this environment variable belongs to (`agt_...`)." 2030 ) 2031 created_at: datetime | None = Field( 2032 default=None, description="When the environment variable was created (ISO 8601)." 2033 ) 2034 description: str | None = Field( 2035 default=None, 2036 description="Optional human-readable note describing the purpose of this variable. `null` if not set.", 2037 ) 2038 id: str = Field(..., description="Environment variable ID (`anv_...`).") 2039 key: str = Field( 2040 ..., description="Name of the environment variable as it appears in the agent's runtime." 2041 ) 2042 masked_value: str = Field( 2043 ..., 2044 description="Redacted representation of the secret value. The last four characters are preserved; all preceding characters are replaced with `****`. Returns `****` when the value is absent or four characters or fewer.", 2045 ) 2046 updated_at: datetime | None = Field( 2047 default=None, description="When the environment variable was last updated (ISO 8601)." 2048 ) 2049 2050 2051class AgentEnvVarMaskedList(BaseModel): 2052 """ 2053 Flat list of masked environment variables belonging to an agent. 2054 """ 2055 2056 data: list[AgentEnvVarMasked] = Field( 2057 ..., description="Array of masked environment variable objects for the agent." 2058 ) 2059 2060 2061class AgentExport(BaseModel): 2062 """ 2063 A portable export bundle for an agent, containing everything needed to re-deploy it in another workspace or environment. 2064 """ 2065 2066 configs: list[Config] = Field( 2067 ..., 2068 description="Ordered list of config file objects that the agent depends on. Included in full so the import can recreate all dependencies without additional requests.", 2069 ) 2070 template: dict[str, Any] = Field( 2071 ..., 2072 description="The agent template definition as a structured map. Pass this directly to the import endpoint to recreate the agent.", 2073 ) 2074 2075 2076class AgentHealth(BaseModel): 2077 """ 2078 Aggregate health profile for an agent, summarizing its current operational status, score, and the full list of setup and health actions. 2079 """ 2080 2081 activity: dict[str, Any] = Field( 2082 ..., 2083 description="Timestamps for the agent's most recent and next scheduled activity, used to surface last-run and upcoming-run information.", 2084 ) 2085 agent: Agent = Field(..., description="The agent this health profile describes.") 2086 checked_at: datetime = Field( 2087 ..., description="When the health profile was last computed (ISO 8601)." 2088 ) 2089 checks: list[dict[str, Any]] = Field( 2090 ..., 2091 description="Renderable health check results. Each object includes at minimum `key`, `label`, `status`, and `summary` fields.", 2092 ) 2093 counts: dict[str, Any] = Field( 2094 ..., 2095 description="Action counts broken down by dependency area and resolution status, used to render progress indicators per category.", 2096 ) 2097 health_actions: list[AgentHealthAction] = Field( 2098 ..., 2099 description='All actionable items tracked for this agent, including both `"setup"` items (post-install checklist) and `"health"` items (probe-detected issues). Sorted by `(source, sort_order, id)`. Use each item\'s `params` field to construct deep-links that route the user to the correct resolution flow.', 2100 ) 2101 recent: dict[str, Any] = Field( 2102 ..., 2103 description="Recent execution metrics for the agent, including run counts and failure counts over a recent time window.", 2104 ) 2105 score: int = Field( 2106 ..., 2107 description="Normalized health score from `0` (fully degraded) to `100` (fully healthy), derived from the weight and status of all health actions.", 2108 ) 2109 status: str = Field( 2110 ..., 2111 description='Overall health status of the agent. One of `"ok"`, `"warning"`, or `"critical"`.', 2112 ) 2113 2114 2115class AgentListResponse(BaseModel): 2116 """ 2117 Paginated list of agent objects. Use the pagination fields to traverse multiple pages of results. 2118 """ 2119 2120 data: list[Agent] = Field(..., description="Array of agent objects for the current page.") 2121 has_next: bool | None = Field( 2122 default=None, description="`true` when a subsequent page of results exists." 2123 ) 2124 has_prev: bool | None = Field( 2125 default=None, description="`true` when a previous page of results exists." 2126 ) 2127 page: int | None = Field(default=None, description="Current page number, starting at 1.") 2128 page_size: int | None = Field( 2129 default=None, description="Maximum number of agents returned per page." 2130 ) 2131 total_entries: int | None = Field( 2132 default=None, description="Total number of agents matching the query across all pages." 2133 ) 2134 total_pages: int | None = Field( 2135 default=None, description="Total number of pages available given the current `page_size`." 2136 ) 2137 2138 2139class AgentRoutine(BaseModel): 2140 """ 2141 An agent routine defines a reusable handler script, preset, or chain that runs in response to events or on a schedule. 2142 """ 2143 2144 acl: Acl | None = Field( 2145 default=None, 2146 description="Access control list for the routine. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied and the routine is accessible to all members of its scope.", 2147 ) 2148 agent: str | None = Field( 2149 default=None, description="ID of the agent that owns this routine (`agi_...`)." 2150 ) 2151 app: str | None = Field( 2152 default=None, description="Application that scopes this routine (`dap_...`)." 2153 ) 2154 config: str | None = Field( 2155 default=None, 2156 description="ID of the Config record that backs this routine's configuration (`cfg_...`). `null` when the routine is not config-backed.", 2157 ) 2158 created_at: datetime | None = Field( 2159 default=None, description="When this routine was created (ISO 8601)." 2160 ) 2161 description: str | None = Field( 2162 default=None, 2163 description="Optional description of what this routine does. `null` when not set.", 2164 ) 2165 event_config: dict[str, Any] | None = Field( 2166 default=None, 2167 description="Additional configuration controlling how the event trigger is matched or filtered. Shape depends on `event_type`. `null` when not configured.", 2168 ) 2169 event_type: str | None = Field( 2170 default=None, 2171 description='Platform event type that triggers this routine, e.g. `"agentroutine.invoked"`. `null` for schedule-only routines.', 2172 ) 2173 handler_type: str | None = Field( 2174 default=None, 2175 description='Execution strategy for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`.', 2176 ) 2177 id: str = Field(..., description="Routine ID (`arn_...`).") 2178 last_applied_template_config: str | None = Field( 2179 default=None, 2180 description="ID of the AgentRoutineTemplate Config this routine was last provisioned or updated from (`cfg_...`). `null` for hand-built routines.", 2181 ) 2182 lookup_key: str | None = Field( 2183 default=None, 2184 description="Unique human-readable key used to look up this routine without knowing its ID. `null` when not set.", 2185 ) 2186 metadata: dict[str, Any] | None = Field( 2187 default=None, 2188 description="Arbitrary key-value metadata attached to this routine. `null` when not set.", 2189 ) 2190 name: str | None = Field(default=None, description="Human-readable name for the routine.") 2191 preset_config: PresetConfig | None = Field( 2192 default=None, 2193 description='Resolved preset configuration when `handler_type` is `"preset"`. `null` for other handler types.', 2194 ) 2195 preset_name: str | None = Field( 2196 default=None, 2197 description='Name of the preset invoked when `handler_type` is `"preset"`. `null` for other handler types.', 2198 ) 2199 schedule: str | None = Field( 2200 default=None, 2201 description="Cron expression controlling when the routine fires on a schedule. `null` for event-only routines.", 2202 ) 2203 script: str | None = Field( 2204 default=None, 2205 description='Inline script body executed when `handler_type` is `"script"`. `null` for other handler types.', 2206 ) 2207 status: str | None = Field( 2208 default=None, 2209 description='Lifecycle status of the routine. One of `"draft"`, `"active"`, or `"paused"`. Only `"active"` routines respond to triggers.', 2210 ) 2211 steps: list[dict[str, Any]] | None = Field( 2212 default=None, 2213 description='Ordered list of chain steps (present when handler_type is "chain"). Each step is a plain map with handler_type, optional body fields (preset_name / preset_config / script / config), and step-local plumbing (name, inputs, output_key, on_error).', 2214 ) 2215 trigger_context: str | None = Field( 2216 default=None, 2217 description='Execution context in which runs are created. One of `"event"` (background job) or `"chat_session"` (interactive session). Defaults to `"event"`.', 2218 ) 2219 updated_at: datetime | None = Field( 2220 default=None, description="When this routine was last updated (ISO 8601)." 2221 ) 2222 2223 2224class AgentRoutineListResponse(BaseModel): 2225 """ 2226 List of agent routine objects belonging to a given agent. 2227 """ 2228 2229 data: list[AgentRoutine] = Field(..., description="Array of agent routine objects.") 2230 2231 2232class AgentRoutineRun(BaseModel): 2233 """ 2234 A single execution of an agent routine, capturing its status, inputs, outputs, and timing. 2235 """ 2236 2237 acl: Acl | None = Field( 2238 default=None, 2239 description="Access control list for the run. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied and the run is accessible to all members of its scope.", 2240 ) 2241 agent: str | None = Field( 2242 default=None, description="ID of the agent that owns the parent routine (`agi_...`)." 2243 ) 2244 app: str | None = Field( 2245 default=None, description="Application that scopes this run (`dap_...`)." 2246 ) 2247 created_at: datetime | None = Field( 2248 default=None, description="When this run was created (ISO 8601)." 2249 ) 2250 duration_ms: int | None = Field( 2251 default=None, 2252 description="Total wall-clock time the run took to execute, in milliseconds. `null` while the run is still in progress.", 2253 ) 2254 event_id: str | None = Field( 2255 default=None, 2256 description="Identifier of the platform event that triggered this run. `null` for manually invoked runs.", 2257 ) 2258 id: str = Field(..., description="Routine run ID (`arr_...`).") 2259 metadata: dict[str, Any] | None = Field( 2260 default=None, 2261 description="Arbitrary key-value metadata attached to this run. Empty object when no metadata was set.", 2262 ) 2263 payload: dict[str, Any] | None = Field( 2264 default=None, 2265 description="Input payload delivered to the routine when this run was triggered. Empty object when no payload was provided.", 2266 ) 2267 result: dict[str, Any] | None = Field( 2268 default=None, 2269 description="Output produced by the routine after execution. `null` while the run has not yet completed.", 2270 ) 2271 routine: str | None = Field( 2272 default=None, description="ID of the parent routine that produced this run (`arn_...`)." 2273 ) 2274 status: str | None = Field( 2275 default=None, 2276 description='Current execution status. One of `"pending"`, `"running"`, `"completed"`, `"failed"`, `"skipped"`, or `"cancelled"`.', 2277 ) 2278 structured_response: dict[str, Any] | None = Field( 2279 default=None, 2280 description="Validated structured output extracted from `result` when the routine uses an AgentMessageSchema. `null` if the routine does not use a schema or the run has not completed.", 2281 ) 2282 updated_at: datetime | None = Field( 2283 default=None, description="When this run was last updated (ISO 8601)." 2284 ) 2285 worker: WorkerStatus | None = Field( 2286 default=None, 2287 description="Background worker status. `null` when no worker job is associated with this run.", 2288 ) 2289 2290 2291class AgentRoutineRunListResponse(BaseModel): 2292 """ 2293 Cursor-paginated list of agent routine run objects, ordered by creation time descending. 2294 """ 2295 2296 after_cursor: str | None = Field( 2297 default=None, 2298 description="Opaque cursor to pass as the after-cursor parameter to fetch the next page of runs. `null` when no later results exist.", 2299 ) 2300 before_cursor: str | None = Field( 2301 default=None, 2302 description="Opaque cursor to pass as the before-cursor parameter to fetch the page of runs that precede this one. `null` when no earlier results exist.", 2303 ) 2304 data: list[AgentRoutineRun] = Field( 2305 ..., description="Array of agent routine run objects for the current page." 2306 ) 2307 2308 2309class AgentSchedule(BaseModel): 2310 """ 2311 A scheduled task created by an agent. Supports one-time and recurring (cron-based) execution patterns. 2312 """ 2313 2314 agent: str | None = Field( 2315 default=None, description="ID of the agent that owns this schedule (`agi_...`)." 2316 ) 2317 app: str | None = Field( 2318 default=None, description="ID of the application the schedule belongs to (`dap_...`)." 2319 ) 2320 created_at: datetime | None = Field( 2321 default=None, description="When the schedule was created (ISO 8601)." 2322 ) 2323 cron_expression: str | None = Field( 2324 default=None, 2325 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.', 2326 ) 2327 id: str = Field(..., description="Schedule ID (`asc_...`).") 2328 instructions: str | None = Field( 2329 default=None, 2330 description="The task description the agent will execute when this schedule fires.", 2331 ) 2332 last_run_at: datetime | None = Field( 2333 default=None, 2334 description="UTC datetime of the most recent successful execution. `null` if the schedule has never run.", 2335 ) 2336 max_runs: int | None = Field( 2337 default=None, 2338 description='Maximum number of times a recurring schedule may fire before automatically transitioning to `"completed"`. `null` means no limit.', 2339 ) 2340 metadata: dict[str, Any] | None = Field( 2341 default=None, 2342 description="Arbitrary key-value pairs attached to the schedule by the agent. Not interpreted by the platform.", 2343 ) 2344 next_run_at: datetime | None = Field( 2345 default=None, 2346 description="UTC datetime of the next planned execution. `null` if the schedule has completed, been cancelled, or has not yet been computed.", 2347 ) 2348 run_count: int | None = Field( 2349 default=None, description="Total number of times this schedule has fired." 2350 ) 2351 schedule_type: str | None = Field( 2352 default=None, 2353 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.', 2354 ) 2355 scheduled_at: datetime | None = Field( 2356 default=None, 2357 description='The exact UTC datetime at which a one-time schedule fires. Present only when `schedule_type` is `"once"`. `null` for recurring schedules.', 2358 ) 2359 status: str | None = Field( 2360 default=None, 2361 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).', 2362 ) 2363 thread: str | None = Field( 2364 default=None, 2365 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.", 2366 ) 2367 timezone: str | None = Field( 2368 default=None, 2369 description='IANA timezone name used to interpret the cron expression or `scheduled_at` (e.g. `"America/New_York"`). Defaults to `"Etc/UTC"`.', 2370 ) 2371 updated_at: datetime | None = Field( 2372 default=None, description="When the schedule was last modified (ISO 8601)." 2373 ) 2374 2375 2376class AgentSession(BaseModel): 2377 """ 2378 A durable agent session record representing a single AI task execution. Tracks status, trajectory, result, and any inbox messages delivered to the session. 2379 """ 2380 2381 agent: str | None = Field( 2382 default=None, description="ID of the agent that owns this session (`agi_...`)." 2383 ) 2384 completed_at: datetime | None = Field( 2385 default=None, 2386 description='When the session reached a terminal state (`"completed"`, `"failed"`, or `"cancelled"`). `null` if still in progress.', 2387 ) 2388 created_at: datetime | None = Field( 2389 default=None, description="When the session was created (ISO 8601)." 2390 ) 2391 error: str | None = Field( 2392 default=None, 2393 description='Human-readable error message describing why the session failed. `null` unless `status` is `"failed"`.', 2394 ) 2395 id: str = Field(..., description="Session ID (`ase_...`).") 2396 inbox: list[dict[str, Any]] | None = Field( 2397 default=None, 2398 description='Ordered list of messages delivered to the session\'s inbox while it was in the `"waiting"` state. Each entry includes `id`, `role`, `content`, `sender_id`, `sender_type`, `sent_at`, and `metadata`.', 2399 ) 2400 instructions: str | None = Field( 2401 default=None, description="The task the agent is instructed to perform in this session." 2402 ) 2403 is_system_session: bool | None = Field( 2404 default=None, 2405 description="`true` if this session was created by the platform internally (e.g. by a schedule or health action) rather than by a user or API caller.", 2406 ) 2407 max_runs_per_turn: int | None = Field( 2408 default=None, 2409 description="Maximum number of tool calls the agent may make within a single turn. Defaults to `25`.", 2410 ) 2411 max_tokens: int | None = Field( 2412 default=None, 2413 description="Maximum number of tokens the session may consume across all turns before being terminated. Defaults to `20000`.", 2414 ) 2415 max_turns: int | None = Field( 2416 default=None, 2417 description="Maximum number of agent turns (LLM calls) allowed before the session is forcibly terminated. Defaults to `100`.", 2418 ) 2419 metadata: dict[str, Any] | None = Field( 2420 default=None, 2421 description="Arbitrary key-value pairs attached to the session. Not interpreted by the platform.", 2422 ) 2423 name: str | None = Field( 2424 default=None, 2425 description="Optional human-readable label for the session. `null` when not set.", 2426 ) 2427 result: dict[str, Any] | None = Field( 2428 default=None, 2429 description="Structured output produced by the session on successful completion. Shape is agent-defined. `null` while the session is still running or if it failed.", 2430 ) 2431 started_at: datetime | None = Field( 2432 default=None, description='When the session began executing. `null` if still `"pending"`.' 2433 ) 2434 status: str | None = Field( 2435 default=None, 2436 description='Current execution status. One of `"pending"` (queued, not yet started), `"running"` (actively executing), `"waiting"` (paused for an inbox message or external event), `"completed"` (finished successfully), `"failed"` (terminated with an error), or `"cancelled"` (manually stopped).', 2437 ) 2438 trajectory: str | None = Field( 2439 default=None, 2440 description="ID of the trajectory that records the full message history for this session (`trj_...`). `null` until the session has started.", 2441 ) 2442 2443 2444class AgentSessionListResponse(BaseModel): 2445 """ 2446 Paginated list response containing an array of agent session objects. 2447 """ 2448 2449 data: list[AgentSession] = Field( 2450 ..., description="Array of agent session objects for the current page." 2451 ) 2452 2453 2454class AgentSkill(BaseModel): 2455 """ 2456 A skill enabled on an agent, linking the agent to a skill configuration. Controls which capabilities the agent has access to. 2457 """ 2458 2459 agent: str | None = Field( 2460 default=None, description="ID of the agent this skill is attached to (`agi_...`)." 2461 ) 2462 app: str | None = Field( 2463 default=None, description="ID of the application this skill belongs to (`dap_...`)." 2464 ) 2465 config: str | None = Field( 2466 default=None, 2467 description="ID of the root skill config record that defines this skill's behavior (`cfg_...`).", 2468 ) 2469 created_at: datetime | None = Field( 2470 default=None, description="When the skill was added to the agent (ISO 8601)." 2471 ) 2472 id: str = Field(..., description="Skill ID (`ask_...`).") 2473 instruction: str | None = Field( 2474 default=None, 2475 description="Optional instruction text that overrides the default skill instructions for this specific agent. `null` when no override is set.", 2476 ) 2477 last_applied_template_config: str | None = Field( 2478 default=None, 2479 description="ID of the agent template config from which this skill was last provisioned or updated (`cfg_...`). `null` if the skill was not provisioned from a template.", 2480 ) 2481 metadata: dict[str, Any] | None = Field( 2482 default=None, 2483 description="Arbitrary key-value pairs attached to the skill. Not interpreted by the platform.", 2484 ) 2485 status: str | None = Field( 2486 default=None, 2487 description='Whether the skill is currently in use. `"active"` means the agent will use this skill during sessions. `"inactive"` means it is disabled but not deleted.', 2488 ) 2489 updated_at: datetime | None = Field( 2490 default=None, description="When the skill was last modified (ISO 8601)." 2491 ) 2492 2493 2494class AgentSkillList(BaseModel): 2495 """ 2496 Paginated list response containing an array of agent skill objects. 2497 """ 2498 2499 data: list[AgentSkill] = Field( 2500 ..., description="Array of agent skill objects for the current page." 2501 ) 2502 2503 2504class AgentTool(BaseModel): 2505 """ 2506 A tool attached to an agent, defining a capability the agent can invoke during a conversation or task run. 2507 """ 2508 2509 model_config = ConfigDict(populate_by_name=True) 2510 2511 agent: str | None = Field( 2512 default=None, description="ID of the agent this tool belongs to (`agi_...`)." 2513 ) 2514 app: str | None = Field( 2515 default=None, description="ID of the application that owns this tool (`dap_...`)." 2516 ) 2517 async_: bool | None = Field( 2518 default=None, 2519 alias="async", 2520 description="`true` when the tool executes asynchronously and returns a task handle rather than an immediate result.", 2521 ) 2522 builtin_tool_config: dict[str, Any] | None = Field( 2523 default=None, 2524 description='Provider-specific configuration for the built-in tool. Present only when `kind` is `"builtin"`. Shape varies by `builtin_tool_key`.', 2525 ) 2526 builtin_tool_key: str | None = Field( 2527 default=None, 2528 description='Registry key identifying the built-in tool implementation. Present only when `kind` is `"builtin"`.', 2529 ) 2530 config: str | None = Field( 2531 default=None, 2532 description="ID of the config record (`cfg_...`) containing this tool's full configuration. `null` for inline-only tools.", 2533 ) 2534 created_at: datetime | None = Field( 2535 default=None, description="When the tool was created (ISO 8601)." 2536 ) 2537 description: str | None = Field( 2538 default=None, 2539 description='Description of what the tool does, passed to the LLM as part of the tool definition. Resolved from the built-in registry for `kind: "builtin"` tools.', 2540 ) 2541 handler_type: str | None = Field( 2542 default=None, 2543 description='Execution handler type. One of `"http"`, `"script"`, or `"builtin"`.', 2544 ) 2545 id: str = Field(..., description="Tool ID (`atl_...`).") 2546 instruction: str | None = Field( 2547 default=None, 2548 description="Optional system-level instruction appended to the agent prompt when this tool is active.", 2549 ) 2550 kind: str | None = Field( 2551 default=None, description='Tool kind. One of `"builtin"`, `"custom"`, or `"mcp"`.' 2552 ) 2553 last_applied_template_config: str | None = Field( 2554 default=None, 2555 description="ID of the AgentToolTemplate config (`cfg_...`) this tool was last provisioned or updated from. `null` for manually created tools.", 2556 ) 2557 lookup_key: str | None = Field( 2558 default=None, 2559 description="Stable, user-defined identifier for this tool within the agent. Unique per agent.", 2560 ) 2561 metadata: dict[str, Any] | None = Field( 2562 default=None, 2563 description="Arbitrary key-value metadata attached to the tool. Not interpreted by the platform.", 2564 ) 2565 name: str | None = Field( 2566 default=None, 2567 description='Human-readable name of the tool as exposed to the LLM. Resolved from the built-in registry for `kind: "builtin"` tools.', 2568 ) 2569 name_prefix: str | None = Field( 2570 default=None, 2571 description="Per-instance namespace prepended to LLM-facing tool names for built-in tools that support multiple instances per agent. `null` when not applicable.", 2572 ) 2573 parameters: dict[str, Any] | None = Field( 2574 default=None, 2575 description="JSON Schema object describing the tool's input parameters as presented to the LLM.", 2576 ) 2577 parameters_config: str | None = Field( 2578 default=None, 2579 description="ID of the config record (`cfg_...`) storing the tool's parameter schema. `null` when parameters are defined inline.", 2580 ) 2581 status: str | None = Field( 2582 default=None, description='Current status of the tool. One of `"active"` or `"disabled"`.' 2583 ) 2584 updated_at: datetime | None = Field( 2585 default=None, description="When the tool was last modified (ISO 8601)." 2586 ) 2587 2588 2589class AgentToolListResponse(BaseModel): 2590 """ 2591 Paginated list response containing the tools attached to an agent. 2592 """ 2593 2594 data: list[AgentTool] = Field( 2595 ..., description="Array of agent tool objects returned for the current request." 2596 ) 2597 2598 2599class AgentUpgradeFieldChange(BaseModel): 2600 """ 2601 One field-level diff entry within an agent upgrade change, describing how a single field will change. 2602 `baseline` and `locally_edited` are populated only for `agent_base` entries; child resource entries (tools, routines, skills, computers) carry only `field`, `old`, and `new`. 2603 """ 2604 2605 baseline: Any | None = Field( 2606 default=None, 2607 description="Value that was set by the last-applied template version (pinned baseline). Populated only on `agent_base` field changes. `null` when no baseline is available (legacy agent or deleted version).", 2608 ) 2609 field: str = Field( 2610 ..., description='Name of the field that will change, e.g. `"name"` or `"identity"`.' 2611 ) 2612 locally_edited: bool | None = Field( 2613 default=None, 2614 description="`true` when the agent's current value differs from `baseline`, indicating a local edit that this upgrade will overwrite. `false` when the current value matches the baseline. `null` when `baseline` is unavailable. Populated only on `agent_base` field changes.", 2615 ) 2616 new: Any | None = Field( 2617 default=None, 2618 description="Incoming value the field will be set to after the upgrade (string, number, boolean, or `null`).", 2619 ) 2620 old: Any | None = Field( 2621 default=None, 2622 description="Current value of the field before the upgrade (string, number, boolean, or `null`).", 2623 ) 2624 2625 2626class AgentUpgradeChange(BaseModel): 2627 """ 2628 One child-resource change produced by an agent upgrade, describing the action to be taken on a single resource. 2629 """ 2630 2631 action: str = Field( 2632 ..., 2633 description='The operation that will be performed. One of `"add"`, `"update"`, `"remove"`, or `"noop"`.', 2634 ) 2635 description: str | None = Field( 2636 default=None, 2637 description="Description of the child resource this change touches, when one is set. `null` when no description is available.", 2638 ) 2639 field_changes: list[AgentUpgradeFieldChange] | None = Field( 2640 default=None, 2641 description='Field-level diff entries for this change. Populated only when `action` is `"update"`; empty or absent for `add`, `remove`, and `noop` entries.', 2642 ) 2643 id: str | None = Field( 2644 default=None, 2645 description="Public ID of the existing resource being updated or removed (e.g. `atl_...`, `arn_...`). `null` for `add` entries.", 2646 ) 2647 key: str | None = Field( 2648 default=None, 2649 description="Lookup key of the resource derived from its source template. `null` when the template has no lookup key.", 2650 ) 2651 name: str | None = Field( 2652 default=None, 2653 description="Human-facing name of the child resource this change touches (tool/routine/skill/computer name, or builtin tool key for unnamed builtin tools). Falls back to the source template's name. `null` for the synthetic `agent_base` entry.", 2654 ) 2655 parent_template_config: UpgradeTemplateSummary = Field( 2656 ..., 2657 description="Summary of the parent AgentTemplate config (`cfg_...`) being applied in this upgrade.", 2658 ) 2659 resource: dict[str, Any] | None = Field( 2660 default=None, 2661 description="Resource-type-specific identity details. Tools: `tool_type`, `builtin_tool_key`, `name_prefix`, `handler_type`, `instruction`. Routines: `handler_type`, `preset_name`, `event_type`, `schedule`, `trigger_context`. Skills: `instruction`. Computers: `region`. Only populated keys are present; `null` when nothing is known.", 2662 ) 2663 resource_type: str = Field( 2664 ..., 2665 description='Type of the child resource being changed. One of `"agent"`, `"tool"`, `"routine"`, `"skill"`, or `"computer"`.', 2666 ) 2667 source_template_config: UpgradeTemplateSummary | None = Field( 2668 default=None, 2669 description="Summary of the specific child template config (`cfg_...`) that defines this resource. `null` when no source template is resolvable.", 2670 ) 2671 2672 2673class AgentUpgradeSummary(BaseModel): 2674 """ 2675 Aggregate counts of each change type produced by an agent upgrade diff. 2676 """ 2677 2678 adds: int = Field( 2679 ..., description="Number of child resources that will be created by this upgrade." 2680 ) 2681 noops: int = Field( 2682 ..., description="Number of child resources with no changes in this upgrade." 2683 ) 2684 removes: int = Field( 2685 ..., description="Number of child resources that will be removed by this upgrade." 2686 ) 2687 updates: int = Field( 2688 ..., description="Number of child resources that will be updated by this upgrade." 2689 ) 2690 2691 2692class AgentUpgradeResult(BaseModel): 2693 """ 2694 The computed diff and outcome of an agent upgrade operation, including the full list of per-resource changes. 2695 """ 2696 2697 changes: list[AgentUpgradeChange] = Field( 2698 ..., 2699 description="Ordered list of per-resource changes that will be (or were) applied by this upgrade.", 2700 ) 2701 dry_run: bool = Field( 2702 ..., 2703 description="`true` when the request was a dry run and no changes were persisted to the agent.", 2704 ) 2705 mode: str = Field( 2706 ..., 2707 description='Upgrade mode that was used. One of `"full"` (apply all changes) or `"review"` (require fingerprint confirmation).', 2708 ) 2709 review_fingerprint: str | None = Field( 2710 default=None, 2711 description='Opaque fingerprint of the computed diff. Pass this value back as `review_fingerprint` to confirm and apply a `"review"` mode upgrade.', 2712 ) 2713 status: str = Field( 2714 ..., 2715 description='Outcome of the upgrade. `"ready"` for a dry-run (no changes applied); `"upgraded"` when the upgrade was committed.', 2716 ) 2717 summary: AgentUpgradeSummary = Field( 2718 ..., 2719 description="Aggregate counts of adds, updates, removes, and noops across all child resources.", 2720 ) 2721 2722 2723class AgentUpgradeResponse(BaseModel): 2724 """ 2725 Response returned by the agent upgrade endpoint, combining the updated agent, its source Solution and template, and the full upgrade diff. 2726 """ 2727 2728 agent: Agent | None = Field( 2729 default=None, 2730 description="The agent after the upgrade has been applied. `null` for dry-run requests where no changes were persisted.", 2731 ) 2732 solution: SolutionSummary = Field( 2733 ..., description="Summary of the parent Solution the agent was upgraded from." 2734 ) 2735 template: UpgradeTemplateSummary = Field( 2736 ..., 2737 description="Summary of the AgentTemplate config (`cfg_...`) that was selected for this upgrade.", 2738 ) 2739 upgrade_result: AgentUpgradeResult = Field( 2740 ..., 2741 description="Full upgrade diff including status, mode, dry-run flag, summary counts, and per-resource change list.", 2742 ) 2743 2744 2745class SolutionCategorySummary(BaseModel): 2746 """ 2747 A solution category that organizes solutions in the catalog, identified by a stable key and optionally nested under a parent category. 2748 """ 2749 2750 created_at: datetime | None = Field( 2751 default=None, 2752 description="When this category was first created (ISO 8601). `null` for system-built-in categories.", 2753 ) 2754 description: str | None = Field( 2755 default=None, 2756 description="Short prose description of what solutions in this category do. `null` when not configured.", 2757 ) 2758 id: str = Field(..., description="Solution category config ID (`cfg_...`).") 2759 key: str = Field( 2760 ..., 2761 description="Stable, human-readable key for this category, referenced by solutions via `category_keys`.", 2762 ) 2763 kind: str = Field(..., description='Resource type identifier. Always `"SolutionCategory"`.') 2764 lookup_key: str | None = Field( 2765 default=None, description="Lookup key of the underlying config record. `null` when not set." 2766 ) 2767 metadata: dict[str, Any] | None = Field( 2768 default=None, 2769 description="Arbitrary key-value metadata attached to this category by the publisher.", 2770 ) 2771 name: str | None = Field( 2772 default=None, description="Display name shown to users. `null` when not configured." 2773 ) 2774 org: str | None = Field( 2775 default=None, 2776 description="Organization ID (`org_...`) that owns this category. `null` for system-scoped categories.", 2777 ) 2778 owners: list[str] = Field( 2779 ..., 2780 description='Scopes under which this category is visible. Possible values are `"system"` (available to all apps) and `"org"` (scoped to the viewer\'s organization).', 2781 ) 2782 parent_key: str | None = Field( 2783 default=None, 2784 description="Key of the parent `SolutionCategory`, enabling a hierarchy. `null` for top-level categories.", 2785 ) 2786 sort_order: int | None = Field( 2787 default=None, 2788 description="Numeric hint for ordering categories in a list. Lower values sort first. `null` when not configured.", 2789 ) 2790 updated_at: datetime | None = Field( 2791 default=None, 2792 description="When this category was last modified (ISO 8601). `null` for system-built-in categories.", 2793 ) 2794 virtual_path: str | None = Field( 2795 default=None, 2796 description="Virtual path of the underlying config record. `null` when not set.", 2797 ) 2798 2799 2800class SolutionCategoryListResponse(BaseModel): 2801 """ 2802 Paginated list of solution category summaries. Use `page` and `page_size` to navigate pages of results. 2803 """ 2804 2805 data: list[SolutionCategorySummary] = Field( 2806 ..., description="Array of solution category summary objects for the current page." 2807 ) 2808 has_next: bool = Field(..., description="`true` when a subsequent page of results exists.") 2809 has_prev: bool = Field(..., description="`true` when a previous page of results exists.") 2810 page: int = Field(..., description="Current page number (1-indexed).") 2811 page_size: int = Field(..., description="Maximum number of entries returned per page.") 2812 total_entries: int = Field( 2813 ..., description="Total number of distinct solution categories across all pages." 2814 ) 2815 total_pages: int = Field( 2816 ..., description="Total number of pages available at the current `page_size`." 2817 ) 2818 2819 2820class SolutionDependentAgent(BaseModel): 2821 """ 2822 A brief representation of an agent that references at least one config bundled by a Solution, included in the dependents preview response. 2823 """ 2824 2825 id: str = Field(..., description="Agent ID (`agi_...`).") 2826 name: str | None = Field( 2827 default=None, 2828 description="Human-readable display name of the agent. `null` when no name has been set.", 2829 ) 2830 2831 2832class SolutionDependentsResponse(BaseModel): 2833 """ 2834 A preview of the agents and configs that would be affected by deleting a Solution, returned before any deletion occurs so the caller can display a confirmation warning. 2835 """ 2836 2837 dependent_agent_count: int = Field( 2838 ..., 2839 description="Total number of distinct agents that reference at least one config bundled by this Solution. Use this count in the confirmation message; `dependent_agents` may be a shorter sample.", 2840 ) 2841 dependent_agents: list[SolutionDependentAgent] = Field( 2842 ..., 2843 description="A representative sample of the dependent agents, suitable for displaying in a warning list. May contain fewer entries than `dependent_agent_count` when there are many dependents.", 2844 ) 2845 preserved_config_count: int = Field( 2846 ..., 2847 description="Number of bundled configs that would be detached and preserved rather than deleted, because at least one live agent still references them.", 2848 ) 2849 2850 2851class SolutionDiffReference(BaseModel): 2852 """ 2853 A reference from another config to an orphaned entry in a solution upgrade diff, explaining why the orphan cannot be safely removed. 2854 """ 2855 2856 id: str = Field(..., description="ID of the referencing config (`cfg_...`).") 2857 kind: str = Field( 2858 ..., 2859 description='Object type of the referencing config, e.g. `"Automation"` or `"Template"`.', 2860 ) 2861 lookup_key: str | None = Field( 2862 default=None, 2863 description="Human-readable stable identifier of the referencing config. `null` if not assigned.", 2864 ) 2865 reason: str = Field( 2866 ..., description="Explanation of how the referencing config depends on the orphaned entry." 2867 ) 2868 2869 2870class SolutionDiffEntry(BaseModel): 2871 """ 2872 A single config entry in a solution upgrade diff, describing what action will be taken on a specific config key. 2873 """ 2874 2875 action: str = Field( 2876 ..., 2877 description='Planned action for this entry. One of `"add"` (new config), `"update"` (existing config changes), `"noop"` (no change needed), `"orphan"` (config no longer in the solution), or `"delete"` (config to be removed).', 2878 ) 2879 content_changed: bool = Field( 2880 ..., 2881 description="`true` if the config content differs between the existing and incoming solution versions.", 2882 ) 2883 id: str | None = Field( 2884 default=None, 2885 description="Config ID (`cfg_...`) if this entry corresponds to an existing config record. `null` for new additions.", 2886 ) 2887 key: str = Field( 2888 ..., description="Stable string key identifying this config entry within the solution." 2889 ) 2890 kind: str | None = Field( 2891 default=None, 2892 description='Config object type, e.g. `"Automation"` or `"Template"`. `null` if not yet known.', 2893 ) 2894 lookup_key: str | None = Field( 2895 default=None, 2896 description="Human-readable stable identifier for this config. `null` if not assigned.", 2897 ) 2898 mime_type_changed: bool = Field( 2899 ..., description="`true` if the MIME type of the config changed between versions." 2900 ) 2901 referenced_by: list[SolutionDiffReference] | None = Field( 2902 default=None, 2903 description="List of other configs that reference this entry. Populated for orphaned configs that cannot be safely removed. Empty array when there are no references.", 2904 ) 2905 relative_path_changed: bool = Field( 2906 ..., 2907 description="`true` if the relative path of the config within the solution changed between versions.", 2908 ) 2909 role: str = Field( 2910 ..., 2911 description="Role of this config within the solution. Indicates whether it is a primary config or a dependency.", 2912 ) 2913 virtual_path: str | None = Field( 2914 default=None, 2915 description="Hierarchical path of this config in the config tree. `null` if not assigned.", 2916 ) 2917 2918 2919class SolutionDiffSummary(BaseModel): 2920 """ 2921 Aggregate counts of each action type across all entries in a solution upgrade diff. 2922 """ 2923 2924 adds: int = Field( 2925 ..., description="Number of config entries that will be newly created by this upgrade." 2926 ) 2927 deletes: int = Field( 2928 ..., description="Number of config entries that will be deleted as part of the upgrade." 2929 ) 2930 noops: int = Field( 2931 ..., 2932 description="Number of config entries that are already up to date and require no changes.", 2933 ) 2934 orphans: int = Field( 2935 ..., 2936 description="Number of config entries present in the existing solution that are absent from the incoming version and have no external references blocking removal.", 2937 ) 2938 referenced_orphans: int = Field( 2939 ..., 2940 description="Number of orphaned config entries that cannot be removed because other configs still reference them.", 2941 ) 2942 updates: int = Field( 2943 ..., description="Number of config entries that exist and will be updated with new content." 2944 ) 2945 2946 2947class SolutionImportResult(BaseModel): 2948 """ 2949 The machine-readable outcome of a Solution import attempt, indicating whether the import succeeded or requires an upgrade flow to resolve a version conflict. 2950 """ 2951 2952 code: str | None = Field( 2953 default=None, 2954 description='Machine-readable conflict code present when `status` is `"conflict"`, identifying the specific conflict reason. `null` when `status` is `"ready"`.', 2955 ) 2956 dry_run: bool = Field( 2957 ..., 2958 description="Whether this result was produced by a dry-run check. `true` when the import was validated without persisting any changes.", 2959 ) 2960 existing_solution_version: str | None = Field( 2961 default=None, 2962 description="Semver string of the Solution version already present in the library. `null` when no prior version exists.", 2963 ) 2964 incoming_solution_version: str | None = Field( 2965 default=None, 2966 description="Semver string of the Solution version in the bundle being imported. `null` when the bundle does not declare a version.", 2967 ) 2968 message: str | None = Field( 2969 default=None, 2970 description="Human-readable description of the import status or conflict reason, suitable for display in a confirmation dialog. `null` when no detail is available.", 2971 ) 2972 status: str = Field( 2973 ..., 2974 description='Outcome of the import check. `"ready"` means the import can proceed as a normal create or update. `"conflict"` means a version conflict was detected and the upgrade flow must be used instead.', 2975 ) 2976 upgrade_required: bool = Field( 2977 ..., 2978 description='Whether the caller must invoke the dedicated upgrade flow to complete the import. Mirrors `status == "conflict"` as a convenience boolean.', 2979 ) 2980 2981 2982class SolutionImportResponse(BaseModel): 2983 """ 2984 The result of importing a Solution bundle into the library, including the Solution config record, a structured import result, and the list of all configs persisted during the transaction. 2985 """ 2986 2987 created_at: datetime | None = Field( 2988 default=None, description="When the Solution config record was first created (ISO 8601)." 2989 ) 2990 id: str = Field(..., description="Solution config ID (`cfg_...`).") 2991 import_result: SolutionImportResult = Field( 2992 ..., 2993 description="Structured outcome of the import, including status, conflict details, and version information.", 2994 ) 2995 installed_configs: list[InstalledConfigEntry] | None = Field( 2996 default=None, 2997 description="Deprecated legacy field. One entry per persisted config in the import (including the Solution itself), defaulting to an empty array. Callers should prefer `solution` plus follow-up APIs instead. `key` echoes the caller-supplied input identifier (original lookup_key for top-level configs; `<skill_lookup_key>:<relative_path>` for skill / solution-file children). Order is stable: sorted by `key`.", 2998 ) 2999 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 3000 lookup_key: str | None = Field( 3001 default=None, 3002 description="The `lookup_key` stored on the Solution config after the import's suffix normalization. `null` when the Solution was not given a lookup key.", 3003 ) 3004 solution: SolutionSummary = Field( 3005 ..., 3006 description="Full summary of the imported Solution, in the same shape as the individual Solution retrieval endpoint.", 3007 ) 3008 updated_at: datetime | None = Field( 3009 default=None, description="When the Solution config record was last modified (ISO 8601)." 3010 ) 3011 virtual_path: str | None = Field( 3012 default=None, 3013 description="The `virtual_path` stored on the Solution config, used as the stable dedupe key across owner scopes. `null` when no virtual path was assigned.", 3014 ) 3015 3016 3017class SolutionInstallResponse(BaseModel): 3018 """ 3019 The runtime resource provisioned by installing a Solution, along with a reference back to the source Solution config. 3020 """ 3021 3022 id: str = Field( 3023 ..., 3024 description="Public ID of the provisioned resource. The prefix reflects the resource kind: `agi_...` for Agent, `aut_...` for Automation, `art_...` for AgentRoutine, `att_...` for AgentTool, `ask_...` for AgentSkill, `cmp_...` for AgentComputer.", 3025 ) 3026 kind: str = Field( 3027 ..., 3028 description='Type of the provisioned resource. One of `"Agent"`, `"Automation"`, `"AgentRoutine"`, `"AgentTool"`, `"AgentSkill"`, or `"AgentComputer"`.', 3029 ) 3030 lookup_key: str | None = Field( 3031 default=None, 3032 description="The `lookup_key` stamped on the provisioned resource. `null` for `AgentSkill`, which is a join record and does not carry a lookup key.", 3033 ) 3034 solution: str = Field( 3035 ..., 3036 description="Solution config ID (`cfg_...`) that was used as the source for this install.", 3037 ) 3038 3039 3040class SolutionListResponse(BaseModel): 3041 """ 3042 A paginated collection of Solution summaries, with page metadata for navigating the result set. 3043 """ 3044 3045 data: list[SolutionSummary] = Field( 3046 ..., 3047 description="Array of Solution summary objects for the current page, in the order returned by the query.", 3048 ) 3049 has_next: bool = Field( 3050 ..., description="`true` when a subsequent page exists; `false` when this is the last page." 3051 ) 3052 has_prev: bool = Field( 3053 ..., description="`true` when a preceding page exists; `false` when this is the first page." 3054 ) 3055 page: int = Field(..., description="1-based index of the current page.") 3056 page_size: int = Field(..., description="Maximum number of results included per page.") 3057 total_entries: int = Field( 3058 ..., 3059 description="Total number of Solutions matching the query after deduplication by `solution_id` across owner scopes.", 3060 ) 3061 total_pages: int = Field( 3062 ..., description="Total number of pages available at the current `page_size`." 3063 ) 3064 3065 3066class SolutionTagSummary(BaseModel): 3067 """ 3068 A single solution tag definition, representing a named classification label that can be applied to solutions. 3069 """ 3070 3071 created_at: datetime | None = Field( 3072 default=None, 3073 description="When the solution tag was first created (ISO 8601). `null` if unavailable.", 3074 ) 3075 description: str | None = Field( 3076 default=None, 3077 description="Short prose explanation of what the tag represents. `null` if not provided.", 3078 ) 3079 id: str = Field(..., description="Solution tag config ID (`cfg_...`).") 3080 key: str = Field( 3081 ..., 3082 description="Stable string key for this tag, referenced by `Solution.tag_keys` to associate solutions with this tag.", 3083 ) 3084 kind: str = Field(..., description='Object type discriminator. Always `"SolutionTag"`.') 3085 lookup_key: str | None = Field( 3086 default=None, 3087 description="Human-readable stable identifier for this tag config, used for lookups and imports. `null` if not assigned.", 3088 ) 3089 metadata: dict[str, Any] | None = Field( 3090 default=None, 3091 description="Arbitrary key-value metadata attached to this tag. Empty object `{}` when no metadata is present.", 3092 ) 3093 name: str | None = Field( 3094 default=None, description="Human-readable display name for the tag. `null` if not yet set." 3095 ) 3096 org: str | None = Field( 3097 default=None, 3098 description="ID of the organization that owns this tag (`org_...`). `null` for system-scoped tags.", 3099 ) 3100 owners: list[str] = Field( 3101 ..., 3102 description='Scopes under which this tag is visible to the caller. One or both of `"system"` (platform-level tag available to all orgs) and `"org"` (tag scoped to the viewer\'s org).', 3103 ) 3104 sort_order: int | None = Field( 3105 default=None, 3106 description="Optional integer hint for ordering tags in UI lists. Lower values sort first. `null` if not set.", 3107 ) 3108 updated_at: datetime | None = Field( 3109 default=None, 3110 description="When the solution tag was last modified (ISO 8601). `null` if unavailable.", 3111 ) 3112 virtual_path: str | None = Field( 3113 default=None, 3114 description="Hierarchical path used to organize this tag in the config tree. `null` if not assigned.", 3115 ) 3116 3117 3118class SolutionTagListResponse(BaseModel): 3119 """ 3120 Paginated list of solution tag summaries returned by the list solution tags endpoint. 3121 """ 3122 3123 data: list[SolutionTagSummary] = Field( 3124 ..., description="Array of solution tag objects for the current page." 3125 ) 3126 has_next: bool = Field( 3127 ..., description="`true` if a subsequent page exists; `false` when this is the last page." 3128 ) 3129 has_prev: bool = Field( 3130 ..., description="`true` if a preceding page exists; `false` when this is the first page." 3131 ) 3132 page: int = Field(..., description="Current page number (1-indexed).") 3133 page_size: int = Field(..., description="Maximum number of results returned per page.") 3134 total_entries: int = Field( 3135 ..., 3136 description="Total number of distinct solution tags across all pages, after deduplication by key.", 3137 ) 3138 total_pages: int = Field( 3139 ..., description="Total number of pages available at the current `page_size`." 3140 ) 3141 3142 3143class SolutionUpgradeResult(BaseModel): 3144 """ 3145 The outcome of a solution upgrade operation, including the computed diff and conflict status. 3146 """ 3147 3148 changes: list[SolutionDiffEntry] = Field( 3149 ..., 3150 description="Ordered list of individual config change entries representing every add, update, noop, orphan, and delete in the diff.", 3151 ) 3152 code: str | None = Field( 3153 default=None, 3154 description='Machine-readable conflict code when `status` is `"conflict"`, e.g. `"review_required"`. `null` when there is no conflict.', 3155 ) 3156 dry_run: bool = Field( 3157 ..., 3158 description="`true` when the upgrade was computed without writing any changes; `false` when changes were committed.", 3159 ) 3160 existing_solution_version: str | None = Field( 3161 default=None, 3162 description="Version string of the currently installed solution, as declared in its manifest. `null` if no prior version is installed.", 3163 ) 3164 incoming_solution_version: str | None = Field( 3165 default=None, 3166 description="Version string of the incoming solution to be installed, as declared in its manifest. `null` if the incoming manifest omits a version.", 3167 ) 3168 message: str | None = Field( 3169 default=None, 3170 description="Human-readable description of the conflict or error. `null` when there is no conflict.", 3171 ) 3172 review_fingerprint: str | None = Field( 3173 default=None, 3174 description="Opaque fingerprint that uniquely identifies this diff. Pass this value as `review_fingerprint` on a subsequent non-dry-run upgrade call to confirm you have reviewed the diff. `null` if not applicable.", 3175 ) 3176 status: str = Field( 3177 ..., 3178 description='Overall result of the upgrade. `"ready"` means the upgrade can proceed; `"conflict"` means a blocking issue was detected and the upgrade was not applied.', 3179 ) 3180 summary: SolutionDiffSummary = Field( 3181 ..., description="Aggregate counts of each action type across all diff entries." 3182 ) 3183 version_change: str = Field( 3184 ..., 3185 description='Describes the nature of the version transition. One of `"upgrade"`, `"downgrade"`, `"same"`, or `"unknown"`.', 3186 ) 3187 3188 3189class SolutionUpgradeResponse(BaseModel): 3190 """ 3191 Response returned by the solution upgrade endpoint, containing the solution record, the full upgrade diff, and the resulting installed configs. 3192 """ 3193 3194 created_at: datetime | None = Field( 3195 default=None, 3196 description="When the solution config record was first created (ISO 8601). `null` if unavailable.", 3197 ) 3198 id: str = Field(..., description="Config ID of the solution record (`cfg_...`).") 3199 installed_configs: list[InstalledConfigEntry] | None = Field( 3200 default=None, 3201 description="List of config entries that were installed or updated as part of this upgrade. Empty when `dry_run` is `true` or when no configs changed.", 3202 ) 3203 kind: str = Field(..., description='Object type discriminator. Always `"Solution"`.') 3204 lookup_key: str | None = Field( 3205 default=None, 3206 description="Human-readable stable identifier for this solution config. `null` if not assigned.", 3207 ) 3208 solution: SolutionSummary = Field( 3209 ..., 3210 description="Summary of the solution being upgraded, including its name, manifest metadata, and tag keys.", 3211 ) 3212 updated_at: datetime | None = Field( 3213 default=None, 3214 description="When the solution config record was last modified (ISO 8601). `null` if unavailable.", 3215 ) 3216 upgrade_result: SolutionUpgradeResult = Field( 3217 ..., 3218 description="Detailed result of the upgrade operation, including the computed diff and any conflict information.", 3219 ) 3220 virtual_path: str | None = Field( 3221 default=None, 3222 description="Hierarchical path of the solution in the config tree. `null` if not assigned.", 3223 )
class
AclGrant(pydantic.main.BaseModel):
16class AclGrant(BaseModel): 17 """ 18 A single access-control grant that pairs a principal with the set of actions it is allowed to perform. 19 """ 20 21 actions: list[str] = Field( 22 ..., 23 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 24 ) 25 principal: str | None = Field( 26 default=None, 27 description='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"`.', 28 ) 29 principal_type: str = Field( 30 ..., 31 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 32 )
A single access-control grant that pairs a principal with the set of actions it is allowed to perform.
actions: list[str] =
PydanticUndefined
Array of action strings the principal is permitted to perform, e.g. ["read", "write"]. Must contain at least one entry.
principal: str | None =
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
AclRemoveTarget(pydantic.main.BaseModel):
35class AclRemoveTarget(BaseModel): 36 """ 37 Identifies a principal to be removed from an access-control list. 38 """ 39 40 principal: str | None = Field( 41 default=None, 42 description='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"`.', 43 ) 44 principal_type: str = Field( 45 ..., 46 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 47 )
Identifies a principal to be removed from an access-control list.
principal: str | None =
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
Acl(pydantic.main.BaseModel):
50class Acl(BaseModel): 51 """ 52 An access-control list payload that supports either full replacement or targeted patch operations on a resource's grants. 53 """ 54 55 add: list[AclGrant] | None = Field( 56 default=None, 57 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 58 ) 59 grants: list[AclGrant] | None = Field( 60 default=None, 61 description="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`.", 62 ) 63 remove: list[AclRemoveTarget] | None = Field( 64 default=None, 65 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 66 )
An access-control list payload that supports either full replacement or targeted patch operations on a resource's grants.
Patch mode: grants to add or merge into the existing list. Cannot be combined with grants.
Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with grants.
class
ActivityFeedEntry(pydantic.main.BaseModel):
69class ActivityFeedEntry(BaseModel): 70 """ 71 A single event record in an activity feed, capturing what happened, who caused it, and which resources were involved. 72 """ 73 74 agent: str | dict[str, Any] | None = Field( 75 default=None, 76 description="The agent that produced this event. Returns an agent ID (`agi_...`) by default, or an expanded agent object when the association is loaded. `null` if no agent is associated.", 77 ) 78 app: str | None = Field( 79 default=None, 80 description="ID of the application that produced this entry (`dap_...`). `null` if not scoped to an app.", 81 ) 82 attachments: list[dict[str, Any]] | None = Field( 83 default=None, 84 description='Array of attachment objects associated with this entry. Each attachment has a `type` field (e.g. `"file"`, `"task"`, `"artifact"`) and type-specific additional fields. Empty array when there are no attachments.', 85 ) 86 automation_run: str | None = Field( 87 default=None, 88 description="ID of the automation run that produced this entry (`atr_...`). `null` if not produced by an automation run.", 89 ) 90 content: str | None = Field( 91 default=None, 92 description="A longer explanation of the event rendered as Markdown. `null` if no additional content is available.", 93 ) 94 correlation_id: str | None = Field( 95 default=None, 96 description="An opaque string used to group related entries together. Entries sharing the same `correlation_id` belong to a single logical operation. `null` if not correlated.", 97 ) 98 created_at: datetime | None = Field( 99 default=None, description="When this activity feed entry was created (ISO 8601)." 100 ) 101 id: str = Field(..., description="Activity feed entry ID (`afe_...`).") 102 kind: str | None = Field( 103 default=None, 104 description='The type of event this entry represents, e.g. `"agent_step"` or `"tool_call"`. Determines how `title`, `content`, and `attachments` should be interpreted.', 105 ) 106 level: str | None = Field( 107 default=None, 108 description='Severity level of the event. One of `"info"`, `"warning"`, or `"error"`. `null` if no severity is set.', 109 ) 110 metadata: dict[str, Any] | None = Field( 111 default=None, 112 description="Arbitrary key-value metadata stored on this entry. Returns an empty object when no metadata is set.", 113 ) 114 org: str | None = Field( 115 default=None, 116 description="ID of the organization this entry belongs to (`org_...`). `null` if not org-scoped.", 117 ) 118 routine_run: str | None = Field( 119 default=None, 120 description="ID of the agent routine run that produced this entry (`arr_...`). `null` if not produced by a routine run.", 121 ) 122 sandbox: str | None = Field( 123 default=None, 124 description="Identifier of the sandbox environment this entry was generated in. `null` in production contexts.", 125 ) 126 session_record: str | None = Field( 127 default=None, 128 description="ID of the agent session record this entry belongs to (`ase_...`). `null` if not part of an agent session.", 129 ) 130 team: str | None = Field( 131 default=None, 132 description="ID of the team this entry is associated with (`tem_...`). `null` if not team-scoped.", 133 ) 134 thread: str | None = Field( 135 default=None, 136 description="ID of the thread this entry is associated with (`thr_...`). `null` if not linked to a thread.", 137 ) 138 title: str | None = Field( 139 default=None, 140 description="A one-line human-readable summary of the event. `null` if the entry has no title.", 141 ) 142 updated_at: datetime | None = Field( 143 default=None, description="When this activity feed entry was last modified (ISO 8601)." 144 ) 145 user: str | dict[str, Any] | None = Field( 146 default=None, 147 description="The user who triggered this event. Returns a user ID (`usr_...`) by default, or an expanded user object when the association is loaded. `null` if no user is associated.", 148 )
A single event record in an activity feed, capturing what happened, who caused it, and which resources were involved.
agent: str | dict[str, typing.Any] | None =
None
The agent that produced this event. Returns an agent ID (agi_...) by default, or an expanded agent object when the association is loaded. null if no agent is associated.
app: str | None =
None
ID of the application that produced this entry (dap_...). null if not scoped to an app.
attachments: list[dict[str, typing.Any]] | None =
None
Array of attachment objects associated with this entry. Each attachment has a type field (e.g. "file", "task", "artifact") and type-specific additional fields. Empty array when there are no attachments.
automation_run: str | None =
None
ID of the automation run that produced this entry (atr_...). null if not produced by an automation run.
content: str | None =
None
A longer explanation of the event rendered as Markdown. null if no additional content is available.
correlation_id: str | None =
None
An opaque string used to group related entries together. Entries sharing the same correlation_id belong to a single logical operation. null if not correlated.
kind: str | None =
None
The type of event this entry represents, e.g. "agent_step" or "tool_call". Determines how title, content, and attachments should be interpreted.
level: str | None =
None
Severity level of the event. One of "info", "warning", or "error". null if no severity is set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata stored on this entry. Returns an empty object when no metadata is set.
org: str | None =
None
ID of the organization this entry belongs to (org_...). null if not org-scoped.
routine_run: str | None =
None
ID of the agent routine run that produced this entry (arr_...). null if not produced by a routine run.
sandbox: str | None =
None
Identifier of the sandbox environment this entry was generated in. null in production contexts.
session_record: str | None =
None
ID of the agent session record this entry belongs to (ase_...). null if not part of an agent session.
team: str | None =
None
ID of the team this entry is associated with (tem_...). null if not team-scoped.
thread: str | None =
None
ID of the thread this entry is associated with (thr_...). null if not linked to a thread.
title: str | None =
None
A one-line human-readable summary of the event. null if the entry has no title.
class
ActivityFeedEntryListResponse(pydantic.main.BaseModel):
151class ActivityFeedEntryListResponse(BaseModel): 152 """ 153 A paginated list of activity feed entries returned by a feed query, with cursors for navigating backward and forward through results. 154 """ 155 156 after_cursor: str | None = Field( 157 default=None, 158 description="Opaque cursor to pass as `after` to retrieve the next page of entries. `null` when this is the last page.", 159 ) 160 before_cursor: str | None = Field( 161 default=None, 162 description="Opaque cursor to pass as `before` to retrieve the previous page of entries. `null` when this is the first page.", 163 ) 164 entries: list[ActivityFeedEntry] = Field( 165 ..., 166 description="Array of activity feed entry objects for the current page, ordered by time descending.", 167 ) 168 has_more: bool = Field( 169 ..., 170 description="Whether additional entries exist beyond the current page. When `true`, use `after_cursor` to fetch the next page.", 171 )
A paginated list of activity feed entries returned by a feed query, with cursors for navigating backward and forward through results.
after_cursor: str | None =
None
Opaque cursor to pass as after to retrieve the next page of entries. null when this is the last page.
before_cursor: str | None =
None
Opaque cursor to pass as before to retrieve the previous page of entries. null when this is the first page.
has_more: bool =
PydanticUndefined
Whether additional entries exist beyond the current page. When true, use after_cursor to fetch the next page.
class
Actor(pydantic.main.BaseModel):
174class Actor(BaseModel): 175 """ 176 The entity that authored a message, either a human user or an agent. 177 """ 178 179 alias: str | None = Field( 180 default=None, 181 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 182 ) 183 id: str | None = Field( 184 default=None, 185 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 186 ) 187 name: str | None = Field( 188 default=None, 189 description="Display name of the actor shown in the UI. `null` if no name is set.", 190 ) 191 profile_picture: ImageSource | None = Field( 192 default=None, 193 description="Profile picture for the actor. `null` if the actor has no profile picture.", 194 )
The entity that authored a message, either a human user or an agent.
alias: str | None =
None
Short handle or alias for the actor, used as an alternate display identifier. null if not configured.
id: str | None =
None
Composite actor identifier. Format is "user-<usr_...>" for human users or "agent-<agi_...>" for agents.
class
UpgradeTemplateSummary(pydantic.main.BaseModel):
197class UpgradeTemplateSummary(BaseModel): 198 """ 199 Compact summary of an AgentTemplate config referenced by an agent upgrade or source-solution response. 200 """ 201 202 created_at: datetime | None = Field( 203 default=None, description="When this template config was created (ISO 8601)." 204 ) 205 description: str | None = Field( 206 default=None, 207 description="Description of the template from the config body. `null` if the current version has no `description` field.", 208 ) 209 display_name: str | None = Field( 210 default=None, 211 description="Human-readable display name from the config body. `null` if the current version has no `display_name` field.", 212 ) 213 id: str = Field(..., description="Template config ID (`cfg_...`).") 214 kind: str = Field( 215 ..., description='Config kind identifier for this template (e.g. `"agent_tool_template"`).' 216 ) 217 lookup_key: str | None = Field( 218 default=None, 219 description="Stable lookup key assigned to this template config. `null` if no lookup key is set.", 220 ) 221 name: str | None = Field( 222 default=None, 223 description="Template name as stored in the config body. `null` if the current version has no `name` field.", 224 ) 225 updated_at: datetime | None = Field( 226 default=None, description="When this template config was last modified (ISO 8601)." 227 ) 228 virtual_path: str | None = Field( 229 default=None, 230 description="Virtual filesystem path for this template config. `null` if not set.", 231 )
Compact summary of an AgentTemplate config referenced by an agent upgrade or source-solution response.
description: str | None =
None
Description of the template from the config body. null if the current version has no description field.
display_name: str | None =
None
Human-readable display name from the config body. null if the current version has no display_name field.
kind: str =
PydanticUndefined
Config kind identifier for this template (e.g. "agent_tool_template").
lookup_key: str | None =
None
Stable lookup key assigned to this template config. null if no lookup key is set.
name: str | None =
None
Template name as stored in the config body. null if the current version has no name field.
class
InstalledConfigEntry(pydantic.main.BaseModel):
234class InstalledConfigEntry(BaseModel): 235 """ 236 A slim summary of a single config record created during an agent install transaction. Returned as an entry in `AgentCreateResponse.installed_configs`. 237 """ 238 239 id: str = Field(..., description="ID of the persisted config record (`cfg_...`).") 240 key: str = Field( 241 ..., 242 description='Caller-supplied correlation key echoed back from the request. For top-level configs this is the original `lookup_key` (before any suffix is applied). For skill file children it is the composite `"<skill_lookup_key>:<relative_path>"` string, since file rows have no lookup_key of their own.', 243 ) 244 kind: str = Field( 245 ..., 246 description='Type of config that was created. One of `"Skill"`, `"File"`, `"Script"`, `"AgentTemplate"`, or `"Config"`.', 247 ) 248 lookup_key: str | None = Field( 249 default=None, 250 description="Stored `lookup_key` for this config after any suffix has been applied. `null` for `File` children inside a skill bundle, which are keyed by `(parent_id, relative_path)` rather than by `lookup_key`.", 251 )
A slim summary of a single config record created during an agent install transaction. Returned as an entry in AgentCreateResponse.installed_configs.
key: str =
PydanticUndefined
Caller-supplied correlation key echoed back from the request. For top-level configs this is the original lookup_key (before any suffix is applied). For skill file children it is the composite "<skill_lookup_key>:<relative_path>" string, since file rows have no lookup_key of their own.
kind: str =
PydanticUndefined
Type of config that was created. One of "Skill", "File", "Script", "AgentTemplate", or "Config".
lookup_key: str | None =
None
Stored lookup_key for this config after any suffix has been applied. null for File children inside a skill bundle, which are keyed by (parent_id, relative_path) rather than by lookup_key.
class
LLMConfig(pydantic.main.BaseModel):
254class LLMConfig(BaseModel): 255 """ 256 LLM invocation settings for a routine or chain step. When present, overrides the agent-level model selection. 257 """ 258 259 model: str | None = Field( 260 default=None, 261 description='Model identifier to use for this routine or step, e.g. `"claude-sonnet-4-5"`. When omitted, the agent\'s default model is used.', 262 )
LLM invocation settings for a routine or chain step. When present, overrides the agent-level model selection.
class
PresetConfig(pydantic.main.BaseModel):
265class PresetConfig(BaseModel): 266 """ 267 Configuration for a preset routine handler. Controls the agent's behavior, session persistence, and model selection for a given routine or chain step. 268 """ 269 270 instructions: str | None = Field( 271 default=None, 272 description="Custom task or behavior instructions for the preset (max 10,000 chars).", 273 ) 274 llm: LLMConfig | None = Field( 275 default=None, 276 description="LLM invocation settings (e.g. a `model` override for this routine/step).", 277 ) 278 session_mode: str | None = Field( 279 default=None, 280 description="Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`).", 281 ) 282 session_scope: str | None = Field( 283 default=None, 284 description="When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`.", 285 ) 286 structured_message_template_ids: list[str] | None = Field( 287 default=None, 288 description="IDs of structured message templates that constrain the agent's responses to predefined structured formats.", 289 )
Configuration for a preset routine handler. Controls the agent's behavior, session persistence, and model selection for a given routine or chain step.
instructions: str | None =
None
Custom task or behavior instructions for the preset (max 10,000 chars).
session_mode: str | None =
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 =
None
When session_mode is session, controls session scoping: per_user (default), per_key, per_org, or global.
class
WorkerStatus(pydantic.main.BaseModel):
292class WorkerStatus(BaseModel): 293 """ 294 Execution state of the background worker processing a routine run. Reflects the current job status and retry progress. 295 """ 296 297 attempt: int = Field( 298 ..., 299 description="Number of times the worker has been attempted so far. `0` means the job has been enqueued but not yet started.", 300 ) 301 max_attempts: int = Field( 302 ..., 303 description='Maximum number of attempts the worker is allowed before the job is marked `"discarded"`.', 304 ) 305 status: str = Field( 306 ..., 307 description='Current execution state of the worker. One of `"queued"`, `"executing"`, `"retrying"`, `"completed"`, `"discarded"`, or `"cancelled"`.', 308 )
Execution state of the background worker processing a routine run. Reflects the current job status and retry progress.
attempt: int =
PydanticUndefined
Number of times the worker has been attempted so far. 0 means the job has been enqueued but not yet started.
class
MediaVariant(pydantic.main.BaseModel):
311class MediaVariant(BaseModel): 312 """ 313 A processed variant of a media item, such as the original upload or a resized thumbnail, including a signed download URL resolved at request time. 314 """ 315 316 content_type: str | None = Field( 317 default=None, 318 description='MIME type of this variant\'s file (e.g., `"image/jpeg"`, `"video/mp4"`). `null` if the file is not loaded.', 319 ) 320 created_at: datetime | None = Field( 321 default=None, description="When this variant was created (ISO 8601)." 322 ) 323 file: str | None = Field( 324 default=None, 325 description="ID of the underlying storage file that backs this variant (`fil_...`).", 326 ) 327 filename: str | None = Field( 328 default=None, 329 description="Original filename of the uploaded file for this variant. `null` if the file is not loaded.", 330 ) 331 height: int | None = Field( 332 default=None, description="Height of this variant in pixels. `null` if not recorded." 333 ) 334 id: str = Field(..., description="Media variant ID (`mvr_...`).") 335 image_source: ImageSource | None = Field( 336 default=None, 337 description="Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types.", 338 ) 339 updated_at: datetime | None = Field( 340 default=None, description="When this variant was last updated (ISO 8601)." 341 ) 342 url: str | None = Field( 343 default=None, 344 description="Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", 345 ) 346 variant_key: str | None = Field( 347 default=None, 348 description='Identifier for this variant\'s processing tier. Common values include `"original"` (the unmodified upload) and `"thumbnail"` (a resized preview).', 349 ) 350 width: int | None = Field( 351 default=None, description="Width of this variant in pixels. `null` if not recorded." 352 )
A processed variant of a media item, such as the original upload or a resized thumbnail, including a signed download URL resolved at request time.
content_type: str | None =
None
MIME type of this variant's file (e.g., "image/jpeg", "video/mp4"). null if the file is not loaded.
filename: str | None =
None
Original filename of the uploaded file for this variant. null if the file is not loaded.
Resolved image delivery metadata for this variant, including dimensions and CDN URL. null for non-image content types.
url: str | None =
None
Signed download URL for this variant, resolved at request time. null if the file is unavailable.
class
Attachment(pydantic.main.BaseModel):
355class Attachment(BaseModel): 356 """ 357 A rich attachment associated with a message, such as a file, scraped link, artifact, task, media item, or inline action. 358 """ 359 360 content_type: str | None = Field( 361 default=None, 362 description='MIME type of the attached file, e.g. `"image/png"` or `"application/pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 363 ) 364 description: str | None = Field( 365 default=None, 366 description="Short description. The page meta-description for `scraped_link`, the artifact description for `artifact`, and the task description for `task` types. `null` on other types.", 367 ) 368 filename: str | None = Field( 369 default=None, 370 description='Original filename of the attached file, e.g. `"report.pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 371 ) 372 height: int | None = Field( 373 default=None, 374 description="Height in pixels of the media item. Present on `media` type only. `null` otherwise.", 375 ) 376 id: str = Field(..., description="Unique identifier for this attachment within the message.") 377 image_height: int | None = Field( 378 default=None, 379 description="Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 380 ) 381 image_source: ImageSource | None = Field( 382 default=None, 383 description="Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise.", 384 ) 385 image_url: str | None = Field( 386 default=None, 387 description="URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", 388 ) 389 image_width: int | None = Field( 390 default=None, 391 description="Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 392 ) 393 media_type: str | None = Field( 394 default=None, 395 description='The media category, e.g. `"video"` or `"audio"`. Present on `media` type only. `null` otherwise.', 396 ) 397 name: str | None = Field( 398 default=None, 399 description="Display name of the media item. Present on `media` type only. `null` otherwise.", 400 ) 401 object: dict[str, Any] | None = Field( 402 default=None, 403 description="The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. `null` on other types.", 404 ) 405 title: str | None = Field( 406 default=None, 407 description="Display title. The page title for `scraped_link`, the artifact name for `artifact`, and the task title for `task` types. `null` on other types.", 408 ) 409 type: str = Field( 410 ..., 411 description='The attachment type. One of `"file"`, `"scraped_link"`, `"artifact"`, `"task"`, `"media"`, or `"action"`. Determines which additional fields are present.', 412 ) 413 url: str | None = Field( 414 default=None, 415 description="URL to access the resource. A signed download URL for `file` and `artifact` types; the original URL for `scraped_link`; a media playback URL for `media`. `null` on `task` and `action` types.", 416 ) 417 variants: list[MediaVariant] | None = Field( 418 default=None, 419 description="Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only. `null` otherwise.", 420 ) 421 version: int | None = Field( 422 default=None, 423 description="Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", 424 ) 425 width: int | None = Field( 426 default=None, 427 description="Width in pixels of the media item. Present on `media` type only. `null` otherwise.", 428 )
A rich attachment associated with a message, such as a file, scraped link, artifact, task, media item, or inline action.
content_type: str | None =
None
MIME type of the attached file, e.g. "image/png" or "application/pdf". Present on file, artifact, and media types. null otherwise.
description: str | None =
None
Short description. The page meta-description for scraped_link, the artifact description for artifact, and the task description for task types. null on other types.
filename: str | None =
None
Original filename of the attached file, e.g. "report.pdf". Present on file, artifact, and media types. null otherwise.
height: int | None =
None
Height in pixels of the media item. Present on media type only. null otherwise.
image_height: int | None =
None
Height in pixels of the scraped preview image. Present on scraped_link type only. null otherwise.
Image source metadata for inline rendering. Present on file, scraped_link, artifact, and media types when the content is an image. null otherwise.
image_url: str | None =
None
URL of the preview image extracted from the scraped page. Present on scraped_link type only. null otherwise.
image_width: int | None =
None
Width in pixels of the scraped preview image. Present on scraped_link type only. null otherwise.
media_type: str | None =
None
The media category, e.g. "video" or "audio". Present on media type only. null otherwise.
object: dict[str, typing.Any] | None =
None
The full embedded object payload. For task type, contains the task record. For action type, contains the action definition. null on other types.
title: str | None =
None
Display title. The page title for scraped_link, the artifact name for artifact, and the task title for task types. null on other types.
type: str =
PydanticUndefined
The attachment type. One of "file", "scraped_link", "artifact", "task", "media", or "action". Determines which additional fields are present.
url: str | None =
None
URL to access the resource. A signed download URL for file and artifact types; the original URL for scraped_link; a media playback URL for media. null on task and action types.
Array of available encoding variants for the media item (e.g. different resolutions). Present on media type only. null otherwise.
class
AuthTokens(pydantic.main.BaseModel):
431class AuthTokens(BaseModel): 432 """ 433 Credential bundle returned after a successful authentication exchange. Contains the access token, refresh token, and the authenticated user. 434 """ 435 436 expires_in: int = Field( 437 ..., 438 description="Number of seconds until `token` expires. After this period, use `refresh_token` to obtain a new access token.", 439 ) 440 metadata: dict[str, Any] | None = Field( 441 default=None, 442 description="Optional auxiliary data associated with this authentication event, such as `onboarding_job_id` when the user is completing onboarding. `null` when no extra context is present.", 443 ) 444 refresh_token: str = Field( 445 ..., 446 description="Long-lived opaque refresh token. Use this to obtain a new access token when `token` expires.", 447 ) 448 token: str = Field( 449 ..., 450 description="Short-lived JWT access token. Include this value in the `Authorization: Bearer <token>` header for all authenticated API requests.", 451 ) 452 token_type: str = Field(..., description='Token scheme. Always `"Bearer"`.') 453 user: User = Field( 454 ..., 455 description="The user who authenticated. Contains the user's profile and account details.", 456 )
Credential bundle returned after a successful authentication exchange. Contains the access token, refresh token, and the authenticated user.
expires_in: int =
PydanticUndefined
Number of seconds until token expires. After this period, use refresh_token to obtain a new access token.
metadata: dict[str, typing.Any] | None =
None
Optional auxiliary data associated with this authentication event, such as onboarding_job_id when the user is completing onboarding. null when no extra context is present.
refresh_token: str =
PydanticUndefined
Long-lived opaque refresh token. Use this to obtain a new access token when token expires.
token: str =
PydanticUndefined
Short-lived JWT access token. Include this value in the Authorization: Bearer <token> header for all authenticated API requests.
class
BugReport(pydantic.main.BaseModel):
459class BugReport(BaseModel): 460 """ 461 A bug report or freeform feedback submission from any ArchAstro client. Bug reports are write-only for the submitting user and are not returned by any public list or show endpoint. 462 """ 463 464 app: str | None = Field( 465 default=None, 466 description="App ID (`dap_...`) of the developer app through which the report was submitted.", 467 ) 468 client: str = Field( 469 ..., 470 description='The client application that submitted this report. One of `"agent_network_web"`, `"cli"`, or `"developer_portal"`.', 471 ) 472 client_version: str = Field( 473 ..., 474 description='Version string of the submitting client at the time of submission, e.g. `"1.4.2"`.', 475 ) 476 context: dict[str, Any] | None = Field( 477 default=None, 478 description="Optional free-form JSON object providing additional context captured by the client (e.g. viewport size, active route). `null` when no context was provided. Maximum 5 KB when serialized.", 479 ) 480 created_at: datetime | None = Field( 481 default=None, description="When the bug report was submitted (ISO 8601)." 482 ) 483 description: str = Field( 484 ..., 485 description="Freeform text describing the issue or feedback, as entered by the user. Up to 10,000 characters.", 486 ) 487 id: str = Field(..., description="Bug report ID (`bgr_...`).") 488 org: str | None = Field( 489 default=None, 490 description="Organization ID (`org_...`) scoping this report. `null` when the user's account is not part of an organization.", 491 ) 492 sandbox: str | None = Field( 493 default=None, 494 description="Sandbox ID (`dsb_...`) active at submission time. `null` when the report was not submitted from a sandbox context.", 495 ) 496 team: str | None = Field( 497 default=None, 498 description="Team ID (`tem_...`) of the team the submitting user belonged to at submission time. `null` when the user had no active team.", 499 ) 500 updated_at: datetime | None = Field( 501 default=None, description="When the bug report record was last modified (ISO 8601)." 502 )
A bug report or freeform feedback submission from any ArchAstro client. Bug reports are write-only for the submitting user and are not returned by any public list or show endpoint.
app: str | None =
None
App ID (dap_...) of the developer app through which the report was submitted.
client: str =
PydanticUndefined
The client application that submitted this report. One of "agent_network_web", "cli", or "developer_portal".
client_version: str =
PydanticUndefined
Version string of the submitting client at the time of submission, e.g. "1.4.2".
context: dict[str, typing.Any] | None =
None
Optional free-form JSON object providing additional context captured by the client (e.g. viewport size, active route). null when no context was provided. Maximum 5 KB when serialized.
description: str =
PydanticUndefined
Freeform text describing the issue or feedback, as entered by the user. Up to 10,000 characters.
org: str | None =
None
Organization ID (org_...) scoping this report. null when the user's account is not part of an organization.
sandbox: str | None =
None
Sandbox ID (dsb_...) active at submission time. null when the report was not submitted from a sandbox context.
class
BuiltinTool(pydantic.main.BaseModel):
505class BuiltinTool(BaseModel): 506 """ 507 A single callable tool within a builtin tool catalog entry. Represents one discrete function an agent can invoke. 508 """ 509 510 description: str | None = Field( 511 default=None, 512 description="Human-readable explanation of what the tool does. Surfaced to the agent as part of tool selection context. `null` when no description has been defined.", 513 ) 514 name: str = Field( 515 ..., 516 description='Machine-readable name of the tool as it is registered with the agent runtime, e.g. `"web_search"` or `"github_create_issue"`.', 517 )
A single callable tool within a builtin tool catalog entry. Represents one discrete function an agent can invoke.
class
BuiltinToolCatalogEntry(pydantic.main.BaseModel):
520class BuiltinToolCatalogEntry(BaseModel): 521 """ 522 A catalog entry describing a category of platform-provided (builtin) tools that can be enabled for an agent. Each entry groups one or more individual tools under a shared key, label, and configuration schema. 523 """ 524 525 config_schema: dict[str, Any] | None = Field( 526 default=None, 527 description="JSON Schema object describing the configuration options for this tool category. Clients should use this schema to render and validate configuration forms before submitting. `null` when no configuration is needed.", 528 ) 529 description: str | None = Field( 530 default=None, 531 description="Short prose description of what this tool category does. Suitable for display in setup UIs. `null` when no description has been defined.", 532 ) 533 instruction: str | None = Field( 534 default=None, 535 description="Additional guidance surfaced to the agent at runtime when this tool category is enabled. `null` when no custom instruction is set.", 536 ) 537 key: str = Field( 538 ..., 539 description='Unique slug identifying this tool category, e.g. `"web_search"` or `"github"`.', 540 ) 541 label: str | None = Field( 542 default=None, 543 description='Human-readable display name for the tool category, e.g. `"Web Search"`. `null` when no label has been assigned.', 544 ) 545 multi_instance_mode: str | None = Field( 546 default=None, 547 description='Controls whether multiple instances of this tool category may be enabled simultaneously. `"namespaced"` multiple instances allowed; each must carry a `name_prefix` to distinguish them. `"passthrough"` multiple instances allowed without a `name_prefix`; names are derived from the underlying source. `null` single-instance only.', 548 ) 549 providers: list[str] | None = Field( 550 default=None, 551 description='List of integration provider slugs that can back this tool category, e.g. `["github", "gitlab"]`. Empty when the tool is provider-agnostic.', 552 ) 553 requires_integration: bool | None = Field( 554 default=None, 555 description="Whether enabling this tool category requires the user to connect a third-party integration. `true` means at least one active integration of the appropriate type must exist before the tool can be used.", 556 ) 557 server_tool_type: str | None = Field( 558 default=None, 559 description="Internal type identifier used by the platform server when registering these tools. `null` for client-side-only tool categories.", 560 ) 561 tools: list[BuiltinTool] | None = Field( 562 default=None, 563 description="Array of individual tool definitions included in this category. Each entry describes a single callable tool with its own name and description.", 564 )
A catalog entry describing a category of platform-provided (builtin) tools that can be enabled for an agent. Each entry groups one or more individual tools under a shared key, label, and configuration schema.
config_schema: dict[str, typing.Any] | None =
None
JSON Schema object describing the configuration options for this tool category. Clients should use this schema to render and validate configuration forms before submitting. null when no configuration is needed.
description: str | None =
None
Short prose description of what this tool category does. Suitable for display in setup UIs. null when no description has been defined.
instruction: str | None =
None
Additional guidance surfaced to the agent at runtime when this tool category is enabled. null when no custom instruction is set.
key: str =
PydanticUndefined
Unique slug identifying this tool category, e.g. "web_search" or "github".
label: str | None =
None
Human-readable display name for the tool category, e.g. "Web Search". null when no label has been assigned.
multi_instance_mode: str | None =
None
Controls whether multiple instances of this tool category may be enabled simultaneously. "namespaced" multiple instances allowed; each must carry a name_prefix to distinguish them. "passthrough" multiple instances allowed without a name_prefix; names are derived from the underlying source. null single-instance only.
providers: list[str] | None =
None
List of integration provider slugs that can back this tool category, e.g. ["github", "gitlab"]. Empty when the tool is provider-agnostic.
requires_integration: bool | None =
None
Whether enabling this tool category requires the user to connect a third-party integration. true means at least one active integration of the appropriate type must exist before the tool can be used.
server_tool_type: str | None =
None
Internal type identifier used by the platform server when registering these tools. null for client-side-only tool categories.
class
ChannelAck(pydantic.main.BaseModel):
567class ChannelAck(BaseModel): 568 """ 569 Empty acknowledgement payload returned by channel message handlers that produce no data. The wire envelope is `{"status": "ok", "response": {}}`. 570 """ 571 572 pass
Empty acknowledgement payload returned by channel message handlers that produce no data. The wire envelope is {"status": "ok", "response": {}}.
class
MessageReaction(pydantic.main.BaseModel):
575class MessageReaction(BaseModel): 576 """ 577 A compact reaction record embedded in a message's `reactions` array, representing a single user's reaction to a message. 578 """ 579 580 payload: dict[str, Any] | None = Field( 581 default=None, 582 description='Type-specific reaction data. For `"emoji_reaction"` reactions, contains an `emoji` key with the Unicode emoji string (e.g., `" "`).', 583 ) 584 type: str = Field( 585 ..., 586 description='Reaction type identifier. Currently always `"emoji_reaction"` for emoji-based reactions.', 587 ) 588 user: str | None = Field( 589 default=None, description="Public ID of the user who added the reaction (`usr_...`)." 590 )
A compact reaction record embedded in a message's reactions array, representing a single user's reaction to a message.
payload: dict[str, typing.Any] | None =
None
Type-specific reaction data. For "emoji_reaction" reactions, contains an emoji key with the Unicode emoji string (e.g., " ").
class
Message(pydantic.main.BaseModel):
593class Message(BaseModel): 594 """ 595 A chat message posted in a thread, including its content, author, attachments, reactions, and optional reply metadata. 596 """ 597 598 actors: list[Actor] | None = Field( 599 default=None, 600 description="Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry.", 601 ) 602 agent: str | None = Field( 603 default=None, 604 description="ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", 605 ) 606 agent_mode: Literal["cli", "embedded"] | None = Field( 607 default=None, 608 description="Local agent execution mode for this message. One of `cli`, `embedded`, or `null` when the message was not created by a local agent execution path.", 609 ) 610 attachments: list[Attachment] | None = Field( 611 default=None, 612 description="Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments.", 613 ) 614 branched_thread: str | None = Field( 615 default=None, 616 description="ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", 617 ) 618 content: str | None = Field( 619 default=None, 620 description="Text content of the message. `null` for messages that contain only attachments.", 621 ) 622 created_at: datetime | None = Field( 623 default=None, description="When the message was posted (ISO 8601)." 624 ) 625 has_replies: bool | None = Field( 626 default=None, 627 description="Whether this message has at least one reply. Only present when explicitly requested or computed by the server.", 628 ) 629 id: str = Field(..., description="Message ID (`msg_...`).") 630 idempotency_key: str | None = Field( 631 default=None, 632 description="Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", 633 ) 634 legacy_agent: str | None = Field( 635 default=None, 636 description="Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", 637 ) 638 metadata: dict[str, Any] | None = Field( 639 default=None, 640 description="Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set.", 641 ) 642 org: str | None = Field( 643 default=None, description="ID of the organization that owns this message (`org_...`)." 644 ) 645 reactions: list[MessageReaction] | None = Field( 646 default=None, 647 description="Emoji and other reactions added to this message by users. Empty array if no reactions have been added or the association is not preloaded.", 648 ) 649 rendering_mode: str | None = Field( 650 default=None, 651 description='Display hint for how the message should be rendered. One of `"reply"`, `"direct"`, or `"inline"`. `null` for user-authored messages, which are always rendered as standard replies.', 652 ) 653 replies: list[dict[str, Any]] | None = Field( 654 default=None, 655 description="Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message.", 656 ) 657 replies_after_cursor: str | None = Field( 658 default=None, 659 description="Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", 660 ) 661 replies_before_cursor: str | None = Field( 662 default=None, 663 description="Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", 664 ) 665 reply_count: int | None = Field( 666 default=None, 667 description="Total number of direct replies to this message. Only present when explicitly requested or computed by the server.", 668 ) 669 reply_to: dict[str, Any] | None = Field( 670 default=None, 671 description="The parent message this message is a reply to, expanded as a full message object when loaded. `null` if this is a top-level message or the association is not preloaded.", 672 ) 673 sandbox: str | None = Field( 674 default=None, 675 description="ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", 676 ) 677 team: str | None = Field( 678 default=None, 679 description="ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", 680 ) 681 thread: str | None = Field( 682 default=None, 683 description="ID of the thread this message belongs to (`thr_...`). `null` for messages not yet associated with a thread.", 684 ) 685 user: str | None = Field( 686 default=None, 687 description="The human user who sent this message. Returns a public ID string (`usr_...`) when the association is not preloaded, or an expanded user object when it is. `null` for messages sent by agents.", 688 )
A chat message posted in a thread, including its content, author, attachments, reactions, and optional reply metadata.
Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry.
agent: str | None =
None
ID of the agent user that sent this message (agi_...). null for messages sent by human users.
agent_mode: Optional[Literal['cli', 'embedded']] =
None
Local agent execution mode for this message. One of cli, embedded, or null when the message was not created by a local agent execution path.
Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments.
branched_thread: str | None =
None
ID of the thread that was branched from this message (thr_...). null if this message has not spawned a branch thread.
content: str | None =
None
Text content of the message. null for messages that contain only attachments.
has_replies: bool | None =
None
Whether this message has at least one reply. Only present when explicitly requested or computed by the server.
idempotency_key: str | None =
None
Client-supplied idempotency key used to deduplicate message sends. null if the sender did not provide one.
legacy_agent: str | None =
None
Identifier of the legacy chat agent that sent this message, if applicable. null for messages sent by users or modern agent users.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set.
Emoji and other reactions added to this message by users. Empty array if no reactions have been added or the association is not preloaded.
rendering_mode: str | None =
None
Display hint for how the message should be rendered. One of "reply", "direct", or "inline". null for user-authored messages, which are always rendered as standard replies.
replies: list[dict[str, typing.Any]] | None =
None
Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message.
replies_after_cursor: str | None =
None
Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.
replies_before_cursor: str | None =
None
Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.
reply_count: int | None =
None
Total number of direct replies to this message. Only present when explicitly requested or computed by the server.
reply_to: dict[str, typing.Any] | None =
None
The parent message this message is a reply to, expanded as a full message object when loaded. null if this is a top-level message or the association is not preloaded.
sandbox: str | None =
None
ID of the developer sandbox this message belongs to (dsb_...). null for non-sandbox messages.
team: str | None =
None
ID of the team this message is scoped to (tem_...). null if the message is not team-scoped.
class
ComputerExecResult(pydantic.main.BaseModel):
691class ComputerExecResult(BaseModel): 692 """ 693 The result of executing a shell command on an agent's computer environment. Contains the captured output and the process exit code. 694 """ 695 696 exit_code: int | None = Field( 697 default=None, 698 description="The UNIX exit code returned by the process. `0` indicates success; any non-zero value indicates an error. `null` if the process did not terminate normally.", 699 ) 700 output: str | None = Field( 701 default=None, 702 description="The combined stdout and stderr output produced by the command. `null` if the command produced no output.", 703 )
The result of executing a shell command on an agent's computer environment. Contains the captured output and the process exit code.
class
ContextDocument(pydantic.main.BaseModel):
706class ContextDocument(BaseModel): 707 """ 708 A context document stored within a context source. Carries metadata and size information only; retrieve the full text content via the `/content` endpoint. 709 """ 710 711 agent: str | None = Field( 712 default=None, 713 description="ID of the agent that owns this document (`agi_...`). `null` if owned by a user or team.", 714 ) 715 created_at: datetime | None = Field( 716 default=None, description="When the document was created (ISO 8601)." 717 ) 718 file: str | None = Field( 719 default=None, 720 description="ID of the backing storage file (`fil_...`) when the document is file-backed. `null` for inline documents.", 721 ) 722 id: str = Field(..., description="Context document ID (`cdo_...`).") 723 metadata: dict[str, Any] | None = Field( 724 default=None, 725 description="Arbitrary key-value metadata attached to the document. Shape varies by source type.", 726 ) 727 source: str | None = Field( 728 default=None, description="ID of the context source this document belongs to (`cso_...`)." 729 ) 730 team: str | None = Field( 731 default=None, 732 description="ID of the team that owns this document (`tem_...`). `null` if owned by a user or agent.", 733 ) 734 title: str | None = Field( 735 default=None, 736 description="Human-readable display title of the document. `null` if no title has been set.", 737 ) 738 total_lines: int | None = Field( 739 default=None, 740 description="Total number of lines in the document's text content. `0` if the document has no content.", 741 ) 742 total_size: int | None = Field( 743 default=None, 744 description="Total byte size of the document's text content. `0` if the document has no content.", 745 ) 746 updated_at: datetime | None = Field( 747 default=None, description="When the document was last modified (ISO 8601)." 748 ) 749 user: str | None = Field( 750 default=None, 751 description="ID of the user that owns this document (`usr_...`). `null` if owned by a team or agent.", 752 )
A context document stored within a context source. Carries metadata and size information only; retrieve the full text content via the /content endpoint.
agent: str | None =
None
ID of the agent that owns this document (agi_...). null if owned by a user or team.
file: str | None =
None
ID of the backing storage file (fil_...) when the document is file-backed. null for inline documents.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata attached to the document. Shape varies by source type.
team: str | None =
None
ID of the team that owns this document (tem_...). null if owned by a user or agent.
title: str | None =
None
Human-readable display title of the document. null if no title has been set.
total_lines: int | None =
None
Total number of lines in the document's text content. 0 if the document has no content.
class
ContextDocumentContent(pydantic.main.BaseModel):
755class ContextDocumentContent(BaseModel): 756 """ 757 The text content of a context document, optionally sliced by line or byte range. Includes totals and slice boundary fields for the requested unit. 758 """ 759 760 content: str = Field( 761 ..., 762 description="Text of the document. Contains the full content when no `offset`/`limit` was requested, or only the requested slice otherwise.", 763 ) 764 end_byte: int | None = Field( 765 default=None, 766 description='Zero-based exclusive index of the last byte in `content` (i.e. the slice covers bytes `start_byte..end_byte-1`). Populated only when `unit` is `"bytes"`; `null` otherwise.', 767 ) 768 end_line: int | None = Field( 769 default=None, 770 description='1-indexed line number of the last line included in `content` (i.e. the slice covers lines `start_line` through `end_line` inclusive). Populated only when `unit` is `"lines"`; `null` otherwise.', 771 ) 772 id: str = Field(..., description="Context document ID (`cdo_...`).") 773 limit: int | None = Field( 774 default=None, 775 description="The `limit` value echoed from the request. `null` when no limit was requested.", 776 ) 777 metadata: dict[str, Any] | None = Field( 778 default=None, 779 description="Arbitrary key-value metadata attached to the document, such as source URL or author. `null` if no metadata was recorded.", 780 ) 781 offset: int | None = Field( 782 default=None, 783 description="The `offset` value echoed from the request. `null` when no offset was requested.", 784 ) 785 start_byte: int | None = Field( 786 default=None, 787 description='Zero-based index of the first byte included in `content`. Populated only when `unit` is `"bytes"`; `null` otherwise.', 788 ) 789 start_line: int | None = Field( 790 default=None, 791 description='1-indexed line number of the first line included in `content`. Populated only when `unit` is `"lines"`; `null` otherwise.', 792 ) 793 title: str | None = Field( 794 default=None, 795 description="Human-readable display title of the document. `null` if the document has no title set.", 796 ) 797 total_lines: int = Field( 798 ..., 799 description="Total number of lines in the document's full content, regardless of any slice.", 800 ) 801 total_size: int = Field( 802 ..., description="Total byte size of the document's full content, regardless of any slice." 803 ) 804 unit: str | None = Field( 805 default=None, 806 description='Slice unit used when `offset` and `limit` were provided. One of `"lines"` (default) or `"bytes"`. `null` when no slice was requested.', 807 )
The text content of a context document, optionally sliced by line or byte range. Includes totals and slice boundary fields for the requested unit.
end_line: int | None =
None
1-indexed line number of the last line included in content (i.e. the slice covers lines start_line through end_line inclusive). Populated only when unit is "lines"; null otherwise.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata attached to the document, such as source URL or author. null if no metadata was recorded.
offset: int | None =
None
The offset value echoed from the request. null when no offset was requested.
title: str | None =
None
Human-readable display title of the document. null if the document has no title set.
total_lines: int =
PydanticUndefined
Total number of lines in the document's full content, regardless of any slice.
class
ContextIngestion(pydantic.main.BaseModel):
810class ContextIngestion(BaseModel): 811 """ 812 A context ingestion job that processes a context source and populates its documents. Tracks status and timing from submission through completion or failure. 813 """ 814 815 agent: str | None = Field( 816 default=None, 817 description="ID of the agent that initiated this ingestion (`agi_...`). `null` if initiated by a user.", 818 ) 819 completed_at: datetime | None = Field( 820 default=None, 821 description="When the ingestion job finished, either successfully or with a failure. `null` if still in progress.", 822 ) 823 created_at: datetime | None = Field( 824 default=None, description="When the ingestion was submitted (ISO 8601)." 825 ) 826 error: dict[str, Any] | None = Field( 827 default=None, 828 description='Structured error details when the ingestion has `status: "failed"`. `null` for any other status.', 829 ) 830 id: str = Field(..., description="Context ingestion ID (`cig_...`).") 831 metadata: dict[str, Any] | None = Field( 832 default=None, 833 description="Arbitrary key-value metadata associated with this ingestion run. Shape is caller-defined.", 834 ) 835 source: str | None = Field( 836 default=None, 837 description="ID of the context source being ingested (`cso_...`). `null` if the source has been deleted.", 838 ) 839 started_at: datetime | None = Field( 840 default=None, 841 description="When the ingestion job began processing. `null` if the job is still pending.", 842 ) 843 status: str = Field( 844 ..., 845 description='Current processing status. One of `"pending"`, `"running"`, `"awaiting_callback"`, `"succeeded"`, or `"failed"`.', 846 ) 847 team: str | None = Field( 848 default=None, 849 description="ID of the team that owns this ingestion (`tem_...`). `null` if owned by a user or agent.", 850 ) 851 updated_at: datetime | None = Field( 852 default=None, description="When the ingestion record was last updated (ISO 8601)." 853 ) 854 user: str | None = Field( 855 default=None, 856 description="ID of the user that initiated this ingestion (`usr_...`). `null` if initiated by an agent.", 857 )
A context ingestion job that processes a context source and populates its documents. Tracks status and timing from submission through completion or failure.
agent: str | None =
None
ID of the agent that initiated this ingestion (agi_...). null if initiated by a user.
completed_at: datetime.datetime | None =
None
When the ingestion job finished, either successfully or with a failure. null if still in progress.
error: dict[str, typing.Any] | None =
None
Structured error details when the ingestion has status: "failed". null for any other status.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata associated with this ingestion run. Shape is caller-defined.
source: str | None =
None
ID of the context source being ingested (cso_...). null if the source has been deleted.
started_at: datetime.datetime | None =
None
When the ingestion job began processing. null if the job is still pending.
status: str =
PydanticUndefined
Current processing status. One of "pending", "running", "awaiting_callback", "succeeded", or "failed".
class
CustomObject(pydantic.main.BaseModel):
860class CustomObject(BaseModel): 861 """ 862 A custom object belonging to an organization. Custom objects store arbitrary structured data defined by a schema type and are scoped to an org, team, or user. 863 """ 864 865 created_at: datetime | None = Field( 866 default=None, description="When the custom object was created (ISO 8601)." 867 ) 868 fields: dict[str, Any] | None = Field( 869 default=None, 870 description="Map of field names to their current values as defined by the object's schema type.", 871 ) 872 id: str = Field(..., description="Unique identifier for the custom object (`cobj_...`).") 873 org: str | None = Field( 874 default=None, description="ID of the organization this object belongs to (`org_...`)." 875 ) 876 row_key: str | None = Field( 877 default=None, 878 description="An optional stable key used to identify this object by a caller-controlled string rather than its generated ID. `null` if not set.", 879 ) 880 sandbox: str | None = Field( 881 default=None, 882 description="ID of the sandbox environment this object is scoped to (`dsb_...`). `null` for production objects.", 883 ) 884 schema_type: str | None = Field( 885 default=None, 886 description="The lookup key of the schema type that defines this object's field structure. `null` if the schema type has not been set.", 887 ) 888 team: str | None = Field( 889 default=None, 890 description="ID of the team that owns this object (`tem_...`). `null` if the object is not team-scoped.", 891 ) 892 updated_at: datetime | None = Field( 893 default=None, 894 description="When the custom object was last modified (ISO 8601). `null` if the object has never been updated after creation.", 895 ) 896 user: str | None = Field( 897 default=None, 898 description="ID of the user that owns this object (`usr_...`). `null` if the object is not user-scoped.", 899 ) 900 version: int | None = Field( 901 default=None, 902 description="Optimistic concurrency version of the object. Increments with each successful update; pass this value in write operations to detect conflicting changes.", 903 )
A custom object belonging to an organization. Custom objects store arbitrary structured data defined by a schema type and are scoped to an org, team, or user.
fields: dict[str, typing.Any] | None =
None
Map of field names to their current values as defined by the object's schema type.
row_key: str | None =
None
An optional stable key used to identify this object by a caller-controlled string rather than its generated ID. null if not set.
sandbox: str | None =
None
ID of the sandbox environment this object is scoped to (dsb_...). null for production objects.
schema_type: str | None =
None
The lookup key of the schema type that defines this object's field structure. null if the schema type has not been set.
team: str | None =
None
ID of the team that owns this object (tem_...). null if the object is not team-scoped.
updated_at: datetime.datetime | None =
None
When the custom object was last modified (ISO 8601). null if the object has never been updated after creation.
class
CustomObjectListResponse(pydantic.main.BaseModel):
906class CustomObjectListResponse(BaseModel): 907 """ 908 A paginated page of custom objects returned by a list operation. Use the pagination fields to navigate through result sets. 909 """ 910 911 data: list[CustomObject] = Field( 912 ..., description="Array of custom objects for the current page." 913 ) 914 has_next: bool = Field( 915 ..., 916 description="`true` if a subsequent page of results exists; `false` if this is the last page.", 917 ) 918 has_prev: bool = Field( 919 ..., 920 description="`true` if a preceding page of results exists; `false` if this is the first page.", 921 ) 922 page: int = Field(..., description="The current page number (1-indexed).") 923 page_size: int = Field(..., description="Maximum number of results returned per page.") 924 total_entries: int = Field( 925 ..., description="Total number of custom objects matching the query across all pages." 926 ) 927 total_pages: int = Field( 928 ..., description="Total number of pages available for the current query." 929 )
A paginated page of custom objects returned by a list operation. Use the pagination fields to navigate through result sets.
has_next: bool =
PydanticUndefined
true if a subsequent page of results exists; false if this is the last page.
has_prev: bool =
PydanticUndefined
true if a preceding page of results exists; false if this is the first page.
class
CustomObjectUpdateFieldsResponse(pydantic.main.BaseModel):
932class CustomObjectUpdateFieldsResponse(BaseModel): 933 """ 934 Response returned after updating one or more fields on a custom object. Confirms the object that was modified and the field values that were applied. 935 """ 936 937 fields: dict[str, Any] = Field( 938 ..., 939 description="Map of field names to their new values as applied during the update. Only the fields that were included in the update request are present.", 940 ) 941 id: str = Field(..., description="ID of the custom object that was updated (`cobj_...`).")
Response returned after updating one or more fields on a custom object. Confirms the object that was modified and the field values that were applied.
class
DeviceAuthorizationResponse(pydantic.main.BaseModel):
944class DeviceAuthorizationResponse(BaseModel): 945 """ 946 The initial response from an OAuth 2.0 Device Authorization Grant request, containing the codes and URIs needed to complete device authentication. 947 """ 948 949 device_code: str = Field( 950 ..., 951 description="Opaque code identifying this device authorization session. Pass this value when polling the token endpoint; do not display it to the user.", 952 ) 953 expires_in: int = Field( 954 ..., 955 description="Number of seconds until the `device_code` and `user_code` expire. After expiry the user must restart the authorization flow.", 956 ) 957 interval: int = Field( 958 ..., 959 description="Minimum number of seconds to wait between polling attempts on the token endpoint. Polling more frequently will result in a `slow_down` error.", 960 ) 961 user_code: str = Field( 962 ..., 963 description="Short alphanumeric code the user must enter at `verification_uri` to authorize the device.", 964 ) 965 verification_uri: str = Field( 966 ..., 967 description="URL the user visits to enter the `user_code` and approve the authorization request.", 968 ) 969 verification_uri_complete: str = Field( 970 ..., 971 description="Full verification URL with the `user_code` pre-filled as a query parameter. Display this as a QR code or deep link to reduce manual entry.", 972 )
The initial response from an OAuth 2.0 Device Authorization Grant request, containing the codes and URIs needed to complete device authentication.
device_code: str =
PydanticUndefined
Opaque code identifying this device authorization session. Pass this value when polling the token endpoint; do not display it to the user.
expires_in: int =
PydanticUndefined
Number of seconds until the device_code and user_code expire. After expiry the user must restart the authorization flow.
interval: int =
PydanticUndefined
Minimum number of seconds to wait between polling attempts on the token endpoint. Polling more frequently will result in a slow_down error.
user_code: str =
PydanticUndefined
Short alphanumeric code the user must enter at verification_uri to authorize the device.
verification_uri: str =
PydanticUndefined
URL the user visits to enter the user_code and approve the authorization request.
verification_uri_complete: str =
PydanticUndefined
Full verification URL with the user_code pre-filled as a query parameter. Display this as a QR code or deep link to reduce manual entry.
class
DeviceAuthorizationStatusResponse(pydantic.main.BaseModel):
975class DeviceAuthorizationStatusResponse(BaseModel): 976 """ 977 The result of a completed OAuth 2.0 Device Authorization flow, indicating whether the user approved or denied the device's access request. 978 """ 979 980 status: str = Field( 981 ..., 982 description='Outcome of the device authorization request. One of `"approved"` (the user granted access) or `"denied"` (the user rejected or cancelled the request).', 983 )
The result of a completed OAuth 2.0 Device Authorization flow, indicating whether the user approved or denied the device's access request.
class
AgentHealthAction(pydantic.main.BaseModel):
986class AgentHealthAction(BaseModel): 987 """ 988 A single actionable item in an agent's health or setup checklist, carrying the structured data needed to render the item and deep-link to the resolution flow. 989 """ 990 991 agent: str | None = Field( 992 default=None, 993 description="ID of the agent this action is scoped to (`agt_...`). `null` for org-level actions.", 994 ) 995 app: str | None = Field( 996 default=None, 997 description="ID of the application this action is associated with (`app_...`). `null` when not app-scoped.", 998 ) 999 created_at: datetime | None = Field( 1000 default=None, description="When this health action was first created (ISO 8601)." 1001 ) 1002 depends_on: list[str] | None = Field( 1003 default=None, 1004 description='IDs of other health actions that must reach `"completed"` status before this action can be started. Empty array when there are no dependencies.', 1005 ) 1006 description: str | None = Field( 1007 default=None, 1008 description="Longer Markdown-formatted explanation of what the action requires and why. `null` if not provided.", 1009 ) 1010 id: str = Field(..., description="Health action ID (`aha_...`).") 1011 kind: str = Field( 1012 ..., 1013 description='Category of action to take. One of `"env_var"` (set a secret), `"install"` (complete an agent installation, e.g. a GitHub App), `"custom"` (agent-defined step), or `"integration"` (authorize an OAuth-backed MCP server integration).', 1014 ) 1015 last_verified_at: datetime | None = Field( 1016 default=None, 1017 description="When the verifier last ran for this action (ISO 8601). `null` until the verifier has been invoked at least once.", 1018 ) 1019 last_verifier_message: str | None = Field( 1020 default=None, 1021 description="Human-readable output from the most recent verifier run. `null` if the verifier has not run yet.", 1022 ) 1023 org: str | None = Field( 1024 default=None, 1025 description="ID of the organization this action is associated with (`org_...`). `null` when not org-scoped.", 1026 ) 1027 params: dict[str, Any] | None = Field( 1028 default=None, 1029 description='Kind-specific structured data used to construct the deep-link for this action. For `"env_var"` actions includes `key` and `scope`; for `"install"` actions includes `installation_kind`; for `"integration"` actions includes `mcp_server_ref`, and when resolvable also includes `provider`, `integration_id` for OAuth handoff, and `connection_status` (`"connected"`, `"disconnected"`, or `"token_expired"`). Empty object `{}` when no additional parameters are needed.', 1030 ) 1031 required: bool = Field( 1032 ..., 1033 description="`true` if this action must be completed before the agent is considered fully operational and counts toward the blocking checklist progress bar.", 1034 ) 1035 sort_order: int = Field( 1036 ..., description="Display order within the same `source` group. Lower values appear first." 1037 ) 1038 source: str = Field( 1039 ..., 1040 description='Lifecycle stage that produced this action. One of `"setup"` (post-install checklist item) or `"health"` (probe-detected issue).', 1041 ) 1042 status: str = Field( 1043 ..., 1044 description='Current resolution state. One of `"pending"` (not yet completed), `"completed"` (resolved), `"skipped"` (dismissed by the user), or `"degraded"` (completed but the verifier is reporting a warning).', 1045 ) 1046 title: str = Field( 1047 ..., 1048 description="Short display label for this action, intended for use as a checklist item heading.", 1049 ) 1050 updated_at: datetime | None = Field( 1051 default=None, description="When this health action was last modified (ISO 8601)." 1052 ) 1053 verify_config: dict[str, Any] | None = Field( 1054 default=None, 1055 description="Configuration for the action's verifier step. Contains at minimum a `type` field that indicates which verification affordance to render. Server-internal fields are stripped before this is returned.", 1056 )
A single actionable item in an agent's health or setup checklist, carrying the structured data needed to render the item and deep-link to the resolution flow.
agent: str | None =
None
ID of the agent this action is scoped to (agt_...). null for org-level actions.
app: str | None =
None
ID of the application this action is associated with (app_...). null when not app-scoped.
depends_on: list[str] | None =
None
IDs of other health actions that must reach "completed" status before this action can be started. Empty array when there are no dependencies.
description: str | None =
None
Longer Markdown-formatted explanation of what the action requires and why. null if not provided.
kind: str =
PydanticUndefined
Category of action to take. One of "env_var" (set a secret), "install" (complete an agent installation, e.g. a GitHub App), "custom" (agent-defined step), or "integration" (authorize an OAuth-backed MCP server integration).
last_verified_at: datetime.datetime | None =
None
When the verifier last ran for this action (ISO 8601). null until the verifier has been invoked at least once.
last_verifier_message: str | None =
None
Human-readable output from the most recent verifier run. null if the verifier has not run yet.
org: str | None =
None
ID of the organization this action is associated with (org_...). null when not org-scoped.
params: dict[str, typing.Any] | None =
None
Kind-specific structured data used to construct the deep-link for this action. For "env_var" actions includes key and scope; for "install" actions includes installation_kind; for "integration" actions includes mcp_server_ref, and when resolvable also includes provider, integration_id for OAuth handoff, and connection_status ("connected", "disconnected", or "token_expired"). Empty object {} when no additional parameters are needed.
required: bool =
PydanticUndefined
true if this action must be completed before the agent is considered fully operational and counts toward the blocking checklist progress bar.
sort_order: int =
PydanticUndefined
Display order within the same source group. Lower values appear first.
source: str =
PydanticUndefined
Lifecycle stage that produced this action. One of "setup" (post-install checklist item) or "health" (probe-detected issue).
status: str =
PydanticUndefined
Current resolution state. One of "pending" (not yet completed), "completed" (resolved), "skipped" (dismissed by the user), or "degraded" (completed but the verifier is reporting a warning).
class
HealthActionListResponse(pydantic.main.BaseModel):
1059class HealthActionListResponse(BaseModel): 1060 """ 1061 List response containing agent health actions for a given agent or organization. 1062 """ 1063 1064 data: list[AgentHealthAction] = Field( 1065 ..., 1066 description="Array of agent health action objects representing setup checklist items and probe-detected issues.", 1067 )
List response containing agent health actions for a given agent or organization.
class
Installation(pydantic.main.BaseModel):
1070class Installation(BaseModel): 1071 """ 1072 An installation representing a connection between an agent and an external service or enablement channel. Tracks configuration, lifecycle state, and any bound integration. 1073 """ 1074 1075 agent: str | None = Field( 1076 default=None, 1077 description="ID of the agent that owns this installation (`agi_...`). `null` if the installation has no agent owner.", 1078 ) 1079 config: dict[str, Any] | None = Field( 1080 default=None, 1081 description="Kind-specific configuration object for this installation. Shape depends on the `kind` value. `null` if the kind requires no configuration.", 1082 ) 1083 created_at: datetime | None = Field( 1084 default=None, description="When the installation was created (ISO 8601)." 1085 ) 1086 id: str = Field(..., description="Installation ID (`cin_...`).") 1087 kind: str | None = Field( 1088 default=None, 1089 description='Slug identifying the type of external service this installation connects to, e.g. `"enablement/github_app"` or `"integration/gmail"`. `null` if not set.', 1090 ) 1091 lookup_key: str | None = Field( 1092 default=None, 1093 description="Caller-assigned stable identifier for this installation, used to reference it in knowledge search `source_refs`. `null` if no lookup key was provided at creation time.", 1094 ) 1095 shared_integration: str | None = Field( 1096 default=None, 1097 description="ID of the shared org- or app-level integration bound to this installation (`int_...`). `null` if no integration has been bound.", 1098 ) 1099 state: str | None = Field( 1100 default=None, 1101 description='Current lifecycle state of the installation. One of `"pending"`, `"active"`, `"paused"`, or `"error"`. `"error"` indicates the installation was suspended due to a policy or compliance issue and requires attention.', 1102 ) 1103 status_payload: dict[str, Any] | None = Field( 1104 default=None, 1105 description="Provider-supplied status detail for this installation, set during activation or event processing. `null` if no status has been reported.", 1106 ) 1107 updated_at: datetime | None = Field( 1108 default=None, description="When the installation record was last updated (ISO 8601)." 1109 )
An installation representing a connection between an agent and an external service or enablement channel. Tracks configuration, lifecycle state, and any bound integration.
agent: str | None =
None
ID of the agent that owns this installation (agi_...). null if the installation has no agent owner.
config: dict[str, typing.Any] | None =
None
Kind-specific configuration object for this installation. Shape depends on the kind value. null if the kind requires no configuration.
kind: str | None =
None
Slug identifying the type of external service this installation connects to, e.g. "enablement/github_app" or "integration/gmail". null if not set.
lookup_key: str | None =
None
Caller-assigned stable identifier for this installation, used to reference it in knowledge search source_refs. null if no lookup key was provided at creation time.
state: str | None =
None
Current lifecycle state of the installation. One of "pending", "active", "paused", or "error". "error" indicates the installation was suspended due to a policy or compliance issue and requires attention.
class
InstallationKind(pydantic.main.BaseModel):
1112class InstallationKind(BaseModel): 1113 """ 1114 A supported installation kind describing a category of external service or enablement channel an agent can be connected to. 1115 """ 1116 1117 accepts_sources: bool | None = Field( 1118 default=None, 1119 description="When `true`, sources can be attached to installations of this kind to supply additional context to the agent.", 1120 ) 1121 category: str | None = Field( 1122 default=None, 1123 description='Grouping category for UI display purposes, e.g. `"enablement"` or `"integration"`. `null` if uncategorized.', 1124 ) 1125 config_schema: dict[str, Any] | None = Field( 1126 default=None, 1127 description="JSON Schema object describing the shape of the `config` parameter accepted when creating or updating an installation of this kind. `null` if the kind accepts no configuration.", 1128 ) 1129 description: str | None = Field( 1130 default=None, 1131 description="Short prose description of what this kind connects to and how it is used. `null` if no description is defined.", 1132 ) 1133 kind: str = Field( 1134 ..., 1135 description='Unique slug identifying this installation kind, e.g. `"enablement/github_app"`, `"integration/gmail"`, or `"web/site"`. Pass this value as `kind` when creating an installation.', 1136 ) 1137 label: str | None = Field( 1138 default=None, 1139 description='Human-readable display name for this kind, e.g. `"GitHub App"`. `null` if the kind has no label defined.', 1140 ) 1141 provider: str | None = Field( 1142 default=None, 1143 description='Identifier of the external provider this kind connects to, e.g. `"github"` or `"slack"`. `null` for kinds with no specific provider.', 1144 ) 1145 requires_integration: bool | None = Field( 1146 default=None, 1147 description="When `true`, this kind requires an integration to be provided (either inline or via `shared_integration`) before the installation can be activated.", 1148 )
A supported installation kind describing a category of external service or enablement channel an agent can be connected to.
accepts_sources: bool | None =
None
When true, sources can be attached to installations of this kind to supply additional context to the agent.
category: str | None =
None
Grouping category for UI display purposes, e.g. "enablement" or "integration". null if uncategorized.
config_schema: dict[str, typing.Any] | None =
None
JSON Schema object describing the shape of the config parameter accepted when creating or updating an installation of this kind. null if the kind accepts no configuration.
description: str | None =
None
Short prose description of what this kind connects to and how it is used. null if no description is defined.
kind: str =
PydanticUndefined
Unique slug identifying this installation kind, e.g. "enablement/github_app", "integration/gmail", or "web/site". Pass this value as kind when creating an installation.
label: str | None =
None
Human-readable display name for this kind, e.g. "GitHub App". null if the kind has no label defined.
class
InstallationKindListResponse(pydantic.main.BaseModel):
1151class InstallationKindListResponse(BaseModel): 1152 """ 1153 List response containing all available installation kinds that can be used when configuring an agent installation. 1154 """ 1155 1156 data: list[InstallationKind] = Field( 1157 ..., 1158 description="Array of installation kind objects describing the available integration types and their configuration requirements.", 1159 )
List response containing all available installation kinds that can be used when configuring an agent installation.
class
InstallationListResponse(pydantic.main.BaseModel):
1162class InstallationListResponse(BaseModel): 1163 """ 1164 Paginated list response containing installation objects for an agent. 1165 """ 1166 1167 data: list[Installation] = Field( 1168 ..., description="Array of installation objects returned for the current page." 1169 )
Paginated list response containing installation objects for an agent.
class
InstallationSource(pydantic.main.BaseModel):
1172class InstallationSource(BaseModel): 1173 """ 1174 A source attached to an installation that supplies content for the agent's context. Sources are processed asynchronously after creation. 1175 """ 1176 1177 agent: str | None = Field( 1178 default=None, 1179 description="ID of the agent that owns this source (`agi_...`). `null` if the source is not agent-owned.", 1180 ) 1181 context_installation: str | None = Field( 1182 default=None, 1183 description="ID of the installation this source belongs to (`cin_...`). `null` if the source is not attached to an installation.", 1184 ) 1185 created_at: datetime | None = Field( 1186 default=None, description="When the source was created (ISO 8601)." 1187 ) 1188 id: str = Field(..., description="Source ID (`cso_...`).") 1189 metadata: dict[str, Any] | None = Field( 1190 default=None, 1191 description="Arbitrary key-value metadata associated with this source. Shape is caller-defined. `null` if no metadata was set.", 1192 ) 1193 parent_source: str | None = Field( 1194 default=None, 1195 description="ID of the parent source (`cso_...`) when this source was derived from another source. `null` for top-level sources.", 1196 ) 1197 payload: dict[str, Any] | None = Field( 1198 default=None, 1199 description="Type-specific payload provided when the source was created. The shape depends on the `type` value. `null` if no payload was supplied.", 1200 ) 1201 state: str | None = Field( 1202 default=None, 1203 description='Current lifecycle state of this source. One of `"active"` (ingestion running normally) or `"paused"` (ingestion suspended). Note that per-run ingestion progress is tracked separately and is not exposed on this field.', 1204 ) 1205 team: str | None = Field( 1206 default=None, 1207 description="ID of the team associated with this source (`tem_...`). `null` if the source has no team association.", 1208 ) 1209 thread: str | None = Field( 1210 default=None, 1211 description="ID of the conversation thread linked to this source (`thr_...`). `null` if the source is not thread-scoped.", 1212 ) 1213 type: str | None = Field( 1214 default=None, 1215 description='Slug identifying the kind of content this source provides, e.g. `"file/document"` or `"web/link"`. `null` if the type is not set.', 1216 ) 1217 updated_at: datetime | None = Field( 1218 default=None, description="When the source record was last updated (ISO 8601)." 1219 ) 1220 user: str | None = Field( 1221 default=None, 1222 description="ID of the user associated with this source (`usr_...`). `null` if the source has no user association.", 1223 )
A source attached to an installation that supplies content for the agent's context. Sources are processed asynchronously after creation.
agent: str | None =
None
ID of the agent that owns this source (agi_...). null if the source is not agent-owned.
context_installation: str | None =
None
ID of the installation this source belongs to (cin_...). null if the source is not attached to an installation.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata associated with this source. Shape is caller-defined. null if no metadata was set.
parent_source: str | None =
None
ID of the parent source (cso_...) when this source was derived from another source. null for top-level sources.
payload: dict[str, typing.Any] | None =
None
Type-specific payload provided when the source was created. The shape depends on the type value. null if no payload was supplied.
state: str | None =
None
Current lifecycle state of this source. One of "active" (ingestion running normally) or "paused" (ingestion suspended). Note that per-run ingestion progress is tracked separately and is not exposed on this field.
team: str | None =
None
ID of the team associated with this source (tem_...). null if the source has no team association.
thread: str | None =
None
ID of the conversation thread linked to this source (thr_...). null if the source is not thread-scoped.
class
InstallationSourceListResponse(pydantic.main.BaseModel):
1226class InstallationSourceListResponse(BaseModel): 1227 """ 1228 Paginated list response containing installation source objects attached to an installation. 1229 """ 1230 1231 data: list[InstallationSource] = Field( 1232 ..., description="Array of installation source objects returned for the current page." 1233 )
Paginated list response containing installation source objects attached to an installation.
class
KeyValueStorageEntry(pydantic.main.BaseModel):
1236class KeyValueStorageEntry(BaseModel): 1237 """ 1238 A single key-value storage entry belonging to a user. Represents one key/value pair written to a user's isolated storage namespace within an app. 1239 """ 1240 1241 created_at: datetime | None = Field( 1242 default=None, 1243 description="When this storage entry was first created (ISO 8601). `null` if not yet persisted.", 1244 ) 1245 key: str = Field(..., description="The string key used to store and look up this entry.") 1246 updated_at: datetime | None = Field( 1247 default=None, 1248 description="When this storage entry was last updated (ISO 8601). `null` if not yet persisted.", 1249 ) 1250 user: str = Field(..., description="ID of the user who owns this storage entry (`usr_...`).") 1251 value: str = Field(..., description="The string value stored under `key` for this user.")
A single key-value storage entry belonging to a user. Represents one key/value pair written to a user's isolated storage namespace within an app.
created_at: datetime.datetime | None =
None
When this storage entry was first created (ISO 8601). null if not yet persisted.
class
KeyValueStorageEntryWithUser(pydantic.main.BaseModel):
1254class KeyValueStorageEntryWithUser(BaseModel): 1255 """ 1256 A key-value storage entry enriched with owner information. Developer and server-to-server callers receive `user_email` and `user_name` populated; end-user (user-JWT) callers receive those fields as `null`. 1257 """ 1258 1259 created_at: datetime = Field( 1260 ..., description="When this storage entry was first created (ISO 8601)." 1261 ) 1262 key: str = Field(..., description="The string key used to store and look up this entry.") 1263 updated_at: datetime = Field( 1264 ..., description="When this storage entry was last updated (ISO 8601)." 1265 ) 1266 user: str = Field(..., description="ID of the user who owns this storage entry (`usr_...`).") 1267 user_email: str | None = Field( 1268 default=None, 1269 description="Email address of the owning user. `null` for end-user (user-JWT) callers; populated for developer and server-to-server callers.", 1270 ) 1271 user_name: str | None = Field( 1272 default=None, 1273 description="Display name of the owning user. `null` for end-user (user-JWT) callers; populated for developer and server-to-server callers.", 1274 ) 1275 value: str = Field(..., description="The string value stored under `key` for this user.")
A key-value storage entry enriched with owner information. Developer and server-to-server callers receive user_email and user_name populated; end-user (user-JWT) callers receive those fields as null.
created_at: datetime.datetime =
PydanticUndefined
When this storage entry was first created (ISO 8601).
updated_at: datetime.datetime =
PydanticUndefined
When this storage entry was last updated (ISO 8601).
user_email: str | None =
None
Email address of the owning user. null for end-user (user-JWT) callers; populated for developer and server-to-server callers.
class
KeyValueStorageEntryPage(pydantic.main.BaseModel):
1278class KeyValueStorageEntryPage(BaseModel): 1279 """ 1280 Paginated response envelope for the dual-mode key-value storage list endpoint. End-user (user-JWT) callers receive only `data`; developer and server-to-server callers also receive pagination metadata fields. 1281 """ 1282 1283 data: list[KeyValueStorageEntryWithUser] = Field( 1284 ..., description="Array of key-value storage entries for the current page." 1285 ) 1286 has_next: bool | None = Field( 1287 default=None, 1288 description="Whether a subsequent page exists. `false` when the current page is the last page. Present only for developer and server-to-server callers.", 1289 ) 1290 has_prev: bool | None = Field( 1291 default=None, 1292 description="Whether a preceding page exists. `false` when the current page is the first page. Present only for developer and server-to-server callers.", 1293 ) 1294 page: int | None = Field( 1295 default=None, 1296 description="Current page number (1-indexed). Present only for developer and server-to-server callers.", 1297 ) 1298 page_size: int | None = Field( 1299 default=None, 1300 description="Maximum number of results returned per page. Present only for developer and server-to-server callers.", 1301 ) 1302 total_entries: int | None = Field( 1303 default=None, 1304 description="Total number of storage entries matching the applied filters across all pages. Present only for developer and server-to-server callers.", 1305 ) 1306 total_pages: int | None = Field( 1307 default=None, 1308 description="Total number of pages available given the current `page_size`. Present only for developer and server-to-server callers.", 1309 )
Paginated response envelope for the dual-mode key-value storage list endpoint. End-user (user-JWT) callers receive only data; developer and server-to-server callers also receive pagination metadata fields.
has_next: bool | None =
None
Whether a subsequent page exists. false when the current page is the last page. Present only for developer and server-to-server callers.
has_prev: bool | None =
None
Whether a preceding page exists. false when the current page is the first page. Present only for developer and server-to-server callers.
page: int | None =
None
Current page number (1-indexed). Present only for developer and server-to-server callers.
page_size: int | None =
None
Maximum number of results returned per page. Present only for developer and server-to-server callers.
total_entries: int | None =
None
Total number of storage entries matching the applied filters across all pages. Present only for developer and server-to-server callers.
total_pages: int | None =
None
Total number of pages available given the current page_size. Present only for developer and server-to-server callers.
class
KnowledgeSource(pydantic.main.BaseModel):
1312class KnowledgeSource(BaseModel): 1313 """ 1314 A knowledge source that ingests content into the knowledge base. Sources connect to external systems (e.g. Gmail, GitHub) and continuously or on-demand index items for search. 1315 """ 1316 1317 agent: str | None = Field( 1318 default=None, 1319 description="ID of the agent that owns this source (`agt_...`). `null` if owned by a human user or team.", 1320 ) 1321 context_installation: str | None = Field( 1322 default=None, 1323 description="ID of the context installation that provisioned this source (`cin_...`). `null` when the source was created directly rather than through an installation.", 1324 ) 1325 created_at: datetime | None = Field( 1326 default=None, description="When this knowledge source was created (ISO 8601)." 1327 ) 1328 id: str = Field(..., description="Knowledge source ID (`cso_...`).") 1329 metadata: dict[str, Any] | None = Field( 1330 default=None, 1331 description="Arbitrary key-value metadata attached to this source. Useful for storing caller-defined labels or references.", 1332 ) 1333 org: str | None = Field( 1334 default=None, 1335 description="ID of the organization this source belongs to (`org_...`). `null` if not scoped to an org.", 1336 ) 1337 parent_source: str | None = Field( 1338 default=None, 1339 description="ID of the parent knowledge source (`cso_...`) when this source was derived from another. `null` for top-level sources.", 1340 ) 1341 payload: dict[str, Any] | None = Field( 1342 default=None, 1343 description="Type-specific configuration object. The keys depend on the source `type`; see the create endpoint for the expected shape per type.", 1344 ) 1345 sandbox: str | None = Field( 1346 default=None, 1347 description="ID of the developer sandbox this source is scoped to (`sbx_...`). `null` outside sandbox contexts.", 1348 ) 1349 state: str = Field( 1350 ..., 1351 description='Current lifecycle state of the source. One of `"active"` (ingestion running normally) or `"paused"` (ingestion suspended).', 1352 ) 1353 team: str | None = Field( 1354 default=None, 1355 description="ID of the team that owns this source (`tea_...`). `null` if owned by a user, agent, or org.", 1356 ) 1357 thread: str | None = Field( 1358 default=None, 1359 description="ID of the chat thread this source is associated with (`thr_...`). `null` when not thread-scoped.", 1360 ) 1361 type: str = Field( 1362 ..., 1363 description='Source type identifier (e.g. `"gmail"`, `"github_activity"`). Determines the shape of `payload` and the ingestion behavior.', 1364 ) 1365 updated_at: datetime | None = Field( 1366 default=None, description="When this knowledge source was last modified (ISO 8601)." 1367 ) 1368 user: str | None = Field( 1369 default=None, 1370 description="ID of the user that owns this source (`usr_...`). `null` if owned by a team, agent, or org.", 1371 )
A knowledge source that ingests content into the knowledge base. Sources connect to external systems (e.g. Gmail, GitHub) and continuously or on-demand index items for search.
agent: str | None =
None
ID of the agent that owns this source (agt_...). null if owned by a human user or team.
context_installation: str | None =
None
ID of the context installation that provisioned this source (cin_...). null when the source was created directly rather than through an installation.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata attached to this source. Useful for storing caller-defined labels or references.
org: str | None =
None
ID of the organization this source belongs to (org_...). null if not scoped to an org.
parent_source: str | None =
None
ID of the parent knowledge source (cso_...) when this source was derived from another. null for top-level sources.
payload: dict[str, typing.Any] | None =
None
Type-specific configuration object. The keys depend on the source type; see the create endpoint for the expected shape per type.
sandbox: str | None =
None
ID of the developer sandbox this source is scoped to (sbx_...). null outside sandbox contexts.
state: str =
PydanticUndefined
Current lifecycle state of the source. One of "active" (ingestion running normally) or "paused" (ingestion suspended).
team: str | None =
None
ID of the team that owns this source (tea_...). null if owned by a user, agent, or org.
thread: str | None =
None
ID of the chat thread this source is associated with (thr_...). null when not thread-scoped.
type: str =
PydanticUndefined
Source type identifier (e.g. "gmail", "github_activity"). Determines the shape of payload and the ingestion behavior.
class
KnowledgeSourceKind(pydantic.main.BaseModel):
1374class KnowledgeSourceKind(BaseModel): 1375 """ 1376 Describes a single knowledge source kind that can be created through the public API. Use the `type` value when creating a new knowledge source. 1377 """ 1378 1379 description: str | None = Field( 1380 default=None, 1381 description="Short description of what this source kind ingests and how it is used.", 1382 ) 1383 label: str | None = Field( 1384 default=None, 1385 description="Human-readable display name for this source kind, suitable for showing in a UI.", 1386 ) 1387 type: str = Field( 1388 ..., 1389 description='Machine-readable type identifier for this source kind (e.g. `"gmail"`, `"github_activity"`). Pass this value as `type` when creating a knowledge source.', 1390 )
Describes a single knowledge source kind that can be created through the public API. Use the type value when creating a new knowledge source.
description: str | None =
None
Short description of what this source kind ingests and how it is used.
label: str | None =
None
Human-readable display name for this source kind, suitable for showing in a UI.
type: str =
PydanticUndefined
Machine-readable type identifier for this source kind (e.g. "gmail", "github_activity"). Pass this value as type when creating a knowledge source.
class
KnowledgeSourceKindListResponse(pydantic.main.BaseModel):
1393class KnowledgeSourceKindListResponse(BaseModel): 1394 """ 1395 List response containing the knowledge source kinds available for creation via the API. 1396 """ 1397 1398 data: list[KnowledgeSourceKind] = Field( 1399 ..., 1400 description="Array of knowledge source kind objects describing each creatable source type.", 1401 )
List response containing the knowledge source kinds available for creation via the API.
class
OAuthTokenResponse(pydantic.main.BaseModel):
1404class OAuthTokenResponse(BaseModel): 1405 """ 1406 A successful OAuth 2.0 token response. Issued by the token endpoint after a completed authorization or device-flow grant. 1407 """ 1408 1409 access_token: str = Field( 1410 ..., 1411 description="Bearer token used to authenticate API requests. Include this value in the `Authorization: Bearer <token>` header.", 1412 ) 1413 expires_in: int = Field(..., description="Number of seconds until the access token expires.") 1414 refresh_token: str | None = Field( 1415 default=None, 1416 description="Token that can be exchanged for a new access token once the current one expires. `null` if the grant type does not issue refresh tokens.", 1417 ) 1418 scope: str | None = Field( 1419 default=None, 1420 description="Space-separated list of scopes granted to the access token. `null` if scope was not included in the grant request.", 1421 ) 1422 token_type: str = Field(..., description='Token type. Always `"Bearer"`.') 1423 user: User | None = Field( 1424 default=None, 1425 description="The authenticated user associated with this token. `null` when the token is not tied to a specific user (e.g. client-credentials grants).", 1426 )
A successful OAuth 2.0 token response. Issued by the token endpoint after a completed authorization or device-flow grant.
access_token: str =
PydanticUndefined
Bearer token used to authenticate API requests. Include this value in the Authorization: Bearer <token> header.
refresh_token: str | None =
None
Token that can be exchanged for a new access token once the current one expires. null if the grant type does not issue refresh tokens.
scope: str | None =
None
Space-separated list of scopes granted to the access token. null if scope was not included in the grant request.
class
PaginatedReplies(pydantic.main.BaseModel):
1429class PaginatedReplies(BaseModel): 1430 """ 1431 A paginated list of reply messages for a thread. The reply array is returned directly, not nested inside a `data` wrapper. 1432 """ 1433 1434 after_cursor: str | None = Field( 1435 default=None, 1436 description="Opaque cursor to pass as the pagination cursor to retrieve the page of replies that follow this one. `null` when no further pages exist.", 1437 ) 1438 before_cursor: str | None = Field( 1439 default=None, 1440 description="Opaque cursor to pass as the pagination cursor to retrieve the page of replies that precede this one. `null` when no earlier pages exist.", 1441 ) 1442 has_more: bool | None = Field( 1443 default=None, description="Whether additional reply pages exist beyond the current page." 1444 ) 1445 replies: list[Message] = Field( 1446 ..., description="Array of reply message objects for the current page." 1447 ) 1448 total_count: int | None = Field( 1449 default=None, description="Total number of replies in the thread across all pages." 1450 )
A paginated list of reply messages for a thread. The reply array is returned directly, not nested inside a data wrapper.
after_cursor: str | None =
None
Opaque cursor to pass as the pagination cursor to retrieve the page of replies that follow this one. null when no further pages exist.
class
RoutinePreset(pydantic.main.BaseModel):
1453class RoutinePreset(BaseModel): 1454 """ 1455 A named preset that defines the execution model and constraints for a routine. Presets are shared definitions; individual routines reference a preset by name. 1456 """ 1457 1458 applicable_events: list[str] = Field( 1459 ..., 1460 description='Event types that routines using this preset may be triggered by. `["*"]` means the preset accepts any event type. Routines assigned to this preset will be rejected at creation time if their trigger event is not in this list.', 1461 ) 1462 chainable: bool = Field( 1463 ..., 1464 description="Whether routines using this preset can be composed as a step inside a chain routine. Presets with sessionable or asynchronous execution models are not chainable.", 1465 ) 1466 description: str = Field( 1467 ..., description="Human-readable description of what the preset does and when to use it." 1468 ) 1469 label: str = Field( 1470 ..., description="Human-readable display name for the preset, suitable for use in UIs." 1471 ) 1472 name: str = Field( 1473 ..., 1474 description='Stable machine identifier for the preset, e.g. `"do_task"`. Used when assigning a preset to a routine.', 1475 ) 1476 sessionable: bool = Field( 1477 ..., 1478 description="Whether routines using this preset maintain a persistent conversation session across invocations. Sessionable presets do not expose instruction or session-mode configuration on individual routines.", 1479 ) 1480 unique: bool = Field( 1481 ..., 1482 description="Whether at most one routine with this preset may exist per agent. Attempting to create a second routine with a unique preset on the same agent will be rejected.", 1483 )
A named preset that defines the execution model and constraints for a routine. Presets are shared definitions; individual routines reference a preset by name.
applicable_events: list[str] =
PydanticUndefined
Event types that routines using this preset may be triggered by. ["*"] means the preset accepts any event type. Routines assigned to this preset will be rejected at creation time if their trigger event is not in this list.
chainable: bool =
PydanticUndefined
Whether routines using this preset can be composed as a step inside a chain routine. Presets with sessionable or asynchronous execution models are not chainable.
description: str =
PydanticUndefined
Human-readable description of what the preset does and when to use it.
name: str =
PydanticUndefined
Stable machine identifier for the preset, e.g. "do_task". Used when assigning a preset to a routine.
class
SlackChannelBinding(pydantic.main.BaseModel):
1486class SlackChannelBinding(BaseModel): 1487 """ 1488 A binding that connects a Slack channel to an ArchAstro team and one or more agents, enabling those agents to receive and respond to messages in that channel. 1489 """ 1490 1491 agents: list[str] | None = Field( 1492 default=None, 1493 description="IDs of the agents attached to this binding. Empty array when no agents are assigned.", 1494 ) 1495 channel: str | None = Field( 1496 default=None, description="Slack channel ID (e.g. `C01234ABCDE`) that this binding targets." 1497 ) 1498 customer_label: str | None = Field( 1499 default=None, 1500 description="Human-readable label identifying the customer, derived from the binding's embedded config. `null` when not set.", 1501 ) 1502 id: str = Field(..., description="Unique identifier for this Slack channel binding.") 1503 integration: str | None = Field( 1504 default=None, description="ID of the Slack integration that owns this binding." 1505 ) 1506 is_ext_shared_cached: bool | None = Field( 1507 default=None, 1508 description="Cached value of Slack's `is_ext_shared` flag for this channel. May be stale relative to Slack's current state.", 1509 ) 1510 team: str | None = Field( 1511 default=None, description="ID of the ArchAstro team this channel is bound to." 1512 )
A binding that connects a Slack channel to an ArchAstro team and one or more agents, enabling those agents to receive and respond to messages in that channel.
agents: list[str] | None =
None
IDs of the agents attached to this binding. Empty array when no agents are assigned.
class
SlackChannelBindingListResponse(pydantic.main.BaseModel):
1515class SlackChannelBindingListResponse(BaseModel): 1516 """ 1517 Paginated list of Slack channel bindings for the requested integration or team. Use the `page` and `per_page` fields to navigate pages of results. 1518 """ 1519 1520 data: list[SlackChannelBinding] = Field( 1521 ..., description="Array of Slack channel binding objects for the current page." 1522 ) 1523 page: int = Field(..., description="Current page number (1-indexed).") 1524 per_page: int = Field(..., description="Maximum number of bindings returned per page.") 1525 total_count: int = Field( 1526 ..., 1527 description="Total number of Slack channel bindings matching the query across all pages.", 1528 ) 1529 total_pages: int = Field( 1530 ..., description="Total number of pages available at the current `per_page` size." 1531 )
Paginated list of Slack channel bindings for the requested integration or team. Use the page and per_page fields to navigate pages of results.
class
StorageFile(pydantic.main.BaseModel):
1534class StorageFile(BaseModel): 1535 """ 1536 A file stored in the platform's object storage, with metadata and a signed URL for downloading its contents. 1537 """ 1538 1539 content_type: str | None = Field( 1540 default=None, 1541 description='MIME type of the file, e.g. `"image/png"` or `"application/pdf"`.', 1542 ) 1543 created_at: datetime | None = Field( 1544 default=None, description="When the file was uploaded (ISO 8601)." 1545 ) 1546 filename: str | None = Field( 1547 default=None, description="Original filename as provided at upload time." 1548 ) 1549 id: str = Field(..., description="File ID (`fil_...`).") 1550 image_source: ImageSource | None = Field( 1551 default=None, 1552 description="Image display metadata. Present only when `content_type` is an image type; `null` otherwise.", 1553 ) 1554 org: str | None = Field( 1555 default=None, description="ID of the organization that owns this file (`org_...`)." 1556 ) 1557 sandbox: str | None = Field( 1558 default=None, 1559 description="ID of the sandbox this file is scoped to (`sbx_...`). `null` for files not associated with a sandbox.", 1560 ) 1561 size: int | None = Field(default=None, description="Size of the file in bytes.") 1562 updated_at: datetime | None = Field( 1563 default=None, description="When the file record was last modified (ISO 8601)." 1564 ) 1565 url: str | None = Field( 1566 default=None, 1567 description="Short-lived signed URL for downloading the file. `null` if a URL could not be generated.", 1568 )
A file stored in the platform's object storage, with metadata and a signed URL for downloading its contents.
Image display metadata. Present only when content_type is an image type; null otherwise.
class
ValidationResult(pydantic.main.BaseModel):
1571class ValidationResult(BaseModel): 1572 """ 1573 The result of a configuration validation check, indicating whether the config is valid and listing any errors or warnings. 1574 """ 1575 1576 errors: list[str] | None = Field( 1577 default=None, 1578 description="List of human-readable error messages describing why validation failed. Empty or absent when `valid` is `true`.", 1579 ) 1580 valid: bool = Field( 1581 ..., 1582 description="`true` if the configuration passed all validation checks, `false` if one or more errors were found.", 1583 ) 1584 warnings: list[str] | None = Field( 1585 default=None, 1586 description="List of human-readable warning messages emitted during validation. Warnings do not cause `valid` to be `false` but indicate potentially problematic configuration.", 1587 )
The result of a configuration validation check, indicating whether the config is valid and listing any errors or warnings.
errors: list[str] | None =
None
List of human-readable error messages describing why validation failed. Empty or absent when valid is true.
valid: bool =
PydanticUndefined
true if the configuration passed all validation checks, false if one or more errors were found.
warnings: list[str] | None =
None
List of human-readable warning messages emitted during validation. Warnings do not cause valid to be false but indicate potentially problematic configuration.
class
WorkingMemoryEntry(pydantic.main.BaseModel):
1590class WorkingMemoryEntry(BaseModel): 1591 """ 1592 A key-value memory record stored for an agent, optionally scoped to a user. Memory entries persist across invocations and may carry an expiration time. 1593 """ 1594 1595 agent: str | None = Field( 1596 default=None, description="ID of the agent that owns this memory entry (`agt_...`)." 1597 ) 1598 created_at: datetime | None = Field( 1599 default=None, description="When this memory entry was first written (ISO 8601)." 1600 ) 1601 expires_at: datetime | None = Field( 1602 default=None, 1603 description="When this entry will be automatically deleted. `null` if the entry does not expire.", 1604 ) 1605 id: str = Field(..., description="Working memory entry ID (`amm_...`).") 1606 key: str | None = Field( 1607 default=None, 1608 description="The string key used to look up this memory entry within the agent's memory namespace.", 1609 ) 1610 updated_at: datetime | None = Field( 1611 default=None, description="When this memory entry was last modified (ISO 8601)." 1612 ) 1613 value: str | None = Field( 1614 default=None, 1615 description="The string value stored under `key`. May be any serialized content the agent wrote.", 1616 )
A key-value memory record stored for an agent, optionally scoped to a user. Memory entries persist across invocations and may carry an expiration time.
expires_at: datetime.datetime | None =
None
When this entry will be automatically deleted. null if the entry does not expire.
key: str | None =
None
The string key used to look up this memory entry within the agent's memory namespace.
value: str | None =
None
The string value stored under key. May be any serialized content the agent wrote.
class
WorkingMemoryEntryListResponse(pydantic.main.BaseModel):
1619class WorkingMemoryEntryListResponse(BaseModel): 1620 """ 1621 Paginated list of working memory entries stored for an agent. Includes page metadata to support sequential page traversal. 1622 """ 1623 1624 data: list[WorkingMemoryEntry] = Field( 1625 ..., description="Array of working memory entry objects for the current page." 1626 ) 1627 has_next: bool | None = Field( 1628 default=None, 1629 description="`true` if a subsequent page exists and can be fetched by incrementing the page number.", 1630 ) 1631 has_prev: bool | None = Field( 1632 default=None, 1633 description="`true` if a previous page exists and can be fetched by decrementing the page number.", 1634 ) 1635 page: int | None = Field(default=None, description="The current page number, starting at `1`.") 1636 page_size: int | None = Field( 1637 default=None, description="Maximum number of entries returned per page." 1638 ) 1639 total_entries: int | None = Field( 1640 default=None, 1641 description="Total number of working memory entries matching the query across all pages.", 1642 ) 1643 total_pages: int | None = Field( 1644 default=None, description="Total number of pages given the current `page_size`." 1645 )
Paginated list of working memory entries stored for an agent. Includes page metadata to support sequential page traversal.
has_next: bool | None =
None
true if a subsequent page exists and can be fetched by incrementing the page number.
has_prev: bool | None =
None
true if a previous page exists and can be fetched by decrementing the page number.
class
SolutionTemplateSummary(pydantic.main.BaseModel):
1648class SolutionTemplateSummary(BaseModel): 1649 """ 1650 Identity and display metadata for a single template bundled by a Solution, used to represent each wrapped or sibling template at template granularity. 1651 """ 1652 1653 description: str | None = Field( 1654 default=None, 1655 description="Short prose blurb from the template body's `description:` field. `null` when the body doesn't set one. Used as the card subhead in the Library carousel.", 1656 ) 1657 display_name: str | None = Field( 1658 default=None, 1659 description="Human-facing label from the template body's `display_name:` field. `null` when the body doesn't set one. Library carousels use this for the card title, falling back to a humanized `name`.", 1660 ) 1661 id: str | None = Field( 1662 default=None, 1663 description="Template config ID (`cfg_...`). `null` for inline-only templates.", 1664 ) 1665 kind: str = Field( 1666 ..., 1667 description="Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.", 1668 ) 1669 lookup_key: str | None = Field( 1670 default=None, 1671 description="Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", 1672 ) 1673 name: str | None = Field( 1674 default=None, 1675 description="Canonical name from the template body. For `AgentTemplate` this doubles as the human-facing label; for `AgentToolTemplate` it's the LLM-facing tool function identifier (snake_case); for `AgentRoutineTemplate` it's the routine identifier (kebab-case). Clients rendering carousels should prefer `display_name` and fall back to humanizing `name`.", 1676 ) 1677 readme_url: str | None = Field( 1678 default=None, 1679 description="Relative path to the public README endpoint with a signed token already embedded, scoped to this template's bundled markdown asset. `null` when the Solution body's `templates[].readme_path` is unset for this entry. Token expires in 1 hour refresh via `GET /api/v1/solutions/:solution`.", 1680 ) 1681 virtual_path: str | None = Field( 1682 default=None, 1683 description="Stable virtual path assigned to the template config. `null` when no virtual path was set.", 1684 )
Identity and display metadata for a single template bundled by a Solution, used to represent each wrapped or sibling template at template granularity.
description: str | None =
None
Short prose blurb from the template body's description: field. null when the body doesn't set one. Used as the card subhead in the Library carousel.
display_name: str | None =
None
Human-facing label from the template body's display_name: field. null when the body doesn't set one. Library carousels use this for the card title, falling back to a humanized name.
kind: str =
PydanticUndefined
Template config kind, or SolutionTemplateRef / SolutionTemplatePath when unresolved.
lookup_key: str | None =
None
Lookup key stamped on the template config at import time. null when no lookup key was assigned.
name: str | None =
None
Canonical name from the template body. For AgentTemplate this doubles as the human-facing label; for AgentToolTemplate it's the LLM-facing tool function identifier (snake_case); for AgentRoutineTemplate it's the routine identifier (kebab-case). Clients rendering carousels should prefer display_name and fall back to humanizing name.
readme_url: str | None =
None
Relative path to the public README endpoint with a signed token already embedded, scoped to this template's bundled markdown asset. null when the Solution body's templates[].readme_path is unset for this entry. Token expires in 1 hour refresh via GET /api/v1/solutions/:solution.
class
SolutionSummary(pydantic.main.BaseModel):
1687class SolutionSummary(BaseModel): 1688 """ 1689 A catalog entry for an imported Solution, including its display metadata, bundled templates, owner scopes, and any available upgrade information. 1690 """ 1691 1692 category_keys: list[str] | None = Field( 1693 default=None, 1694 description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", 1695 ) 1696 created_at: datetime | None = Field( 1697 default=None, description="When the Solution config was first imported (ISO 8601)." 1698 ) 1699 description: str | None = Field( 1700 default=None, 1701 description="Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. `null` when the Solution body does not set one.", 1702 ) 1703 id: str = Field(..., description="Solution config ID (`cfg_...`).") 1704 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 1705 latest_solution: str | None = Field( 1706 default=None, 1707 description="When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", 1708 ) 1709 latest_version: str | None = Field( 1710 default=None, 1711 description="When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", 1712 ) 1713 lookup_key: str | None = Field( 1714 default=None, 1715 description="The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", 1716 ) 1717 metadata: dict[str, Any] | None = Field( 1718 default=None, 1719 description="Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none.", 1720 ) 1721 name: str | None = Field( 1722 default=None, 1723 description="Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", 1724 ) 1725 org: str | None = Field( 1726 default=None, 1727 description="Organization ID (`org_...`) that owns this Solution config, when the Solution is scoped to a specific org. `null` for system-scope (app-level) Solutions.", 1728 ) 1729 org_logo: ImageSource | None = Field( 1730 default=None, 1731 description="Canonical image-source object for the resolved `org`'s logo, used as the principal category section glyph. Carries the signed `url` plus a `refresh_url`. `null` when `org_slug` is `null` or the org has no logo.", 1732 ) 1733 org_name: str | None = Field( 1734 default=None, 1735 description="Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", 1736 ) 1737 org_slug: str | None = Field( 1738 default=None, 1739 description="Resolved slug of the Solution body's `org` (the publishing organization), when set and it resolves to a real org visible to the viewer. When present this is the Solution's principal catalog category key clients group the Solution under this org ahead of `category_keys`. `null` when the body has no `org` or it doesn't resolve.", 1740 ) 1741 owners: list[str] = Field( 1742 ..., 1743 description='Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer\'s org scope).', 1744 ) 1745 readme_url: str | None = Field( 1746 default=None, 1747 description="Relative path to the public README endpoint with a signed token already embedded. `null` when the Solution has no README. Token expires in 1 hour refresh via `GET /api/v1/solutions/:solution`.", 1748 ) 1749 solution_id: str | None = Field( 1750 default=None, 1751 description="Stable UUID declared in the Solution body, used to identify the same logical Solution across multiple installed copies and owner scopes. `null` when the body omits it.", 1752 ) 1753 solution_version: str | None = Field( 1754 default=None, 1755 description='Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.', 1756 ) 1757 tag_keys: list[str] | None = Field( 1758 default=None, 1759 description="Freeform tag keys declared in the Solution body. An empty array when the body declares none.", 1760 ) 1761 template_kind: str | None = Field( 1762 default=None, 1763 description='Wrapped template kind `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.', 1764 ) 1765 templates: list[SolutionTemplateSummary] = Field( 1766 ..., 1767 description="Template configs bundled by this Solution, in declaration order the first entry is the deployable template the Solution wraps; the rest are sibling templates the wrapped template references.", 1768 ) 1769 updated_at: datetime | None = Field( 1770 default=None, description="When the Solution config was last modified (ISO 8601)." 1771 ) 1772 upgrade_available: bool = Field( 1773 ..., 1774 description="`true` when this Solution is installed at the viewer's org scope and the app-level system scope carries a higher `solution_version`. Always `false` for system-only rows.", 1775 ) 1776 virtual_path: str | None = Field( 1777 default=None, 1778 description="The stable virtual path assigned to this Solution config, used as the deduplication key when the same Solution appears under multiple owner scopes. `null` when unset.", 1779 )
A catalog entry for an imported Solution, including its display metadata, bundled templates, owner scopes, and any available upgrade information.
category_keys: list[str] | None =
None
Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.
description: str | None =
None
Short tagline or summary declared in the Solution body, used as the card subhead in catalog UIs. null when the Solution body does not set one.
latest_solution: str | None =
None
When upgrade_available is true, the system-scope Solution config ID (cfg_...) that should be used as the upgrade source. null otherwise.
latest_version: str | None =
None
When upgrade_available is true, the higher system-scope solution_version available to upgrade to. null otherwise.
lookup_key: str | None =
None
The lookup key stored on the Solution config, if one was assigned during import. null when no lookup key was set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata declared in the Solution body (e.g. category or display hints). Present as an empty object when the body declares none.
name: str | None =
None
Human-facing display name declared in the Solution body. null when the Solution body does not set one.
org: str | None =
None
Organization ID (org_...) that owns this Solution config, when the Solution is scoped to a specific org. null for system-scope (app-level) Solutions.
org_slug: str | None =
None
Resolved slug of the Solution body's org (the publishing organization), when set and it resolves to a real org visible to the viewer. When present this is the Solution's principal catalog category key clients group the Solution under this org ahead of category_keys. null when the body has no org or it doesn't resolve.
owners: list[str] =
PydanticUndefined
Owner scopes this Solution appears under. Members: "system" (app-level system scope) and/or "org" (viewer's org scope).
readme_url: str | None =
None
Relative path to the public README endpoint with a signed token already embedded. null when the Solution has no README. Token expires in 1 hour refresh via GET /api/v1/solutions/:solution.
solution_id: str | None =
None
Stable UUID declared in the Solution body, used to identify the same logical Solution across multiple installed copies and owner scopes. null when the body omits it.
solution_version: str | None =
None
Semver string declared in the Solution body (e.g. "1.2.0"). null when the body does not declare a version.
tag_keys: list[str] | None =
None
Freeform tag keys declared in the Solution body. An empty array when the body declares none.
template_kind: str | None =
None
Wrapped template kind "AgentTemplate", "AutomationTemplate", "AgentRoutineTemplate", "AgentToolTemplate", "AgentComputerTemplate", or "SolutionTemplateRef" for ref-mode bundles.
Template configs bundled by this Solution, in declaration order the first entry is the deployable template the Solution wraps; the rest are sibling templates the wrapped template references.
upgrade_available: bool =
PydanticUndefined
true when this Solution is installed at the viewer's org scope and the app-level system scope carries a higher solution_version. Always false for system-only rows.
class
AgentSourceSolution(pydantic.main.BaseModel):
1782class AgentSourceSolution(BaseModel): 1783 """ 1784 Summary of the Solution and AgentTemplate that an agent was last provisioned from. 1785 Returned on single-agent responses; `null` for hand-built agents and agents whose tracked template or parent Solution has been deleted. 1786 """ 1787 1788 solution: SolutionSummary = Field( 1789 ..., 1790 description="Summary of the parent Solution, including `upgrade_available`, `latest_version`, and `latest_solution` when a newer system-scoped version is available for the agent's org-scoped Solution.", 1791 ) 1792 template: UpgradeTemplateSummary = Field( 1793 ..., 1794 description="Summary of the AgentTemplate config (`cfg_...`) the agent was last provisioned or updated from.", 1795 )
Summary of the Solution and AgentTemplate that an agent was last provisioned from.
Returned on single-agent responses; null for hand-built agents and agents whose tracked template or parent Solution has been deleted.
Summary of the parent Solution, including upgrade_available, latest_version, and latest_solution when a newer system-scoped version is available for the agent's org-scoped Solution.
class
Agent(pydantic.main.BaseModel):
1798class Agent(BaseModel): 1799 """ 1800 An AI agent that can be configured with tools, routines, and skills, and invoked to handle conversations or tasks. 1801 """ 1802 1803 acl: Acl | None = Field( 1804 default=None, 1805 description="Access control list for the agent. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied and the agent is accessible to all members of its scope.", 1806 ) 1807 app: str | None = Field( 1808 default=None, description="ID of the application that owns this agent (`dap_...`)." 1809 ) 1810 created_at: datetime | None = Field( 1811 default=None, description="When the agent was created (ISO 8601)." 1812 ) 1813 default_model: str | None = Field( 1814 default=None, 1815 description='Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `"claude-3-7-sonnet-latest"`).', 1816 ) 1817 email: str | None = Field( 1818 default=None, 1819 description="Email address provisioned for this agent. `null` if email delivery is not configured.", 1820 ) 1821 id: str = Field(..., description="Agent ID (`agi_...`).") 1822 identity: str | None = Field( 1823 default=None, 1824 description="System-level identity prompt that shapes the agent's persona and behavior.", 1825 ) 1826 last_applied_template_config: str | None = Field( 1827 default=None, 1828 description="ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", 1829 ) 1830 lookup_key: str | None = Field( 1831 default=None, 1832 description="Stable, user-defined identifier for this agent within the application. Unique per app.", 1833 ) 1834 metadata: dict[str, Any] | None = Field( 1835 default=None, 1836 description="Arbitrary key-value metadata attached to the agent. Not interpreted by the platform.", 1837 ) 1838 name: str | None = Field( 1839 default=None, description="Human-readable display name for the agent. `null` if not set." 1840 ) 1841 org: str | None = Field( 1842 default=None, 1843 description="ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", 1844 ) 1845 org_name: str | None = Field( 1846 default=None, 1847 description="Display name of the organization this agent belongs to. `null` when the agent is not org-scoped or when the org association was not preloaded.", 1848 ) 1849 originator: str | None = Field( 1850 default=None, 1851 description="Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", 1852 ) 1853 phone_number: str | None = Field( 1854 default=None, 1855 description="Phone number provisioned for this agent. `null` if SMS is not configured.", 1856 ) 1857 sandbox: str | None = Field( 1858 default=None, 1859 description="ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", 1860 ) 1861 source_solution: AgentSourceSolution | None = Field( 1862 default=None, 1863 description="Source Solution and AgentTemplate summary for agents provisioned from a Solution. Includes `upgrade_available`, `latest_version`, and `latest_solution` so you can render an upgrade badge without a separate dry-run call. `null` for hand-built agents and agents whose tracked template or parent Solution has been deleted. Populated only on single-agent GET responses, never on list endpoints.", 1864 ) 1865 team: str | None = Field( 1866 default=None, 1867 description="ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", 1868 ) 1869 template_upgrade_available: bool | None = Field( 1870 default=None, 1871 description="True when the agent's last-applied template version is behind the current version of its AgentTemplate config i.e. reapplying the template (a per-agent upgrade) would bring it newer Solution content. Self-clears once the agent is reapplied. Computed only on list endpoints; `null` on single-agent GET.", 1872 ) 1873 updated_at: datetime | None = Field( 1874 default=None, description="When the agent was last modified (ISO 8601)." 1875 ) 1876 user: str | None = Field( 1877 default=None, 1878 description="ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", 1879 )
An AI agent that can be configured with tools, routines, and skills, and invoked to handle conversations or tasks.
Access control list for the agent. Contains a grants array where each entry specifies principal_type, principal, and actions. null when no ACL restrictions are applied and the agent is accessible to all members of its scope.
default_model: str | None =
None
Default LLM model identifier used by this agent when no model is specified at runtime (e.g. "claude-3-7-sonnet-latest").
email: str | None =
None
Email address provisioned for this agent. null if email delivery is not configured.
identity: str | None =
None
System-level identity prompt that shapes the agent's persona and behavior.
last_applied_template_config: str | None =
None
ID of the AgentTemplate config (cfg_...) this agent was last provisioned or updated from. null for manually created agents.
lookup_key: str | None =
None
Stable, user-defined identifier for this agent within the application. Unique per app.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata attached to the agent. Not interpreted by the platform.
org: str | None =
None
ID of the organization this agent belongs to (org_...). null if the agent is not org-scoped.
org_name: str | None =
None
Display name of the organization this agent belongs to. null when the agent is not org-scoped or when the org association was not preloaded.
originator: str | None =
None
Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).
phone_number: str | None =
None
Phone number provisioned for this agent. null if SMS is not configured.
sandbox: str | None =
None
ID of the sandbox environment this agent is scoped to (dsb_...). null in production deployments.
Source Solution and AgentTemplate summary for agents provisioned from a Solution. Includes upgrade_available, latest_version, and latest_solution so you can render an upgrade badge without a separate dry-run call. null for hand-built agents and agents whose tracked template or parent Solution has been deleted. Populated only on single-agent GET responses, never on list endpoints.
team: str | None =
None
ID of the team that owns this agent (tem_...). null if the agent is not team-scoped.
template_upgrade_available: bool | None =
None
True when the agent's last-applied template version is behind the current version of its AgentTemplate config i.e. reapplying the template (a per-agent upgrade) would bring it newer Solution content. Self-clears once the agent is reapplied. Computed only on list endpoints; null on single-agent GET.
class
AgentComputer(pydantic.main.BaseModel):
1882class AgentComputer(BaseModel): 1883 """ 1884 A cloud computer resource provisioned for an agent to use for browser and desktop automation tasks. 1885 """ 1886 1887 agent: str | None = Field( 1888 default=None, 1889 description="ID of the agent that owns this computer (`agi_...`). `null` if the computer is not yet assigned to an agent.", 1890 ) 1891 app: str | None = Field( 1892 default=None, description="ID of the app this computer belongs to (`dap_...`)." 1893 ) 1894 config: dict[str, Any] | None = Field( 1895 default=None, 1896 description="Provider-specific configuration key-value pairs for the computer. Structure depends on the underlying compute provider.", 1897 ) 1898 created_at: datetime | None = Field( 1899 default=None, description="When the computer was created (ISO 8601)." 1900 ) 1901 error_message: str | None = Field( 1902 default=None, 1903 description='Human-readable error description when `status` is `"error"`. `null` otherwise.', 1904 ) 1905 id: str = Field(..., description="Computer ID (`cmp_...`).") 1906 last_active_at: datetime | None = Field( 1907 default=None, 1908 description="When the computer last reported activity or received a command. `null` if the computer has never been active.", 1909 ) 1910 lookup_key: str | None = Field( 1911 default=None, 1912 description="Unique, stable identifier you assign to this computer within its app. `null` if not set.", 1913 ) 1914 metadata: dict[str, Any] | None = Field( 1915 default=None, 1916 description="Arbitrary key-value metadata you attached to the computer. `null` if none was provided.", 1917 ) 1918 name: str | None = Field( 1919 default=None, description="Human-readable display name for the computer. `null` if not set." 1920 ) 1921 provider: str | None = Field( 1922 default=None, 1923 description='Compute backend powering this computer: `"sprites"` (Fly Sprites) or `"vercel"` (Vercel Sandbox).', 1924 ) 1925 region: str | None = Field( 1926 default=None, 1927 description='Cloud region where the computer is hosted, e.g. `"us-east-1"`. `null` if not yet assigned or when the provider has no region concept (e.g. `"vercel"`).', 1928 ) 1929 sprite_url: str | None = Field( 1930 default=None, 1931 description="URL of the live screenshot sprite used to render a real-time preview of the computer's screen. `null` when no sprite is available.", 1932 ) 1933 status: str | None = Field( 1934 default=None, 1935 description='Current lifecycle state of the computer. Common values include `"provisioning"`, `"ready"`, `"error"`, and `"terminated"`.', 1936 ) 1937 updated_at: datetime | None = Field( 1938 default=None, description="When the computer record was last modified (ISO 8601)." 1939 )
A cloud computer resource provisioned for an agent to use for browser and desktop automation tasks.
agent: str | None =
None
ID of the agent that owns this computer (agi_...). null if the computer is not yet assigned to an agent.
config: dict[str, typing.Any] | None =
None
Provider-specific configuration key-value pairs for the computer. Structure depends on the underlying compute provider.
error_message: str | None =
None
Human-readable error description when status is "error". null otherwise.
last_active_at: datetime.datetime | None =
None
When the computer last reported activity or received a command. null if the computer has never been active.
lookup_key: str | None =
None
Unique, stable identifier you assign to this computer within its app. null if not set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata you attached to the computer. null if none was provided.
provider: str | None =
None
Compute backend powering this computer: "sprites" (Fly Sprites) or "vercel" (Vercel Sandbox).
region: str | None =
None
Cloud region where the computer is hosted, e.g. "us-east-1". null if not yet assigned or when the provider has no region concept (e.g. "vercel").
sprite_url: str | None =
None
URL of the live screenshot sprite used to render a real-time preview of the computer's screen. null when no sprite is available.
class
AgentComputerListResponse(pydantic.main.BaseModel):
1942class AgentComputerListResponse(BaseModel): 1943 """ 1944 A list of agent computers returned by a list query. 1945 """ 1946 1947 data: list[AgentComputer] = Field( 1948 ..., description="Array of agent computer objects matching the query." 1949 )
A list of agent computers returned by a list query.
class
AgentCreateResponse(pydantic.main.BaseModel):
1952class AgentCreateResponse(BaseModel): 1953 """ 1954 The response returned by `POST /api/v1/agents`. Contains all agent fields plus an optional `installed_configs` array when a `template_bundle` was supplied in the request. 1955 """ 1956 1957 acl: Acl | None = Field( 1958 default=None, 1959 description="Access control list governing who can interact with this agent. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied.", 1960 ) 1961 app: str | None = Field( 1962 default=None, description="ID of the app this agent belongs to (`dap_...`)." 1963 ) 1964 created_at: datetime | None = Field( 1965 default=None, description="When the agent was created (ISO 8601)." 1966 ) 1967 default_model: str | None = Field( 1968 default=None, 1969 description='Default AI model the agent uses when no model is specified at runtime, e.g. `"claude-3-5-sonnet-20241022"`. `null` if not configured.', 1970 ) 1971 email: str | None = Field( 1972 default=None, 1973 description="Email address assigned to this agent for inbound email handling. `null` if not configured.", 1974 ) 1975 id: str = Field(..., description="Agent ID (`agi_...`).") 1976 identity: str | None = Field( 1977 default=None, 1978 description="System prompt or persona description that shapes the agent's behavior. `null` if not set.", 1979 ) 1980 installed_configs: list[InstalledConfigEntry] | None = Field( 1981 default=None, 1982 description="List of config records created as part of this request's `template_bundle` install. One entry per persisted config, sorted by `key`. Omitted entirely when the request did not include a `template_bundle`.", 1983 ) 1984 lookup_key: str | None = Field( 1985 default=None, 1986 description="Unique, stable identifier for the agent within its app. `null` if not set.", 1987 ) 1988 metadata: dict[str, Any] | None = Field( 1989 default=None, 1990 description="Arbitrary key-value metadata attached to the agent. `null` if none was provided.", 1991 ) 1992 name: str | None = Field( 1993 default=None, description="Human-readable display name for the agent. `null` if not set." 1994 ) 1995 org: str | None = Field( 1996 default=None, 1997 description="ID of the organization this agent belongs to (`org_...`). `null` for agents outside an org.", 1998 ) 1999 originator: str | None = Field( 2000 default=None, 2001 description="Free-form label identifying the source or author of the agent, e.g. a username or service name. `null` if not set.", 2002 ) 2003 phone_number: str | None = Field( 2004 default=None, 2005 description="Phone number assigned to this agent for inbound SMS or voice handling. `null` if not configured.", 2006 ) 2007 sandbox: str | None = Field( 2008 default=None, 2009 description="ID of the sandbox environment this agent is scoped to (`sbx_...`). `null` for agents not scoped to a sandbox.", 2010 ) 2011 team: str | None = Field( 2012 default=None, 2013 description="ID of the team that owns this agent (`tea_...`). `null` if owned by a user rather than a team.", 2014 ) 2015 updated_at: datetime | None = Field( 2016 default=None, description="When the agent record was last modified (ISO 8601)." 2017 ) 2018 user: str | None = Field( 2019 default=None, 2020 description="ID of the user that owns this agent (`usr_...`). `null` if owned by a team.", 2021 )
The response returned by POST /api/v1/agents. Contains all agent fields plus an optional installed_configs array when a template_bundle was supplied in the request.
Access control list governing who can interact with this agent. Contains a grants array where each entry specifies principal_type, principal, and actions. null when no ACL restrictions are applied.
default_model: str | None =
None
Default AI model the agent uses when no model is specified at runtime, e.g. "claude-3-5-sonnet-20241022". null if not configured.
email: str | None =
None
Email address assigned to this agent for inbound email handling. null if not configured.
identity: str | None =
None
System prompt or persona description that shapes the agent's behavior. null if not set.
List of config records created as part of this request's template_bundle install. One entry per persisted config, sorted by key. Omitted entirely when the request did not include a template_bundle.
lookup_key: str | None =
None
Unique, stable identifier for the agent within its app. null if not set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata attached to the agent. null if none was provided.
org: str | None =
None
ID of the organization this agent belongs to (org_...). null for agents outside an org.
originator: str | None =
None
Free-form label identifying the source or author of the agent, e.g. a username or service name. null if not set.
phone_number: str | None =
None
Phone number assigned to this agent for inbound SMS or voice handling. null if not configured.
sandbox: str | None =
None
ID of the sandbox environment this agent is scoped to (sbx_...). null for agents not scoped to a sandbox.
class
AgentEnvVarMasked(pydantic.main.BaseModel):
2024class AgentEnvVarMasked(BaseModel): 2025 """ 2026 An agent environment variable with its secret value masked for safe display in list and show responses. 2027 """ 2028 2029 agent: str = Field( 2030 ..., description="ID of the agent this environment variable belongs to (`agt_...`)." 2031 ) 2032 created_at: datetime | None = Field( 2033 default=None, description="When the environment variable was created (ISO 8601)." 2034 ) 2035 description: str | None = Field( 2036 default=None, 2037 description="Optional human-readable note describing the purpose of this variable. `null` if not set.", 2038 ) 2039 id: str = Field(..., description="Environment variable ID (`anv_...`).") 2040 key: str = Field( 2041 ..., description="Name of the environment variable as it appears in the agent's runtime." 2042 ) 2043 masked_value: str = Field( 2044 ..., 2045 description="Redacted representation of the secret value. The last four characters are preserved; all preceding characters are replaced with `****`. Returns `****` when the value is absent or four characters or fewer.", 2046 ) 2047 updated_at: datetime | None = Field( 2048 default=None, description="When the environment variable was last updated (ISO 8601)." 2049 )
An agent environment variable with its secret value masked for safe display in list and show responses.
description: str | None =
None
Optional human-readable note describing the purpose of this variable. null if not set.
class
AgentEnvVarMaskedList(pydantic.main.BaseModel):
2052class AgentEnvVarMaskedList(BaseModel): 2053 """ 2054 Flat list of masked environment variables belonging to an agent. 2055 """ 2056 2057 data: list[AgentEnvVarMasked] = Field( 2058 ..., description="Array of masked environment variable objects for the agent." 2059 )
Flat list of masked environment variables belonging to an agent.
class
AgentExport(pydantic.main.BaseModel):
2062class AgentExport(BaseModel): 2063 """ 2064 A portable export bundle for an agent, containing everything needed to re-deploy it in another workspace or environment. 2065 """ 2066 2067 configs: list[Config] = Field( 2068 ..., 2069 description="Ordered list of config file objects that the agent depends on. Included in full so the import can recreate all dependencies without additional requests.", 2070 ) 2071 template: dict[str, Any] = Field( 2072 ..., 2073 description="The agent template definition as a structured map. Pass this directly to the import endpoint to recreate the agent.", 2074 )
A portable export bundle for an agent, containing everything needed to re-deploy it in another workspace or environment.
class
AgentHealth(pydantic.main.BaseModel):
2077class AgentHealth(BaseModel): 2078 """ 2079 Aggregate health profile for an agent, summarizing its current operational status, score, and the full list of setup and health actions. 2080 """ 2081 2082 activity: dict[str, Any] = Field( 2083 ..., 2084 description="Timestamps for the agent's most recent and next scheduled activity, used to surface last-run and upcoming-run information.", 2085 ) 2086 agent: Agent = Field(..., description="The agent this health profile describes.") 2087 checked_at: datetime = Field( 2088 ..., description="When the health profile was last computed (ISO 8601)." 2089 ) 2090 checks: list[dict[str, Any]] = Field( 2091 ..., 2092 description="Renderable health check results. Each object includes at minimum `key`, `label`, `status`, and `summary` fields.", 2093 ) 2094 counts: dict[str, Any] = Field( 2095 ..., 2096 description="Action counts broken down by dependency area and resolution status, used to render progress indicators per category.", 2097 ) 2098 health_actions: list[AgentHealthAction] = Field( 2099 ..., 2100 description='All actionable items tracked for this agent, including both `"setup"` items (post-install checklist) and `"health"` items (probe-detected issues). Sorted by `(source, sort_order, id)`. Use each item\'s `params` field to construct deep-links that route the user to the correct resolution flow.', 2101 ) 2102 recent: dict[str, Any] = Field( 2103 ..., 2104 description="Recent execution metrics for the agent, including run counts and failure counts over a recent time window.", 2105 ) 2106 score: int = Field( 2107 ..., 2108 description="Normalized health score from `0` (fully degraded) to `100` (fully healthy), derived from the weight and status of all health actions.", 2109 ) 2110 status: str = Field( 2111 ..., 2112 description='Overall health status of the agent. One of `"ok"`, `"warning"`, or `"critical"`.', 2113 )
Aggregate health profile for an agent, summarizing its current operational status, score, and the full list of setup and health actions.
activity: dict[str, typing.Any] =
PydanticUndefined
Timestamps for the agent's most recent and next scheduled activity, used to surface last-run and upcoming-run information.
checked_at: datetime.datetime =
PydanticUndefined
When the health profile was last computed (ISO 8601).
checks: list[dict[str, typing.Any]] =
PydanticUndefined
Renderable health check results. Each object includes at minimum key, label, status, and summary fields.
counts: dict[str, typing.Any] =
PydanticUndefined
Action counts broken down by dependency area and resolution status, used to render progress indicators per category.
All actionable items tracked for this agent, including both "setup" items (post-install checklist) and "health" items (probe-detected issues). Sorted by (source, sort_order, id). Use each item's params field to construct deep-links that route the user to the correct resolution flow.
recent: dict[str, typing.Any] =
PydanticUndefined
Recent execution metrics for the agent, including run counts and failure counts over a recent time window.
class
AgentListResponse(pydantic.main.BaseModel):
2116class AgentListResponse(BaseModel): 2117 """ 2118 Paginated list of agent objects. Use the pagination fields to traverse multiple pages of results. 2119 """ 2120 2121 data: list[Agent] = Field(..., description="Array of agent objects for the current page.") 2122 has_next: bool | None = Field( 2123 default=None, description="`true` when a subsequent page of results exists." 2124 ) 2125 has_prev: bool | None = Field( 2126 default=None, description="`true` when a previous page of results exists." 2127 ) 2128 page: int | None = Field(default=None, description="Current page number, starting at 1.") 2129 page_size: int | None = Field( 2130 default=None, description="Maximum number of agents returned per page." 2131 ) 2132 total_entries: int | None = Field( 2133 default=None, description="Total number of agents matching the query across all pages." 2134 ) 2135 total_pages: int | None = Field( 2136 default=None, description="Total number of pages available given the current `page_size`." 2137 )
Paginated list of agent objects. Use the pagination fields to traverse multiple pages of results.
class
AgentRoutine(pydantic.main.BaseModel):
2140class AgentRoutine(BaseModel): 2141 """ 2142 An agent routine defines a reusable handler script, preset, or chain that runs in response to events or on a schedule. 2143 """ 2144 2145 acl: Acl | None = Field( 2146 default=None, 2147 description="Access control list for the routine. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied and the routine is accessible to all members of its scope.", 2148 ) 2149 agent: str | None = Field( 2150 default=None, description="ID of the agent that owns this routine (`agi_...`)." 2151 ) 2152 app: str | None = Field( 2153 default=None, description="Application that scopes this routine (`dap_...`)." 2154 ) 2155 config: str | None = Field( 2156 default=None, 2157 description="ID of the Config record that backs this routine's configuration (`cfg_...`). `null` when the routine is not config-backed.", 2158 ) 2159 created_at: datetime | None = Field( 2160 default=None, description="When this routine was created (ISO 8601)." 2161 ) 2162 description: str | None = Field( 2163 default=None, 2164 description="Optional description of what this routine does. `null` when not set.", 2165 ) 2166 event_config: dict[str, Any] | None = Field( 2167 default=None, 2168 description="Additional configuration controlling how the event trigger is matched or filtered. Shape depends on `event_type`. `null` when not configured.", 2169 ) 2170 event_type: str | None = Field( 2171 default=None, 2172 description='Platform event type that triggers this routine, e.g. `"agentroutine.invoked"`. `null` for schedule-only routines.', 2173 ) 2174 handler_type: str | None = Field( 2175 default=None, 2176 description='Execution strategy for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`.', 2177 ) 2178 id: str = Field(..., description="Routine ID (`arn_...`).") 2179 last_applied_template_config: str | None = Field( 2180 default=None, 2181 description="ID of the AgentRoutineTemplate Config this routine was last provisioned or updated from (`cfg_...`). `null` for hand-built routines.", 2182 ) 2183 lookup_key: str | None = Field( 2184 default=None, 2185 description="Unique human-readable key used to look up this routine without knowing its ID. `null` when not set.", 2186 ) 2187 metadata: dict[str, Any] | None = Field( 2188 default=None, 2189 description="Arbitrary key-value metadata attached to this routine. `null` when not set.", 2190 ) 2191 name: str | None = Field(default=None, description="Human-readable name for the routine.") 2192 preset_config: PresetConfig | None = Field( 2193 default=None, 2194 description='Resolved preset configuration when `handler_type` is `"preset"`. `null` for other handler types.', 2195 ) 2196 preset_name: str | None = Field( 2197 default=None, 2198 description='Name of the preset invoked when `handler_type` is `"preset"`. `null` for other handler types.', 2199 ) 2200 schedule: str | None = Field( 2201 default=None, 2202 description="Cron expression controlling when the routine fires on a schedule. `null` for event-only routines.", 2203 ) 2204 script: str | None = Field( 2205 default=None, 2206 description='Inline script body executed when `handler_type` is `"script"`. `null` for other handler types.', 2207 ) 2208 status: str | None = Field( 2209 default=None, 2210 description='Lifecycle status of the routine. One of `"draft"`, `"active"`, or `"paused"`. Only `"active"` routines respond to triggers.', 2211 ) 2212 steps: list[dict[str, Any]] | None = Field( 2213 default=None, 2214 description='Ordered list of chain steps (present when handler_type is "chain"). Each step is a plain map with handler_type, optional body fields (preset_name / preset_config / script / config), and step-local plumbing (name, inputs, output_key, on_error).', 2215 ) 2216 trigger_context: str | None = Field( 2217 default=None, 2218 description='Execution context in which runs are created. One of `"event"` (background job) or `"chat_session"` (interactive session). Defaults to `"event"`.', 2219 ) 2220 updated_at: datetime | None = Field( 2221 default=None, description="When this routine was last updated (ISO 8601)." 2222 )
An agent routine defines a reusable handler script, preset, or chain that runs in response to events or on a schedule.
Access control list for the routine. Contains a grants array where each entry specifies principal_type, principal, and actions. null when no ACL restrictions are applied and the routine is accessible to all members of its scope.
config: str | None =
None
ID of the Config record that backs this routine's configuration (cfg_...). null when the routine is not config-backed.
event_config: dict[str, typing.Any] | None =
None
Additional configuration controlling how the event trigger is matched or filtered. Shape depends on event_type. null when not configured.
event_type: str | None =
None
Platform event type that triggers this routine, e.g. "agentroutine.invoked". null for schedule-only routines.
handler_type: str | None =
None
Execution strategy for this routine. One of "workflow_graph", "script", "preset", or "chain".
last_applied_template_config: str | None =
None
ID of the AgentRoutineTemplate Config this routine was last provisioned or updated from (cfg_...). null for hand-built routines.
lookup_key: str | None =
None
Unique human-readable key used to look up this routine without knowing its ID. null when not set.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata attached to this routine. null when not set.
Resolved preset configuration when handler_type is "preset". null for other handler types.
preset_name: str | None =
None
Name of the preset invoked when handler_type is "preset". null for other handler types.
schedule: str | None =
None
Cron expression controlling when the routine fires on a schedule. null for event-only routines.
script: str | None =
None
Inline script body executed when handler_type is "script". null for other handler types.
status: str | None =
None
Lifecycle status of the routine. One of "draft", "active", or "paused". Only "active" routines respond to triggers.
steps: list[dict[str, typing.Any]] | None =
None
Ordered list of chain steps (present when handler_type is "chain"). Each step is a plain map with handler_type, optional body fields (preset_name / preset_config / script / config), and step-local plumbing (name, inputs, output_key, on_error).
class
AgentRoutineListResponse(pydantic.main.BaseModel):
2225class AgentRoutineListResponse(BaseModel): 2226 """ 2227 List of agent routine objects belonging to a given agent. 2228 """ 2229 2230 data: list[AgentRoutine] = Field(..., description="Array of agent routine objects.")
List of agent routine objects belonging to a given agent.
class
AgentRoutineRun(pydantic.main.BaseModel):
2233class AgentRoutineRun(BaseModel): 2234 """ 2235 A single execution of an agent routine, capturing its status, inputs, outputs, and timing. 2236 """ 2237 2238 acl: Acl | None = Field( 2239 default=None, 2240 description="Access control list for the run. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions`. `null` when no ACL restrictions are applied and the run is accessible to all members of its scope.", 2241 ) 2242 agent: str | None = Field( 2243 default=None, description="ID of the agent that owns the parent routine (`agi_...`)." 2244 ) 2245 app: str | None = Field( 2246 default=None, description="Application that scopes this run (`dap_...`)." 2247 ) 2248 created_at: datetime | None = Field( 2249 default=None, description="When this run was created (ISO 8601)." 2250 ) 2251 duration_ms: int | None = Field( 2252 default=None, 2253 description="Total wall-clock time the run took to execute, in milliseconds. `null` while the run is still in progress.", 2254 ) 2255 event_id: str | None = Field( 2256 default=None, 2257 description="Identifier of the platform event that triggered this run. `null` for manually invoked runs.", 2258 ) 2259 id: str = Field(..., description="Routine run ID (`arr_...`).") 2260 metadata: dict[str, Any] | None = Field( 2261 default=None, 2262 description="Arbitrary key-value metadata attached to this run. Empty object when no metadata was set.", 2263 ) 2264 payload: dict[str, Any] | None = Field( 2265 default=None, 2266 description="Input payload delivered to the routine when this run was triggered. Empty object when no payload was provided.", 2267 ) 2268 result: dict[str, Any] | None = Field( 2269 default=None, 2270 description="Output produced by the routine after execution. `null` while the run has not yet completed.", 2271 ) 2272 routine: str | None = Field( 2273 default=None, description="ID of the parent routine that produced this run (`arn_...`)." 2274 ) 2275 status: str | None = Field( 2276 default=None, 2277 description='Current execution status. One of `"pending"`, `"running"`, `"completed"`, `"failed"`, `"skipped"`, or `"cancelled"`.', 2278 ) 2279 structured_response: dict[str, Any] | None = Field( 2280 default=None, 2281 description="Validated structured output extracted from `result` when the routine uses an AgentMessageSchema. `null` if the routine does not use a schema or the run has not completed.", 2282 ) 2283 updated_at: datetime | None = Field( 2284 default=None, description="When this run was last updated (ISO 8601)." 2285 ) 2286 worker: WorkerStatus | None = Field( 2287 default=None, 2288 description="Background worker status. `null` when no worker job is associated with this run.", 2289 )
A single execution of an agent routine, capturing its status, inputs, outputs, and timing.
Access control list for the run. Contains a grants array where each entry specifies principal_type, principal, and actions. null when no ACL restrictions are applied and the run is accessible to all members of its scope.
duration_ms: int | None =
None
Total wall-clock time the run took to execute, in milliseconds. null while the run is still in progress.
event_id: str | None =
None
Identifier of the platform event that triggered this run. null for manually invoked runs.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata attached to this run. Empty object when no metadata was set.
payload: dict[str, typing.Any] | None =
None
Input payload delivered to the routine when this run was triggered. Empty object when no payload was provided.
result: dict[str, typing.Any] | None =
None
Output produced by the routine after execution. null while the run has not yet completed.
status: str | None =
None
Current execution status. One of "pending", "running", "completed", "failed", "skipped", or "cancelled".
structured_response: dict[str, typing.Any] | None =
None
Validated structured output extracted from result when the routine uses an AgentMessageSchema. null if the routine does not use a schema or the run has not completed.
class
AgentRoutineRunListResponse(pydantic.main.BaseModel):
2292class AgentRoutineRunListResponse(BaseModel): 2293 """ 2294 Cursor-paginated list of agent routine run objects, ordered by creation time descending. 2295 """ 2296 2297 after_cursor: str | None = Field( 2298 default=None, 2299 description="Opaque cursor to pass as the after-cursor parameter to fetch the next page of runs. `null` when no later results exist.", 2300 ) 2301 before_cursor: str | None = Field( 2302 default=None, 2303 description="Opaque cursor to pass as the before-cursor parameter to fetch the page of runs that precede this one. `null` when no earlier results exist.", 2304 ) 2305 data: list[AgentRoutineRun] = Field( 2306 ..., description="Array of agent routine run objects for the current page." 2307 )
Cursor-paginated list of agent routine run objects, ordered by creation time descending.
after_cursor: str | None =
None
Opaque cursor to pass as the after-cursor parameter to fetch the next page of runs. null when no later results exist.
before_cursor: str | None =
None
Opaque cursor to pass as the before-cursor parameter to fetch the page of runs that precede this one. null when no earlier results exist.
class
AgentSchedule(pydantic.main.BaseModel):
2310class AgentSchedule(BaseModel): 2311 """ 2312 A scheduled task created by an agent. Supports one-time and recurring (cron-based) execution patterns. 2313 """ 2314 2315 agent: str | None = Field( 2316 default=None, description="ID of the agent that owns this schedule (`agi_...`)." 2317 ) 2318 app: str | None = Field( 2319 default=None, description="ID of the application the schedule belongs to (`dap_...`)." 2320 ) 2321 created_at: datetime | None = Field( 2322 default=None, description="When the schedule was created (ISO 8601)." 2323 ) 2324 cron_expression: str | None = Field( 2325 default=None, 2326 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.', 2327 ) 2328 id: str = Field(..., description="Schedule ID (`asc_...`).") 2329 instructions: str | None = Field( 2330 default=None, 2331 description="The task description the agent will execute when this schedule fires.", 2332 ) 2333 last_run_at: datetime | None = Field( 2334 default=None, 2335 description="UTC datetime of the most recent successful execution. `null` if the schedule has never run.", 2336 ) 2337 max_runs: int | None = Field( 2338 default=None, 2339 description='Maximum number of times a recurring schedule may fire before automatically transitioning to `"completed"`. `null` means no limit.', 2340 ) 2341 metadata: dict[str, Any] | None = Field( 2342 default=None, 2343 description="Arbitrary key-value pairs attached to the schedule by the agent. Not interpreted by the platform.", 2344 ) 2345 next_run_at: datetime | None = Field( 2346 default=None, 2347 description="UTC datetime of the next planned execution. `null` if the schedule has completed, been cancelled, or has not yet been computed.", 2348 ) 2349 run_count: int | None = Field( 2350 default=None, description="Total number of times this schedule has fired." 2351 ) 2352 schedule_type: str | None = Field( 2353 default=None, 2354 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.', 2355 ) 2356 scheduled_at: datetime | None = Field( 2357 default=None, 2358 description='The exact UTC datetime at which a one-time schedule fires. Present only when `schedule_type` is `"once"`. `null` for recurring schedules.', 2359 ) 2360 status: str | None = Field( 2361 default=None, 2362 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).', 2363 ) 2364 thread: str | None = Field( 2365 default=None, 2366 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.", 2367 ) 2368 timezone: str | None = Field( 2369 default=None, 2370 description='IANA timezone name used to interpret the cron expression or `scheduled_at` (e.g. `"America/New_York"`). Defaults to `"Etc/UTC"`.', 2371 ) 2372 updated_at: datetime | None = Field( 2373 default=None, description="When the schedule was last modified (ISO 8601)." 2374 )
A scheduled task created by an agent. Supports one-time and recurring (cron-based) execution patterns.
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
AgentSession(pydantic.main.BaseModel):
2377class AgentSession(BaseModel): 2378 """ 2379 A durable agent session record representing a single AI task execution. Tracks status, trajectory, result, and any inbox messages delivered to the session. 2380 """ 2381 2382 agent: str | None = Field( 2383 default=None, description="ID of the agent that owns this session (`agi_...`)." 2384 ) 2385 completed_at: datetime | None = Field( 2386 default=None, 2387 description='When the session reached a terminal state (`"completed"`, `"failed"`, or `"cancelled"`). `null` if still in progress.', 2388 ) 2389 created_at: datetime | None = Field( 2390 default=None, description="When the session was created (ISO 8601)." 2391 ) 2392 error: str | None = Field( 2393 default=None, 2394 description='Human-readable error message describing why the session failed. `null` unless `status` is `"failed"`.', 2395 ) 2396 id: str = Field(..., description="Session ID (`ase_...`).") 2397 inbox: list[dict[str, Any]] | None = Field( 2398 default=None, 2399 description='Ordered list of messages delivered to the session\'s inbox while it was in the `"waiting"` state. Each entry includes `id`, `role`, `content`, `sender_id`, `sender_type`, `sent_at`, and `metadata`.', 2400 ) 2401 instructions: str | None = Field( 2402 default=None, description="The task the agent is instructed to perform in this session." 2403 ) 2404 is_system_session: bool | None = Field( 2405 default=None, 2406 description="`true` if this session was created by the platform internally (e.g. by a schedule or health action) rather than by a user or API caller.", 2407 ) 2408 max_runs_per_turn: int | None = Field( 2409 default=None, 2410 description="Maximum number of tool calls the agent may make within a single turn. Defaults to `25`.", 2411 ) 2412 max_tokens: int | None = Field( 2413 default=None, 2414 description="Maximum number of tokens the session may consume across all turns before being terminated. Defaults to `20000`.", 2415 ) 2416 max_turns: int | None = Field( 2417 default=None, 2418 description="Maximum number of agent turns (LLM calls) allowed before the session is forcibly terminated. Defaults to `100`.", 2419 ) 2420 metadata: dict[str, Any] | None = Field( 2421 default=None, 2422 description="Arbitrary key-value pairs attached to the session. Not interpreted by the platform.", 2423 ) 2424 name: str | None = Field( 2425 default=None, 2426 description="Optional human-readable label for the session. `null` when not set.", 2427 ) 2428 result: dict[str, Any] | None = Field( 2429 default=None, 2430 description="Structured output produced by the session on successful completion. Shape is agent-defined. `null` while the session is still running or if it failed.", 2431 ) 2432 started_at: datetime | None = Field( 2433 default=None, description='When the session began executing. `null` if still `"pending"`.' 2434 ) 2435 status: str | None = Field( 2436 default=None, 2437 description='Current execution status. One of `"pending"` (queued, not yet started), `"running"` (actively executing), `"waiting"` (paused for an inbox message or external event), `"completed"` (finished successfully), `"failed"` (terminated with an error), or `"cancelled"` (manually stopped).', 2438 ) 2439 trajectory: str | None = Field( 2440 default=None, 2441 description="ID of the trajectory that records the full message history for this session (`trj_...`). `null` until the session has started.", 2442 )
A durable agent session record representing a single AI task execution. Tracks status, trajectory, result, and any inbox messages delivered to the session.
completed_at: datetime.datetime | None =
None
When the session reached a terminal state ("completed", "failed", or "cancelled"). null if still in progress.
error: str | None =
None
Human-readable error message describing why the session failed. null unless status is "failed".
is_system_session: bool | None =
None
true if this session was created by the platform internally (e.g. by a schedule or health action) rather than by a user or API caller.
max_runs_per_turn: int | None =
None
Maximum number of tool calls the agent may make within a single turn. Defaults to 25.
max_tokens: int | None =
None
Maximum number of tokens the session may consume across all turns before being terminated. Defaults to 20000.
max_turns: int | None =
None
Maximum number of agent turns (LLM calls) allowed before the session is forcibly terminated. Defaults to 100.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value pairs attached to the session. Not interpreted by the platform.
result: dict[str, typing.Any] | None =
None
Structured output produced by the session on successful completion. Shape is agent-defined. null while the session is still running or if it failed.
started_at: datetime.datetime | None =
None
When the session began executing. null if still "pending".
class
AgentSessionListResponse(pydantic.main.BaseModel):
2445class AgentSessionListResponse(BaseModel): 2446 """ 2447 Paginated list response containing an array of agent session objects. 2448 """ 2449 2450 data: list[AgentSession] = Field( 2451 ..., description="Array of agent session objects for the current page." 2452 )
Paginated list response containing an array of agent session objects.
class
AgentSkill(pydantic.main.BaseModel):
2455class AgentSkill(BaseModel): 2456 """ 2457 A skill enabled on an agent, linking the agent to a skill configuration. Controls which capabilities the agent has access to. 2458 """ 2459 2460 agent: str | None = Field( 2461 default=None, description="ID of the agent this skill is attached to (`agi_...`)." 2462 ) 2463 app: str | None = Field( 2464 default=None, description="ID of the application this skill belongs to (`dap_...`)." 2465 ) 2466 config: str | None = Field( 2467 default=None, 2468 description="ID of the root skill config record that defines this skill's behavior (`cfg_...`).", 2469 ) 2470 created_at: datetime | None = Field( 2471 default=None, description="When the skill was added to the agent (ISO 8601)." 2472 ) 2473 id: str = Field(..., description="Skill ID (`ask_...`).") 2474 instruction: str | None = Field( 2475 default=None, 2476 description="Optional instruction text that overrides the default skill instructions for this specific agent. `null` when no override is set.", 2477 ) 2478 last_applied_template_config: str | None = Field( 2479 default=None, 2480 description="ID of the agent template config from which this skill was last provisioned or updated (`cfg_...`). `null` if the skill was not provisioned from a template.", 2481 ) 2482 metadata: dict[str, Any] | None = Field( 2483 default=None, 2484 description="Arbitrary key-value pairs attached to the skill. Not interpreted by the platform.", 2485 ) 2486 status: str | None = Field( 2487 default=None, 2488 description='Whether the skill is currently in use. `"active"` means the agent will use this skill during sessions. `"inactive"` means it is disabled but not deleted.', 2489 ) 2490 updated_at: datetime | None = Field( 2491 default=None, description="When the skill was last modified (ISO 8601)." 2492 )
A skill enabled on an agent, linking the agent to a skill configuration. Controls which capabilities the agent has access to.
config: str | None =
None
ID of the root skill config record that defines this skill's behavior (cfg_...).
instruction: str | None =
None
Optional instruction text that overrides the default skill instructions for this specific agent. null when no override is set.
last_applied_template_config: str | None =
None
ID of the agent template config from which this skill was last provisioned or updated (cfg_...). null if the skill was not provisioned from a template.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value pairs attached to the skill. Not interpreted by the platform.
class
AgentSkillList(pydantic.main.BaseModel):
2495class AgentSkillList(BaseModel): 2496 """ 2497 Paginated list response containing an array of agent skill objects. 2498 """ 2499 2500 data: list[AgentSkill] = Field( 2501 ..., description="Array of agent skill objects for the current page." 2502 )
Paginated list response containing an array of agent skill objects.
class
AgentTool(pydantic.main.BaseModel):
2505class AgentTool(BaseModel): 2506 """ 2507 A tool attached to an agent, defining a capability the agent can invoke during a conversation or task run. 2508 """ 2509 2510 model_config = ConfigDict(populate_by_name=True) 2511 2512 agent: str | None = Field( 2513 default=None, description="ID of the agent this tool belongs to (`agi_...`)." 2514 ) 2515 app: str | None = Field( 2516 default=None, description="ID of the application that owns this tool (`dap_...`)." 2517 ) 2518 async_: bool | None = Field( 2519 default=None, 2520 alias="async", 2521 description="`true` when the tool executes asynchronously and returns a task handle rather than an immediate result.", 2522 ) 2523 builtin_tool_config: dict[str, Any] | None = Field( 2524 default=None, 2525 description='Provider-specific configuration for the built-in tool. Present only when `kind` is `"builtin"`. Shape varies by `builtin_tool_key`.', 2526 ) 2527 builtin_tool_key: str | None = Field( 2528 default=None, 2529 description='Registry key identifying the built-in tool implementation. Present only when `kind` is `"builtin"`.', 2530 ) 2531 config: str | None = Field( 2532 default=None, 2533 description="ID of the config record (`cfg_...`) containing this tool's full configuration. `null` for inline-only tools.", 2534 ) 2535 created_at: datetime | None = Field( 2536 default=None, description="When the tool was created (ISO 8601)." 2537 ) 2538 description: str | None = Field( 2539 default=None, 2540 description='Description of what the tool does, passed to the LLM as part of the tool definition. Resolved from the built-in registry for `kind: "builtin"` tools.', 2541 ) 2542 handler_type: str | None = Field( 2543 default=None, 2544 description='Execution handler type. One of `"http"`, `"script"`, or `"builtin"`.', 2545 ) 2546 id: str = Field(..., description="Tool ID (`atl_...`).") 2547 instruction: str | None = Field( 2548 default=None, 2549 description="Optional system-level instruction appended to the agent prompt when this tool is active.", 2550 ) 2551 kind: str | None = Field( 2552 default=None, description='Tool kind. One of `"builtin"`, `"custom"`, or `"mcp"`.' 2553 ) 2554 last_applied_template_config: str | None = Field( 2555 default=None, 2556 description="ID of the AgentToolTemplate config (`cfg_...`) this tool was last provisioned or updated from. `null` for manually created tools.", 2557 ) 2558 lookup_key: str | None = Field( 2559 default=None, 2560 description="Stable, user-defined identifier for this tool within the agent. Unique per agent.", 2561 ) 2562 metadata: dict[str, Any] | None = Field( 2563 default=None, 2564 description="Arbitrary key-value metadata attached to the tool. Not interpreted by the platform.", 2565 ) 2566 name: str | None = Field( 2567 default=None, 2568 description='Human-readable name of the tool as exposed to the LLM. Resolved from the built-in registry for `kind: "builtin"` tools.', 2569 ) 2570 name_prefix: str | None = Field( 2571 default=None, 2572 description="Per-instance namespace prepended to LLM-facing tool names for built-in tools that support multiple instances per agent. `null` when not applicable.", 2573 ) 2574 parameters: dict[str, Any] | None = Field( 2575 default=None, 2576 description="JSON Schema object describing the tool's input parameters as presented to the LLM.", 2577 ) 2578 parameters_config: str | None = Field( 2579 default=None, 2580 description="ID of the config record (`cfg_...`) storing the tool's parameter schema. `null` when parameters are defined inline.", 2581 ) 2582 status: str | None = Field( 2583 default=None, description='Current status of the tool. One of `"active"` or `"disabled"`.' 2584 ) 2585 updated_at: datetime | None = Field( 2586 default=None, description="When the tool was last modified (ISO 8601)." 2587 )
A tool attached to an agent, defining a capability the agent can invoke during a conversation or task run.
async_: bool | None =
None
true when the tool executes asynchronously and returns a task handle rather than an immediate result.
builtin_tool_config: dict[str, typing.Any] | None =
None
Provider-specific configuration for the built-in tool. Present only when kind is "builtin". Shape varies by builtin_tool_key.
builtin_tool_key: str | None =
None
Registry key identifying the built-in tool implementation. Present only when kind is "builtin".
config: str | None =
None
ID of the config record (cfg_...) containing this tool's full configuration. null for inline-only tools.
description: str | None =
None
Description of what the tool does, passed to the LLM as part of the tool definition. Resolved from the built-in registry for kind: "builtin" tools.
instruction: str | None =
None
Optional system-level instruction appended to the agent prompt when this tool is active.
last_applied_template_config: str | None =
None
ID of the AgentToolTemplate config (cfg_...) this tool was last provisioned or updated from. null for manually created tools.
lookup_key: str | None =
None
Stable, user-defined identifier for this tool within the agent. Unique per agent.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata attached to the tool. Not interpreted by the platform.
name: str | None =
None
Human-readable name of the tool as exposed to the LLM. Resolved from the built-in registry for kind: "builtin" tools.
name_prefix: str | None =
None
Per-instance namespace prepended to LLM-facing tool names for built-in tools that support multiple instances per agent. null when not applicable.
parameters: dict[str, typing.Any] | None =
None
JSON Schema object describing the tool's input parameters as presented to the LLM.
class
AgentToolListResponse(pydantic.main.BaseModel):
2590class AgentToolListResponse(BaseModel): 2591 """ 2592 Paginated list response containing the tools attached to an agent. 2593 """ 2594 2595 data: list[AgentTool] = Field( 2596 ..., description="Array of agent tool objects returned for the current request." 2597 )
Paginated list response containing the tools attached to an agent.
class
AgentUpgradeFieldChange(pydantic.main.BaseModel):
2600class AgentUpgradeFieldChange(BaseModel): 2601 """ 2602 One field-level diff entry within an agent upgrade change, describing how a single field will change. 2603 `baseline` and `locally_edited` are populated only for `agent_base` entries; child resource entries (tools, routines, skills, computers) carry only `field`, `old`, and `new`. 2604 """ 2605 2606 baseline: Any | None = Field( 2607 default=None, 2608 description="Value that was set by the last-applied template version (pinned baseline). Populated only on `agent_base` field changes. `null` when no baseline is available (legacy agent or deleted version).", 2609 ) 2610 field: str = Field( 2611 ..., description='Name of the field that will change, e.g. `"name"` or `"identity"`.' 2612 ) 2613 locally_edited: bool | None = Field( 2614 default=None, 2615 description="`true` when the agent's current value differs from `baseline`, indicating a local edit that this upgrade will overwrite. `false` when the current value matches the baseline. `null` when `baseline` is unavailable. Populated only on `agent_base` field changes.", 2616 ) 2617 new: Any | None = Field( 2618 default=None, 2619 description="Incoming value the field will be set to after the upgrade (string, number, boolean, or `null`).", 2620 ) 2621 old: Any | None = Field( 2622 default=None, 2623 description="Current value of the field before the upgrade (string, number, boolean, or `null`).", 2624 )
One field-level diff entry within an agent upgrade change, describing how a single field will change.
baseline and locally_edited are populated only for agent_base entries; child resource entries (tools, routines, skills, computers) carry only field, old, and new.
baseline: typing.Any | None =
None
Value that was set by the last-applied template version (pinned baseline). Populated only on agent_base field changes. null when no baseline is available (legacy agent or deleted version).
class
AgentUpgradeChange(pydantic.main.BaseModel):
2627class AgentUpgradeChange(BaseModel): 2628 """ 2629 One child-resource change produced by an agent upgrade, describing the action to be taken on a single resource. 2630 """ 2631 2632 action: str = Field( 2633 ..., 2634 description='The operation that will be performed. One of `"add"`, `"update"`, `"remove"`, or `"noop"`.', 2635 ) 2636 description: str | None = Field( 2637 default=None, 2638 description="Description of the child resource this change touches, when one is set. `null` when no description is available.", 2639 ) 2640 field_changes: list[AgentUpgradeFieldChange] | None = Field( 2641 default=None, 2642 description='Field-level diff entries for this change. Populated only when `action` is `"update"`; empty or absent for `add`, `remove`, and `noop` entries.', 2643 ) 2644 id: str | None = Field( 2645 default=None, 2646 description="Public ID of the existing resource being updated or removed (e.g. `atl_...`, `arn_...`). `null` for `add` entries.", 2647 ) 2648 key: str | None = Field( 2649 default=None, 2650 description="Lookup key of the resource derived from its source template. `null` when the template has no lookup key.", 2651 ) 2652 name: str | None = Field( 2653 default=None, 2654 description="Human-facing name of the child resource this change touches (tool/routine/skill/computer name, or builtin tool key for unnamed builtin tools). Falls back to the source template's name. `null` for the synthetic `agent_base` entry.", 2655 ) 2656 parent_template_config: UpgradeTemplateSummary = Field( 2657 ..., 2658 description="Summary of the parent AgentTemplate config (`cfg_...`) being applied in this upgrade.", 2659 ) 2660 resource: dict[str, Any] | None = Field( 2661 default=None, 2662 description="Resource-type-specific identity details. Tools: `tool_type`, `builtin_tool_key`, `name_prefix`, `handler_type`, `instruction`. Routines: `handler_type`, `preset_name`, `event_type`, `schedule`, `trigger_context`. Skills: `instruction`. Computers: `region`. Only populated keys are present; `null` when nothing is known.", 2663 ) 2664 resource_type: str = Field( 2665 ..., 2666 description='Type of the child resource being changed. One of `"agent"`, `"tool"`, `"routine"`, `"skill"`, or `"computer"`.', 2667 ) 2668 source_template_config: UpgradeTemplateSummary | None = Field( 2669 default=None, 2670 description="Summary of the specific child template config (`cfg_...`) that defines this resource. `null` when no source template is resolvable.", 2671 )
One child-resource change produced by an agent upgrade, describing the action to be taken on a single resource.
action: str =
PydanticUndefined
The operation that will be performed. One of "add", "update", "remove", or "noop".
description: str | None =
None
Description of the child resource this change touches, when one is set. null when no description is available.
Field-level diff entries for this change. Populated only when action is "update"; empty or absent for add, remove, and noop entries.
id: str | None =
None
Public ID of the existing resource being updated or removed (e.g. atl_..., arn_...). null for add entries.
key: str | None =
None
Lookup key of the resource derived from its source template. null when the template has no lookup key.
name: str | None =
None
Human-facing name of the child resource this change touches (tool/routine/skill/computer name, or builtin tool key for unnamed builtin tools). Falls back to the source template's name. null for the synthetic agent_base entry.
resource: dict[str, typing.Any] | None =
None
Resource-type-specific identity details. Tools: tool_type, builtin_tool_key, name_prefix, handler_type, instruction. Routines: handler_type, preset_name, event_type, schedule, trigger_context. Skills: instruction. Computers: region. Only populated keys are present; null when nothing is known.
resource_type: str =
PydanticUndefined
Type of the child resource being changed. One of "agent", "tool", "routine", "skill", or "computer".
class
AgentUpgradeSummary(pydantic.main.BaseModel):
2674class AgentUpgradeSummary(BaseModel): 2675 """ 2676 Aggregate counts of each change type produced by an agent upgrade diff. 2677 """ 2678 2679 adds: int = Field( 2680 ..., description="Number of child resources that will be created by this upgrade." 2681 ) 2682 noops: int = Field( 2683 ..., description="Number of child resources with no changes in this upgrade." 2684 ) 2685 removes: int = Field( 2686 ..., description="Number of child resources that will be removed by this upgrade." 2687 ) 2688 updates: int = Field( 2689 ..., description="Number of child resources that will be updated by this upgrade." 2690 )
Aggregate counts of each change type produced by an agent upgrade diff.
class
AgentUpgradeResult(pydantic.main.BaseModel):
2693class AgentUpgradeResult(BaseModel): 2694 """ 2695 The computed diff and outcome of an agent upgrade operation, including the full list of per-resource changes. 2696 """ 2697 2698 changes: list[AgentUpgradeChange] = Field( 2699 ..., 2700 description="Ordered list of per-resource changes that will be (or were) applied by this upgrade.", 2701 ) 2702 dry_run: bool = Field( 2703 ..., 2704 description="`true` when the request was a dry run and no changes were persisted to the agent.", 2705 ) 2706 mode: str = Field( 2707 ..., 2708 description='Upgrade mode that was used. One of `"full"` (apply all changes) or `"review"` (require fingerprint confirmation).', 2709 ) 2710 review_fingerprint: str | None = Field( 2711 default=None, 2712 description='Opaque fingerprint of the computed diff. Pass this value back as `review_fingerprint` to confirm and apply a `"review"` mode upgrade.', 2713 ) 2714 status: str = Field( 2715 ..., 2716 description='Outcome of the upgrade. `"ready"` for a dry-run (no changes applied); `"upgraded"` when the upgrade was committed.', 2717 ) 2718 summary: AgentUpgradeSummary = Field( 2719 ..., 2720 description="Aggregate counts of adds, updates, removes, and noops across all child resources.", 2721 )
The computed diff and outcome of an agent upgrade operation, including the full list of per-resource changes.
dry_run: bool =
PydanticUndefined
true when the request was a dry run and no changes were persisted to the agent.
mode: str =
PydanticUndefined
Upgrade mode that was used. One of "full" (apply all changes) or "review" (require fingerprint confirmation).
review_fingerprint: str | None =
None
Opaque fingerprint of the computed diff. Pass this value back as review_fingerprint to confirm and apply a "review" mode upgrade.
status: str =
PydanticUndefined
Outcome of the upgrade. "ready" for a dry-run (no changes applied); "upgraded" when the upgrade was committed.
class
AgentUpgradeResponse(pydantic.main.BaseModel):
2724class AgentUpgradeResponse(BaseModel): 2725 """ 2726 Response returned by the agent upgrade endpoint, combining the updated agent, its source Solution and template, and the full upgrade diff. 2727 """ 2728 2729 agent: Agent | None = Field( 2730 default=None, 2731 description="The agent after the upgrade has been applied. `null` for dry-run requests where no changes were persisted.", 2732 ) 2733 solution: SolutionSummary = Field( 2734 ..., description="Summary of the parent Solution the agent was upgraded from." 2735 ) 2736 template: UpgradeTemplateSummary = Field( 2737 ..., 2738 description="Summary of the AgentTemplate config (`cfg_...`) that was selected for this upgrade.", 2739 ) 2740 upgrade_result: AgentUpgradeResult = Field( 2741 ..., 2742 description="Full upgrade diff including status, mode, dry-run flag, summary counts, and per-resource change list.", 2743 )
Response returned by the agent upgrade endpoint, combining the updated agent, its source Solution and template, and the full upgrade diff.
The agent after the upgrade has been applied. null for dry-run requests where no changes were persisted.
class
SolutionCategorySummary(pydantic.main.BaseModel):
2746class SolutionCategorySummary(BaseModel): 2747 """ 2748 A solution category that organizes solutions in the catalog, identified by a stable key and optionally nested under a parent category. 2749 """ 2750 2751 created_at: datetime | None = Field( 2752 default=None, 2753 description="When this category was first created (ISO 8601). `null` for system-built-in categories.", 2754 ) 2755 description: str | None = Field( 2756 default=None, 2757 description="Short prose description of what solutions in this category do. `null` when not configured.", 2758 ) 2759 id: str = Field(..., description="Solution category config ID (`cfg_...`).") 2760 key: str = Field( 2761 ..., 2762 description="Stable, human-readable key for this category, referenced by solutions via `category_keys`.", 2763 ) 2764 kind: str = Field(..., description='Resource type identifier. Always `"SolutionCategory"`.') 2765 lookup_key: str | None = Field( 2766 default=None, description="Lookup key of the underlying config record. `null` when not set." 2767 ) 2768 metadata: dict[str, Any] | None = Field( 2769 default=None, 2770 description="Arbitrary key-value metadata attached to this category by the publisher.", 2771 ) 2772 name: str | None = Field( 2773 default=None, description="Display name shown to users. `null` when not configured." 2774 ) 2775 org: str | None = Field( 2776 default=None, 2777 description="Organization ID (`org_...`) that owns this category. `null` for system-scoped categories.", 2778 ) 2779 owners: list[str] = Field( 2780 ..., 2781 description='Scopes under which this category is visible. Possible values are `"system"` (available to all apps) and `"org"` (scoped to the viewer\'s organization).', 2782 ) 2783 parent_key: str | None = Field( 2784 default=None, 2785 description="Key of the parent `SolutionCategory`, enabling a hierarchy. `null` for top-level categories.", 2786 ) 2787 sort_order: int | None = Field( 2788 default=None, 2789 description="Numeric hint for ordering categories in a list. Lower values sort first. `null` when not configured.", 2790 ) 2791 updated_at: datetime | None = Field( 2792 default=None, 2793 description="When this category was last modified (ISO 8601). `null` for system-built-in categories.", 2794 ) 2795 virtual_path: str | None = Field( 2796 default=None, 2797 description="Virtual path of the underlying config record. `null` when not set.", 2798 )
A solution category that organizes solutions in the catalog, identified by a stable key and optionally nested under a parent category.
created_at: datetime.datetime | None =
None
When this category was first created (ISO 8601). null for system-built-in categories.
description: str | None =
None
Short prose description of what solutions in this category do. null when not configured.
key: str =
PydanticUndefined
Stable, human-readable key for this category, referenced by solutions via category_keys.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata attached to this category by the publisher.
org: str | None =
None
Organization ID (org_...) that owns this category. null for system-scoped categories.
owners: list[str] =
PydanticUndefined
Scopes under which this category is visible. Possible values are "system" (available to all apps) and "org" (scoped to the viewer's organization).
parent_key: str | None =
None
Key of the parent SolutionCategory, enabling a hierarchy. null for top-level categories.
sort_order: int | None =
None
Numeric hint for ordering categories in a list. Lower values sort first. null when not configured.
class
SolutionCategoryListResponse(pydantic.main.BaseModel):
2801class SolutionCategoryListResponse(BaseModel): 2802 """ 2803 Paginated list of solution category summaries. Use `page` and `page_size` to navigate pages of results. 2804 """ 2805 2806 data: list[SolutionCategorySummary] = Field( 2807 ..., description="Array of solution category summary objects for the current page." 2808 ) 2809 has_next: bool = Field(..., description="`true` when a subsequent page of results exists.") 2810 has_prev: bool = Field(..., description="`true` when a previous page of results exists.") 2811 page: int = Field(..., description="Current page number (1-indexed).") 2812 page_size: int = Field(..., description="Maximum number of entries returned per page.") 2813 total_entries: int = Field( 2814 ..., description="Total number of distinct solution categories across all pages." 2815 ) 2816 total_pages: int = Field( 2817 ..., description="Total number of pages available at the current `page_size`." 2818 )
class
SolutionDependentAgent(pydantic.main.BaseModel):
2821class SolutionDependentAgent(BaseModel): 2822 """ 2823 A brief representation of an agent that references at least one config bundled by a Solution, included in the dependents preview response. 2824 """ 2825 2826 id: str = Field(..., description="Agent ID (`agi_...`).") 2827 name: str | None = Field( 2828 default=None, 2829 description="Human-readable display name of the agent. `null` when no name has been set.", 2830 )
A brief representation of an agent that references at least one config bundled by a Solution, included in the dependents preview response.
class
SolutionDependentsResponse(pydantic.main.BaseModel):
2833class SolutionDependentsResponse(BaseModel): 2834 """ 2835 A preview of the agents and configs that would be affected by deleting a Solution, returned before any deletion occurs so the caller can display a confirmation warning. 2836 """ 2837 2838 dependent_agent_count: int = Field( 2839 ..., 2840 description="Total number of distinct agents that reference at least one config bundled by this Solution. Use this count in the confirmation message; `dependent_agents` may be a shorter sample.", 2841 ) 2842 dependent_agents: list[SolutionDependentAgent] = Field( 2843 ..., 2844 description="A representative sample of the dependent agents, suitable for displaying in a warning list. May contain fewer entries than `dependent_agent_count` when there are many dependents.", 2845 ) 2846 preserved_config_count: int = Field( 2847 ..., 2848 description="Number of bundled configs that would be detached and preserved rather than deleted, because at least one live agent still references them.", 2849 )
A preview of the agents and configs that would be affected by deleting a Solution, returned before any deletion occurs so the caller can display a confirmation warning.
dependent_agent_count: int =
PydanticUndefined
Total number of distinct agents that reference at least one config bundled by this Solution. Use this count in the confirmation message; dependent_agents may be a shorter sample.
A representative sample of the dependent agents, suitable for displaying in a warning list. May contain fewer entries than dependent_agent_count when there are many dependents.
class
SolutionDiffReference(pydantic.main.BaseModel):
2852class SolutionDiffReference(BaseModel): 2853 """ 2854 A reference from another config to an orphaned entry in a solution upgrade diff, explaining why the orphan cannot be safely removed. 2855 """ 2856 2857 id: str = Field(..., description="ID of the referencing config (`cfg_...`).") 2858 kind: str = Field( 2859 ..., 2860 description='Object type of the referencing config, e.g. `"Automation"` or `"Template"`.', 2861 ) 2862 lookup_key: str | None = Field( 2863 default=None, 2864 description="Human-readable stable identifier of the referencing config. `null` if not assigned.", 2865 ) 2866 reason: str = Field( 2867 ..., description="Explanation of how the referencing config depends on the orphaned entry." 2868 )
A reference from another config to an orphaned entry in a solution upgrade diff, explaining why the orphan cannot be safely removed.
kind: str =
PydanticUndefined
Object type of the referencing config, e.g. "Automation" or "Template".
class
SolutionDiffEntry(pydantic.main.BaseModel):
2871class SolutionDiffEntry(BaseModel): 2872 """ 2873 A single config entry in a solution upgrade diff, describing what action will be taken on a specific config key. 2874 """ 2875 2876 action: str = Field( 2877 ..., 2878 description='Planned action for this entry. One of `"add"` (new config), `"update"` (existing config changes), `"noop"` (no change needed), `"orphan"` (config no longer in the solution), or `"delete"` (config to be removed).', 2879 ) 2880 content_changed: bool = Field( 2881 ..., 2882 description="`true` if the config content differs between the existing and incoming solution versions.", 2883 ) 2884 id: str | None = Field( 2885 default=None, 2886 description="Config ID (`cfg_...`) if this entry corresponds to an existing config record. `null` for new additions.", 2887 ) 2888 key: str = Field( 2889 ..., description="Stable string key identifying this config entry within the solution." 2890 ) 2891 kind: str | None = Field( 2892 default=None, 2893 description='Config object type, e.g. `"Automation"` or `"Template"`. `null` if not yet known.', 2894 ) 2895 lookup_key: str | None = Field( 2896 default=None, 2897 description="Human-readable stable identifier for this config. `null` if not assigned.", 2898 ) 2899 mime_type_changed: bool = Field( 2900 ..., description="`true` if the MIME type of the config changed between versions." 2901 ) 2902 referenced_by: list[SolutionDiffReference] | None = Field( 2903 default=None, 2904 description="List of other configs that reference this entry. Populated for orphaned configs that cannot be safely removed. Empty array when there are no references.", 2905 ) 2906 relative_path_changed: bool = Field( 2907 ..., 2908 description="`true` if the relative path of the config within the solution changed between versions.", 2909 ) 2910 role: str = Field( 2911 ..., 2912 description="Role of this config within the solution. Indicates whether it is a primary config or a dependency.", 2913 ) 2914 virtual_path: str | None = Field( 2915 default=None, 2916 description="Hierarchical path of this config in the config tree. `null` if not assigned.", 2917 )
A single config entry in a solution upgrade diff, describing what action will be taken on a specific config key.
action: str =
PydanticUndefined
Planned action for this entry. One of "add" (new config), "update" (existing config changes), "noop" (no change needed), "orphan" (config no longer in the solution), or "delete" (config to be removed).
content_changed: bool =
PydanticUndefined
true if the config content differs between the existing and incoming solution versions.
id: str | None =
None
Config ID (cfg_...) if this entry corresponds to an existing config record. null for new additions.
lookup_key: str | None =
None
Human-readable stable identifier for this config. null if not assigned.
mime_type_changed: bool =
PydanticUndefined
true if the MIME type of the config changed between versions.
List of other configs that reference this entry. Populated for orphaned configs that cannot be safely removed. Empty array when there are no references.
relative_path_changed: bool =
PydanticUndefined
true if the relative path of the config within the solution changed between versions.
class
SolutionDiffSummary(pydantic.main.BaseModel):
2920class SolutionDiffSummary(BaseModel): 2921 """ 2922 Aggregate counts of each action type across all entries in a solution upgrade diff. 2923 """ 2924 2925 adds: int = Field( 2926 ..., description="Number of config entries that will be newly created by this upgrade." 2927 ) 2928 deletes: int = Field( 2929 ..., description="Number of config entries that will be deleted as part of the upgrade." 2930 ) 2931 noops: int = Field( 2932 ..., 2933 description="Number of config entries that are already up to date and require no changes.", 2934 ) 2935 orphans: int = Field( 2936 ..., 2937 description="Number of config entries present in the existing solution that are absent from the incoming version and have no external references blocking removal.", 2938 ) 2939 referenced_orphans: int = Field( 2940 ..., 2941 description="Number of orphaned config entries that cannot be removed because other configs still reference them.", 2942 ) 2943 updates: int = Field( 2944 ..., description="Number of config entries that exist and will be updated with new content." 2945 )
Aggregate counts of each action type across all entries in a solution upgrade diff.
deletes: int =
PydanticUndefined
Number of config entries that will be deleted as part of the upgrade.
noops: int =
PydanticUndefined
Number of config entries that are already up to date and require no changes.
orphans: int =
PydanticUndefined
Number of config entries present in the existing solution that are absent from the incoming version and have no external references blocking removal.
class
SolutionImportResult(pydantic.main.BaseModel):
2948class SolutionImportResult(BaseModel): 2949 """ 2950 The machine-readable outcome of a Solution import attempt, indicating whether the import succeeded or requires an upgrade flow to resolve a version conflict. 2951 """ 2952 2953 code: str | None = Field( 2954 default=None, 2955 description='Machine-readable conflict code present when `status` is `"conflict"`, identifying the specific conflict reason. `null` when `status` is `"ready"`.', 2956 ) 2957 dry_run: bool = Field( 2958 ..., 2959 description="Whether this result was produced by a dry-run check. `true` when the import was validated without persisting any changes.", 2960 ) 2961 existing_solution_version: str | None = Field( 2962 default=None, 2963 description="Semver string of the Solution version already present in the library. `null` when no prior version exists.", 2964 ) 2965 incoming_solution_version: str | None = Field( 2966 default=None, 2967 description="Semver string of the Solution version in the bundle being imported. `null` when the bundle does not declare a version.", 2968 ) 2969 message: str | None = Field( 2970 default=None, 2971 description="Human-readable description of the import status or conflict reason, suitable for display in a confirmation dialog. `null` when no detail is available.", 2972 ) 2973 status: str = Field( 2974 ..., 2975 description='Outcome of the import check. `"ready"` means the import can proceed as a normal create or update. `"conflict"` means a version conflict was detected and the upgrade flow must be used instead.', 2976 ) 2977 upgrade_required: bool = Field( 2978 ..., 2979 description='Whether the caller must invoke the dedicated upgrade flow to complete the import. Mirrors `status == "conflict"` as a convenience boolean.', 2980 )
The machine-readable outcome of a Solution import attempt, indicating whether the import succeeded or requires an upgrade flow to resolve a version conflict.
dry_run: bool =
PydanticUndefined
Whether this result was produced by a dry-run check. true when the import was validated without persisting any changes.
existing_solution_version: str | None =
None
Semver string of the Solution version already present in the library. null when no prior version exists.
incoming_solution_version: str | None =
None
Semver string of the Solution version in the bundle being imported. null when the bundle does not declare a version.
message: str | None =
None
Human-readable description of the import status or conflict reason, suitable for display in a confirmation dialog. null when no detail is available.
class
SolutionImportResponse(pydantic.main.BaseModel):
2983class SolutionImportResponse(BaseModel): 2984 """ 2985 The result of importing a Solution bundle into the library, including the Solution config record, a structured import result, and the list of all configs persisted during the transaction. 2986 """ 2987 2988 created_at: datetime | None = Field( 2989 default=None, description="When the Solution config record was first created (ISO 8601)." 2990 ) 2991 id: str = Field(..., description="Solution config ID (`cfg_...`).") 2992 import_result: SolutionImportResult = Field( 2993 ..., 2994 description="Structured outcome of the import, including status, conflict details, and version information.", 2995 ) 2996 installed_configs: list[InstalledConfigEntry] | None = Field( 2997 default=None, 2998 description="Deprecated legacy field. One entry per persisted config in the import (including the Solution itself), defaulting to an empty array. Callers should prefer `solution` plus follow-up APIs instead. `key` echoes the caller-supplied input identifier (original lookup_key for top-level configs; `<skill_lookup_key>:<relative_path>` for skill / solution-file children). Order is stable: sorted by `key`.", 2999 ) 3000 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 3001 lookup_key: str | None = Field( 3002 default=None, 3003 description="The `lookup_key` stored on the Solution config after the import's suffix normalization. `null` when the Solution was not given a lookup key.", 3004 ) 3005 solution: SolutionSummary = Field( 3006 ..., 3007 description="Full summary of the imported Solution, in the same shape as the individual Solution retrieval endpoint.", 3008 ) 3009 updated_at: datetime | None = Field( 3010 default=None, description="When the Solution config record was last modified (ISO 8601)." 3011 ) 3012 virtual_path: str | None = Field( 3013 default=None, 3014 description="The `virtual_path` stored on the Solution config, used as the stable dedupe key across owner scopes. `null` when no virtual path was assigned.", 3015 )
The result of importing a Solution bundle into the library, including the Solution config record, a structured import result, and the list of all configs persisted during the transaction.
created_at: datetime.datetime | None =
None
When the Solution config record was first created (ISO 8601).
Deprecated legacy field. One entry per persisted config in the import (including the Solution itself), defaulting to an empty array. Callers should prefer solution plus follow-up APIs instead. key echoes the caller-supplied input identifier (original lookup_key for top-level configs; <skill_lookup_key>:<relative_path> for skill / solution-file children). Order is stable: sorted by key.
lookup_key: str | None =
None
The lookup_key stored on the Solution config after the import's suffix normalization. null when the Solution was not given a lookup key.
Full summary of the imported Solution, in the same shape as the individual Solution retrieval endpoint.
updated_at: datetime.datetime | None =
None
When the Solution config record was last modified (ISO 8601).
virtual_path: str | None =
None
The virtual_path stored on the Solution config, used as the stable dedupe key across owner scopes. null when no virtual path was assigned.
class
SolutionInstallResponse(pydantic.main.BaseModel):
3018class SolutionInstallResponse(BaseModel): 3019 """ 3020 The runtime resource provisioned by installing a Solution, along with a reference back to the source Solution config. 3021 """ 3022 3023 id: str = Field( 3024 ..., 3025 description="Public ID of the provisioned resource. The prefix reflects the resource kind: `agi_...` for Agent, `aut_...` for Automation, `art_...` for AgentRoutine, `att_...` for AgentTool, `ask_...` for AgentSkill, `cmp_...` for AgentComputer.", 3026 ) 3027 kind: str = Field( 3028 ..., 3029 description='Type of the provisioned resource. One of `"Agent"`, `"Automation"`, `"AgentRoutine"`, `"AgentTool"`, `"AgentSkill"`, or `"AgentComputer"`.', 3030 ) 3031 lookup_key: str | None = Field( 3032 default=None, 3033 description="The `lookup_key` stamped on the provisioned resource. `null` for `AgentSkill`, which is a join record and does not carry a lookup key.", 3034 ) 3035 solution: str = Field( 3036 ..., 3037 description="Solution config ID (`cfg_...`) that was used as the source for this install.", 3038 )
The runtime resource provisioned by installing a Solution, along with a reference back to the source Solution config.
id: str =
PydanticUndefined
Public ID of the provisioned resource. The prefix reflects the resource kind: agi_... for Agent, aut_... for Automation, art_... for AgentRoutine, att_... for AgentTool, ask_... for AgentSkill, cmp_... for AgentComputer.
kind: str =
PydanticUndefined
Type of the provisioned resource. One of "Agent", "Automation", "AgentRoutine", "AgentTool", "AgentSkill", or "AgentComputer".
lookup_key: str | None =
None
The lookup_key stamped on the provisioned resource. null for AgentSkill, which is a join record and does not carry a lookup key.
class
SolutionListResponse(pydantic.main.BaseModel):
3041class SolutionListResponse(BaseModel): 3042 """ 3043 A paginated collection of Solution summaries, with page metadata for navigating the result set. 3044 """ 3045 3046 data: list[SolutionSummary] = Field( 3047 ..., 3048 description="Array of Solution summary objects for the current page, in the order returned by the query.", 3049 ) 3050 has_next: bool = Field( 3051 ..., description="`true` when a subsequent page exists; `false` when this is the last page." 3052 ) 3053 has_prev: bool = Field( 3054 ..., description="`true` when a preceding page exists; `false` when this is the first page." 3055 ) 3056 page: int = Field(..., description="1-based index of the current page.") 3057 page_size: int = Field(..., description="Maximum number of results included per page.") 3058 total_entries: int = Field( 3059 ..., 3060 description="Total number of Solutions matching the query after deduplication by `solution_id` across owner scopes.", 3061 ) 3062 total_pages: int = Field( 3063 ..., description="Total number of pages available at the current `page_size`." 3064 )
A paginated collection of Solution summaries, with page metadata for navigating the result set.
has_next: bool =
PydanticUndefined
true when a subsequent page exists; false when this is the last page.
has_prev: bool =
PydanticUndefined
true when a preceding page exists; false when this is the first page.
class
SolutionTagSummary(pydantic.main.BaseModel):
3067class SolutionTagSummary(BaseModel): 3068 """ 3069 A single solution tag definition, representing a named classification label that can be applied to solutions. 3070 """ 3071 3072 created_at: datetime | None = Field( 3073 default=None, 3074 description="When the solution tag was first created (ISO 8601). `null` if unavailable.", 3075 ) 3076 description: str | None = Field( 3077 default=None, 3078 description="Short prose explanation of what the tag represents. `null` if not provided.", 3079 ) 3080 id: str = Field(..., description="Solution tag config ID (`cfg_...`).") 3081 key: str = Field( 3082 ..., 3083 description="Stable string key for this tag, referenced by `Solution.tag_keys` to associate solutions with this tag.", 3084 ) 3085 kind: str = Field(..., description='Object type discriminator. Always `"SolutionTag"`.') 3086 lookup_key: str | None = Field( 3087 default=None, 3088 description="Human-readable stable identifier for this tag config, used for lookups and imports. `null` if not assigned.", 3089 ) 3090 metadata: dict[str, Any] | None = Field( 3091 default=None, 3092 description="Arbitrary key-value metadata attached to this tag. Empty object `{}` when no metadata is present.", 3093 ) 3094 name: str | None = Field( 3095 default=None, description="Human-readable display name for the tag. `null` if not yet set." 3096 ) 3097 org: str | None = Field( 3098 default=None, 3099 description="ID of the organization that owns this tag (`org_...`). `null` for system-scoped tags.", 3100 ) 3101 owners: list[str] = Field( 3102 ..., 3103 description='Scopes under which this tag is visible to the caller. One or both of `"system"` (platform-level tag available to all orgs) and `"org"` (tag scoped to the viewer\'s org).', 3104 ) 3105 sort_order: int | None = Field( 3106 default=None, 3107 description="Optional integer hint for ordering tags in UI lists. Lower values sort first. `null` if not set.", 3108 ) 3109 updated_at: datetime | None = Field( 3110 default=None, 3111 description="When the solution tag was last modified (ISO 8601). `null` if unavailable.", 3112 ) 3113 virtual_path: str | None = Field( 3114 default=None, 3115 description="Hierarchical path used to organize this tag in the config tree. `null` if not assigned.", 3116 )
A single solution tag definition, representing a named classification label that can be applied to solutions.
created_at: datetime.datetime | None =
None
When the solution tag was first created (ISO 8601). null if unavailable.
description: str | None =
None
Short prose explanation of what the tag represents. null if not provided.
key: str =
PydanticUndefined
Stable string key for this tag, referenced by Solution.tag_keys to associate solutions with this tag.
lookup_key: str | None =
None
Human-readable stable identifier for this tag config, used for lookups and imports. null if not assigned.
metadata: dict[str, typing.Any] | None =
None
Arbitrary key-value metadata attached to this tag. Empty object {} when no metadata is present.
org: str | None =
None
ID of the organization that owns this tag (org_...). null for system-scoped tags.
owners: list[str] =
PydanticUndefined
Scopes under which this tag is visible to the caller. One or both of "system" (platform-level tag available to all orgs) and "org" (tag scoped to the viewer's org).
sort_order: int | None =
None
Optional integer hint for ordering tags in UI lists. Lower values sort first. null if not set.
class
SolutionTagListResponse(pydantic.main.BaseModel):
3119class SolutionTagListResponse(BaseModel): 3120 """ 3121 Paginated list of solution tag summaries returned by the list solution tags endpoint. 3122 """ 3123 3124 data: list[SolutionTagSummary] = Field( 3125 ..., description="Array of solution tag objects for the current page." 3126 ) 3127 has_next: bool = Field( 3128 ..., description="`true` if a subsequent page exists; `false` when this is the last page." 3129 ) 3130 has_prev: bool = Field( 3131 ..., description="`true` if a preceding page exists; `false` when this is the first page." 3132 ) 3133 page: int = Field(..., description="Current page number (1-indexed).") 3134 page_size: int = Field(..., description="Maximum number of results returned per page.") 3135 total_entries: int = Field( 3136 ..., 3137 description="Total number of distinct solution tags across all pages, after deduplication by key.", 3138 ) 3139 total_pages: int = Field( 3140 ..., description="Total number of pages available at the current `page_size`." 3141 )
Paginated list of solution tag summaries returned by the list solution tags endpoint.
has_next: bool =
PydanticUndefined
true if a subsequent page exists; false when this is the last page.
has_prev: bool =
PydanticUndefined
true if a preceding page exists; false when this is the first page.
class
SolutionUpgradeResult(pydantic.main.BaseModel):
3144class SolutionUpgradeResult(BaseModel): 3145 """ 3146 The outcome of a solution upgrade operation, including the computed diff and conflict status. 3147 """ 3148 3149 changes: list[SolutionDiffEntry] = Field( 3150 ..., 3151 description="Ordered list of individual config change entries representing every add, update, noop, orphan, and delete in the diff.", 3152 ) 3153 code: str | None = Field( 3154 default=None, 3155 description='Machine-readable conflict code when `status` is `"conflict"`, e.g. `"review_required"`. `null` when there is no conflict.', 3156 ) 3157 dry_run: bool = Field( 3158 ..., 3159 description="`true` when the upgrade was computed without writing any changes; `false` when changes were committed.", 3160 ) 3161 existing_solution_version: str | None = Field( 3162 default=None, 3163 description="Version string of the currently installed solution, as declared in its manifest. `null` if no prior version is installed.", 3164 ) 3165 incoming_solution_version: str | None = Field( 3166 default=None, 3167 description="Version string of the incoming solution to be installed, as declared in its manifest. `null` if the incoming manifest omits a version.", 3168 ) 3169 message: str | None = Field( 3170 default=None, 3171 description="Human-readable description of the conflict or error. `null` when there is no conflict.", 3172 ) 3173 review_fingerprint: str | None = Field( 3174 default=None, 3175 description="Opaque fingerprint that uniquely identifies this diff. Pass this value as `review_fingerprint` on a subsequent non-dry-run upgrade call to confirm you have reviewed the diff. `null` if not applicable.", 3176 ) 3177 status: str = Field( 3178 ..., 3179 description='Overall result of the upgrade. `"ready"` means the upgrade can proceed; `"conflict"` means a blocking issue was detected and the upgrade was not applied.', 3180 ) 3181 summary: SolutionDiffSummary = Field( 3182 ..., description="Aggregate counts of each action type across all diff entries." 3183 ) 3184 version_change: str = Field( 3185 ..., 3186 description='Describes the nature of the version transition. One of `"upgrade"`, `"downgrade"`, `"same"`, or `"unknown"`.', 3187 )
The outcome of a solution upgrade operation, including the computed diff and conflict status.
Ordered list of individual config change entries representing every add, update, noop, orphan, and delete in the diff.
code: str | None =
None
Machine-readable conflict code when status is "conflict", e.g. "review_required". null when there is no conflict.
dry_run: bool =
PydanticUndefined
true when the upgrade was computed without writing any changes; false when changes were committed.
existing_solution_version: str | None =
None
Version string of the currently installed solution, as declared in its manifest. null if no prior version is installed.
incoming_solution_version: str | None =
None
Version string of the incoming solution to be installed, as declared in its manifest. null if the incoming manifest omits a version.
message: str | None =
None
Human-readable description of the conflict or error. null when there is no conflict.
review_fingerprint: str | None =
None
Opaque fingerprint that uniquely identifies this diff. Pass this value as review_fingerprint on a subsequent non-dry-run upgrade call to confirm you have reviewed the diff. null if not applicable.
status: str =
PydanticUndefined
Overall result of the upgrade. "ready" means the upgrade can proceed; "conflict" means a blocking issue was detected and the upgrade was not applied.
class
SolutionUpgradeResponse(pydantic.main.BaseModel):
3190class SolutionUpgradeResponse(BaseModel): 3191 """ 3192 Response returned by the solution upgrade endpoint, containing the solution record, the full upgrade diff, and the resulting installed configs. 3193 """ 3194 3195 created_at: datetime | None = Field( 3196 default=None, 3197 description="When the solution config record was first created (ISO 8601). `null` if unavailable.", 3198 ) 3199 id: str = Field(..., description="Config ID of the solution record (`cfg_...`).") 3200 installed_configs: list[InstalledConfigEntry] | None = Field( 3201 default=None, 3202 description="List of config entries that were installed or updated as part of this upgrade. Empty when `dry_run` is `true` or when no configs changed.", 3203 ) 3204 kind: str = Field(..., description='Object type discriminator. Always `"Solution"`.') 3205 lookup_key: str | None = Field( 3206 default=None, 3207 description="Human-readable stable identifier for this solution config. `null` if not assigned.", 3208 ) 3209 solution: SolutionSummary = Field( 3210 ..., 3211 description="Summary of the solution being upgraded, including its name, manifest metadata, and tag keys.", 3212 ) 3213 updated_at: datetime | None = Field( 3214 default=None, 3215 description="When the solution config record was last modified (ISO 8601). `null` if unavailable.", 3216 ) 3217 upgrade_result: SolutionUpgradeResult = Field( 3218 ..., 3219 description="Detailed result of the upgrade operation, including the computed diff and any conflict information.", 3220 ) 3221 virtual_path: str | None = Field( 3222 default=None, 3223 description="Hierarchical path of the solution in the config tree. `null` if not assigned.", 3224 )
Response returned by the solution upgrade endpoint, containing the solution record, the full upgrade diff, and the resulting installed configs.
created_at: datetime.datetime | None =
None
When the solution config record was first created (ISO 8601). null if unavailable.
List of config entries that were installed or updated as part of this upgrade. Empty when dry_run is true or when no configs changed.
lookup_key: str | None =
None
Human-readable stable identifier for this solution config. null if not assigned.
updated_at: datetime.datetime | None =
None
When the solution config record was last modified (ISO 8601). null if unavailable.