An experimental agentic framework that replaces traditional tool-calling with skills (subagents). Built for developers who want more control, lower costs, and better workflows.
skillgraph reimagines how AI agents work by introducing Skills - autonomous subagents that handle specific tasks end-to-end, rather than exposing low-level tool functions to a primary agent.
Traditional approach: Agent receives tools → plans execution → calls tools → combines results
skillgraph approach: Agent receives skills → delegates to appropriate skill → skill handles everything
This architecture reduces token waste, improves reliability, and enables complex multi-turn workflows that are difficult to implement with traditional tool-calling frameworks.
Replaces complex RAG systems with efficient state tracking:
- Subject: User goals, constraints, and preferences (accumulated over conversation)
- Object: Current topic being discussed (type, attributes, cached data)
- Uses fast Utility LLM (Llama-3-8B, ~200ms) for analysis
- Fallback chain: Utility LLM → Gamma LLM → Previous state (graceful degradation)
Intelligent caching that reduces costs by up to 89%:
- Caches static system prompt (shared across all conversations)
- Avoids caching conversation-specific data (no reuse = wasted cost)
- Important: Due to minimum token requirements, caching only works with Sonnet 4.5 (alpha model)
- Haiku 4.5 requires 4,096 tokens minimum
- Current system prompt is ~1,248 tokens (below Haiku's threshold)
- Sonnet 4.5 requires only 1,024 tokens minimum
- Conversation history cached in Redis for sub-5ms retrieval
- Auto-invalidation on new messages
- Fallback to PostgreSQL on cache miss
- 10x faster than database-only approach
Graceful degradation for high availability:
- Primary: Beta (Haiku 4.5) for medium complexity
- Fallback: Alpha (Sonnet 4.5) if Beta fails
- Retry: Alpha retry for transient failures
- Error: Only if all attempts fail
Context compression for unbounded conversations:
- Triggered every 10 messages for "detailed" conversations
- Incremental summarization (summary of summary)
- Enables indefinite conversation length without context limit issues
Semantic search for past messages using pgvector:
- Retrieves relevant context from earlier in conversation
- Security scoped to current conversation only
- Enables "what did you mention earlier" type queries
Automatic conversation type detection:
- Detailed: Complex research queries (full features enabled)
- Lightweight: Quick Q&A (minimal overhead)
- Auto-upgrades from lightweight to detailed as complexity increases
- Anthropic (Claude)
- OpenAI (GPT)
- AWS Bedrock
- Azure OpenAI
- DeepSeek
- Together AI
- HuggingFace
Multi-layer content moderation system:
- Layer 1: Optional keyword blocklist (instant)
- Layer 2: OpenAI Moderation API (~200ms, free)
- Layer 3: LLM built-in refusals (automatic)
- Configurable fail-open/fail-closed modes
- Basic agent operations (chat, streaming)
- Skills system (creation, routing, execution)
- Interactive skills (multi-turn workflows)
- Dual-layer caching (Anthropic + Redis)
- Conversation intelligence (Subject-Object tracking, strategy selection, summarization)
- Vector search with pgvector
- LLM fallback chain for reliability
- Learning system (feedback collection, skill improvement)
- Security guardrails (rate limiting, SQL injection detection, content moderation)
- React frontend with skill result rendering
- Message planning
- Multi-message streaming
- Parallel skill execution
- Learning engine improvement loop
- Prometheus + Grafana integration
- Comprehensive testing at scale
- Extended documentation
- Kubernetes deployment configurations
- Python 3.12+
- PostgreSQL with pgvector extension
- Redis (recommended for production)
- API key from Anthropic, OpenAI, or other supported provider
# Clone repository
git clone https://github.com/tejassudsfp/skillgraph-backend.git
cd skillgraph-backend
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Configure environment
cp .env.example .env
# Edit .env with your API keys and database URLs# Start services (Docker)
docker-compose up -d
# Run migrations
python -m alembic upgrade headfrom skillgraph import Agent
# Initialize agent
agent = Agent(config_path="agent.config.yml")
await agent.initialize()
# Basic chat
response = await agent.chat(
user_id="user_123",
message="What's the weather in Paris?",
)
print(response)
# Streaming responses
async for chunk in agent.stream(
user_id="user_123",
message="Tell me about quantum computing",
):
print(chunk, end="", flush=True)python run_api.pyAPI will be available at http://localhost:8000
- Documentation:
http://localhost:8000/docs - Health check:
http://localhost:8000/health
The frontend is available in a separate repository:
# Clone frontend repository
git clone https://github.com/tejassudsfp/skillgraph-frontend.git
cd skillgraph-frontend
# Install and run
npm install
npm run devFrontend will be available at http://localhost:3000
Skills are autonomous agents that handle specific domains:
from skillgraph import BaseSkill
class WeatherSkill(BaseSkill):
name = "weather"
description = "Get weather information for any city"
async def execute(self, query: str, context: dict, llm, tools: dict):
city = self._extract_city(query)
weather_data = await tools["get_weather"](city)
return {
"success": True,
"data": weather_data,
"message": f"Weather in {city}: {weather_data['temp']}°C"
}Skills can:
- Use multiple tools internally
- Make autonomous decisions
- Handle errors gracefully
- Maintain their own prompts
- Support multi-turn interactions
For workflows requiring multiple conversation turns:
class TicketBookingSkill(BaseSkill):
name = "ticket_booking"
interactive = True
async def should_enter_skill_mode(self, query: str, context: dict) -> bool:
return "book" in query.lower() and "ticket" in query.lower()
async def handle_skill_turn(self, user_input: str, state: dict, context: dict):
if state["step"] == "confirm":
return {"prompt": "Confirm booking?", "render": {...}}
elif state["step"] == "payment":
return {"prompt": "Payment method?", "render": {...}}Low-level functions used by skills:
from skillgraph import tool
@tool(name="get_weather", description="Get current weather")
async def get_weather(city: str) -> dict:
# Call weather API
return {"temp": 20, "condition": "Sunny"}Key distinction: Agents delegate to skills; skills orchestrate tools.
Create agent.config.yml:
models:
alpha:
provider: anthropic
model: claude-sonnet-4-5-20250929
api_source: direct
max_tokens: 4096
temperature: 0.7
supports_caching: true
beta:
provider: anthropic
model: claude-haiku-4-5-20251001
api_source: direct
max_tokens: 4096
temperature: 0.7
database:
url: postgresql+asyncpg://user:pass@localhost:5432/skillgraph
cache:
enabled: true
provider: redis
redis_url: redis://localhost:6379/0
content_safety:
enabled: true
use_openai_moderation: true
openai_api_key: ${API_KEY_OPENAI}
fail_open: true┌─────────────────────────────────────────────────────────┐
│ Agent │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Skill Router │ │ Conversation │ │ Caching │ │
│ │ │ │ Manager │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Skills (Subagents) │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ Weather │ │ Booking │ │ Search │ ... │
│ │ Skill │ │ Skill │ │ Skill │ │
│ └────────────┘ └────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Tools │
│ [get_weather] [search_web] [calculate] [send_email] │
└─────────────────────────────────────────────────────────┘
user: "What's the weather in Paris and send me an email about it?"
# Agent reasoning:
# 1. Which tools are needed? (token intensive)
# 2. In what order? (more tokens)
# 3. How to combine results? (even more tokens)
# 4. Calls get_weather("Paris")
# 5. Calls send_email(subject="...", body="...")Limitations:
- Excessive token usage on planning
- Limited error recovery
- No native multi-turn workflow support
- Difficult to control agent behavior
user: "What's the weather in Paris and send me an email about it?"
# Agent reasoning:
# 1. Route to WeatherSkill and EmailSkill (minimal tokens)
# 2. Delegate execution
# WeatherSkill handles:
# - Weather retrieval
# - Error handling
# - Response formatting
# - Internal tool usage
# EmailSkill handles:
# - Email logic
# - Input validation
# - Sending
# - Internal tool usageBenefits:
- Reduced token consumption (delegation vs planning)
- Robust error handling (skill-level)
- Native multi-turn workflow support
- Enhanced control through skill-level business logic
Token usage reduction through skill-based architecture:
- Agent performs routing only (minimal tokens)
- Skills handle execution logic internally
- Reduced LLM calls overall
Anthropic prompt caching (when enabled) provides additional 89% savings on system prompt tokens.
- Simple queries: < 200ms
- Complex queries with skills: 500ms - 2s
- Interactive skills: < 300ms per turn
- Cached responses: < 50ms
- Async-first architecture
- Supports 1000+ concurrent requests
- PostgreSQL + Redis for optimized data retrieval
See deployment/RENDER_DEPLOYMENT.md for detailed instructions.
Key benefits:
- No timeout limits (ideal for LLM operations)
- Free PostgreSQL and Redis
- Auto-deploy from GitHub
- HTTPS/SSL included
docker-compose up -dpython run_api.py- How It Works - Complete system architecture walkthrough
- Content Safety - Content moderation guide
- Deployment Guide - Production deployment instructions
- Backend: skillgraph-backend (this repository)
- Frontend: skillgraph-frontend - React chat UI with skill result rendering
Contributions are welcome. Please:
- File issues for bugs
- Open discussions for feature ideas
- Submit pull requests with clear descriptions
- Follow existing code style
No formal contribution guidelines yet - use common sense and write clean code.
Apache 2.0 - See LICENSE for details.
Tejas Parthasarathi Sudarshan
- GitHub: @tejassudsfp
- Email: t@fanpit.live
Built with inspiration from the open-source AI community and a belief that agent architectures can be fundamentally improved.
Special thanks to everyone building open-source AI tools and providing feedback on early versions.
Note: This is an experimental framework. While functional, it has not been battle-tested at large scale. Use in production at your own discretion.