aiconfig-agent-graphs

$27

Core Concepts

What Are Agent Graphs?

An agent graph is a directed graph where:

• 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

Scenario

Example

Multi-step workflows

Triage agent -> Specialist agent -> Summary agent

Routing by intent

Router agent decides which specialist handles the request

Escalation chains

L1 support -> L2 support -> Human handoff

Pipeline processing

Extract -> Transform -> Validate -> Store

Graph Structure

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

                  \--edge--> [Config B]

Each edge has:

• 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

• Design Before Building: Map out nodes and edges on paper/whiteboard first

• One Agent, One Job: Each node should have a clear, focused responsibility

• Root Config Is the Router: The entry point should understand how to dispatch

• Handoff Data Matters: Define what context flows between agents

• Verify the Full Path: Test that routing works end-to-end

Workflow

Step 1: Design the Graph

Before creating anything:

• Identify the agents (AI Configs) needed — each is a graph node

• Map the routing: which agent hands off to which?

• Define handoff data: what context does each edge carry?

• Identify the root config: which agent receives initial input?

• Check existing graphs with list-agent-graphs to avoid duplicates

• Check existing AI Configs with get-ai-config to see what nodes already exist

Step 2: Ensure Nodes Exist

Each node in the graph must be an existing AI Config. If configs don't exist yet:

• Use create-ai-config to create each agent config

• Set up variations with appropriate models and prompts for each agent's role

• Verify each config exists with get-ai-config

Step 3: Create the Graph

Use create-agent-graph with:

• 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

• Use get-agent-graph to confirm the graph was created with the correct structure

• Verify edges connect the right source and target configs

• Check that the root config key matches the intended entry point

• Confirm handoff data is present on edges that need it

Report results:

• Graph created with N nodes and M edges

• Root config set correctly

• All edges verified

Edge Cases

Situation

Action

Config doesn't exist yet

Create it first with create-ai-config before referencing in a graph

Circular routing

Allowed but warn user — ensure there's a termination condition in the agent logic

Single-node graph

Valid but unusual — consider if a graph is actually needed

Updating edges

Use update-agent-graph — provide the complete new edge list

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