A reference implementation demonstrating how to build production-ready AI agents with autonomous task execution capabilities.
Note: This project accompanies the blog article "Robots Are Taking Our Jobs: Understanding AI Agents"
This starter kit shows you how to build an AI agent that:
- Executes multi-step tasks autonomously
- Uses fictional tools to retrieve information
- Maintains conversation context and memory
- Runs in a dockerized enivronment
- Uses a supervisor pattern with specific subagent for specific tasks
Built with VoltAgent and deployed using SST, this project provides a foundation for creating your own custom agents.
- Node.js 20+
- Git
- pnpm (install with
npm install -g pnpm) - AWS Account (for deployment and bedrock access)
# Clone the repository
git clone <your-repo-url>
cd my-agent-app
# Install dependencies
pnpm installThis project uses AWS and AWS Bedrock for access to an LLM. Set up your credentials for your AWS account with access to AWS Bedrock as environment variables.
A tip, checkout sesh which is an excellent tool for accessing multiple AWS accounts.
If you prefer other providers, checkout the VoltAgent docs how to reconfigure the model.
# Start development server with hot reload
pnpm devYour agent is now running at http://localhost:3141 which exposes and API and API docs, VoltAgent comes with a really nice
console which is referenced via the termonal output to test the agents out.
The agent includes example tools and workflows. You can interact with it via HTTP requests or integrate it into your applications.
Example tools included:
- Weather Tool: Demonstrates external API integration
- Meme agent Which only return reponses in memes
- Custom tools can be added in
src/tools/
This project uses SST (Serverless Stack) for deployment, which creates a serverless API running your agent.
The deployment uses a ECS and fargate which is a very cheap way of hosting your docker containers, but this still has a ticking cost. Make sure to tear down your stack if you are just playing around.
Ensure you have AWS credentials configured:
# Option 1: Using AWS CLI
aws configure
# Option 2: Set environment variables
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
export AWS_REGION=us-east-1# Deploy to your AWS account
pnpm sst deployThe deployment will output your API endpoint URL. Your agent is now accessible via this public endpoint.
Important: To avoid ongoing AWS charges, remove the stack when you're finished:
# Remove all AWS resources
pnpm sst removeCreate new tools in src/tools/:
import { createTool } from "@voltagent/core";
import { z } from "zod";
export const myTool = createTool({
name: "myTool",
description: "Description of what this tool does",
input: z.object({
param: z.string(),
}),
output: z.string(),
handler: async ({ param }) => {
// Tool logic here
return `Result: ${param}`;
},
});Then export it from src/tools/index.ts and register it in src/index.ts.
Tools can interact with any external system:
- APIs and webhooks
- Databases
- Cloud services (S3, DynamoDB, etc.)
- Third-party integrations (Stripe, SendGrid, etc.)
See the weather tool (src/tools/weather.ts) for an example of external API integration.
Alternative deployment option using Docker:
# Build image
docker build -t my-agent-app .
# Run container
docker run -p 3141:3141 --env-file .env my-agent-app- Documentation: voltagent.dev
- Examples: github.com/VoltAgent/voltagent
- Community: VoltAgent Discord
- Documentation: sst.dev
- Getting Started: sst.dev/docs
- Discord Community: SST Discord
pnpm dev- Start development server with hot reloadpnpm build- Build for productionpnpm start- Run production build locallypnpm sst deploy- Deploy to AWSpnpm sst remove- Remove AWS resources