archastro.platform.v1.resources.automations

  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: f8a6c28afc3a
  4
  5from __future__ import annotations
  6
  7from typing import Any, TypedDict
  8
  9from ...runtime.http_client import HttpClient, SyncHttpClient
 10from ...types.automations import AutomationRun
 11
 12
 13class AutomationInvokeInput(TypedDict, total=False):
 14    "Invoke an automation"
 15
 16    idempotency_key: str | None
 17    "Unique key to deduplicate concurrent or retried invocations. A second request with the same key returns the existing run instead of creating a new one."
 18    participants: dict[str, Any] | None
 19    "Map of symbolic participant refs to agent ids (`agi_...` or UUID) for distributed embed_agent handoffs. Stored in the run's top-level `participants` field."
 20    payload: dict[str, Any] | None
 21    "Free-form invoke input the workflow parameters. Validated against the automation's `input_schema` when configured. Stored as `event_payload` and becomes the workflow `$` after trigger unwrap (e.g. `{{$.bug}}`)."
 22
 23
 24class AsyncAutomationResource:
 25    def __init__(self, http: HttpClient):
 26        self._http = http
 27
 28    async def invoke(self, automation: str, input: AutomationInvokeInput) -> AutomationRun:
 29        """
 30        Invoke an automation
 31        Triggers a single run of an automation that has `type: "invoked"`. Returns
 32        the resulting automation run object, which you can use to poll or display
 33        run status.
 34        Both server-to-server (secret key) and user (publishable key + JWT) auth
 35        are supported. The automation's `invoke_auth` setting controls which auth
 36        modes are accepted; requests using an unsupported mode are rejected with
 37        403. For server-to-server callers the run executes under the identity
 38        configured in the automation's `run_as_user` or `run_as_agent` fields. For
 39        authenticated user callers the invoking user's identity is used
 40        automatically.
 41        If you supply an `idempotency_key`, a second request with the same key
 42        returns the existing run rather than creating a new one.
 43        ## Body fields
 44        * `payload` free-form invoke input. **This is the workflow parameters**:
 45        validated against `input_schema` when configured, stored as
 46        `event_payload`, and becomes the workflow `$` after trigger unwrap
 47        (e.g. `{{$.bug}}` for `{"bug":"upload fails"}`).
 48        * `participants` optional map of symbolic participant refs to agent ids
 49        for distributed `embed_agent` nodes, e.g.
 50        `{"investigator":"agi_...","evaluator":"agi_..."}`. Stored in the
 51        run's top-level `participants` field (not inside free-form payload) and
 52        exposed to workflows through their system context.
 53        Same top-level `payload` + `participants` shape as routine invoke.
 54
 55        Args:
 56            automation: Automation ID (`auto_...`) or `lookup_key` of the automation to invoke.
 57            input: Request body.
 58            input.idempotency_key: Unique key to deduplicate concurrent or retried invocations. A second request with the same key returns the existing run instead of creating a new one.
 59            input.participants: Map of symbolic participant refs to agent ids (`agi_...` or UUID) for distributed embed_agent handoffs. Stored in the run's top-level `participants` field.
 60            input.payload: Free-form invoke input the workflow parameters. Validated against the automation's `input_schema` when configured. Stored as `event_payload` and becomes the workflow `$` after trigger unwrap (e.g. `{{$.bug}}`).
 61
 62        Returns:
 63            The automation run created by this invocation.
 64        """
 65        return await self._http.request(
 66            f"/api/v1/automations/{automation}/invoke",
 67            method="POST",
 68            body=input,
 69            response_type=AutomationRun,
 70        )
 71
 72
 73class AutomationResource:
 74    def __init__(self, http: SyncHttpClient):
 75        self._http = http
 76
 77    def invoke(self, automation: str, input: AutomationInvokeInput) -> AutomationRun:
 78        """
 79        Invoke an automation
 80        Triggers a single run of an automation that has `type: "invoked"`. Returns
 81        the resulting automation run object, which you can use to poll or display
 82        run status.
 83        Both server-to-server (secret key) and user (publishable key + JWT) auth
 84        are supported. The automation's `invoke_auth` setting controls which auth
 85        modes are accepted; requests using an unsupported mode are rejected with
 86        403. For server-to-server callers the run executes under the identity
 87        configured in the automation's `run_as_user` or `run_as_agent` fields. For
 88        authenticated user callers the invoking user's identity is used
 89        automatically.
 90        If you supply an `idempotency_key`, a second request with the same key
 91        returns the existing run rather than creating a new one.
 92        ## Body fields
 93        * `payload` free-form invoke input. **This is the workflow parameters**:
 94        validated against `input_schema` when configured, stored as
 95        `event_payload`, and becomes the workflow `$` after trigger unwrap
 96        (e.g. `{{$.bug}}` for `{"bug":"upload fails"}`).
 97        * `participants` optional map of symbolic participant refs to agent ids
 98        for distributed `embed_agent` nodes, e.g.
 99        `{"investigator":"agi_...","evaluator":"agi_..."}`. Stored in the
100        run's top-level `participants` field (not inside free-form payload) and
101        exposed to workflows through their system context.
102        Same top-level `payload` + `participants` shape as routine invoke.
103
104        Args:
105            automation: Automation ID (`auto_...`) or `lookup_key` of the automation to invoke.
106            input: Request body.
107            input.idempotency_key: Unique key to deduplicate concurrent or retried invocations. A second request with the same key returns the existing run instead of creating a new one.
108            input.participants: Map of symbolic participant refs to agent ids (`agi_...` or UUID) for distributed embed_agent handoffs. Stored in the run's top-level `participants` field.
109            input.payload: Free-form invoke input the workflow parameters. Validated against the automation's `input_schema` when configured. Stored as `event_payload` and becomes the workflow `$` after trigger unwrap (e.g. `{{$.bug}}`).
110
111        Returns:
112            The automation run created by this invocation.
113        """
114        return self._http.request(
115            f"/api/v1/automations/{automation}/invoke",
116            method="POST",
117            body=input,
118            response_type=AutomationRun,
119        )