Module 2: Build Your First Coding Agent

Module Summary

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

🚀 In this module, you’ll set up a complete AI coding assistant powered by xpander.ai and Amazon Bedrock. 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 uninstall python --ignore-dependencies && \ 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

🔑 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:

AWS_ACCESS_KEY_ID=your_aws_access_key
AWS_SECRET_ACCESS_KEY=your_aws_secret_key
AWS_SESSION_TOKEN=your_aws_session_token  # if using temporary credentials
AWS_PROFILE=your_profile # if using AWS Profile without keys
AWS_REGION=us-west-2
XPANDER_API_KEY=your_xpander_api_key ## From the output above

Make sure you have your AWS credentials set up with Amazon Bedrock access and an xpander.ai API key ready for this step. 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-4o
──────────────────────────────────────────────────

✅ 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

If you skipped the init command, you can always run xpander agent init and select the agent you just created.

🚀 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
loading agent 9002f816-1926-4556-a275-6e6fcc8bb86a
🧠 Adding task to a new thread
🪄 Starting Agent Loop
🧠 Thread id: 81b08c86-ca55-4b3e-a14d-af690f07846e
--------------------------------------------------------------------------------
🔍 Step 1
running tool git_clone on agent 9002f816-1926-4556-a275-6e6fcc8bb86a with execution 1da0e645-068b-4fdf-8d71-762a5c880241
🔦 Executing local tool: git_clone with generated payload: {'repo_url': 'https://github.com/xpander-ai/coding-agent'}
✅ git_clone
🧠 Thread id: 81b08c86-ca55-4b3e-a14d-af690f07846e
--------------------------------------------------------------------------------
🔍 Step 2
running tool describe_folders_and_files on agent 9002f816-1926-4556-a275-6e6fcc8bb86a with execution 1da0e645-068b-4fdf-8d71-762a5c880241
🔦 Executing local tool: describe_folders_and_files with generated payload: {}
✅ describe_folders_and_files
🧠 Thread id: 81b08c86-ca55-4b3e-a14d-af690f07846e
--------------------------------------------------------------------------------
🔍 Step 3
running tool read_file on agent 9002f816-1926-4556-a275-6e6fcc8bb86a with execution 1da0e645-068b-4fdf-8d71-762a5c880241
🔦 Executing local tool: read_file with generated payload: {'file_path': 'coding-agent/README.md'}
✅ read_file
🧠 Thread id: 81b08c86-ca55-4b3e-a14d-af690f07846e
--------------------------------------------------------------------------------
🔍 Step 4
running tool read_file on agent 9002f816-1926-4556-a275-6e6fcc8bb86a with execution 1da0e645-068b-4fdf-8d71-762a5c880241
🔦 Executing local tool: read_file with generated payload: {'file_path': 'coding-agent/coding_agent.py'}
✅ read_file
🧠 Thread id: 81b08c86-ca55-4b3e-a14d-af690f07846e
--------------------------------------------------------------------------------
🔍 Step 5
running tool read_file on agent 9002f816-1926-4556-a275-6e6fcc8bb86a with execution 1da0e645-068b-4fdf-8d71-762a5c880241
🔦 Executing local tool: read_file with generated payload: {'file_path': 'coding-agent/main.py'}
✅ read_file
🧠 Thread id: 81b08c86-ca55-4b3e-a14d-af690f07846e
--------------------------------------------------------------------------------
🔍 Step 6
running tool read_file on agent 9002f816-1926-4556-a275-6e6fcc8bb86a with execution 1da0e645-068b-4fdf-8d71-762a5c880241
🔦 Executing local tool: read_file with generated payload: {'file_path': 'coding-agent/local_tools.py'}
✅ read_file
🧠 Thread id: 81b08c86-ca55-4b3e-a14d-af690f07846e
--------------------------------------------------------------------------------
🔍 Step 7
running tool new_file on agent 9002f816-1926-4556-a275-6e6fcc8bb86a with execution 1da0e645-068b-4fdf-8d71-762a5c880241
🔦 Executing local tool: new_file with generated payload: {'file_path': 'coding-agent-intro.md', 'content': '# 🤖 Autonomous Coding Agent\n\n## Introduction\n\nI am an autonomous Coding Agent built with the xpander-ai/coding-agent framework. As a self-driven software engineer, I can generate, execute, and manage code through structured function-calling and a smart agent loop. I operate independently to help you build, test, and deploy software with minimal human intervention.\n\n## Modular Architecture\n\nMy architecture is designed with modularity at its core:\n\n```\n┌───────────────┐         ┌──────────────┐         ┌────────────────────┐\n│ Any other     │         │ coding_agent ├─Native─►│  Any LLM provider  │\n│ Agent         ├─--A2A──►│              │         └────────────────────┘\n└───────────────┘         └──────────────┘\n                                 │\n                                 │ function‑calls (MCP)\n                                 ▼\n                          ┌─────────────────────────┐\n                          │  xpander.ai connectors  │───▶ Any Rest API\n                          └─────────────────────────┘\n                                 │\n                                 ▼\n                          ┌─────────────────────────┐\n                          │  Secure sandbox (FS)    │\n                          └─────────────────────────┘\n```\n\n### Key Components:\n\n1. **LLM-Agnostic Core**: I can work with any LLM provider (OpenAI, Anthropic, Bedrock, etc.) without modification.\n2. **Secure Sandbox**: All file operations occur in an isolated environment to prevent security risks.\n3. **Function-Call Interface**: I interact with systems through a standardized function-calling mechanism.\n4. **Agent-to-Agent Communication**: I can collaborate with other specialized agents in a coordinated workflow.\n\n## Schema-Driven Actions\n\nI operate using well-defined schemas for all actions:\n\n- **Tool Declarations**: Each function I can call is precisely defined with parameter types and requirements\n- **Model Context Protocol (MCP)**: I follow standardized protocols for interacting with external systems\n- **Validation Layers**: All inputs and outputs are validated against schemas to ensure correctness\n\nThis schema-driven approach ensures that my actions are predictable, secure, and compatible with various systems.\n\n## Multi-Step Planning\n\nI break down complex tasks into manageable steps:\n\n1. **Task Analysis**: I analyze the requirements to determine necessary actions\n2. **Dependency Mapping**: I identify dependencies between subtasks\n3. **Sequential Execution**: I execute steps in the optimal order\n4. **Error Handling**: I detect failures and adapt my approach accordingly\n\nThis planning capability allows me to tackle complex software engineering tasks that require multiple coordinated actions.\n\n## Context-Aware Memory\n\nMy memory system maintains state across interactions:\n\n- **Thread-Based Memory**: Each conversation maintains its own persistent state\n- **Contextual Awareness**: I remember previous actions and their outcomes\n- **File System Awareness**: I track changes to the codebase over time\n- **Execution History**: I maintain a record of all tool calls and their results\n\nThis memory system enables me to work on long-running tasks and maintain context across multiple interactions.\n\n## Connector-Based System Integration\n\nI integrate with external systems through a flexible connector architecture:\n\n- **Git Operations**: Clone repositories, commit changes, and push to branches\n- **File System Operations**: Create, read, update, and delete files securely\n- **API Integrations**: Connect to any REST or gRPC endpoint\n- **Testing Frameworks**: Execute and interpret test results\n\nThese connectors allow me to interact with real-world systems while maintaining security and reliability.\n\n## The Agent Loop: Reliable, Auditable, Deterministic Automation\n\nAt the heart of my operation is the agent loop, which enables reliable, auditable, and deterministic automation:\n\n1. **Input Processing**: I receive and interpret user instructions\n2. **Planning**: I determine the sequence of actions needed\n3. **Tool Selection**: I choose the appropriate tools for each step\n4. **Execution**: I call functions with validated parameters\n5. **Result Analysis**: I interpret the results of each action\n6. **Adaptation**: I adjust my approach based on outcomes\n7. **Communication**: I provide clear updates on progress and results\n\nThis structured loop ensures that my actions are:\n\n- **Reliable**: I follow consistent patterns and handle errors gracefully\n- **Auditable**: Every action is logged and can be reviewed\n- **Deterministic**: Given the same inputs, I produce consistent outputs\n\nBy combining these capabilities, I can autonomously handle complex software engineering tasks while maintaining the high standards expected in professional development environments.'}
✅ new_file
🧠 Thread id: 81b08c86-ca55-4b3e-a14d-af690f07846e
--------------------------------------------------------------------------------
🔍 Step 8
running tool xpfinish-agent-execution-finished on agent 9002f816-1926-4556-a275-6e6fcc8bb86a with execution 1da0e645-068b-4fdf-8d71-762a5c880241
✅ xpfinish-agent-execution-finished
📝 Last message: {'toolResult': {'toolUseId': 'tooluse_20vLMJVATIOaHWVJmx477Q', 'content': [{'text': '"I\'ve successfully cloned the xpander-ai/coding-agent repository and created a comprehensive introduction file called \'coding-agent-intro.md\'. This file introduces the Autonomous Coding Agent as a self-driven software engineer capable of generating, executing, and managing code through structured function-calling and a smart agent loop.\\n\\nThe introduction covers:\\n\\n1. The agent\'s modular architecture that works with any LLM provider\\n2. Schema-driven actions that ensure predictable and secure operations\\n3. Multi-step planning capabilities for complex tasks\\n4. Context-aware memory system that maintains state across interactions\\n5. Connector-based system integration for working with external systems\\n6. The agent loop that enables reliable, auditable, and deterministic automation\\n\\nThe file is ready for review in the repository. As requested, I did not commit any changes."'}]}}

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

🧠 AI Agent response: I've successfully cloned the xpander-ai/coding-agent repository and created a comprehensive introduction file called 'coding-agent-intro.md'. This file introduces the Autonomous Coding Agent as a self-driven software engineer capable of generating, executing, and managing code through structured function-calling and a smart agent loop.

The introduction covers:

1. The agent's modular architecture that works with any LLM provider
2. Schema-driven actions that ensure predictable and secure operations
3. Multi-step planning capabilities for complex tasks
4. Context-aware memory system that maintains state across interactions
5. Connector-based system integration for working with external systems
6. The agent loop that enables reliable, auditable, and deterministic automation

The file is ready for review in the repository. As requested, I did not commit any changes.

You can now interact with your agent through the terminal by typing messages and questions!

Ask your agent follow-up questions about how function calling works and how it succeeded in performing the git clone operation. Also ask it to explain what the agent loop is.

🌐 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.

🚀 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! While the deployment is in progress, let’s configure the necessary environment variables in the xpander vault to ensure your agent can run properly in the cloud environment.

🔑 Configure Cloud Environment Variables

Navigate to the xpander.ai platform and sign in
Go to settings > Environment Secrets
Add the following keys with their respective values:

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"
GIT_TOKEN=your-git-token # Get it from (https://github.com/settings/tokens/new)
GIT_USERNAME=your-git-username 

Make sure to create a Personal Access Token (classic) with repository action permissions

These credentials will allow your cloud-deployed agent to access Amazon Bedrock services securely without storing sensitive information in your code.

Configuring these environment variables in the vault is crucial for cloud deployment. Your local .env file is not uploaded to the cloud for security reasons, so these values must be configured separately in the xpander platform.

Once deployment is complete and environment variables are configured, 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)

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

​🌐 Stream Events from the Cloud to Your Local Agent

​🚀 Deploy to the Cloud

​🔑 Configure Cloud Environment Variables

​✅ 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

🌐 Stream Events from the Cloud to Your Local Agent

🚀 Deploy to the Cloud

🔑 Configure Cloud Environment Variables

✅ Checkpoint

🔄 Next Steps