Agent graphs

Overview

This topic explains how to create and use agent graphs to orchestrate multi-agent workflows with AI Configs.

Agent graphs let you define and manage multi-agent workflows by modeling how data flows between agent-based AI Configs. An agent graph is a directed graph where each node represents an agent-based AI Config, and each edge defines how output is passed from one agent to another.

Use agent graphs for workflows that require multiple agents. Agent graphs coordinate responsibilities across agents, support reuse across workflows, and define the execution order of agents in complex systems.

At an organizational level, agent graphs support:

• Standardized multi-agent orchestration patterns
• Centralized definition of workflow structure outside application code
• Workflow changes managed through configuration
• A shared representation of how agents interact during execution

Agent graphs build on agent-based AI Configs. To learn more about the underlying concepts, read AI Configs and Agents in AI Configs.

How agent graphs work at runtime

An agent graph is a rooted, directed graph that uses existing agent-based AI Configs as nodes. Edges define how execution can move from one agent to another, and can optionally include handoff data.

An agent graph is defined by:

• A root node, which determines where execution starts
• A set of directed edges, which define how agents are connected

An AI Config can appear in multiple agent graphs. Agent graphs can include cycles, including cases where two agents reference each other. LaunchDarkly does not enforce acyclic graphs and does not impose recursion or termination rules.

Agent graphs are evaluated through the LaunchDarkly AI SDK. The SDK resolves the graph structure and evaluates each agent-based AI Config using standard targeting rules.

LaunchDarkly does not execute agent graphs or call LLMs. The SDK does not manage graph state or traversal decisions. Execution behavior such as model invocation, state handling, edge selection, and termination logic occurs outside of LaunchDarkly.

Agent graphs provide a structured representation of multi-agent workflows that can be evaluated and distributed through LaunchDarkly without embedding the graph topology in application code.

Permissions and constraints

This section describes the permissions required to manage agent graphs and the constraints that apply to agent graph structure.

Permissions and access

To create or manage agent graphs, you must have permissions that allow editing AI Config resources in the project. Agent graphs use the same role-based access control model as AI Configs. Users without permissions to edit AI Config resources can view agent graphs but cannot modify them.

Constraints

Agent graphs must meet the following requirements:

• Each agent graph defines a root agent.
• All referenced agent-based AI Configs must exist.
• All nodes must be reachable from the root agent for the graph to be enabled.
• Each source agent can define at most one edge to a given target agent.

LaunchDarkly enforces these conditions when an agent graph is created, updated, or evaluated through the SDK.

Manage agent graphs in the UI

Use the agent graph builder in the LaunchDarkly UI to create and manage agent graphs.

The agent graph builder shows:

• Agent nodes, each representing an agent-based AI Config in the graph.
• The default variation served in the selected environment, along with the total number of variations for each agent.
• Connections between agents, where you define handoff data passed from one agent to the next.
• The Preview JSON action, which opens a JSON view of the graph structure evaluated by the SDK.

Create an agent graph

To create an agent graph:

1. Navigate to your project.
2. In the left navigation, expand AI, then select Agent graphs.
3. Click Create new graph.
4. Enter a name for the agent graph.
5. (Optional) Click Edit key to update the agent graph key. You use the key to reference the agent graph in your code.
6. (Optional) Enter a description.
7. Click Create.

After you create the agent graph, LaunchDarkly opens the agent graph builder.

Add agent nodes and handoffs

Each node in an agent graph represents an agent-based AI Config.

To add an agent node:

1. In the agent graph builder, click + Add your first agent or Add agent.

2. Use the Select an agent dropdown to select the first agent-based AI Config for your graph. Once selected, the node shows the chosen agent and its available variations.

3. Click the Add a new connected agent button.

   

4. Use the new Select an agent dropdown to select another agent-based AI Config.

   

5. (Optional) Repeat these steps to add additional agents.

6. Click Save.

Configure handoffs

Handoffs are JSON objects attached to edges between nodes. Handoff data is available during graph traversal in the SDK and can be interpreted according to your application logic.

To configure a handoff:

1. Click the + button on the edge that connects two agents.
2. Enter data in JSON format to be passed from the parent node to the child node.
3. Click outside the handoff data dialog to save and close it.

Edit an agent graph

You can update an agent graph to change its structure or metadata.

To edit an agent graph:

1. Open the agent graph.
2. Add or remove agents, set connections between agents, or edit handoff data.
3. Click Save.

When you save an update, LaunchDarkly replaces the existing graph structure with the new version.

Delete an agent graph

Delete an agent graph when it is no longer needed.

To delete an agent graph:

1. Navigate to your project.
2. In the left navigation, expand AI, then select Agent graphs.
3. Click the three-dot overflow menu for the agent graph and select Delete graph.

View the graph structure

The agent graph builder includes a JSON preview that shows the graph structure evaluated by the SDK.

To view the JSON representation, open an agent graph and click Preview JSON in the upper-right corner of the builder.

Use this view to:

• Confirm which agent is configured as the root
• Review how agents are connected through edges
• Verify the handoff data passed between agents

The JSON preview reflects the exact structure delivered to the SDK at runtime and can help validate that the graph behaves as expected before you use it in your application.

Agent graphs in the SDK

Use the LaunchDarkly AI SDK to evaluate and traverse an agent graph at runtime.

Before you begin, make sure your application has a live SDK connection by completing the Quickstart for AI Configs.

Initialize an agent graph

Each agent graph has a unique key that you use to reference it in code. You can find this key in the agent graph details panel in the UI.

Use the graph key to initialize the agent graph with an SDK context:

1
from ldclient import Context
2
from ldai.client import LDAIClient
3
4
ai_client = LDAIClient(client)
5
context = Context.builder("example-user").build()
6
7
agent_graph = ai_client.agent_graph("example-graph-key", context)

After initialization, verify that the graph is enabled:

1
if agent_graph.is_enabled():
2
    # The graph is ready to use
3
else:
4
    # Handle the disabled case

An agent graph may be disabled if:

• One or more nodes are not reachable from the root agent
• One or more agents resolve to a disabled variation
• The graph definition is missing a root or is otherwise invalid

You can enable debug logging in your application to receive warning messages that explain why a graph is disabled.

Traverse an agent graph

After initializing the graph, traverse it to construct or execute your workflow. The SDK provides two traversal methods:

• traverse
• reverse_traverse

Use reverse_traverse when child agents must be created before their parent agents.

The following example uses reverse_traverse with the OpenAI Agents framework to construct a simple multi-agent workflow:

1
from typing import Dict
2
from openai.agents import Agent, Runner
3
4
def handle_traversal(node, ctx: Dict[str, Agent]):
5
    node_config = node.get_config()
6
    node_edges = node.get_edges()
7
8
    handoffs = [ctx[edge.target_config] for edge in node_edges]
9
10
    return Agent(
11
        name=node_config.key,
12
        instructions=node_config.instructions,
13
        handoffs=handoffs,
14
    )
15
16
root = agent_graph.reverse_traverse(fn=handle_traversal)
17
18
result = await Runner.run(
19
    root,
20
    "I'd like some information about your engineering team"
21
)
22
23
print(result.final_output)

Understand traversal behavior

Traversal functions receive two arguments:

• node, an AgentGraphNode representing the current agent
• ctx, a mutable execution context used to store state during traversal

Calling node.get_config() returns the evaluated agent-based AI Config. Calling node.get_edges() returns the outgoing edges from that node, including any associated handoff data.

Each value returned from the traversal function is stored in the execution context, keyed by the agent’s AI Config key.

When using reverse_traverse, traversal processes child agents before parent agents. Agents created earlier in the traversal are available to agents created later.

In a graph where some agents depend on the output of others, traversal begins at the leaf nodes and proceeds toward the root. Each agent is created before any agent that references it.

The following diagram shows a simplified view of agent relationships in the graph. It illustrates parent and child agents and does not represent a serialized format such as JSON.

base-agent
  engineering-info-agent
    engineering-sub-agent
  sales-info-agent

The traversal method returns the root node of the graph. In this example, the root node is an OpenAI Agent instance that can be executed directly using Runner.run.

Next steps

After building an agent graph, you can monitor agent performance using Monitor AI Configs and experiment with workflow changes using Run experiments with AI Configs.