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