> ## Documentation Index > Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Workflows > Build automations for AGO conversations, tickets, and external APIs Administrators can create workflows in **AI Studio → Workflows**. Each workflow connects a trigger to actions, conditions, waits, and a result. Your platform administrator must check **Workflows enabled** in **AGO Config** first. It is off by default for each workspace. Disabling it hides the editor and workflow MCP tools and blocks API access and new triggers. Already accepted executions can finish; drafts and published versions are kept. ## Create and publish 1. Select **Create workflow**, enter a name, and describe what it does. 2. Add input fields in **Settings** if the workflow needs information at launch. 3. Open **Editor**, select the trigger block, and choose its type under **Trigger** in **Block settings**. Select **+** on a block’s output to open **Add a block**. Search by name or browse the grouped actions, then choose one to connect it to that output. Existing connections stay in place. 4. Select a block to configure it and give it a **Block name**. Icons identify block types in the editor, connection list, and execution logs. Connect blocks by dragging between their handles or choosing **Connect an existing block…** in the block settings. 5. **Save draft**, then **Publish**. Publishing validates the blocks and their connections. The side panel switches between **Add a block** and **Block settings**, leaving more room for the graph. On smaller screens it appears below the graph. Select a workflow in the list to open it. To delete one, open the **⋮** menu at the end of its row and choose **Delete**: the workflow, its versions and its execution history are removed, and agents and triggers stop using it. Cancel its active executions first. Saving a draft does not change the published version. Executions already in progress keep the version they started with. **Pause triggers** stops new launches; cancel an existing execution separately. ## Add parallel branches Select **+** on the source block’s output, or **Add a new branch** in its settings, then choose an action. Repeat from the same output to add more branches. Conditions have separate **Yes** and **No** buttons; the library shows which branch you are extending. All connections on the chosen output run. Branches run independently. For example, a trigger can create a ticket and start a separate waiting branch at the same time. A wait pauses only its own branch. An execution completes after every active branch finishes; a failure stops further work in the remaining branches but does not undo completed actions. Each block accepts one incoming connection. Branches cannot merge, loop back, or read each other’s results. A branch can read the common blocks that precede it. Renaming a block preserves its identifier and data references. With one final block, the execution output is that block’s result. With several final blocks, **Output** contains their results under their block identifiers. The combined output must fit within 256 KiB. ## Choose a trigger | Trigger | Starts when | | - | - | | Manual | An administrator selects **Run workflow** | | AGO event | A conversation or ticket is created, or its status changes | | Schedule | The configured interval elapses; intervals use minutes | | Incoming webhook | An external service sends an authenticated request | | Agent tool call | An allowed AGO agent chooses the workflow as a tool | Event inputs include `thread_id` or `ticket_id`, plus `status_id` and `previous_status_id`. An absent status is an empty string. Conversation events refer to the conversation's admin status. Changes made by a workflow do not start another workflow through these model events. Schedules use no input fields and skip overlapping executions. Event, schedule, and webhook actions run with the workflow creator's permissions. Agent actions use the calling user's permissions; granting an agent access does not grant its users administrator rights. ## Choose how it runs In **Settings**, **Execution** decides whether the caller waits for the result: | Execution | Use it when | The caller receives | | - | - | - | | **In the background** (default) | The work is long, waits, or nobody needs the answer right away | An execution reference; the result appears in **Executions** | | **Wait for the result** | An agent or an external system needs the answer, for example an API call followed by a small data transformation | The workflow output, or its error | A workflow that waits for its result must start from a manual, webhook or agent trigger, finish within 20 seconds, contain at most 10 blocks and no Wait block. If it fails or takes too long, the caller receives the error and AGO does not retry it; the execution and its error stay in **Executions**. If AGO stops while it runs, for example during an update, the caller loses the connection and the execution is shown as interrupted after two minutes. Schedules and AGO events always run in the background. ## Use data between blocks Choose how each field is filled with the selector next to its name: | Mode | Use it to | Stored as | | - | - | - | | **Value** | Enter a fixed value | the value itself | | **Reference** | Reuse data unchanged, keeping its type | `{"$ref": "input.message"}` | | **Text with references** | Write text that includes data | `{"$template": "Hello {{input.name}}"}` | | **Function** | Transform data: text, numbers, lists, dates | `{"$fn": "lower", "args": [...]}` | References point to: * `input.message`: a launch input named `message`. * `steps.create_ticket.ticket_id`: a completed block's result. Expand **Data reference** in that block’s settings to find its identifier. * `input`: the complete input object. A branch can only reference blocks that run before it. A reference to a missing field stops the execution; use `get` with a default value for optional fields. ### Text with references Place references between double braces: `Ticket {{steps.create_ticket.ticket_id}} for {{input.email}}`. Text is inserted as is, numbers and booleans as written, an empty value as nothing, and lists or objects as JSON. ### Functions Each function receives a JSON list of arguments. An argument can be a value, a reference, a text with references or another function. For example, this returns the lower-case, trimmed email: ```json theme={null} {"$fn": "lower", "args": [{"$fn": "trim", "args": [{"$ref": "input.email"}]}]} ``` | Category | Functions | | - | - | | Text | `concat`, `lower`, `upper`, `trim`, `replace`, `split`, `join`, `slice`, `length`, `starts_with`, `ends_with`, `contains`, `url_encode`, `base64_encode`, `base64_decode`, `sha256` | | Values and logic | `get`, `coalesce`, `if`, `equals`, `not`, `and`, `or`, `type_of`, `to_text`, `to_number`, `to_boolean`, `json_parse`, `json_stringify` | | Numbers | `add`, `subtract`, `multiply`, `divide`, `round`, `min`, `max` | | Lists | `first`, `last`, `pluck`, `where`, `find`, `unique`, `sort`, `flatten`, `concat_lists` | | Objects | `pick`, `omit`, `merge`, `keys`, `values` | | Dates | `now`, `to_timezone`, `format_date`, `add_to_date`, `date_diff` | The catalogue (`get_workflow_catalogue`) lists each function's arguments and behaviour. Functions check their argument types: `lower` of a number stops the execution with a clear error rather than guessing. Dates use ISO 8601 text such as `2026-10-17T09:30:00Z`; a date without an offset is read as UTC. Timezones use names such as `Europe/Paris`. For a condition, compute a boolean with a function, for example `and` or `contains`, then compare it with `true`. Use **Transform data** to build a JSON object whose fields mix values, references, texts and functions. Functions run inside AGO and are limited to 1,000 calls per block and 256 KiB of text per result. ## Connect external services Use **HTTP request** to call a public HTTPS API with GET, POST, PUT, or DELETE. Private addresses and redirects are blocked. Responses must fit within 128 KiB. To build the address from data, use **Text with references** and keep the start fixed, for example `https://api.example.com/customers/{{input.customer_id}}?expand={{input.fields}}`. AGO encodes each inserted value, so data from a webhook or a conversation cannot change the host, add path segments or add query parameters. Publishing rejects a template that inserts data before the first `/` or `?` after the host. A **Reference** or **Function** can supply a complete address instead; it is checked when the request is sent. If the API is only reachable on your private network, for example through a VPN connection set up with AGO, contact AGO to allow its hostname for your workspace. The same allowed hostnames apply to HTTP tools and workflows. To authenticate, select a saved HTTP tool under **Connection**. Its credentials remain in AGO and can only be used with the connection's configured host. Configure credentials in the existing HTTP tool settings instead of entering secrets in workflow inputs. The calling user must have access to the selected tool. `Authorization`, `Proxy-Authorization`, `Cookie`, `X-API-Key` and `API-Key` headers can only come from a connection: workflows are readable by every administrator, so secrets typed into them are rejected. By default, any status outside 2xx stops the execution. List the 4xx statuses your workflow handles in **Statuses handled by the workflow**, for example `[404]` for a lookup that may find nothing or `[409]` for a record that already exists. These responses then continue to the next block, which can branch on `steps..status`: for example, a condition comparing it with `404` leads to a block that creates the missing contact. 429 and 5xx statuses always stop the execution. The HTTP result contains `status` and `body`. Ticket creation returns `ticket_id`; status actions use the existing AGO permissions and services. ## Let agents start workflows Choose **Agent tool call**, describe when the workflow should be used, define its input fields, and select **Allowed agents** in Settings. Publish the workflow. The agent receives a tool with the workflow's input schema. With **Wait for the result**, the tool returns the workflow output, so the agent can use it in its answer. In the background, starting the workflow returns an execution reference immediately, and the agent checks its status and result with `workflow_status`. It can only inspect executions belonging to the calling user and agent. Removing an agent's access blocks further workflow actions for that agent. ## Call a webhook Choose **Incoming webhook**, save the workflow, and generate a webhook secret in Settings. Copy it immediately; AGO stores only its hash. Generating another secret invalidates the previous one. Send a POST to the displayed path on your tenant's AGO API domain, with the secret in `X-AGO-Webhook-Secret`: ```json theme={null} { "request_key": "external-event-123", "input": { "message": "Please open a support ticket" } } ``` With **Wait for the result**, the response also contains the workflow `output`, or the `error` when it failed. Reuse the same request key when retrying the same event. Reusing a key with different input is rejected. Use a new key for a new event. ## Inspect executions Open **Executions** to view the latest run, or select an earlier execution. The list shows each execution's status, when it started and how long it took. The selected execution shows its status, start and end times, elapsed time, published version and whether the caller waited for the result. Active executions refresh automatically. Starting a workflow opens its execution. **Timeline** lists the executed blocks in order, with their status and duration; the bar shows when each block ran within the execution. Select a block to see its times, its error and its output. Blocks keep the names saved in the execution's published version, so later renames do not change earlier executions. Search by block name, identifier or error message, or select **Errors only**. **Execution input** and **Output** show the data received and returned, with a copy button. **Download JSON** saves the full execution record, including blocks hidden by your search. A Wait block records **Timer scheduled** when its delay is set. This does not mean the wait has elapsed; the next step appears when execution resumes. **Run workflow** executes real actions using the published version, even when the editor contains an unsaved draft. Waiting workflows resume after AGO restarts or is updated. Completed steps are reused. Cancellation stops future steps; it does not undo actions that have already taken effect. If an external action loses its response, AGO can report **Outcome uncertain**. Check the destination before launching another execution: the external service may already have performed the action. An HTTP request that AGO refuses before sending it (blocked address, invalid URL, unknown connection), that cannot reach the destination, or that the API rejects with a 4xx status is reported as failed instead: nothing was performed, so you can fix the cause and start a new execution. AGO sends an idempotency key with HTTP requests, but support for that key depends on the destination. This release supports up to 50 blocks per workflow and 100 active executions per tenant. Loops and merging branches are not supported. Input and block results are limited to 256 KiB. Existing connector synchronizations continue to use their current execution system. ## Create and edit through the API or MCP Grant your API key or OAuth connection **workflows:write** to create, edit, publish and run workflows. **workflows:read** allows reading the catalogue, drafts and execution logs, and validating a graph. These permissions apply to the current workspace. Use an active administrator's key or connection for manual runs. Start with `GET /api/v1/workflows/catalogue` or the MCP tool `get_workflow_catalogue`. It returns supported node types, versions, configuration schemas, output ports, functions, agents and saved HTTP connections. Use these definitions when building a graph. Create a draft with just its name to get a manual trigger: ```bash theme={null} curl "$AGO_API_URL/api/v1/workflows" \ -H "X-API-Key: $AGO_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Route support requests"}' ``` Read the draft with `GET /api/v1/workflows/{id}` before editing. Send its current `revision` with `PUT /api/v1/workflows/{id}`. Omitted fields are preserved; a supplied `draft` replaces the whole graph, and `allowed_agent_ids` replaces the agent list. For example, renaming does not require resending the graph: ```json theme={null} {"revision": 1, "name": "Route urgent support requests"} ``` A graph contains `nodes`, `edges`, `input_schema` and optionally `execution` (`async` by default, or `sync` to wait for the result). Each node has an `id`, `type`, `version` and `config`; `name` and `position` are optional. Keep existing IDs and positions when editing. Edges specify `source`, `target` and `port`, such as `next`, `true` or `false`. JSON references use `{"$ref":"input.message"}` or `{"$ref":"steps.create_ticket.ticket_id"}`; texts use `{"$template":"Hello {{input.name}}"}` and functions `{"$fn":"lower","args":[...]}` (see [Functions](#functions)). Validate a graph without saving or executing it using `POST /api/v1/workflows/validate` with `{"draft": ...}`. When ready, publish the saved revision with `POST /api/v1/workflows/{id}/publish` and `{"revision": 2}`. Publication enables the configured triggers. A `409` response means someone edited the draft; read it again before reapplying your changes. The MCP equivalents are `create_workflow`, `get_workflow`, `update_workflow`, `validate_workflow` and `publish_workflow`. For example, ask your connected assistant: “Create a draft workflow that routes urgent support requests. Use the available node catalogue and validate it before I publish.” To run a published workflow, call `POST /api/v1/workflows/{id}/runs` or `run_workflow` with `input` and a unique `request_key`. Reuse that key only to retry the same execution request. For a `sync` workflow, the response already contains the final status and `output`. Read its logs with `GET /api/v1/workflows/runs/{run_id}` or `get_workflow_run`. Pause future triggers through `PUT /api/v1/workflows/{id}/enabled` with `{"enabled": false}`; cancel an accepted execution through `POST /api/v1/workflows/runs/{run_id}/cancel`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.