Set up a local developer agent and understand its core capabilities
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!
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β AuthorizingHi 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 aboveAWS_ACCESS_KEY_ID=your_aws_access_keyAWS_SECRET_ACCESS_KEY=your_aws_secret_keyAWS_SESSION_TOKEN=your_aws_session_token # only needed if using temporary credentialsAWS_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/newGIT_USERNAME=your-git-usernameMAXIMUM_STEPS_SOFT_LIMIT=40MAXIMUM_STEPS_HARD_LIMIT=60OPENAI_MODEL_ID=gpt-4.1OPENAI_API_KEY=your-open-ai-keys
If you are running this workshop in person, ask the xpander.ai team to provide you access.
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-1ID: 4fe1163d-bb00-4837-9e25-6f82aed8038cIcon: π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
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.
Hereβs what you might see in the terminal as your agent runs:
β― python main.pySandbox base directory: /Users/david/Developer/workshop/dev-agent-1/sandboxesb'{"stdout":"bG9hZGluZyBhZ2VudCA3Mzc2MmYyNi04MDMzLTRkODEtYWVlOC02NjViOWI0NGQ5Y2YK"}\n'2025-05-07 22:12:53.344 | INFO | coding_agent:chat:82 - π§ Adding task to a new thread2025-05-07 22:12:54.254 | INFO | coding_agent:_agent_loop:116 - πͺ Starting Agent Loop2025-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 12025-05-07 22:12:58.438 | INFO | llm_providers.openai:invoke_model:107 - π Model response received in 1.51β―s2025-05-07 22:13:00.507 | INFO | coding_agent:_agent_loop:177 - β xpfinish-agent-execution-finished2025-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 s2025-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-5c49fbbeef292025-05-07 22:17:34.202 | INFO | coding_agent:_agent_loop:116 - πͺ Starting Agent Loop2025-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 12025-05-07 22:17:36.941 | INFO | llm_providers.openai:invoke_model:107 - π Model response received in 1.25β―s2025-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 s2025-05-07 22:17:41.667 | INFO | coding_agent:_agent_loop:177 - β git_clone2025-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 22025-05-07 22:17:49.063 | INFO | llm_providers.openai:invoke_model:107 - π Model response received in 6.17β―s2025-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 s2025-05-07 22:17:52.319 | INFO | coding_agent:_agent_loop:177 - β new_file2025-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 32025-05-07 22:17:54.696 | INFO | llm_providers.openai:invoke_model:107 - π Model response received in 1.24β―s2025-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 s2025-05-07 22:17:57.047 | INFO | coding_agent:_agent_loop:177 - β read_file2025-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 42025-05-07 22:18:01.627 | INFO | llm_providers.openai:invoke_model:107 - π Model response received in 3.43β―s2025-05-07 22:18:04.100 | INFO | coding_agent:_agent_loop:177 - β xpfinish-agent-execution-finished2025-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 s2025-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 IntroductionHello! 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 ArchitectureMy 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 ActionsI 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 PlanningI 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 MemoryMy 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 IntegrationI 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 AutomationMy 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.pySandbox base directory: /Users/david/Developer/workshop/dev-agent-1/sandboxes2025-04-30 13:16:57.677 | INFO | xpander_utils.events.listener:register:287 - Starting events listener2025-04-30 13:17:02.118 | INFO | xpander_utils.events.listener:_register_agent_worker:238 - Worker registered - 1f588e29-fb15-4d53-b87b-5d037e1083742025-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.
Ensure your .env file (or manual input) includes the following keys:
XPANDER_API_KEY=your_xpander_api_key ## From the output aboveAWS_ACCESS_KEY_ID=your_aws_access_keyAWS_SECRET_ACCESS_KEY=your_aws_secret_keyAWS_SESSION_TOKEN=your_aws_session_token # only needed if using temporary credentialsAWS_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/newGIT_USERNAME=your-git-usernameMAXIMUM_STEPS_SOFT_LIMIT=40MAXIMUM_STEPS_HARD_LIMIT=60OPENAI_MODEL_ID=gpt-4.1OPENAI_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:
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!
