AI Agent Platform

A comprehensive platform for creating, managing, and deploying standalone AI agents with tool support and MCP server integration.

🚀 Key Features

• Standalone Agent Deployment: Each agent is an independent, deployable application
• Automatic Setup: Dependencies installed automatically during agent creation
• Tool-Aware Instructions: Agents automatically understand their available tools (Gmail, Calendar, Slack)
• Supported Models: gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, o4-mini, o3
• Distributed Architecture: Centralized development, distributed deployment
• Multiple Deployment Targets: Lambda, Docker, HTTP servers, custom environments
• Runtime Package: Shared ai-agent-runtime package for easy updates
• Custom Tools: Agent-specific tools and business logic
• MCP Server Support: Connect to Model Context Protocol servers with OAuth support
• Template System: Pre-configured agent templates
• Version Management: Controlled runtime updates across agents

Quick Start

Installation

git clone <repository>
npm install
npm run build

Create Your First Standalone Agent

# Create a standalone agent repository (dependencies auto-installed)
npm run dev -- agent create-repo -n "my-assistant" -m "gpt-4.1" -i "You are a helpful assistant" --mcp-servers "google-workspace"

# Ready to use immediately! Chat with your agent:
npm run dev -- chat --agent "my-assistant"

# Or run directly from agent directory:
cd ~/.agent-fleet/agents/my-assistant/
npm run dev  # Interactive development mode

# Or build and deploy
npm run build
npm start    # HTTP server mode

Alternative: Platform-managed Agents

# Create agent in platform database (legacy)
npm run dev agent add --interactive

# Chat through platform
npm run dev chat --agent my-assistant

Architecture

The platform uses a distributed architecture designed for scalability:

┌─ AI Agent CLI Platform ─┐     ┌─ ai-agent-runtime ─┐
│  ├─ Agent Builder       │────▶│  ├─ AgentRuntime    │
│  ├─ Template System     │     │  ├─ Built-in Tools  │
│  ├─ Database (SQLite)   │     │  ├─ MCP Integration │
│  └─ Repository Manager  │     │  └─ Tool-Aware AI   │
└─────────────────────────┘     └────────────────────┘
            │                                   │
    ┌───────▼───────┐                          │
    │ Configuration │                          │
    └───────────────┘                          │
                                               │
            ┌──────────────────────────────────▼──────────────────────┘
            │
    ┌───────▼───────┐
    │ Standalone    │
    │ Agents        │
    ├─ Lambda       │
    ├─ Docker       │
    ├─ HTTP Server  │
    └─ Custom       │

Components

• CLI Platform: Agent creation, management, and development tools
• Runtime Package: Shared ai-agent-runtime package for deployed agents
• Agent Repositories: Independent TypeScript applications with auto-generated tool awareness
• Template System: Reusable agent configurations
• Version Management: Centralized updates, distributed deployment

Configuration

Platform Environment Variables

Create a .env file in the project root:

OPENAI_API_KEY=your-openai-api-key
AI_MODEL=gpt-4.1

Agent Environment Variables

Each agent has its own .env file:

# In ~/.agent-fleet/agents/my-agent/.env
OPENAI_API_KEY=your-openai-api-key
NODE_ENV=development
PORT=3000

Standalone Agent Development

Custom Tools

Add agent-specific tools in src/custom-tools.ts:

import { z } from 'zod';
import type { ToolDefinition } from 'ai-agent-runtime';

export async function getCustomTools(): Promise<ToolDefinition[]> {
  return [
    {
      name: 'weather_check',
      description: 'Check current weather for a location',
      parameters: z.object({
        location: z.string().describe('City name')
      }),
      execute: async ({ location }) => {
        // Your weather API integration
        return { temperature: 72, condition: 'sunny' };
      }
    }
  ];
}

Deployment Options

# HTTP Server
npm run build && npm start

# Docker
npm run deploy:docker

# AWS Lambda
npm run deploy:lambda

# Development
npm run dev

MCP Server Integration

Connect to external services using MCP servers:

# agent.yaml
mcpServers:
  - name: filesystem
    url: npx @modelcontextprotocol/server-filesystem /allowed/path
  - name: database
    url: node ./custom-mcp-server.js
    env:
      DB_CONNECTION: "postgresql://..."

Development

Platform Development

# Build CLI platform
npm run build
npm run typecheck

# Build runtime package
cd packages/runtime/
npm run build

Agent Development

# In agent directory
cd ~/.agent-fleet/agents/my-agent/

# Development mode
npm run dev

# Build for production
npm run build

# Type checking
npm run typecheck

# Validate configuration
npm run validate

Runtime Updates

# Update runtime package
cd packages/runtime/
npm version minor
npm publish

# Update specific agents
cd ~/.agent-fleet/agents/my-agent/
npm update ai-agent-runtime
npm run build && npm run deploy

Agent Templates

Available templates for quick agent creation:

• sample-developer-assistant: File system and shell access for development tasks
• personal-assistant: General purpose assistant with productivity tools
• custom: Start from scratch

# List available templates
npm run dev template list

# Create from template
npm run dev agent create-repo --template "sample-developer-assistant"

Version Management

Centralized Updates

1. Platform team updates runtime:

   cd packages/runtime/
   # Add new tools/features
   npm version minor  # 1.0.0 → 1.1.0
   npm publish

2. Agent owners update selectively:

   cd ~/.agent-fleet/agents/my-agent/
   npm update [email protected]
   npm run build && npm run deploy

3. Bulk updates (optional):

   npm run dev agent bulk-update --runtime-version 1.1.0

Production Examples

HTTP Server Agent

// Automatically included in each agent
import { createAgentRuntime, loadManifestFromFile } from 'ai-agent-runtime';
import { startServer } from './server.js';

const manifest = await loadManifestFromFile('agent.yaml');
const runtime = await createAgentRuntime(manifest, customTools);
await startServer(runtime, 3000);

AWS Lambda Agent

export const handler = async (event, context) => {
  const runtime = await createAgentRuntime(manifest, customTools);
  const response = await runtime.chat(event.message);
  return { statusCode: 200, body: JSON.stringify({ response }) };
};

Docker Deployment

# Automatically included in each agent
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

Built-in Tools

Each agent includes these built-in tools:

• calculator: Mathematical calculations
• read_file: Read file contents
• write_file: Write to files
• list_directory: List directory contents
• shell: Execute shell commands
• web_search: Web search capabilities

Contributing

Contributions are welcome! Please read the contributing guidelines before submitting PRs.

• Runtime Package: Shared functionality for all agents
• CLI Platform: Agent creation and management tools
• Templates: Reusable agent configurations
• Documentation: Guides and examples

Documentation

• Quick Start Guide: Get started quickly
• Deployment Guide: Complete deployment instructions
• Development Guide: Detailed development documentation
• Runtime Package: ai-agent-runtime docs

License

MIT License - see LICENSE file for details.