Build your first workflow

Create a support desk of three agents, try it in the chat, make it ask before a handoff, watch what it costs, and embed it. Then see the same workflow as a file you can keep in source control.

See Workflows for what a workflow is. This page is the hands-on version.

1. Start from the Support desk template

Open Workflows and press New workflow. Choose the Router — Support desk template, name the workflow support-desk, and create it.

The console creates four things: three agents called support-desk-triage, support-desk-billing and support-desk-tech, each with a short system prompt written for its job, and the workflow that connects them. They belong to the console’s own plugin, named ui, so you can edit them like any other agent.

You land on the workflow’s page. Its tabs are Workflow, Details, Versions, Traces, Monitor, Evaluation, API and Embed, and Sharing if you can manage who sees it.

2. Look at it on the canvas

The Workflow tab shows the workflow as a canvas, and a switch turns it into the same workflow as YAML. Each agent is a box. A Start box points at the agent that answers first, support-desk-triage. Solid arrows are transfers: triage to billing, triage to tech, and one back from each specialist.

Double-click an agent’s box to edit its prompt, model, tools and knowledge. The change is saved to that agent, so it applies everywhere the agent is used. Press Run to open the chat.

Select an arrow to see its kind, its when hint and its approval switch.

3. Try it

Press Run and the chat opens over the canvas. Ask I was charged twice this month. Triage reads it and transfers to billing, and billing answers. Each reply is labelled with the agent that wrote it.

While a run is going the canvas follows it: the active agent is highlighted, and each box shows how many model calls it made and what they cost.

Ask Now, the app will not start. Billing’s prompt tells it to hand anything that is not billing back to triage, which should pass it on to tech. The agents decide each handoff themselves, so read the labels to see who actually answered.

4. Ask before a handoff

Select the arrow from triage to billing and turn on Requires approval. Press Save.

Send the billing question again. The run stops before the handoff, and the chat asks you to allow it. Allow it and billing answers. Deny it and triage carries on without the handoff, and says so.

Over the API the paused run ends with status interrupted, and you resume it with your decision. See Threads & runs.

5. Watch it

Open Monitor for the last day’s runs, errors and latency. Cost by agent (24h) sits below them: one row per agent, with its model calls, tokens in and out, and cost. It counts each agent’s own model calls inside this workflow. Search embedding and reranking are not included. A model with no configured price shows as Not priced.

Open Traces to read one run. The trace has one span for each agent that took a turn, so you can see which agent made which call. See Read traces and evals.

6. Evaluate it

Open Evaluation and press Run evaluation to run the workflow against a golden set. The run reports a pass or fail, like an agent’s does. See Golden sets.

7. Embed it

Open Embed and create an embed, as in Embedding an agent.

Under Agents, the switch Show which agent is answering controls whether visitors see an agent’s name above its reply. With it on, each member gets a field, Label for and its name. Type what visitors should see instead, such as Billing team. A label can be up to 40 characters, and leaving it blank shows the agent’s own name.

8. The same workflow as a file

A workflow can live in a plugin, next to its agents. Put it under workflows/, in a file named <name>.workflow.yaml:

support-plugin/
  plugin.json
  agents/
    support-desk-triage.agent.md
    support-desk-billing.agent.md
    support-desk-tech.agent.md
  workflows/
    support-desk.workflow.yaml

workflows/support-desk.workflow.yaml holds what the template made:

description: Support desk. Triage routes to billing or technical specialists.
entry: support-desk-triage
agents:
  - support-desk-triage
  - support-desk-billing
  - support-desk-tech
edges:
  - from: support-desk-triage
    to: support-desk-billing
    kind: transfer
    when: invoices, payments, refunds
  - from: support-desk-triage
    to: support-desk-tech
    kind: transfer
    when: errors, outages, how-to
  - from: support-desk-billing
    to: support-desk-triage
    kind: transfer
    when: anything that is not billing
  - from: support-desk-tech
    to: support-desk-triage
    kind: transfer
    when: anything that is not technical

Members are named by their agent name, because they live in the same plugin. To use an agent from another plugin, write plugin/name. Add requires_approval: true to an edge to ask before that handoff, and a limits block to change the run ceilings.

Importing the plugin creates the three agents and the workflow in that plugin. The workflow takes its name from the file, and exporting the plugin writes it back to the same path. See Author a plugin for the rest of the layout.

Over the API

The template is available over the API too. The same call the console makes creates the three agents and the workflow, in the ui plugin:

curl -s "$KOVAC_BASE/api/manage/workflow-templates/router" \
  -H "Authorization: Bearer $KOVAC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "support-desk"}'

The answer carries the workflow’s assistant_id, with a content_hash and changed:

{"assistant_id": "…", "content_hash": "…", "changed": true}

To choose the agents’ names, add agent_names, an object from role (triage, billing, tech) to name. A name already taken is a 409, and nothing is written. Start a run against the returned assistant_id exactly as you would for an agent: see Threads and runs.

Next: Embedding an agent.