SPB Git

Repository Public

trigger-runs.md 5.1 KB 149 lines markdown

1# Trigger workspace agent runs23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45Use the Workspace Agents API to programmatically trigger a published ChatGPT6workspace agent through API.78This endpoint is designed to integrate with workflows where an external system9needs to trigger an agent outside of the ChatGPT UI and third party10triggers offered.1112## Endpoint1314```text15POST https://api.chatgpt.com/v1/workspace_agents/{id}/trigger16GET  https://api.chatgpt.com/v1/workspace_agents/{id}/runs/{run_id}17```1819`id` is the stable public API trigger identifier for the published API channel,20in a `agtch_XXX` format.2122`run_id` is the trigger run identifier returned by a beta trigger request, in an23`apirun_XXX` format.2425## Authentication2627Authenticate with a Workspace Agent access token:2829```bash30Authorization: Bearer $AGENT_ACCESS_TOKEN31```3233See [Authenticate with Workspace Agent access tokens](https://developers.openai.com/workspace-agents/authentication)34for how to provision a token.3536## Request body3738```json39{40  "conversation_key": "email_thread_abc",41  "input": "Summarize the customer escalation and recommend a response."42}43```4445### Fields4647| Field              | Type   | Required | Description                                                                                                 |48| ------------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------------- |49| `input`            | string | Yes      | Message text passed to the agent as trigger input.                                                          |50| `conversation_key` | string | No       | Caller-defined stable identifier for continuing the same agent conversation across multiple trigger events. |5152To safely retry the same trigger event, send an optional `Idempotency-Key`53header. Reuse the same key only when retrying the same event. Requests to the54same API trigger with the same key return the original accepted outcome instead55of adding a second trigger event to the queue.5657## Response5859The API durably queues the trigger event and returns `202 Accepted` with a link60to the ChatGPT conversation:6162```json63{64  "conversation_url": "https://chatgpt.com/c/123"65}66```6768The agent's response cannot currently be retrieved through the API.6970## Track run status7172Run status polling is in beta. To receive a trigger run ID, include73  `OpenAI-Beta: workspace_agent_runs=v1` when you trigger the agent.7475With the beta header, the trigger response includes `agent_trigger_run_id`:7677```json78{79  "conversation_url": "https://chatgpt.com/c/123",80  "agent_trigger_run_id": "apirun_123"81}82```8384Poll the run ID until it reaches a terminal status:8586```bash87curl https://api.chatgpt.com/v1/workspace_agents/$API_TRIGGER_ID/runs/$RUN_ID \88  -H "Authorization: Bearer $AGENT_ACCESS_TOKEN"89```9091The response describes the latest run state:9293```json94{95  "object": "workspace_agent.trigger_run",96  "id": "apirun_123",97  "status": "in_progress",98  "created_at": 1784763880,99  "agent_id": "agt_123",100  "api_trigger_id": "agtch_123",101  "conversation_url": "https://chatgpt.com/c/123",102  "error": null103}104```105106| Status        | Description                                                      |107| ------------- | ---------------------------------------------------------------- |108| `queued`      | The trigger was accepted and is waiting to start.                |109| `in_progress` | The agent is running.                                            |110| `suspended`   | The agent is waiting for an external action or tool.             |111| `completed`   | The agent run completed successfully.                            |112| `failed`      | The agent run failed. See `error.code` for the failure category. |113114`completed` and `failed` are terminal statuses. For failed runs, `error.code`115can be `dispatch_failed` or `run_failed`.116117## Example118119```bash120curl -i https://api.chatgpt.com/v1/workspace_agents/agtch_complaints_123/trigger \121  -X POST \122  -H "Authorization: Bearer $AGENT_ACCESS_TOKEN" \123  -H "Content-Type: application/json" \124  -H "OpenAI-Beta: workspace_agent_runs=v1" \125  -d '{126    "conversation_key": "email_thread_abc",127    "input": "Summarize the newest escalation and recommend next steps."128  }'129```130131Expected response:132133```text134HTTP/1.1 202 Accepted135136{137  "conversation_url": "https://chatgpt.com/c/123",138  "agent_trigger_run_id": "apirun_123"139}140```141142## Errors143144| Status             | When returned                                                                              |145| ------------------ | ------------------------------------------------------------------------------------------ |146| `401 Unauthorized` | The bearer credential is missing, expired, revoked, or invalid.                            |147| `403 Forbidden`    | The token is valid but does not have permission to trigger the requested workspace agent.  |148| `404 Not Found`    | The trigger or run does not exist or is not visible to the caller's workspace.             |149| `409 Conflict`     | The trigger could not be accepted because the channel or agent is not in a runnable state. |
Files main
Menu

Theme