archastro.platform.types.common
1# Copyright (c) 2026 ArchAstro Inc. Licensed under the MIT License. 2# This file is auto-generated by @archastro/sdk-generator. Do not edit. 3# Content hash: 5649ca8f18df 4 5from datetime import datetime 6from typing import Annotated, Any, Literal 7 8from pydantic import BaseModel, ConfigDict, Field 9 10from .automations import AutomationParticipantSlot, AutomationPrefills 11from .config import Config 12from .image import ImageSource 13from .users import User 14 15 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 ) 33 34 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 ) 48 49 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 ) 67 68 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 ) 149 150 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 ) 172 173 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 ) 195 196 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 ) 232 233 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 ) 252 253 254class MessagePolicy(BaseModel): 255 """ 256 Controls visibility and canonical recipient selection for routine-emitted messages. 257 """ 258 259 recipients: list[str] | None = Field( 260 default=None, 261 description="Required and non-empty for private visibility. Sources are additive. Routine owner includes the agent owner and optional user co-owner.", 262 ) 263 visibility: str | None = Field( 264 default=None, description="Message visibility. One of `default` or `private`." 265 ) 266 267 268class LLMConfig(BaseModel): 269 """ 270 LLM invocation settings for a routine or chain step. When present, overrides the agent-level model selection. 271 """ 272 273 model: str | None = Field( 274 default=None, 275 description='Provider-prefixed model identifier for this routine or step, e.g. `"openrouter/anthropic/claude-sonnet-latest"`. When omitted, the agent\'s default model is used.', 276 ) 277 278 279class PresetConfig(BaseModel): 280 """ 281 Configuration for a preset routine handler. Controls the agent's behavior, session persistence, and model selection for a given routine or chain step. 282 """ 283 284 instructions: str | None = Field( 285 default=None, 286 description="Custom task or behavior instructions for the preset (max 10,000 chars).", 287 ) 288 llm: LLMConfig | None = Field( 289 default=None, 290 description="LLM invocation settings (e.g. a `model` override for this routine/step).", 291 ) 292 session_mode: str | None = Field( 293 default=None, 294 description="Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`).", 295 ) 296 session_scope: str | None = Field( 297 default=None, 298 description="When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`.", 299 ) 300 structured_message_template_ids: list[str] | None = Field( 301 default=None, 302 description="IDs of structured message templates that constrain the agent's responses to predefined structured formats.", 303 ) 304 305 306class WorkerStatus(BaseModel): 307 """ 308 Execution state of the background worker processing a routine run. Reflects the current job status and retry progress. 309 """ 310 311 attempt: int = Field( 312 ..., 313 description="Number of times the worker has been attempted so far. `0` means the job has been enqueued but not yet started.", 314 ) 315 max_attempts: int = Field( 316 ..., 317 description='Maximum number of attempts the worker is allowed before the job is marked `"discarded"`.', 318 ) 319 status: str = Field( 320 ..., 321 description='Current execution state of the worker. One of `"queued"`, `"executing"`, `"retrying"`, `"completed"`, `"discarded"`, or `"cancelled"`.', 322 ) 323 324 325class MediaVariant(BaseModel): 326 """ 327 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. 328 """ 329 330 content_type: str | None = Field( 331 default=None, 332 description='MIME type of this variant\'s file (e.g., `"image/jpeg"`, `"video/mp4"`). `null` if the file is not loaded.', 333 ) 334 created_at: datetime | None = Field( 335 default=None, description="When this variant was created (ISO 8601)." 336 ) 337 file: str | None = Field( 338 default=None, 339 description="ID of the underlying storage file that backs this variant (`fil_...`).", 340 ) 341 filename: str | None = Field( 342 default=None, 343 description="Original filename of the uploaded file for this variant. `null` if the file is not loaded.", 344 ) 345 height: int | None = Field( 346 default=None, description="Height of this variant in pixels. `null` if not recorded." 347 ) 348 id: str = Field(..., description="Media variant ID (`mvr_...`).") 349 image_source: ImageSource | None = Field( 350 default=None, 351 description="Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types.", 352 ) 353 updated_at: datetime | None = Field( 354 default=None, description="When this variant was last updated (ISO 8601)." 355 ) 356 url: str | None = Field( 357 default=None, 358 description="Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", 359 ) 360 variant_key: str | None = Field( 361 default=None, 362 description='Identifier for this variant\'s processing tier. Common values include `"original"` (the unmodified upload) and `"thumbnail"` (a resized preview).', 363 ) 364 width: int | None = Field( 365 default=None, description="Width of this variant in pixels. `null` if not recorded." 366 ) 367 368 369class Attachment(BaseModel): 370 """ 371 A rich attachment associated with a message, such as a file, scraped link, artifact, task, media item, or inline action. 372 """ 373 374 content_type: str | None = Field( 375 default=None, 376 description='MIME type of the attached file, e.g. `"image/png"` or `"application/pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 377 ) 378 description: str | None = Field( 379 default=None, 380 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.", 381 ) 382 filename: str | None = Field( 383 default=None, 384 description='Original filename of the attached file, e.g. `"report.pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 385 ) 386 height: int | None = Field( 387 default=None, 388 description="Height in pixels of the media item. Present on `media` type only. `null` otherwise.", 389 ) 390 id: str = Field(..., description="Unique identifier for this attachment within the message.") 391 image_height: int | None = Field( 392 default=None, 393 description="Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 394 ) 395 image_source: ImageSource | None = Field( 396 default=None, 397 description="Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise.", 398 ) 399 image_url: str | None = Field( 400 default=None, 401 description="URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", 402 ) 403 image_width: int | None = Field( 404 default=None, 405 description="Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 406 ) 407 media_type: str | None = Field( 408 default=None, 409 description='The media category, e.g. `"video"` or `"audio"`. Present on `media` type only; omitted otherwise.', 410 ) 411 name: str | None = Field( 412 default=None, 413 description="Display name of the media item. Present on `media` type only. `null` otherwise.", 414 ) 415 object: dict[str, Any] | None = Field( 416 default=None, 417 description="The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", 418 ) 419 title: str | None = Field( 420 default=None, 421 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.", 422 ) 423 type: str = Field( 424 ..., 425 description='The attachment type. One of `"file"`, `"scraped_link"`, `"artifact"`, `"task"`, `"media"`, `"action"`, or `"chart"`. Determines which additional fields are present.', 426 ) 427 url: str | None = Field( 428 default=None, 429 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.", 430 ) 431 variants: list[MediaVariant] | None = Field( 432 default=None, 433 description="Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", 434 ) 435 version: int | None = Field( 436 default=None, 437 description="Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", 438 ) 439 width: int | None = Field( 440 default=None, 441 description="Width in pixels of the media item. Present on `media` type only. `null` otherwise.", 442 ) 443 444 445class AuthTokens(BaseModel): 446 """ 447 Credential bundle returned after a successful authentication exchange. Contains the access token, refresh token, and the authenticated user. 448 """ 449 450 expires_in: int = Field( 451 ..., 452 description="Number of seconds until `token` expires. After this period, use `refresh_token` to obtain a new access token.", 453 ) 454 metadata: dict[str, Any] | None = Field( 455 default=None, 456 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.", 457 ) 458 refresh_token: str = Field( 459 ..., 460 description="Long-lived opaque refresh token. Use this to obtain a new access token when `token` expires.", 461 ) 462 token: str = Field( 463 ..., 464 description="Short-lived JWT access token. Include this value in the `Authorization: Bearer <token>` header for all authenticated API requests.", 465 ) 466 token_type: str = Field(..., description='Token scheme. Always `"Bearer"`.') 467 user: User = Field( 468 ..., 469 description="The user who authenticated. Contains the user's profile and account details.", 470 ) 471 472 473class BugReport(BaseModel): 474 """ 475 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. 476 """ 477 478 app: str | None = Field( 479 default=None, 480 description="App ID (`dap_...`) of the developer app through which the report was submitted.", 481 ) 482 client: str = Field( 483 ..., 484 description='The client application that submitted this report. One of `"agent_network_web"`, `"cli"`, or `"developer_portal"`.', 485 ) 486 client_version: str = Field( 487 ..., 488 description='Version string of the submitting client at the time of submission, e.g. `"1.4.2"`.', 489 ) 490 context: dict[str, Any] | None = Field( 491 default=None, 492 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.", 493 ) 494 created_at: datetime | None = Field( 495 default=None, description="When the bug report was submitted (ISO 8601)." 496 ) 497 description: str = Field( 498 ..., 499 description="Freeform text describing the issue or feedback, as entered by the user. Up to 10,000 characters.", 500 ) 501 id: str = Field(..., description="Bug report ID (`bgr_...`).") 502 org: str | None = Field( 503 default=None, 504 description="Organization ID (`org_...`) scoping this report. `null` when the user's account is not part of an organization.", 505 ) 506 sandbox: str | None = Field( 507 default=None, 508 description="Sandbox ID (`dsb_...`) active at submission time. `null` when the report was not submitted from a sandbox context.", 509 ) 510 team: str | None = Field( 511 default=None, 512 description="Team ID (`tem_...`) of the team the submitting user belonged to at submission time. `null` when the user had no active team.", 513 ) 514 updated_at: datetime | None = Field( 515 default=None, description="When the bug report record was last modified (ISO 8601)." 516 ) 517 518 519class BuiltinTool(BaseModel): 520 """ 521 A single callable tool within a builtin tool catalog entry. Represents one discrete function an agent can invoke. 522 """ 523 524 description: str | None = Field( 525 default=None, 526 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.", 527 ) 528 name: str = Field( 529 ..., 530 description='Machine-readable name of the tool as it is registered with the agent runtime, e.g. `"web_search"` or `"github_create_issue"`.', 531 ) 532 533 534class BuiltinToolCatalogEntry(BaseModel): 535 """ 536 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. 537 """ 538 539 config_schema: dict[str, Any] | None = Field( 540 default=None, 541 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.", 542 ) 543 description: str | None = Field( 544 default=None, 545 description="Short prose description of what this tool category does. Suitable for display in setup UIs. `null` when no description has been defined.", 546 ) 547 instruction: str | None = Field( 548 default=None, 549 description="Additional guidance surfaced to the agent at runtime when this tool category is enabled. `null` when no custom instruction is set.", 550 ) 551 key: str = Field( 552 ..., 553 description='Unique slug identifying this tool category, e.g. `"web_search"` or `"github"`.', 554 ) 555 label: str | None = Field( 556 default=None, 557 description='Human-readable display name for the tool category, e.g. `"Web Search"`. `null` when no label has been assigned.', 558 ) 559 multi_instance_mode: str | None = Field( 560 default=None, 561 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.', 562 ) 563 providers: list[str] | None = Field( 564 default=None, 565 description='List of integration provider slugs that can back this tool category, e.g. `["github", "gitlab"]`. Empty when the tool is provider-agnostic.', 566 ) 567 requires_integration: bool | None = Field( 568 default=None, 569 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.", 570 ) 571 server_tool_type: str | None = Field( 572 default=None, 573 description="Internal type identifier used by the platform server when registering these tools. `null` for client-side-only tool categories.", 574 ) 575 tools: list[BuiltinTool] | None = Field( 576 default=None, 577 description="Array of individual tool definitions included in this category. Each entry describes a single callable tool with its own name and description.", 578 ) 579 580 581class ChannelAck(BaseModel): 582 """ 583 Empty acknowledgement payload returned by channel message handlers that produce no data. The wire envelope is `{"status": "ok", "response": {}}`. 584 """ 585 586 pass 587 588 589class MessageReaction(BaseModel): 590 """ 591 A compact reaction record embedded in a message's `reactions` array, representing a single user's reaction to a message. 592 """ 593 594 payload: dict[str, Any] | None = Field( 595 default=None, 596 description='Type-specific reaction data. For `"emoji_reaction"` reactions, contains an `emoji` key with the Unicode emoji string (e.g., `" "`).', 597 ) 598 type: str = Field( 599 ..., 600 description='Reaction type identifier. Currently always `"emoji_reaction"` for emoji-based reactions.', 601 ) 602 user: str | None = Field( 603 default=None, description="Public ID of the user who added the reaction (`usr_...`)." 604 ) 605 606 607class Message(BaseModel): 608 """ 609 A chat message posted in a thread, including its content, author, attachments, reactions, and optional reply metadata. 610 """ 611 612 acl: Acl | None = Field( 613 default=None, 614 description="Access control list for private messages (grants with `read` action). Only returned to resource owners (and privileged/org-admin viewers) via server-side `field_redactions: [acl: :owner]`; `null` for everyone else.", 615 ) 616 actors: list[Actor] | None = Field( 617 default=None, 618 description="Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry.", 619 ) 620 agent: str | None = Field( 621 default=None, 622 description="ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", 623 ) 624 agent_mode: Literal["cli", "embedded"] | None = Field( 625 default=None, 626 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.", 627 ) 628 attachments: list[Attachment] | None = Field( 629 default=None, 630 description="Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments.", 631 ) 632 branched_thread: str | None = Field( 633 default=None, 634 description="ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", 635 ) 636 content: str | None = Field( 637 default=None, 638 description="Text content of the message. `null` for messages that contain only attachments.", 639 ) 640 created_at: str | None = Field( 641 default=None, description="When the message was posted (ISO 8601)." 642 ) 643 has_replies: bool | None = Field( 644 default=None, 645 description="Whether this message has at least one reply. Only present when explicitly requested or computed by the server.", 646 ) 647 id: str = Field(..., description="Message ID (`msg_...`).") 648 idempotency_key: str | None = Field( 649 default=None, 650 description="Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", 651 ) 652 is_deleted: bool | None = Field( 653 default=None, 654 description="Whether this message is a deletion tombstone. `true` only on the `message_updated` broadcast emitted when a message is deleted: the original content is replaced with a placeholder and the message no longer exists on the server. Always `false` for live messages.", 655 ) 656 legacy_agent: str | None = Field( 657 default=None, 658 description="Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", 659 ) 660 metadata: dict[str, Any] | None = Field( 661 default=None, 662 description="Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set.", 663 ) 664 org: str | None = Field( 665 default=None, description="ID of the organization that owns this message (`org_...`)." 666 ) 667 reactions: list[MessageReaction] | None = Field( 668 default=None, 669 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.", 670 ) 671 rendering_mode: str | None = Field( 672 default=None, 673 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.', 674 ) 675 replies: list[dict[str, Any]] | None = Field( 676 default=None, 677 description="Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message.", 678 ) 679 replies_after_cursor: str | None = Field( 680 default=None, 681 description="Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", 682 ) 683 replies_before_cursor: str | None = Field( 684 default=None, 685 description="Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", 686 ) 687 reply_count: int | None = Field( 688 default=None, 689 description="Total number of direct replies to this message. Only present when explicitly requested or computed by the server.", 690 ) 691 reply_to: dict[str, Any] | None = Field( 692 default=None, 693 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.", 694 ) 695 root_message_id: str | None = Field( 696 default=None, 697 description="ID of the root message in this reply chain (`msg_...`). `null` for a top-level message. The value is persisted when the reply is created, so callers can correlate a multi-turn session without walking parent messages.", 698 ) 699 sandbox: str | None = Field( 700 default=None, 701 description="ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", 702 ) 703 team: str | None = Field( 704 default=None, 705 description="ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", 706 ) 707 thread: str | None = Field( 708 default=None, description="ID of the thread this message belongs to (`thr_...`)." 709 ) 710 type: str | None = Field( 711 default=None, 712 description="Optional client-defined classification for the message (for example `note` or `status`). Free-form string up to 64 characters. The value `system` is reserved for platform-authored messages and cannot be set by clients. `null` when unset.", 713 ) 714 user: str | dict[str, Any] | None = Field( 715 default=None, 716 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.", 717 ) 718 visibility: Literal["default", "private"] | None = Field( 719 default=None, 720 description="Message-level visibility. `default` is visible to anyone who can see the parent thread. `private` is restricted to the sender and explicit ACL `read` grantees.", 721 ) 722 723 724class ComputerExecResult(BaseModel): 725 """ 726 The result of executing a shell command on an agent's computer environment. Contains the captured output and the process exit code. 727 """ 728 729 exit_code: int | None = Field( 730 default=None, 731 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.", 732 ) 733 output: str | None = Field( 734 default=None, 735 description="The combined stdout and stderr output produced by the command. `null` if the command produced no output.", 736 ) 737 738 739class ContextDocument(BaseModel): 740 """ 741 A context document stored within a context source. Carries metadata and size information only; retrieve the full text content via the `/content` endpoint. 742 """ 743 744 agent: str | None = Field( 745 default=None, 746 description="ID of the agent that owns this document (`agi_...`). `null` if owned by a user or team.", 747 ) 748 content_hash: str | None = Field( 749 default=None, 750 description="Lowercase-hex sha256 of the document's full text, covering content only not `title` or `metadata`. Compare it against a hash of your local copy to decide whether the document needs re-ingesting, without fetching `/content`. `null` for documents ingested before this field existed; it is not backfilled.", 751 ) 752 created_at: datetime | None = Field( 753 default=None, description="When the document was created (ISO 8601)." 754 ) 755 file: str | None = Field( 756 default=None, 757 description="ID of the backing storage file (`fil_...`) when the document is file-backed. `null` for inline documents.", 758 ) 759 id: str = Field(..., description="Context document ID (`cdo_...`).") 760 metadata: dict[str, Any] | None = Field( 761 default=None, 762 description="Arbitrary key-value metadata attached to the document. Shape varies by source type.", 763 ) 764 source: str | None = Field( 765 default=None, description="ID of the context source this document belongs to (`cso_...`)." 766 ) 767 team: str | None = Field( 768 default=None, 769 description="ID of the team that owns this document (`tem_...`). `null` if owned by a user or agent.", 770 ) 771 title: str | None = Field( 772 default=None, 773 description="Human-readable display title of the document. `null` if no title has been set.", 774 ) 775 total_lines: int | None = Field( 776 default=None, 777 description="Total number of lines in the document's text content. `0` if the document has no content.", 778 ) 779 total_size: int | None = Field( 780 default=None, 781 description="Total byte size of the document's text content. `0` if the document has no content.", 782 ) 783 updated_at: datetime | None = Field( 784 default=None, description="When the document was last modified (ISO 8601)." 785 ) 786 user: str | None = Field( 787 default=None, 788 description="ID of the user that owns this document (`usr_...`). `null` if owned by a team or agent.", 789 ) 790 791 792class ContextDocumentContent(BaseModel): 793 """ 794 The text content of a context document, optionally sliced by line or byte range. Includes totals and slice boundary fields for the requested unit. 795 """ 796 797 content: str = Field( 798 ..., 799 description="Text of the document. Contains the full content when no `offset`/`limit` was requested, or only the requested slice otherwise.", 800 ) 801 end_byte: int | None = Field( 802 default=None, 803 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.', 804 ) 805 end_line: int | None = Field( 806 default=None, 807 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.', 808 ) 809 id: str = Field(..., description="Context document ID (`cdo_...`).") 810 limit: int | None = Field( 811 default=None, 812 description="The `limit` value echoed from the request. `null` when no limit was requested.", 813 ) 814 metadata: dict[str, Any] | None = Field( 815 default=None, 816 description="Arbitrary key-value metadata attached to the document, such as source URL or author. `null` if no metadata was recorded.", 817 ) 818 offset: int | None = Field( 819 default=None, 820 description="The `offset` value echoed from the request. `null` when no offset was requested.", 821 ) 822 start_byte: int | None = Field( 823 default=None, 824 description='Zero-based index of the first byte included in `content`. Populated only when `unit` is `"bytes"`; `null` otherwise.', 825 ) 826 start_line: int | None = Field( 827 default=None, 828 description='1-indexed line number of the first line included in `content`. Populated only when `unit` is `"lines"`; `null` otherwise.', 829 ) 830 title: str | None = Field( 831 default=None, 832 description="Human-readable display title of the document. `null` if the document has no title set.", 833 ) 834 total_lines: int = Field( 835 ..., 836 description="Total number of lines in the document's full content, regardless of any slice.", 837 ) 838 total_size: int = Field( 839 ..., description="Total byte size of the document's full content, regardless of any slice." 840 ) 841 unit: str | None = Field( 842 default=None, 843 description='Slice unit used when `offset` and `limit` were provided. One of `"lines"` (default) or `"bytes"`. `null` when no slice was requested.', 844 ) 845 846 847class ContextIngestion(BaseModel): 848 """ 849 A context ingestion job that processes a context source and populates its documents. Tracks status and timing from submission through completion or failure. 850 """ 851 852 agent: str | None = Field( 853 default=None, 854 description="ID of the agent that initiated this ingestion (`agi_...`). `null` if initiated by a user.", 855 ) 856 completed_at: datetime | None = Field( 857 default=None, 858 description="When the ingestion job finished, either successfully or with a failure. `null` if still in progress.", 859 ) 860 created_at: datetime | None = Field( 861 default=None, description="When the ingestion was submitted (ISO 8601)." 862 ) 863 error: dict[str, Any] | None = Field( 864 default=None, 865 description='Structured error details when the ingestion has `status: "failed"`. `null` for any other status.', 866 ) 867 id: str = Field(..., description="Context ingestion ID (`cig_...`).") 868 metadata: dict[str, Any] | None = Field( 869 default=None, 870 description="Arbitrary key-value metadata associated with this ingestion run. Shape is caller-defined.", 871 ) 872 source: str | None = Field( 873 default=None, 874 description="ID of the context source being ingested (`cso_...`). `null` if the source has been deleted.", 875 ) 876 started_at: datetime | None = Field( 877 default=None, 878 description="When the ingestion job began processing. `null` if the job is still pending.", 879 ) 880 status: str = Field( 881 ..., 882 description='Current processing status. One of `"pending"`, `"running"`, `"awaiting_callback"`, `"succeeded"`, or `"failed"`.', 883 ) 884 team: str | None = Field( 885 default=None, 886 description="ID of the team that owns this ingestion (`tem_...`). `null` if owned by a user or agent.", 887 ) 888 updated_at: datetime | None = Field( 889 default=None, description="When the ingestion record was last updated (ISO 8601)." 890 ) 891 user: str | None = Field( 892 default=None, 893 description="ID of the user that initiated this ingestion (`usr_...`). `null` if initiated by an agent.", 894 ) 895 896 897class CreatedPrivateServiceEnrollment(BaseModel): 898 """ 899 Creation-only private service enrollment response. The raw token is shown 900 once and is omitted from every read schema. 901 """ 902 903 enrollment_token: str = Field( 904 ..., description="One-time connector enrollment token. Store it immediately." 905 ) 906 enrollment_token_expires_at: datetime = Field( 907 ..., description="When the one-time enrollment token expires." 908 ) 909 generation: int 910 id: str 911 private_service: str 912 913 914class CustomObject(BaseModel): 915 """ 916 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. 917 """ 918 919 acl: Acl | None = Field( 920 default=None, 921 description="Access control list governing read and write access to this custom object. Only returned to resource owners and privileged or organization-admin viewers; `null` for everyone else.", 922 ) 923 created_at: datetime | None = Field( 924 default=None, description="When the custom object was created (ISO 8601)." 925 ) 926 fields: dict[str, Any] | None = Field( 927 default=None, 928 description="Map of field names to their current values as defined by the object's schema type.", 929 ) 930 id: str = Field(..., description="Unique identifier for the custom object (`cobj_...`).") 931 org: str | None = Field( 932 default=None, description="ID of the organization this object belongs to (`org_...`)." 933 ) 934 row_key: str | None = Field( 935 default=None, 936 description="An optional stable key used to identify this object by a caller-controlled string rather than its generated ID. `null` if not set.", 937 ) 938 sandbox: str | None = Field( 939 default=None, 940 description="ID of the sandbox environment this object is scoped to (`dsb_...`). `null` for production objects.", 941 ) 942 schema_type: str | None = Field( 943 default=None, 944 description="The lookup key of the schema type that defines this object's field structure. `null` if the schema type has not been set.", 945 ) 946 team: str | None = Field( 947 default=None, 948 description="ID of the team that owns this object (`tem_...`). `null` if the object is not team-scoped.", 949 ) 950 updated_at: datetime | None = Field( 951 default=None, 952 description="When the custom object was last modified (ISO 8601). `null` if the object has never been updated after creation.", 953 ) 954 user: str | None = Field( 955 default=None, 956 description="ID of the user that owns this object (`usr_...`). `null` if the object is not user-scoped.", 957 ) 958 version: int | None = Field( 959 default=None, 960 description="Optimistic concurrency version of the object. Increments with each successful update; pass this value in write operations to detect conflicting changes.", 961 ) 962 963 964class CustomObjectJoinResponse(BaseModel): 965 """ 966 Initial authoritative snapshot returned by a custom-object channel join. 967 """ 968 969 connection_id: str = Field( 970 ..., description="Collision-free identifier for this browser connection." 971 ) 972 fields: dict[str, Any] | None = Field( 973 ..., description="Current materialized fields, or `null` while waiting for object creation." 974 ) 975 id: str | None = Field( 976 ..., 977 description="Custom-object ID, or `null` while a row-key subscription waits for creation.", 978 ) 979 presence: list[dict[str, Any]] = Field( 980 ..., description="Current ephemeral collaborator presence." 981 ) 982 readonly: bool = Field( 983 ..., description="Whether the current connection may only read the object." 984 ) 985 986 987class CustomObjectListResponse(BaseModel): 988 """ 989 A paginated page of custom objects returned by a list operation. Use the pagination fields to navigate through result sets. 990 """ 991 992 data: list[CustomObject] = Field( 993 ..., description="Array of custom objects for the current page." 994 ) 995 has_next: bool = Field( 996 ..., 997 description="`true` if a subsequent page of results exists; `false` if this is the last page.", 998 ) 999 has_prev: bool = Field( 1000 ..., 1001 description="`true` if a preceding page of results exists; `false` if this is the first page.", 1002 ) 1003 page: int = Field(..., description="The current page number (1-indexed).") 1004 page_size: int = Field(..., description="Maximum number of results returned per page.") 1005 total_entries: int = Field( 1006 ..., description="Total number of custom objects matching the query across all pages." 1007 ) 1008 total_pages: int = Field( 1009 ..., description="Total number of pages available for the current query." 1010 ) 1011 1012 1013class CustomObjectPresenceAck(BaseModel): 1014 """ 1015 Acknowledges an ephemeral custom-object presence update. 1016 """ 1017 1018 connection_id: str = Field( 1019 ..., description="Collision-free connection identifier assigned to this browser connection." 1020 ) 1021 1022 1023class CustomObjectSaveResponse(BaseModel): 1024 """ 1025 Acknowledges that the current custom-object document reached durable storage. 1026 """ 1027 1028 version: int = Field(..., description="Durable optimistic-concurrency version after the save.") 1029 1030 1031class CustomObjectUpdateFieldsResponse(BaseModel): 1032 """ 1033 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. 1034 """ 1035 1036 fields: dict[str, Any] = Field( 1037 ..., description="The materialized object fields after the update." 1038 ) 1039 id: str = Field(..., description="ID of the custom object that was updated (`cobj_...`).") 1040 operation_id: str = Field(..., description="Idempotency key acknowledged for this update.") 1041 1042 1043class Deployment(BaseModel): 1044 """ 1045 Deployment metadata. 1046 """ 1047 1048 environment: str | None = Field( 1049 default=None, description="Deployment environment, or `null` when it is not configured." 1050 ) 1051 release: str | None = Field( 1052 default=None, 1053 description="Opaque SHA-256 fingerprint of the image reference, or `null` in local development.", 1054 ) 1055 1056 1057class DomainEvent(BaseModel): 1058 """ 1059 A domain event with stable attribution fields and an event-specific payload. 1060 """ 1061 1062 agent: str | None = None 1063 created_at: datetime 1064 event_name: str 1065 id: str 1066 idempotency_key: str | None = None 1067 org: str | None = None 1068 payload: dict[str, Any] = Field( 1069 ..., 1070 description="Opaque event-specific JSON. Use event_name to select the expected payload schema.", 1071 ) 1072 sandbox: str | None = None 1073 team: str | None = None 1074 user: str | None = None 1075 1076 1077class EventSubscription(BaseModel): 1078 """ 1079 An app-scoped subscription to exact domain-event names. 1080 """ 1081 1082 agent: str | None = None 1083 available_count: int 1084 created_at: datetime 1085 dropped_events_total: int 1086 dropped_through_position: int 1087 event_names: list[str] 1088 id: str 1089 last_overflow_at: datetime | None = None 1090 leased_count: int 1091 max_pending_events: int 1092 name: str 1093 org: str | None = None 1094 queue_epoch: int 1095 retention_seconds: int 1096 sandbox: str | None = None 1097 status: Literal["active", "paused"] 1098 team: str | None = None 1099 updated_at: datetime 1100 user: str | None = None 1101 visibility_timeout_seconds: int 1102 1103 1104class EventSubscriptionDelivery(BaseModel): 1105 """ 1106 A domain event leased from a subscription queue. 1107 """ 1108 1109 delivery_id: str 1110 event: DomainEvent 1111 lease_expires_at: datetime 1112 receipt_handle: str 1113 receive_count: int 1114 sequence: int 1115 1116 1117class EventSubscriptionClaim(BaseModel): 1118 """ 1119 Result of atomically claiming the head delivery. 1120 """ 1121 1122 data: list[EventSubscriptionDelivery] 1123 dropped_events_total: int 1124 dropped_through_position: int 1125 has_more: bool 1126 queue_epoch: int 1127 1128 1129class EventSubscriptionQueueEntry(BaseModel): 1130 """ 1131 A non-reserving view of one queued delivery. 1132 """ 1133 1134 delivery_id: str 1135 event: DomainEvent 1136 lease_expires_at: datetime | None = None 1137 receive_count: int 1138 sequence: int 1139 state: Literal["available", "leased"] 1140 1141 1142class EventSubscriptionHead(BaseModel): 1143 """ 1144 A non-reserving view of the queue head. 1145 """ 1146 1147 data: EventSubscriptionQueueEntry | None = None 1148 1149 1150class EventSubscriptionPage(BaseModel): 1151 """ 1152 A page of domain-event subscriptions. 1153 """ 1154 1155 data: list[EventSubscription] 1156 page: int 1157 per_page: int 1158 total_count: int 1159 total_pages: int 1160 1161 1162class EventSubscriptionQueue(BaseModel): 1163 """ 1164 A cursor-paginated non-reserving view of a subscription queue. 1165 """ 1166 1167 after_cursor: str | None = None 1168 before_cursor: str | None = None 1169 data: list[EventSubscriptionQueueEntry] 1170 dropped_events_total: int 1171 dropped_through_position: int 1172 has_more: bool 1173 queue_epoch: int 1174 1175 1176class StorageFile(BaseModel): 1177 """ 1178 A file stored in the platform's object storage, with metadata and a signed URL for downloading its contents. 1179 """ 1180 1181 app: str | None = Field( 1182 default=None, description="ID of the app this file belongs to (`app_...`)." 1183 ) 1184 content_type: str | None = Field( 1185 default=None, 1186 description='MIME type of the file, e.g. `"image/png"` or `"application/pdf"`.', 1187 ) 1188 created_at: datetime | None = Field( 1189 default=None, description="When the file was uploaded (ISO 8601)." 1190 ) 1191 filename: str | None = Field( 1192 default=None, description="Original filename as provided at upload time." 1193 ) 1194 id: str = Field(..., description="File ID (`fil_...`).") 1195 image_source: ImageSource | None = Field( 1196 default=None, 1197 description="Image display metadata. Present only when `content_type` is an image type; `null` otherwise.", 1198 ) 1199 org: str | None = Field( 1200 default=None, description="ID of the organization that owns this file (`org_...`)." 1201 ) 1202 sandbox: str | None = Field( 1203 default=None, 1204 description="ID of the sandbox this file is scoped to (`sbx_...`). `null` for files not associated with a sandbox.", 1205 ) 1206 share_url: str | None = Field( 1207 default=None, 1208 description="Stable public URL for the file, fetchable without authentication. Present only when the file was shared (`share: true`); does not expire until sharing is disabled. Disabling and re-enabling sharing reactivates the same URL. `null` otherwise.", 1209 ) 1210 size: int | None = Field(default=None, description="Size of the file in bytes.") 1211 team: str | None = Field( 1212 default=None, 1213 description="ID of the team that owns this file (`team_...`). `null` if not team-owned.", 1214 ) 1215 updated_at: datetime | None = Field( 1216 default=None, description="When the file record was last modified (ISO 8601)." 1217 ) 1218 url: str | None = Field( 1219 default=None, 1220 description="Short-lived signed URL for downloading the file. `null` if a URL could not be generated.", 1221 ) 1222 user: str | None = Field( 1223 default=None, 1224 description="ID of the user that owns this file (`user_...`). `null` if not user-owned.", 1225 ) 1226 1227 1228class AgentHealthAction(BaseModel): 1229 """ 1230 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. 1231 """ 1232 1233 agent: str | None = Field( 1234 default=None, 1235 description="ID of the agent this action is scoped to (`agt_...`). `null` for org-level actions.", 1236 ) 1237 app: str | None = Field( 1238 default=None, 1239 description="ID of the application this action is associated with (`app_...`). `null` when not app-scoped.", 1240 ) 1241 created_at: datetime | None = Field( 1242 default=None, description="When this health action was first created (ISO 8601)." 1243 ) 1244 depends_on: list[str] | None = Field( 1245 default=None, 1246 description='IDs of other health actions that must reach `"completed"` status before this action can be started. Empty array when there are no dependencies.', 1247 ) 1248 description: str | None = Field( 1249 default=None, 1250 description="Longer Markdown-formatted explanation of what the action requires and why. `null` if not provided.", 1251 ) 1252 id: str = Field(..., description="Health action ID (`aha_...`).") 1253 kind: str = Field( 1254 ..., 1255 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).', 1256 ) 1257 last_verified_at: datetime | None = Field( 1258 default=None, 1259 description="When the verifier last ran for this action (ISO 8601). `null` until the verifier has been invoked at least once.", 1260 ) 1261 last_verifier_message: str | None = Field( 1262 default=None, 1263 description="Human-readable output from the most recent verifier run. `null` if the verifier has not run yet.", 1264 ) 1265 org: str | None = Field( 1266 default=None, 1267 description="ID of the organization this action is associated with (`org_...`). `null` when not org-scoped.", 1268 ) 1269 params: dict[str, Any] | None = Field( 1270 default=None, 1271 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.', 1272 ) 1273 required: bool = Field( 1274 ..., 1275 description="`true` if this action must be completed before the agent is considered fully operational and counts toward the blocking checklist progress bar.", 1276 ) 1277 sort_order: int = Field( 1278 ..., description="Display order within the same `source` group. Lower values appear first." 1279 ) 1280 source: str = Field( 1281 ..., 1282 description='Lifecycle stage that produced this action. One of `"setup"` (post-install checklist item) or `"health"` (probe-detected issue).', 1283 ) 1284 status: str = Field( 1285 ..., 1286 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).', 1287 ) 1288 title: str = Field( 1289 ..., 1290 description="Short display label for this action, intended for use as a checklist item heading.", 1291 ) 1292 updated_at: datetime | None = Field( 1293 default=None, description="When this health action was last modified (ISO 8601)." 1294 ) 1295 verify_config: dict[str, Any] | None = Field( 1296 default=None, 1297 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.", 1298 ) 1299 1300 1301class HealthActionListResponse(BaseModel): 1302 """ 1303 List response containing agent health actions for a given agent or organization. 1304 """ 1305 1306 data: list[AgentHealthAction] = Field( 1307 ..., 1308 description="Array of agent health action objects representing setup checklist items and probe-detected issues.", 1309 ) 1310 1311 1312class Installation(BaseModel): 1313 """ 1314 An installation representing a connection between an agent and an external service or enablement channel. Tracks configuration, lifecycle state, and any bound integration. 1315 """ 1316 1317 agent: str | None = Field( 1318 default=None, 1319 description="ID of the agent that owns this installation (`agi_...`). `null` if the installation has no agent owner.", 1320 ) 1321 config: dict[str, Any] | None = Field( 1322 default=None, 1323 description="Kind-specific configuration object for this installation. Shape depends on the `kind` value. `null` if the kind requires no configuration.", 1324 ) 1325 created_at: datetime | None = Field( 1326 default=None, description="When the installation was created (ISO 8601)." 1327 ) 1328 id: str = Field(..., description="Installation ID (`cin_...`).") 1329 kind: str | None = Field( 1330 default=None, 1331 description='Slug identifying the type of external service this installation connects to, e.g. `"enablement/github_app"` or `"integration/gmail"`. `null` if not set.', 1332 ) 1333 lookup_key: str | None = Field( 1334 default=None, 1335 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.", 1336 ) 1337 shared_integration: str | None = Field( 1338 default=None, 1339 description="ID of the shared org- or app-level integration bound to this installation (`int_...`). `null` if no integration has been bound.", 1340 ) 1341 state: str | None = Field( 1342 default=None, 1343 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.', 1344 ) 1345 status_payload: dict[str, Any] | None = Field( 1346 default=None, 1347 description="Provider-supplied status detail for this installation, set during activation or event processing. `null` if no status has been reported.", 1348 ) 1349 updated_at: datetime | None = Field( 1350 default=None, description="When the installation record was last updated (ISO 8601)." 1351 ) 1352 1353 1354class InstallationKind(BaseModel): 1355 """ 1356 A supported installation kind describing a category of external service or enablement channel an agent can be connected to. 1357 """ 1358 1359 accepts_sources: bool | None = Field( 1360 default=None, 1361 description="When `true`, sources can be attached to installations of this kind to supply additional context to the agent.", 1362 ) 1363 category: str | None = Field( 1364 default=None, 1365 description='Grouping category for UI display purposes, e.g. `"enablement"` or `"integration"`. `null` if uncategorized.', 1366 ) 1367 config_schema: dict[str, Any] | None = Field( 1368 default=None, 1369 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.", 1370 ) 1371 description: str | None = Field( 1372 default=None, 1373 description="Short prose description of what this kind connects to and how it is used. `null` if no description is defined.", 1374 ) 1375 kind: str = Field( 1376 ..., 1377 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.', 1378 ) 1379 label: str | None = Field( 1380 default=None, 1381 description='Human-readable display name for this kind, e.g. `"GitHub App"`. `null` if the kind has no label defined.', 1382 ) 1383 provider: str | None = Field( 1384 default=None, 1385 description='Identifier of the external provider this kind connects to, e.g. `"github"` or `"slack"`. `null` for kinds with no specific provider.', 1386 ) 1387 requires_integration: bool | None = Field( 1388 default=None, 1389 description="When `true`, this kind requires an integration to be provided (either inline or via `shared_integration`) before the installation can be activated.", 1390 ) 1391 1392 1393class InstallationKindListResponse(BaseModel): 1394 """ 1395 List response containing the publicly available installation kinds that can be used when configuring an agent installation. 1396 """ 1397 1398 data: list[InstallationKind] = Field( 1399 ..., 1400 description="Array of installation kind objects describing the available integration types and their configuration requirements.", 1401 ) 1402 1403 1404class InstallationListResponse(BaseModel): 1405 """ 1406 Paginated list response containing installation objects for an agent. 1407 """ 1408 1409 data: list[Installation] = Field( 1410 ..., description="Array of installation objects returned for the current page." 1411 ) 1412 1413 1414class InstallationSource(BaseModel): 1415 """ 1416 A source attached to an installation that supplies content for the agent's context. Sources are processed asynchronously after creation. 1417 """ 1418 1419 agent: str | None = Field( 1420 default=None, 1421 description="ID of the agent that owns this source (`agi_...`). `null` if the source is not agent-owned.", 1422 ) 1423 context_installation: str | None = Field( 1424 default=None, 1425 description="ID of the installation this source belongs to (`cin_...`). `null` if the source is not attached to an installation.", 1426 ) 1427 created_at: datetime | None = Field( 1428 default=None, description="When the source was created (ISO 8601)." 1429 ) 1430 id: str = Field(..., description="Source ID (`cso_...`).") 1431 metadata: dict[str, Any] | None = Field( 1432 default=None, 1433 description="Arbitrary key-value metadata associated with this source. Shape is caller-defined. `null` if no metadata was set.", 1434 ) 1435 parent_source: str | None = Field( 1436 default=None, 1437 description="ID of the parent source (`cso_...`) when this source was derived from another source. `null` for top-level sources.", 1438 ) 1439 payload: dict[str, Any] | None = Field( 1440 default=None, 1441 description="Type-specific payload provided when the source was created. The shape depends on the `type` value. `null` if no payload was supplied.", 1442 ) 1443 state: str | None = Field( 1444 default=None, 1445 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.', 1446 ) 1447 team: str | None = Field( 1448 default=None, 1449 description="ID of the team associated with this source (`tem_...`). `null` if the source has no team association.", 1450 ) 1451 thread: str | None = Field( 1452 default=None, 1453 description="ID of the conversation thread linked to this source (`thr_...`). `null` if the source is not thread-scoped.", 1454 ) 1455 type: str | None = Field( 1456 default=None, 1457 description='Slug identifying the kind of content this source provides, e.g. `"file/document"` or `"web/link"`. `null` if the type is not set.', 1458 ) 1459 updated_at: datetime | None = Field( 1460 default=None, description="When the source record was last updated (ISO 8601)." 1461 ) 1462 user: str | None = Field( 1463 default=None, 1464 description="ID of the user associated with this source (`usr_...`). `null` if the source has no user association.", 1465 ) 1466 1467 1468class InstallationSourceListResponse(BaseModel): 1469 """ 1470 Paginated list response containing installation source objects attached to an installation. 1471 """ 1472 1473 data: list[InstallationSource] = Field( 1474 ..., description="Array of installation source objects returned for the current page." 1475 ) 1476 1477 1478class KeyValueStorageEntry(BaseModel): 1479 """ 1480 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. 1481 """ 1482 1483 created_at: datetime | None = Field( 1484 default=None, 1485 description="When this storage entry was first created (ISO 8601). `null` if not yet persisted.", 1486 ) 1487 key: str = Field(..., description="The string key used to store and look up this entry.") 1488 updated_at: datetime | None = Field( 1489 default=None, 1490 description="When this storage entry was last updated (ISO 8601). `null` if not yet persisted.", 1491 ) 1492 user: str = Field(..., description="ID of the user who owns this storage entry (`usr_...`).") 1493 value: str = Field(..., description="The string value stored under `key` for this user.") 1494 1495 1496class KeyValueStorageEntryWithUser(BaseModel): 1497 """ 1498 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`. 1499 """ 1500 1501 created_at: datetime = Field( 1502 ..., description="When this storage entry was first created (ISO 8601)." 1503 ) 1504 key: str = Field(..., description="The string key used to store and look up this entry.") 1505 updated_at: datetime = Field( 1506 ..., description="When this storage entry was last updated (ISO 8601)." 1507 ) 1508 user: str = Field(..., description="ID of the user who owns this storage entry (`usr_...`).") 1509 user_email: str | None = Field( 1510 default=None, 1511 description="Email address of the owning user. `null` for end-user (user-JWT) callers; populated for developer and server-to-server callers.", 1512 ) 1513 user_name: str | None = Field( 1514 default=None, 1515 description="Display name of the owning user. `null` for end-user (user-JWT) callers; populated for developer and server-to-server callers.", 1516 ) 1517 value: str = Field(..., description="The string value stored under `key` for this user.") 1518 1519 1520class KeyValueStorageEntryPage(BaseModel): 1521 """ 1522 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. 1523 """ 1524 1525 data: list[KeyValueStorageEntryWithUser] = Field( 1526 ..., description="Array of key-value storage entries for the current page." 1527 ) 1528 has_next: bool | None = Field( 1529 default=None, 1530 description="Whether a subsequent page exists. `false` when the current page is the last page. Present only for developer and server-to-server callers.", 1531 ) 1532 has_prev: bool | None = Field( 1533 default=None, 1534 description="Whether a preceding page exists. `false` when the current page is the first page. Present only for developer and server-to-server callers.", 1535 ) 1536 page: int | None = Field( 1537 default=None, 1538 description="Current page number (1-indexed). Present only for developer and server-to-server callers.", 1539 ) 1540 page_size: int | None = Field( 1541 default=None, 1542 description="Maximum number of results returned per page. Present only for developer and server-to-server callers.", 1543 ) 1544 total_entries: int | None = Field( 1545 default=None, 1546 description="Total number of storage entries matching the applied filters across all pages. Present only for developer and server-to-server callers.", 1547 ) 1548 total_pages: int | None = Field( 1549 default=None, 1550 description="Total number of pages available given the current `page_size`. Present only for developer and server-to-server callers.", 1551 ) 1552 1553 1554class KnowledgeSource(BaseModel): 1555 """ 1556 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. 1557 """ 1558 1559 agent: str | None = Field( 1560 default=None, 1561 description="ID of the agent that owns this source (`agt_...`). `null` if owned by a human user or team.", 1562 ) 1563 context_installation: str | None = Field( 1564 default=None, 1565 description="ID of the context installation that provisioned this source (`cin_...`). `null` when the source was created directly rather than through an installation.", 1566 ) 1567 created_at: datetime | None = Field( 1568 default=None, description="When this knowledge source was created (ISO 8601)." 1569 ) 1570 id: str = Field(..., description="Knowledge source ID (`cso_...`).") 1571 metadata: dict[str, Any] | None = Field( 1572 default=None, 1573 description="Arbitrary key-value metadata attached to this source. Useful for storing caller-defined labels or references.", 1574 ) 1575 org: str | None = Field( 1576 default=None, 1577 description="ID of the organization this source belongs to (`org_...`). `null` if not scoped to an org.", 1578 ) 1579 parent_source: str | None = Field( 1580 default=None, 1581 description="ID of the parent knowledge source (`cso_...`) when this source was derived from another. `null` for top-level sources.", 1582 ) 1583 payload: dict[str, Any] | None = Field( 1584 default=None, 1585 description="Type-specific configuration object. The keys depend on the source `type`; see the create endpoint for the expected shape per type.", 1586 ) 1587 sandbox: str | None = Field( 1588 default=None, 1589 description="ID of the developer sandbox this source is scoped to (`sbx_...`). `null` outside sandbox contexts.", 1590 ) 1591 state: str = Field( 1592 ..., 1593 description='Current lifecycle state of the source. One of `"active"` (ingestion running normally) or `"paused"` (ingestion suspended).', 1594 ) 1595 team: str | None = Field( 1596 default=None, 1597 description="ID of the team that owns this source (`tea_...`). `null` if owned by a user, agent, or org.", 1598 ) 1599 thread: str | None = Field( 1600 default=None, 1601 description="ID of the chat thread this source is associated with (`thr_...`). `null` when not thread-scoped.", 1602 ) 1603 type: str = Field( 1604 ..., 1605 description='Source type identifier (e.g. `"gmail"`, `"github_activity"`). Determines the shape of `payload` and the ingestion behavior.', 1606 ) 1607 updated_at: datetime | None = Field( 1608 default=None, description="When this knowledge source was last modified (ISO 8601)." 1609 ) 1610 user: str | None = Field( 1611 default=None, 1612 description="ID of the user that owns this source (`usr_...`). `null` if owned by a team, agent, or org.", 1613 ) 1614 1615 1616class KnowledgeSourceKind(BaseModel): 1617 """ 1618 Describes a single knowledge source kind that can be created through the public API. Use the `type` value when creating a new knowledge source. 1619 """ 1620 1621 description: str | None = Field( 1622 default=None, 1623 description="Short description of what this source kind ingests and how it is used.", 1624 ) 1625 label: str | None = Field( 1626 default=None, 1627 description="Human-readable display name for this source kind, suitable for showing in a UI.", 1628 ) 1629 type: str = Field( 1630 ..., 1631 description='Machine-readable type identifier for this source kind (e.g. `"gmail"`, `"github_activity"`). Pass this value as `type` when creating a knowledge source.', 1632 ) 1633 1634 1635class KnowledgeSourceKindListResponse(BaseModel): 1636 """ 1637 List response containing the knowledge source kinds available for creation via the API. 1638 """ 1639 1640 data: list[KnowledgeSourceKind] = Field( 1641 ..., 1642 description="Array of knowledge source kind objects describing each creatable source type.", 1643 ) 1644 1645 1646class PaginatedReplies(BaseModel): 1647 """ 1648 A paginated list of reply messages for a thread. The reply array is returned directly, not nested inside a `data` wrapper. 1649 """ 1650 1651 after_cursor: str | None = Field( 1652 default=None, 1653 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.", 1654 ) 1655 before_cursor: str | None = Field( 1656 default=None, 1657 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.", 1658 ) 1659 has_more: bool | None = Field( 1660 default=None, description="Whether additional reply pages exist beyond the current page." 1661 ) 1662 replies: list[Message] = Field( 1663 ..., description="Array of reply message objects for the current page." 1664 ) 1665 total_count: int | None = Field( 1666 default=None, description="Total number of replies in the thread across all pages." 1667 ) 1668 1669 1670class PrivateServiceFunction(BaseModel): 1671 """ 1672 A documented callable operation exposed by a private service. 1673 """ 1674 1675 description: str = Field( 1676 ..., description="Human-readable guidance describing when and why to call the operation." 1677 ) 1678 input_schema: dict[str, Any] = Field( 1679 ..., description="JSON Schema Draft 7 object describing the operation's argument object." 1680 ) 1681 name: str = Field( 1682 ..., description="Stable operation name used when invoking the private service." 1683 ) 1684 output_schema: dict[str, Any] | None = Field( 1685 default=None, 1686 description="Optional JSON Schema Draft 7 object describing the successful result.", 1687 ) 1688 1689 1690class PrivateService(BaseModel): 1691 """ 1692 An immutable private service with complete callable operation contracts. 1693 """ 1694 1695 functions: list[PrivateServiceFunction] = Field( 1696 ..., description="Sorted callable definitions exposed by this private service." 1697 ) 1698 id: str = Field(..., description="Private service ID (`pvs_...`).") 1699 1700 1701class PrivateServiceEnrollment(BaseModel): 1702 """ 1703 A private service's durable connector identity. Read responses never contain 1704 an enrollment token or certificate. 1705 """ 1706 1707 generation: int = Field( 1708 ..., 1709 description="Latest committed connector certificate generation, or zero before enrollment.", 1710 ) 1711 id: str = Field(..., description="Canonical certificate-bound service identity.") 1712 private_service: str = Field(..., description="Immutable private service ID (`pvs_...`).") 1713 1714 1715class PrivateServiceEnrollmentPage(BaseModel): 1716 """ 1717 A secret-free page of private service enrollments. 1718 """ 1719 1720 data: list[PrivateServiceEnrollment] 1721 has_next: bool 1722 has_prev: bool 1723 page: int 1724 page_size: int 1725 total_entries: int 1726 total_pages: int 1727 1728 1729class PrivateServicePage(BaseModel): 1730 """ 1731 A page of private services. 1732 """ 1733 1734 data: list[PrivateService] 1735 has_next: bool 1736 has_prev: bool 1737 page: int 1738 page_size: int 1739 total_entries: int 1740 total_pages: int 1741 1742 1743class ProductKnowledgeReconcileFailure(BaseModel): 1744 """ 1745 One stamped customer whose product-knowledge tool update did not converge. 1746 """ 1747 1748 customer_key: str = Field( 1749 ..., description="Stable vendor-defined key for the customer whose agent did not converge." 1750 ) 1751 error: str = Field(..., description="Stable failure reason for operator and vendor feedback.") 1752 retryable: bool = Field( 1753 ..., description="Whether rerunning the desired-state reconciliation is safe." 1754 ) 1755 1756 1757class ProductKnowledgeReconcileResponse(BaseModel): 1758 """ 1759 Desired-state reconciliation result for a CM install's stamped agents. 1760 """ 1761 1762 complete: bool = Field( 1763 ..., 1764 description="True when every stamped customer agent now has the desired source allowlist.", 1765 ) 1766 failures: list[ProductKnowledgeReconcileFailure] = Field( 1767 ..., description="Per-customer failures. Empty when reconciliation is complete." 1768 ) 1769 reconciled_customers: list[str] = Field( 1770 ..., description="Customer keys whose agent tool config is converged." 1771 ) 1772 1773 1774class RoutinePreset(BaseModel): 1775 """ 1776 A named preset that defines the execution model and constraints for a routine. Presets are shared definitions; individual routines reference a preset by name. 1777 """ 1778 1779 applicable_events: list[str] = Field( 1780 ..., 1781 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.', 1782 ) 1783 chainable: bool = Field( 1784 ..., 1785 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.", 1786 ) 1787 description: str = Field( 1788 ..., description="Human-readable description of what the preset does and when to use it." 1789 ) 1790 label: str = Field( 1791 ..., description="Human-readable display name for the preset, suitable for use in UIs." 1792 ) 1793 name: str = Field( 1794 ..., 1795 description='Stable machine identifier for the preset, e.g. `"do_task"`. Used when assigning a preset to a routine.', 1796 ) 1797 sessionable: bool = Field( 1798 ..., 1799 description="Whether the preset runs inside the thread conversation-session lifecycle. This is distinct from preset_config.session_mode, which controls durable session reuse for do_task and send_message.", 1800 ) 1801 unique: bool = Field( 1802 ..., 1803 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.", 1804 ) 1805 1806 1807class WorkflowJournalEntry(BaseModel): 1808 """ 1809 One ordered, replayable record from a durable workflow journal. 1810 """ 1811 1812 command_id: str | None = Field( 1813 default=None, 1814 description="Durable command identifier associated with the record, when present.", 1815 ) 1816 created_at: datetime | None = Field( 1817 default=None, description="When this entry was durably committed." 1818 ) 1819 id: str = Field(..., description="Journal entry ID (`wdr_...`).") 1820 node_id: str | None = Field( 1821 default=None, 1822 description="Workflow node associated with the record. `null` for execution-level records.", 1823 ) 1824 record: dict[str, Any] = Field( 1825 ..., 1826 description="Replayable workflow record body, including payload, context, environment, metadata, and timestamp.", 1827 ) 1828 sequence: int = Field(..., description="Monotonically increasing sequence within the journal.") 1829 timer_id: str | None = Field( 1830 default=None, 1831 description="Durable timer identifier associated with the record, when present.", 1832 ) 1833 type: str = Field( 1834 ..., 1835 description="Workflow record type, such as `node_started`, `node_completed`, or `node_failed`.", 1836 ) 1837 1838 1839class WorkflowJournal(BaseModel): 1840 """ 1841 Summary of the durable workflow execution journal associated with a run. 1842 """ 1843 1844 completed_at: datetime | None = Field( 1845 default=None, 1846 description="When durable workflow execution reached a terminal state. `null` while it is active.", 1847 ) 1848 created_at: datetime | None = Field(default=None, description="When the journal was created.") 1849 current_sequence: int = Field( 1850 ..., description="Highest workflow record sequence durably committed to this journal." 1851 ) 1852 id: str = Field(..., description="Journal execution ID (`wde_...`).") 1853 started_at: datetime | None = Field( 1854 default=None, description="When durable workflow execution started." 1855 ) 1856 status: str = Field( 1857 ..., 1858 description="Current durable execution status: `pending`, `running`, `waiting`, `completed`, `failed`, or `cancelled`.", 1859 ) 1860 updated_at: datetime | None = Field( 1861 default=None, description="When the journal was last updated." 1862 ) 1863 1864 1865class RunJournalPage(BaseModel): 1866 """ 1867 A forward-paginated journal entry page for an automation or routine run. 1868 """ 1869 1870 after_cursor: str | None = Field( 1871 default=None, 1872 description="Opaque cursor for the next entry page. `null` when this is the final page.", 1873 ) 1874 before_cursor: str | None = Field( 1875 default=None, description="Always `null`; journal pagination is forward-only." 1876 ) 1877 data: list[WorkflowJournalEntry] = Field( 1878 ..., 1879 description="Journal entries ordered by ascending sequence. Empty when the run has no journal.", 1880 ) 1881 has_more: bool = Field(..., description="Whether additional entries exist after this page.") 1882 journal: WorkflowJournal | None = Field( 1883 default=None, 1884 description="Durable execution summary. `null` when this run has no journal, which is valid for script-backed, preview, or legacy runs.", 1885 ) 1886 1887 1888class SandboxKey(BaseModel): 1889 """ 1890 An API key scoped to a developer sandbox, used to authenticate requests against sandbox resources. 1891 """ 1892 1893 created_at: datetime | None = Field( 1894 default=None, description="When this key was created (ISO 8601)." 1895 ) 1896 expires_at: datetime | None = Field( 1897 default=None, 1898 description="When this key expires and becomes invalid. `null` if the key does not expire.", 1899 ) 1900 full_key: str | None = Field( 1901 default=None, 1902 description="The complete secret key value, returned only once when the key is first created. `null` on subsequent retrievals.", 1903 ) 1904 id: str = Field(..., description="Sandbox key ID (`dsk_...`).") 1905 key_hint: str | None = Field( 1906 default=None, 1907 description="A short hint showing the last four characters of the key, used for identification. `null` if no hint is available.", 1908 ) 1909 key_value: str | None = Field( 1910 default=None, 1911 description='The full key value for `"publishable"` keys. `null` for `"secret"` keys; use `full_key` instead, which is returned only at creation time.', 1912 ) 1913 last_used_at: datetime | None = Field( 1914 default=None, 1915 description="When this key was last used to authenticate a request. `null` if the key has never been used.", 1916 ) 1917 status: str = Field( 1918 ..., 1919 description='Current lifecycle status of the key. One of `"active"` (usable) or `"revoked"` (permanently disabled).', 1920 ) 1921 type: str = Field( 1922 ..., 1923 description='The kind of key. One of `"publishable"` (safe for client-side use) or `"secret"` (server-side only).', 1924 ) 1925 1926 1927class Sandbox(BaseModel): 1928 """ 1929 An isolated developer sandbox environment used for testing integrations without affecting production data or sending real emails. 1930 """ 1931 1932 created_at: datetime | None = Field( 1933 default=None, description="When this sandbox was created (ISO 8601)." 1934 ) 1935 expires_at: datetime | None = Field( 1936 default=None, 1937 description="When an eval sandbox expires and becomes eligible for platform cleanup. `null` for ordinary developer sandboxes.", 1938 ) 1939 id: str = Field(..., description="Sandbox ID (`dsb_...`).") 1940 keys: list[SandboxKey] | None = Field( 1941 default=None, 1942 description="API keys associated with this sandbox. `null` if keys were not loaded with this response.", 1943 ) 1944 name: str = Field(..., description="Human-readable display name for the sandbox.") 1945 org: str | None = Field( 1946 default=None, 1947 description="Organization ID this sandbox is scoped to, or `null` for an app-level sandbox.", 1948 ) 1949 org_logo: ImageSource | None = Field( 1950 default=None, description="Logo of the owning organization, when present." 1951 ) 1952 org_name: str | None = Field( 1953 default=None, description="Display name of the owning organization, when org-scoped." 1954 ) 1955 purpose: str | None = Field( 1956 default=None, 1957 description='Sandbox purpose marker. `"eval"` marks a remote-eval sandbox; `null` for ordinary developer sandboxes.', 1958 ) 1959 slug: str = Field( 1960 ..., 1961 description='URL-safe identifier for the sandbox, unique within the application (e.g. `"my-sandbox"`).', 1962 ) 1963 updated_at: datetime | None = Field( 1964 default=None, description="When this sandbox was last modified (ISO 8601)." 1965 ) 1966 1967 1968class SlackChannelBinding(BaseModel): 1969 """ 1970 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. 1971 """ 1972 1973 agents: list[str] | None = Field( 1974 default=None, 1975 description="IDs of every agent attached to this binding, including legacy concierge attachments. Use `resident_agent` and `route_kind` for the effective runtime route.", 1976 ) 1977 allow_bot_conversations: bool = Field( 1978 ..., 1979 description="Whether this channel opts into sustained bot-to-bot conversation, exempting it from the reply loop brake. Defaults to `false`.", 1980 ) 1981 channel: str | None = Field( 1982 default=None, description="Slack channel ID (e.g. `C01234ABCDE`) that this binding targets." 1983 ) 1984 customer_label: str | None = Field( 1985 default=None, 1986 description="Human-readable label identifying the customer, derived from the binding's embedded config. `null` when not set.", 1987 ) 1988 deposit_thread: str | None = Field( 1989 default=None, 1990 description="Staging thread the deposit pipe copies this channel's mirror content into (`thr_ ` public ID). `null` when the pipe is off for this binding.", 1991 ) 1992 disclosure_state: Literal["pending", "posted", "suppressed"] | None = Field( 1993 default=None, 1994 description="Slack Connect lifecycle: `pending` while the customer has not accepted the invite (nothing mirrors), `posted` once the AI disclosure is in the channel and the channel is live, `suppressed` when relay is stopped. `null` for a binding that never went through Connect provisioning.", 1995 ) 1996 id: str = Field(..., description="Unique identifier for this Slack channel binding.") 1997 integration: str | None = Field( 1998 default=None, description="ID of the Slack integration that owns this binding." 1999 ) 2000 is_ext_shared_cached: bool | None = Field( 2001 default=None, 2002 description="Cached value of Slack's `is_ext_shared` flag for this channel. May be stale relative to Slack's current state.", 2003 ) 2004 is_private_cached: bool | None = Field( 2005 default=None, 2006 description="Cached value of Slack's `is_private` flag for this channel. May be stale relative to Slack's current state. Private channels are member-managed: mutating the binding requires in-channel evidence.", 2007 ) 2008 mirrors: list[str] | None = Field( 2009 default=None, 2010 description="IDs of every mirror thread this channel's messages land in (`thr_ ` public IDs) that the caller can read, including any legacy peel or chain threads. Empty for a caller with no membership on any of them, and for a channel that has not mirrored anything yet. IDs only: reading a mirror's contents still requires membership on it.", 2011 ) 2012 muted: bool = Field( 2013 ..., 2014 description="Whether the resident agent is currently muted. A muted resident keeps mirroring the channel (reading) but stops replying. A timed mute expires automatically at `muted_until`; this reflects the effective state as of now. Defaults to `false`.", 2015 ) 2016 muted_until: str | None = Field( 2017 default=None, 2018 description="ISO 8601 timestamp when a timed mute expires and replies resume. `null` for an indefinite mute (until an explicit unmute) or when not muted.", 2019 ) 2020 reply_style: str = Field( 2021 ..., 2022 description="How the resident agent's replies post to Slack: `thread` (default) threads a reply under the message that triggered it; `top_level` posts it flat in the channel.", 2023 ) 2024 resident_agent: str | None = Field( 2025 default=None, 2026 description="ID of the resident agent selected by Slack ingress. `null` when no resident is attached and the channel is an observer.", 2027 ) 2028 route_kind: Literal["fda", "resident", "observer", "concierge"] = Field( 2029 ..., 2030 description="Effective Slack ingress route. `fda` a resident on a team-bound channel, replying through the Forward Deployed Agent chain. `resident` a resident on an internal channel, replying through the channel mirror. `observer` no resident is attached, so the channel is recorded and nobody replies. `concierge` no longer returned anywhere; until Track F it was the value for a channel with no resident, meaning the shared concierge agent answered there. The value is retained in this enum so consumers matching on it do not break, and its removal rides a deliberate API change.", 2031 ) 2032 scope_key: str | None = Field( 2033 default=None, 2034 description="The customer key this channel's agent is locked to, written when adding the customer finishes. A `posted` binding whose `scope_key` is still null has been accepted but not finished the addition is either in flight or was refused.", 2035 ) 2036 team: str | None = Field( 2037 default=None, description="ID of the ArchAstro team this channel is bound to." 2038 ) 2039 vendor_admin_channel_access: ( 2040 Literal["invited", "already_member", "no_slack_user", "failed"] | None 2041 ) = Field( 2042 default=None, 2043 description="Whether the admin who added this customer ended up inside a Connect channel we created for them: `invited` (we put them in), `already_member` (they were in it already), `no_slack_user` (their account email is not a Slack account in your workspace, so nobody was invited), or `failed` (Slack refused). A created Connect channel is private and has no self-join, so the last two mean the channel has no human from your side until someone already in it adds one. `null` when nobody was added: the channel was adopted rather than created (an existing channel already has its own members), the binding never went through Connect provisioning, or the call had no admin behind it.", 2044 ) 2045 2046 2047class SlackChannelBindingListResponse(BaseModel): 2048 """ 2049 Paginated list of Slack channel bindings for the requested integration or team. Use the `page` and `per_page` fields to navigate pages of results. 2050 """ 2051 2052 data: list[SlackChannelBinding] = Field( 2053 ..., description="Array of Slack channel binding objects for the current page." 2054 ) 2055 page: int = Field(..., description="Current page number (1-indexed).") 2056 per_page: int = Field(..., description="Maximum number of bindings returned per page.") 2057 total_count: int = Field( 2058 ..., 2059 description="Total number of Slack channel bindings matching the query across all pages.", 2060 ) 2061 total_pages: int = Field( 2062 ..., description="Total number of pages available at the current `per_page` size." 2063 ) 2064 2065 2066class SlackDeliveryOutcome(BaseModel): 2067 """ 2068 What happened to one agent message this platform sent to a Slack channel. Lets you confirm delivery, or find out why a reply never arrived, without reading the channel's mirrored conversation. 2069 """ 2070 2071 agent: str | None = Field(default=None, description="ID of the agent whose message this was.") 2072 binding: str | None = Field( 2073 default=None, 2074 description="ID of the Slack channel binding in force for this send. `null` when no binding could be resolved, in which case the send was treated as cross-org and floored on that basis.", 2075 ) 2076 channel: str = Field(..., description="Slack channel ID the send was addressed to.") 2077 failure_reason: str | None = Field( 2078 default=None, 2079 description="For a `failed` send, a short machine-readable cause `slack:<slack_error_code>` when Slack rejected the call, or `floor_config` when the content floor could not be evaluated and the send failed closed.", 2080 ) 2081 guard_kind: str | None = Field( 2082 default=None, 2083 description="For a withheld send, the kind of guard that stopped it `RegexMatch`, `ContainsAny`, `ContainsString`, or `LLMJudge`. `null` when the send was not withheld by a guard.", 2084 ) 2085 guard_labels: list[str] | None = Field( 2086 default=None, 2087 description="For a withheld send, the labels of the guards that stopped it (for example `Contains AWS access key ID`). These are the content policy's own descriptions, recorded as they read at the time of the send; they never contain the withheld message.", 2088 ) 2089 id: str = Field(..., description="Unique identifier for this delivery outcome.") 2090 message: str | None = Field( 2091 default=None, 2092 description="ID of the platform message this attempt was carrying. Reading that message still requires access to its thread this field correlates, it does not grant.", 2093 ) 2094 operation: Literal["post", "post_ephemeral", "update"] = Field( 2095 ..., 2096 description="Which Slack call the attempt made. `post` a new message in the channel, visible to everyone in it. `post_ephemeral` a message only one named channel member could see; Slack returns no durable timestamp for one, so it has no `thread_ts` to correlate and cannot be found in the channel's history afterwards. `update` replacing an existing message (typically a thinking placeholder).", 2097 ) 2098 outcome: Literal["delivered", "floored", "judge_refused", "failed"] = Field( 2099 ..., 2100 description="What happened to the send. `delivered` Slack accepted the message. `floored` a deterministic content guard withheld it, so it never left. `judge_refused` the cross-org judge decided it was not appropriate for this channel's audience. `failed` Slack rejected the call, or the content floor could not be evaluated and the send failed closed.", 2101 ) 2102 recorded_at: datetime = Field(..., description="When the send was attempted.") 2103 thread_ts: str | None = Field( 2104 default=None, 2105 description="Slack thread timestamp the send targeted, letting attempts be grouped into the conversation they belong to. `null` for a top-level channel post.", 2106 ) 2107 2108 2109class SlackDeliveryOutcomeListResponse(BaseModel): 2110 """ 2111 A page of delivery outcomes for one Slack channel, newest first. Page through history with the returned cursors; `since` and `outcome` are filters, not paging controls. 2112 """ 2113 2114 after_cursor: str | None = Field( 2115 default=None, 2116 description="Opaque cursor for the page of newer outcomes. Pass back as `after_cursor` to poll for attempts recorded since. `null` when the page is empty.", 2117 ) 2118 before_cursor: str | None = Field( 2119 default=None, 2120 description="Opaque cursor for the page of older outcomes. Pass back as `before_cursor` to continue into history. `null` when the page is empty.", 2121 ) 2122 data: list[SlackDeliveryOutcome] = Field( 2123 ..., description="Delivery outcomes matching the query, newest attempt first." 2124 ) 2125 has_more: bool = Field(..., description="True when more outcomes exist beyond this page.") 2126 2127 2128class Trajectory(BaseModel): 2129 """ 2130 A recorded sequence of AI messages and tool interactions representing a single AI reasoning session. Trajectories are stored as structured message logs and can be replayed or inspected after execution. 2131 """ 2132 2133 created_at: str | None = Field( 2134 default=None, description="When the trajectory was recorded (ISO 8601)." 2135 ) 2136 file: str | None = Field( 2137 default=None, 2138 description="ID of the storage file that persists the raw trajectory data (`fil_...`).", 2139 ) 2140 id: str = Field(..., description="Trajectory ID (`trj_...`).") 2141 messages: list[dict[str, Any]] | None = Field( 2142 default=None, 2143 description="Serialized message log for this trajectory. Contains the ordered sequence of AI and tool messages produced during the session.", 2144 ) 2145 org: str | None = Field( 2146 default=None, 2147 description="ID of the organization this trajectory belongs to (`org_...`). `null` for trajectories outside an org context.", 2148 ) 2149 sandbox: str | None = Field( 2150 default=None, 2151 description="ID of the developer sandbox this trajectory is scoped to (`sbx_...`). `null` for production trajectories.", 2152 ) 2153 team: str | None = Field( 2154 default=None, 2155 description="ID of the team this trajectory is scoped to (`team_...`). `null` for trajectories not associated with a team.", 2156 ) 2157 updated_at: str | None = Field( 2158 default=None, description="When the trajectory record was last updated (ISO 8601)." 2159 ) 2160 2161 2162class ValidationResult(BaseModel): 2163 """ 2164 The result of a configuration validation check, indicating whether the config is valid and listing any errors or warnings. 2165 """ 2166 2167 errors: list[str] | None = Field( 2168 default=None, 2169 description="List of human-readable error messages describing why validation failed. Empty or absent when `valid` is `true`.", 2170 ) 2171 valid: bool = Field( 2172 ..., 2173 description="`true` if the configuration passed all validation checks, `false` if one or more errors were found.", 2174 ) 2175 warnings: list[str] | None = Field( 2176 default=None, 2177 description="List of human-readable warning messages emitted during validation. Warnings do not cause `valid` to be `false` but indicate potentially problematic configuration.", 2178 ) 2179 2180 2181class WorkflowWorkItem(BaseModel): 2182 """ 2183 Externally executable work yielded by a durable workflow. 2184 """ 2185 2186 agent: str = Field(..., description="Agent assigned to execute this work.") 2187 attempt_count: int = Field( 2188 ..., description="Number of times this work has been freshly claimed or reclaimed." 2189 ) 2190 command_id: str = Field( 2191 ..., description="Opaque journal command identity used to resume the workflow exactly once." 2192 ) 2193 created_at: datetime 2194 execution: str = Field(..., description="Durable workflow execution that owns this work.") 2195 id: str = Field(..., description="Work item ID (`wdi_...`).") 2196 lease_expires_at: datetime | None = Field( 2197 default=None, 2198 description="When the current claim expires. Null for queued or terminal work.", 2199 ) 2200 node_id: str = Field(..., description="Workflow graph node that yielded the work.") 2201 payload: dict[str, Any] = Field( 2202 ..., description="Instructions and participant bindings needed to execute the work." 2203 ) 2204 routine_run: str | None = Field( 2205 default=None, 2206 description="Routine run that owns the execution, when this work came from a routine.", 2207 ) 2208 status: str = Field(..., description="Current queue lifecycle status.") 2209 type: str = Field( 2210 ..., description="Stable resource discriminator. Always `workflow_work_item`." 2211 ) 2212 updated_at: datetime 2213 2214 2215class WorkflowWorkItemLease(BaseModel): 2216 """ 2217 A claimed workflow work item and its caller-held lease token. 2218 """ 2219 2220 lease_owner: str = Field( 2221 ..., 2222 description="Opaque lease token that must be persisted and presented for later transitions.", 2223 ) 2224 work_item: WorkflowWorkItem = Field( 2225 ..., description="The claimed, resumed, started, or heartbeated work item." 2226 ) 2227 2228 2229class WorkflowWorkItemClaim(BaseModel): 2230 """ 2231 Result of polling an agent's durable workflow work queue. 2232 """ 2233 2234 data: WorkflowWorkItemLease | None = Field( 2235 default=None, 2236 description="Claimed or resumed work and its lease; null when no eligible item exists.", 2237 ) 2238 2239 2240class WorkflowWorkItemList(BaseModel): 2241 """ 2242 Active durable workflow work available to the viewer. 2243 """ 2244 2245 after_cursor: str | None = Field( 2246 default=None, description="Opaque cursor for the next page, or null at the end." 2247 ) 2248 before_cursor: str | None = Field( 2249 default=None, description="Always null because queue pagination is forward-only." 2250 ) 2251 data: list[WorkflowWorkItem] = Field( 2252 ..., 2253 description="Active work items. Lease tokens are intentionally never included in list responses.", 2254 ) 2255 has_more: bool = Field(..., description="Whether another page of work exists.") 2256 2257 2258class WorkingMemoryEntry(BaseModel): 2259 """ 2260 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. 2261 """ 2262 2263 agent: str | None = Field( 2264 default=None, description="ID of the agent that owns this memory entry (`agt_...`)." 2265 ) 2266 created_at: datetime | None = Field( 2267 default=None, description="When this memory entry was first written (ISO 8601)." 2268 ) 2269 expires_at: datetime | None = Field( 2270 default=None, 2271 description="When this entry will be automatically deleted. `null` if the entry does not expire.", 2272 ) 2273 id: str = Field(..., description="Working memory entry ID (`amm_...`).") 2274 key: str | None = Field( 2275 default=None, 2276 description="The string key used to look up this memory entry within the agent's memory namespace.", 2277 ) 2278 updated_at: datetime | None = Field( 2279 default=None, description="When this memory entry was last modified (ISO 8601)." 2280 ) 2281 value: str | None = Field( 2282 default=None, 2283 description="The string value stored under `key`. May be any serialized content the agent wrote.", 2284 ) 2285 2286 2287class WorkingMemoryEntryListResponse(BaseModel): 2288 """ 2289 Paginated list of working memory entries stored for an agent. Includes page metadata to support sequential page traversal. 2290 """ 2291 2292 data: list[WorkingMemoryEntry] = Field( 2293 ..., description="Array of working memory entry objects for the current page." 2294 ) 2295 has_next: bool | None = Field( 2296 default=None, 2297 description="`true` if a subsequent page exists and can be fetched by incrementing the page number.", 2298 ) 2299 has_prev: bool | None = Field( 2300 default=None, 2301 description="`true` if a previous page exists and can be fetched by decrementing the page number.", 2302 ) 2303 page: int | None = Field(default=None, description="The current page number, starting at `1`.") 2304 page_size: int | None = Field( 2305 default=None, description="Maximum number of entries returned per page." 2306 ) 2307 total_entries: int | None = Field( 2308 default=None, 2309 description="Total number of working memory entries matching the query across all pages.", 2310 ) 2311 total_pages: int | None = Field( 2312 default=None, description="Total number of pages given the current `page_size`." 2313 ) 2314 2315 2316class SolutionAutomationInvokeContract(BaseModel): 2317 """ 2318 The schema-driven values an installer may lock when provisioning an invoked automation template. 2319 """ 2320 2321 input_schema: dict[str, Any] | None = Field( 2322 default=None, 2323 description="JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", 2324 ) 2325 participants: list[AutomationParticipantSlot] | None = Field( 2326 default=None, 2327 description="Named participant slots declared by the workflow, sorted by name. `null` when the workflow declares none. Values supplied under the top-level `participants` field are agent IDs.", 2328 ) 2329 prefills: AutomationPrefills = Field( 2330 ..., 2331 description="Owner-controlled payload and participant values the platform applies to every invocation. Supplying a conflicting value is rejected.", 2332 ) 2333 2334 2335class SolutionAutomationTemplateDetails(BaseModel): 2336 """ 2337 AutomationTemplate-specific details exposed by a Solution template summary. 2338 """ 2339 2340 automation_type: str | None = Field( 2341 default=None, 2342 description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", 2343 ) 2344 invoke_contract: SolutionAutomationInvokeContract | None = Field( 2345 default=None, 2346 description="Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning. `null` for non-invoked automation types.", 2347 ) 2348 type: Literal["automation"] = Field( 2349 default="automation", 2350 description="Template-details discriminator. Always `automation` for this variant.", 2351 ) 2352 2353 2354# Template-kind-specific Solution summary details, discriminated by `type`. 2355SolutionTemplateDetails = Annotated[SolutionAutomationTemplateDetails, Field(discriminator="type")] 2356 2357 2358class SolutionTemplateSummary(BaseModel): 2359 """ 2360 Identity and display metadata for a single template bundled by a Solution, used to represent each wrapped or sibling template at template granularity. 2361 """ 2362 2363 description: str | None = Field( 2364 default=None, 2365 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.", 2366 ) 2367 details: SolutionTemplateDetails | None = Field( 2368 default=None, 2369 description="Template-kind-specific details selected by the `type` discriminator. `null` when this template kind has no additional details.", 2370 ) 2371 display_name: str | None = Field( 2372 default=None, 2373 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`.", 2374 ) 2375 id: str | None = Field( 2376 default=None, 2377 description="Template config ID (`cfg_...`). `null` for inline-only templates.", 2378 ) 2379 kind: str = Field( 2380 ..., 2381 description="Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.", 2382 ) 2383 lookup_key: str | None = Field( 2384 default=None, 2385 description="Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", 2386 ) 2387 name: str | None = Field( 2388 default=None, 2389 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`.", 2390 ) 2391 readme_url: str | None = Field( 2392 default=None, 2393 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`.", 2394 ) 2395 virtual_path: str | None = Field( 2396 default=None, 2397 description="Stable virtual path assigned to the template config. `null` when no virtual path was set.", 2398 ) 2399 2400 2401class SolutionSummary(BaseModel): 2402 """ 2403 A catalog entry for an imported Solution, including its display metadata, bundled templates, owner scopes, and any available upgrade information. 2404 """ 2405 2406 category_keys: list[str] | None = Field( 2407 default=None, 2408 description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", 2409 ) 2410 created_at: str | None = Field( 2411 default=None, description="When the Solution config was first imported (ISO 8601)." 2412 ) 2413 description: str | None = Field( 2414 default=None, 2415 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.", 2416 ) 2417 events: dict[str, Any] | None = Field( 2418 default=None, 2419 description="Custom analytics events declared in the Solution body's `events:` manifest a map of event key (snake_case) to its definition (`label`, optional `description`, optional typed `fields`). Dashboards use the `label` as the event's display name. Present as an empty object when the body declares none.", 2420 ) 2421 id: str = Field(..., description="Solution config ID (`cfg_...`).") 2422 image_url: str | None = Field( 2423 default=None, 2424 description="Absolute URL of the Solution's cover image the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows the permanent URL is minted for system-scope (catalog) Solutions only.", 2425 ) 2426 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 2427 latest_solution: str | None = Field( 2428 default=None, 2429 description="When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", 2430 ) 2431 latest_version: str | None = Field( 2432 default=None, 2433 description="When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", 2434 ) 2435 lookup_key: str | None = Field( 2436 default=None, 2437 description="The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", 2438 ) 2439 metadata: dict[str, Any] | None = Field( 2440 default=None, 2441 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.", 2442 ) 2443 name: str | None = Field( 2444 default=None, 2445 description="Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", 2446 ) 2447 org: str | None = Field( 2448 default=None, 2449 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.", 2450 ) 2451 org_logo: ImageSource | None = Field( 2452 default=None, 2453 description="Canonical image-source object for the resolved `org`'s logo, used as the principal category section glyph. The `url` is a stable, non-expiring capability URL (`refresh_url` is `null` there is nothing to refresh). `null` when `org_slug` is `null` or the org has no logo.", 2454 ) 2455 org_name: str | None = Field( 2456 default=None, 2457 description="Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", 2458 ) 2459 org_slug: str | None = Field( 2460 default=None, 2461 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.", 2462 ) 2463 owners: list[str] = Field( 2464 ..., 2465 description='Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer\'s org scope).', 2466 ) 2467 readme_url: str | None = Field( 2468 default=None, 2469 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`.", 2470 ) 2471 screenshot_urls: list[str] | None = Field( 2472 default=None, 2473 description="Absolute URLs of the Solution's gallery screenshots the bundled assets the body's `screenshots:` field names, in declared order. Each is a stable, non-expiring capability URL with the same cacheability contract as `image_url` (one shared token, a `v` cache key, and a `file` param selecting the screenshot); a URL 404s if the Solution stops declaring its screenshot. An empty array when the Solution declares none, and always empty for org-scoped rows the permanent URLs are minted for system-scope (catalog) Solutions only.", 2474 ) 2475 solution_id: str | None = Field( 2476 default=None, 2477 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.", 2478 ) 2479 solution_version: str | None = Field( 2480 default=None, 2481 description='Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.', 2482 ) 2483 tag_keys: list[str] | None = Field( 2484 default=None, 2485 description="Freeform tag keys declared in the Solution body. An empty array when the body declares none.", 2486 ) 2487 template_kind: str | None = Field( 2488 default=None, 2489 description='Wrapped template kind `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.', 2490 ) 2491 templates: list[SolutionTemplateSummary] = Field( 2492 ..., 2493 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.", 2494 ) 2495 updated_at: str | None = Field( 2496 default=None, description="When the Solution config was last modified (ISO 8601)." 2497 ) 2498 upgrade_available: bool = Field( 2499 ..., 2500 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.", 2501 ) 2502 virtual_path: str | None = Field( 2503 default=None, 2504 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.", 2505 ) 2506 2507 2508class AgentSourceSolution(BaseModel): 2509 """ 2510 Summary of the Solution and AgentTemplate that an agent was last provisioned from. 2511 Returned on single-agent responses; `null` for hand-built agents and agents whose tracked template or parent Solution has been deleted. 2512 """ 2513 2514 current_solution: SolutionSummary | None = Field( 2515 default=None, 2516 description="Summary of the current parent Solution config row. `solution` is the pinned Solution version the agent points at; `current_solution` is the source Solution config row as it exists now.", 2517 ) 2518 solution: SolutionSummary = Field( 2519 ..., 2520 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.", 2521 ) 2522 template: UpgradeTemplateSummary = Field( 2523 ..., 2524 description="Summary of the AgentTemplate config (`cfg_...`) the agent was last provisioned or updated from.", 2525 ) 2526 2527 2528class Agent(BaseModel): 2529 """ 2530 An AI agent that can be configured with tools, routines, and skills, and invoked to handle conversations or tasks. 2531 """ 2532 2533 acl: Acl | None = Field( 2534 default=None, 2535 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.", 2536 ) 2537 app: str | None = Field( 2538 default=None, description="ID of the application that owns this agent (`dap_...`)." 2539 ) 2540 created_at: str | None = Field( 2541 default=None, description="When the agent was created (ISO 8601)." 2542 ) 2543 default_model: str | None = Field( 2544 default=None, 2545 description='Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `"claude-3-7-sonnet-latest"`).', 2546 ) 2547 description: str | None = Field( 2548 default=None, 2549 description="Human-readable description of what the agent does. `null` if not set.", 2550 ) 2551 email: str | None = Field( 2552 default=None, 2553 description="Email address provisioned for this agent. `null` if email delivery is not configured.", 2554 ) 2555 id: str = Field(..., description="Agent ID (`agi_...`).") 2556 identity: str | None = Field( 2557 default=None, 2558 description="System-level identity prompt that shapes the agent's persona and behavior.", 2559 ) 2560 last_applied_template_config: str | None = Field( 2561 default=None, 2562 description="ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", 2563 ) 2564 lookup_key: str | None = Field( 2565 default=None, 2566 description="Stable, user-defined identifier for this agent within the application. Unique per app.", 2567 ) 2568 metadata: dict[str, Any] | None = Field( 2569 default=None, 2570 description="Arbitrary key-value metadata attached to the agent. Not interpreted by the platform.", 2571 ) 2572 name: str | None = Field( 2573 default=None, description="Human-readable display name for the agent. `null` if not set." 2574 ) 2575 org: str | None = Field( 2576 default=None, 2577 description="ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", 2578 ) 2579 org_name: str | None = Field( 2580 default=None, 2581 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.", 2582 ) 2583 originator: str | None = Field( 2584 default=None, 2585 description="Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", 2586 ) 2587 phone_number: str | None = Field( 2588 default=None, 2589 description="Phone number provisioned for this agent. `null` if SMS is not configured.", 2590 ) 2591 sandbox: str | None = Field( 2592 default=None, 2593 description="ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", 2594 ) 2595 source_solution: AgentSourceSolution | None = Field( 2596 default=None, 2597 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.", 2598 ) 2599 team: str | None = Field( 2600 default=None, 2601 description="ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", 2602 ) 2603 template_upgrade_available: bool | None = Field( 2604 default=None, 2605 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 on both the list endpoints and single-agent GET. Distinct from `source_solution.upgrade_available`, which compares Solution *versions*: an agent can lag its template (`template_upgrade_available: true`) while the org already holds the latest Solution version (`upgrade_available: false`).", 2606 ) 2607 updated_at: str | None = Field( 2608 default=None, description="When the agent was last modified (ISO 8601)." 2609 ) 2610 user: str | None = Field( 2611 default=None, 2612 description="ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", 2613 ) 2614 2615 2616class AgentComputer(BaseModel): 2617 """ 2618 A cloud computer resource provisioned for an agent to use for browser and desktop automation tasks. 2619 """ 2620 2621 agent: str | None = Field( 2622 default=None, 2623 description="ID of the agent that owns this computer (`agi_...`). `null` if the computer is not yet assigned to an agent.", 2624 ) 2625 app: str | None = Field( 2626 default=None, description="ID of the app this computer belongs to (`dap_...`)." 2627 ) 2628 config: dict[str, Any] | None = Field( 2629 default=None, 2630 description="Provider-specific configuration key-value pairs for the computer. Structure depends on the underlying compute provider.", 2631 ) 2632 created_at: datetime | None = Field( 2633 default=None, description="When the computer was created (ISO 8601)." 2634 ) 2635 error_message: str | None = Field( 2636 default=None, 2637 description='Human-readable error description when `status` is `"error"`. `null` otherwise.', 2638 ) 2639 id: str = Field(..., description="Computer ID (`cmp_...`).") 2640 last_active_at: datetime | None = Field( 2641 default=None, 2642 description="When the computer last reported activity or received a command. `null` if the computer has never been active.", 2643 ) 2644 lookup_key: str | None = Field( 2645 default=None, 2646 description="Unique, stable identifier you assign to this computer within its app. `null` if not set.", 2647 ) 2648 metadata: dict[str, Any] | None = Field( 2649 default=None, 2650 description="Arbitrary key-value metadata you attached to the computer. `null` if none was provided.", 2651 ) 2652 name: str | None = Field( 2653 default=None, description="Human-readable display name for the computer. `null` if not set." 2654 ) 2655 provider: str | None = Field( 2656 default=None, 2657 description='Compute backend powering this computer: `"sprites"` (Fly Sprites) or `"vercel"` (Vercel Sandbox).', 2658 ) 2659 region: str | None = Field( 2660 default=None, 2661 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"`).', 2662 ) 2663 sprite_url: str | None = Field( 2664 default=None, 2665 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.", 2666 ) 2667 status: str | None = Field( 2668 default=None, 2669 description='Current lifecycle state of the computer. Common values include `"provisioning"`, `"ready"`, `"error"`, and `"terminated"`.', 2670 ) 2671 updated_at: datetime | None = Field( 2672 default=None, description="When the computer record was last modified (ISO 8601)." 2673 ) 2674 2675 2676class AgentComputerListResponse(BaseModel): 2677 """ 2678 A list of agent computers returned by a list query. 2679 """ 2680 2681 data: list[AgentComputer] = Field( 2682 ..., description="Array of agent computer objects matching the query." 2683 ) 2684 2685 2686class AgentCreateResponse(BaseModel): 2687 """ 2688 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. 2689 """ 2690 2691 acl: Acl | None = Field( 2692 default=None, 2693 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.", 2694 ) 2695 app: str | None = Field( 2696 default=None, description="ID of the app this agent belongs to (`dap_...`)." 2697 ) 2698 created_at: str | None = Field( 2699 default=None, description="When the agent was created (ISO 8601)." 2700 ) 2701 default_model: str | None = Field( 2702 default=None, 2703 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.', 2704 ) 2705 email: str | None = Field( 2706 default=None, 2707 description="Email address assigned to this agent for inbound email handling. `null` if not configured.", 2708 ) 2709 id: str = Field(..., description="Agent ID (`agi_...`).") 2710 identity: str | None = Field( 2711 default=None, 2712 description="System prompt or persona description that shapes the agent's behavior. `null` if not set.", 2713 ) 2714 installed_configs: list[InstalledConfigEntry] | None = Field( 2715 default=None, 2716 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`.", 2717 ) 2718 lookup_key: str | None = Field( 2719 default=None, 2720 description="Unique, stable identifier for the agent within its app. `null` if not set.", 2721 ) 2722 metadata: dict[str, Any] | None = Field( 2723 default=None, 2724 description="Arbitrary key-value metadata attached to the agent. `null` if none was provided.", 2725 ) 2726 name: str | None = Field( 2727 default=None, description="Human-readable display name for the agent. `null` if not set." 2728 ) 2729 org: str | None = Field( 2730 default=None, 2731 description="ID of the organization this agent belongs to (`org_...`). `null` for agents outside an org.", 2732 ) 2733 originator: str | None = Field( 2734 default=None, 2735 description="Free-form label identifying the source or author of the agent, e.g. a username or service name. `null` if not set.", 2736 ) 2737 phone_number: str | None = Field( 2738 default=None, 2739 description="Phone number assigned to this agent for inbound SMS or voice handling. `null` if not configured.", 2740 ) 2741 sandbox: str | None = Field( 2742 default=None, 2743 description="ID of the sandbox environment this agent is scoped to (`sbx_...`). `null` for agents not scoped to a sandbox.", 2744 ) 2745 team: str | None = Field( 2746 default=None, 2747 description="ID of the team that owns this agent (`tea_...`). `null` if owned by a user rather than a team.", 2748 ) 2749 updated_at: str | None = Field( 2750 default=None, description="When the agent record was last modified (ISO 8601)." 2751 ) 2752 user: str | None = Field( 2753 default=None, 2754 description="ID of the user that owns this agent (`usr_...`). `null` if owned by a team.", 2755 ) 2756 2757 2758class AgentEnvVarMasked(BaseModel): 2759 """ 2760 An agent environment variable with its secret value masked for safe display in list and show responses. 2761 """ 2762 2763 agent: str = Field( 2764 ..., description="ID of the agent this environment variable belongs to (`agt_...`)." 2765 ) 2766 created_at: datetime | None = Field( 2767 default=None, description="When the environment variable was created (ISO 8601)." 2768 ) 2769 description: str | None = Field( 2770 default=None, 2771 description="Optional human-readable note describing the purpose of this variable. `null` if not set.", 2772 ) 2773 id: str = Field(..., description="Environment variable ID (`anv_...`).") 2774 key: str = Field( 2775 ..., description="Name of the environment variable as it appears in the agent's runtime." 2776 ) 2777 masked_value: str = Field( 2778 ..., 2779 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.", 2780 ) 2781 updated_at: datetime | None = Field( 2782 default=None, description="When the environment variable was last updated (ISO 8601)." 2783 ) 2784 2785 2786class AgentEnvVarMaskedList(BaseModel): 2787 """ 2788 Flat list of masked environment variables belonging to an agent. 2789 """ 2790 2791 data: list[AgentEnvVarMasked] = Field( 2792 ..., description="Array of masked environment variable objects for the agent." 2793 ) 2794 2795 2796class AgentExport(BaseModel): 2797 """ 2798 A portable export bundle for an agent, containing everything needed to re-deploy it in another workspace or environment. 2799 """ 2800 2801 configs: list[Config] = Field( 2802 ..., 2803 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.", 2804 ) 2805 template: dict[str, Any] = Field( 2806 ..., 2807 description="The agent template definition as a structured map. Pass this directly to the import endpoint to recreate the agent.", 2808 ) 2809 2810 2811class AgentHealth(BaseModel): 2812 """ 2813 Aggregate health profile for an agent, summarizing its current operational status, score, and the full list of setup and health actions. 2814 """ 2815 2816 activity: dict[str, Any] = Field( 2817 ..., 2818 description="Timestamps for the agent's most recent and next scheduled activity, used to surface last-run and upcoming-run information.", 2819 ) 2820 agent: Agent = Field(..., description="The agent this health profile describes.") 2821 checked_at: datetime = Field( 2822 ..., description="When the health profile was last computed (ISO 8601)." 2823 ) 2824 checks: list[dict[str, Any]] = Field( 2825 ..., 2826 description="Renderable health check results. Each object includes at minimum `key`, `label`, `status`, and `summary` fields.", 2827 ) 2828 counts: dict[str, Any] = Field( 2829 ..., 2830 description="Action counts broken down by dependency area and resolution status, used to render progress indicators per category.", 2831 ) 2832 health_actions: list[AgentHealthAction] = Field( 2833 ..., 2834 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.', 2835 ) 2836 recent: dict[str, Any] = Field( 2837 ..., 2838 description="Recent execution metrics for the agent, including run counts and failure counts over a recent time window.", 2839 ) 2840 score: int = Field( 2841 ..., 2842 description="Normalized health score from `0` (fully degraded) to `100` (fully healthy), derived from the weight and status of all health actions.", 2843 ) 2844 status: str = Field( 2845 ..., 2846 description='Overall health status of the agent. One of `"ok"`, `"warning"`, or `"critical"`.', 2847 ) 2848 2849 2850class AgentListResponse(BaseModel): 2851 """ 2852 Paginated list of agent objects. Use the pagination fields to traverse multiple pages of results. 2853 """ 2854 2855 data: list[Agent] = Field(..., description="Array of agent objects for the current page.") 2856 has_next: bool | None = Field( 2857 default=None, description="`true` when a subsequent page of results exists." 2858 ) 2859 has_prev: bool | None = Field( 2860 default=None, description="`true` when a previous page of results exists." 2861 ) 2862 page: int | None = Field(default=None, description="Current page number, starting at 1.") 2863 page_size: int | None = Field( 2864 default=None, description="Maximum number of agents returned per page." 2865 ) 2866 total_entries: int | None = Field( 2867 default=None, description="Total number of agents matching the query across all pages." 2868 ) 2869 total_pages: int | None = Field( 2870 default=None, description="Total number of pages available given the current `page_size`." 2871 ) 2872 2873 2874class AgentRoutine(BaseModel): 2875 """ 2876 An agent routine defines a reusable handler script, preset, or chain that runs in response to events or on a schedule. 2877 """ 2878 2879 acl: Acl | None = Field( 2880 default=None, 2881 description='Access control list for the routine. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions` (`"read"`, `"invoke"`, or `"assign"` an `"assign"` grant names the agents or orgs that may be handed this routine\'s embedded work items). `null` when no ACL restrictions are applied and the routine is accessible to all members of its scope.', 2882 ) 2883 agent: str | None = Field( 2884 default=None, description="ID of the agent that owns this routine (`agi_...`)." 2885 ) 2886 app: str | None = Field( 2887 default=None, description="Application that scopes this routine (`dap_...`)." 2888 ) 2889 config: str | None = Field( 2890 default=None, 2891 description="ID of the Config record that backs this routine's configuration (`cfg_...`). `null` when the routine is not config-backed.", 2892 ) 2893 created_at: datetime | None = Field( 2894 default=None, description="When this routine was created (ISO 8601)." 2895 ) 2896 description: str | None = Field( 2897 default=None, 2898 description="Optional description of what this routine does. `null` when not set.", 2899 ) 2900 event_config: dict[str, Any] | None = Field( 2901 default=None, 2902 description="Additional configuration controlling how the event trigger is matched or filtered. Shape depends on `event_type`. `null` when not configured.", 2903 ) 2904 event_type: str | None = Field( 2905 default=None, 2906 description='Platform event type that triggers this routine, e.g. `"agentroutine.invoked"`. `null` for schedule-only routines.', 2907 ) 2908 handler_type: str | None = Field( 2909 default=None, 2910 description='Execution strategy for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`.', 2911 ) 2912 id: str = Field(..., description="Routine ID (`arn_...`).") 2913 last_applied_template_config: str | None = Field( 2914 default=None, 2915 description="ID of the AgentRoutineTemplate Config this routine was last provisioned or updated from (`cfg_...`). `null` for hand-built routines.", 2916 ) 2917 lookup_key: str | None = Field( 2918 default=None, 2919 description="Unique human-readable key used to look up this routine without knowing its ID. `null` when not set.", 2920 ) 2921 message_policy: MessagePolicy | None = Field( 2922 default=None, 2923 description="Visibility and explicit recipient selection for messages emitted by this routine.", 2924 ) 2925 metadata: dict[str, Any] | None = Field( 2926 default=None, 2927 description="Arbitrary key-value metadata attached to this routine. `null` when not set.", 2928 ) 2929 name: str | None = Field(default=None, description="Human-readable name for the routine.") 2930 preset_config: PresetConfig | None = Field( 2931 default=None, 2932 description='Resolved preset configuration when `handler_type` is `"preset"`. `null` for other handler types.', 2933 ) 2934 preset_name: str | None = Field( 2935 default=None, 2936 description='Name of the preset invoked when `handler_type` is `"preset"`. `null` for other handler types.', 2937 ) 2938 schedule: str | None = Field( 2939 default=None, 2940 description="Cron expression controlling when the routine fires on a schedule. `null` for event-only routines.", 2941 ) 2942 script: str | None = Field( 2943 default=None, 2944 description='Inline script body executed when `handler_type` is `"script"`. `null` for other handler types.', 2945 ) 2946 status: str | None = Field( 2947 default=None, 2948 description='Lifecycle status of the routine. One of `"draft"`, `"active"`, or `"paused"`. Only `"active"` routines respond to triggers.', 2949 ) 2950 steps: list[dict[str, Any]] | None = Field( 2951 default=None, 2952 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).', 2953 ) 2954 trigger_context: str | None = Field( 2955 default=None, 2956 description='Execution context in which runs are created. One of `"event"` (background job) or `"chat_session"` (interactive session). Defaults to `"event"`.', 2957 ) 2958 updated_at: datetime | None = Field( 2959 default=None, description="When this routine was last updated (ISO 8601)." 2960 ) 2961 user: str | None = Field( 2962 default=None, 2963 description="Optional co-owner user (`usr_...`). When set, that user shares view/modify/delete authority on this routine without administering the parent agent. `null` when not set. Never inferred from the caller only present when explicitly provided on create/update.", 2964 ) 2965 2966 2967class AgentRoutineListResponse(BaseModel): 2968 """ 2969 List of agent routine objects belonging to a given agent. 2970 """ 2971 2972 data: list[AgentRoutine] = Field(..., description="Array of agent routine objects.") 2973 2974 2975class AgentRoutineRunDelivery(BaseModel): 2976 """ 2977 Normalized destination and status for an agent routine run's final-result delivery. 2978 """ 2979 2980 delivered_at: datetime | None = Field( 2981 default=None, description="When delivery completed successfully (ISO 8601)." 2982 ) 2983 delivered_message: str | None = Field( 2984 default=None, description="ID of the message created by a successful delivery (`msg_...`)." 2985 ) 2986 last_error: str | None = Field( 2987 default=None, 2988 description="Stable public error code for the most recent failed delivery attempt.", 2989 ) 2990 message: str | None = Field( 2991 default=None, description="Source message ID (`msg_...`) when the delivery is a reply." 2992 ) 2993 status: Literal["not_requested", "pending", "delivered", "failed"] = Field( 2994 ..., description="Current delivery lifecycle status." 2995 ) 2996 thread: str | None = Field( 2997 default=None, description="Destination thread ID (`thr_...`) when delivery was requested." 2998 ) 2999 type: Literal["none", "thread", "reply"] = Field(..., description="Normalized delivery mode.") 3000 3001 3002class AgentRoutineRun(BaseModel): 3003 """ 3004 A single execution of an agent routine, capturing its status, inputs, outputs, and timing. 3005 """ 3006 3007 acl: Acl | None = Field( 3008 default=None, 3009 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.", 3010 ) 3011 agent: str | None = Field( 3012 default=None, description="ID of the agent that owns the parent routine (`agi_...`)." 3013 ) 3014 app: str | None = Field( 3015 default=None, description="Application that scopes this run (`dap_...`)." 3016 ) 3017 created_at: datetime | None = Field( 3018 default=None, description="When this run was created (ISO 8601)." 3019 ) 3020 delivery: AgentRoutineRunDelivery | None = Field( 3021 default=None, 3022 description="Normalized final-result delivery destination and its current delivery status.", 3023 ) 3024 duration_ms: int | None = Field( 3025 default=None, 3026 description="Total wall-clock time the run took to execute, in milliseconds. `null` while the run is still in progress.", 3027 ) 3028 event_id: str | None = Field( 3029 default=None, 3030 description="Identifier of the platform event that triggered this run. `null` for manually invoked runs.", 3031 ) 3032 id: str = Field(..., description="Routine run ID (`arr_...`).") 3033 metadata: dict[str, Any] | None = Field( 3034 default=None, 3035 description="Arbitrary key-value metadata attached to this run. Empty object when no metadata was set.", 3036 ) 3037 participants: dict[str, Any] | None = Field( 3038 default=None, 3039 description="Invoke-time map of symbolic participant references to agent IDs. `null` when no participants were supplied.", 3040 ) 3041 payload: dict[str, Any] | None = Field( 3042 default=None, 3043 description="Input payload delivered to the routine when this run was triggered. Empty object when no payload was provided.", 3044 ) 3045 result: dict[str, Any] | None = Field( 3046 default=None, 3047 description="Output produced by the routine after execution. `null` while the run has not yet completed.", 3048 ) 3049 routine: str | None = Field( 3050 default=None, description="ID of the parent routine that produced this run (`arn_...`)." 3051 ) 3052 status: str | None = Field( 3053 default=None, 3054 description='Current execution status. One of `"pending"`, `"running"`, `"completed"`, `"failed"`, `"skipped"`, or `"cancelled"`.', 3055 ) 3056 structured_response: dict[str, Any] | None = Field( 3057 default=None, 3058 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.", 3059 ) 3060 updated_at: datetime | None = Field( 3061 default=None, description="When this run was last updated (ISO 8601)." 3062 ) 3063 worker: WorkerStatus | None = Field( 3064 default=None, 3065 description="Background worker status. `null` when no worker job is associated with this run.", 3066 ) 3067 3068 3069class AgentRoutineRunListResponse(BaseModel): 3070 """ 3071 Cursor-paginated list of agent routine run objects, ordered by creation time descending. 3072 """ 3073 3074 after_cursor: str | None = Field( 3075 default=None, 3076 description="Opaque cursor to pass as the after-cursor parameter to fetch the next page of runs. `null` when no later results exist.", 3077 ) 3078 before_cursor: str | None = Field( 3079 default=None, 3080 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.", 3081 ) 3082 data: list[AgentRoutineRun] = Field( 3083 ..., description="Array of agent routine run objects for the current page." 3084 ) 3085 3086 3087class AgentSchedule(BaseModel): 3088 """ 3089 A scheduled task created by an agent. Supports one-time and recurring (cron-based) execution patterns. 3090 """ 3091 3092 agent: str | None = Field( 3093 default=None, description="ID of the agent that owns this schedule (`agi_...`)." 3094 ) 3095 app: str | None = Field( 3096 default=None, description="ID of the application the schedule belongs to (`dap_...`)." 3097 ) 3098 created_at: datetime | None = Field( 3099 default=None, description="When the schedule was created (ISO 8601)." 3100 ) 3101 cron_expression: str | None = Field( 3102 default=None, 3103 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.', 3104 ) 3105 id: str = Field(..., description="Schedule ID (`asc_...`).") 3106 instructions: str | None = Field( 3107 default=None, 3108 description="The task description the agent will execute when this schedule fires.", 3109 ) 3110 last_run_at: datetime | None = Field( 3111 default=None, 3112 description="UTC datetime of the most recent successful execution. `null` if the schedule has never run.", 3113 ) 3114 max_runs: int | None = Field( 3115 default=None, 3116 description='Maximum number of times a recurring schedule may fire before automatically transitioning to `"completed"`. `null` means no limit.', 3117 ) 3118 metadata: dict[str, Any] | None = Field( 3119 default=None, 3120 description="Arbitrary key-value pairs attached to the schedule by the agent. Not interpreted by the platform.", 3121 ) 3122 next_run_at: datetime | None = Field( 3123 default=None, 3124 description="UTC datetime of the next planned execution. `null` if the schedule has completed, been cancelled, or has not yet been computed.", 3125 ) 3126 run_count: int | None = Field( 3127 default=None, description="Total number of times this schedule has fired." 3128 ) 3129 schedule_type: str | None = Field( 3130 default=None, 3131 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.', 3132 ) 3133 scheduled_at: datetime | None = Field( 3134 default=None, 3135 description='The exact UTC datetime at which a one-time schedule fires. Present only when `schedule_type` is `"once"`. `null` for recurring schedules.', 3136 ) 3137 status: str | None = Field( 3138 default=None, 3139 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).', 3140 ) 3141 thread: str | None = Field( 3142 default=None, 3143 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.", 3144 ) 3145 timezone: str | None = Field( 3146 default=None, 3147 description='IANA timezone name used to interpret the cron expression or `scheduled_at` (e.g. `"America/New_York"`). Defaults to `"Etc/UTC"`.', 3148 ) 3149 updated_at: datetime | None = Field( 3150 default=None, description="When the schedule was last modified (ISO 8601)." 3151 ) 3152 3153 3154class AgentSession(BaseModel): 3155 """ 3156 A durable agent session record representing a single AI task execution. Tracks status, trajectory, result, and any inbox messages delivered to the session. 3157 """ 3158 3159 agent: str | None = Field( 3160 default=None, description="ID of the agent that owns this session (`agi_...`)." 3161 ) 3162 completed_at: datetime | None = Field( 3163 default=None, 3164 description='When the session reached a terminal state (`"completed"`, `"failed"`, or `"cancelled"`). `null` if still in progress.', 3165 ) 3166 created_at: datetime | None = Field( 3167 default=None, description="When the session was created (ISO 8601)." 3168 ) 3169 error: str | None = Field( 3170 default=None, 3171 description='Human-readable error message describing why the session failed. `null` unless `status` is `"failed"`.', 3172 ) 3173 id: str = Field(..., description="Session ID (`ase_...`).") 3174 inbox: list[dict[str, Any]] | None = Field( 3175 default=None, 3176 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`.', 3177 ) 3178 instructions: str | None = Field( 3179 default=None, description="The task the agent is instructed to perform in this session." 3180 ) 3181 is_system_session: bool | None = Field( 3182 default=None, 3183 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.", 3184 ) 3185 max_runs_per_turn: int | None = Field( 3186 default=None, 3187 description="Maximum number of tool calls the agent may make within a single turn. Defaults to `25`.", 3188 ) 3189 max_tokens: int | None = Field( 3190 default=None, 3191 description="Maximum number of tokens the session may consume across all turns before being terminated. Defaults to `20000`.", 3192 ) 3193 max_turns: int | None = Field( 3194 default=None, 3195 description="Maximum number of agent turns (LLM calls) allowed before the session is forcibly terminated. Defaults to `100`.", 3196 ) 3197 metadata: dict[str, Any] | None = Field( 3198 default=None, 3199 description="Arbitrary key-value pairs attached to the session. Not interpreted by the platform.", 3200 ) 3201 name: str | None = Field( 3202 default=None, 3203 description="Optional human-readable label for the session. `null` when not set.", 3204 ) 3205 result: dict[str, Any] | None = Field( 3206 default=None, 3207 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.", 3208 ) 3209 started_at: datetime | None = Field( 3210 default=None, description='When the session began executing. `null` if still `"pending"`.' 3211 ) 3212 status: str | None = Field( 3213 default=None, 3214 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).', 3215 ) 3216 trajectory: str | None = Field( 3217 default=None, 3218 description="ID of the trajectory that records the full message history for this session (`trj_...`). `null` until the session has started.", 3219 ) 3220 3221 3222class AgentSessionListResponse(BaseModel): 3223 """ 3224 Paginated list response containing an array of agent session objects. 3225 """ 3226 3227 data: list[AgentSession] = Field( 3228 ..., description="Array of agent session objects for the current page." 3229 ) 3230 3231 3232class AgentSkill(BaseModel): 3233 """ 3234 A skill enabled on an agent, linking the agent to a skill configuration. Controls which capabilities the agent has access to. 3235 """ 3236 3237 agent: str | None = Field( 3238 default=None, description="ID of the agent this skill is attached to (`agi_...`)." 3239 ) 3240 app: str | None = Field( 3241 default=None, description="ID of the application this skill belongs to (`dap_...`)." 3242 ) 3243 config: str | None = Field( 3244 default=None, 3245 description="ID of the root skill config record that defines this skill's behavior (`cfg_...`).", 3246 ) 3247 created_at: datetime | None = Field( 3248 default=None, description="When the skill was added to the agent (ISO 8601)." 3249 ) 3250 id: str = Field(..., description="Skill ID (`ask_...`).") 3251 instruction: str | None = Field( 3252 default=None, 3253 description="Optional instruction text that overrides the default skill instructions for this specific agent. `null` when no override is set.", 3254 ) 3255 last_applied_template_config: str | None = Field( 3256 default=None, 3257 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.", 3258 ) 3259 metadata: dict[str, Any] | None = Field( 3260 default=None, 3261 description="Arbitrary key-value pairs attached to the skill. Not interpreted by the platform.", 3262 ) 3263 status: str | None = Field( 3264 default=None, 3265 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.', 3266 ) 3267 updated_at: datetime | None = Field( 3268 default=None, description="When the skill was last modified (ISO 8601)." 3269 ) 3270 3271 3272class AgentSkillList(BaseModel): 3273 """ 3274 Paginated list response containing an array of agent skill objects. 3275 """ 3276 3277 data: list[AgentSkill] = Field( 3278 ..., description="Array of agent skill objects for the current page." 3279 ) 3280 3281 3282class AgentTool(BaseModel): 3283 """ 3284 A tool attached to an agent, defining a capability the agent can invoke during a conversation or task run. 3285 """ 3286 3287 model_config = ConfigDict(populate_by_name=True) 3288 3289 agent: str | None = Field( 3290 default=None, description="ID of the agent this tool belongs to (`agi_...`)." 3291 ) 3292 app: str | None = Field( 3293 default=None, description="ID of the application that owns this tool (`dap_...`)." 3294 ) 3295 async_: bool | None = Field( 3296 default=None, 3297 alias="async", 3298 description="`true` when the tool executes asynchronously and returns a task handle rather than an immediate result.", 3299 ) 3300 builtin_tool_config: dict[str, Any] | None = Field( 3301 default=None, 3302 description='Provider-specific configuration for the built-in tool. Present only when `kind` is `"builtin"`. Shape varies by `builtin_tool_key`.', 3303 ) 3304 builtin_tool_key: str | None = Field( 3305 default=None, 3306 description='Registry key identifying the built-in tool implementation. Present only when `kind` is `"builtin"`.', 3307 ) 3308 config: str | None = Field( 3309 default=None, 3310 description="ID of the config record (`cfg_...`) containing this tool's full configuration. `null` for inline-only tools.", 3311 ) 3312 created_at: datetime | None = Field( 3313 default=None, description="When the tool was created (ISO 8601)." 3314 ) 3315 description: str | None = Field( 3316 default=None, 3317 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.', 3318 ) 3319 handler_type: str | None = Field( 3320 default=None, 3321 description='Execution handler type. One of `"http"`, `"script"`, or `"builtin"`.', 3322 ) 3323 id: str = Field(..., description="Tool ID (`atl_...`).") 3324 instruction: str | None = Field( 3325 default=None, 3326 description="Optional system-level instruction appended to the agent prompt when this tool is active.", 3327 ) 3328 kind: str | None = Field( 3329 default=None, description='Tool kind. One of `"builtin"`, `"custom"`, or `"mcp"`.' 3330 ) 3331 last_applied_template_config: str | None = Field( 3332 default=None, 3333 description="ID of the AgentToolTemplate config (`cfg_...`) this tool was last provisioned or updated from. `null` for manually created tools.", 3334 ) 3335 lookup_key: str | None = Field( 3336 default=None, 3337 description="Stable, user-defined identifier for this tool within the agent. Unique per agent.", 3338 ) 3339 metadata: dict[str, Any] | None = Field( 3340 default=None, 3341 description="Arbitrary key-value metadata attached to the tool. Not interpreted by the platform.", 3342 ) 3343 name: str | None = Field( 3344 default=None, 3345 description='Human-readable name of the tool as exposed to the LLM. Resolved from the built-in registry for `kind: "builtin"` tools.', 3346 ) 3347 name_prefix: str | None = Field( 3348 default=None, 3349 description="Per-instance namespace prepended to LLM-facing tool names for built-in tools that support multiple instances per agent. `null` when not applicable.", 3350 ) 3351 parameters: dict[str, Any] | None = Field( 3352 default=None, 3353 description="JSON Schema object describing the tool's input parameters as presented to the LLM.", 3354 ) 3355 parameters_config: str | None = Field( 3356 default=None, 3357 description="ID of the config record (`cfg_...`) storing the tool's parameter schema. `null` when parameters are defined inline.", 3358 ) 3359 status: str | None = Field( 3360 default=None, description='Current status of the tool. One of `"active"` or `"disabled"`.' 3361 ) 3362 updated_at: datetime | None = Field( 3363 default=None, description="When the tool was last modified (ISO 8601)." 3364 ) 3365 3366 3367class AgentToolListResponse(BaseModel): 3368 """ 3369 Paginated list response containing the tools attached to an agent. 3370 """ 3371 3372 data: list[AgentTool] = Field( 3373 ..., description="Array of agent tool objects returned for the current request." 3374 ) 3375 3376 3377class AgentUpgradeFieldChange(BaseModel): 3378 """ 3379 One field-level diff entry within an agent upgrade change, describing how a single field will change. 3380 `baseline` and `locally_edited` are populated only for `agent_base` entries; child resource entries (tools, routines, skills, computers) carry only `field`, `old`, and `new`. 3381 """ 3382 3383 baseline: Any | None = Field( 3384 default=None, 3385 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).", 3386 ) 3387 field: str = Field( 3388 ..., description='Name of the field that will change, e.g. `"name"` or `"identity"`.' 3389 ) 3390 locally_edited: bool | None = Field( 3391 default=None, 3392 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.", 3393 ) 3394 new: Any | None = Field( 3395 default=None, 3396 description="Incoming value the field will be set to after the upgrade (string, number, boolean, or `null`).", 3397 ) 3398 old: Any | None = Field( 3399 default=None, 3400 description="Current value of the field before the upgrade (string, number, boolean, or `null`).", 3401 ) 3402 3403 3404class AgentUpgradeChange(BaseModel): 3405 """ 3406 One child-resource change produced by an agent upgrade, describing the action to be taken on a single resource. 3407 """ 3408 3409 action: str = Field( 3410 ..., 3411 description='The operation that will be performed. One of `"add"`, `"update"`, `"remove"`, or `"noop"`.', 3412 ) 3413 description: str | None = Field( 3414 default=None, 3415 description="Description of the child resource this change touches, when one is set. `null` when no description is available.", 3416 ) 3417 field_changes: list[AgentUpgradeFieldChange] | None = Field( 3418 default=None, 3419 description='Field-level diff entries for this change. Populated only when `action` is `"update"`; empty or absent for `add`, `remove`, and `noop` entries.', 3420 ) 3421 id: str | None = Field( 3422 default=None, 3423 description="Public ID of the existing resource being updated or removed (e.g. `atl_...`, `arn_...`). `null` for `add` entries.", 3424 ) 3425 key: str | None = Field( 3426 default=None, 3427 description="Lookup key of the resource derived from its source template. `null` when the template has no lookup key.", 3428 ) 3429 name: str | None = Field( 3430 default=None, 3431 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.", 3432 ) 3433 parent_template_config: UpgradeTemplateSummary = Field( 3434 ..., 3435 description="Summary of the parent AgentTemplate config (`cfg_...`) being applied in this upgrade.", 3436 ) 3437 resource: dict[str, Any] | None = Field( 3438 default=None, 3439 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.", 3440 ) 3441 resource_type: str = Field( 3442 ..., 3443 description='Type of the child resource being changed. One of `"agent"`, `"tool"`, `"routine"`, `"skill"`, or `"computer"`.', 3444 ) 3445 source_template_config: UpgradeTemplateSummary | None = Field( 3446 default=None, 3447 description="Summary of the specific child template config (`cfg_...`) that defines this resource. `null` when no source template is resolvable.", 3448 ) 3449 3450 3451class AgentUpgradeSummary(BaseModel): 3452 """ 3453 Aggregate counts of each change type produced by an agent upgrade diff. 3454 """ 3455 3456 adds: int = Field( 3457 ..., description="Number of child resources that will be created by this upgrade." 3458 ) 3459 noops: int = Field( 3460 ..., description="Number of child resources with no changes in this upgrade." 3461 ) 3462 removes: int = Field( 3463 ..., description="Number of child resources that will be removed by this upgrade." 3464 ) 3465 updates: int = Field( 3466 ..., description="Number of child resources that will be updated by this upgrade." 3467 ) 3468 3469 3470class AgentUpgradeResult(BaseModel): 3471 """ 3472 The computed diff and outcome of an agent upgrade operation, including the full list of per-resource changes. 3473 """ 3474 3475 changes: list[AgentUpgradeChange] = Field( 3476 ..., 3477 description="Ordered list of per-resource changes that will be (or were) applied by this upgrade.", 3478 ) 3479 dry_run: bool = Field( 3480 ..., 3481 description="`true` when the request was a dry run and no changes were persisted to the agent.", 3482 ) 3483 mode: str = Field( 3484 ..., 3485 description='Upgrade mode that was used. One of `"full"` (apply all changes) or `"review"` (require fingerprint confirmation).', 3486 ) 3487 review_fingerprint: str | None = Field( 3488 default=None, 3489 description='Opaque fingerprint of the computed diff. Pass this value back as `review_fingerprint` to confirm and apply a `"review"` mode upgrade.', 3490 ) 3491 status: str = Field( 3492 ..., 3493 description='Outcome of the upgrade. `"ready"` for a dry-run (no changes applied); `"upgraded"` when the upgrade was committed.', 3494 ) 3495 summary: AgentUpgradeSummary = Field( 3496 ..., 3497 description="Aggregate counts of adds, updates, removes, and noops across all child resources.", 3498 ) 3499 3500 3501class AgentUpgradeResponse(BaseModel): 3502 """ 3503 Response returned by the agent upgrade endpoint, combining the updated agent, its source Solution and template, and the full upgrade diff. 3504 """ 3505 3506 agent: Agent | None = Field( 3507 default=None, 3508 description="The agent after the upgrade has been applied. `null` for dry-run requests where no changes were persisted.", 3509 ) 3510 solution: SolutionSummary = Field( 3511 ..., description="Summary of the parent Solution the agent was upgraded from." 3512 ) 3513 template: UpgradeTemplateSummary = Field( 3514 ..., 3515 description="Summary of the AgentTemplate config (`cfg_...`) that was selected for this upgrade.", 3516 ) 3517 upgrade_result: AgentUpgradeResult = Field( 3518 ..., 3519 description="Full upgrade diff including status, mode, dry-run flag, summary counts, and per-resource change list.", 3520 ) 3521 3522 3523class SolutionCategorySummary(BaseModel): 3524 """ 3525 A solution category that organizes solutions in the catalog, identified by a stable key and optionally nested under a parent category. 3526 """ 3527 3528 created_at: datetime | None = Field( 3529 default=None, 3530 description="When this category was first created (ISO 8601). `null` for system-built-in categories.", 3531 ) 3532 description: str | None = Field( 3533 default=None, 3534 description="Short prose description of what solutions in this category do. `null` when not configured.", 3535 ) 3536 id: str = Field(..., description="Solution category config ID (`cfg_...`).") 3537 key: str = Field( 3538 ..., 3539 description="Stable, human-readable key for this category, referenced by solutions via `category_keys`.", 3540 ) 3541 kind: str = Field(..., description='Resource type identifier. Always `"SolutionCategory"`.') 3542 lookup_key: str | None = Field( 3543 default=None, description="Lookup key of the underlying config record. `null` when not set." 3544 ) 3545 metadata: dict[str, Any] | None = Field( 3546 default=None, 3547 description="Arbitrary key-value metadata attached to this category by the publisher.", 3548 ) 3549 name: str | None = Field( 3550 default=None, description="Display name shown to users. `null` when not configured." 3551 ) 3552 org: str | None = Field( 3553 default=None, 3554 description="Organization ID (`org_...`) that owns this category. `null` for system-scoped categories.", 3555 ) 3556 owners: list[str] = Field( 3557 ..., 3558 description='Scopes under which this category is visible. Possible values are `"system"` (available to all apps) and `"org"` (scoped to the viewer\'s organization).', 3559 ) 3560 parent_key: str | None = Field( 3561 default=None, 3562 description="Key of the parent `SolutionCategory`, enabling a hierarchy. `null` for top-level categories.", 3563 ) 3564 sort_order: int | None = Field( 3565 default=None, 3566 description="Numeric hint for ordering categories in a list. Lower values sort first. `null` when not configured.", 3567 ) 3568 updated_at: datetime | None = Field( 3569 default=None, 3570 description="When this category was last modified (ISO 8601). `null` for system-built-in categories.", 3571 ) 3572 virtual_path: str | None = Field( 3573 default=None, 3574 description="Virtual path of the underlying config record. `null` when not set.", 3575 ) 3576 3577 3578class SolutionCategoryListResponse(BaseModel): 3579 """ 3580 Paginated list of solution category summaries. Use `page` and `page_size` to navigate pages of results. 3581 """ 3582 3583 data: list[SolutionCategorySummary] = Field( 3584 ..., description="Array of solution category summary objects for the current page." 3585 ) 3586 has_next: bool = Field(..., description="`true` when a subsequent page of results exists.") 3587 has_prev: bool = Field(..., description="`true` when a previous page of results exists.") 3588 page: int = Field(..., description="Current page number (1-indexed).") 3589 page_size: int = Field(..., description="Maximum number of entries returned per page.") 3590 total_entries: int = Field( 3591 ..., description="Total number of distinct solution categories across all pages." 3592 ) 3593 total_pages: int = Field( 3594 ..., description="Total number of pages available at the current `page_size`." 3595 ) 3596 3597 3598class SolutionDependentAgent(BaseModel): 3599 """ 3600 A brief representation of an agent that references at least one config bundled by a Solution, included in the dependents preview response. 3601 """ 3602 3603 id: str = Field(..., description="Agent ID (`agi_...`).") 3604 name: str | None = Field( 3605 default=None, 3606 description="Human-readable display name of the agent. `null` when no name has been set.", 3607 ) 3608 3609 3610class SolutionDependentsResponse(BaseModel): 3611 """ 3612 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. 3613 """ 3614 3615 dependent_agent_count: int = Field( 3616 ..., 3617 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.", 3618 ) 3619 dependent_agents: list[SolutionDependentAgent] = Field( 3620 ..., 3621 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.", 3622 ) 3623 preserved_config_count: int = Field( 3624 ..., 3625 description="Number of bundled configs that would be detached and preserved rather than deleted, because at least one live agent still references them.", 3626 ) 3627 3628 3629class SolutionDiffReference(BaseModel): 3630 """ 3631 A reference from another config to an orphaned entry in a solution upgrade diff, explaining why the orphan cannot be safely removed. 3632 """ 3633 3634 id: str = Field(..., description="ID of the referencing config (`cfg_...`).") 3635 kind: str = Field( 3636 ..., 3637 description='Object type of the referencing config, e.g. `"Automation"` or `"Template"`.', 3638 ) 3639 lookup_key: str | None = Field( 3640 default=None, 3641 description="Human-readable stable identifier of the referencing config. `null` if not assigned.", 3642 ) 3643 reason: str = Field( 3644 ..., description="Explanation of how the referencing config depends on the orphaned entry." 3645 ) 3646 3647 3648class SolutionDiffEntry(BaseModel): 3649 """ 3650 A single config entry in a solution upgrade diff, describing what action will be taken on a specific config key. 3651 """ 3652 3653 action: str = Field( 3654 ..., 3655 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).', 3656 ) 3657 content_changed: bool = Field( 3658 ..., 3659 description="`true` if the config content differs between the existing and incoming solution versions.", 3660 ) 3661 id: str | None = Field( 3662 default=None, 3663 description="Config ID (`cfg_...`) if this entry corresponds to an existing config record. `null` for new additions.", 3664 ) 3665 key: str = Field( 3666 ..., description="Stable string key identifying this config entry within the solution." 3667 ) 3668 kind: str | None = Field( 3669 default=None, 3670 description='Config object type, e.g. `"Automation"` or `"Template"`. `null` if not yet known.', 3671 ) 3672 lookup_key: str | None = Field( 3673 default=None, 3674 description="Human-readable stable identifier for this config. `null` if not assigned.", 3675 ) 3676 mime_type_changed: bool = Field( 3677 ..., description="`true` if the MIME type of the config changed between versions." 3678 ) 3679 referenced_by: list[SolutionDiffReference] | None = Field( 3680 default=None, 3681 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.", 3682 ) 3683 relative_path_changed: bool = Field( 3684 ..., 3685 description="`true` if the relative path of the config within the solution changed between versions.", 3686 ) 3687 role: str = Field( 3688 ..., 3689 description="Role of this config within the solution. Indicates whether it is a primary config or a dependency.", 3690 ) 3691 virtual_path: str | None = Field( 3692 default=None, 3693 description="Hierarchical path of this config in the config tree. `null` if not assigned.", 3694 ) 3695 3696 3697class SolutionDiffSummary(BaseModel): 3698 """ 3699 Aggregate counts of each action type across all entries in a solution upgrade diff. 3700 """ 3701 3702 adds: int = Field( 3703 ..., description="Number of config entries that will be newly created by this upgrade." 3704 ) 3705 deletes: int = Field( 3706 ..., description="Number of config entries that will be deleted as part of the upgrade." 3707 ) 3708 noops: int = Field( 3709 ..., 3710 description="Number of config entries that are already up to date and require no changes.", 3711 ) 3712 orphans: int = Field( 3713 ..., 3714 description="Number of config entries present in the existing solution that are absent from the incoming version and have no external references blocking removal.", 3715 ) 3716 referenced_orphans: int = Field( 3717 ..., 3718 description="Number of orphaned config entries that cannot be removed because other configs still reference them.", 3719 ) 3720 updates: int = Field( 3721 ..., description="Number of config entries that exist and will be updated with new content." 3722 ) 3723 3724 3725class SolutionImportWarning(BaseModel): 3726 """ 3727 A non-fatal finding surfaced by a Solution import. The import proceeds despite warnings; validation callers (dry-run) can choose to treat them as failures. 3728 """ 3729 3730 code: str = Field( 3731 ..., 3732 description='Machine-readable warning code. `"setup_requirements_dropped"`: a template or config body declares catalog-DSL `setup_requirements` that direct import does not convert installs read only `setup_actions`, so those setup steps would never surface.', 3733 ) 3734 message: str = Field( 3735 ..., description="Human-readable explanation of the warning and how to resolve it." 3736 ) 3737 path: str = Field( 3738 ..., 3739 description="Which bundle entry the warning is about, as `<slot>[<index>] (<relative_path>)`.", 3740 ) 3741 3742 3743class SolutionImportResult(BaseModel): 3744 """ 3745 The machine-readable outcome of a Solution import attempt, indicating whether the import succeeded or requires an upgrade flow to resolve a version conflict. 3746 """ 3747 3748 code: str | None = Field( 3749 default=None, 3750 description='Machine-readable conflict code present when `status` is `"conflict"`, identifying the specific conflict reason. `null` when `status` is `"ready"`.', 3751 ) 3752 dry_run: bool = Field( 3753 ..., 3754 description="Whether this result was produced by a dry-run check. `true` when the import was validated without persisting any changes.", 3755 ) 3756 existing_solution_version: str | None = Field( 3757 default=None, 3758 description="Semver string of the Solution version already present in the library. `null` when no prior version exists.", 3759 ) 3760 incoming_solution_version: str | None = Field( 3761 default=None, 3762 description="Semver string of the Solution version in the bundle being imported. `null` when the bundle does not declare a version.", 3763 ) 3764 message: str | None = Field( 3765 default=None, 3766 description="Human-readable description of the import status or conflict reason, suitable for display in a confirmation dialog. `null` when no detail is available.", 3767 ) 3768 status: str = Field( 3769 ..., 3770 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.', 3771 ) 3772 upgrade_required: bool = Field( 3773 ..., 3774 description='Whether the caller must invoke the dedicated upgrade flow to complete the import. Mirrors `status == "conflict"` as a convenience boolean.', 3775 ) 3776 warnings: list[SolutionImportWarning] | None = Field( 3777 default=None, 3778 description="Non-fatal findings the import proceeded despite (present on real imports and dry-runs alike; defaults to an empty array). Dry-run validation callers should surface these or treat them as failures before applying the real import.", 3779 ) 3780 3781 3782class SolutionImportResponse(BaseModel): 3783 """ 3784 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. 3785 """ 3786 3787 created_at: str | None = Field( 3788 default=None, description="When the Solution config record was first created (ISO 8601)." 3789 ) 3790 id: str = Field(..., description="Solution config ID (`cfg_...`).") 3791 import_result: SolutionImportResult = Field( 3792 ..., 3793 description="Structured outcome of the import, including status, conflict details, and version information.", 3794 ) 3795 installed_configs: list[InstalledConfigEntry] | None = Field( 3796 default=None, 3797 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`.", 3798 ) 3799 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 3800 lookup_key: str | None = Field( 3801 default=None, 3802 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.", 3803 ) 3804 solution: SolutionSummary = Field( 3805 ..., 3806 description="Full summary of the imported Solution, in the same shape as the individual Solution retrieval endpoint.", 3807 ) 3808 updated_at: str | None = Field( 3809 default=None, description="When the Solution config record was last modified (ISO 8601)." 3810 ) 3811 virtual_path: str | None = Field( 3812 default=None, 3813 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.", 3814 ) 3815 3816 3817class SolutionInstallResponseWebhook(BaseModel): 3818 """ 3819 One-time connection details for a webhook-auth Automation install. 3820 """ 3821 3822 signing_secret: str 3823 url: str 3824 3825 3826class SolutionInstallResponse(BaseModel): 3827 """ 3828 The runtime resource provisioned by installing a Solution, along with a reference back to the source Solution config. 3829 """ 3830 3831 id: str = Field( 3832 ..., 3833 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.", 3834 ) 3835 kind: str = Field( 3836 ..., 3837 description='Type of the provisioned resource. One of `"Agent"`, `"Automation"`, `"AgentRoutine"`, `"AgentTool"`, `"AgentSkill"`, or `"AgentComputer"`.', 3838 ) 3839 lookup_key: str | None = Field( 3840 default=None, 3841 description="The `lookup_key` stamped on the provisioned resource. `null` for `AgentSkill`, which is a join record and does not carry a lookup key.", 3842 ) 3843 solution: str = Field( 3844 ..., 3845 description="Solution config ID (`cfg_...`) that was used as the source for this install.", 3846 ) 3847 webhook: SolutionInstallResponseWebhook | None = Field( 3848 default=None, 3849 description="One-time connection details for a webhook-auth Automation install.", 3850 ) 3851 3852 3853class SolutionInstance(BaseModel): 3854 """ 3855 A customer-keyed instance stamped from an installed solution template. 3856 """ 3857 3858 agent: str | None = Field( 3859 default=None, 3860 description="Materialized agent for this customer (`agi_...`). `null` for a row without an agent.", 3861 ) 3862 agent_name: str | None = Field( 3863 default=None, 3864 description="Human-readable display name of the materialized agent. `null` when no agent is visible.", 3865 ) 3866 attachment_ref: dict[str, Any] | None = Field( 3867 default=None, 3868 description="Opaque tagged reference to the deployment target. Consumers interpret its kind.", 3869 ) 3870 created_at: datetime = Field(..., description="When this instance was stamped.") 3871 customer_key: str = Field(..., description="Stable vendor-defined key for the customer.") 3872 customer_label: str | None = Field( 3873 default=None, 3874 description="Human-readable customer label. `null` when the vendor did not provide one.", 3875 ) 3876 id: str = Field(..., description="Solution instance ID (`sli_...`).") 3877 local_edit_count: int | None = Field( 3878 default=None, 3879 description="Count of local agent edits relative to the pinned template. `null` when unavailable.", 3880 ) 3881 pinned_template_version: str | None = Field( 3882 default=None, 3883 description="Pinned template version record (`cfv_...`). `null` when no version is pinned.", 3884 ) 3885 pinned_version_number: int | None = Field( 3886 default=None, 3887 description="Human-readable version number of the pinned template. `null` when unavailable.", 3888 ) 3889 solution_template_config: str = Field( 3890 ..., 3891 description="Installed solution template config that stamped this instance (`cfg_...`).", 3892 ) 3893 status: Literal["active", "archived"] = Field( 3894 ..., description="Lifecycle status of this stamped instance." 3895 ) 3896 updated_at: datetime = Field(..., description="When this instance was last updated.") 3897 3898 3899class SolutionInstanceListResponse(BaseModel): 3900 """ 3901 A forward cursor-paginated page of customer solution instances. 3902 """ 3903 3904 after_cursor: str | None = Field( 3905 default=None, 3906 description="Opaque cursor for the next page. `null` when this is the final page.", 3907 ) 3908 before_cursor: str | None = Field( 3909 default=None, description="Always `null`; this endpoint supports forward pagination only." 3910 ) 3911 data: list[SolutionInstance] = Field( 3912 ..., description="Customer solution instances in stable customer-key order." 3913 ) 3914 has_more: bool = Field(..., description="Whether another page exists after this one.") 3915 3916 3917class SolutionListResponse(BaseModel): 3918 """ 3919 A paginated collection of Solution summaries, with page metadata for navigating the result set. 3920 """ 3921 3922 data: list[SolutionSummary] = Field( 3923 ..., 3924 description="Array of Solution summary objects for the current page, in the order returned by the query.", 3925 ) 3926 has_next: bool = Field( 3927 ..., description="`true` when a subsequent page exists; `false` when this is the last page." 3928 ) 3929 has_prev: bool = Field( 3930 ..., description="`true` when a preceding page exists; `false` when this is the first page." 3931 ) 3932 page: int = Field(..., description="1-based index of the current page.") 3933 page_size: int = Field(..., description="Maximum number of results included per page.") 3934 total_entries: int = Field( 3935 ..., 3936 description="Total number of Solutions matching the query after deduplication by `solution_id` across owner scopes.", 3937 ) 3938 total_pages: int = Field( 3939 ..., description="Total number of pages available at the current `page_size`." 3940 ) 3941 3942 3943class SolutionTagSummary(BaseModel): 3944 """ 3945 A single solution tag definition, representing a named classification label that can be applied to solutions. 3946 """ 3947 3948 created_at: datetime | None = Field( 3949 default=None, 3950 description="When the solution tag was first created (ISO 8601). `null` if unavailable.", 3951 ) 3952 description: str | None = Field( 3953 default=None, 3954 description="Short prose explanation of what the tag represents. `null` if not provided.", 3955 ) 3956 id: str = Field(..., description="Solution tag config ID (`cfg_...`).") 3957 key: str = Field( 3958 ..., 3959 description="Stable string key for this tag, referenced by `Solution.tag_keys` to associate solutions with this tag.", 3960 ) 3961 kind: str = Field(..., description='Object type discriminator. Always `"SolutionTag"`.') 3962 lookup_key: str | None = Field( 3963 default=None, 3964 description="Human-readable stable identifier for this tag config, used for lookups and imports. `null` if not assigned.", 3965 ) 3966 metadata: dict[str, Any] | None = Field( 3967 default=None, 3968 description="Arbitrary key-value metadata attached to this tag. Empty object `{}` when no metadata is present.", 3969 ) 3970 name: str | None = Field( 3971 default=None, description="Human-readable display name for the tag. `null` if not yet set." 3972 ) 3973 org: str | None = Field( 3974 default=None, 3975 description="ID of the organization that owns this tag (`org_...`). `null` for system-scoped tags.", 3976 ) 3977 owners: list[str] = Field( 3978 ..., 3979 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).', 3980 ) 3981 sort_order: int | None = Field( 3982 default=None, 3983 description="Optional integer hint for ordering tags in UI lists. Lower values sort first. `null` if not set.", 3984 ) 3985 updated_at: datetime | None = Field( 3986 default=None, 3987 description="When the solution tag was last modified (ISO 8601). `null` if unavailable.", 3988 ) 3989 virtual_path: str | None = Field( 3990 default=None, 3991 description="Hierarchical path used to organize this tag in the config tree. `null` if not assigned.", 3992 ) 3993 3994 3995class SolutionTagListResponse(BaseModel): 3996 """ 3997 Paginated list of solution tag summaries returned by the list solution tags endpoint. 3998 """ 3999 4000 data: list[SolutionTagSummary] = Field( 4001 ..., description="Array of solution tag objects for the current page." 4002 ) 4003 has_next: bool = Field( 4004 ..., description="`true` if a subsequent page exists; `false` when this is the last page." 4005 ) 4006 has_prev: bool = Field( 4007 ..., description="`true` if a preceding page exists; `false` when this is the first page." 4008 ) 4009 page: int = Field(..., description="Current page number (1-indexed).") 4010 page_size: int = Field(..., description="Maximum number of results returned per page.") 4011 total_entries: int = Field( 4012 ..., 4013 description="Total number of distinct solution tags across all pages, after deduplication by key.", 4014 ) 4015 total_pages: int = Field( 4016 ..., description="Total number of pages available at the current `page_size`." 4017 ) 4018 4019 4020class SolutionUpgradeResult(BaseModel): 4021 """ 4022 The outcome of a solution upgrade operation, including the computed diff and conflict status. 4023 """ 4024 4025 changes: list[SolutionDiffEntry] = Field( 4026 ..., 4027 description="Ordered list of individual config change entries representing every add, update, noop, orphan, and delete in the diff.", 4028 ) 4029 code: str | None = Field( 4030 default=None, 4031 description='Machine-readable conflict code when `status` is `"conflict"`, e.g. `"review_required"`. `null` when there is no conflict.', 4032 ) 4033 dry_run: bool = Field( 4034 ..., 4035 description="`true` when the upgrade was computed without writing any changes; `false` when changes were committed.", 4036 ) 4037 existing_solution_version: str | None = Field( 4038 default=None, 4039 description="Version string of the currently installed solution, as declared in its manifest. `null` if no prior version is installed.", 4040 ) 4041 incoming_solution_version: str | None = Field( 4042 default=None, 4043 description="Version string of the incoming solution to be installed, as declared in its manifest. `null` if the incoming manifest omits a version.", 4044 ) 4045 message: str | None = Field( 4046 default=None, 4047 description="Human-readable description of the conflict or error. `null` when there is no conflict.", 4048 ) 4049 review_fingerprint: str | None = Field( 4050 default=None, 4051 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.", 4052 ) 4053 status: str = Field( 4054 ..., 4055 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.', 4056 ) 4057 summary: SolutionDiffSummary = Field( 4058 ..., description="Aggregate counts of each action type across all diff entries." 4059 ) 4060 version_change: str = Field( 4061 ..., 4062 description='Describes the nature of the version transition. One of `"upgrade"`, `"downgrade"`, `"same"`, or `"unknown"`.', 4063 ) 4064 4065 4066class SolutionUpgradeResponse(BaseModel): 4067 """ 4068 Response returned by the solution upgrade endpoint, containing the solution record, the full upgrade diff, and the resulting installed configs. 4069 """ 4070 4071 created_at: datetime | None = Field( 4072 default=None, 4073 description="When the solution config record was first created (ISO 8601). `null` if unavailable.", 4074 ) 4075 id: str = Field(..., description="Config ID of the solution record (`cfg_...`).") 4076 installed_configs: list[InstalledConfigEntry] | None = Field( 4077 default=None, 4078 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.", 4079 ) 4080 kind: str = Field(..., description='Object type discriminator. Always `"Solution"`.') 4081 lookup_key: str | None = Field( 4082 default=None, 4083 description="Human-readable stable identifier for this solution config. `null` if not assigned.", 4084 ) 4085 solution: SolutionSummary = Field( 4086 ..., 4087 description="Summary of the solution being upgraded, including its name, manifest metadata, and tag keys.", 4088 ) 4089 updated_at: datetime | None = Field( 4090 default=None, 4091 description="When the solution config record was last modified (ISO 8601). `null` if unavailable.", 4092 ) 4093 upgrade_result: SolutionUpgradeResult = Field( 4094 ..., 4095 description="Detailed result of the upgrade operation, including the computed diff and any conflict information.", 4096 ) 4097 virtual_path: str | None = Field( 4098 default=None, 4099 description="Hierarchical path of the solution in the config tree. `null` if not assigned.", 4100 )
class
AclGrant(pydantic.main.BaseModel):
17class AclGrant(BaseModel): 18 """ 19 A single access-control grant that pairs a principal with the set of actions it is allowed to perform. 20 """ 21 22 actions: list[str] = Field( 23 ..., 24 description='Array of action strings the principal is permitted to perform, e.g. `["read", "write"]`. Must contain at least one entry.', 25 ) 26 principal: str | None = Field( 27 default=None, 28 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"`.', 29 ) 30 principal_type: str = Field( 31 ..., 32 description='The kind of principal receiving the grant. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 33 )
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):
36class AclRemoveTarget(BaseModel): 37 """ 38 Identifies a principal to be removed from an access-control list. 39 """ 40 41 principal: str | None = Field( 42 default=None, 43 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"`.', 44 ) 45 principal_type: str = Field( 46 ..., 47 description='The kind of principal to remove. One of `"user"`, `"team"`, `"org"`, `"org_role"`, `"agent"`, or `"everyone"`.', 48 )
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):
51class Acl(BaseModel): 52 """ 53 An access-control list payload that supports either full replacement or targeted patch operations on a resource's grants. 54 """ 55 56 add: list[AclGrant] | None = Field( 57 default=None, 58 description="Patch mode: grants to add or merge into the existing list. Cannot be combined with `grants`.", 59 ) 60 grants: list[AclGrant] | None = Field( 61 default=None, 62 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`.", 63 ) 64 remove: list[AclRemoveTarget] | None = Field( 65 default=None, 66 description="Patch mode: principals whose grants should be removed from the existing list. Cannot be combined with `grants`.", 67 )
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):
70class ActivityFeedEntry(BaseModel): 71 """ 72 A single event record in an activity feed, capturing what happened, who caused it, and which resources were involved. 73 """ 74 75 agent: str | dict[str, Any] | None = Field( 76 default=None, 77 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.", 78 ) 79 app: str | None = Field( 80 default=None, 81 description="ID of the application that produced this entry (`dap_...`). `null` if not scoped to an app.", 82 ) 83 attachments: list[dict[str, Any]] | None = Field( 84 default=None, 85 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.', 86 ) 87 automation_run: str | None = Field( 88 default=None, 89 description="ID of the automation run that produced this entry (`atr_...`). `null` if not produced by an automation run.", 90 ) 91 content: str | None = Field( 92 default=None, 93 description="A longer explanation of the event rendered as Markdown. `null` if no additional content is available.", 94 ) 95 correlation_id: str | None = Field( 96 default=None, 97 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.", 98 ) 99 created_at: datetime | None = Field( 100 default=None, description="When this activity feed entry was created (ISO 8601)." 101 ) 102 id: str = Field(..., description="Activity feed entry ID (`afe_...`).") 103 kind: str | None = Field( 104 default=None, 105 description='The type of event this entry represents, e.g. `"agent_step"` or `"tool_call"`. Determines how `title`, `content`, and `attachments` should be interpreted.', 106 ) 107 level: str | None = Field( 108 default=None, 109 description='Severity level of the event. One of `"info"`, `"warning"`, or `"error"`. `null` if no severity is set.', 110 ) 111 metadata: dict[str, Any] | None = Field( 112 default=None, 113 description="Arbitrary key-value metadata stored on this entry. Returns an empty object when no metadata is set.", 114 ) 115 org: str | None = Field( 116 default=None, 117 description="ID of the organization this entry belongs to (`org_...`). `null` if not org-scoped.", 118 ) 119 routine_run: str | None = Field( 120 default=None, 121 description="ID of the agent routine run that produced this entry (`arr_...`). `null` if not produced by a routine run.", 122 ) 123 sandbox: str | None = Field( 124 default=None, 125 description="Identifier of the sandbox environment this entry was generated in. `null` in production contexts.", 126 ) 127 session_record: str | None = Field( 128 default=None, 129 description="ID of the agent session record this entry belongs to (`ase_...`). `null` if not part of an agent session.", 130 ) 131 team: str | None = Field( 132 default=None, 133 description="ID of the team this entry is associated with (`tem_...`). `null` if not team-scoped.", 134 ) 135 thread: str | None = Field( 136 default=None, 137 description="ID of the thread this entry is associated with (`thr_...`). `null` if not linked to a thread.", 138 ) 139 title: str | None = Field( 140 default=None, 141 description="A one-line human-readable summary of the event. `null` if the entry has no title.", 142 ) 143 updated_at: datetime | None = Field( 144 default=None, description="When this activity feed entry was last modified (ISO 8601)." 145 ) 146 user: str | dict[str, Any] | None = Field( 147 default=None, 148 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.", 149 )
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):
152class ActivityFeedEntryListResponse(BaseModel): 153 """ 154 A paginated list of activity feed entries returned by a feed query, with cursors for navigating backward and forward through results. 155 """ 156 157 after_cursor: str | None = Field( 158 default=None, 159 description="Opaque cursor to pass as `after` to retrieve the next page of entries. `null` when this is the last page.", 160 ) 161 before_cursor: str | None = Field( 162 default=None, 163 description="Opaque cursor to pass as `before` to retrieve the previous page of entries. `null` when this is the first page.", 164 ) 165 entries: list[ActivityFeedEntry] = Field( 166 ..., 167 description="Array of activity feed entry objects for the current page, ordered by time descending.", 168 ) 169 has_more: bool = Field( 170 ..., 171 description="Whether additional entries exist beyond the current page. When `true`, use `after_cursor` to fetch the next page.", 172 )
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):
175class Actor(BaseModel): 176 """ 177 The entity that authored a message, either a human user or an agent. 178 """ 179 180 alias: str | None = Field( 181 default=None, 182 description="Short handle or alias for the actor, used as an alternate display identifier. `null` if not configured.", 183 ) 184 id: str | None = Field( 185 default=None, 186 description='Composite actor identifier. Format is `"user-<usr_...>"` for human users or `"agent-<agi_...>"` for agents.', 187 ) 188 name: str | None = Field( 189 default=None, 190 description="Display name of the actor shown in the UI. `null` if no name is set.", 191 ) 192 profile_picture: ImageSource | None = Field( 193 default=None, 194 description="Profile picture for the actor. `null` if the actor has no profile picture.", 195 )
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):
198class UpgradeTemplateSummary(BaseModel): 199 """ 200 Compact summary of an AgentTemplate config referenced by an agent upgrade or source-solution response. 201 """ 202 203 created_at: datetime | None = Field( 204 default=None, description="When this template config was created (ISO 8601)." 205 ) 206 description: str | None = Field( 207 default=None, 208 description="Description of the template from the config body. `null` if the current version has no `description` field.", 209 ) 210 display_name: str | None = Field( 211 default=None, 212 description="Human-readable display name from the config body. `null` if the current version has no `display_name` field.", 213 ) 214 id: str = Field(..., description="Template config ID (`cfg_...`).") 215 kind: str = Field( 216 ..., description='Config kind identifier for this template (e.g. `"agent_tool_template"`).' 217 ) 218 lookup_key: str | None = Field( 219 default=None, 220 description="Stable lookup key assigned to this template config. `null` if no lookup key is set.", 221 ) 222 name: str | None = Field( 223 default=None, 224 description="Template name as stored in the config body. `null` if the current version has no `name` field.", 225 ) 226 updated_at: datetime | None = Field( 227 default=None, description="When this template config was last modified (ISO 8601)." 228 ) 229 virtual_path: str | None = Field( 230 default=None, 231 description="Virtual filesystem path for this template config. `null` if not set.", 232 )
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):
235class InstalledConfigEntry(BaseModel): 236 """ 237 A slim summary of a single config record created during an agent install transaction. Returned as an entry in `AgentCreateResponse.installed_configs`. 238 """ 239 240 id: str = Field(..., description="ID of the persisted config record (`cfg_...`).") 241 key: str = Field( 242 ..., 243 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.', 244 ) 245 kind: str = Field( 246 ..., 247 description='Type of config that was created. One of `"Skill"`, `"File"`, `"Script"`, `"AgentTemplate"`, or `"Config"`.', 248 ) 249 lookup_key: str | None = Field( 250 default=None, 251 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`.", 252 )
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
MessagePolicy(pydantic.main.BaseModel):
255class MessagePolicy(BaseModel): 256 """ 257 Controls visibility and canonical recipient selection for routine-emitted messages. 258 """ 259 260 recipients: list[str] | None = Field( 261 default=None, 262 description="Required and non-empty for private visibility. Sources are additive. Routine owner includes the agent owner and optional user co-owner.", 263 ) 264 visibility: str | None = Field( 265 default=None, description="Message visibility. One of `default` or `private`." 266 )
Controls visibility and canonical recipient selection for routine-emitted messages.
class
LLMConfig(pydantic.main.BaseModel):
269class LLMConfig(BaseModel): 270 """ 271 LLM invocation settings for a routine or chain step. When present, overrides the agent-level model selection. 272 """ 273 274 model: str | None = Field( 275 default=None, 276 description='Provider-prefixed model identifier for this routine or step, e.g. `"openrouter/anthropic/claude-sonnet-latest"`. When omitted, the agent\'s default model is used.', 277 )
LLM invocation settings for a routine or chain step. When present, overrides the agent-level model selection.
class
PresetConfig(pydantic.main.BaseModel):
280class PresetConfig(BaseModel): 281 """ 282 Configuration for a preset routine handler. Controls the agent's behavior, session persistence, and model selection for a given routine or chain step. 283 """ 284 285 instructions: str | None = Field( 286 default=None, 287 description="Custom task or behavior instructions for the preset (max 10,000 chars).", 288 ) 289 llm: LLMConfig | None = Field( 290 default=None, 291 description="LLM invocation settings (e.g. a `model` override for this routine/step).", 292 ) 293 session_mode: str | None = Field( 294 default=None, 295 description="Session mode: `stateless` (default, new session per trigger) or `session` (find-or-create a persistent session scoped by `session_scope`).", 296 ) 297 session_scope: str | None = Field( 298 default=None, 299 description="When `session_mode` is `session`, controls session scoping: `per_user` (default), `per_key`, `per_org`, or `global`.", 300 ) 301 structured_message_template_ids: list[str] | None = Field( 302 default=None, 303 description="IDs of structured message templates that constrain the agent's responses to predefined structured formats.", 304 )
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):
307class WorkerStatus(BaseModel): 308 """ 309 Execution state of the background worker processing a routine run. Reflects the current job status and retry progress. 310 """ 311 312 attempt: int = Field( 313 ..., 314 description="Number of times the worker has been attempted so far. `0` means the job has been enqueued but not yet started.", 315 ) 316 max_attempts: int = Field( 317 ..., 318 description='Maximum number of attempts the worker is allowed before the job is marked `"discarded"`.', 319 ) 320 status: str = Field( 321 ..., 322 description='Current execution state of the worker. One of `"queued"`, `"executing"`, `"retrying"`, `"completed"`, `"discarded"`, or `"cancelled"`.', 323 )
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):
326class MediaVariant(BaseModel): 327 """ 328 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. 329 """ 330 331 content_type: str | None = Field( 332 default=None, 333 description='MIME type of this variant\'s file (e.g., `"image/jpeg"`, `"video/mp4"`). `null` if the file is not loaded.', 334 ) 335 created_at: datetime | None = Field( 336 default=None, description="When this variant was created (ISO 8601)." 337 ) 338 file: str | None = Field( 339 default=None, 340 description="ID of the underlying storage file that backs this variant (`fil_...`).", 341 ) 342 filename: str | None = Field( 343 default=None, 344 description="Original filename of the uploaded file for this variant. `null` if the file is not loaded.", 345 ) 346 height: int | None = Field( 347 default=None, description="Height of this variant in pixels. `null` if not recorded." 348 ) 349 id: str = Field(..., description="Media variant ID (`mvr_...`).") 350 image_source: ImageSource | None = Field( 351 default=None, 352 description="Resolved image delivery metadata for this variant, including dimensions and CDN URL. `null` for non-image content types.", 353 ) 354 updated_at: datetime | None = Field( 355 default=None, description="When this variant was last updated (ISO 8601)." 356 ) 357 url: str | None = Field( 358 default=None, 359 description="Signed download URL for this variant, resolved at request time. `null` if the file is unavailable.", 360 ) 361 variant_key: str | None = Field( 362 default=None, 363 description='Identifier for this variant\'s processing tier. Common values include `"original"` (the unmodified upload) and `"thumbnail"` (a resized preview).', 364 ) 365 width: int | None = Field( 366 default=None, description="Width of this variant in pixels. `null` if not recorded." 367 )
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):
370class Attachment(BaseModel): 371 """ 372 A rich attachment associated with a message, such as a file, scraped link, artifact, task, media item, or inline action. 373 """ 374 375 content_type: str | None = Field( 376 default=None, 377 description='MIME type of the attached file, e.g. `"image/png"` or `"application/pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 378 ) 379 description: str | None = Field( 380 default=None, 381 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.", 382 ) 383 filename: str | None = Field( 384 default=None, 385 description='Original filename of the attached file, e.g. `"report.pdf"`. Present on `file`, `artifact`, and `media` types. `null` otherwise.', 386 ) 387 height: int | None = Field( 388 default=None, 389 description="Height in pixels of the media item. Present on `media` type only. `null` otherwise.", 390 ) 391 id: str = Field(..., description="Unique identifier for this attachment within the message.") 392 image_height: int | None = Field( 393 default=None, 394 description="Height in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 395 ) 396 image_source: ImageSource | None = Field( 397 default=None, 398 description="Image source metadata for inline rendering. Present on `file`, `scraped_link`, `artifact`, and `media` types when the content is an image. `null` otherwise.", 399 ) 400 image_url: str | None = Field( 401 default=None, 402 description="URL of the preview image extracted from the scraped page. Present on `scraped_link` type only. `null` otherwise.", 403 ) 404 image_width: int | None = Field( 405 default=None, 406 description="Width in pixels of the scraped preview image. Present on `scraped_link` type only. `null` otherwise.", 407 ) 408 media_type: str | None = Field( 409 default=None, 410 description='The media category, e.g. `"video"` or `"audio"`. Present on `media` type only; omitted otherwise.', 411 ) 412 name: str | None = Field( 413 default=None, 414 description="Display name of the media item. Present on `media` type only. `null` otherwise.", 415 ) 416 object: dict[str, Any] | None = Field( 417 default=None, 418 description="The full embedded object payload. For `task` type, contains the task record. For `action` type, contains the action definition. For `chart` type, contains the chart with its inline `spec`. Omitted on other types.", 419 ) 420 title: str | None = Field( 421 default=None, 422 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.", 423 ) 424 type: str = Field( 425 ..., 426 description='The attachment type. One of `"file"`, `"scraped_link"`, `"artifact"`, `"task"`, `"media"`, `"action"`, or `"chart"`. Determines which additional fields are present.', 427 ) 428 url: str | None = Field( 429 default=None, 430 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.", 431 ) 432 variants: list[MediaVariant] | None = Field( 433 default=None, 434 description="Array of available encoding variants for the media item (e.g. different resolutions). Present on `media` type only; omitted otherwise.", 435 ) 436 version: int | None = Field( 437 default=None, 438 description="Version number of the attached artifact at the time of attachment. Present on `artifact` type only. `null` otherwise.", 439 ) 440 width: int | None = Field( 441 default=None, 442 description="Width in pixels of the media item. Present on `media` type only. `null` otherwise.", 443 )
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; omitted 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. For chart type, contains the chart with its inline spec. Omitted 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", "action", or "chart". 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; omitted otherwise.
class
AuthTokens(pydantic.main.BaseModel):
446class AuthTokens(BaseModel): 447 """ 448 Credential bundle returned after a successful authentication exchange. Contains the access token, refresh token, and the authenticated user. 449 """ 450 451 expires_in: int = Field( 452 ..., 453 description="Number of seconds until `token` expires. After this period, use `refresh_token` to obtain a new access token.", 454 ) 455 metadata: dict[str, Any] | None = Field( 456 default=None, 457 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.", 458 ) 459 refresh_token: str = Field( 460 ..., 461 description="Long-lived opaque refresh token. Use this to obtain a new access token when `token` expires.", 462 ) 463 token: str = Field( 464 ..., 465 description="Short-lived JWT access token. Include this value in the `Authorization: Bearer <token>` header for all authenticated API requests.", 466 ) 467 token_type: str = Field(..., description='Token scheme. Always `"Bearer"`.') 468 user: User = Field( 469 ..., 470 description="The user who authenticated. Contains the user's profile and account details.", 471 )
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):
474class BugReport(BaseModel): 475 """ 476 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. 477 """ 478 479 app: str | None = Field( 480 default=None, 481 description="App ID (`dap_...`) of the developer app through which the report was submitted.", 482 ) 483 client: str = Field( 484 ..., 485 description='The client application that submitted this report. One of `"agent_network_web"`, `"cli"`, or `"developer_portal"`.', 486 ) 487 client_version: str = Field( 488 ..., 489 description='Version string of the submitting client at the time of submission, e.g. `"1.4.2"`.', 490 ) 491 context: dict[str, Any] | None = Field( 492 default=None, 493 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.", 494 ) 495 created_at: datetime | None = Field( 496 default=None, description="When the bug report was submitted (ISO 8601)." 497 ) 498 description: str = Field( 499 ..., 500 description="Freeform text describing the issue or feedback, as entered by the user. Up to 10,000 characters.", 501 ) 502 id: str = Field(..., description="Bug report ID (`bgr_...`).") 503 org: str | None = Field( 504 default=None, 505 description="Organization ID (`org_...`) scoping this report. `null` when the user's account is not part of an organization.", 506 ) 507 sandbox: str | None = Field( 508 default=None, 509 description="Sandbox ID (`dsb_...`) active at submission time. `null` when the report was not submitted from a sandbox context.", 510 ) 511 team: str | None = Field( 512 default=None, 513 description="Team ID (`tem_...`) of the team the submitting user belonged to at submission time. `null` when the user had no active team.", 514 ) 515 updated_at: datetime | None = Field( 516 default=None, description="When the bug report record was last modified (ISO 8601)." 517 )
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):
520class BuiltinTool(BaseModel): 521 """ 522 A single callable tool within a builtin tool catalog entry. Represents one discrete function an agent can invoke. 523 """ 524 525 description: str | None = Field( 526 default=None, 527 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.", 528 ) 529 name: str = Field( 530 ..., 531 description='Machine-readable name of the tool as it is registered with the agent runtime, e.g. `"web_search"` or `"github_create_issue"`.', 532 )
A single callable tool within a builtin tool catalog entry. Represents one discrete function an agent can invoke.
class
BuiltinToolCatalogEntry(pydantic.main.BaseModel):
535class BuiltinToolCatalogEntry(BaseModel): 536 """ 537 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. 538 """ 539 540 config_schema: dict[str, Any] | None = Field( 541 default=None, 542 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.", 543 ) 544 description: str | None = Field( 545 default=None, 546 description="Short prose description of what this tool category does. Suitable for display in setup UIs. `null` when no description has been defined.", 547 ) 548 instruction: str | None = Field( 549 default=None, 550 description="Additional guidance surfaced to the agent at runtime when this tool category is enabled. `null` when no custom instruction is set.", 551 ) 552 key: str = Field( 553 ..., 554 description='Unique slug identifying this tool category, e.g. `"web_search"` or `"github"`.', 555 ) 556 label: str | None = Field( 557 default=None, 558 description='Human-readable display name for the tool category, e.g. `"Web Search"`. `null` when no label has been assigned.', 559 ) 560 multi_instance_mode: str | None = Field( 561 default=None, 562 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.', 563 ) 564 providers: list[str] | None = Field( 565 default=None, 566 description='List of integration provider slugs that can back this tool category, e.g. `["github", "gitlab"]`. Empty when the tool is provider-agnostic.', 567 ) 568 requires_integration: bool | None = Field( 569 default=None, 570 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.", 571 ) 572 server_tool_type: str | None = Field( 573 default=None, 574 description="Internal type identifier used by the platform server when registering these tools. `null` for client-side-only tool categories.", 575 ) 576 tools: list[BuiltinTool] | None = Field( 577 default=None, 578 description="Array of individual tool definitions included in this category. Each entry describes a single callable tool with its own name and description.", 579 )
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):
582class ChannelAck(BaseModel): 583 """ 584 Empty acknowledgement payload returned by channel message handlers that produce no data. The wire envelope is `{"status": "ok", "response": {}}`. 585 """ 586 587 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):
590class MessageReaction(BaseModel): 591 """ 592 A compact reaction record embedded in a message's `reactions` array, representing a single user's reaction to a message. 593 """ 594 595 payload: dict[str, Any] | None = Field( 596 default=None, 597 description='Type-specific reaction data. For `"emoji_reaction"` reactions, contains an `emoji` key with the Unicode emoji string (e.g., `" "`).', 598 ) 599 type: str = Field( 600 ..., 601 description='Reaction type identifier. Currently always `"emoji_reaction"` for emoji-based reactions.', 602 ) 603 user: str | None = Field( 604 default=None, description="Public ID of the user who added the reaction (`usr_...`)." 605 )
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):
608class Message(BaseModel): 609 """ 610 A chat message posted in a thread, including its content, author, attachments, reactions, and optional reply metadata. 611 """ 612 613 acl: Acl | None = Field( 614 default=None, 615 description="Access control list for private messages (grants with `read` action). Only returned to resource owners (and privileged/org-admin viewers) via server-side `field_redactions: [acl: :owner]`; `null` for everyone else.", 616 ) 617 actors: list[Actor] | None = Field( 618 default=None, 619 description="Resolved actor descriptors for the message sender, combining identity and display metadata. Always contains exactly one entry.", 620 ) 621 agent: str | None = Field( 622 default=None, 623 description="ID of the agent user that sent this message (`agi_...`). `null` for messages sent by human users.", 624 ) 625 agent_mode: Literal["cli", "embedded"] | None = Field( 626 default=None, 627 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.", 628 ) 629 attachments: list[Attachment] | None = Field( 630 default=None, 631 description="Files, links, tasks, media, artifacts, and actions attached to this message. Empty array if there are no attachments.", 632 ) 633 branched_thread: str | None = Field( 634 default=None, 635 description="ID of the thread that was branched from this message (`thr_...`). `null` if this message has not spawned a branch thread.", 636 ) 637 content: str | None = Field( 638 default=None, 639 description="Text content of the message. `null` for messages that contain only attachments.", 640 ) 641 created_at: str | None = Field( 642 default=None, description="When the message was posted (ISO 8601)." 643 ) 644 has_replies: bool | None = Field( 645 default=None, 646 description="Whether this message has at least one reply. Only present when explicitly requested or computed by the server.", 647 ) 648 id: str = Field(..., description="Message ID (`msg_...`).") 649 idempotency_key: str | None = Field( 650 default=None, 651 description="Client-supplied idempotency key used to deduplicate message sends. `null` if the sender did not provide one.", 652 ) 653 is_deleted: bool | None = Field( 654 default=None, 655 description="Whether this message is a deletion tombstone. `true` only on the `message_updated` broadcast emitted when a message is deleted: the original content is replaced with a placeholder and the message no longer exists on the server. Always `false` for live messages.", 656 ) 657 legacy_agent: str | None = Field( 658 default=None, 659 description="Identifier of the legacy chat agent that sent this message, if applicable. `null` for messages sent by users or modern agent users.", 660 ) 661 metadata: dict[str, Any] | None = Field( 662 default=None, 663 description="Arbitrary key-value metadata attached to the message. Always present; defaults to an empty object when no metadata has been set.", 664 ) 665 org: str | None = Field( 666 default=None, description="ID of the organization that owns this message (`org_...`)." 667 ) 668 reactions: list[MessageReaction] | None = Field( 669 default=None, 670 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.", 671 ) 672 rendering_mode: str | None = Field( 673 default=None, 674 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.', 675 ) 676 replies: list[dict[str, Any]] | None = Field( 677 default=None, 678 description="Inline array of reply messages, each serialized as a full message object. Only present when the server has preloaded replies for this message.", 679 ) 680 replies_after_cursor: str | None = Field( 681 default=None, 682 description="Opaque pagination cursor to fetch replies posted after the current page. Only present when inline replies are included in the response.", 683 ) 684 replies_before_cursor: str | None = Field( 685 default=None, 686 description="Opaque pagination cursor to fetch replies posted before the current page. Only present when inline replies are included in the response.", 687 ) 688 reply_count: int | None = Field( 689 default=None, 690 description="Total number of direct replies to this message. Only present when explicitly requested or computed by the server.", 691 ) 692 reply_to: dict[str, Any] | None = Field( 693 default=None, 694 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.", 695 ) 696 root_message_id: str | None = Field( 697 default=None, 698 description="ID of the root message in this reply chain (`msg_...`). `null` for a top-level message. The value is persisted when the reply is created, so callers can correlate a multi-turn session without walking parent messages.", 699 ) 700 sandbox: str | None = Field( 701 default=None, 702 description="ID of the developer sandbox this message belongs to (`dsb_...`). `null` for non-sandbox messages.", 703 ) 704 team: str | None = Field( 705 default=None, 706 description="ID of the team this message is scoped to (`tem_...`). `null` if the message is not team-scoped.", 707 ) 708 thread: str | None = Field( 709 default=None, description="ID of the thread this message belongs to (`thr_...`)." 710 ) 711 type: str | None = Field( 712 default=None, 713 description="Optional client-defined classification for the message (for example `note` or `status`). Free-form string up to 64 characters. The value `system` is reserved for platform-authored messages and cannot be set by clients. `null` when unset.", 714 ) 715 user: str | dict[str, Any] | None = Field( 716 default=None, 717 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.", 718 ) 719 visibility: Literal["default", "private"] | None = Field( 720 default=None, 721 description="Message-level visibility. `default` is visible to anyone who can see the parent thread. `private` is restricted to the sender and explicit ACL `read` grantees.", 722 )
A chat message posted in a thread, including its content, author, attachments, reactions, and optional reply metadata.
Access control list for private messages (grants with read action). Only returned to resource owners (and privileged/org-admin viewers) via server-side field_redactions: [acl: :owner]; null for everyone else.
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.
is_deleted: bool | None =
None
Whether this message is a deletion tombstone. true only on the message_updated broadcast emitted when a message is deleted: the original content is replaced with a placeholder and the message no longer exists on the server. Always false for live messages.
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.
root_message_id: str | None =
None
ID of the root message in this reply chain (msg_...). null for a top-level message. The value is persisted when the reply is created, so callers can correlate a multi-turn session without walking parent messages.
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.
type: str | None =
None
Optional client-defined classification for the message (for example note or status). Free-form string up to 64 characters. The value system is reserved for platform-authored messages and cannot be set by clients. null when unset.
class
ComputerExecResult(pydantic.main.BaseModel):
725class ComputerExecResult(BaseModel): 726 """ 727 The result of executing a shell command on an agent's computer environment. Contains the captured output and the process exit code. 728 """ 729 730 exit_code: int | None = Field( 731 default=None, 732 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.", 733 ) 734 output: str | None = Field( 735 default=None, 736 description="The combined stdout and stderr output produced by the command. `null` if the command produced no output.", 737 )
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):
740class ContextDocument(BaseModel): 741 """ 742 A context document stored within a context source. Carries metadata and size information only; retrieve the full text content via the `/content` endpoint. 743 """ 744 745 agent: str | None = Field( 746 default=None, 747 description="ID of the agent that owns this document (`agi_...`). `null` if owned by a user or team.", 748 ) 749 content_hash: str | None = Field( 750 default=None, 751 description="Lowercase-hex sha256 of the document's full text, covering content only not `title` or `metadata`. Compare it against a hash of your local copy to decide whether the document needs re-ingesting, without fetching `/content`. `null` for documents ingested before this field existed; it is not backfilled.", 752 ) 753 created_at: datetime | None = Field( 754 default=None, description="When the document was created (ISO 8601)." 755 ) 756 file: str | None = Field( 757 default=None, 758 description="ID of the backing storage file (`fil_...`) when the document is file-backed. `null` for inline documents.", 759 ) 760 id: str = Field(..., description="Context document ID (`cdo_...`).") 761 metadata: dict[str, Any] | None = Field( 762 default=None, 763 description="Arbitrary key-value metadata attached to the document. Shape varies by source type.", 764 ) 765 source: str | None = Field( 766 default=None, description="ID of the context source this document belongs to (`cso_...`)." 767 ) 768 team: str | None = Field( 769 default=None, 770 description="ID of the team that owns this document (`tem_...`). `null` if owned by a user or agent.", 771 ) 772 title: str | None = Field( 773 default=None, 774 description="Human-readable display title of the document. `null` if no title has been set.", 775 ) 776 total_lines: int | None = Field( 777 default=None, 778 description="Total number of lines in the document's text content. `0` if the document has no content.", 779 ) 780 total_size: int | None = Field( 781 default=None, 782 description="Total byte size of the document's text content. `0` if the document has no content.", 783 ) 784 updated_at: datetime | None = Field( 785 default=None, description="When the document was last modified (ISO 8601)." 786 ) 787 user: str | None = Field( 788 default=None, 789 description="ID of the user that owns this document (`usr_...`). `null` if owned by a team or agent.", 790 )
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):
793class ContextDocumentContent(BaseModel): 794 """ 795 The text content of a context document, optionally sliced by line or byte range. Includes totals and slice boundary fields for the requested unit. 796 """ 797 798 content: str = Field( 799 ..., 800 description="Text of the document. Contains the full content when no `offset`/`limit` was requested, or only the requested slice otherwise.", 801 ) 802 end_byte: int | None = Field( 803 default=None, 804 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.', 805 ) 806 end_line: int | None = Field( 807 default=None, 808 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.', 809 ) 810 id: str = Field(..., description="Context document ID (`cdo_...`).") 811 limit: int | None = Field( 812 default=None, 813 description="The `limit` value echoed from the request. `null` when no limit was requested.", 814 ) 815 metadata: dict[str, Any] | None = Field( 816 default=None, 817 description="Arbitrary key-value metadata attached to the document, such as source URL or author. `null` if no metadata was recorded.", 818 ) 819 offset: int | None = Field( 820 default=None, 821 description="The `offset` value echoed from the request. `null` when no offset was requested.", 822 ) 823 start_byte: int | None = Field( 824 default=None, 825 description='Zero-based index of the first byte included in `content`. Populated only when `unit` is `"bytes"`; `null` otherwise.', 826 ) 827 start_line: int | None = Field( 828 default=None, 829 description='1-indexed line number of the first line included in `content`. Populated only when `unit` is `"lines"`; `null` otherwise.', 830 ) 831 title: str | None = Field( 832 default=None, 833 description="Human-readable display title of the document. `null` if the document has no title set.", 834 ) 835 total_lines: int = Field( 836 ..., 837 description="Total number of lines in the document's full content, regardless of any slice.", 838 ) 839 total_size: int = Field( 840 ..., description="Total byte size of the document's full content, regardless of any slice." 841 ) 842 unit: str | None = Field( 843 default=None, 844 description='Slice unit used when `offset` and `limit` were provided. One of `"lines"` (default) or `"bytes"`. `null` when no slice was requested.', 845 )
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):
848class ContextIngestion(BaseModel): 849 """ 850 A context ingestion job that processes a context source and populates its documents. Tracks status and timing from submission through completion or failure. 851 """ 852 853 agent: str | None = Field( 854 default=None, 855 description="ID of the agent that initiated this ingestion (`agi_...`). `null` if initiated by a user.", 856 ) 857 completed_at: datetime | None = Field( 858 default=None, 859 description="When the ingestion job finished, either successfully or with a failure. `null` if still in progress.", 860 ) 861 created_at: datetime | None = Field( 862 default=None, description="When the ingestion was submitted (ISO 8601)." 863 ) 864 error: dict[str, Any] | None = Field( 865 default=None, 866 description='Structured error details when the ingestion has `status: "failed"`. `null` for any other status.', 867 ) 868 id: str = Field(..., description="Context ingestion ID (`cig_...`).") 869 metadata: dict[str, Any] | None = Field( 870 default=None, 871 description="Arbitrary key-value metadata associated with this ingestion run. Shape is caller-defined.", 872 ) 873 source: str | None = Field( 874 default=None, 875 description="ID of the context source being ingested (`cso_...`). `null` if the source has been deleted.", 876 ) 877 started_at: datetime | None = Field( 878 default=None, 879 description="When the ingestion job began processing. `null` if the job is still pending.", 880 ) 881 status: str = Field( 882 ..., 883 description='Current processing status. One of `"pending"`, `"running"`, `"awaiting_callback"`, `"succeeded"`, or `"failed"`.', 884 ) 885 team: str | None = Field( 886 default=None, 887 description="ID of the team that owns this ingestion (`tem_...`). `null` if owned by a user or agent.", 888 ) 889 updated_at: datetime | None = Field( 890 default=None, description="When the ingestion record was last updated (ISO 8601)." 891 ) 892 user: str | None = Field( 893 default=None, 894 description="ID of the user that initiated this ingestion (`usr_...`). `null` if initiated by an agent.", 895 )
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
CreatedPrivateServiceEnrollment(pydantic.main.BaseModel):
898class CreatedPrivateServiceEnrollment(BaseModel): 899 """ 900 Creation-only private service enrollment response. The raw token is shown 901 once and is omitted from every read schema. 902 """ 903 904 enrollment_token: str = Field( 905 ..., description="One-time connector enrollment token. Store it immediately." 906 ) 907 enrollment_token_expires_at: datetime = Field( 908 ..., description="When the one-time enrollment token expires." 909 ) 910 generation: int 911 id: str 912 private_service: str
Creation-only private service enrollment response. The raw token is shown once and is omitted from every read schema.
enrollment_token: str =
PydanticUndefined
One-time connector enrollment token. Store it immediately.
class
CustomObject(pydantic.main.BaseModel):
915class CustomObject(BaseModel): 916 """ 917 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. 918 """ 919 920 acl: Acl | None = Field( 921 default=None, 922 description="Access control list governing read and write access to this custom object. Only returned to resource owners and privileged or organization-admin viewers; `null` for everyone else.", 923 ) 924 created_at: datetime | None = Field( 925 default=None, description="When the custom object was created (ISO 8601)." 926 ) 927 fields: dict[str, Any] | None = Field( 928 default=None, 929 description="Map of field names to their current values as defined by the object's schema type.", 930 ) 931 id: str = Field(..., description="Unique identifier for the custom object (`cobj_...`).") 932 org: str | None = Field( 933 default=None, description="ID of the organization this object belongs to (`org_...`)." 934 ) 935 row_key: str | None = Field( 936 default=None, 937 description="An optional stable key used to identify this object by a caller-controlled string rather than its generated ID. `null` if not set.", 938 ) 939 sandbox: str | None = Field( 940 default=None, 941 description="ID of the sandbox environment this object is scoped to (`dsb_...`). `null` for production objects.", 942 ) 943 schema_type: str | None = Field( 944 default=None, 945 description="The lookup key of the schema type that defines this object's field structure. `null` if the schema type has not been set.", 946 ) 947 team: str | None = Field( 948 default=None, 949 description="ID of the team that owns this object (`tem_...`). `null` if the object is not team-scoped.", 950 ) 951 updated_at: datetime | None = Field( 952 default=None, 953 description="When the custom object was last modified (ISO 8601). `null` if the object has never been updated after creation.", 954 ) 955 user: str | None = Field( 956 default=None, 957 description="ID of the user that owns this object (`usr_...`). `null` if the object is not user-scoped.", 958 ) 959 version: int | None = Field( 960 default=None, 961 description="Optimistic concurrency version of the object. Increments with each successful update; pass this value in write operations to detect conflicting changes.", 962 )
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.
Access control list governing read and write access to this custom object. Only returned to resource owners and privileged or organization-admin viewers; null for everyone else.
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
CustomObjectJoinResponse(pydantic.main.BaseModel):
965class CustomObjectJoinResponse(BaseModel): 966 """ 967 Initial authoritative snapshot returned by a custom-object channel join. 968 """ 969 970 connection_id: str = Field( 971 ..., description="Collision-free identifier for this browser connection." 972 ) 973 fields: dict[str, Any] | None = Field( 974 ..., description="Current materialized fields, or `null` while waiting for object creation." 975 ) 976 id: str | None = Field( 977 ..., 978 description="Custom-object ID, or `null` while a row-key subscription waits for creation.", 979 ) 980 presence: list[dict[str, Any]] = Field( 981 ..., description="Current ephemeral collaborator presence." 982 ) 983 readonly: bool = Field( 984 ..., description="Whether the current connection may only read the object." 985 )
Initial authoritative snapshot returned by a custom-object channel join.
fields: dict[str, typing.Any] | None =
PydanticUndefined
Current materialized fields, or null while waiting for object creation.
class
CustomObjectListResponse(pydantic.main.BaseModel):
988class CustomObjectListResponse(BaseModel): 989 """ 990 A paginated page of custom objects returned by a list operation. Use the pagination fields to navigate through result sets. 991 """ 992 993 data: list[CustomObject] = Field( 994 ..., description="Array of custom objects for the current page." 995 ) 996 has_next: bool = Field( 997 ..., 998 description="`true` if a subsequent page of results exists; `false` if this is the last page.", 999 ) 1000 has_prev: bool = Field( 1001 ..., 1002 description="`true` if a preceding page of results exists; `false` if this is the first page.", 1003 ) 1004 page: int = Field(..., description="The current page number (1-indexed).") 1005 page_size: int = Field(..., description="Maximum number of results returned per page.") 1006 total_entries: int = Field( 1007 ..., description="Total number of custom objects matching the query across all pages." 1008 ) 1009 total_pages: int = Field( 1010 ..., description="Total number of pages available for the current query." 1011 )
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
CustomObjectPresenceAck(pydantic.main.BaseModel):
1014class CustomObjectPresenceAck(BaseModel): 1015 """ 1016 Acknowledges an ephemeral custom-object presence update. 1017 """ 1018 1019 connection_id: str = Field( 1020 ..., description="Collision-free connection identifier assigned to this browser connection." 1021 )
Acknowledges an ephemeral custom-object presence update.
class
CustomObjectSaveResponse(pydantic.main.BaseModel):
1024class CustomObjectSaveResponse(BaseModel): 1025 """ 1026 Acknowledges that the current custom-object document reached durable storage. 1027 """ 1028 1029 version: int = Field(..., description="Durable optimistic-concurrency version after the save.")
Acknowledges that the current custom-object document reached durable storage.
class
CustomObjectUpdateFieldsResponse(pydantic.main.BaseModel):
1032class CustomObjectUpdateFieldsResponse(BaseModel): 1033 """ 1034 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. 1035 """ 1036 1037 fields: dict[str, Any] = Field( 1038 ..., description="The materialized object fields after the update." 1039 ) 1040 id: str = Field(..., description="ID of the custom object that was updated (`cobj_...`).") 1041 operation_id: str = Field(..., description="Idempotency key acknowledged for this update.")
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
Deployment(pydantic.main.BaseModel):
1044class Deployment(BaseModel): 1045 """ 1046 Deployment metadata. 1047 """ 1048 1049 environment: str | None = Field( 1050 default=None, description="Deployment environment, or `null` when it is not configured." 1051 ) 1052 release: str | None = Field( 1053 default=None, 1054 description="Opaque SHA-256 fingerprint of the image reference, or `null` in local development.", 1055 )
Deployment metadata.
class
DomainEvent(pydantic.main.BaseModel):
1058class DomainEvent(BaseModel): 1059 """ 1060 A domain event with stable attribution fields and an event-specific payload. 1061 """ 1062 1063 agent: str | None = None 1064 created_at: datetime 1065 event_name: str 1066 id: str 1067 idempotency_key: str | None = None 1068 org: str | None = None 1069 payload: dict[str, Any] = Field( 1070 ..., 1071 description="Opaque event-specific JSON. Use event_name to select the expected payload schema.", 1072 ) 1073 sandbox: str | None = None 1074 team: str | None = None 1075 user: str | None = None
A domain event with stable attribution fields and an event-specific payload.
class
EventSubscription(pydantic.main.BaseModel):
1078class EventSubscription(BaseModel): 1079 """ 1080 An app-scoped subscription to exact domain-event names. 1081 """ 1082 1083 agent: str | None = None 1084 available_count: int 1085 created_at: datetime 1086 dropped_events_total: int 1087 dropped_through_position: int 1088 event_names: list[str] 1089 id: str 1090 last_overflow_at: datetime | None = None 1091 leased_count: int 1092 max_pending_events: int 1093 name: str 1094 org: str | None = None 1095 queue_epoch: int 1096 retention_seconds: int 1097 sandbox: str | None = None 1098 status: Literal["active", "paused"] 1099 team: str | None = None 1100 updated_at: datetime 1101 user: str | None = None 1102 visibility_timeout_seconds: int
An app-scoped subscription to exact domain-event names.
class
EventSubscriptionDelivery(pydantic.main.BaseModel):
1105class EventSubscriptionDelivery(BaseModel): 1106 """ 1107 A domain event leased from a subscription queue. 1108 """ 1109 1110 delivery_id: str 1111 event: DomainEvent 1112 lease_expires_at: datetime 1113 receipt_handle: str 1114 receive_count: int 1115 sequence: int
A domain event leased from a subscription queue.
class
EventSubscriptionClaim(pydantic.main.BaseModel):
1118class EventSubscriptionClaim(BaseModel): 1119 """ 1120 Result of atomically claiming the head delivery. 1121 """ 1122 1123 data: list[EventSubscriptionDelivery] 1124 dropped_events_total: int 1125 dropped_through_position: int 1126 has_more: bool 1127 queue_epoch: int
Result of atomically claiming the head delivery.
class
EventSubscriptionQueueEntry(pydantic.main.BaseModel):
1130class EventSubscriptionQueueEntry(BaseModel): 1131 """ 1132 A non-reserving view of one queued delivery. 1133 """ 1134 1135 delivery_id: str 1136 event: DomainEvent 1137 lease_expires_at: datetime | None = None 1138 receive_count: int 1139 sequence: int 1140 state: Literal["available", "leased"]
A non-reserving view of one queued delivery.
class
EventSubscriptionHead(pydantic.main.BaseModel):
1143class EventSubscriptionHead(BaseModel): 1144 """ 1145 A non-reserving view of the queue head. 1146 """ 1147 1148 data: EventSubscriptionQueueEntry | None = None
A non-reserving view of the queue head.
class
EventSubscriptionPage(pydantic.main.BaseModel):
1151class EventSubscriptionPage(BaseModel): 1152 """ 1153 A page of domain-event subscriptions. 1154 """ 1155 1156 data: list[EventSubscription] 1157 page: int 1158 per_page: int 1159 total_count: int 1160 total_pages: int
A page of domain-event subscriptions.
class
EventSubscriptionQueue(pydantic.main.BaseModel):
1163class EventSubscriptionQueue(BaseModel): 1164 """ 1165 A cursor-paginated non-reserving view of a subscription queue. 1166 """ 1167 1168 after_cursor: str | None = None 1169 before_cursor: str | None = None 1170 data: list[EventSubscriptionQueueEntry] 1171 dropped_events_total: int 1172 dropped_through_position: int 1173 has_more: bool 1174 queue_epoch: int
A cursor-paginated non-reserving view of a subscription queue.
class
StorageFile(pydantic.main.BaseModel):
1177class StorageFile(BaseModel): 1178 """ 1179 A file stored in the platform's object storage, with metadata and a signed URL for downloading its contents. 1180 """ 1181 1182 app: str | None = Field( 1183 default=None, description="ID of the app this file belongs to (`app_...`)." 1184 ) 1185 content_type: str | None = Field( 1186 default=None, 1187 description='MIME type of the file, e.g. `"image/png"` or `"application/pdf"`.', 1188 ) 1189 created_at: datetime | None = Field( 1190 default=None, description="When the file was uploaded (ISO 8601)." 1191 ) 1192 filename: str | None = Field( 1193 default=None, description="Original filename as provided at upload time." 1194 ) 1195 id: str = Field(..., description="File ID (`fil_...`).") 1196 image_source: ImageSource | None = Field( 1197 default=None, 1198 description="Image display metadata. Present only when `content_type` is an image type; `null` otherwise.", 1199 ) 1200 org: str | None = Field( 1201 default=None, description="ID of the organization that owns this file (`org_...`)." 1202 ) 1203 sandbox: str | None = Field( 1204 default=None, 1205 description="ID of the sandbox this file is scoped to (`sbx_...`). `null` for files not associated with a sandbox.", 1206 ) 1207 share_url: str | None = Field( 1208 default=None, 1209 description="Stable public URL for the file, fetchable without authentication. Present only when the file was shared (`share: true`); does not expire until sharing is disabled. Disabling and re-enabling sharing reactivates the same URL. `null` otherwise.", 1210 ) 1211 size: int | None = Field(default=None, description="Size of the file in bytes.") 1212 team: str | None = Field( 1213 default=None, 1214 description="ID of the team that owns this file (`team_...`). `null` if not team-owned.", 1215 ) 1216 updated_at: datetime | None = Field( 1217 default=None, description="When the file record was last modified (ISO 8601)." 1218 ) 1219 url: str | None = Field( 1220 default=None, 1221 description="Short-lived signed URL for downloading the file. `null` if a URL could not be generated.", 1222 ) 1223 user: str | None = Field( 1224 default=None, 1225 description="ID of the user that owns this file (`user_...`). `null` if not user-owned.", 1226 )
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.
sandbox: str | None =
None
ID of the sandbox this file is scoped to (sbx_...). null for files not associated with a sandbox.
class
AgentHealthAction(pydantic.main.BaseModel):
1229class AgentHealthAction(BaseModel): 1230 """ 1231 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. 1232 """ 1233 1234 agent: str | None = Field( 1235 default=None, 1236 description="ID of the agent this action is scoped to (`agt_...`). `null` for org-level actions.", 1237 ) 1238 app: str | None = Field( 1239 default=None, 1240 description="ID of the application this action is associated with (`app_...`). `null` when not app-scoped.", 1241 ) 1242 created_at: datetime | None = Field( 1243 default=None, description="When this health action was first created (ISO 8601)." 1244 ) 1245 depends_on: list[str] | None = Field( 1246 default=None, 1247 description='IDs of other health actions that must reach `"completed"` status before this action can be started. Empty array when there are no dependencies.', 1248 ) 1249 description: str | None = Field( 1250 default=None, 1251 description="Longer Markdown-formatted explanation of what the action requires and why. `null` if not provided.", 1252 ) 1253 id: str = Field(..., description="Health action ID (`aha_...`).") 1254 kind: str = Field( 1255 ..., 1256 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).', 1257 ) 1258 last_verified_at: datetime | None = Field( 1259 default=None, 1260 description="When the verifier last ran for this action (ISO 8601). `null` until the verifier has been invoked at least once.", 1261 ) 1262 last_verifier_message: str | None = Field( 1263 default=None, 1264 description="Human-readable output from the most recent verifier run. `null` if the verifier has not run yet.", 1265 ) 1266 org: str | None = Field( 1267 default=None, 1268 description="ID of the organization this action is associated with (`org_...`). `null` when not org-scoped.", 1269 ) 1270 params: dict[str, Any] | None = Field( 1271 default=None, 1272 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.', 1273 ) 1274 required: bool = Field( 1275 ..., 1276 description="`true` if this action must be completed before the agent is considered fully operational and counts toward the blocking checklist progress bar.", 1277 ) 1278 sort_order: int = Field( 1279 ..., description="Display order within the same `source` group. Lower values appear first." 1280 ) 1281 source: str = Field( 1282 ..., 1283 description='Lifecycle stage that produced this action. One of `"setup"` (post-install checklist item) or `"health"` (probe-detected issue).', 1284 ) 1285 status: str = Field( 1286 ..., 1287 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).', 1288 ) 1289 title: str = Field( 1290 ..., 1291 description="Short display label for this action, intended for use as a checklist item heading.", 1292 ) 1293 updated_at: datetime | None = Field( 1294 default=None, description="When this health action was last modified (ISO 8601)." 1295 ) 1296 verify_config: dict[str, Any] | None = Field( 1297 default=None, 1298 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.", 1299 )
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):
1302class HealthActionListResponse(BaseModel): 1303 """ 1304 List response containing agent health actions for a given agent or organization. 1305 """ 1306 1307 data: list[AgentHealthAction] = Field( 1308 ..., 1309 description="Array of agent health action objects representing setup checklist items and probe-detected issues.", 1310 )
List response containing agent health actions for a given agent or organization.
class
Installation(pydantic.main.BaseModel):
1313class Installation(BaseModel): 1314 """ 1315 An installation representing a connection between an agent and an external service or enablement channel. Tracks configuration, lifecycle state, and any bound integration. 1316 """ 1317 1318 agent: str | None = Field( 1319 default=None, 1320 description="ID of the agent that owns this installation (`agi_...`). `null` if the installation has no agent owner.", 1321 ) 1322 config: dict[str, Any] | None = Field( 1323 default=None, 1324 description="Kind-specific configuration object for this installation. Shape depends on the `kind` value. `null` if the kind requires no configuration.", 1325 ) 1326 created_at: datetime | None = Field( 1327 default=None, description="When the installation was created (ISO 8601)." 1328 ) 1329 id: str = Field(..., description="Installation ID (`cin_...`).") 1330 kind: str | None = Field( 1331 default=None, 1332 description='Slug identifying the type of external service this installation connects to, e.g. `"enablement/github_app"` or `"integration/gmail"`. `null` if not set.', 1333 ) 1334 lookup_key: str | None = Field( 1335 default=None, 1336 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.", 1337 ) 1338 shared_integration: str | None = Field( 1339 default=None, 1340 description="ID of the shared org- or app-level integration bound to this installation (`int_...`). `null` if no integration has been bound.", 1341 ) 1342 state: str | None = Field( 1343 default=None, 1344 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.', 1345 ) 1346 status_payload: dict[str, Any] | None = Field( 1347 default=None, 1348 description="Provider-supplied status detail for this installation, set during activation or event processing. `null` if no status has been reported.", 1349 ) 1350 updated_at: datetime | None = Field( 1351 default=None, description="When the installation record was last updated (ISO 8601)." 1352 )
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):
1355class InstallationKind(BaseModel): 1356 """ 1357 A supported installation kind describing a category of external service or enablement channel an agent can be connected to. 1358 """ 1359 1360 accepts_sources: bool | None = Field( 1361 default=None, 1362 description="When `true`, sources can be attached to installations of this kind to supply additional context to the agent.", 1363 ) 1364 category: str | None = Field( 1365 default=None, 1366 description='Grouping category for UI display purposes, e.g. `"enablement"` or `"integration"`. `null` if uncategorized.', 1367 ) 1368 config_schema: dict[str, Any] | None = Field( 1369 default=None, 1370 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.", 1371 ) 1372 description: str | None = Field( 1373 default=None, 1374 description="Short prose description of what this kind connects to and how it is used. `null` if no description is defined.", 1375 ) 1376 kind: str = Field( 1377 ..., 1378 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.', 1379 ) 1380 label: str | None = Field( 1381 default=None, 1382 description='Human-readable display name for this kind, e.g. `"GitHub App"`. `null` if the kind has no label defined.', 1383 ) 1384 provider: str | None = Field( 1385 default=None, 1386 description='Identifier of the external provider this kind connects to, e.g. `"github"` or `"slack"`. `null` for kinds with no specific provider.', 1387 ) 1388 requires_integration: bool | None = Field( 1389 default=None, 1390 description="When `true`, this kind requires an integration to be provided (either inline or via `shared_integration`) before the installation can be activated.", 1391 )
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):
1394class InstallationKindListResponse(BaseModel): 1395 """ 1396 List response containing the publicly available installation kinds that can be used when configuring an agent installation. 1397 """ 1398 1399 data: list[InstallationKind] = Field( 1400 ..., 1401 description="Array of installation kind objects describing the available integration types and their configuration requirements.", 1402 )
List response containing the publicly available installation kinds that can be used when configuring an agent installation.
class
InstallationListResponse(pydantic.main.BaseModel):
1405class InstallationListResponse(BaseModel): 1406 """ 1407 Paginated list response containing installation objects for an agent. 1408 """ 1409 1410 data: list[Installation] = Field( 1411 ..., description="Array of installation objects returned for the current page." 1412 )
Paginated list response containing installation objects for an agent.
class
InstallationSource(pydantic.main.BaseModel):
1415class InstallationSource(BaseModel): 1416 """ 1417 A source attached to an installation that supplies content for the agent's context. Sources are processed asynchronously after creation. 1418 """ 1419 1420 agent: str | None = Field( 1421 default=None, 1422 description="ID of the agent that owns this source (`agi_...`). `null` if the source is not agent-owned.", 1423 ) 1424 context_installation: str | None = Field( 1425 default=None, 1426 description="ID of the installation this source belongs to (`cin_...`). `null` if the source is not attached to an installation.", 1427 ) 1428 created_at: datetime | None = Field( 1429 default=None, description="When the source was created (ISO 8601)." 1430 ) 1431 id: str = Field(..., description="Source ID (`cso_...`).") 1432 metadata: dict[str, Any] | None = Field( 1433 default=None, 1434 description="Arbitrary key-value metadata associated with this source. Shape is caller-defined. `null` if no metadata was set.", 1435 ) 1436 parent_source: str | None = Field( 1437 default=None, 1438 description="ID of the parent source (`cso_...`) when this source was derived from another source. `null` for top-level sources.", 1439 ) 1440 payload: dict[str, Any] | None = Field( 1441 default=None, 1442 description="Type-specific payload provided when the source was created. The shape depends on the `type` value. `null` if no payload was supplied.", 1443 ) 1444 state: str | None = Field( 1445 default=None, 1446 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.', 1447 ) 1448 team: str | None = Field( 1449 default=None, 1450 description="ID of the team associated with this source (`tem_...`). `null` if the source has no team association.", 1451 ) 1452 thread: str | None = Field( 1453 default=None, 1454 description="ID of the conversation thread linked to this source (`thr_...`). `null` if the source is not thread-scoped.", 1455 ) 1456 type: str | None = Field( 1457 default=None, 1458 description='Slug identifying the kind of content this source provides, e.g. `"file/document"` or `"web/link"`. `null` if the type is not set.', 1459 ) 1460 updated_at: datetime | None = Field( 1461 default=None, description="When the source record was last updated (ISO 8601)." 1462 ) 1463 user: str | None = Field( 1464 default=None, 1465 description="ID of the user associated with this source (`usr_...`). `null` if the source has no user association.", 1466 )
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):
1469class InstallationSourceListResponse(BaseModel): 1470 """ 1471 Paginated list response containing installation source objects attached to an installation. 1472 """ 1473 1474 data: list[InstallationSource] = Field( 1475 ..., description="Array of installation source objects returned for the current page." 1476 )
Paginated list response containing installation source objects attached to an installation.
class
KeyValueStorageEntry(pydantic.main.BaseModel):
1479class KeyValueStorageEntry(BaseModel): 1480 """ 1481 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. 1482 """ 1483 1484 created_at: datetime | None = Field( 1485 default=None, 1486 description="When this storage entry was first created (ISO 8601). `null` if not yet persisted.", 1487 ) 1488 key: str = Field(..., description="The string key used to store and look up this entry.") 1489 updated_at: datetime | None = Field( 1490 default=None, 1491 description="When this storage entry was last updated (ISO 8601). `null` if not yet persisted.", 1492 ) 1493 user: str = Field(..., description="ID of the user who owns this storage entry (`usr_...`).") 1494 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):
1497class KeyValueStorageEntryWithUser(BaseModel): 1498 """ 1499 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`. 1500 """ 1501 1502 created_at: datetime = Field( 1503 ..., description="When this storage entry was first created (ISO 8601)." 1504 ) 1505 key: str = Field(..., description="The string key used to store and look up this entry.") 1506 updated_at: datetime = Field( 1507 ..., description="When this storage entry was last updated (ISO 8601)." 1508 ) 1509 user: str = Field(..., description="ID of the user who owns this storage entry (`usr_...`).") 1510 user_email: str | None = Field( 1511 default=None, 1512 description="Email address of the owning user. `null` for end-user (user-JWT) callers; populated for developer and server-to-server callers.", 1513 ) 1514 user_name: str | None = Field( 1515 default=None, 1516 description="Display name of the owning user. `null` for end-user (user-JWT) callers; populated for developer and server-to-server callers.", 1517 ) 1518 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):
1521class KeyValueStorageEntryPage(BaseModel): 1522 """ 1523 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. 1524 """ 1525 1526 data: list[KeyValueStorageEntryWithUser] = Field( 1527 ..., description="Array of key-value storage entries for the current page." 1528 ) 1529 has_next: bool | None = Field( 1530 default=None, 1531 description="Whether a subsequent page exists. `false` when the current page is the last page. Present only for developer and server-to-server callers.", 1532 ) 1533 has_prev: bool | None = Field( 1534 default=None, 1535 description="Whether a preceding page exists. `false` when the current page is the first page. Present only for developer and server-to-server callers.", 1536 ) 1537 page: int | None = Field( 1538 default=None, 1539 description="Current page number (1-indexed). Present only for developer and server-to-server callers.", 1540 ) 1541 page_size: int | None = Field( 1542 default=None, 1543 description="Maximum number of results returned per page. Present only for developer and server-to-server callers.", 1544 ) 1545 total_entries: int | None = Field( 1546 default=None, 1547 description="Total number of storage entries matching the applied filters across all pages. Present only for developer and server-to-server callers.", 1548 ) 1549 total_pages: int | None = Field( 1550 default=None, 1551 description="Total number of pages available given the current `page_size`. Present only for developer and server-to-server callers.", 1552 )
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):
1555class KnowledgeSource(BaseModel): 1556 """ 1557 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. 1558 """ 1559 1560 agent: str | None = Field( 1561 default=None, 1562 description="ID of the agent that owns this source (`agt_...`). `null` if owned by a human user or team.", 1563 ) 1564 context_installation: str | None = Field( 1565 default=None, 1566 description="ID of the context installation that provisioned this source (`cin_...`). `null` when the source was created directly rather than through an installation.", 1567 ) 1568 created_at: datetime | None = Field( 1569 default=None, description="When this knowledge source was created (ISO 8601)." 1570 ) 1571 id: str = Field(..., description="Knowledge source ID (`cso_...`).") 1572 metadata: dict[str, Any] | None = Field( 1573 default=None, 1574 description="Arbitrary key-value metadata attached to this source. Useful for storing caller-defined labels or references.", 1575 ) 1576 org: str | None = Field( 1577 default=None, 1578 description="ID of the organization this source belongs to (`org_...`). `null` if not scoped to an org.", 1579 ) 1580 parent_source: str | None = Field( 1581 default=None, 1582 description="ID of the parent knowledge source (`cso_...`) when this source was derived from another. `null` for top-level sources.", 1583 ) 1584 payload: dict[str, Any] | None = Field( 1585 default=None, 1586 description="Type-specific configuration object. The keys depend on the source `type`; see the create endpoint for the expected shape per type.", 1587 ) 1588 sandbox: str | None = Field( 1589 default=None, 1590 description="ID of the developer sandbox this source is scoped to (`sbx_...`). `null` outside sandbox contexts.", 1591 ) 1592 state: str = Field( 1593 ..., 1594 description='Current lifecycle state of the source. One of `"active"` (ingestion running normally) or `"paused"` (ingestion suspended).', 1595 ) 1596 team: str | None = Field( 1597 default=None, 1598 description="ID of the team that owns this source (`tea_...`). `null` if owned by a user, agent, or org.", 1599 ) 1600 thread: str | None = Field( 1601 default=None, 1602 description="ID of the chat thread this source is associated with (`thr_...`). `null` when not thread-scoped.", 1603 ) 1604 type: str = Field( 1605 ..., 1606 description='Source type identifier (e.g. `"gmail"`, `"github_activity"`). Determines the shape of `payload` and the ingestion behavior.', 1607 ) 1608 updated_at: datetime | None = Field( 1609 default=None, description="When this knowledge source was last modified (ISO 8601)." 1610 ) 1611 user: str | None = Field( 1612 default=None, 1613 description="ID of the user that owns this source (`usr_...`). `null` if owned by a team, agent, or org.", 1614 )
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):
1617class KnowledgeSourceKind(BaseModel): 1618 """ 1619 Describes a single knowledge source kind that can be created through the public API. Use the `type` value when creating a new knowledge source. 1620 """ 1621 1622 description: str | None = Field( 1623 default=None, 1624 description="Short description of what this source kind ingests and how it is used.", 1625 ) 1626 label: str | None = Field( 1627 default=None, 1628 description="Human-readable display name for this source kind, suitable for showing in a UI.", 1629 ) 1630 type: str = Field( 1631 ..., 1632 description='Machine-readable type identifier for this source kind (e.g. `"gmail"`, `"github_activity"`). Pass this value as `type` when creating a knowledge source.', 1633 )
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):
1636class KnowledgeSourceKindListResponse(BaseModel): 1637 """ 1638 List response containing the knowledge source kinds available for creation via the API. 1639 """ 1640 1641 data: list[KnowledgeSourceKind] = Field( 1642 ..., 1643 description="Array of knowledge source kind objects describing each creatable source type.", 1644 )
List response containing the knowledge source kinds available for creation via the API.
class
PaginatedReplies(pydantic.main.BaseModel):
1647class PaginatedReplies(BaseModel): 1648 """ 1649 A paginated list of reply messages for a thread. The reply array is returned directly, not nested inside a `data` wrapper. 1650 """ 1651 1652 after_cursor: str | None = Field( 1653 default=None, 1654 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.", 1655 ) 1656 before_cursor: str | None = Field( 1657 default=None, 1658 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.", 1659 ) 1660 has_more: bool | None = Field( 1661 default=None, description="Whether additional reply pages exist beyond the current page." 1662 ) 1663 replies: list[Message] = Field( 1664 ..., description="Array of reply message objects for the current page." 1665 ) 1666 total_count: int | None = Field( 1667 default=None, description="Total number of replies in the thread across all pages." 1668 )
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
PrivateServiceFunction(pydantic.main.BaseModel):
1671class PrivateServiceFunction(BaseModel): 1672 """ 1673 A documented callable operation exposed by a private service. 1674 """ 1675 1676 description: str = Field( 1677 ..., description="Human-readable guidance describing when and why to call the operation." 1678 ) 1679 input_schema: dict[str, Any] = Field( 1680 ..., description="JSON Schema Draft 7 object describing the operation's argument object." 1681 ) 1682 name: str = Field( 1683 ..., description="Stable operation name used when invoking the private service." 1684 ) 1685 output_schema: dict[str, Any] | None = Field( 1686 default=None, 1687 description="Optional JSON Schema Draft 7 object describing the successful result.", 1688 )
A documented callable operation exposed by a private service.
description: str =
PydanticUndefined
Human-readable guidance describing when and why to call the operation.
class
PrivateService(pydantic.main.BaseModel):
1691class PrivateService(BaseModel): 1692 """ 1693 An immutable private service with complete callable operation contracts. 1694 """ 1695 1696 functions: list[PrivateServiceFunction] = Field( 1697 ..., description="Sorted callable definitions exposed by this private service." 1698 ) 1699 id: str = Field(..., description="Private service ID (`pvs_...`).")
An immutable private service with complete callable operation contracts.
class
PrivateServiceEnrollment(pydantic.main.BaseModel):
1702class PrivateServiceEnrollment(BaseModel): 1703 """ 1704 A private service's durable connector identity. Read responses never contain 1705 an enrollment token or certificate. 1706 """ 1707 1708 generation: int = Field( 1709 ..., 1710 description="Latest committed connector certificate generation, or zero before enrollment.", 1711 ) 1712 id: str = Field(..., description="Canonical certificate-bound service identity.") 1713 private_service: str = Field(..., description="Immutable private service ID (`pvs_...`).")
A private service's durable connector identity. Read responses never contain an enrollment token or certificate.
class
PrivateServiceEnrollmentPage(pydantic.main.BaseModel):
1716class PrivateServiceEnrollmentPage(BaseModel): 1717 """ 1718 A secret-free page of private service enrollments. 1719 """ 1720 1721 data: list[PrivateServiceEnrollment] 1722 has_next: bool 1723 has_prev: bool 1724 page: int 1725 page_size: int 1726 total_entries: int 1727 total_pages: int
A secret-free page of private service enrollments.
class
PrivateServicePage(pydantic.main.BaseModel):
1730class PrivateServicePage(BaseModel): 1731 """ 1732 A page of private services. 1733 """ 1734 1735 data: list[PrivateService] 1736 has_next: bool 1737 has_prev: bool 1738 page: int 1739 page_size: int 1740 total_entries: int 1741 total_pages: int
A page of private services.
class
ProductKnowledgeReconcileFailure(pydantic.main.BaseModel):
1744class ProductKnowledgeReconcileFailure(BaseModel): 1745 """ 1746 One stamped customer whose product-knowledge tool update did not converge. 1747 """ 1748 1749 customer_key: str = Field( 1750 ..., description="Stable vendor-defined key for the customer whose agent did not converge." 1751 ) 1752 error: str = Field(..., description="Stable failure reason for operator and vendor feedback.") 1753 retryable: bool = Field( 1754 ..., description="Whether rerunning the desired-state reconciliation is safe." 1755 )
One stamped customer whose product-knowledge tool update did not converge.
class
ProductKnowledgeReconcileResponse(pydantic.main.BaseModel):
1758class ProductKnowledgeReconcileResponse(BaseModel): 1759 """ 1760 Desired-state reconciliation result for a CM install's stamped agents. 1761 """ 1762 1763 complete: bool = Field( 1764 ..., 1765 description="True when every stamped customer agent now has the desired source allowlist.", 1766 ) 1767 failures: list[ProductKnowledgeReconcileFailure] = Field( 1768 ..., description="Per-customer failures. Empty when reconciliation is complete." 1769 ) 1770 reconciled_customers: list[str] = Field( 1771 ..., description="Customer keys whose agent tool config is converged." 1772 )
Desired-state reconciliation result for a CM install's stamped agents.
complete: bool =
PydanticUndefined
True when every stamped customer agent now has the desired source allowlist.
class
RoutinePreset(pydantic.main.BaseModel):
1775class RoutinePreset(BaseModel): 1776 """ 1777 A named preset that defines the execution model and constraints for a routine. Presets are shared definitions; individual routines reference a preset by name. 1778 """ 1779 1780 applicable_events: list[str] = Field( 1781 ..., 1782 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.', 1783 ) 1784 chainable: bool = Field( 1785 ..., 1786 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.", 1787 ) 1788 description: str = Field( 1789 ..., description="Human-readable description of what the preset does and when to use it." 1790 ) 1791 label: str = Field( 1792 ..., description="Human-readable display name for the preset, suitable for use in UIs." 1793 ) 1794 name: str = Field( 1795 ..., 1796 description='Stable machine identifier for the preset, e.g. `"do_task"`. Used when assigning a preset to a routine.', 1797 ) 1798 sessionable: bool = Field( 1799 ..., 1800 description="Whether the preset runs inside the thread conversation-session lifecycle. This is distinct from preset_config.session_mode, which controls durable session reuse for do_task and send_message.", 1801 ) 1802 unique: bool = Field( 1803 ..., 1804 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.", 1805 )
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
WorkflowJournalEntry(pydantic.main.BaseModel):
1808class WorkflowJournalEntry(BaseModel): 1809 """ 1810 One ordered, replayable record from a durable workflow journal. 1811 """ 1812 1813 command_id: str | None = Field( 1814 default=None, 1815 description="Durable command identifier associated with the record, when present.", 1816 ) 1817 created_at: datetime | None = Field( 1818 default=None, description="When this entry was durably committed." 1819 ) 1820 id: str = Field(..., description="Journal entry ID (`wdr_...`).") 1821 node_id: str | None = Field( 1822 default=None, 1823 description="Workflow node associated with the record. `null` for execution-level records.", 1824 ) 1825 record: dict[str, Any] = Field( 1826 ..., 1827 description="Replayable workflow record body, including payload, context, environment, metadata, and timestamp.", 1828 ) 1829 sequence: int = Field(..., description="Monotonically increasing sequence within the journal.") 1830 timer_id: str | None = Field( 1831 default=None, 1832 description="Durable timer identifier associated with the record, when present.", 1833 ) 1834 type: str = Field( 1835 ..., 1836 description="Workflow record type, such as `node_started`, `node_completed`, or `node_failed`.", 1837 )
One ordered, replayable record from a durable workflow journal.
node_id: str | None =
None
Workflow node associated with the record. null for execution-level records.
class
WorkflowJournal(pydantic.main.BaseModel):
1840class WorkflowJournal(BaseModel): 1841 """ 1842 Summary of the durable workflow execution journal associated with a run. 1843 """ 1844 1845 completed_at: datetime | None = Field( 1846 default=None, 1847 description="When durable workflow execution reached a terminal state. `null` while it is active.", 1848 ) 1849 created_at: datetime | None = Field(default=None, description="When the journal was created.") 1850 current_sequence: int = Field( 1851 ..., description="Highest workflow record sequence durably committed to this journal." 1852 ) 1853 id: str = Field(..., description="Journal execution ID (`wde_...`).") 1854 started_at: datetime | None = Field( 1855 default=None, description="When durable workflow execution started." 1856 ) 1857 status: str = Field( 1858 ..., 1859 description="Current durable execution status: `pending`, `running`, `waiting`, `completed`, `failed`, or `cancelled`.", 1860 ) 1861 updated_at: datetime | None = Field( 1862 default=None, description="When the journal was last updated." 1863 )
Summary of the durable workflow execution journal associated with a run.
completed_at: datetime.datetime | None =
None
When durable workflow execution reached a terminal state. null while it is active.
current_sequence: int =
PydanticUndefined
Highest workflow record sequence durably committed to this journal.
class
RunJournalPage(pydantic.main.BaseModel):
1866class RunJournalPage(BaseModel): 1867 """ 1868 A forward-paginated journal entry page for an automation or routine run. 1869 """ 1870 1871 after_cursor: str | None = Field( 1872 default=None, 1873 description="Opaque cursor for the next entry page. `null` when this is the final page.", 1874 ) 1875 before_cursor: str | None = Field( 1876 default=None, description="Always `null`; journal pagination is forward-only." 1877 ) 1878 data: list[WorkflowJournalEntry] = Field( 1879 ..., 1880 description="Journal entries ordered by ascending sequence. Empty when the run has no journal.", 1881 ) 1882 has_more: bool = Field(..., description="Whether additional entries exist after this page.") 1883 journal: WorkflowJournal | None = Field( 1884 default=None, 1885 description="Durable execution summary. `null` when this run has no journal, which is valid for script-backed, preview, or legacy runs.", 1886 )
A forward-paginated journal entry page for an automation or routine run.
after_cursor: str | None =
None
Opaque cursor for the next entry page. null when this is the final page.
class
SandboxKey(pydantic.main.BaseModel):
1889class SandboxKey(BaseModel): 1890 """ 1891 An API key scoped to a developer sandbox, used to authenticate requests against sandbox resources. 1892 """ 1893 1894 created_at: datetime | None = Field( 1895 default=None, description="When this key was created (ISO 8601)." 1896 ) 1897 expires_at: datetime | None = Field( 1898 default=None, 1899 description="When this key expires and becomes invalid. `null` if the key does not expire.", 1900 ) 1901 full_key: str | None = Field( 1902 default=None, 1903 description="The complete secret key value, returned only once when the key is first created. `null` on subsequent retrievals.", 1904 ) 1905 id: str = Field(..., description="Sandbox key ID (`dsk_...`).") 1906 key_hint: str | None = Field( 1907 default=None, 1908 description="A short hint showing the last four characters of the key, used for identification. `null` if no hint is available.", 1909 ) 1910 key_value: str | None = Field( 1911 default=None, 1912 description='The full key value for `"publishable"` keys. `null` for `"secret"` keys; use `full_key` instead, which is returned only at creation time.', 1913 ) 1914 last_used_at: datetime | None = Field( 1915 default=None, 1916 description="When this key was last used to authenticate a request. `null` if the key has never been used.", 1917 ) 1918 status: str = Field( 1919 ..., 1920 description='Current lifecycle status of the key. One of `"active"` (usable) or `"revoked"` (permanently disabled).', 1921 ) 1922 type: str = Field( 1923 ..., 1924 description='The kind of key. One of `"publishable"` (safe for client-side use) or `"secret"` (server-side only).', 1925 )
An API key scoped to a developer sandbox, used to authenticate requests against sandbox resources.
expires_at: datetime.datetime | None =
None
When this key expires and becomes invalid. null if the key does not expire.
full_key: str | None =
None
The complete secret key value, returned only once when the key is first created. null on subsequent retrievals.
key_hint: str | None =
None
A short hint showing the last four characters of the key, used for identification. null if no hint is available.
key_value: str | None =
None
The full key value for "publishable" keys. null for "secret" keys; use full_key instead, which is returned only at creation time.
last_used_at: datetime.datetime | None =
None
When this key was last used to authenticate a request. null if the key has never been used.
class
Sandbox(pydantic.main.BaseModel):
1928class Sandbox(BaseModel): 1929 """ 1930 An isolated developer sandbox environment used for testing integrations without affecting production data or sending real emails. 1931 """ 1932 1933 created_at: datetime | None = Field( 1934 default=None, description="When this sandbox was created (ISO 8601)." 1935 ) 1936 expires_at: datetime | None = Field( 1937 default=None, 1938 description="When an eval sandbox expires and becomes eligible for platform cleanup. `null` for ordinary developer sandboxes.", 1939 ) 1940 id: str = Field(..., description="Sandbox ID (`dsb_...`).") 1941 keys: list[SandboxKey] | None = Field( 1942 default=None, 1943 description="API keys associated with this sandbox. `null` if keys were not loaded with this response.", 1944 ) 1945 name: str = Field(..., description="Human-readable display name for the sandbox.") 1946 org: str | None = Field( 1947 default=None, 1948 description="Organization ID this sandbox is scoped to, or `null` for an app-level sandbox.", 1949 ) 1950 org_logo: ImageSource | None = Field( 1951 default=None, description="Logo of the owning organization, when present." 1952 ) 1953 org_name: str | None = Field( 1954 default=None, description="Display name of the owning organization, when org-scoped." 1955 ) 1956 purpose: str | None = Field( 1957 default=None, 1958 description='Sandbox purpose marker. `"eval"` marks a remote-eval sandbox; `null` for ordinary developer sandboxes.', 1959 ) 1960 slug: str = Field( 1961 ..., 1962 description='URL-safe identifier for the sandbox, unique within the application (e.g. `"my-sandbox"`).', 1963 ) 1964 updated_at: datetime | None = Field( 1965 default=None, description="When this sandbox was last modified (ISO 8601)." 1966 )
An isolated developer sandbox environment used for testing integrations without affecting production data or sending real emails.
expires_at: datetime.datetime | None =
None
When an eval sandbox expires and becomes eligible for platform cleanup. null for ordinary developer sandboxes.
purpose: str | None =
None
Sandbox purpose marker. "eval" marks a remote-eval sandbox; null for ordinary developer sandboxes.
class
SlackChannelBinding(pydantic.main.BaseModel):
1969class SlackChannelBinding(BaseModel): 1970 """ 1971 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. 1972 """ 1973 1974 agents: list[str] | None = Field( 1975 default=None, 1976 description="IDs of every agent attached to this binding, including legacy concierge attachments. Use `resident_agent` and `route_kind` for the effective runtime route.", 1977 ) 1978 allow_bot_conversations: bool = Field( 1979 ..., 1980 description="Whether this channel opts into sustained bot-to-bot conversation, exempting it from the reply loop brake. Defaults to `false`.", 1981 ) 1982 channel: str | None = Field( 1983 default=None, description="Slack channel ID (e.g. `C01234ABCDE`) that this binding targets." 1984 ) 1985 customer_label: str | None = Field( 1986 default=None, 1987 description="Human-readable label identifying the customer, derived from the binding's embedded config. `null` when not set.", 1988 ) 1989 deposit_thread: str | None = Field( 1990 default=None, 1991 description="Staging thread the deposit pipe copies this channel's mirror content into (`thr_ ` public ID). `null` when the pipe is off for this binding.", 1992 ) 1993 disclosure_state: Literal["pending", "posted", "suppressed"] | None = Field( 1994 default=None, 1995 description="Slack Connect lifecycle: `pending` while the customer has not accepted the invite (nothing mirrors), `posted` once the AI disclosure is in the channel and the channel is live, `suppressed` when relay is stopped. `null` for a binding that never went through Connect provisioning.", 1996 ) 1997 id: str = Field(..., description="Unique identifier for this Slack channel binding.") 1998 integration: str | None = Field( 1999 default=None, description="ID of the Slack integration that owns this binding." 2000 ) 2001 is_ext_shared_cached: bool | None = Field( 2002 default=None, 2003 description="Cached value of Slack's `is_ext_shared` flag for this channel. May be stale relative to Slack's current state.", 2004 ) 2005 is_private_cached: bool | None = Field( 2006 default=None, 2007 description="Cached value of Slack's `is_private` flag for this channel. May be stale relative to Slack's current state. Private channels are member-managed: mutating the binding requires in-channel evidence.", 2008 ) 2009 mirrors: list[str] | None = Field( 2010 default=None, 2011 description="IDs of every mirror thread this channel's messages land in (`thr_ ` public IDs) that the caller can read, including any legacy peel or chain threads. Empty for a caller with no membership on any of them, and for a channel that has not mirrored anything yet. IDs only: reading a mirror's contents still requires membership on it.", 2012 ) 2013 muted: bool = Field( 2014 ..., 2015 description="Whether the resident agent is currently muted. A muted resident keeps mirroring the channel (reading) but stops replying. A timed mute expires automatically at `muted_until`; this reflects the effective state as of now. Defaults to `false`.", 2016 ) 2017 muted_until: str | None = Field( 2018 default=None, 2019 description="ISO 8601 timestamp when a timed mute expires and replies resume. `null` for an indefinite mute (until an explicit unmute) or when not muted.", 2020 ) 2021 reply_style: str = Field( 2022 ..., 2023 description="How the resident agent's replies post to Slack: `thread` (default) threads a reply under the message that triggered it; `top_level` posts it flat in the channel.", 2024 ) 2025 resident_agent: str | None = Field( 2026 default=None, 2027 description="ID of the resident agent selected by Slack ingress. `null` when no resident is attached and the channel is an observer.", 2028 ) 2029 route_kind: Literal["fda", "resident", "observer", "concierge"] = Field( 2030 ..., 2031 description="Effective Slack ingress route. `fda` a resident on a team-bound channel, replying through the Forward Deployed Agent chain. `resident` a resident on an internal channel, replying through the channel mirror. `observer` no resident is attached, so the channel is recorded and nobody replies. `concierge` no longer returned anywhere; until Track F it was the value for a channel with no resident, meaning the shared concierge agent answered there. The value is retained in this enum so consumers matching on it do not break, and its removal rides a deliberate API change.", 2032 ) 2033 scope_key: str | None = Field( 2034 default=None, 2035 description="The customer key this channel's agent is locked to, written when adding the customer finishes. A `posted` binding whose `scope_key` is still null has been accepted but not finished the addition is either in flight or was refused.", 2036 ) 2037 team: str | None = Field( 2038 default=None, description="ID of the ArchAstro team this channel is bound to." 2039 ) 2040 vendor_admin_channel_access: ( 2041 Literal["invited", "already_member", "no_slack_user", "failed"] | None 2042 ) = Field( 2043 default=None, 2044 description="Whether the admin who added this customer ended up inside a Connect channel we created for them: `invited` (we put them in), `already_member` (they were in it already), `no_slack_user` (their account email is not a Slack account in your workspace, so nobody was invited), or `failed` (Slack refused). A created Connect channel is private and has no self-join, so the last two mean the channel has no human from your side until someone already in it adds one. `null` when nobody was added: the channel was adopted rather than created (an existing channel already has its own members), the binding never went through Connect provisioning, or the call had no admin behind it.", 2045 )
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 every agent attached to this binding, including legacy concierge attachments. Use resident_agent and route_kind for the effective runtime route.
allow_bot_conversations: bool =
PydanticUndefined
Whether this channel opts into sustained bot-to-bot conversation, exempting it from the reply loop brake. Defaults to false.
customer_label: str | None =
None
Human-readable label identifying the customer, derived from the binding's embedded config. null when not set.
deposit_thread: str | None =
None
Staging thread the deposit pipe copies this channel's mirror content into (thr_ public ID). null when the pipe is off for this binding.
disclosure_state: Optional[Literal['pending', 'posted', 'suppressed']] =
None
Slack Connect lifecycle: pending while the customer has not accepted the invite (nothing mirrors), posted once the AI disclosure is in the channel and the channel is live, suppressed when relay is stopped. null for a binding that never went through Connect provisioning.
is_private_cached: bool | None =
None
Cached value of Slack's is_private flag for this channel. May be stale relative to Slack's current state. Private channels are member-managed: mutating the binding requires in-channel evidence.
mirrors: list[str] | None =
None
IDs of every mirror thread this channel's messages land in (thr_ public IDs) that the caller can read, including any legacy peel or chain threads. Empty for a caller with no membership on any of them, and for a channel that has not mirrored anything yet. IDs only: reading a mirror's contents still requires membership on it.
muted: bool =
PydanticUndefined
Whether the resident agent is currently muted. A muted resident keeps mirroring the channel (reading) but stops replying. A timed mute expires automatically at muted_until; this reflects the effective state as of now. Defaults to false.
muted_until: str | None =
None
ISO 8601 timestamp when a timed mute expires and replies resume. null for an indefinite mute (until an explicit unmute) or when not muted.
reply_style: str =
PydanticUndefined
How the resident agent's replies post to Slack: thread (default) threads a reply under the message that triggered it; top_level posts it flat in the channel.
resident_agent: str | None =
None
ID of the resident agent selected by Slack ingress. null when no resident is attached and the channel is an observer.
route_kind: Literal['fda', 'resident', 'observer', 'concierge'] =
PydanticUndefined
Effective Slack ingress route. fda a resident on a team-bound channel, replying through the Forward Deployed Agent chain. resident a resident on an internal channel, replying through the channel mirror. observer no resident is attached, so the channel is recorded and nobody replies. concierge no longer returned anywhere; until Track F it was the value for a channel with no resident, meaning the shared concierge agent answered there. The value is retained in this enum so consumers matching on it do not break, and its removal rides a deliberate API change.
scope_key: str | None =
None
The customer key this channel's agent is locked to, written when adding the customer finishes. A posted binding whose scope_key is still null has been accepted but not finished the addition is either in flight or was refused.
vendor_admin_channel_access: Optional[Literal['invited', 'already_member', 'no_slack_user', 'failed']] =
None
Whether the admin who added this customer ended up inside a Connect channel we created for them: invited (we put them in), already_member (they were in it already), no_slack_user (their account email is not a Slack account in your workspace, so nobody was invited), or failed (Slack refused). A created Connect channel is private and has no self-join, so the last two mean the channel has no human from your side until someone already in it adds one. null when nobody was added: the channel was adopted rather than created (an existing channel already has its own members), the binding never went through Connect provisioning, or the call had no admin behind it.
class
SlackChannelBindingListResponse(pydantic.main.BaseModel):
2048class SlackChannelBindingListResponse(BaseModel): 2049 """ 2050 Paginated list of Slack channel bindings for the requested integration or team. Use the `page` and `per_page` fields to navigate pages of results. 2051 """ 2052 2053 data: list[SlackChannelBinding] = Field( 2054 ..., description="Array of Slack channel binding objects for the current page." 2055 ) 2056 page: int = Field(..., description="Current page number (1-indexed).") 2057 per_page: int = Field(..., description="Maximum number of bindings returned per page.") 2058 total_count: int = Field( 2059 ..., 2060 description="Total number of Slack channel bindings matching the query across all pages.", 2061 ) 2062 total_pages: int = Field( 2063 ..., description="Total number of pages available at the current `per_page` size." 2064 )
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
SlackDeliveryOutcome(pydantic.main.BaseModel):
2067class SlackDeliveryOutcome(BaseModel): 2068 """ 2069 What happened to one agent message this platform sent to a Slack channel. Lets you confirm delivery, or find out why a reply never arrived, without reading the channel's mirrored conversation. 2070 """ 2071 2072 agent: str | None = Field(default=None, description="ID of the agent whose message this was.") 2073 binding: str | None = Field( 2074 default=None, 2075 description="ID of the Slack channel binding in force for this send. `null` when no binding could be resolved, in which case the send was treated as cross-org and floored on that basis.", 2076 ) 2077 channel: str = Field(..., description="Slack channel ID the send was addressed to.") 2078 failure_reason: str | None = Field( 2079 default=None, 2080 description="For a `failed` send, a short machine-readable cause `slack:<slack_error_code>` when Slack rejected the call, or `floor_config` when the content floor could not be evaluated and the send failed closed.", 2081 ) 2082 guard_kind: str | None = Field( 2083 default=None, 2084 description="For a withheld send, the kind of guard that stopped it `RegexMatch`, `ContainsAny`, `ContainsString`, or `LLMJudge`. `null` when the send was not withheld by a guard.", 2085 ) 2086 guard_labels: list[str] | None = Field( 2087 default=None, 2088 description="For a withheld send, the labels of the guards that stopped it (for example `Contains AWS access key ID`). These are the content policy's own descriptions, recorded as they read at the time of the send; they never contain the withheld message.", 2089 ) 2090 id: str = Field(..., description="Unique identifier for this delivery outcome.") 2091 message: str | None = Field( 2092 default=None, 2093 description="ID of the platform message this attempt was carrying. Reading that message still requires access to its thread this field correlates, it does not grant.", 2094 ) 2095 operation: Literal["post", "post_ephemeral", "update"] = Field( 2096 ..., 2097 description="Which Slack call the attempt made. `post` a new message in the channel, visible to everyone in it. `post_ephemeral` a message only one named channel member could see; Slack returns no durable timestamp for one, so it has no `thread_ts` to correlate and cannot be found in the channel's history afterwards. `update` replacing an existing message (typically a thinking placeholder).", 2098 ) 2099 outcome: Literal["delivered", "floored", "judge_refused", "failed"] = Field( 2100 ..., 2101 description="What happened to the send. `delivered` Slack accepted the message. `floored` a deterministic content guard withheld it, so it never left. `judge_refused` the cross-org judge decided it was not appropriate for this channel's audience. `failed` Slack rejected the call, or the content floor could not be evaluated and the send failed closed.", 2102 ) 2103 recorded_at: datetime = Field(..., description="When the send was attempted.") 2104 thread_ts: str | None = Field( 2105 default=None, 2106 description="Slack thread timestamp the send targeted, letting attempts be grouped into the conversation they belong to. `null` for a top-level channel post.", 2107 )
What happened to one agent message this platform sent to a Slack channel. Lets you confirm delivery, or find out why a reply never arrived, without reading the channel's mirrored conversation.
binding: str | None =
None
ID of the Slack channel binding in force for this send. null when no binding could be resolved, in which case the send was treated as cross-org and floored on that basis.
failure_reason: str | None =
None
For a failed send, a short machine-readable cause slack:<slack_error_code> when Slack rejected the call, or floor_config when the content floor could not be evaluated and the send failed closed.
guard_kind: str | None =
None
For a withheld send, the kind of guard that stopped it RegexMatch, ContainsAny, ContainsString, or LLMJudge. null when the send was not withheld by a guard.
guard_labels: list[str] | None =
None
For a withheld send, the labels of the guards that stopped it (for example Contains AWS access key ID). These are the content policy's own descriptions, recorded as they read at the time of the send; they never contain the withheld message.
message: str | None =
None
ID of the platform message this attempt was carrying. Reading that message still requires access to its thread this field correlates, it does not grant.
operation: Literal['post', 'post_ephemeral', 'update'] =
PydanticUndefined
Which Slack call the attempt made. post a new message in the channel, visible to everyone in it. post_ephemeral a message only one named channel member could see; Slack returns no durable timestamp for one, so it has no thread_ts to correlate and cannot be found in the channel's history afterwards. update replacing an existing message (typically a thinking placeholder).
outcome: Literal['delivered', 'floored', 'judge_refused', 'failed'] =
PydanticUndefined
What happened to the send. delivered Slack accepted the message. floored a deterministic content guard withheld it, so it never left. judge_refused the cross-org judge decided it was not appropriate for this channel's audience. failed Slack rejected the call, or the content floor could not be evaluated and the send failed closed.
class
SlackDeliveryOutcomeListResponse(pydantic.main.BaseModel):
2110class SlackDeliveryOutcomeListResponse(BaseModel): 2111 """ 2112 A page of delivery outcomes for one Slack channel, newest first. Page through history with the returned cursors; `since` and `outcome` are filters, not paging controls. 2113 """ 2114 2115 after_cursor: str | None = Field( 2116 default=None, 2117 description="Opaque cursor for the page of newer outcomes. Pass back as `after_cursor` to poll for attempts recorded since. `null` when the page is empty.", 2118 ) 2119 before_cursor: str | None = Field( 2120 default=None, 2121 description="Opaque cursor for the page of older outcomes. Pass back as `before_cursor` to continue into history. `null` when the page is empty.", 2122 ) 2123 data: list[SlackDeliveryOutcome] = Field( 2124 ..., description="Delivery outcomes matching the query, newest attempt first." 2125 ) 2126 has_more: bool = Field(..., description="True when more outcomes exist beyond this page.")
A page of delivery outcomes for one Slack channel, newest first. Page through history with the returned cursors; since and outcome are filters, not paging controls.
after_cursor: str | None =
None
Opaque cursor for the page of newer outcomes. Pass back as after_cursor to poll for attempts recorded since. null when the page is empty.
before_cursor: str | None =
None
Opaque cursor for the page of older outcomes. Pass back as before_cursor to continue into history. null when the page is empty.
class
Trajectory(pydantic.main.BaseModel):
2129class Trajectory(BaseModel): 2130 """ 2131 A recorded sequence of AI messages and tool interactions representing a single AI reasoning session. Trajectories are stored as structured message logs and can be replayed or inspected after execution. 2132 """ 2133 2134 created_at: str | None = Field( 2135 default=None, description="When the trajectory was recorded (ISO 8601)." 2136 ) 2137 file: str | None = Field( 2138 default=None, 2139 description="ID of the storage file that persists the raw trajectory data (`fil_...`).", 2140 ) 2141 id: str = Field(..., description="Trajectory ID (`trj_...`).") 2142 messages: list[dict[str, Any]] | None = Field( 2143 default=None, 2144 description="Serialized message log for this trajectory. Contains the ordered sequence of AI and tool messages produced during the session.", 2145 ) 2146 org: str | None = Field( 2147 default=None, 2148 description="ID of the organization this trajectory belongs to (`org_...`). `null` for trajectories outside an org context.", 2149 ) 2150 sandbox: str | None = Field( 2151 default=None, 2152 description="ID of the developer sandbox this trajectory is scoped to (`sbx_...`). `null` for production trajectories.", 2153 ) 2154 team: str | None = Field( 2155 default=None, 2156 description="ID of the team this trajectory is scoped to (`team_...`). `null` for trajectories not associated with a team.", 2157 ) 2158 updated_at: str | None = Field( 2159 default=None, description="When the trajectory record was last updated (ISO 8601)." 2160 )
A recorded sequence of AI messages and tool interactions representing a single AI reasoning session. Trajectories are stored as structured message logs and can be replayed or inspected after execution.
messages: list[dict[str, typing.Any]] | None =
None
Serialized message log for this trajectory. Contains the ordered sequence of AI and tool messages produced during the session.
org: str | None =
None
ID of the organization this trajectory belongs to (org_...). null for trajectories outside an org context.
sandbox: str | None =
None
ID of the developer sandbox this trajectory is scoped to (sbx_...). null for production trajectories.
class
ValidationResult(pydantic.main.BaseModel):
2163class ValidationResult(BaseModel): 2164 """ 2165 The result of a configuration validation check, indicating whether the config is valid and listing any errors or warnings. 2166 """ 2167 2168 errors: list[str] | None = Field( 2169 default=None, 2170 description="List of human-readable error messages describing why validation failed. Empty or absent when `valid` is `true`.", 2171 ) 2172 valid: bool = Field( 2173 ..., 2174 description="`true` if the configuration passed all validation checks, `false` if one or more errors were found.", 2175 ) 2176 warnings: list[str] | None = Field( 2177 default=None, 2178 description="List of human-readable warning messages emitted during validation. Warnings do not cause `valid` to be `false` but indicate potentially problematic configuration.", 2179 )
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
WorkflowWorkItem(pydantic.main.BaseModel):
2182class WorkflowWorkItem(BaseModel): 2183 """ 2184 Externally executable work yielded by a durable workflow. 2185 """ 2186 2187 agent: str = Field(..., description="Agent assigned to execute this work.") 2188 attempt_count: int = Field( 2189 ..., description="Number of times this work has been freshly claimed or reclaimed." 2190 ) 2191 command_id: str = Field( 2192 ..., description="Opaque journal command identity used to resume the workflow exactly once." 2193 ) 2194 created_at: datetime 2195 execution: str = Field(..., description="Durable workflow execution that owns this work.") 2196 id: str = Field(..., description="Work item ID (`wdi_...`).") 2197 lease_expires_at: datetime | None = Field( 2198 default=None, 2199 description="When the current claim expires. Null for queued or terminal work.", 2200 ) 2201 node_id: str = Field(..., description="Workflow graph node that yielded the work.") 2202 payload: dict[str, Any] = Field( 2203 ..., description="Instructions and participant bindings needed to execute the work." 2204 ) 2205 routine_run: str | None = Field( 2206 default=None, 2207 description="Routine run that owns the execution, when this work came from a routine.", 2208 ) 2209 status: str = Field(..., description="Current queue lifecycle status.") 2210 type: str = Field( 2211 ..., description="Stable resource discriminator. Always `workflow_work_item`." 2212 ) 2213 updated_at: datetime
Externally executable work yielded by a durable workflow.
attempt_count: int =
PydanticUndefined
Number of times this work has been freshly claimed or reclaimed.
command_id: str =
PydanticUndefined
Opaque journal command identity used to resume the workflow exactly once.
lease_expires_at: datetime.datetime | None =
None
When the current claim expires. Null for queued or terminal work.
payload: dict[str, typing.Any] =
PydanticUndefined
Instructions and participant bindings needed to execute the work.
class
WorkflowWorkItemLease(pydantic.main.BaseModel):
2216class WorkflowWorkItemLease(BaseModel): 2217 """ 2218 A claimed workflow work item and its caller-held lease token. 2219 """ 2220 2221 lease_owner: str = Field( 2222 ..., 2223 description="Opaque lease token that must be persisted and presented for later transitions.", 2224 ) 2225 work_item: WorkflowWorkItem = Field( 2226 ..., description="The claimed, resumed, started, or heartbeated work item." 2227 )
A claimed workflow work item and its caller-held lease token.
lease_owner: str =
PydanticUndefined
Opaque lease token that must be persisted and presented for later transitions.
class
WorkflowWorkItemClaim(pydantic.main.BaseModel):
2230class WorkflowWorkItemClaim(BaseModel): 2231 """ 2232 Result of polling an agent's durable workflow work queue. 2233 """ 2234 2235 data: WorkflowWorkItemLease | None = Field( 2236 default=None, 2237 description="Claimed or resumed work and its lease; null when no eligible item exists.", 2238 )
Result of polling an agent's durable workflow work queue.
class
WorkflowWorkItemList(pydantic.main.BaseModel):
2241class WorkflowWorkItemList(BaseModel): 2242 """ 2243 Active durable workflow work available to the viewer. 2244 """ 2245 2246 after_cursor: str | None = Field( 2247 default=None, description="Opaque cursor for the next page, or null at the end." 2248 ) 2249 before_cursor: str | None = Field( 2250 default=None, description="Always null because queue pagination is forward-only." 2251 ) 2252 data: list[WorkflowWorkItem] = Field( 2253 ..., 2254 description="Active work items. Lease tokens are intentionally never included in list responses.", 2255 ) 2256 has_more: bool = Field(..., description="Whether another page of work exists.")
Active durable workflow work available to the viewer.
class
WorkingMemoryEntry(pydantic.main.BaseModel):
2259class WorkingMemoryEntry(BaseModel): 2260 """ 2261 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. 2262 """ 2263 2264 agent: str | None = Field( 2265 default=None, description="ID of the agent that owns this memory entry (`agt_...`)." 2266 ) 2267 created_at: datetime | None = Field( 2268 default=None, description="When this memory entry was first written (ISO 8601)." 2269 ) 2270 expires_at: datetime | None = Field( 2271 default=None, 2272 description="When this entry will be automatically deleted. `null` if the entry does not expire.", 2273 ) 2274 id: str = Field(..., description="Working memory entry ID (`amm_...`).") 2275 key: str | None = Field( 2276 default=None, 2277 description="The string key used to look up this memory entry within the agent's memory namespace.", 2278 ) 2279 updated_at: datetime | None = Field( 2280 default=None, description="When this memory entry was last modified (ISO 8601)." 2281 ) 2282 value: str | None = Field( 2283 default=None, 2284 description="The string value stored under `key`. May be any serialized content the agent wrote.", 2285 )
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):
2288class WorkingMemoryEntryListResponse(BaseModel): 2289 """ 2290 Paginated list of working memory entries stored for an agent. Includes page metadata to support sequential page traversal. 2291 """ 2292 2293 data: list[WorkingMemoryEntry] = Field( 2294 ..., description="Array of working memory entry objects for the current page." 2295 ) 2296 has_next: bool | None = Field( 2297 default=None, 2298 description="`true` if a subsequent page exists and can be fetched by incrementing the page number.", 2299 ) 2300 has_prev: bool | None = Field( 2301 default=None, 2302 description="`true` if a previous page exists and can be fetched by decrementing the page number.", 2303 ) 2304 page: int | None = Field(default=None, description="The current page number, starting at `1`.") 2305 page_size: int | None = Field( 2306 default=None, description="Maximum number of entries returned per page." 2307 ) 2308 total_entries: int | None = Field( 2309 default=None, 2310 description="Total number of working memory entries matching the query across all pages.", 2311 ) 2312 total_pages: int | None = Field( 2313 default=None, description="Total number of pages given the current `page_size`." 2314 )
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
SolutionAutomationInvokeContract(pydantic.main.BaseModel):
2317class SolutionAutomationInvokeContract(BaseModel): 2318 """ 2319 The schema-driven values an installer may lock when provisioning an invoked automation template. 2320 """ 2321 2322 input_schema: dict[str, Any] | None = Field( 2323 default=None, 2324 description="JSON Schema validated against the whole invoke payload, from the automation's `input_schema_config`. `null` when none is configured.", 2325 ) 2326 participants: list[AutomationParticipantSlot] | None = Field( 2327 default=None, 2328 description="Named participant slots declared by the workflow, sorted by name. `null` when the workflow declares none. Values supplied under the top-level `participants` field are agent IDs.", 2329 ) 2330 prefills: AutomationPrefills = Field( 2331 ..., 2332 description="Owner-controlled payload and participant values the platform applies to every invocation. Supplying a conflicting value is rejected.", 2333 )
The schema-driven values an installer may lock when provisioning an invoked automation template.
input_schema: dict[str, typing.Any] | None =
None
JSON Schema validated against the whole invoke payload, from the automation's input_schema_config. null when none is configured.
Named participant slots declared by the workflow, sorted by name. null when the workflow declares none. Values supplied under the top-level participants field are agent IDs.
class
SolutionAutomationTemplateDetails(pydantic.main.BaseModel):
2336class SolutionAutomationTemplateDetails(BaseModel): 2337 """ 2338 AutomationTemplate-specific details exposed by a Solution template summary. 2339 """ 2340 2341 automation_type: str | None = Field( 2342 default=None, 2343 description="Automation execution type (`invoked`, `scheduled`, or `trigger`). `null` when the template body does not declare one.", 2344 ) 2345 invoke_contract: SolutionAutomationInvokeContract | None = Field( 2346 default=None, 2347 description="Schema-driven payload and participant inputs for an invoked automation. Used by installation clients to collect locked prefills before provisioning. `null` for non-invoked automation types.", 2348 ) 2349 type: Literal["automation"] = Field( 2350 default="automation", 2351 description="Template-details discriminator. Always `automation` for this variant.", 2352 )
AutomationTemplate-specific details exposed by a Solution template summary.
automation_type: str | None =
None
Automation execution type (invoked, scheduled, or trigger). null when the template body does not declare one.
SolutionTemplateDetails =
typing.Annotated[SolutionAutomationTemplateDetails, FieldInfo(annotation=NoneType, required=True, discriminator='type')]
class
SolutionTemplateSummary(pydantic.main.BaseModel):
2359class SolutionTemplateSummary(BaseModel): 2360 """ 2361 Identity and display metadata for a single template bundled by a Solution, used to represent each wrapped or sibling template at template granularity. 2362 """ 2363 2364 description: str | None = Field( 2365 default=None, 2366 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.", 2367 ) 2368 details: SolutionTemplateDetails | None = Field( 2369 default=None, 2370 description="Template-kind-specific details selected by the `type` discriminator. `null` when this template kind has no additional details.", 2371 ) 2372 display_name: str | None = Field( 2373 default=None, 2374 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`.", 2375 ) 2376 id: str | None = Field( 2377 default=None, 2378 description="Template config ID (`cfg_...`). `null` for inline-only templates.", 2379 ) 2380 kind: str = Field( 2381 ..., 2382 description="Template config kind, or `SolutionTemplateRef` / `SolutionTemplatePath` when unresolved.", 2383 ) 2384 lookup_key: str | None = Field( 2385 default=None, 2386 description="Lookup key stamped on the template config at import time. `null` when no lookup key was assigned.", 2387 ) 2388 name: str | None = Field( 2389 default=None, 2390 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`.", 2391 ) 2392 readme_url: str | None = Field( 2393 default=None, 2394 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`.", 2395 ) 2396 virtual_path: str | None = Field( 2397 default=None, 2398 description="Stable virtual path assigned to the template config. `null` when no virtual path was set.", 2399 )
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.
details: Optional[Annotated[SolutionAutomationTemplateDetails, FieldInfo(annotation=NoneType, required=True, discriminator='type')]] =
None
Template-kind-specific details selected by the type discriminator. null when this template kind has no additional details.
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):
2402class SolutionSummary(BaseModel): 2403 """ 2404 A catalog entry for an imported Solution, including its display metadata, bundled templates, owner scopes, and any available upgrade information. 2405 """ 2406 2407 category_keys: list[str] | None = Field( 2408 default=None, 2409 description="Category tag keys declared in the Solution body, used to group Solutions in the catalog. An empty array when the body declares none.", 2410 ) 2411 created_at: str | None = Field( 2412 default=None, description="When the Solution config was first imported (ISO 8601)." 2413 ) 2414 description: str | None = Field( 2415 default=None, 2416 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.", 2417 ) 2418 events: dict[str, Any] | None = Field( 2419 default=None, 2420 description="Custom analytics events declared in the Solution body's `events:` manifest a map of event key (snake_case) to its definition (`label`, optional `description`, optional typed `fields`). Dashboards use the `label` as the event's display name. Present as an empty object when the body declares none.", 2421 ) 2422 id: str = Field(..., description="Solution config ID (`cfg_...`).") 2423 image_url: str | None = Field( 2424 default=None, 2425 description="Absolute URL of the Solution's cover image the bundled asset the body's `image:` field names. A stable, non-expiring capability URL (like `org_logo.url`), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. `null` when the Solution has no cover image, and always `null` for org-scoped rows the permanent URL is minted for system-scope (catalog) Solutions only.", 2426 ) 2427 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 2428 latest_solution: str | None = Field( 2429 default=None, 2430 description="When `upgrade_available` is `true`, the system-scope Solution config ID (`cfg_...`) that should be used as the upgrade source. `null` otherwise.", 2431 ) 2432 latest_version: str | None = Field( 2433 default=None, 2434 description="When `upgrade_available` is `true`, the higher system-scope `solution_version` available to upgrade to. `null` otherwise.", 2435 ) 2436 lookup_key: str | None = Field( 2437 default=None, 2438 description="The lookup key stored on the Solution config, if one was assigned during import. `null` when no lookup key was set.", 2439 ) 2440 metadata: dict[str, Any] | None = Field( 2441 default=None, 2442 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.", 2443 ) 2444 name: str | None = Field( 2445 default=None, 2446 description="Human-facing display name declared in the Solution body. `null` when the Solution body does not set one.", 2447 ) 2448 org: str | None = Field( 2449 default=None, 2450 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.", 2451 ) 2452 org_logo: ImageSource | None = Field( 2453 default=None, 2454 description="Canonical image-source object for the resolved `org`'s logo, used as the principal category section glyph. The `url` is a stable, non-expiring capability URL (`refresh_url` is `null` there is nothing to refresh). `null` when `org_slug` is `null` or the org has no logo.", 2455 ) 2456 org_name: str | None = Field( 2457 default=None, 2458 description="Display name of the resolved `org`. Pairs with `org_slug` as the principal catalog category's label. `null` when `org_slug` is `null`.", 2459 ) 2460 org_slug: str | None = Field( 2461 default=None, 2462 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.", 2463 ) 2464 owners: list[str] = Field( 2465 ..., 2466 description='Owner scopes this Solution appears under. Members: `"system"` (app-level system scope) and/or `"org"` (viewer\'s org scope).', 2467 ) 2468 readme_url: str | None = Field( 2469 default=None, 2470 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`.", 2471 ) 2472 screenshot_urls: list[str] | None = Field( 2473 default=None, 2474 description="Absolute URLs of the Solution's gallery screenshots the bundled assets the body's `screenshots:` field names, in declared order. Each is a stable, non-expiring capability URL with the same cacheability contract as `image_url` (one shared token, a `v` cache key, and a `file` param selecting the screenshot); a URL 404s if the Solution stops declaring its screenshot. An empty array when the Solution declares none, and always empty for org-scoped rows the permanent URLs are minted for system-scope (catalog) Solutions only.", 2475 ) 2476 solution_id: str | None = Field( 2477 default=None, 2478 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.", 2479 ) 2480 solution_version: str | None = Field( 2481 default=None, 2482 description='Semver string declared in the Solution body (e.g. `"1.2.0"`). `null` when the body does not declare a version.', 2483 ) 2484 tag_keys: list[str] | None = Field( 2485 default=None, 2486 description="Freeform tag keys declared in the Solution body. An empty array when the body declares none.", 2487 ) 2488 template_kind: str | None = Field( 2489 default=None, 2490 description='Wrapped template kind `"AgentTemplate"`, `"AutomationTemplate"`, `"AgentRoutineTemplate"`, `"AgentToolTemplate"`, `"AgentComputerTemplate"`, or `"SolutionTemplateRef"` for ref-mode bundles.', 2491 ) 2492 templates: list[SolutionTemplateSummary] = Field( 2493 ..., 2494 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.", 2495 ) 2496 updated_at: str | None = Field( 2497 default=None, description="When the Solution config was last modified (ISO 8601)." 2498 ) 2499 upgrade_available: bool = Field( 2500 ..., 2501 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.", 2502 ) 2503 virtual_path: str | None = Field( 2504 default=None, 2505 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.", 2506 )
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.
events: dict[str, typing.Any] | None =
None
Custom analytics events declared in the Solution body's events: manifest a map of event key (snake_case) to its definition (label, optional description, optional typed fields). Dashboards use the label as the event's display name. Present as an empty object when the body declares none.
image_url: str | None =
None
Absolute URL of the Solution's cover image the bundled asset the body's image: field names. A stable, non-expiring capability URL (like org_logo.url), safe to hold in caches and OpenGraph tags; it 404s if the Solution stops declaring a cover. null when the Solution has no cover image, and always null for org-scoped rows the permanent URL is minted for system-scope (catalog) Solutions only.
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.
screenshot_urls: list[str] | None =
None
Absolute URLs of the Solution's gallery screenshots the bundled assets the body's screenshots: field names, in declared order. Each is a stable, non-expiring capability URL with the same cacheability contract as image_url (one shared token, a v cache key, and a file param selecting the screenshot); a URL 404s if the Solution stops declaring its screenshot. An empty array when the Solution declares none, and always empty for org-scoped rows the permanent URLs are minted for system-scope (catalog) Solutions only.
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):
2509class AgentSourceSolution(BaseModel): 2510 """ 2511 Summary of the Solution and AgentTemplate that an agent was last provisioned from. 2512 Returned on single-agent responses; `null` for hand-built agents and agents whose tracked template or parent Solution has been deleted. 2513 """ 2514 2515 current_solution: SolutionSummary | None = Field( 2516 default=None, 2517 description="Summary of the current parent Solution config row. `solution` is the pinned Solution version the agent points at; `current_solution` is the source Solution config row as it exists now.", 2518 ) 2519 solution: SolutionSummary = Field( 2520 ..., 2521 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.", 2522 ) 2523 template: UpgradeTemplateSummary = Field( 2524 ..., 2525 description="Summary of the AgentTemplate config (`cfg_...`) the agent was last provisioned or updated from.", 2526 )
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 current parent Solution config row. solution is the pinned Solution version the agent points at; current_solution is the source Solution config row as it exists now.
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):
2529class Agent(BaseModel): 2530 """ 2531 An AI agent that can be configured with tools, routines, and skills, and invoked to handle conversations or tasks. 2532 """ 2533 2534 acl: Acl | None = Field( 2535 default=None, 2536 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.", 2537 ) 2538 app: str | None = Field( 2539 default=None, description="ID of the application that owns this agent (`dap_...`)." 2540 ) 2541 created_at: str | None = Field( 2542 default=None, description="When the agent was created (ISO 8601)." 2543 ) 2544 default_model: str | None = Field( 2545 default=None, 2546 description='Default LLM model identifier used by this agent when no model is specified at runtime (e.g. `"claude-3-7-sonnet-latest"`).', 2547 ) 2548 description: str | None = Field( 2549 default=None, 2550 description="Human-readable description of what the agent does. `null` if not set.", 2551 ) 2552 email: str | None = Field( 2553 default=None, 2554 description="Email address provisioned for this agent. `null` if email delivery is not configured.", 2555 ) 2556 id: str = Field(..., description="Agent ID (`agi_...`).") 2557 identity: str | None = Field( 2558 default=None, 2559 description="System-level identity prompt that shapes the agent's persona and behavior.", 2560 ) 2561 last_applied_template_config: str | None = Field( 2562 default=None, 2563 description="ID of the AgentTemplate config (`cfg_...`) this agent was last provisioned or updated from. `null` for manually created agents.", 2564 ) 2565 lookup_key: str | None = Field( 2566 default=None, 2567 description="Stable, user-defined identifier for this agent within the application. Unique per app.", 2568 ) 2569 metadata: dict[str, Any] | None = Field( 2570 default=None, 2571 description="Arbitrary key-value metadata attached to the agent. Not interpreted by the platform.", 2572 ) 2573 name: str | None = Field( 2574 default=None, description="Human-readable display name for the agent. `null` if not set." 2575 ) 2576 org: str | None = Field( 2577 default=None, 2578 description="ID of the organization this agent belongs to (`org_...`). `null` if the agent is not org-scoped.", 2579 ) 2580 org_name: str | None = Field( 2581 default=None, 2582 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.", 2583 ) 2584 originator: str | None = Field( 2585 default=None, 2586 description="Free-form label identifying the source or author that created this agent (e.g. a username or pipeline name).", 2587 ) 2588 phone_number: str | None = Field( 2589 default=None, 2590 description="Phone number provisioned for this agent. `null` if SMS is not configured.", 2591 ) 2592 sandbox: str | None = Field( 2593 default=None, 2594 description="ID of the sandbox environment this agent is scoped to (`dsb_...`). `null` in production deployments.", 2595 ) 2596 source_solution: AgentSourceSolution | None = Field( 2597 default=None, 2598 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.", 2599 ) 2600 team: str | None = Field( 2601 default=None, 2602 description="ID of the team that owns this agent (`tem_...`). `null` if the agent is not team-scoped.", 2603 ) 2604 template_upgrade_available: bool | None = Field( 2605 default=None, 2606 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 on both the list endpoints and single-agent GET. Distinct from `source_solution.upgrade_available`, which compares Solution *versions*: an agent can lag its template (`template_upgrade_available: true`) while the org already holds the latest Solution version (`upgrade_available: false`).", 2607 ) 2608 updated_at: str | None = Field( 2609 default=None, description="When the agent was last modified (ISO 8601)." 2610 ) 2611 user: str | None = Field( 2612 default=None, 2613 description="ID of the user that owns this agent (`usr_...`). `null` if the agent is not user-scoped.", 2614 )
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 on both the list endpoints and single-agent GET. Distinct from source_solution.upgrade_available, which compares Solution versions: an agent can lag its template (template_upgrade_available: true) while the org already holds the latest Solution version (upgrade_available: false).
class
AgentComputer(pydantic.main.BaseModel):
2617class AgentComputer(BaseModel): 2618 """ 2619 A cloud computer resource provisioned for an agent to use for browser and desktop automation tasks. 2620 """ 2621 2622 agent: str | None = Field( 2623 default=None, 2624 description="ID of the agent that owns this computer (`agi_...`). `null` if the computer is not yet assigned to an agent.", 2625 ) 2626 app: str | None = Field( 2627 default=None, description="ID of the app this computer belongs to (`dap_...`)." 2628 ) 2629 config: dict[str, Any] | None = Field( 2630 default=None, 2631 description="Provider-specific configuration key-value pairs for the computer. Structure depends on the underlying compute provider.", 2632 ) 2633 created_at: datetime | None = Field( 2634 default=None, description="When the computer was created (ISO 8601)." 2635 ) 2636 error_message: str | None = Field( 2637 default=None, 2638 description='Human-readable error description when `status` is `"error"`. `null` otherwise.', 2639 ) 2640 id: str = Field(..., description="Computer ID (`cmp_...`).") 2641 last_active_at: datetime | None = Field( 2642 default=None, 2643 description="When the computer last reported activity or received a command. `null` if the computer has never been active.", 2644 ) 2645 lookup_key: str | None = Field( 2646 default=None, 2647 description="Unique, stable identifier you assign to this computer within its app. `null` if not set.", 2648 ) 2649 metadata: dict[str, Any] | None = Field( 2650 default=None, 2651 description="Arbitrary key-value metadata you attached to the computer. `null` if none was provided.", 2652 ) 2653 name: str | None = Field( 2654 default=None, description="Human-readable display name for the computer. `null` if not set." 2655 ) 2656 provider: str | None = Field( 2657 default=None, 2658 description='Compute backend powering this computer: `"sprites"` (Fly Sprites) or `"vercel"` (Vercel Sandbox).', 2659 ) 2660 region: str | None = Field( 2661 default=None, 2662 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"`).', 2663 ) 2664 sprite_url: str | None = Field( 2665 default=None, 2666 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.", 2667 ) 2668 status: str | None = Field( 2669 default=None, 2670 description='Current lifecycle state of the computer. Common values include `"provisioning"`, `"ready"`, `"error"`, and `"terminated"`.', 2671 ) 2672 updated_at: datetime | None = Field( 2673 default=None, description="When the computer record was last modified (ISO 8601)." 2674 )
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):
2677class AgentComputerListResponse(BaseModel): 2678 """ 2679 A list of agent computers returned by a list query. 2680 """ 2681 2682 data: list[AgentComputer] = Field( 2683 ..., description="Array of agent computer objects matching the query." 2684 )
A list of agent computers returned by a list query.
class
AgentCreateResponse(pydantic.main.BaseModel):
2687class AgentCreateResponse(BaseModel): 2688 """ 2689 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. 2690 """ 2691 2692 acl: Acl | None = Field( 2693 default=None, 2694 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.", 2695 ) 2696 app: str | None = Field( 2697 default=None, description="ID of the app this agent belongs to (`dap_...`)." 2698 ) 2699 created_at: str | None = Field( 2700 default=None, description="When the agent was created (ISO 8601)." 2701 ) 2702 default_model: str | None = Field( 2703 default=None, 2704 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.', 2705 ) 2706 email: str | None = Field( 2707 default=None, 2708 description="Email address assigned to this agent for inbound email handling. `null` if not configured.", 2709 ) 2710 id: str = Field(..., description="Agent ID (`agi_...`).") 2711 identity: str | None = Field( 2712 default=None, 2713 description="System prompt or persona description that shapes the agent's behavior. `null` if not set.", 2714 ) 2715 installed_configs: list[InstalledConfigEntry] | None = Field( 2716 default=None, 2717 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`.", 2718 ) 2719 lookup_key: str | None = Field( 2720 default=None, 2721 description="Unique, stable identifier for the agent within its app. `null` if not set.", 2722 ) 2723 metadata: dict[str, Any] | None = Field( 2724 default=None, 2725 description="Arbitrary key-value metadata attached to the agent. `null` if none was provided.", 2726 ) 2727 name: str | None = Field( 2728 default=None, description="Human-readable display name for the agent. `null` if not set." 2729 ) 2730 org: str | None = Field( 2731 default=None, 2732 description="ID of the organization this agent belongs to (`org_...`). `null` for agents outside an org.", 2733 ) 2734 originator: str | None = Field( 2735 default=None, 2736 description="Free-form label identifying the source or author of the agent, e.g. a username or service name. `null` if not set.", 2737 ) 2738 phone_number: str | None = Field( 2739 default=None, 2740 description="Phone number assigned to this agent for inbound SMS or voice handling. `null` if not configured.", 2741 ) 2742 sandbox: str | None = Field( 2743 default=None, 2744 description="ID of the sandbox environment this agent is scoped to (`sbx_...`). `null` for agents not scoped to a sandbox.", 2745 ) 2746 team: str | None = Field( 2747 default=None, 2748 description="ID of the team that owns this agent (`tea_...`). `null` if owned by a user rather than a team.", 2749 ) 2750 updated_at: str | None = Field( 2751 default=None, description="When the agent record was last modified (ISO 8601)." 2752 ) 2753 user: str | None = Field( 2754 default=None, 2755 description="ID of the user that owns this agent (`usr_...`). `null` if owned by a team.", 2756 )
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):
2759class AgentEnvVarMasked(BaseModel): 2760 """ 2761 An agent environment variable with its secret value masked for safe display in list and show responses. 2762 """ 2763 2764 agent: str = Field( 2765 ..., description="ID of the agent this environment variable belongs to (`agt_...`)." 2766 ) 2767 created_at: datetime | None = Field( 2768 default=None, description="When the environment variable was created (ISO 8601)." 2769 ) 2770 description: str | None = Field( 2771 default=None, 2772 description="Optional human-readable note describing the purpose of this variable. `null` if not set.", 2773 ) 2774 id: str = Field(..., description="Environment variable ID (`anv_...`).") 2775 key: str = Field( 2776 ..., description="Name of the environment variable as it appears in the agent's runtime." 2777 ) 2778 masked_value: str = Field( 2779 ..., 2780 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.", 2781 ) 2782 updated_at: datetime | None = Field( 2783 default=None, description="When the environment variable was last updated (ISO 8601)." 2784 )
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):
2787class AgentEnvVarMaskedList(BaseModel): 2788 """ 2789 Flat list of masked environment variables belonging to an agent. 2790 """ 2791 2792 data: list[AgentEnvVarMasked] = Field( 2793 ..., description="Array of masked environment variable objects for the agent." 2794 )
Flat list of masked environment variables belonging to an agent.
class
AgentExport(pydantic.main.BaseModel):
2797class AgentExport(BaseModel): 2798 """ 2799 A portable export bundle for an agent, containing everything needed to re-deploy it in another workspace or environment. 2800 """ 2801 2802 configs: list[Config] = Field( 2803 ..., 2804 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.", 2805 ) 2806 template: dict[str, Any] = Field( 2807 ..., 2808 description="The agent template definition as a structured map. Pass this directly to the import endpoint to recreate the agent.", 2809 )
A portable export bundle for an agent, containing everything needed to re-deploy it in another workspace or environment.
class
AgentHealth(pydantic.main.BaseModel):
2812class AgentHealth(BaseModel): 2813 """ 2814 Aggregate health profile for an agent, summarizing its current operational status, score, and the full list of setup and health actions. 2815 """ 2816 2817 activity: dict[str, Any] = Field( 2818 ..., 2819 description="Timestamps for the agent's most recent and next scheduled activity, used to surface last-run and upcoming-run information.", 2820 ) 2821 agent: Agent = Field(..., description="The agent this health profile describes.") 2822 checked_at: datetime = Field( 2823 ..., description="When the health profile was last computed (ISO 8601)." 2824 ) 2825 checks: list[dict[str, Any]] = Field( 2826 ..., 2827 description="Renderable health check results. Each object includes at minimum `key`, `label`, `status`, and `summary` fields.", 2828 ) 2829 counts: dict[str, Any] = Field( 2830 ..., 2831 description="Action counts broken down by dependency area and resolution status, used to render progress indicators per category.", 2832 ) 2833 health_actions: list[AgentHealthAction] = Field( 2834 ..., 2835 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.', 2836 ) 2837 recent: dict[str, Any] = Field( 2838 ..., 2839 description="Recent execution metrics for the agent, including run counts and failure counts over a recent time window.", 2840 ) 2841 score: int = Field( 2842 ..., 2843 description="Normalized health score from `0` (fully degraded) to `100` (fully healthy), derived from the weight and status of all health actions.", 2844 ) 2845 status: str = Field( 2846 ..., 2847 description='Overall health status of the agent. One of `"ok"`, `"warning"`, or `"critical"`.', 2848 )
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):
2851class AgentListResponse(BaseModel): 2852 """ 2853 Paginated list of agent objects. Use the pagination fields to traverse multiple pages of results. 2854 """ 2855 2856 data: list[Agent] = Field(..., description="Array of agent objects for the current page.") 2857 has_next: bool | None = Field( 2858 default=None, description="`true` when a subsequent page of results exists." 2859 ) 2860 has_prev: bool | None = Field( 2861 default=None, description="`true` when a previous page of results exists." 2862 ) 2863 page: int | None = Field(default=None, description="Current page number, starting at 1.") 2864 page_size: int | None = Field( 2865 default=None, description="Maximum number of agents returned per page." 2866 ) 2867 total_entries: int | None = Field( 2868 default=None, description="Total number of agents matching the query across all pages." 2869 ) 2870 total_pages: int | None = Field( 2871 default=None, description="Total number of pages available given the current `page_size`." 2872 )
Paginated list of agent objects. Use the pagination fields to traverse multiple pages of results.
class
AgentRoutine(pydantic.main.BaseModel):
2875class AgentRoutine(BaseModel): 2876 """ 2877 An agent routine defines a reusable handler script, preset, or chain that runs in response to events or on a schedule. 2878 """ 2879 2880 acl: Acl | None = Field( 2881 default=None, 2882 description='Access control list for the routine. Contains a `grants` array where each entry specifies `principal_type`, `principal`, and `actions` (`"read"`, `"invoke"`, or `"assign"` an `"assign"` grant names the agents or orgs that may be handed this routine\'s embedded work items). `null` when no ACL restrictions are applied and the routine is accessible to all members of its scope.', 2883 ) 2884 agent: str | None = Field( 2885 default=None, description="ID of the agent that owns this routine (`agi_...`)." 2886 ) 2887 app: str | None = Field( 2888 default=None, description="Application that scopes this routine (`dap_...`)." 2889 ) 2890 config: str | None = Field( 2891 default=None, 2892 description="ID of the Config record that backs this routine's configuration (`cfg_...`). `null` when the routine is not config-backed.", 2893 ) 2894 created_at: datetime | None = Field( 2895 default=None, description="When this routine was created (ISO 8601)." 2896 ) 2897 description: str | None = Field( 2898 default=None, 2899 description="Optional description of what this routine does. `null` when not set.", 2900 ) 2901 event_config: dict[str, Any] | None = Field( 2902 default=None, 2903 description="Additional configuration controlling how the event trigger is matched or filtered. Shape depends on `event_type`. `null` when not configured.", 2904 ) 2905 event_type: str | None = Field( 2906 default=None, 2907 description='Platform event type that triggers this routine, e.g. `"agentroutine.invoked"`. `null` for schedule-only routines.', 2908 ) 2909 handler_type: str | None = Field( 2910 default=None, 2911 description='Execution strategy for this routine. One of `"workflow_graph"`, `"script"`, `"preset"`, or `"chain"`.', 2912 ) 2913 id: str = Field(..., description="Routine ID (`arn_...`).") 2914 last_applied_template_config: str | None = Field( 2915 default=None, 2916 description="ID of the AgentRoutineTemplate Config this routine was last provisioned or updated from (`cfg_...`). `null` for hand-built routines.", 2917 ) 2918 lookup_key: str | None = Field( 2919 default=None, 2920 description="Unique human-readable key used to look up this routine without knowing its ID. `null` when not set.", 2921 ) 2922 message_policy: MessagePolicy | None = Field( 2923 default=None, 2924 description="Visibility and explicit recipient selection for messages emitted by this routine.", 2925 ) 2926 metadata: dict[str, Any] | None = Field( 2927 default=None, 2928 description="Arbitrary key-value metadata attached to this routine. `null` when not set.", 2929 ) 2930 name: str | None = Field(default=None, description="Human-readable name for the routine.") 2931 preset_config: PresetConfig | None = Field( 2932 default=None, 2933 description='Resolved preset configuration when `handler_type` is `"preset"`. `null` for other handler types.', 2934 ) 2935 preset_name: str | None = Field( 2936 default=None, 2937 description='Name of the preset invoked when `handler_type` is `"preset"`. `null` for other handler types.', 2938 ) 2939 schedule: str | None = Field( 2940 default=None, 2941 description="Cron expression controlling when the routine fires on a schedule. `null` for event-only routines.", 2942 ) 2943 script: str | None = Field( 2944 default=None, 2945 description='Inline script body executed when `handler_type` is `"script"`. `null` for other handler types.', 2946 ) 2947 status: str | None = Field( 2948 default=None, 2949 description='Lifecycle status of the routine. One of `"draft"`, `"active"`, or `"paused"`. Only `"active"` routines respond to triggers.', 2950 ) 2951 steps: list[dict[str, Any]] | None = Field( 2952 default=None, 2953 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).', 2954 ) 2955 trigger_context: str | None = Field( 2956 default=None, 2957 description='Execution context in which runs are created. One of `"event"` (background job) or `"chat_session"` (interactive session). Defaults to `"event"`.', 2958 ) 2959 updated_at: datetime | None = Field( 2960 default=None, description="When this routine was last updated (ISO 8601)." 2961 ) 2962 user: str | None = Field( 2963 default=None, 2964 description="Optional co-owner user (`usr_...`). When set, that user shares view/modify/delete authority on this routine without administering the parent agent. `null` when not set. Never inferred from the caller only present when explicitly provided on create/update.", 2965 )
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 ("read", "invoke", or "assign" an "assign" grant names the agents or orgs that may be handed this routine's embedded work items). 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):
2968class AgentRoutineListResponse(BaseModel): 2969 """ 2970 List of agent routine objects belonging to a given agent. 2971 """ 2972 2973 data: list[AgentRoutine] = Field(..., description="Array of agent routine objects.")
List of agent routine objects belonging to a given agent.
class
AgentRoutineRunDelivery(pydantic.main.BaseModel):
2976class AgentRoutineRunDelivery(BaseModel): 2977 """ 2978 Normalized destination and status for an agent routine run's final-result delivery. 2979 """ 2980 2981 delivered_at: datetime | None = Field( 2982 default=None, description="When delivery completed successfully (ISO 8601)." 2983 ) 2984 delivered_message: str | None = Field( 2985 default=None, description="ID of the message created by a successful delivery (`msg_...`)." 2986 ) 2987 last_error: str | None = Field( 2988 default=None, 2989 description="Stable public error code for the most recent failed delivery attempt.", 2990 ) 2991 message: str | None = Field( 2992 default=None, description="Source message ID (`msg_...`) when the delivery is a reply." 2993 ) 2994 status: Literal["not_requested", "pending", "delivered", "failed"] = Field( 2995 ..., description="Current delivery lifecycle status." 2996 ) 2997 thread: str | None = Field( 2998 default=None, description="Destination thread ID (`thr_...`) when delivery was requested." 2999 ) 3000 type: Literal["none", "thread", "reply"] = Field(..., description="Normalized delivery mode.")
Normalized destination and status for an agent routine run's final-result delivery.
class
AgentRoutineRun(pydantic.main.BaseModel):
3003class AgentRoutineRun(BaseModel): 3004 """ 3005 A single execution of an agent routine, capturing its status, inputs, outputs, and timing. 3006 """ 3007 3008 acl: Acl | None = Field( 3009 default=None, 3010 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.", 3011 ) 3012 agent: str | None = Field( 3013 default=None, description="ID of the agent that owns the parent routine (`agi_...`)." 3014 ) 3015 app: str | None = Field( 3016 default=None, description="Application that scopes this run (`dap_...`)." 3017 ) 3018 created_at: datetime | None = Field( 3019 default=None, description="When this run was created (ISO 8601)." 3020 ) 3021 delivery: AgentRoutineRunDelivery | None = Field( 3022 default=None, 3023 description="Normalized final-result delivery destination and its current delivery status.", 3024 ) 3025 duration_ms: int | None = Field( 3026 default=None, 3027 description="Total wall-clock time the run took to execute, in milliseconds. `null` while the run is still in progress.", 3028 ) 3029 event_id: str | None = Field( 3030 default=None, 3031 description="Identifier of the platform event that triggered this run. `null` for manually invoked runs.", 3032 ) 3033 id: str = Field(..., description="Routine run ID (`arr_...`).") 3034 metadata: dict[str, Any] | None = Field( 3035 default=None, 3036 description="Arbitrary key-value metadata attached to this run. Empty object when no metadata was set.", 3037 ) 3038 participants: dict[str, Any] | None = Field( 3039 default=None, 3040 description="Invoke-time map of symbolic participant references to agent IDs. `null` when no participants were supplied.", 3041 ) 3042 payload: dict[str, Any] | None = Field( 3043 default=None, 3044 description="Input payload delivered to the routine when this run was triggered. Empty object when no payload was provided.", 3045 ) 3046 result: dict[str, Any] | None = Field( 3047 default=None, 3048 description="Output produced by the routine after execution. `null` while the run has not yet completed.", 3049 ) 3050 routine: str | None = Field( 3051 default=None, description="ID of the parent routine that produced this run (`arn_...`)." 3052 ) 3053 status: str | None = Field( 3054 default=None, 3055 description='Current execution status. One of `"pending"`, `"running"`, `"completed"`, `"failed"`, `"skipped"`, or `"cancelled"`.', 3056 ) 3057 structured_response: dict[str, Any] | None = Field( 3058 default=None, 3059 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.", 3060 ) 3061 updated_at: datetime | None = Field( 3062 default=None, description="When this run was last updated (ISO 8601)." 3063 ) 3064 worker: WorkerStatus | None = Field( 3065 default=None, 3066 description="Background worker status. `null` when no worker job is associated with this run.", 3067 )
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.
participants: dict[str, typing.Any] | None =
None
Invoke-time map of symbolic participant references to agent IDs. null when no participants were supplied.
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):
3070class AgentRoutineRunListResponse(BaseModel): 3071 """ 3072 Cursor-paginated list of agent routine run objects, ordered by creation time descending. 3073 """ 3074 3075 after_cursor: str | None = Field( 3076 default=None, 3077 description="Opaque cursor to pass as the after-cursor parameter to fetch the next page of runs. `null` when no later results exist.", 3078 ) 3079 before_cursor: str | None = Field( 3080 default=None, 3081 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.", 3082 ) 3083 data: list[AgentRoutineRun] = Field( 3084 ..., description="Array of agent routine run objects for the current page." 3085 )
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):
3088class AgentSchedule(BaseModel): 3089 """ 3090 A scheduled task created by an agent. Supports one-time and recurring (cron-based) execution patterns. 3091 """ 3092 3093 agent: str | None = Field( 3094 default=None, description="ID of the agent that owns this schedule (`agi_...`)." 3095 ) 3096 app: str | None = Field( 3097 default=None, description="ID of the application the schedule belongs to (`dap_...`)." 3098 ) 3099 created_at: datetime | None = Field( 3100 default=None, description="When the schedule was created (ISO 8601)." 3101 ) 3102 cron_expression: str | None = Field( 3103 default=None, 3104 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.', 3105 ) 3106 id: str = Field(..., description="Schedule ID (`asc_...`).") 3107 instructions: str | None = Field( 3108 default=None, 3109 description="The task description the agent will execute when this schedule fires.", 3110 ) 3111 last_run_at: datetime | None = Field( 3112 default=None, 3113 description="UTC datetime of the most recent successful execution. `null` if the schedule has never run.", 3114 ) 3115 max_runs: int | None = Field( 3116 default=None, 3117 description='Maximum number of times a recurring schedule may fire before automatically transitioning to `"completed"`. `null` means no limit.', 3118 ) 3119 metadata: dict[str, Any] | None = Field( 3120 default=None, 3121 description="Arbitrary key-value pairs attached to the schedule by the agent. Not interpreted by the platform.", 3122 ) 3123 next_run_at: datetime | None = Field( 3124 default=None, 3125 description="UTC datetime of the next planned execution. `null` if the schedule has completed, been cancelled, or has not yet been computed.", 3126 ) 3127 run_count: int | None = Field( 3128 default=None, description="Total number of times this schedule has fired." 3129 ) 3130 schedule_type: str | None = Field( 3131 default=None, 3132 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.', 3133 ) 3134 scheduled_at: datetime | None = Field( 3135 default=None, 3136 description='The exact UTC datetime at which a one-time schedule fires. Present only when `schedule_type` is `"once"`. `null` for recurring schedules.', 3137 ) 3138 status: str | None = Field( 3139 default=None, 3140 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).', 3141 ) 3142 thread: str | None = Field( 3143 default=None, 3144 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.", 3145 ) 3146 timezone: str | None = Field( 3147 default=None, 3148 description='IANA timezone name used to interpret the cron expression or `scheduled_at` (e.g. `"America/New_York"`). Defaults to `"Etc/UTC"`.', 3149 ) 3150 updated_at: datetime | None = Field( 3151 default=None, description="When the schedule was last modified (ISO 8601)." 3152 )
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):
3155class AgentSession(BaseModel): 3156 """ 3157 A durable agent session record representing a single AI task execution. Tracks status, trajectory, result, and any inbox messages delivered to the session. 3158 """ 3159 3160 agent: str | None = Field( 3161 default=None, description="ID of the agent that owns this session (`agi_...`)." 3162 ) 3163 completed_at: datetime | None = Field( 3164 default=None, 3165 description='When the session reached a terminal state (`"completed"`, `"failed"`, or `"cancelled"`). `null` if still in progress.', 3166 ) 3167 created_at: datetime | None = Field( 3168 default=None, description="When the session was created (ISO 8601)." 3169 ) 3170 error: str | None = Field( 3171 default=None, 3172 description='Human-readable error message describing why the session failed. `null` unless `status` is `"failed"`.', 3173 ) 3174 id: str = Field(..., description="Session ID (`ase_...`).") 3175 inbox: list[dict[str, Any]] | None = Field( 3176 default=None, 3177 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`.', 3178 ) 3179 instructions: str | None = Field( 3180 default=None, description="The task the agent is instructed to perform in this session." 3181 ) 3182 is_system_session: bool | None = Field( 3183 default=None, 3184 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.", 3185 ) 3186 max_runs_per_turn: int | None = Field( 3187 default=None, 3188 description="Maximum number of tool calls the agent may make within a single turn. Defaults to `25`.", 3189 ) 3190 max_tokens: int | None = Field( 3191 default=None, 3192 description="Maximum number of tokens the session may consume across all turns before being terminated. Defaults to `20000`.", 3193 ) 3194 max_turns: int | None = Field( 3195 default=None, 3196 description="Maximum number of agent turns (LLM calls) allowed before the session is forcibly terminated. Defaults to `100`.", 3197 ) 3198 metadata: dict[str, Any] | None = Field( 3199 default=None, 3200 description="Arbitrary key-value pairs attached to the session. Not interpreted by the platform.", 3201 ) 3202 name: str | None = Field( 3203 default=None, 3204 description="Optional human-readable label for the session. `null` when not set.", 3205 ) 3206 result: dict[str, Any] | None = Field( 3207 default=None, 3208 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.", 3209 ) 3210 started_at: datetime | None = Field( 3211 default=None, description='When the session began executing. `null` if still `"pending"`.' 3212 ) 3213 status: str | None = Field( 3214 default=None, 3215 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).', 3216 ) 3217 trajectory: str | None = Field( 3218 default=None, 3219 description="ID of the trajectory that records the full message history for this session (`trj_...`). `null` until the session has started.", 3220 )
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):
3223class AgentSessionListResponse(BaseModel): 3224 """ 3225 Paginated list response containing an array of agent session objects. 3226 """ 3227 3228 data: list[AgentSession] = Field( 3229 ..., description="Array of agent session objects for the current page." 3230 )
Paginated list response containing an array of agent session objects.
class
AgentSkill(pydantic.main.BaseModel):
3233class AgentSkill(BaseModel): 3234 """ 3235 A skill enabled on an agent, linking the agent to a skill configuration. Controls which capabilities the agent has access to. 3236 """ 3237 3238 agent: str | None = Field( 3239 default=None, description="ID of the agent this skill is attached to (`agi_...`)." 3240 ) 3241 app: str | None = Field( 3242 default=None, description="ID of the application this skill belongs to (`dap_...`)." 3243 ) 3244 config: str | None = Field( 3245 default=None, 3246 description="ID of the root skill config record that defines this skill's behavior (`cfg_...`).", 3247 ) 3248 created_at: datetime | None = Field( 3249 default=None, description="When the skill was added to the agent (ISO 8601)." 3250 ) 3251 id: str = Field(..., description="Skill ID (`ask_...`).") 3252 instruction: str | None = Field( 3253 default=None, 3254 description="Optional instruction text that overrides the default skill instructions for this specific agent. `null` when no override is set.", 3255 ) 3256 last_applied_template_config: str | None = Field( 3257 default=None, 3258 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.", 3259 ) 3260 metadata: dict[str, Any] | None = Field( 3261 default=None, 3262 description="Arbitrary key-value pairs attached to the skill. Not interpreted by the platform.", 3263 ) 3264 status: str | None = Field( 3265 default=None, 3266 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.', 3267 ) 3268 updated_at: datetime | None = Field( 3269 default=None, description="When the skill was last modified (ISO 8601)." 3270 )
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):
3273class AgentSkillList(BaseModel): 3274 """ 3275 Paginated list response containing an array of agent skill objects. 3276 """ 3277 3278 data: list[AgentSkill] = Field( 3279 ..., description="Array of agent skill objects for the current page." 3280 )
Paginated list response containing an array of agent skill objects.
class
AgentTool(pydantic.main.BaseModel):
3283class AgentTool(BaseModel): 3284 """ 3285 A tool attached to an agent, defining a capability the agent can invoke during a conversation or task run. 3286 """ 3287 3288 model_config = ConfigDict(populate_by_name=True) 3289 3290 agent: str | None = Field( 3291 default=None, description="ID of the agent this tool belongs to (`agi_...`)." 3292 ) 3293 app: str | None = Field( 3294 default=None, description="ID of the application that owns this tool (`dap_...`)." 3295 ) 3296 async_: bool | None = Field( 3297 default=None, 3298 alias="async", 3299 description="`true` when the tool executes asynchronously and returns a task handle rather than an immediate result.", 3300 ) 3301 builtin_tool_config: dict[str, Any] | None = Field( 3302 default=None, 3303 description='Provider-specific configuration for the built-in tool. Present only when `kind` is `"builtin"`. Shape varies by `builtin_tool_key`.', 3304 ) 3305 builtin_tool_key: str | None = Field( 3306 default=None, 3307 description='Registry key identifying the built-in tool implementation. Present only when `kind` is `"builtin"`.', 3308 ) 3309 config: str | None = Field( 3310 default=None, 3311 description="ID of the config record (`cfg_...`) containing this tool's full configuration. `null` for inline-only tools.", 3312 ) 3313 created_at: datetime | None = Field( 3314 default=None, description="When the tool was created (ISO 8601)." 3315 ) 3316 description: str | None = Field( 3317 default=None, 3318 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.', 3319 ) 3320 handler_type: str | None = Field( 3321 default=None, 3322 description='Execution handler type. One of `"http"`, `"script"`, or `"builtin"`.', 3323 ) 3324 id: str = Field(..., description="Tool ID (`atl_...`).") 3325 instruction: str | None = Field( 3326 default=None, 3327 description="Optional system-level instruction appended to the agent prompt when this tool is active.", 3328 ) 3329 kind: str | None = Field( 3330 default=None, description='Tool kind. One of `"builtin"`, `"custom"`, or `"mcp"`.' 3331 ) 3332 last_applied_template_config: str | None = Field( 3333 default=None, 3334 description="ID of the AgentToolTemplate config (`cfg_...`) this tool was last provisioned or updated from. `null` for manually created tools.", 3335 ) 3336 lookup_key: str | None = Field( 3337 default=None, 3338 description="Stable, user-defined identifier for this tool within the agent. Unique per agent.", 3339 ) 3340 metadata: dict[str, Any] | None = Field( 3341 default=None, 3342 description="Arbitrary key-value metadata attached to the tool. Not interpreted by the platform.", 3343 ) 3344 name: str | None = Field( 3345 default=None, 3346 description='Human-readable name of the tool as exposed to the LLM. Resolved from the built-in registry for `kind: "builtin"` tools.', 3347 ) 3348 name_prefix: str | None = Field( 3349 default=None, 3350 description="Per-instance namespace prepended to LLM-facing tool names for built-in tools that support multiple instances per agent. `null` when not applicable.", 3351 ) 3352 parameters: dict[str, Any] | None = Field( 3353 default=None, 3354 description="JSON Schema object describing the tool's input parameters as presented to the LLM.", 3355 ) 3356 parameters_config: str | None = Field( 3357 default=None, 3358 description="ID of the config record (`cfg_...`) storing the tool's parameter schema. `null` when parameters are defined inline.", 3359 ) 3360 status: str | None = Field( 3361 default=None, description='Current status of the tool. One of `"active"` or `"disabled"`.' 3362 ) 3363 updated_at: datetime | None = Field( 3364 default=None, description="When the tool was last modified (ISO 8601)." 3365 )
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):
3368class AgentToolListResponse(BaseModel): 3369 """ 3370 Paginated list response containing the tools attached to an agent. 3371 """ 3372 3373 data: list[AgentTool] = Field( 3374 ..., description="Array of agent tool objects returned for the current request." 3375 )
Paginated list response containing the tools attached to an agent.
class
AgentUpgradeFieldChange(pydantic.main.BaseModel):
3378class AgentUpgradeFieldChange(BaseModel): 3379 """ 3380 One field-level diff entry within an agent upgrade change, describing how a single field will change. 3381 `baseline` and `locally_edited` are populated only for `agent_base` entries; child resource entries (tools, routines, skills, computers) carry only `field`, `old`, and `new`. 3382 """ 3383 3384 baseline: Any | None = Field( 3385 default=None, 3386 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).", 3387 ) 3388 field: str = Field( 3389 ..., description='Name of the field that will change, e.g. `"name"` or `"identity"`.' 3390 ) 3391 locally_edited: bool | None = Field( 3392 default=None, 3393 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.", 3394 ) 3395 new: Any | None = Field( 3396 default=None, 3397 description="Incoming value the field will be set to after the upgrade (string, number, boolean, or `null`).", 3398 ) 3399 old: Any | None = Field( 3400 default=None, 3401 description="Current value of the field before the upgrade (string, number, boolean, or `null`).", 3402 )
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):
3405class AgentUpgradeChange(BaseModel): 3406 """ 3407 One child-resource change produced by an agent upgrade, describing the action to be taken on a single resource. 3408 """ 3409 3410 action: str = Field( 3411 ..., 3412 description='The operation that will be performed. One of `"add"`, `"update"`, `"remove"`, or `"noop"`.', 3413 ) 3414 description: str | None = Field( 3415 default=None, 3416 description="Description of the child resource this change touches, when one is set. `null` when no description is available.", 3417 ) 3418 field_changes: list[AgentUpgradeFieldChange] | None = Field( 3419 default=None, 3420 description='Field-level diff entries for this change. Populated only when `action` is `"update"`; empty or absent for `add`, `remove`, and `noop` entries.', 3421 ) 3422 id: str | None = Field( 3423 default=None, 3424 description="Public ID of the existing resource being updated or removed (e.g. `atl_...`, `arn_...`). `null` for `add` entries.", 3425 ) 3426 key: str | None = Field( 3427 default=None, 3428 description="Lookup key of the resource derived from its source template. `null` when the template has no lookup key.", 3429 ) 3430 name: str | None = Field( 3431 default=None, 3432 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.", 3433 ) 3434 parent_template_config: UpgradeTemplateSummary = Field( 3435 ..., 3436 description="Summary of the parent AgentTemplate config (`cfg_...`) being applied in this upgrade.", 3437 ) 3438 resource: dict[str, Any] | None = Field( 3439 default=None, 3440 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.", 3441 ) 3442 resource_type: str = Field( 3443 ..., 3444 description='Type of the child resource being changed. One of `"agent"`, `"tool"`, `"routine"`, `"skill"`, or `"computer"`.', 3445 ) 3446 source_template_config: UpgradeTemplateSummary | None = Field( 3447 default=None, 3448 description="Summary of the specific child template config (`cfg_...`) that defines this resource. `null` when no source template is resolvable.", 3449 )
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):
3452class AgentUpgradeSummary(BaseModel): 3453 """ 3454 Aggregate counts of each change type produced by an agent upgrade diff. 3455 """ 3456 3457 adds: int = Field( 3458 ..., description="Number of child resources that will be created by this upgrade." 3459 ) 3460 noops: int = Field( 3461 ..., description="Number of child resources with no changes in this upgrade." 3462 ) 3463 removes: int = Field( 3464 ..., description="Number of child resources that will be removed by this upgrade." 3465 ) 3466 updates: int = Field( 3467 ..., description="Number of child resources that will be updated by this upgrade." 3468 )
Aggregate counts of each change type produced by an agent upgrade diff.
class
AgentUpgradeResult(pydantic.main.BaseModel):
3471class AgentUpgradeResult(BaseModel): 3472 """ 3473 The computed diff and outcome of an agent upgrade operation, including the full list of per-resource changes. 3474 """ 3475 3476 changes: list[AgentUpgradeChange] = Field( 3477 ..., 3478 description="Ordered list of per-resource changes that will be (or were) applied by this upgrade.", 3479 ) 3480 dry_run: bool = Field( 3481 ..., 3482 description="`true` when the request was a dry run and no changes were persisted to the agent.", 3483 ) 3484 mode: str = Field( 3485 ..., 3486 description='Upgrade mode that was used. One of `"full"` (apply all changes) or `"review"` (require fingerprint confirmation).', 3487 ) 3488 review_fingerprint: str | None = Field( 3489 default=None, 3490 description='Opaque fingerprint of the computed diff. Pass this value back as `review_fingerprint` to confirm and apply a `"review"` mode upgrade.', 3491 ) 3492 status: str = Field( 3493 ..., 3494 description='Outcome of the upgrade. `"ready"` for a dry-run (no changes applied); `"upgraded"` when the upgrade was committed.', 3495 ) 3496 summary: AgentUpgradeSummary = Field( 3497 ..., 3498 description="Aggregate counts of adds, updates, removes, and noops across all child resources.", 3499 )
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):
3502class AgentUpgradeResponse(BaseModel): 3503 """ 3504 Response returned by the agent upgrade endpoint, combining the updated agent, its source Solution and template, and the full upgrade diff. 3505 """ 3506 3507 agent: Agent | None = Field( 3508 default=None, 3509 description="The agent after the upgrade has been applied. `null` for dry-run requests where no changes were persisted.", 3510 ) 3511 solution: SolutionSummary = Field( 3512 ..., description="Summary of the parent Solution the agent was upgraded from." 3513 ) 3514 template: UpgradeTemplateSummary = Field( 3515 ..., 3516 description="Summary of the AgentTemplate config (`cfg_...`) that was selected for this upgrade.", 3517 ) 3518 upgrade_result: AgentUpgradeResult = Field( 3519 ..., 3520 description="Full upgrade diff including status, mode, dry-run flag, summary counts, and per-resource change list.", 3521 )
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):
3524class SolutionCategorySummary(BaseModel): 3525 """ 3526 A solution category that organizes solutions in the catalog, identified by a stable key and optionally nested under a parent category. 3527 """ 3528 3529 created_at: datetime | None = Field( 3530 default=None, 3531 description="When this category was first created (ISO 8601). `null` for system-built-in categories.", 3532 ) 3533 description: str | None = Field( 3534 default=None, 3535 description="Short prose description of what solutions in this category do. `null` when not configured.", 3536 ) 3537 id: str = Field(..., description="Solution category config ID (`cfg_...`).") 3538 key: str = Field( 3539 ..., 3540 description="Stable, human-readable key for this category, referenced by solutions via `category_keys`.", 3541 ) 3542 kind: str = Field(..., description='Resource type identifier. Always `"SolutionCategory"`.') 3543 lookup_key: str | None = Field( 3544 default=None, description="Lookup key of the underlying config record. `null` when not set." 3545 ) 3546 metadata: dict[str, Any] | None = Field( 3547 default=None, 3548 description="Arbitrary key-value metadata attached to this category by the publisher.", 3549 ) 3550 name: str | None = Field( 3551 default=None, description="Display name shown to users. `null` when not configured." 3552 ) 3553 org: str | None = Field( 3554 default=None, 3555 description="Organization ID (`org_...`) that owns this category. `null` for system-scoped categories.", 3556 ) 3557 owners: list[str] = Field( 3558 ..., 3559 description='Scopes under which this category is visible. Possible values are `"system"` (available to all apps) and `"org"` (scoped to the viewer\'s organization).', 3560 ) 3561 parent_key: str | None = Field( 3562 default=None, 3563 description="Key of the parent `SolutionCategory`, enabling a hierarchy. `null` for top-level categories.", 3564 ) 3565 sort_order: int | None = Field( 3566 default=None, 3567 description="Numeric hint for ordering categories in a list. Lower values sort first. `null` when not configured.", 3568 ) 3569 updated_at: datetime | None = Field( 3570 default=None, 3571 description="When this category was last modified (ISO 8601). `null` for system-built-in categories.", 3572 ) 3573 virtual_path: str | None = Field( 3574 default=None, 3575 description="Virtual path of the underlying config record. `null` when not set.", 3576 )
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):
3579class SolutionCategoryListResponse(BaseModel): 3580 """ 3581 Paginated list of solution category summaries. Use `page` and `page_size` to navigate pages of results. 3582 """ 3583 3584 data: list[SolutionCategorySummary] = Field( 3585 ..., description="Array of solution category summary objects for the current page." 3586 ) 3587 has_next: bool = Field(..., description="`true` when a subsequent page of results exists.") 3588 has_prev: bool = Field(..., description="`true` when a previous page of results exists.") 3589 page: int = Field(..., description="Current page number (1-indexed).") 3590 page_size: int = Field(..., description="Maximum number of entries returned per page.") 3591 total_entries: int = Field( 3592 ..., description="Total number of distinct solution categories across all pages." 3593 ) 3594 total_pages: int = Field( 3595 ..., description="Total number of pages available at the current `page_size`." 3596 )
class
SolutionDependentAgent(pydantic.main.BaseModel):
3599class SolutionDependentAgent(BaseModel): 3600 """ 3601 A brief representation of an agent that references at least one config bundled by a Solution, included in the dependents preview response. 3602 """ 3603 3604 id: str = Field(..., description="Agent ID (`agi_...`).") 3605 name: str | None = Field( 3606 default=None, 3607 description="Human-readable display name of the agent. `null` when no name has been set.", 3608 )
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):
3611class SolutionDependentsResponse(BaseModel): 3612 """ 3613 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. 3614 """ 3615 3616 dependent_agent_count: int = Field( 3617 ..., 3618 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.", 3619 ) 3620 dependent_agents: list[SolutionDependentAgent] = Field( 3621 ..., 3622 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.", 3623 ) 3624 preserved_config_count: int = Field( 3625 ..., 3626 description="Number of bundled configs that would be detached and preserved rather than deleted, because at least one live agent still references them.", 3627 )
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):
3630class SolutionDiffReference(BaseModel): 3631 """ 3632 A reference from another config to an orphaned entry in a solution upgrade diff, explaining why the orphan cannot be safely removed. 3633 """ 3634 3635 id: str = Field(..., description="ID of the referencing config (`cfg_...`).") 3636 kind: str = Field( 3637 ..., 3638 description='Object type of the referencing config, e.g. `"Automation"` or `"Template"`.', 3639 ) 3640 lookup_key: str | None = Field( 3641 default=None, 3642 description="Human-readable stable identifier of the referencing config. `null` if not assigned.", 3643 ) 3644 reason: str = Field( 3645 ..., description="Explanation of how the referencing config depends on the orphaned entry." 3646 )
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):
3649class SolutionDiffEntry(BaseModel): 3650 """ 3651 A single config entry in a solution upgrade diff, describing what action will be taken on a specific config key. 3652 """ 3653 3654 action: str = Field( 3655 ..., 3656 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).', 3657 ) 3658 content_changed: bool = Field( 3659 ..., 3660 description="`true` if the config content differs between the existing and incoming solution versions.", 3661 ) 3662 id: str | None = Field( 3663 default=None, 3664 description="Config ID (`cfg_...`) if this entry corresponds to an existing config record. `null` for new additions.", 3665 ) 3666 key: str = Field( 3667 ..., description="Stable string key identifying this config entry within the solution." 3668 ) 3669 kind: str | None = Field( 3670 default=None, 3671 description='Config object type, e.g. `"Automation"` or `"Template"`. `null` if not yet known.', 3672 ) 3673 lookup_key: str | None = Field( 3674 default=None, 3675 description="Human-readable stable identifier for this config. `null` if not assigned.", 3676 ) 3677 mime_type_changed: bool = Field( 3678 ..., description="`true` if the MIME type of the config changed between versions." 3679 ) 3680 referenced_by: list[SolutionDiffReference] | None = Field( 3681 default=None, 3682 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.", 3683 ) 3684 relative_path_changed: bool = Field( 3685 ..., 3686 description="`true` if the relative path of the config within the solution changed between versions.", 3687 ) 3688 role: str = Field( 3689 ..., 3690 description="Role of this config within the solution. Indicates whether it is a primary config or a dependency.", 3691 ) 3692 virtual_path: str | None = Field( 3693 default=None, 3694 description="Hierarchical path of this config in the config tree. `null` if not assigned.", 3695 )
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):
3698class SolutionDiffSummary(BaseModel): 3699 """ 3700 Aggregate counts of each action type across all entries in a solution upgrade diff. 3701 """ 3702 3703 adds: int = Field( 3704 ..., description="Number of config entries that will be newly created by this upgrade." 3705 ) 3706 deletes: int = Field( 3707 ..., description="Number of config entries that will be deleted as part of the upgrade." 3708 ) 3709 noops: int = Field( 3710 ..., 3711 description="Number of config entries that are already up to date and require no changes.", 3712 ) 3713 orphans: int = Field( 3714 ..., 3715 description="Number of config entries present in the existing solution that are absent from the incoming version and have no external references blocking removal.", 3716 ) 3717 referenced_orphans: int = Field( 3718 ..., 3719 description="Number of orphaned config entries that cannot be removed because other configs still reference them.", 3720 ) 3721 updates: int = Field( 3722 ..., description="Number of config entries that exist and will be updated with new content." 3723 )
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
SolutionImportWarning(pydantic.main.BaseModel):
3726class SolutionImportWarning(BaseModel): 3727 """ 3728 A non-fatal finding surfaced by a Solution import. The import proceeds despite warnings; validation callers (dry-run) can choose to treat them as failures. 3729 """ 3730 3731 code: str = Field( 3732 ..., 3733 description='Machine-readable warning code. `"setup_requirements_dropped"`: a template or config body declares catalog-DSL `setup_requirements` that direct import does not convert installs read only `setup_actions`, so those setup steps would never surface.', 3734 ) 3735 message: str = Field( 3736 ..., description="Human-readable explanation of the warning and how to resolve it." 3737 ) 3738 path: str = Field( 3739 ..., 3740 description="Which bundle entry the warning is about, as `<slot>[<index>] (<relative_path>)`.", 3741 )
A non-fatal finding surfaced by a Solution import. The import proceeds despite warnings; validation callers (dry-run) can choose to treat them as failures.
class
SolutionImportResult(pydantic.main.BaseModel):
3744class SolutionImportResult(BaseModel): 3745 """ 3746 The machine-readable outcome of a Solution import attempt, indicating whether the import succeeded or requires an upgrade flow to resolve a version conflict. 3747 """ 3748 3749 code: str | None = Field( 3750 default=None, 3751 description='Machine-readable conflict code present when `status` is `"conflict"`, identifying the specific conflict reason. `null` when `status` is `"ready"`.', 3752 ) 3753 dry_run: bool = Field( 3754 ..., 3755 description="Whether this result was produced by a dry-run check. `true` when the import was validated without persisting any changes.", 3756 ) 3757 existing_solution_version: str | None = Field( 3758 default=None, 3759 description="Semver string of the Solution version already present in the library. `null` when no prior version exists.", 3760 ) 3761 incoming_solution_version: str | None = Field( 3762 default=None, 3763 description="Semver string of the Solution version in the bundle being imported. `null` when the bundle does not declare a version.", 3764 ) 3765 message: str | None = Field( 3766 default=None, 3767 description="Human-readable description of the import status or conflict reason, suitable for display in a confirmation dialog. `null` when no detail is available.", 3768 ) 3769 status: str = Field( 3770 ..., 3771 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.', 3772 ) 3773 upgrade_required: bool = Field( 3774 ..., 3775 description='Whether the caller must invoke the dedicated upgrade flow to complete the import. Mirrors `status == "conflict"` as a convenience boolean.', 3776 ) 3777 warnings: list[SolutionImportWarning] | None = Field( 3778 default=None, 3779 description="Non-fatal findings the import proceeded despite (present on real imports and dry-runs alike; defaults to an empty array). Dry-run validation callers should surface these or treat them as failures before applying the real import.", 3780 )
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.
status: str =
PydanticUndefined
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.
upgrade_required: bool =
PydanticUndefined
Whether the caller must invoke the dedicated upgrade flow to complete the import. Mirrors status == "conflict" as a convenience boolean.
class
SolutionImportResponse(pydantic.main.BaseModel):
3783class SolutionImportResponse(BaseModel): 3784 """ 3785 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. 3786 """ 3787 3788 created_at: str | None = Field( 3789 default=None, description="When the Solution config record was first created (ISO 8601)." 3790 ) 3791 id: str = Field(..., description="Solution config ID (`cfg_...`).") 3792 import_result: SolutionImportResult = Field( 3793 ..., 3794 description="Structured outcome of the import, including status, conflict details, and version information.", 3795 ) 3796 installed_configs: list[InstalledConfigEntry] | None = Field( 3797 default=None, 3798 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`.", 3799 ) 3800 kind: str = Field(..., description='Resource type. Always `"Solution"`.') 3801 lookup_key: str | None = Field( 3802 default=None, 3803 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.", 3804 ) 3805 solution: SolutionSummary = Field( 3806 ..., 3807 description="Full summary of the imported Solution, in the same shape as the individual Solution retrieval endpoint.", 3808 ) 3809 updated_at: str | None = Field( 3810 default=None, description="When the Solution config record was last modified (ISO 8601)." 3811 ) 3812 virtual_path: str | None = Field( 3813 default=None, 3814 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.", 3815 )
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.
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.
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
SolutionInstallResponseWebhook(pydantic.main.BaseModel):
3818class SolutionInstallResponseWebhook(BaseModel): 3819 """ 3820 One-time connection details for a webhook-auth Automation install. 3821 """ 3822 3823 signing_secret: str 3824 url: str
One-time connection details for a webhook-auth Automation install.
class
SolutionInstallResponse(pydantic.main.BaseModel):
3827class SolutionInstallResponse(BaseModel): 3828 """ 3829 The runtime resource provisioned by installing a Solution, along with a reference back to the source Solution config. 3830 """ 3831 3832 id: str = Field( 3833 ..., 3834 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.", 3835 ) 3836 kind: str = Field( 3837 ..., 3838 description='Type of the provisioned resource. One of `"Agent"`, `"Automation"`, `"AgentRoutine"`, `"AgentTool"`, `"AgentSkill"`, or `"AgentComputer"`.', 3839 ) 3840 lookup_key: str | None = Field( 3841 default=None, 3842 description="The `lookup_key` stamped on the provisioned resource. `null` for `AgentSkill`, which is a join record and does not carry a lookup key.", 3843 ) 3844 solution: str = Field( 3845 ..., 3846 description="Solution config ID (`cfg_...`) that was used as the source for this install.", 3847 ) 3848 webhook: SolutionInstallResponseWebhook | None = Field( 3849 default=None, 3850 description="One-time connection details for a webhook-auth Automation install.", 3851 )
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.
solution: str =
PydanticUndefined
Solution config ID (cfg_...) that was used as the source for this install.
class
SolutionInstance(pydantic.main.BaseModel):
3854class SolutionInstance(BaseModel): 3855 """ 3856 A customer-keyed instance stamped from an installed solution template. 3857 """ 3858 3859 agent: str | None = Field( 3860 default=None, 3861 description="Materialized agent for this customer (`agi_...`). `null` for a row without an agent.", 3862 ) 3863 agent_name: str | None = Field( 3864 default=None, 3865 description="Human-readable display name of the materialized agent. `null` when no agent is visible.", 3866 ) 3867 attachment_ref: dict[str, Any] | None = Field( 3868 default=None, 3869 description="Opaque tagged reference to the deployment target. Consumers interpret its kind.", 3870 ) 3871 created_at: datetime = Field(..., description="When this instance was stamped.") 3872 customer_key: str = Field(..., description="Stable vendor-defined key for the customer.") 3873 customer_label: str | None = Field( 3874 default=None, 3875 description="Human-readable customer label. `null` when the vendor did not provide one.", 3876 ) 3877 id: str = Field(..., description="Solution instance ID (`sli_...`).") 3878 local_edit_count: int | None = Field( 3879 default=None, 3880 description="Count of local agent edits relative to the pinned template. `null` when unavailable.", 3881 ) 3882 pinned_template_version: str | None = Field( 3883 default=None, 3884 description="Pinned template version record (`cfv_...`). `null` when no version is pinned.", 3885 ) 3886 pinned_version_number: int | None = Field( 3887 default=None, 3888 description="Human-readable version number of the pinned template. `null` when unavailable.", 3889 ) 3890 solution_template_config: str = Field( 3891 ..., 3892 description="Installed solution template config that stamped this instance (`cfg_...`).", 3893 ) 3894 status: Literal["active", "archived"] = Field( 3895 ..., description="Lifecycle status of this stamped instance." 3896 ) 3897 updated_at: datetime = Field(..., description="When this instance was last updated.")
A customer-keyed instance stamped from an installed solution template.
agent: str | None =
None
Materialized agent for this customer (agi_...). null for a row without an agent.
agent_name: str | None =
None
Human-readable display name of the materialized agent. null when no agent is visible.
attachment_ref: dict[str, typing.Any] | None =
None
Opaque tagged reference to the deployment target. Consumers interpret its kind.
customer_label: str | None =
None
Human-readable customer label. null when the vendor did not provide one.
local_edit_count: int | None =
None
Count of local agent edits relative to the pinned template. null when unavailable.
pinned_template_version: str | None =
None
Pinned template version record (cfv_...). null when no version is pinned.
pinned_version_number: int | None =
None
Human-readable version number of the pinned template. null when unavailable.
solution_template_config: str =
PydanticUndefined
Installed solution template config that stamped this instance (cfg_...).
class
SolutionInstanceListResponse(pydantic.main.BaseModel):
3900class SolutionInstanceListResponse(BaseModel): 3901 """ 3902 A forward cursor-paginated page of customer solution instances. 3903 """ 3904 3905 after_cursor: str | None = Field( 3906 default=None, 3907 description="Opaque cursor for the next page. `null` when this is the final page.", 3908 ) 3909 before_cursor: str | None = Field( 3910 default=None, description="Always `null`; this endpoint supports forward pagination only." 3911 ) 3912 data: list[SolutionInstance] = Field( 3913 ..., description="Customer solution instances in stable customer-key order." 3914 ) 3915 has_more: bool = Field(..., description="Whether another page exists after this one.")
A forward cursor-paginated page of customer solution instances.
class
SolutionListResponse(pydantic.main.BaseModel):
3918class SolutionListResponse(BaseModel): 3919 """ 3920 A paginated collection of Solution summaries, with page metadata for navigating the result set. 3921 """ 3922 3923 data: list[SolutionSummary] = Field( 3924 ..., 3925 description="Array of Solution summary objects for the current page, in the order returned by the query.", 3926 ) 3927 has_next: bool = Field( 3928 ..., description="`true` when a subsequent page exists; `false` when this is the last page." 3929 ) 3930 has_prev: bool = Field( 3931 ..., description="`true` when a preceding page exists; `false` when this is the first page." 3932 ) 3933 page: int = Field(..., description="1-based index of the current page.") 3934 page_size: int = Field(..., description="Maximum number of results included per page.") 3935 total_entries: int = Field( 3936 ..., 3937 description="Total number of Solutions matching the query after deduplication by `solution_id` across owner scopes.", 3938 ) 3939 total_pages: int = Field( 3940 ..., description="Total number of pages available at the current `page_size`." 3941 )
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):
3944class SolutionTagSummary(BaseModel): 3945 """ 3946 A single solution tag definition, representing a named classification label that can be applied to solutions. 3947 """ 3948 3949 created_at: datetime | None = Field( 3950 default=None, 3951 description="When the solution tag was first created (ISO 8601). `null` if unavailable.", 3952 ) 3953 description: str | None = Field( 3954 default=None, 3955 description="Short prose explanation of what the tag represents. `null` if not provided.", 3956 ) 3957 id: str = Field(..., description="Solution tag config ID (`cfg_...`).") 3958 key: str = Field( 3959 ..., 3960 description="Stable string key for this tag, referenced by `Solution.tag_keys` to associate solutions with this tag.", 3961 ) 3962 kind: str = Field(..., description='Object type discriminator. Always `"SolutionTag"`.') 3963 lookup_key: str | None = Field( 3964 default=None, 3965 description="Human-readable stable identifier for this tag config, used for lookups and imports. `null` if not assigned.", 3966 ) 3967 metadata: dict[str, Any] | None = Field( 3968 default=None, 3969 description="Arbitrary key-value metadata attached to this tag. Empty object `{}` when no metadata is present.", 3970 ) 3971 name: str | None = Field( 3972 default=None, description="Human-readable display name for the tag. `null` if not yet set." 3973 ) 3974 org: str | None = Field( 3975 default=None, 3976 description="ID of the organization that owns this tag (`org_...`). `null` for system-scoped tags.", 3977 ) 3978 owners: list[str] = Field( 3979 ..., 3980 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).', 3981 ) 3982 sort_order: int | None = Field( 3983 default=None, 3984 description="Optional integer hint for ordering tags in UI lists. Lower values sort first. `null` if not set.", 3985 ) 3986 updated_at: datetime | None = Field( 3987 default=None, 3988 description="When the solution tag was last modified (ISO 8601). `null` if unavailable.", 3989 ) 3990 virtual_path: str | None = Field( 3991 default=None, 3992 description="Hierarchical path used to organize this tag in the config tree. `null` if not assigned.", 3993 )
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):
3996class SolutionTagListResponse(BaseModel): 3997 """ 3998 Paginated list of solution tag summaries returned by the list solution tags endpoint. 3999 """ 4000 4001 data: list[SolutionTagSummary] = Field( 4002 ..., description="Array of solution tag objects for the current page." 4003 ) 4004 has_next: bool = Field( 4005 ..., description="`true` if a subsequent page exists; `false` when this is the last page." 4006 ) 4007 has_prev: bool = Field( 4008 ..., description="`true` if a preceding page exists; `false` when this is the first page." 4009 ) 4010 page: int = Field(..., description="Current page number (1-indexed).") 4011 page_size: int = Field(..., description="Maximum number of results returned per page.") 4012 total_entries: int = Field( 4013 ..., 4014 description="Total number of distinct solution tags across all pages, after deduplication by key.", 4015 ) 4016 total_pages: int = Field( 4017 ..., description="Total number of pages available at the current `page_size`." 4018 )
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):
4021class SolutionUpgradeResult(BaseModel): 4022 """ 4023 The outcome of a solution upgrade operation, including the computed diff and conflict status. 4024 """ 4025 4026 changes: list[SolutionDiffEntry] = Field( 4027 ..., 4028 description="Ordered list of individual config change entries representing every add, update, noop, orphan, and delete in the diff.", 4029 ) 4030 code: str | None = Field( 4031 default=None, 4032 description='Machine-readable conflict code when `status` is `"conflict"`, e.g. `"review_required"`. `null` when there is no conflict.', 4033 ) 4034 dry_run: bool = Field( 4035 ..., 4036 description="`true` when the upgrade was computed without writing any changes; `false` when changes were committed.", 4037 ) 4038 existing_solution_version: str | None = Field( 4039 default=None, 4040 description="Version string of the currently installed solution, as declared in its manifest. `null` if no prior version is installed.", 4041 ) 4042 incoming_solution_version: str | None = Field( 4043 default=None, 4044 description="Version string of the incoming solution to be installed, as declared in its manifest. `null` if the incoming manifest omits a version.", 4045 ) 4046 message: str | None = Field( 4047 default=None, 4048 description="Human-readable description of the conflict or error. `null` when there is no conflict.", 4049 ) 4050 review_fingerprint: str | None = Field( 4051 default=None, 4052 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.", 4053 ) 4054 status: str = Field( 4055 ..., 4056 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.', 4057 ) 4058 summary: SolutionDiffSummary = Field( 4059 ..., description="Aggregate counts of each action type across all diff entries." 4060 ) 4061 version_change: str = Field( 4062 ..., 4063 description='Describes the nature of the version transition. One of `"upgrade"`, `"downgrade"`, `"same"`, or `"unknown"`.', 4064 )
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):
4067class SolutionUpgradeResponse(BaseModel): 4068 """ 4069 Response returned by the solution upgrade endpoint, containing the solution record, the full upgrade diff, and the resulting installed configs. 4070 """ 4071 4072 created_at: datetime | None = Field( 4073 default=None, 4074 description="When the solution config record was first created (ISO 8601). `null` if unavailable.", 4075 ) 4076 id: str = Field(..., description="Config ID of the solution record (`cfg_...`).") 4077 installed_configs: list[InstalledConfigEntry] | None = Field( 4078 default=None, 4079 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.", 4080 ) 4081 kind: str = Field(..., description='Object type discriminator. Always `"Solution"`.') 4082 lookup_key: str | None = Field( 4083 default=None, 4084 description="Human-readable stable identifier for this solution config. `null` if not assigned.", 4085 ) 4086 solution: SolutionSummary = Field( 4087 ..., 4088 description="Summary of the solution being upgraded, including its name, manifest metadata, and tag keys.", 4089 ) 4090 updated_at: datetime | None = Field( 4091 default=None, 4092 description="When the solution config record was last modified (ISO 8601). `null` if unavailable.", 4093 ) 4094 upgrade_result: SolutionUpgradeResult = Field( 4095 ..., 4096 description="Detailed result of the upgrade operation, including the computed diff and any conflict information.", 4097 ) 4098 virtual_path: str | None = Field( 4099 default=None, 4100 description="Hierarchical path of the solution in the config tree. `null` if not assigned.", 4101 )
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.