​
Agent State Basics

xpander.ai’s agent system uses a sophisticated state management approach that integrates various components. This guide explains the fundamental concepts of agent state and how to get started.

​
Core State Components

xpander.ai’s agent state consists of several key components:

  1. Agent Configuration: Core properties, instructions, and settings
  2. Agent Graph System (AGS): Hierarchical constraints defining which operations can be used and in what order
  3. Execution Context: Current execution status and parameters
  4. Memory: Message history and contextual information
  5. Tool State: Current state of attached tools and operations

Understanding these components is essential for building effective agents.

​
Initializing Agent State

Start by connecting to an existing agent to access its state:

from xpander_sdk import XpanderClient
import os

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

# Connect to an existing agent
agent_id = os.environ.get('XPANDER_AGENT_ID', 'your-agent-id')
agent = xpander_client.agents.get(agent_id)
print(f'Agent: {agent.id}')

​
Basic Agent Execution

Here’s a simple example of running an agent:

from xpander_sdk import XpanderClient, LLMProvider
from openai import OpenAI
import os

# Initialize clients
xpander_client = XpanderClient(api_key=os.environ.get("XPANDER_API_KEY"))
openai_client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

# Get your agent
agent = xpander_client.agents.get(agent_id=os.environ.get("XPANDER_AGENT_ID"))

# Add a task
agent.add_task(input="Tell me about machine learning")

# Run the agent until the task is complete
while not agent.is_finished():
    # Get LLM response
    response = openai_client.chat.completions.create(
        model="gpt-4o",
        messages=agent.messages,
        tools=agent.get_tools(llm_provider=LLMProvider.OPEN_AI),
        tool_choice=agent.tool_choice,
        temperature=0.0
    )
    
    # Add LLM response to memory
    agent.add_messages(response.model_dump())
    
    # Extract and execute tool calls
    tool_calls = XpanderClient.extract_tool_calls(
        llm_response=response.model_dump(),
        llm_provider=LLMProvider.OPEN_AI
    )
    
    if tool_calls:
        agent.run_tools(tool_calls=tool_calls)

# Get the final result
result = agent.retrieve_execution_result()
print(f"Result: {result.result}")

​
Updating Agent Configuration

You can update an agent’s configuration using the update() and sync() methods:

# Update agent instructions
# The instructions property is a dictionary with 'role', 'general', and 'goal' keys
agent.instructions = {
    "role": "You are an AI assistant specialized in machine learning",
    "general": "Provide clear and concise explanations about machine learning concepts",
    "goal": "Help users understand machine learning terms and applications"
}

# Apply the changes
agent.update()  # Updates the agent configuration
agent.sync()    # Deploys the agent with all changes

# Verify changes
print(f"Agent instructions: {agent.instructions}")

​
Next Steps

To dive deeper into specific aspects of agent state management:

Thread & Memory Management

Learn about managing stateful conversations and memory

Debugging State

Inspect and debug agent state

Agent Graph System

Learn about creating hierarchical constraints for your agents

Activity & Monitoring

Monitor agent activity and execution