Agent Graph System (AGS)

What is the Agent Graph System?

The Agent Graph System (AGS) lets you define hierarchical constraints for your AI agents, controlling which operations they can use and in what order.

While agents can see all available operations, they must follow the workflow you define. This balances autonomy with predictable behavior.

When to use AGS

Core Concepts

An agent graph consists of three simple components:

Nodes - Individual operations (tools) your agent can use
Connections - Define which operations must happen before others
Hierarchical levels - Group operations by their position in the workflow

Example Agent Workflow that requires AGS

Let’s explore a practical example of an agent that needs to follow a specific workflow:

Users might ask the agent to research a specific topic, and the agent should follow this sequence:

First, search for general information about the topic
Once basic information is found, extract specific details
Finally, analyze or summarize the collected information

Without AGS constraints, the agent might skip steps or perform them in an incorrect order, leading to incomplete or inaccurate results. With AGS we can design a graph that enforces the correct sequence of operations without limiting the agent’s ability to make decisions.

This example shows how AGS enforces the correct sequence of operations, ensuring data is gathered methodically and reliably.

Key Benefits

Implementation Methods

You can create agent graphs using either the visual UI or programmatically with the SDK. Both approaches offer the same functionality, with the visual builder being more intuitive for non-developers and the SDK providing more flexibility for programmers.

The xpander.ai UI provides a drag-and-drop interface for creating agent graphs:

Access the Graph Builder

Navigate to your agent in the xpander.ai dashboard and select the “Graph” tab

Add Operations

Drag operations from the sidebar into your graph workspace

Create Connections

Draw lines between operations to establish dependencies

Test Your Graph

Use the interface options to test your agent with different invocation methods

Deploy

Save changes to deploy your updated graph

The visual builder gives you all the power of AGS without writing code, making it accessible to both developers and non-developers.

Advanced UI Techniques

The xpander.ai UI provides a drag-and-drop interface for creating agent graphs:

Access the Graph Builder

Navigate to your agent in the xpander.ai dashboard and select the “Graph” tab

Add Operations

Drag operations from the sidebar into your graph workspace

Create Connections

Draw lines between operations to establish dependencies

Test Your Graph

Use the interface options to test your agent with different invocation methods

Deploy

Save changes to deploy your updated graph

The visual builder gives you all the power of AGS without writing code, making it accessible to both developers and non-developers.

Advanced UI Techniques

The SDK offers a programmatic approach that provides the same capabilities as the visual builder, but with the flexibility to create and modify graphs through code:

Add Operations to Your Agent

# Attach operations to your agent
agent.attach_operations(operations=[operation1, operation2])

Create Graph Nodes

# Create graph nodes from operations
node1 = agent.graph.add_node(
    GraphItem(
        agent=agent,
        item_id=operation1.id_to_use_on_graph,
        name=operation1.name
    )
)

node2 = agent.graph.add_node(
    GraphItem(
        agent=agent,
        item_id=operation2.id_to_use_on_graph,
        name=operation2.name
    )
)

Define Hierarchical Constraints

# Create a hierarchical relationship
# The agent must use node1 before it can use node2
node1.connect([node2])

Deploy Your Agent

# Deploy the agent with the defined graph structure
agent.sync()

Creating a Graph Example

Here’s an example of creating a workflow graph with the SDK:

from xpander_sdk import XpanderClient, GraphItem
import os
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Initialize client
xpander_client = XpanderClient(api_key=os.environ['XPANDER_API_KEY'])

# Get the agent
agent = xpander_client.agents.get(agent_id=os.environ.get('XPANDER_AGENT_ID'))

# Retrieve operations from an interface
available_interfaces = agent.retrieve_agentic_interfaces()
search_interface = next((interface for interface in available_interfaces 
                        if 'search' in interface.name.lower()), None)

if search_interface:
    search_operations = agent.retrieve_agentic_operations(agentic_interface=search_interface)
    
    # Attach needed operations to the agent
    agent.attach_operations(operations=search_operations)
    agent.sync()  # Apply the operation attachment
    
    # Create graph nodes
    nodes = []
    for operation in search_operations:
        node = agent.graph.add_node(
            GraphItem(
                agent=agent,
                item_id=operation.id_to_use_on_graph,
                name=operation.name
            )
        )
        nodes.append(node)
    
    # Create relationships between nodes
    if len(nodes) >= 2:
        # Create a simple linear workflow
        nodes[0].connect([nodes[1]])
        
        # Apply the changes
        agent.sync()

Real-world Example: Meeting Recorder Agent

This example shows how to initialize a basic agent for a meeting recording application:

from xpander_sdk import XpanderClient, LLMProvider, Tokens, LLMTokens
from openai import OpenAI
import datetime
import time

class MeetingAgent:
    def __init__(self, openai_api_key, xpander_api_key, agent_id):
        self.agent_id = agent_id
        self.xpander_client = XpanderClient(api_key=xpander_api_key)
        self.openai_client = OpenAI(api_key=openai_api_key)
        self.agent = self.xpander_client.agents.get(agent_id=self.agent_id)
    
    def run(self, prompt=None, thread_id=None):
        """Run the agent with the given prompt"""
        # Create task with thread management
        self.agent.add_task(
            input=prompt or "Check the status of all recorded meetings.", 
            thread_id=thread_id if thread_id else None
        )
        
        # Run the agent execution loop
        while not self.agent.is_finished():
            response = self.openai_client.chat.completions.create(
                model="gpt-4.1",
                messages=self.agent.messages,
                tool_choice=self.agent.tool_choice,
                temperature=0.0
            )
            
            self.agent.add_messages(response.model_dump())
            
            tool_calls = self.agent.extract_tool_calls(
                llm_response=response.model_dump(),
            )
            
            if tool_calls:
                self.agent.run_tools(tool_calls=tool_calls)
                
        # Process results
        result = self.agent.retrieve_execution_result()
        return result.result, result.memory_thread_id

Troubleshooting & Best Practices

Best Practices

Common Issues

Problem	Solution
Agent ignores constraints	Ensure you’ve called `agent.sync()` after defining relationships
Operations unavailable	Check that all operations are properly attached to the agent
Circular dependencies	Look for cycles in your graph that might prevent execution
Unintended restrictions	Verify constraints don’t block valid execution paths
Changes not applied	Verify that `agent.sync()` is called after making graph modifications
Missing prerequisites	Ensure all node requirements are properly connected

Next Steps

Now that you understand the Agent Graph System, you might want to explore:

Introduction

Quickstart

Backend for Agents

AI Agent Workbench

AI State Management

Human Interfaces

Agent Graph System (AGS)

What is the Agent Graph System?

Core Concepts

Example Agent Workflow that requires AGS

Implementation Methods

Multiple Prerequisites

Creating Multiple Paths

Example: Agent Structure in UI

Multiple Prerequisites

Creating Multiple Paths

Example: Agent Structure in UI

Creating a Graph Example

Real-world Example: Meeting Recorder Agent

Troubleshooting & Best Practices

Next Steps

Introduction

Quickstart

Backend for Agents

AI Agent Workbench

AI State Management

Human Interfaces

​What is the Agent Graph System?

​Core Concepts

​Example Agent Workflow that requires AGS

​Implementation Methods

​Creating a Graph Example

​Real-world Example: Meeting Recorder Agent

​Troubleshooting & Best Practices

​Next Steps

What is the Agent Graph System?

Core Concepts

Example Agent Workflow that requires AGS

Implementation Methods

Creating a Graph Example

Real-world Example: Meeting Recorder Agent

Troubleshooting & Best Practices

Next Steps