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:
Ensure all required fields (agent_name, framework, version, agent_architecture) are present.
Check that the module path is correct and the file exists.
# Verify the module can be imported
python -c "from agents import app; print(app.invoke)"
Use one of the supported frameworks or "custom" for others.

​
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"
  }
}