Configuration File

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

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

string

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

string

required

The AI framework your agent uses. Supported values:

langgraph
crewai
agno
letta
custom

string

required

Semantic version of your agent. Follow SemVer format.

Template Information

string

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

object

Source information for the template:

Show properties

string

Git repository URL containing the template

string

Path within the repository to the template

string

Template author’s identifier

Agent Architecture

object

required

Defines how RunAgent interacts with your code:

Show properties

array

required

List of entrypoint configurations. Each entrypoint defines a way to invoke your agent.

Show entrypoint object

string

required

Python file containing the entrypoint

string

required

Dot-notation path to the callable object (e.g., app.invoke)

string

required

Type of entrypoint. Supported values:

generic - Standard request/response
generic_stream - Streaming responses
async - Asynchronous invocation
batch - Batch processing

Environment Variables

object

Environment variables for your agent. Supports two formats:

Dynamic substitution: "${VAR_NAME}" - Reads from environment
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:

Missing required fields

Ensure all required fields (agent_name, framework, version, agent_architecture) are present.

Invalid entrypoint module

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)"

Unsupported framework

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

LangGraph Agent
CrewAI Agent

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

{
  "agent_name": "research_crew",
  "description": "Multi-agent research system",
  "framework": "crewai",
  "version": "1.0.0",
  "agent_architecture": {
    "entrypoints": [
      {
        "file": "crew.py",
        "module": "research_crew.kickoff",
        "type": "generic"
      }
    ]
  },
  "env_vars": {
    "OPENAI_API_KEY": "${OPENAI_API_KEY}",
    "SERPER_API_KEY": "${SERPER_API_KEY}"
  }
}

Reference

API Reference

SDK Reference

CLI Reference

Configuration

Configuration File

Basic Structure

Configuration Fields

Core Fields

Template Information

Agent Architecture

Environment Variables

Entrypoint Types

Generic Entrypoint

Streaming Entrypoint

Advanced Configuration

Multiple Entrypoints

Environment Variable Patterns

Validation

Best Practices

Use Semantic Versioning

Document Entrypoints

Environment Variables

Validate Locally

Example Configurations

​Basic Structure

​Configuration Fields

​Core Fields

​Template Information

​Agent Architecture

​Environment Variables

​Entrypoint Types

​Generic Entrypoint

​Streaming Entrypoint

​Advanced Configuration

​Multiple Entrypoints

​Environment Variable Patterns

​Validation

​Best Practices

Use Semantic Versioning

Document Entrypoints

Environment Variables

Validate Locally

​Example Configurations

Basic Structure

Configuration Fields

Core Fields

Template Information

Agent Architecture

Environment Variables

Entrypoint Types

Generic Entrypoint

Streaming Entrypoint

Advanced Configuration

Multiple Entrypoints

Environment Variable Patterns

Validation

Best Practices

Example Configurations