Overview

Agentuity Overview

Agentuity is a cloud platform designed to run and scale AI agents with enterprise-grade reliability. Our architecture follows a container-based approach, where each agent operates in its own specialized environment.

Unlike traditional serverless platforms, Agentuity ensures agents run for as long as needed, maintaining state and context throughout agent lifecycles. This long-running approach is optimal for complex agent workloads that may require extended processing time, access to storage, or other resources.

The platform is fundamentally cross-platform, allowing you to run different agent frameworks (CrewAI, Langchain, custom agents) side by side in the same ecosystem, with built-in communication channels between them.

Core Components

Agentuity consists of five primary components:

1. Agent Platform - The cloud platform for providing agent services, providing:

   • Agent communication and routing
   • Agent monitoring, logging, telemetry and troubleshooting
   • Agent usage analytics and performance insights
   • Automatic scaling on-demand based on workload
   • Agent services such as KeyValue, Vector storage, AI Gateway and more

2. Agent Runtime - The execution environment where your agents run, providing:

   • Isolated, secure virtualized environment for each agent project
   • Resource management and optimization
   • Long-running support for persistent agents
   • Dynamic Storage, Compute and Networking resources

3. Command Line Interface (CLI) - A developer tool that enables:

   • Quick agent creation and initialization
   • Local development and testing
   • Deployment management to the Agentuity cloud
   • Integration with external Agentic code tools via MCP

4. Software Development Kits (SDKs) - Libraries that provide:

   • Agent-native tools and services integration with the Agent Platform
   • Runtime-specific optimizations for Python and JavaScript (Node and Bun)
   • Integration capabilities with external systems
   • Enhanced agent capabilities and extensions which work cross-framework and cross-runtime

5. Web Console - A management interface offering:

   • Real-time agent monitoring and metrics
   • Deployment and configuration management
   • Usage analytics, logging, monitoring and performance insights
   • Team collaboration features

Data Flow

Agent communication and data flow in Agentuity follow secure, encrypted channels:

1. Agent-to-Agent Communication - Agents can communicate with each other through authenticated, encrypted routing, regardless of the underlying frameworks or runtimes used.

2. External Integrations - Agents can connect to external systems and data sources through managed integration points.

3. Deployment Pipeline - Your project code is packaged, containerized, and deployed to the Agentuity cloud infrastructure with appropriate networking and routing configured automatically. Built-in support for GitHub Actions.

Scalability

Agentuity is designed for enterprise-scale agent deployments:

• Horizontal Scaling - Automatically provision additional resources as demand increases
• Framework Agnostic - Scale any type of agent regardless of the underlying framework
• Load Balancing - Distribute agent workloads efficiently across available resources
• Resource Optimization - Intelligently allocate compute resources based on agent requirements

Security Architecture

Security is foundational to Agentuity's design:

• Agent Isolation - Each agent project operates in its own isolated environment
• Encrypted Communications - All agent-to-agent communication is encrypted
• Secure Deployment - Protected deployment pipeline from development to production

Project Conventions

Agentuity projects follow specific conventions in order to take advantage of the deployment and cloud platform Agentuity offers. While we don't dictate which framework to use, we do have a few things you have to follow in your file system. Understanding these conventions are important.

Project Structure

Every Agentuity project requires the following core components:

1. agentuity.yaml - The central configuration file that defines:

   • Project metadata (name, ID, description)
   • Development settings (port, watch patterns)
   • Deployment configuration (resources, scaling)
   • Bundler settings (language, runtime)
   • Agent definitions and routing

2. Environment Variables - Stored in a .env file:

   • AGENTUITY_SDK_KEY - Identifies the SDK level API Key (only used in development to access the Agentuity Cloud)
   • AGENTUITY_PROJECT_KEY - Identifies the project level API Key
   • Additional provider-specific keys (OpenAI, Anthropic, etc.)

3. Agent Directory - Specified in bundler.agents.dir (determined by the runtime):

   • Each agent has its own subdirectory
   • Language-specific entry points (index.ts/js for JavaScript, agent.py for Python)
   • Agent-specific configuration and dependencies

Language-Specific Conventions

JavaScript/TypeScript Projects

my-project/
├── agentuity.yaml        # Project configuration
├── .env                  # Environment variables
├── package.json          # Dependencies and scripts
└── src/
    └── agents/           # Agent directory
        └── my-agent/     # Individual agent
            └── index.ts  # Agent entry point

• Each agent must export a handler function that processes requests
• TypeScript is recommended but JavaScript is fully supported
• Supported runtimes: Node.js and Bun

Python Projects

my-project/
├── agentuity.yaml        # Project configuration
├── .env                  # Environment variables
├── pyproject.toml        # Dependencies and configuration
└── agents/               # Agents directory
    └── my-agent/         # Individual agent
        └── agent.py      # Agent entry point

• Each agent must define a run() function that processes requests
• Supported runtimes: Python and uv (for dependency management)

Configuration File (agentuity.yaml)

The agentuity.yaml file is the heart of your project, defining how it behaves in development and production:

version: ">=0.0.0"         # Minimum CLI version required
project_id: "proj_..."     # Unique project identifier
name: "My Project"         # Human-readable project name
description: "..."         # Optional project description
 
# Development configuration
development:
  port: 3000               # Local development server port
  watch:
    enabled: true          # Auto-reload on file changes
    files: ["src/**/*.ts"] # Files to watch
 
# Deployment configuration
deployment:
  resources:
    memory: "1Gi"          # Memory allocation
    cpu: "1000m"           # CPU allocation
 
# Bundler configuration
bundler:
  language: "javascript"   # Programming language (javascript or python)
  runtime: "nodejs"        # Runtime environment (nodejs, bunjs, python, uv)
  agents:
    dir: "src/agents"      # Directory where agents are located
 
# Agents configuration
agents:
  - id: "agent_..."        # Unique agent identifier
    name: "My Agent"       # Human-readable agent name
    description: "..."     # Optional agent description

Why These Conventions Matter

These conventions enable several key capabilities:

1. Consistent Development Experience - Standardized structure makes it easier to work across projects
2. Automated Deployment - The CLI can package and deploy your project without additional configuration
3. Framework Flexibility - Use any agent framework while maintaining compatibility with the platform