API reference

Graph agents

Validate a graph agent's nodes and edges before saving it, and test it with scripted callers.

A graph agent is an agent whose conversation is a set of nodes joined by edges, rather than one prompt. You create and update one through the agent endpoints, with llm_agent.agent_type set to graph_agent and the graph under llm_agent.llm_config. Saving an agent with a broken graph is refused. This page has the extra endpoints: one checks a graph and lists every problem without saving anything, and the workflow tests run scripted callers through a saved graph. The graph agents guide describes node and edge types.

Validate a graph

POST /graph-agent/validate

Returns the errors and warnings for a graph. Errors would block saving the agent; warnings would not.

Auth: API key or session token. Role: member and up.

Send one of these shapes:

Request

curl -X POST https://api.kshyamai.space/graph-agent/validate \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "llm_config": {
      "current_node_id": "welcome",
      "nodes": [
        {
          "id": "welcome",
          "prompt": "Greet the caller and find out what they need.",
          "edges": [{"to_node_id": "ghost", "condition": "Caller wants order status"}]
        },
        {"id": "closing", "prompt": "Thank the caller and say goodbye.", "edges": []}
      ]
    }
  }'

Response 200 OK

{
  "valid": false,
  "errors": [
    {
      "severity": "error",
      "code": "missing_transition_target",
      "message": "Node 'welcome': edge 0 points to unknown node 'ghost'",
      "node_id": "welcome",
      "path": "nodes.0.edges.0"
    }
  ],
  "warnings": [
    {
      "severity": "warning",
      "code": "unreachable_node",
      "message": "Node 'closing' has no transitions pointing to it",
      "node_id": "closing"
    }
  ]
}

A graph with no problems returns {"valid": true, "errors": [], "warnings": []}. valid is true whenever errors is empty, even if there are warnings.

Each issue has severity, code and message, and where they apply node_id and path (a dotted path into the graph, such as nodes.1.edges.0). Codes you may see include:

Expression and edge-parameter problems have further codes of their own. Treat any code you do not recognise by its severity.

Errors

Workflow tests

A workflow test plays a scripted caller through a saved graph agent and checks where the conversation goes. Each caller line is routed the way the dashboard's test chat routes it: the agent's model picks the transition. When the agent has no usable model, a keyword rule decides instead and the run says so (routing is keyword). Nothing is dialled, no tool is called and no audio is involved, so a scenario that passes here can still behave differently on a real call.

Scenarios

GET /graph-agent/{agent_id}/tests/scenarios lists them. POST /graph-agent/{agent_id}/tests/scenarios creates one (201); GET, PUT and DELETE /graph-agent/{agent_id}/tests/scenarios/{scenario_id} read, replace and delete one.

curl -X POST https://api.kshyamai.space/graph-agent/3c90c3cc-0d44-4b50-8822-8dd25736052a/tests/scenarios \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order status, happy path",
    "lines": ["Where is my order ORD-3?", "Thanks, that is all"],
    "expect": {"final_node": "closing", "visits": ["collect_order"], "values": {"order_id": "ORD-3"}}
  }'

Suggest scenarios

POST /graph-agent/{agent_id}/tests/suggest

Proposes one scenario for each path from the start node to a closing node (at most 12). The lines come from the edge conditions, reworded by the agent's model when it is available (phrased is llm, otherwise conditions). Send {"save": true} to store the proposals whose name is not taken, and {"phrase": false} to skip the model. The response has suggestions and saved. Read suggested lines before relying on them.

Start a test run

POST /graph-agent/{agent_id}/tests/runs

Runs in the background and answers 202 with the run. One run per agent at a time (409 otherwise).

Read a test run

GET /graph-agent/{agent_id}/tests/runs lists the last 20 runs without detail. GET /graph-agent/{agent_id}/tests/runs/{run_id} returns one in full; poll it until status is done (or error).