What you will achieve in this quickstart guide:

Design an AI Agent in the Workbench, including: The AI Agent state machine, tools (API function calling), and system instructions.
Use the visual tester to test the behavior and tool calling.
Chat to the AI Agent from an external source (fully hosted Chainlit).
Apply the design and configuration to an AI Agent in code.

Using the AI Agent Workbench

Go to https://app.xpander.ai and sign in with your credentials.

Open the AI Agent Workbench.

In the left navigation menu, go to AI Agents, then click the New AI Agent button.

Use the Planner to automatically design your AI Agent via a single prompt

For this quickstart, use the following prompt: “Build an AI Agent that is able to get the top stories and their item details from Hacker News”

This action will automatically: design the AI Agent state machine, add the relevant tools to the AI Agent, and write the AI Agent system level instructions.

It could take up to a minute for the Planner agent to complete the AI Agent design and configuration.

Your result should be similar to:

Manually add another operation (tool) to the AI Agent: Hover over the bottom operation in the graph -> click the + button. Then, go to xpander functions -> send email -> click Done.

Save your AI Agent configuration by clicking the Deploy button.

Use the Agent Tester (left pane) to prompt your AI Agent and view its behavior live

Insert a test prompt such as: Get the top 3 news items from hackernews and send them over to <your email>

You will see the decision making process in the graph indicated by the moving Purple dot, as well as the request/response process and payloads in the left pane.

If email sending doesn’t work despite having added the Email sending operation to the AI Agent’s tools, go to the AI Agent’s settings, and in the Instructions settings, add the following:
“if asked to send an email, use the send_email operation”

You successfully used the AI Agent Workbench to build and test your agent!
Continue the tutorial to trigger and use your AI Agent from external sources.

Chat to you AI Agent from a fully-managed Chainlit instance.

Open Chainlit

Click the Chat trigger node at the top of the graph, and click the URL for your hosted Chainlit instance.

You can continue prompting your AI Agent from this external source.

You successfully chatted to your AI Agent from an external source.

xpander-sdk in your AI Agent code

The magic of the xpander.ai Agent Platform starts here

The state machine, tools, instructions and other configurations will now be enforced by the xpander SDK in your own AI Agent code.

Set up Python virtual environment, install packages, and add environment variables.

To start using the xpander SDK in your AI Agent code, let’s set up a virtual environment.

Create a project and virtual environment

Create a new project directory and set up a Python virtual environment:

mkdir my_project
cd my_project
python -m venv .venv

Activate the virtual environment

Do this every time you start a new terminal session:

# On macOS/Linux
source .venv/bin/activate

# On Windows
.venv\Scripts\activate

Install the xpander SDK

Install the following packages:

pip install xpander-sdk
pip install openai
pip install dotenv

Set up environment variables in .env file

Grab these two API keys and the AI Agent ID and place them in your .env file:

OpenAI Key from https://platform.openai.com
Your AI Agent ID — by clicking the SDK trigger node at the top of the graph in the AI Agent Workbench
Your default API key From the same screen, also check the box next to the default API key and copy the API key

echo "XPANDER_API_KEY=<your_key>" >> .env
echo "OPENAI_API_KEY=<your_key>" >> .env  
echo "XPANDER_AGENT_ID=<your_agent_id>" >> .env  

Make sure the three parameters are correctly added to the .env file.

AI Agent code setup

Load packages and environment variables, and initialize the clients

Create your agent.py file, and let’s start building it step by step. The following code will load the packages and keys, and initialize the clients:

from xpander_sdk import XpanderClient
from openai import OpenAI
from dotenv import load_dotenv
from os import environ

load_dotenv()
OPENAI_API_KEY = environ["OPENAI_API_KEY"]
XPANDER_API_KEY = environ["XPANDER_API_KEY"]
XPANDER_AGENT_ID = environ["XPANDER_AGENT_ID"]

# Initialize clients
xpander_client = XpanderClient(api_key=XPANDER_API_KEY)
openai_client = OpenAI(api_key=OPENAI_API_KEY)

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

Create a task and initialize state

This code creates an immutable task for the agent. Tasks are immutable by design, allowing you to track state changes throughout execution:

# Create a task for the agent
task1 = agent.add_task("""
Summarize the last 24 hours top hackernews posts
""")

{
  "content": "Summarize the last 24 hours top hackernews",
  "role": "user"
}

The input message follows a standard chat format with a role and content. This is automatically generated from your task description and becomes available as agent.execution.input_message.

{
  "general": "You are a Hacker News summarization agent. Retrieve top stories, fetch details, and generate concise summaries using Perplexity AI. Format and present the summarized news. End with xpfinish-agent-execution-finished.\n        IMPORTANT: when making a sub-task (with input_task), make sure to append all related \n        information relevant for the sub-task. For instance, if the sub-task is about sending \n        an email with tags, ensure the tags and any required data are included in the input_task.\n        \n        - Execute tools as needed to complete tasks.  \n        - If a tool fails 3 times, execution stalls, or no tool is called for an extended period, stop immediately and report the issue along with any relevant results or errors.\n        ",
  "goal": "Retrieve top stories from Hacker News, fetch detailed content for each story, generate concise summaries, and format the results for presentation. Finalize with xpfinish-agent-execution-finished, returning the summarized news articles in the 'results'.",
  "role": "Expert in retrieving and processing Hacker News stories, responsible for fetching top stories and their details"
}

The instructions object provides comprehensive guidance to the agent:

general: Overall instructions, constraints, and operational guidelines
goal: Specific objective the agent needs to accomplish
role: Identity and responsibilities the agent should assume

These instructions are used to initialize the agent’s memory and guide its decision-making throughout execution.

Add the AI Agent loop

Add the following code to your agent.py file.

# Run the agent until completion
while not agent.is_finished():
    # Get LLM response with available tools
    response = openai_client.chat.completions.create(
        model="gpt-4o",
        messages=agent.messages,
        tools=agent.get_tools(),
        tool_choice=agent.tool_choice,
        temperature=0.0
    )
            
    # Process LLM response
    agent.add_messages(response.model_dump())
    
    # Extract and run tool calls
    tool_calls = XpanderClient.extract_tool_calls(llm_response=response.model_dump())
    agent.run_tools(tool_calls=tool_calls)

The is_finished() API checks the execution state of the agent, enabling you to control the execution loop programmatically. This approach gives you full visibility into the agent’s execution process.

Retrieve execution results

Once execution is complete, this code retrieves the immutable execution result:

# Get final results
execution_result = agent.retrieve_execution_result()
print("Status:", execution_result.status)
print("Result:", execution_result.result)

The execution result is immutable, meaning it can be safely retrieved at any point during or after execution without affecting the agent’s state. This design allows you to monitor progress or record results while the agent continues processing.

Run the agent.py file in your IDE or via the command line by running python agent.py

Example output:

# execution_result.status
Status: ExecutionStatus.COMPLETED

# execution_result.result
Result: Here are the top Hacker News stories from the last 24 hours:

1. Show HN: Nash, I made a standalone note with a single HTML file
   - Author: yevgenyhong
   - Score: 204
   - Comments: 47
   - Summary: A user has created a standalone note application using a single HTML file. This tool does not require any membership or software installation and can be used both online and offline. It is suitable for sharing content through messengers like Telegram and can also be used for hosting and blogging.
   - Link: [Read more](https://keepworking.github.io/nash/)

2. Finding Signal in the Noise: Machine Learning and the Markets (Jane Street)
   - Author: lewiscarson
   - Score: 76
   - Comments: 32
   - Summary: An article discussing the application of machine learning in financial markets, focusing on how to find meaningful signals amidst the noise.
   - Link: [Read more](https://signalsandthreads.com/finding-signal-in-the-noise/)

3. Sign in as anyone: Bypassing SAML SSO authentication with parser differentials
   - Author: campuscodi
   - Score: 200
   - Comments: 73
   - Summary: A security blog post detailing a method to bypass SAML SSO authentication using parser differentials, highlighting a significant security vulnerability.
   - Link: [Read more](https://github.blog/security/sign-in-as-anyone-bypassing-saml-sso-authentication-with-parser-differentials/)

These stories highlight a range of topics from innovative tech projects to significant security insights.

You successfully used the xpander SDK to run an AI Agent using the configuration you designed in the AI Agent Workbench!

Get Started

AI Agent Workbench

AI State Management

Human Interfaces

Quickstart - Workbench

What you will achieve in this quickstart guide:

Using the AI Agent Workbench

Chat to you AI Agent from a fully-managed Chainlit instance.

xpander-sdk in your AI Agent code

The magic of the xpander.ai Agent Platform starts here

Set up Python virtual environment, install packages, and add environment variables.

AI Agent code setup

Troubleshooting / FAQ

Get Started

AI Agent Workbench

AI State Management

Human Interfaces

​What you will achieve in this quickstart guide:

​Using the AI Agent Workbench

​Chat to you AI Agent from a fully-managed Chainlit instance.

​xpander-sdk in your AI Agent code

The magic of the xpander.ai Agent Platform starts here

​Set up Python virtual environment, install packages, and add environment variables.

​AI Agent code setup

​Troubleshooting / FAQ

What you will achieve in this quickstart guide:

Using the AI Agent Workbench

Chat to you AI Agent from a fully-managed Chainlit instance.

xpander-sdk in your AI Agent code

Set up Python virtual environment, install packages, and add environment variables.

AI Agent code setup

Troubleshooting / FAQ