The runagent.config.json file is the heart of your RunAgent project. It defines how your agent is configured, deployed, and executed.

​
Basic Structure

{
  "agent_name": "problem_solver",
  "description": "A simple agent that responds to basic queries",
  "framework": "langgraph",
  "template": "problem_solver",
  "version": "1.0.0",
  "created_at": "2025-06-25 13:42:03",
  "template_source": {
    "repo_url": "https://github.com/runagent-dev/runagent.git",
    "path": "templates/langgraph/problem_solver",
    "author": "sawradip"
  },
  "agent_architecture": {
    "entrypoints": [
      {
        "file": "agents.py",
        "module": "app.invoke",
        "type": "generic"
      },
      {
        "file": "agents.py",
        "module": "app.stream",
        "type": "generic_stream"
      }
    ]
  },
  "env_vars": {
    "OPENAI_API_KEY": "${OPENAI_API_KEY}",
    "CUSTOM_VAR": "fixed_value"
  }
}

​
Configuration Fields

​
Core Fields

​
agent_name
string
required

Unique identifier for your agent. Used in deployment and SDK initialization.

  • Must be lowercase
  • Can contain letters, numbers, hyphens, and underscores
  • Maximum 50 characters
​
description
string

Human-readable description of what your agent does. Displayed in dashboards and listings.

​
framework
string
required

The AI framework your agent uses. Supported values:

  • langgraph
  • crewai
  • agno
  • letta
  • custom
​
version
string
required

Semantic version of your agent. Follow SemVer format.

​
Template Information

​
template
string

Name of the template used to create this project. Helps with updates and migration.

​
template_source
object

Source information for the template:

​
Agent Architecture

​
agent_architecture
object
required

Defines how RunAgent interacts with your code:

​
Environment Variables

​
env_vars
object

Environment variables for your agent. Supports two formats:

  1. Dynamic substitution: "${VAR_NAME}" - Reads from environment
  2. Fixed values: "fixed_value" - Uses the literal value

Never hardcode sensitive values like API keys. Always use dynamic substitution.

​
Entrypoint Types

​
Generic Entrypoint

Standard request/response pattern:

# agents.py
def invoke(input_data: dict) -> dict:
    """Process input and return result"""
    query = input_data.get("query")
    # Process the query
    return {"result": "processed result"}

app = {"invoke": invoke}

Configuration:

{
  "file": "agents.py",
  "module": "app.invoke",
  "type": "generic"
}

​
Streaming Entrypoint

For real-time response streaming:

# agents.py
def stream(input_data: dict):
    """Generator that yields chunks"""
    query = input_data.get("query")
    for chunk in process_streaming(query):
        yield chunk

app = {"stream": stream}

Configuration:

{
  "file": "agents.py",
  "module": "app.stream",
  "type": "generic_stream"
}

​
Advanced Configuration

​
Multiple Entrypoints

You can define multiple entrypoints for different use cases:

{
  "agent_architecture": {
    "entrypoints": [
      {
        "file": "agents.py",
        "module": "app.chat",
        "type": "generic"
      },
      {
        "file": "agents.py",
        "module": "app.analyze",
        "type": "generic"
      },
      {
        "file": "streaming.py",
        "module": "streamer.process",
        "type": "generic_stream"
      }
    ]
  }
}

​
Environment Variable Patterns

{
  "env_vars": {
    // Dynamic from environment
    "OPENAI_API_KEY": "${OPENAI_API_KEY}",
    
    // Fixed value
    "MODEL_NAME": "gpt-4",
    
    // With default fallback (coming soon)
    "TEMPERATURE": "${TEMPERATURE:-0.7}",
    
    // Complex values
    "CONFIG_JSON": "${CONFIG_JSON}"
  }
}

​
Validation

RunAgent validates your configuration on:

  • runagent init - When creating a project
  • runagent serve - Before starting local server
  • runagent deploy - Before deployment

Common validation errors:

​
Best Practices

Use Semantic Versioning

Follow SemVer for your version numbers to track changes properly

Document Entrypoints

Add comments in your code explaining what each entrypoint does

Environment Variables

Never hardcode secrets. Always use environment variable substitution

Validate Locally

Test your configuration with runagent serve before deploying

​
Example Configurations

{
  "agent_name": "customer_support",
  "description": "AI customer support agent",
  "framework": "langgraph",
  "version": "2.1.0",
  "agent_architecture": {
    "entrypoints": [
      {
        "file": "support_agent.py",
        "module": "agent.handle_query",
        "type": "generic"
      },
      {
        "file": "support_agent.py",
        "module": "agent.chat_stream",
        "type": "generic_stream"
      }
    ]
  },
  "env_vars": {
    "OPENAI_API_KEY": "${OPENAI_API_KEY}",
    "SUPPORT_DB_URL": "${DATABASE_URL}",
    "MAX_TOKENS": "2000"
  }
}