Overview
A well-organized project structure is key to maintainable and deployable AI agents. This guide covers the standard RunAgent project layout and best practices.
Basic Structure
my-agent/
├── agent.py # Main agent implementation
├── runagent.config.json # RunAgent configuration
├── requirements.txt # Python dependencies
├── .env # Environment variables (local only)
├── .env.example # Example environment template
├── .gitignore # Git ignore rules
├── README.md # Project documentation
└── tests/ # Unit tests (optional)
Core Files
agent.py
Your main agent implementation:
# agent.py
def invoke(input_data: dict) -> dict:
"""Main entrypoint for request/response"""
# Your agent logic
return {"response": processed_result}
def stream(input_data: dict):
"""Optional streaming entrypoint"""
for chunk in process_streaming(input_data):
yield chunk
runagent.config.json
Configuration file that tells RunAgent how to run your agent:
{
"agent_name": "my-agent",
"framework": "langgraph",
"version": "1.0.0",
"agent_architecture": {
"entrypoints": [
{
"file": "agent.py",
"module": "invoke",
"type": "generic"
}
]
}
}
requirements.txt
All Python dependencies:
openai>=1.0.0
langchain>=0.1.0
python-dotenv>=1.0.0
# Your other dependencies
Advanced Structure
For larger projects:
my-agent/
├── src/
│ ├── __init__.py
│ ├── agent.py # Main agent
│ ├── models.py # Data models
│ ├── tools.py # Agent tools
│ └── utils.py # Utilities
├── prompts/
│ ├── system.txt # System prompts
│ └── templates.py # Prompt templates
├── config/
│ ├── development.json # Dev config
│ └── production.json # Prod config
├── tests/
│ ├── test_agent.py
│ └── test_tools.py
├── docs/
│ └── API.md
├── runagent.config.json
├── requirements.txt
├── requirements-dev.txt # Dev dependencies
├── Makefile # Common commands
└── README.md
Framework-Specific Structures
LangGraph Projects
langgraph-agent/
├── agents.py # Graph definition
├── nodes/ # Graph nodes
│ ├── __init__.py
│ ├── process.py
│ └── analyze.py
├── edges.py # Edge logic
├── state.py # State schema
├── tools.py # Custom tools
└── runagent.config.json
CrewAI Projects
crewai-project/
├── crew.py # Crew definition
├── agents/ # Individual agents
│ ├── researcher.py
│ ├── writer.py
│ └── reviewer.py
├── tasks/ # Task definitions
│ └── tasks.py
├── tools/ # Shared tools
└── runagent.config.json
File Organization Best Practices
1. Separate Concerns
# Good: Separated modules
# models.py
class InputModel:
pass
# tools.py
def search_tool():
pass
# agent.py
from models import InputModel
from tools import search_tool
2. Configuration Management
# config.py
import os
from typing import Dict
def get_config() -> Dict:
env = os.getenv("ENVIRONMENT", "development")
configs = {
"development": {
"debug": True,
"timeout": 60
},
"production": {
"debug": False,
"timeout": 30
}
}
return configs[env]
3. Modular Entrypoints
# entrypoints.py
from src.agent import Agent
agent = Agent()
def invoke(input_data: dict) -> dict:
return agent.process(input_data)
def stream(input_data: dict):
yield from agent.stream(input_data)
Environment Management
Development
.env file (never commit):
OPENAI_API_KEY=sk-...
DATABASE_URL=postgresql://...
DEBUG=true
Production
Use RunAgent’s environment variable management:
{
"env_vars": {
"OPENAI_API_KEY": "${OPENAI_API_KEY}",
"DATABASE_URL": "${DATABASE_URL}",
"DEBUG": "false"
}
}
Testing Structure
tests/
├── conftest.py # Pytest configuration
├── fixtures/ # Test data
│ └── sample_input.json
├── unit/ # Unit tests
│ ├── test_agent.py
│ └── test_tools.py
└── integration/ # Integration tests
└── test_api.py
Deployment Files
.gitignore
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
venv/
env/
# Environment
.env
.env.local
# IDE
.vscode/
.idea/
*.swp
# OS
.DS_Store
Thumbs.db
# RunAgent
.runagent/
logs/
Makefile
.PHONY: install test run deploy
install:
pip install -r requirements.txt
test:
pytest tests/
run:
runagent serve .
deploy:
runagent deploy .
clean:
find . -type d -name "__pycache__" -exec rm -rf {} +
find . -type f -name "*.pyc" -delete
See Also
