Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.coval.ai/llms.txt

Use this file to discover all available pages before exploring further.

A workflow is a visual map of your agent’s conversation logic — a directed graph that shows the steps your agent can take, the decisions it makes, and how one state transitions to the next. Workflows live inside an agent configuration. They don’t change how your agent behaves at runtime — instead, they give Coval (and you) a structured model of the intended conversation flow that can power simulation guidance, test coverage analysis, and documentation.

​
Why Use a Workflow

Without a workflow, simulations run without a reference model of the intended conversation structure. With one, Coval can:
  • Guide simulations to follow expected paths and decision points
  • Identify gaps in test coverage (steps that aren’t exercised)
  • Provide a visual reference for how your agent should handle conversations
  • Catch deviations from expected behavior during evaluation
Common use cases:
  • Document the intended flow for complex multi-step interactions
  • Ensure test cases cover all critical decision branches
  • Onboard new team members with a visual conversation map
  • Validate that simulations are exercising the full conversation tree

​
What a Workflow Looks Like

A workflow is made up of:
  • Nodes — individual steps or states in the conversation (e.g., Greet Caller, Verify Identity, Handle Cancellation Request, Escalate to Human)
  • Edges — directed connections between nodes that represent valid transitions, optionally labeled with conditions (e.g., “Confirmed”, “Declined”, “Timeout”)
Together, nodes and edges form a DAG (directed acyclic graph) representing your agent’s expected conversation paths. Loops are flagged with a warning — each step should lead forward.

​
Adding a Workflow to an Agent

Navigate to your agent’s configuration page and open the Workflow tab.

​
Generate from Agent Description

If your agent has a system prompt configured, click Generate to automatically create a workflow from it. Coval uses your agent’s name and system prompt to infer the conversation steps and decision points. If your agent doesn’t have a system prompt yet, you’ll be prompted to describe the workflow manually before generating. You can also provide additional requirements in the generation dialog — for example:
“Include an escalation path when the caller asks for a supervisor”

​
Edit an Existing Workflow

Once a workflow exists, you can refine it using two tabs:
  • Edit tab — describe a change in plain language and click Apply. Use the quick-action buttons to add decision points, process steps, error paths, or edge labels.
  • JSON tab — edit the workflow graph directly as JSON for precise control. Coval validates the structure on save.
Use Undo to revert to the previous version at any point.

​
Expand the Canvas

Click the expand icon to open the workflow in a full-screen modal for a better view of complex graphs.

​
Workflow Data Format

A workflow is stored as JSON with two top-level arrays: 
{
  "nodes": [
    {
      "id": "greet",
      "data": { "label": "Greet Caller", "description": "Agent introduces itself" }
    },
    {
      "id": "verify",
      "data": { "label": "Verify Identity", "description": "Confirm caller account" }
    },
    {
      "id": "resolve",
      "data": { "label": "Resolve Issue", "description": "Address the caller's request" }
    },
    {
      "id": "close",
      "data": { "label": "Close Call", "description": "Summarize and end the conversation" }
    }
  ],
  "edges": [
    { "id": "e1", "source": "greet", "target": "verify" },
    { "id": "e2", "source": "verify", "target": "resolve", "label": "Verified" },
    { "id": "e3", "source": "verify", "target": "close", "label": "Unverified" },
    { "id": "e4", "source": "resolve", "target": "close" }
  ]
}
FieldDescription
nodes[].idUnique identifier for the step
nodes[].data.labelDisplay name shown on the canvas
nodes[].data.descriptionOptional description of what happens at this step
edges[].sourceID of the originating node
edges[].targetID of the destination node
edges[].labelOptional condition label for the transition

​
Workflow Validation

Coval validates workflows on save and flags common issues:
  • Cycles / loops — a node that transitions back to an earlier step. Each step should lead forward in the conversation.
  • Missing nodes — an edge references a node ID that doesn’t exist.
  • Disconnected nodes — nodes with no incoming or outgoing edges.
Warnings appear as banners on the canvas and in the JSON editor. You can still save a workflow with warnings, but review them before using the workflow to guide simulations.