> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automate.ax/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Automate.ax automations are TypeScript programs.
> Use Bun for installation and command examples.
> Use Automate.ax for the product name and automate.ax for the package, CLI, and domain.
> Treat documented public APIs as current; do not invent transitional or deprecated names.

# Run workspace agent

> Run a ChatGPT Workspace Agent and continue after it finishes.

`chatgpt.runWorkspaceAgent` triggers a published ChatGPT Workspace Agent, checks its status after durable delays, and emits the terminal run metadata.

```ts automations/run-chatgpt-agent.automation.ts theme={null}
import { automation, onHttpRequest, sendEmail, t } from "automate.ax"
import { chatgpt } from "automate.ax/chatgpt"
import { z } from "zod"

export default automation("Run ChatGPT agent", () => {
  const request = onHttpRequest({
    body: z.object({ message: z.string() }),
    scope: "automation",
  })
  const run = chatgpt.runWorkspaceAgent({
    apiTriggerId: "agtch_engineering_123",
    conversationKey: request.headers["x-thread-id"],
    idempotencyKey: request.headers["x-event-id"],
    input: request.body.message,
  })

  sendEmail({
    subject: t`ChatGPT agent ${run.status}`,
    text: run.conversationUrl,
  })
})
```

The trigger fields match `chatgpt.triggerWorkspaceAgent`. Reuse `conversationKey` for related events that should continue the same ChatGPT conversation. Reuse an `idempotencyKey` only when retrying the same event; it makes trigger submission replay-safe. Optional second argument `{ account }` defaults to the project binding and is reused for every status check. Because checks arrive as independent roots, this account selection must be a literal binding name or a `chatgptAccount()` reference, not a signal.

`pollInterval` accepts a compact duration or milliseconds and defaults to `"30s"`. `maxPolls` accepts `1` through `120` and defaults to `60`, giving the default wait roughly 30 minutes to finish. Automate.ax checks immediately, then runs each remaining check as a new action after a durable delay. It does not keep an action invocation open between checks.

The result matches `chatgpt.getWorkspaceAgentRun`: agent, API trigger, and run IDs; creation time; terminal `status`; nullable failure details; and `conversationUrl`. `completed` and `failed` are terminal. Failed runs report `dispatch_failed` or `run_failed` in `error.code`. The signal fails if the run remains `queued`, `in_progress`, or `suspended` for the complete polling budget.

ChatGPT does not currently expose the agent's response through the Workspace Agents API. Downstream automation receives run metadata and the ChatGPT conversation URL, not the response content.

<Warning>
  `chatgpt.runWorkspaceAgent` uses hidden delay triggers and introduces
  additional context roots. Anchor literal submissions to their initiating
  signal with `withPrerequisites`. The example is already anchored because its
  input comes from the HTTP request.
</Warning>