AI Config Agent Graphs

Prerequisites

• create-agent-graph

  -- create a new graph with nodes and edges

• get-agent-graph

  -- inspect a graph's structure and edges

• list-agent-graphs

  -- browse existing graphs in the project

• update-agent-graph

  -- modify edges, root config, or description

• delete-agent-graph

  -- permanently remove a graph

• get-ai-config

  -- inspect individual AI Configs that serve as nodes

• create-ai-config

  -- create new AI Configs to use as graph nodes

Core Concepts

What Are Agent Graphs?

• Nodes are AI Configs (each config is an agent with its own model, prompt, and tools)
• Edges define routing between configs (source -> target)
• Handoff data on edges controls how context is passed between agents
• Root config is the entry point — the first agent that receives user input

When to Use Agent Graphs

Graph Structure

[Root Config] --edge--> [Config A] --edge--> [Config C]
                  \--edge--> [Config B]

• key

  -- unique identifier for the edge

• sourceConfig

  -- the AI Config key that routes FROM

• targetConfig

  -- the AI Config key that routes TO

• handoff

  (optional) -- data/instructions passed during the transition

Core Principles

1. Design Before Building: Map out nodes and edges on paper/whiteboard first
2. One Agent, One Job: Each node should have a clear, focused responsibility
3. Root Config Is the Router: The entry point should understand how to dispatch
4. Handoff Data Matters: Define what context flows between agents
5. Verify the Full Path: Test that routing works end-to-end

Workflow

Step 1: Design the Graph

1. Identify the agents (AI Configs) needed — each is a graph node
2. Map the routing: which agent hands off to which?
3. Define handoff data: what context does each edge carry?
4. Identify the root config: which agent receives initial input?
5. Check existing graphs with

   list-agent-graphs

   to avoid duplicates
6. Check existing AI Configs with

   get-ai-config

   to see what nodes already exist

Step 2: Ensure Nodes Exist

1. Use

   create-ai-config

   to create each agent config
2. Set up variations with appropriate models and prompts for each agent's role
3. Verify each config exists with

   get-ai-config

Step 3: Create the Graph

create-agent-graph

• projectKey

  -- the project containing the AI Configs

• key

  -- unique identifier for the graph

• name

  -- human-readable display name

• description

  (optional) -- explain the graph's purpose

• rootConfigKey

  -- the entry-point AI Config key

• edges

  -- array of connections between configs

{
  "projectKey": "my-project",
  "key": "support-triage-graph",
  "name": "Customer Support Triage",
  "description": "Routes customer queries to the appropriate specialist agent",
  "rootConfigKey": "triage-agent",
  "edges": [
    {
      "key": "triage-to-billing",
      "sourceConfig": "triage-agent",
      "targetConfig": "billing-specialist",
      "handoff": {"category": "billing", "priority": "normal"}
    },
    {
      "key": "triage-to-technical",
      "sourceConfig": "triage-agent",
      "targetConfig": "technical-specialist",
      "handoff": {"category": "technical", "priority": "normal"}
    }
  ]
}

Step 4: Verify

1. Use

   get-agent-graph

   to confirm the graph was created with the correct structure
2. Verify edges connect the right source and target configs
3. Check that the root config key matches the intended entry point
4. Confirm handoff data is present on edges that need it

• Graph created with N nodes and M edges
• Root config set correctly
• All edges verified

Edge Cases

create-ai-config

update-agent-graph

What NOT to Do

• Don't create a graph before the AI Config nodes exist
• Don't forget handoff data when agents need context from predecessors
• Don't create overly complex graphs — start simple and add nodes as needed
• Don't delete a graph without understanding if it's actively used in agent workflows