​
Overview

RunAgent is built on several core concepts that make it powerful yet simple to use. Understanding these concepts will help you build better agents and use the platform effectively.

​
Agents

An agent in RunAgent is a deployable AI application that:

  • Processes inputs and returns outputs
  • Can use tools and external APIs
  • Maintains state across interactions
  • Runs in a secure, isolated environment

​
Agent Lifecycle

1

Development

Write and test your agent code locally

2

Configuration

Define how RunAgent should interact with your code

3

Deployment

Upload and run your agent on RunAgent infrastructure

4

Execution

Invoke your agent via API, SDK, or CLI

​
Entrypoints

Entrypoints are the functions RunAgent calls to interact with your agent:

# Example entrypoint
def process_request(input_data: dict) -> dict:
    # Your agent logic here
    return {"result": "processed"}

​
Types of Entrypoints

TypePurposeInputOutput
genericStandard request/responseDictDict
generic_streamStreaming responsesDictGenerator[str]
asyncAsynchronous processingDictAwaitable[Dict]
batchBatch processingList[Dict]List[Dict]

​
Configuration

The runagent.config.json file is the contract between your code and RunAgent:

{
  "agent_name": "my-agent",
  "framework": "langgraph",
  "agent_architecture": {
    "entrypoints": [
      {
        "file": "agent.py",
        "module": "app.invoke",
        "type": "generic"
      }
    ]
  }
}

​
Key Configuration Elements

Agent Metadata

Name, version, description, and framework

Entrypoints

How RunAgent calls your code

Environment

Variables and secrets management

Resources

Memory, CPU, and timeout settings

​
Frameworks

RunAgent supports multiple AI frameworks:

from langgraph import StateGraph

# Your LangGraph agent
app = StateGraph(...)

​
Execution Modes

​
Local Development

runagent serve .
  • Runs on your machine
  • Hot reload support
  • Direct access to logs
  • Perfect for testing

​
Production Deployment

runagent deploy .
  • Runs on RunAgent infrastructure
  • Automatic scaling
  • Monitoring and logging
  • High availability

​
Security Model

​
Data Flow

Understanding how data flows through RunAgent:

​
Best Practices

​
Agent Design

  1. Stateless when possible: Design agents to be stateless for better scaling
  2. Idempotent operations: Same input should produce same output
  3. Error handling: Always handle and return meaningful errors
  4. Timeout awareness: Respect execution time limits

​
Resource Usage

# Good: Efficient processing
def process(data):
    # Process only what's needed
    result = quick_operation(data)
    return result

# Bad: Resource intensive
def process(data):
    # Loading large models repeatedly
    model = load_huge_model()  # ❌
    return model.process(data)

​
Security

  • Never hardcode secrets
  • Validate all inputs
  • Sanitize outputs
  • Use least privilege principle

​
Common Patterns

​
Request-Response Pattern

def handle_request(input_data: dict) -> dict:
    try:
        # Validate input
        validate_input(input_data)
        
        # Process
        result = process_data(input_data)
        
        # Return structured response
        return {
            "status": "success",
            "data": result
        }
    except Exception as e:
        return {
            "status": "error",
            "message": str(e)
        }

​
Streaming Pattern

def stream_response(input_data: dict):
    # Initial processing
    context = prepare_context(input_data)
    
    # Stream chunks
    for chunk in generate_response(context):
        yield chunk

​
Tool Usage Pattern

class AgentWithTools:
    def __init__(self):
        self.tools = {
            "search": self.search_tool,
            "calculate": self.calculate_tool
        }
    
    def process(self, input_data: dict) -> dict:
        tool_name = input_data.get("tool")
        if tool_name in self.tools:
            return self.tools[tool_name](input_data)

​
Next Steps

Now that you understand the core concepts:

Build Your First Agent

Create a custom agent from scratch

Explore CLI

Master the command-line interface