Module 1: Build Your First Coding Agent

Module Summary

Goal: Create and deploy your first AI developer agent
Estimated Time: 20-30 minutes
Prerequisites: Open AI credentials, Python 3.12+, Cursor IDE

🚀 In this module, you’ll set up a complete AI coding assistant powered by xpander.ai and Open AI GPT 4.1. You’ll create a local development environment, configure your agent with custom instructions, test it with repository management tasks, and connect it to the cloud for remote access. By the end, you’ll have a powerful AI developer agent that can clone repositories, read and write code, and help automate your development workflow!

🔧 Setup Your Development Environment

Let’s start by creating a workspace directory and cloning the base agent repository:

mkdir workshop 
cd workshop/
git clone https://github.com/xpander-ai/coding-agent.git
mv coding-agent dev-agent-1
cd dev-agent-1

Open the project in Cursor IDE:

cursor .

🛠️ Configure Your Local Environment

This workshop requires Python 3.12.7 or newer. To check your current version, run:

python3 --version

If you need to upgrade, use the following methods:

macOS: brew install python3 && python3 --version
Windows (WSL/Git Bash): Download the latest installer from python.org

Inside the Cursor terminal, set up your Python environment and install dependencies:

python3 -m venv .venv && \
source .venv/bin/activate && \
pip install -r requirements.txt --no-cache-dir
npm install -g xpander-cli

If you encounter issues with Node.js dependencies when installing xpander-cli, use the following commands to resolve them:

# Make sure to use Node 22+
nvm install 22
nvm use 22
nvm alias default 22

🔑 Authenticate to xpander.ai

xpander login

This command will open the xpander.ai platform and ask you to login or register. Once confirmed, you will be redirected back to the terminal, which will display something similar to:

❯ xpander login
⠏ Authorizing
Hi David, Welcome to xpander!
Your organization id: 8d185373*********
Your personal API Key is: IhPLk2C*******

I've created default profile configured in ~/.xpander

Create a .env file in the root directory with the following credentials:

.env file

XPANDER_API_KEY=your_xpander_api_key ## From the output above
AWS_ACCESS_KEY_ID=your_aws_access_key
AWS_SECRET_ACCESS_KEY=your_aws_secret_key
AWS_SESSION_TOKEN=your_aws_session_token  # only needed if using temporary credentials
AWS_REGION="us-east-2"
BEDROCK_MODEL_ID="us.anthropic.claude-3-7-sonnet-20250219-v1:0"

GIT_TOKEN=your-git-token                  # Generate at https://github.com/settings/tokens/new
GIT_USERNAME=your-git-username

MAXIMUM_STEPS_SOFT_LIMIT=40
MAXIMUM_STEPS_HARD_LIMIT=60

OPENAI_MODEL_ID=gpt-4.1
OPENAI_API_KEY=your-open-ai-keys

If you are running this workshop in person, ask the xpander.ai team to provide you access.

🤖 Create Your Agent

Now let’s use the xpander CLI to create a new agent:

xpander agent new

Complete the agent creation wizard (Answer yes to load the agent locally):

✨ Agent Creation Wizard ✨
──────────────────────────────────────────────────
Create a powerful AI agent for your organization
──────────────────────────────────────────────────

? What name would you like for your agent? dev-agent-1
⠋ Creating agent "dev-agent-1"...Creating agent in organization: 8d185373-8b24-47a7-8607-3e9036b968bb...
✔ Agent "dev-agent-1" created successfully!

🚀 Your Agent is Ready!
──────────────────────────────────────────────────
Name:     dev-agent-1
ID:       4fe1163d-bb00-4837-9e25-6f82aed8038c
Icon:     🚀
Model:    openai/gpt-4.1
──────────────────────────────────────────────────

✅ Agent creation complete!

? Do you want to load this agent into your current workdir? Yes


✨ Initializing agent
────────────────────────────────────────────────────────────
ℹ Agent dev-agent-1 retrieved successfully
? The current directory is not empty. Proceeding will override 'requirements.txt' and add or update xpander-related files (xpander_config.json, 
agent_instructions.json, etc). Yes
✔ Agent initialized successfully

🚀 Run Your Agent Locally

Now it’s time to run your agent and ask it to introduce itself and its architecture!

python main.py

Pay attention that the agent is limited to running inside the sandbox folder. To see files generated by the agent, navigate to the sandboxes folder and look for the thread ID from the terminal output.

💬 Example Agent Interaction

Here’s what you might see in the terminal as your agent runs:

❯ python main.py
Sandbox base directory: /Users/david/Developer/workshop/dev-agent-1/sandboxes
b'{"stdout":"bG9hZGluZyBhZ2VudCA3Mzc2MmYyNi04MDMzLTRkODEtYWVlOC02NjViOWI0NGQ5Y2YK"}\n'
2025-05-07 22:12:53.344 | INFO     | coding_agent:chat:82 - 🧠 Adding task to a new thread
2025-05-07 22:12:54.254 | INFO     | coding_agent:_agent_loop:116 - 🪄 Starting Agent Loop
2025-05-07 22:12:56.546 | INFO     | coding_agent:_agent_loop:127 - --------------------------------------------------------------------------------
2025-05-07 22:12:56.546 | INFO     | coding_agent:_agent_loop:128 - 🔍 Step 1
2025-05-07 22:12:58.438 | INFO     | llm_providers.openai:invoke_model:107 - 🔄 Model response received in 1.51 s
2025-05-07 22:13:00.507 | INFO     | coding_agent:_agent_loop:177 - ✅ xpfinish-agent-execution-finished
2025-05-07 22:13:00.508 | INFO     | coding_agent:_agent_loop:179 - 🔢 Step 1 tokens used: 1527 (output: 67, input: 1460)
2025-05-07 22:13:01.677 | INFO     | coding_agent:_agent_loop:185 - ✨ Execution duration: 7.42 s
2025-05-07 22:13:01.679 | INFO     | coding_agent:_agent_loop:188 - 🔢 Total tokens used: 1527 (output: 67, input: 1460)
2025-05-07 22:13:02.051 | INFO     | coding_agent:chat:86 - --------------------------------------------------------------------------------
2025-05-07 22:13:02.051 | INFO     | coding_agent:chat:87 - 🤖 Agent response: Hello! How can I assist you with your coding or project needs today? If you have a specific task or question, please let me know!

Ask the agent to introduce itself and explain how it works

In the same console, paste the following prompt

Prompt

You are an autonomous Coding Agent built with the xpander-ai/coding-agent source-code. Clone the repo, then introduce yourself as a self-driven software engineer capable of generating, executing, and managing code through structured function-calling and a smart agent loop. Briefly explain your modular architecture, support for schema-driven actions, multi-step planning, context-aware memory, and connector-based system integration. Conclude with a clear summary of how your agent loop enables reliable, auditable, and deterministic automation—then write it all to a file named coding-agent-intro.md for the developer. Don't commit anything yet.

After completing various tasks (like creating a markdown introduction file), you’ll see the final agent response:

2025-05-07 22:17:32.228 | INFO     | coding_agent:chat:79 - 🧠 Adding task to existing thread: aeea28ff-a49b-4a20-b5b3-5c49fbbeef29
2025-05-07 22:17:34.202 | INFO     | coding_agent:_agent_loop:116 - 🪄 Starting Agent Loop
2025-05-07 22:17:35.273 | INFO     | coding_agent:_agent_loop:127 - --------------------------------------------------------------------------------
2025-05-07 22:17:35.273 | INFO     | coding_agent:_agent_loop:128 - 🔍 Step 1
2025-05-07 22:17:36.941 | INFO     | llm_providers.openai:invoke_model:107 - 🔄 Model response received in 1.25 s
2025-05-07 22:17:39.798 | INFO     | coding_agent:_execute_local_tool:229 - 🔦 LLM Requesting local tool: git_clone with generated payload: {'repo_url': 'https://github.com/xpander-ai/coding-agent'}
2025-05-07 22:17:41.273 | INFO     | coding_agent:_execute_local_tool:279 - 🔧 Tool git_clone completed in 1.48 s
2025-05-07 22:17:41.667 | INFO     | coding_agent:_agent_loop:177 - ✅ git_clone
2025-05-07 22:17:41.669 | INFO     | coding_agent:_agent_loop:179 - 🔢 Step 1 tokens used: 1614 (output: 29, input: 1585)
2025-05-07 22:17:42.475 | INFO     | coding_agent:_agent_loop:127 - --------------------------------------------------------------------------------
2025-05-07 22:17:42.475 | INFO     | coding_agent:_agent_loop:128 - 🔍 Step 2
2025-05-07 22:17:49.063 | INFO     | llm_providers.openai:invoke_model:107 - 🔄 Model response received in 6.17 s
2025-05-07 22:17:51.932 | INFO     | coding_agent:_execute_local_tool:229 - 🔦 LLM Requesting local tool: new_file with generated payload: {'file_path': 'coding-agent-intro.md', 'content': '# Coding Agent Introduction\n\nHello! I am an autonomous Coding Agent, built with the [xpander-ai/coding-agent](https://github.com/xpander-ai/coding-agent) source code. As a self-driven software engineer, I am capable of generating, executing, and managing code through structured function-calling and a smart agent loop.\n\n## Modular Architecture\nMy architecture is modular, allowing for flexible extension and integration. Each component is designed to handle specific responsibilities, such as code generation, file management, version control, and external system interaction. This modularity ensures maintainability and scalability.\n\n## Schema-Driven Actions\nI support schema-driven actions, which means all my operations are defined and validated against explicit schemas. This guarantees that every action I perform is predictable, type-safe, and easy to audit.\n\n## Multi-Step Planning\nI am capable of multi-step planning, breaking down complex tasks into smaller, manageable subtasks. This enables me to tackle sophisticated development workflows while ensuring each step is executed reliably and in the correct order.\n\n## Context-Aware Memory\nMy context-aware memory allows me to retain and utilize relevant information throughout a session. I can reference previous actions, user instructions, and project state to make informed decisions and maintain continuity across tasks.\n\n## Connector-Based System Integration\nI integrate with external systems through a connector-based approach. This enables seamless interaction with tools such as Git, file systems, and APIs, making me adaptable to a wide range of development environments and workflows.\n\n## Reliable, Auditable, and Deterministic Automation\nMy agent loop orchestrates all actions in a reliable, auditable, and deterministic manner. Each step is logged, validated, and executed according to plan, ensuring transparency and reproducibility. This makes me a trustworthy assistant for automating software engineering tasks.\n\n---\n\nThis file provides an overview of my capabilities and architecture for developers working with or extending the Coding Agent.'}
2025-05-07 22:17:51.935 | INFO     | coding_agent:_execute_local_tool:279 - 🔧 Tool new_file completed in 0.00 s
2025-05-07 22:17:52.319 | INFO     | coding_agent:_agent_loop:177 - ✅ new_file
2025-05-07 22:17:52.320 | INFO     | coding_agent:_agent_loop:179 - 🔢 Step 2 tokens used: 2108 (output: 424, input: 1684)
2025-05-07 22:17:53.082 | INFO     | coding_agent:_agent_loop:127 - --------------------------------------------------------------------------------
2025-05-07 22:17:53.082 | INFO     | coding_agent:_agent_loop:128 - 🔍 Step 3
2025-05-07 22:17:54.696 | INFO     | llm_providers.openai:invoke_model:107 - 🔄 Model response received in 1.24 s
2025-05-07 22:17:56.644 | INFO     | coding_agent:_execute_local_tool:229 - 🔦 LLM Requesting local tool: read_file with generated payload: {'file_path': 'coding-agent-intro.md'}
2025-05-07 22:17:56.646 | INFO     | coding_agent:_execute_local_tool:279 - 🔧 Tool read_file completed in 0.00 s
2025-05-07 22:17:57.047 | INFO     | coding_agent:_agent_loop:177 - ✅ read_file
2025-05-07 22:17:57.049 | INFO     | coding_agent:_agent_loop:179 - 🔢 Step 3 tokens used: 2165 (output: 23, input: 2142)
2025-05-07 22:17:57.822 | INFO     | coding_agent:_agent_loop:127 - --------------------------------------------------------------------------------
2025-05-07 22:17:57.822 | INFO     | coding_agent:_agent_loop:128 - 🔍 Step 4
2025-05-07 22:18:01.627 | INFO     | llm_providers.openai:invoke_model:107 - 🔄 Model response received in 3.43 s
2025-05-07 22:18:04.100 | INFO     | coding_agent:_agent_loop:177 - ✅ xpfinish-agent-execution-finished
2025-05-07 22:18:04.101 | INFO     | coding_agent:_agent_loop:179 - 🔢 Step 4 tokens used: 3068 (output: 474, input: 2594)
2025-05-07 22:18:05.220 | INFO     | coding_agent:_agent_loop:185 - ✨ Execution duration: 31.02 s
2025-05-07 22:18:05.224 | INFO     | coding_agent:_agent_loop:188 - 🔢 Total tokens used: 8955 (output: 950, input: 8005)
2025-05-07 22:18:06.494 | INFO     | coding_agent:chat:86 - --------------------------------------------------------------------------------
2025-05-07 22:18:06.495 | INFO     | coding_agent:chat:87 - 🤖 Agent response: Repository cloned and introduction file created as requested.

---

# Coding Agent Introduction

Hello! I am an autonomous Coding Agent, built with the [xpander-ai/coding-agent](https://github.com/xpander-ai/coding-agent) source code. As a self-driven software engineer, I am capable of generating, executing, and managing code through structured function-calling and a smart agent loop.

## Modular Architecture
My architecture is modular, allowing for flexible extension and integration. Each component is designed to handle specific responsibilities, such as code generation, file management, version control, and external system interaction. This modularity ensures maintainability and scalability.

## Schema-Driven Actions
I support schema-driven actions, which means all my operations are defined and validated against explicit schemas. This guarantees that every action I perform is predictable, type-safe, and easy to audit.

## Multi-Step Planning
I am capable of multi-step planning, breaking down complex tasks into smaller, manageable subtasks. This enables me to tackle sophisticated development workflows while ensuring each step is executed reliably and in the correct order.

## Context-Aware Memory
My context-aware memory allows me to retain and utilize relevant information throughout a session. I can reference previous actions, user instructions, and project state to make informed decisions and maintain continuity across tasks.

## Connector-Based System Integration
I integrate with external systems through a connector-based approach. This enables seamless interaction with tools such as Git, file systems, and APIs, making me adaptable to a wide range of development environments and workflows.

## Reliable, Auditable, and Deterministic Automation
My agent loop orchestrates all actions in a reliable, auditable, and deterministic manner. Each step is logged, validated, and executed according to plan, ensuring transparency and reproducibility. This makes me a trustworthy assistant for automating software engineering tasks.

---

This file provides an overview of my capabilities and architecture for developers working with or extending the Coding Agent.

No commits have been made yet. Let me know if you want to proceed with version control or further actions.

Notice how the AI performed local functions and was able to read files, clone the GitHub repo, and summarize its answer for you. You can now ask your agent follow-up questions about how function calling works and how it succeeded in performing the git clone operation, or continue with the workshop.

🌐 Stream Events from the Cloud to Your Local Agent

Now let’s set up your agent to receive events from the xpander.ai cloud platform. This allows you to interact with your agent through the web UI while processing happens on your local machine.

Start the event handler to listen for cloud events:

python xpander_handler.py

Example output

❯ python xpander_handler.py
Sandbox base directory: /Users/david/Developer/workshop/dev-agent-1/sandboxes
2025-04-30 13:16:57.677 | INFO     | xpander_utils.events.listener:register:287 - Starting events listener
2025-04-30 13:17:02.118 | INFO     | xpander_utils.events.listener:_register_agent_worker:238 - Worker registered - 1f588e29-fb15-4d53-b87b-5d037e108374
2025-04-30 13:17:02.118 | INFO     | xpander_utils.events.listener:_register_agent_worker:244 - Agent Name: dev-agent-1
 Chat URL: https://chocolate-jaguar.agents.xpander.ai

This url is the frontend of your agent, and it’s already configured with threads and memory. Try chatting and watch the events coming to your local machine.

You can also see the agent in the Tester Tab

Navigate to the URL displayed in the terminal output (e.g., https://app.xpander.ai/agents/your-agent-id) or to https://app.xpander.ai and search for dev-agent-1
You’ll see your agent in the xpander.ai web interface
Try sending a message like “Hi” to your agent
Watch as the request is processed by your local machine and the response appears in the web UI

You can now send new messages in the Tester tab, and this time the agent will respond directly from your local machine!

Agent responding from local machine through cloud UI

You’ve built an agent capable of receiving events from anywhere (Slack, MCP, Teams, REST API, and even other Agents using A2A) with just a few lines of code! This allows you to focus your time on writing the business logic rather than integration code.

🔑 Configure Cloud Environment Variables

To securely deploy your agent using the xpander.ai platform, you need to configure your environment secrets. There are two ways to do this:

Auto-sync from .env using the CLI (Recommended)
Manual configuration via the platform UI

🔐 Required Secrets

Ensure your .env file (or manual input) includes the following keys:

XPANDER_API_KEY=your_xpander_api_key ## From the output above
AWS_ACCESS_KEY_ID=your_aws_access_key
AWS_SECRET_ACCESS_KEY=your_aws_secret_key
AWS_SESSION_TOKEN=your_aws_session_token  # only needed if using temporary credentials
AWS_REGION="us-east-2"
BEDROCK_MODEL_ID="us.anthropic.claude-3-7-sonnet-20250219-v1:0"

GIT_TOKEN=your-git-token                  # Generate at https://github.com/settings/tokens/new
GIT_USERNAME=your-git-username

MAXIMUM_STEPS_SOFT_LIMIT=40
MAXIMUM_STEPS_HARD_LIMIT=60

OPENAI_MODEL_ID=gpt-4.1
OPENAI_API_KEY=your-open-ai-keys

Make sure to create a Personal Access Token (classic) on GitHub with repository permissions.

Use the CLI to automatically sync environment secrets from your .env file:

Steps:

Add the required keys above to your .env file.
Run the following command in your terminal:

xpander secrets-sync

Proceed to the validation step to ensure all secrets were created correctly.

Your .env file is not uploaded to the cloud, so syncing via CLI or manually entering secrets in the UI is required for deployment.

Use the CLI to automatically sync environment secrets from your .env file:

Steps:

Add the required keys above to your .env file.
Run the following command in your terminal:

xpander secrets-sync

Proceed to the validation step to ensure all secrets were created correctly.

Your .env file is not uploaded to the cloud, so syncing via CLI or manually entering secrets in the UI is required for deployment.

If you prefer to configure secrets manually, follow these steps:

Steps:

Sign in to xpander.ai
Go to Settings > Environment Secrets
Add each of the required keys and their values manually (see list above)

If you’re participating in this workshop in person, ask the xpander.ai team for credentials.

🧪 Final Validation

After syncing or manually entering your secrets, validate that everything is set up correctly.

Go to the Settings > Environment Secrets page on xpander.ai
Ensure that all required keys appear.

This validation ensures that your cloud agent will have access to the necessary credentials during deployment.

These credentials allow your cloud-deployed agent to access Amazon Bedrock and GitHub securely, without hardcoding sensitive data into your codebase.

🚀 Deploy to the Cloud

Now that we’ve confirmed the agent is performing its job and can receive events from the cloud, we can simply host it as a container in the xpander cloud and trigger it when needed!

Deploy the agent to the cloud:

xpander deploy

Example output:

❯ xpander deploy
✨ Agent deployment
────────────────────────────────────────────────────────────
? Are you sure you want to deploy your AI Agent? Yes
[+] Building 15.9s (9/10)                                                                                                          docker:desktop-linux
[+] Building 17.9s (11/11) FINISHED                                                                                                docker:desktop-linux
 => [internal] load build definition from Dockerfile                                                                                               0.0s
 => => transferring dockerfile: 839B                                                                                                               0.0s
 => [internal] load metadata for docker.io/library/python:3.12-alpine                                                                              1.7s
 => [internal] load .dockerignore                                                                                                                  0.0s
 => => transferring context: 92B                                                                                                                   0.0s
 => [1/6] FROM docker.io/library/python:3.12-alpine@sha256:c08bfdbffc9184cdfd225497bac12b2c0dac1d24bbe13287cfb7d99f1116cf43                        0.0s
 => => resolve docker.io/library/python:3.12-alpine@sha256:c08bfdbffc9184cdfd225497bac12b2c0dac1d24bbe13287cfb7d99f1116cf43                        0.0s
 => [internal] load build context                                                                                                                  0.4s
 => => transferring context: 59.91MB                                                                                                               0.4s
 => CACHED [2/6] WORKDIR /usr/src/app                                                                                                              0.0s
 => CACHED [3/6] RUN apk add --no-cache     curl     bash     gcc     g++     libffi-dev     musl-dev     openssl-dev     make     python3-dev     0.0s
 => CACHED [4/6] RUN python3 -m venv /venv                                                                                                         0.0st
 => [5/6] COPY . .                                                                                                                                 0.4s
 => [6/6] RUN pip install --no-cache-dir --upgrade pip &&     pip install --no-cache-dir -r requirements.txt                                      14.1s
 => exporting to image                                                                                                                             1.2s
 => => exporting layers                                                                                                                            1.2s
 => => exporting manifest sha256:0289aa66b12daf4645d1a1a2b2ad91bf7909c88d5186fde50140d836c577530e                                                  0.0s
 => => exporting config sha256:2b9c7296215e889d6fb02d88a0bee9a70ce2b394c11f0b5c5aaaadc2fa2e4dd8                                                    0.0s
 => => exporting attestation manifest sha256:ae45b33e81cce3fd5f40701243f5ba6bf39d2cb58878d2d19c6b1bbc21d3ca9a                                      0.0s
 => => exporting manifest list sha256:e2fd5bbeb03bfd140e8ea3847f2ce8f6734aba155da858e5e471d1db97857b99                                             0.0s
 => => naming to docker.io/library/95c6db28-7052-4054-8970-fa1f69f16de0:latest                                                                     0.0s
✔ ✅ Upload complete
✔ Agent dev-agent-1 deployed successfully

Congratulations on deploying your agent to the cloud!

Once deployment is complete, your agent will be fully operational in the cloud, allowing others to interact with it through the web interface.

Access your agent via the agent platform (https://app.xpander.ai/agents)

Test the agent with the following prompt

Prompt

I want to submit app to xpander-ai/apps-by-agents can you summarize the requirements ?

run xpander logs to stream logs from the remote server to your terminal

✅ Checkpoint

By completing this module, you should now be able to:

Create and configure a developer agent with xpander.ai
Run the agent locally and interact with it via terminal
Connect your local agent to the xpander.ai cloud platform
Deploy your agent to the cloud for remote access
Understand the core architecture of developer agents

🔄 Next Steps

Now that you’ve built your first developer agent, you’re ready to expand your agent fleet in the next module.

Workshops

​🔧 Setup Your Development Environment

​🛠️ Configure Your Local Environment

​🔑 Authenticate to xpander.ai

​🤖 Create Your Agent

​🚀 Run Your Agent Locally

​💬 Example Agent Interaction

​Ask the agent to introduce itself and explain how it works

​🌐 Stream Events from the Cloud to Your Local Agent

​🔑 Configure Cloud Environment Variables

​🔐 Required Secrets

​Steps:

​Steps:

​Steps:

​🧪 Final Validation

​🚀 Deploy to the Cloud

​✅ Checkpoint

​🔄 Next Steps

🔧 Setup Your Development Environment

🛠️ Configure Your Local Environment

🔑 Authenticate to xpander.ai

🤖 Create Your Agent

🚀 Run Your Agent Locally

💬 Example Agent Interaction

Ask the agent to introduce itself and explain how it works

🌐 Stream Events from the Cloud to Your Local Agent

🔑 Configure Cloud Environment Variables

🔐 Required Secrets

Steps:

Steps:

Steps:

🧪 Final Validation

🚀 Deploy to the Cloud

✅ Checkpoint

🔄 Next Steps