runagent 0.1.19

A command-line tool and SDK for deploying, managing, and interacting with AI agents

Universal AI Agent Platform

Write agent once, use everywhere

Write AI agents once in Python, access them natively from any language.
Deploy locally today, or on our serverless cloud platform (coming soon).

Features • Quick Start • CLI • Documentation • Contributing

---

🎯 What is RunAgent?

RunAgent is an AI Agent Deployment Platform, built for builders who are using AI agents to empower/enhance their products. From development to deployment, RunAgent enables the developer to fully focus on actual agent development, and not care about:

• Deploying AI Agents with powerful RunAgent CLI with a simple configuration file.
• Spinning up a configurable REST-API and WebSocket server for your agents with one cli command.
• Langugae SDK's for most major languages, to use the deployed agents.

As a result you, the developer gets the freedom to:

• Focus on the agent development and avoid repeatative process of implementing REST and Streaming API to use the agents through.
• Use their developed agent in any devlopment environment(Web App, Mobile or Desktop App, Games)
• Build application with cross language response streaming, without even thinking about the complex underlying serialization & deserialization logic.

With RunAgent, you get both a powerful local development environment and a clear path to production-scale serverless deployment. Whether you're building a prototype on your laptop or scaling to millions of users, RunAgent provides the infrastructure and tools to deploy your agents seamlessly.

📖 Table of Contents

• 🎯 What is RunAgent?
• 📖 Table of Contents
  • Why RunAgent?
  • Perfect For
• ✨ Features
• 🚀 QuickStart(Deploying an Agent)
  • 1. Installation
  • 2. Initialize from a template
  • 3. Configure your agent (runagent.config.json)
  • 4. Serve your agent (built-in runagent server)
  • 5. Deploy agent on RunAgent Cloud - Serverless (coming soon)
• 🚀 QuickStart(Use a Deployed Agent)
  • Python SDK
  • Rust SDK
  • JavaScript/ TypeScript SDK
  • Go SDK
• 🌊 Advanced: Streaming Responses
• 🔧 CLI
• 🎨 Framework Support
  • Supported Frameworks
  • Framework Templates
• 🏢 Enterprise Features (Coming Soon)
• 📚 Documentation
  • Getting Started
  • SDK Documentation
  • CLI Documentation
  • Configuration & Deployment
  • API Reference
  • Resources
• 🗺️ Platform Evolution Roadmap
  • ✅ Foundation (Available Now)
  • 🚧 Cloud Platform (Coming Q2 2025)
  • 🔮 Enterprise (Coming 2025)
• 🤝 Contributing
  • Ways to Contribute
  • Development Setup
  • Contribution Guidelines
• 💬 Community & Support
  • Community Channels
  • Getting Help
  • Stay Updated
• 📄 License
• 🙏 Acknowledgments
  • Core Technologies
  • AI Framework Communities
  • Open Source Inspiration
  • Our Community
  • Special Thanks

---

Why RunAgent?

• 🌐 Universal Access: Write agents in Python, use them natively in any language - no API complexity
• 🚀 Deploy in Minutes: From local development to production with a single command
• 🔧 Framework Agnostic: Works with any AI agent framework - LangChain, LangGraph, CrewAI, or custom
• 🌊 Native Streaming: Real-time agent responses that feel natural in every programming language
• 📦 Smart Architecture: Local development today, serverless cloud deployment tomorrow
• 🛡️ Production Ready: Built-in monitoring, logging, and debugging tools included
• 📊 Developer Experience: Intuitive CLI, comprehensive SDKs, and extensive documentation

Perfect For

• Polyglot Teams: Python AI experts collaborating with frontend (JS/TS) and backend (Rust/Go) developers
• Microservices Architecture: Centralized AI logic with distributed access across your service mesh
• Legacy Integration: Add cutting-edge AI capabilities to existing applications without rewrites
• Performance Critical Apps: Write AI logic in Python, consume from high-performance languages
• Rapid Prototyping: Quick local development with seamless production deployment path

✨ Features

SharedCode: Native-feeling SDKs for Python, JavaScript, Rust, and Go with full type safety, intellisense, automatic error handling, and seamless authentication - no more wrestling with REST APIs

UniversalDeploy: Local development server available now with full debugging capabilities, serverless cloud deployment with auto-scaling and global edge distribution coming soon, plus future enterprise options with private cloud and advanced security

StreamingNative: Synchronous and asynchronous clients with language-specific iterators, comprehensive retry logic, and built-in monitoring for complex multi-step agent workflows

CloudScale: Complete agent lifecycle management with smart project initialization, local FastAPI server with hot reload, environment management, and one-command deployment

FrameworkAgnostic: Framework-specific templates, real-time monitoring with logging and metrics, extensive documentation and examples, plus webhook support for event-driven architectures

---

🚀 QuickStart(Deploying an Agent)

RunAgent provides a comprehensive toolset for both deploying agents from any framework and consuming those agents in your applications. The Python SDK is bundled with the CLI, while other language SDKs are available from their respective package repositories.

1. Installation

pip install runagent

Learn more about installation options in our Installation Guide.

2. Initialize from a template

We've created comprehensive templates covering most supported frameworks. These serve as both examples and starting points, and you can initialize them with the runagent init command.

# Framework-specific templates:
runagent init my_agent --langgraph    # LangGraph template
runagent init my_agent --crewai       # CrewAI template
runagent init my_agent --letta        # Letta template
runagent init my_agent --agno         # Agno template

# Create a minimal project:
runagent init my_agent

See all available framework templates in our Frameworks Overview.

If we examine the directory structure:

my-agent/
├── __init__.py
├── email_agent.py
├── main.py
└── runagent.config.json

The most important file in any RunAgent project is runagent.config.json, which contains project metadata and the list of entrypoints - the functions/methods from your codebase that will be exposed through the RunAgent server.

Key Concept: entrypoints are the single most important concept in the RunAgent ecosystem. They define which functions in your code become accessible through our SDKs. Learn more in Core Concepts.

3. Configure your agent (runagent.config.json)

Let's examine the main.py content (partial):

from .email_agent import MockOpenAIClient
from typing import Iterator


def mock_response(message, role="user"):
    """Test the mock agent with non-streaming responses"""
    client = MockOpenAIClient()

    prompt = [
        {
            "role": role,
            "content": message
        }
    ]
    response = client.create(model="gpt-4", messages=prompt)

    print(response.content)
    print(f"\nTokens used: {response.usage_tokens}")
    print(f"Response time: {response.response_time:.2f}s")

    return response.content


def mock_response_stream(message, role="user") -> Iterator[str]:
    """Test the mock agent with streaming responses"""
    client = MockOpenAIClient()
    prompt = [
        {
            "role": role,
            "content": message
        }
    ]
    for chunk in client.create(
        model="gpt-4",
        messages=prompt,
        stream=True
    ):
        if not chunk.finished:
            yield chunk.delta
        else:
            yield "\n[STREAM COMPLETE]"

The functions mock_response and mock_response_stream will serve as agent entrypoints. We specify these in the runagent.config.json file:

{
  "agent_name": "my-agent",
  "description": "A simple placeholder agent",
  "framework": "default",
  "template": "default",
  "version": "1.0.0",
  "created_at": "2025-07-11 15:08:18",
  "template_source": {
    "repo_url": "https://github.com/runagent-dev/runagent.git",
    "author": "sawradip",
    "path": "templates/default"
  },
  "agent_architecture": {
    "entrypoints": [
      {
        "file": "main.py",
        "module": "mock_response",
        "tag": "minimal"
      },
      {
        "file": "main.py",
        "module": "mock_response_stream",
        "tag": "minimal_stream"
      }
    ]
  },
  "env_vars": {}
}

Each entrypoint record specifies:

• file: Relative (or absolute) path to the file containing the entrypoint function
• module: The function name to expose
• tag: Unique identifier for this entrypoint within the project

Important: For streaming entrypoints (like mock_response_stream), the tag should include a _stream suffix to indicate streaming capability.

Learn more about configuration in our Configuration File Guide.

4. Serve your agent (built-in runagent server)

# Start the local development server
runagent serve <project_dir>

# If you're inside the project directory:
runagent serve .

# Using project name also works:
runagent serve my_agent

This command starts a local FastAPI server and provides you with:

• An agent_id for programmatic access
• A host:port URL for HTTP access
• WebSocket endpoints for streaming
• A development dashboard for monitoring

You can use either the agent_id or host:port combination with RunAgentClient from any RunAgent SDK.

See more details in our Local Development Guide.

5. Deploy agent on RunAgent Cloud - Serverless (coming soon)

# Deploy to production cloud infrastructure
runagent deploy <project_dir>

Cloud deployment will provide:

• Automatic scaling based on demand
• Global edge distribution
• Built-in monitoring and analytics
• Webhook integrations
• Production-grade security

Learn more about our upcoming Cloud Deployment features.

🚀 QuickStart(Use a Deployed Agent)

RunAgent provides SDKs for multiple languages, with more being added continuously. If you need support for a specific language or want to contribute, join our Discord or raise an issue.

Remember the agent_id, URL (host:port), and tag from the deployment step. With our SDKs, you can access the entrypoints (defined in runagent.config.json) like native functions - even for streaming responses. We handle all the complex communication in the background.

Python SDK

The Python SDK is already installed when you install the CLI. Let's connect to our agent using the minimal tag, which corresponds to def mock_response(message, role="user"):.

from runagent import RunAgentClient

# Connect using agent_id
ra = RunAgentClient(
    agent_id="<agent_id>",
    entrypoint_tag="<tag>",
    local=True  # You're running a local server
)

# Or connect using host:port
ra = RunAgentClient(
    host="<host>", 
    port=<port>, 
    entrypoint_tag="<tag>", 
    local=True
)

The magic of RunAgent SDKs is that you can invoke the RunAgentClient.run method as if it were the target entrypoint function. Since our function signature is def mock_response(message, role="user"):, you can call:

agent_results = ra.run(
    role="user",
    message="Analyze the benefits of remote work for software teams"
)
print(agent_results)

Complete example:

from runagent import RunAgentClient

ra = RunAgentClient(
    agent_id="<agent_id>",
    entrypoint_tag="<tag>",
    local=True
)

agent_results = ra.run(
    role="user",
    message="Analyze the benefits of remote work for software teams"
)

print(agent_results)

Streaming Support: For streaming functions, you can iterate over the returned object naturally:

from runagent import RunAgentClient

ra = RunAgentClient(
    agent_id="<agent_id>",
    entrypoint_tag="<tag>_stream",  # Note the _stream suffix
    local=True
)

for chunk in ra.run(
    role="user", 
    message="Analyze the benefits of remote work for software teams"
):
    print(chunk, end='')

Learn more in our Python SDK Documentation.

Rust SDK

Non-streaming Example:

use runagent::client::RunAgentClient;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to agent
    let client = RunAgentClient::new("<agent_id>", "<tag>", true).await?;
    
    // Simple invocation with native Rust types
    let result = client.run(&[
        ("message", json!("Help me plan a trip to Japan")),
        ("role", json!("user"))
    ]).await?;
    
    println!("Result: {}", result);
    Ok(())
}

Streaming Example:

use runagent::client::RunAgentClient;
use serde_json::json;
use futures::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Stream responses for real-time interaction
    let client = RunAgentClient::new("<agent_id>", "<tag>_stream", true).await?;
    let mut stream = client.run_stream(&[
        ("message", json!("Explain quantum computing step by step")),
        ("role", json!("user"))
    ]).await?;
    
    while let Some(chunk) = stream.next().await {
        print!("{}", chunk?);
    }
    
    Ok(())
}

JavaScript/ TypeScript SDK

Create an .mjs file or add "type": "module" to your package.json.

Non-streaming Example:

import { RunAgentClient } from 'runagent';

const ra = new RunAgentClient({
  agentId: "<agent_id>",
  host: "<host>",
  port: <port>,
  entrypointTag: "minimal",
  local: true
});

await ra.initialize();

const solutionResult = await ra.run({
  role: 'user',
  message: 'Analyze the benefits of remote work for software teams',
});

console.log(solutionResult);

Streaming Example:

import { RunAgentClient } from 'runagent';

const ra = new RunAgentClient({
  agentId: "<agent_id>",
  host: "<host>",
  port: <port>,
  entrypointTag: "minimal_stream",
  local: true
});

await ra.initialize();

const stream = await ra.run({
  role: 'user',
  message: 'Write a detailed analysis of remote work benefits',
});

for await (const chunk of stream) {
  process.stdout.write(chunk);
}

Go SDK

Non-streaming Example:

package main

import (
 "context"
 "fmt"
 "log"
 "time"

 "github.com/runagent-dev/runagent/runagent-go/runagent"
)

func main() {
 fmt.Println("=== RunAgent Go SDK Example ===")

 config := runagent.Config{
  AgentID:       "<agent_id>",
  EntrypointTag: "minimal",
  Host:          "<host>",
  Port:          <port>,
  Local:         true,
 }

 client := runagent.NewRunAgentClient(config)

 ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
 defer cancel()

 if err := client.Initialize(ctx); err != nil {
  log.Fatalf("Failed to initialize: %v", err)
 }

 result, err := client.Run(ctx, map[string]interface{}{
  "role":    "user",
  "message": "Analyze the benefits of remote work for software teams",
 })
 if err != nil {
  log.Fatalf("Failed to run agent: %v", err)
 }

 fmt.Printf("Result: %v\n", result)
}

Streaming Example:

package main

import (
 "context"
 "fmt"
 "log"
 "time"

 "github.com/runagent-dev/runagent/runagent-go/runagent"
)

func main() {
 fmt.Println("=== Streaming Agent Example ===")

 client := runagent.NewRunAgentClient(runagent.Config{
  AgentID:       "<agent_id>",
  EntrypointTag: "minimal_stream",
  Host:          "<host>",
  Port:          <port>,
  Local:         true,
 })

 ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
 defer cancel()

 if err := client.Initialize(ctx); err != nil {
  log.Fatalf("Failed to initialize: %v", err)
 }

 result, err := client.Run(ctx, map[string]interface{}{
  "role":    "user",
  "message": "Write a detailed analysis of remote work benefits",
 })
 if err != nil {
  log.Fatalf("Failed to start streaming: %v", err)
 }

 stream := result.(*runagent.StreamIterator)
 defer stream.Close()

 fmt.Println("📡 Streaming response:")
 fmt.Println("----------------------------------------")

 for {
  chunk, hasMore, err := stream.Next(ctx)
  if err != nil {
   log.Printf("Stream error: %v", err)
   break
  }
  if !hasMore {
   break
  }
  if chunk != nil {
   fmt.Print(chunk)
  }
 }

 fmt.Println("\n✅ Stream completed!")
}

---

🌊 Advanced: Streaming Responses

One of RunAgent's most powerful features is native streaming support across all languages. Streaming responses feel natural and idiomatic in each programming language:

Python - Uses Python iterators:

for chunk in client.run(message="Generate a long story"):
    print(chunk, end='')

JavaScript - Uses async iterators:

for await (const chunk of client.run({message: "Generate a long story"})) {
    process.stdout.write(chunk);
}

Rust - Uses futures streams:

while let Some(chunk) = stream.next().await {
    print!("{}", chunk?);
}

Go - Uses context-aware iterators:

for {
    chunk, hasMore, err := stream.Next(ctx)
    if !hasMore { break }
    fmt.Print(chunk)
}

Learn more about streaming in our Streaming Responses Guide.

---

🔧 CLI

The RunAgent CLI is your command center for agent operations. Here's the complete reference:

Command	Description	Documentation
runagent init	Create a new agent project from templates	CLI Reference
runagent serve	Run agent locally for development	CLI Reference
runagent deploy	Deploy to cloud (coming soon)	CLI Reference
runagent run	Execute a deployed agent	CLI Reference
runagent setup	Configure authentication	CLI Reference
runagent template	Manage project templates	CLI Reference
runagent upload	Upload agent to remote server	CLI Reference
runagent start	Start an uploaded agent	CLI Reference
runagent teardown	Remove RunAgent configuration	CLI Reference

See our CLI Overview and CLI Examples for comprehensive usage patterns.

🎨 Framework Support

RunAgent works with any Python AI framework. We provide pre-built templates and specific guides for popular frameworks:

Supported Frameworks

• LangGraph - Deploy LangGraph agents with full graph support
• CrewAI - Deploy multi-agent CrewAI systems
• Letta - Deploy Letta agents with long-term memory
• Agno - Deploy Agno agents with built-in reasoning
• Custom Frameworks - Deploy agents built with any Python framework

Framework Templates

runagent init my-agent --langgraph    # LangGraph template
runagent init my-agent --crewai       # CrewAI multi-agent template  
runagent init my-agent --letta        # Letta memory-enabled template
runagent init my-agent --agno         # Agno reasoning template
runagent init my-agent --custom       # Custom framework template

See our Frameworks Overview for detailed guides on each framework.

🏢 Enterprise Features (Coming Soon)

RunAgent's enterprise tier will provide production-grade features for organizations:

• Private Cloud Deployment: Run RunAgent in your own infrastructure
• Advanced Security: SOC2 compliance, encryption at rest and in transit
• Team Collaboration: Shared agents, role-based access control, audit logs
• Custom Domains: Deploy agents to your own domains with SSL
• SLA Support: 99.9% uptime guarantee with dedicated support
• Advanced Monitoring: Custom dashboards, alerts, and analytics
• Compliance: GDPR, HIPAA, and industry-specific compliance features

---

📚 Documentation

Our comprehensive documentation covers every aspect of RunAgent development and deployment:

Getting Started

• Introduction - Deploy AI agents to production in seconds
• Installation - Install RunAgent CLI and SDK
• Quick Start - Deploy your first agent in under 5 minutes
• Core Concepts - Master fundamental RunAgent concepts

SDK Documentation

• SDK Overview - Overview of all RunAgent SDKs
• Python SDK - Complete Python SDK guide
  • API Reference - Complete API documentation
  • Synchronous Client - Using sync clients
  • Asynchronous Client - Using async clients
  • Streaming Responses - Real-time streaming
• Coming Soon: Additional SDKs - JavaScript, Rust, Go SDKs

CLI Documentation

• CLI Overview - Master the command-line interface
• CLI Examples - Common usage patterns
• Command References: init, serve, deploy, run, setup, template, upload, start, teardown

Configuration & Deployment

• Configuration File - Understanding runagent.config.json
• Project Structure - Understanding RunAgent project organization
• Environment Variables - Managing environment variables and secrets
• Local Development - Running and testing agents locally
• Cloud Deployment - Deploy to RunAgent cloud infrastructure

API Reference

• API Introduction - RESTful API for interacting with RunAgent
• Authentication - API authentication and security
• Rate Limits - API rate limiting and quotas
• Error Handling - Understanding and handling API errors
• Endpoints: Health Check, Invoke Agent, Stream Agent Response
• Webhooks - Receive real-time notifications for agent events

Resources

• Examples - Example agents and code snippets
• Troubleshooting Guide - Common issues and solutions
• Frequently Asked Questions - Common questions about RunAgent

🗺️ Platform Evolution Roadmap

✅ Foundation (Available Now)

Our current open-source foundation provides everything you need for local development and self-hosting:

• Cross-Language SDKs: Python, JavaScript, Rust, and Go SDKs with native streaming
• Local Development Server: Full-featured FastAPI server with hot reload
• Framework-Agnostic Support: Works with LangChain, LangGraph, CrewAI, Letta, Agno, or any Python framework
• Pre-Built Templates: Quick-start templates for popular AI frameworks
• Comprehensive CLI: Complete command-line interface for project management
• Real-Time Debugging: Built-in logging, monitoring, and debugging tools
• Production-Ready: Suitable for self-hosting and enterprise deployments

🚧 Cloud Platform (Coming Q2 2025)

Our serverless cloud platform will provide effortless scaling and production deployment:

• One-Command Deployment: Deploy with runagent deploy to auto-scaling infrastructure
• Global Edge Network: Deploy agents across multiple regions for minimal latency
• Auto-Scaling: Scale from zero to thousands of concurrent requests automatically
• Built-in Monitoring: Real-time dashboards, metrics, and alerting
• Webhook Integrations: Event-driven architectures with HTTP callbacks
• Team Collaboration: Shared agents, environment management, and access controls
• Usage Analytics: Detailed insights into agent performance and usage patterns
• API Gateway: Advanced routing, rate limiting, and authentication features

🔮 Enterprise (Coming 2025)

Enterprise features for organizations requiring advanced security and control:

• Private Cloud Deployment: Run RunAgent in your own infrastructure (AWS, GCP, Azure)
• Advanced Security: SOC2 Type II compliance, encryption at rest and in transit
• Compliance Features: GDPR, HIPAA, and industry-specific compliance tools
• Role-Based Access Control: Fine-grained permissions and audit logging
• Custom SLAs: 99.9% uptime guarantees with dedicated support
• Custom Runtime Environments: Specialized containers and security sandboxes
• Enterprise Integrations: SSO, LDAP, and enterprise directory services
• Advanced Analytics: Custom reporting, data export, and business intelligence

---

🤝 Contributing

We welcome contributions from the community! RunAgent is built by developers, for developers, and we're excited to have you join us.

Ways to Contribute

• Bug Reports: Found an issue? Report it on GitHub Issues
• Feature Requests: Have an idea? Share it in GitHub Discussions
• Code Contributions: Submit pull requests for bug fixes or new features
• Documentation: Help improve our guides, examples, and API documentation
• Community Support: Help other developers in Discord and GitHub discussions
• SDK Development: Contribute to existing SDKs or help build new language support

Development Setup

# Clone the repository
git clone https://github.com/runagent-dev/runagent.git
cd runagent

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black runagent tests

# Run linting
flake8 runagent tests

# Type checking
mypy runagent

Contribution Guidelines

• Follow our Code of Conduct
• Write tests for new features and bug fixes
• Follow existing code style and conventions
• Update documentation for any user-facing changes
• Add appropriate type hints for Python code

See our detailed Contributing Guide for more information.

💬 Community & Support

Join our growing community of AI developers and get support from both the team and fellow users:

Community Channels

• Discord Community - Real-time chat with developers, get help, and share projects
• GitHub Discussions - Ask questions, share ideas, and discuss features
• Twitter - Follow for updates, announcements, and AI development tips
• Blog - In-depth tutorials, best practices, and case studies

Getting Help

• Technical Issues: Check our Troubleshooting Guide first
• General Questions: Browse our FAQ
• Community Support: Ask in Discord or GitHub Discussions
• Bug Reports: Create an issue on GitHub with detailed reproduction steps

Stay Updated

• GitHub Releases: Watch our repository for new releases and features
• Newsletter: Subscribe on our website for monthly updates and tutorials
• Social Media: Follow us on Twitter for daily updates and community highlights

📄 License

RunAgent is licensed under the Elastic License 2.0 (ELv2). What this means:

✅ Free to use for development, testing, and production
✅ Modify and distribute as needed
✅ Commercial use in your applications
❌ Cannot offer RunAgent as a managed service without permission

This license ensures RunAgent remains freely available while protecting against unfair competition from cloud providers. See the LICENSE file for complete terms.

🙏 Acknowledgments

RunAgent stands on the shoulders of giants. We're grateful to the entire AI and open-source community, especially:

Core Technologies

• FastAPI - For the blazingly fast API framework that powers our local server
• Pydantic - For data validation and serialization
• Uvicorn - For the lightning-fast ASGI server

AI Framework Communities

• LangChain and LangGraph - For pioneering AI agent frameworks
• LlamaIndex - For advancing RAG and knowledge-based AI systems
• CrewAI - For multi-agent system innovations
• Letta - For advancing memory-enabled conversational AI

Open Source Inspiration

• Vercel - For inspiration in developer experience and deployment simplicity
• Supabase - For demonstrating the power of open-source alternatives
• Hugging Face - For democratizing AI and fostering community

Our Community

• Contributors - Everyone who has submitted code, documentation, or bug reports
• Early Adopters - Beta users who provided feedback and shaped our roadmap
• Discord Community - Active members who help each other and improve RunAgent
• Framework Maintainers - Teams behind the AI frameworks we support

Special Thanks

• All the developers building amazing AI applications with RunAgent
• The broader Python and AI communities for continuous innovation
• Everyone who believes in making AI development more accessible

---

Ready to build universal AI agents?

🌟 Star us on GitHub • 💬 Join Discord • 📚 Read the Docs

Made with ❤️ by the RunAgent Team