SubQL GraphQL Agent

A TypeScript/Node.js GraphQL agent for SubQuery Network that uses LangChain and OpenAI to query GraphQL endpoints intelligently with natural language.

Overview

This toolkit provides LLM agents with the ability to interact with any GraphQL API built with SubQuery SDK through natural language, automatically understanding schemas, validating queries, and executing complex GraphQL operations.

Key Features

• Natural Language Interface: Ask questions about blockchain data in plain English
• Automatic Schema Understanding: Agents learn PostGraphile v4 patterns and SubQuery entity schemas
• Query Generation & Validation: Converts natural language to valid GraphQL queries with built-in validation
• SubQuery SDK Optimized: Works with any project built using SubQuery SDK (Ethereum, Polkadot, Cosmos, etc.)

Design Philosophy

Solving the GraphQL Schema Size Problem

Traditional GraphQL agents face a fundamental challenge: schema size exceeds LLM context limits. Most GraphQL APIs have introspection schemas that are tens of thousands of tokens, making them:

• Too large for most commercial LLMs (exceeding context windows)
• Too expensive for cost-effective query generation
• Too noisy for reliable query construction (low signal-to-noise ratio)

Our Innovative Approach: Entity Schema + Rules

Instead of using raw GraphQL introspection schemas, we developed a compressed, high-density schema representation:

Entity Schema as Compressed Knowledge

• Compact Format: 100x smaller than full introspection schemas
• Domain-Specific: Contains project-specific entities and relationships
• High Information Density: Only essential types, relationships, and patterns
• Rule-Based: Combined with PostGraphile v4 patterns for query construction

Size Comparison

Traditional Approach:
├── Full GraphQL Introspection: ~50,000+ tokens
├── Context Window Usage: 80-95%
└── Result: Often fails or generates invalid queries

Our Approach:
├── Entity Schema: ~500-1,000 tokens
├── PostGraphile Rules: ~200-300 tokens
├── Context Window Usage: 5-10%
└── Result: Reliable, cost-effective query generation

Benefits

• Cost Effective: 10-20x lower token usage than traditional approaches
• Higher Accuracy: Domain-specific knowledge reduces errors
• Faster Responses: Smaller context means faster processing
• Scalable: Works consistently across different LLM models

Architecture

Core Components

1. GraphQLSource - Connection wrapper for GraphQL endpoints with entity schema support
2. GraphQLToolkit - LangChain-compatible toolkit providing all GraphQL tools
3. GraphQL Agent Tools - Individual tools for specific GraphQL operations

Available Tools

1. graphql_schema_info - Get raw entity schema with PostGraphile v4 rules
2. graphql_query_validator_execute - Combined validation and execution tool (validates queries, then executes them if valid)

Installation

# Install dependencies
pnpm install

Configuration

Copy the environment example file:

cp .env.example .env

Edit .env and add your OpenAI API key:

OPENAI_API_KEY=your_openai_api_key_here

Environment Variables

# Required
OPENAI_API_KEY=your-openai-api-key

# Optional
LLM_MODEL=gpt-4o  # Default model
PORT=8000         # Server port (if running API server)

Usage

Basic Example

import { runLangChainGraphQLAgent } from './src/langchain-agent.js';
import type { GraphQLProjectConfig } from './src/types.js';

// Load entity schema (learn more: https://subquery.network/doc/indexer/build/graphql.html)
// This example uses SubQuery Network's schema - replace with your own project's schema
const entitySchema = `
type Indexer implements Entity {
  id: ID!
  ownerId: String!
  active: Boolean!
  rewards: [Reward!]!
  projects: [Project!]!
}

type Project implements Entity {
  id: ID!
  owner: String!
  metadata: String!
}
`;

const config: GraphQLProjectConfig = {
  cid: "subquery-network",
  schemaContent: entitySchema,
  nodeType: GraphqlProvider.SUBQL,
  updatedAt: new Date().toISOString(),
  domainName: "SubQuery Network",
  domainCapabilities: [
    "Indexer information and performance metrics",
    "Project registration and metadata",
    "Staking rewards and delegation data",
    "Network statistics and era information"
  ],
  declineMessage: "I'm specialized in SubQuery Network data queries. I can help you with indexers, projects, staking rewards, and network statistics, but I cannot assist with cooking. Please ask me about SubQuery Network data instead."
};

// Note: This example uses SubQuery Network's API - replace with your own project's endpoint
const endpoint = "https://index-api.onfinality.io/sq/subquery/subquery-mainnet";

// Query with natural language
const answer = await runLangChainGraphQLAgent(
  config,
  "Show me the top 3 indexers with their project information",
  endpoint
);

console.log(answer);

Example Natural Language Queries

Note: These examples are for the SubQuery Network demo. For your own project, the queries would be specific to your indexed blockchain data.

Basic Data Retrieval

• "Show me the first 5 indexers and their IDs"
• "What projects are available? Show me their owners"
• "List all indexers with their project information"

Staking & Rewards

• "What are my staking rewards for wallet 0x123...?"
• "Show me rewards for the last era"
• "Find delegations for a specific indexer"

Performance & Analytics

• "Which indexers have the highest rewards?"
• "Show me project performance metrics"
• "List top performing indexers by era"

PostGraphile v4 Query Patterns

The agent understands PostGraphile v4 patterns automatically:

Entity Queries

• Single: entityName(id: ID!) -> Full entity object
• Collection: entityNames(first: Int, filter: EntityFilter) -> Connection with pagination

Filtering

filter: {
  fieldName: { equalTo: "value" }
  amount: { greaterThan: 100 }
  status: { in: ["active", "pending"] }
}

Ordering

orderBy: [FIELD_NAME_ASC, CREATED_AT_DESC]

Pagination

{
  entities(first: 10, after: "cursor") {
    nodes { id, field }
    pageInfo { hasNextPage, endCursor }
  }
}

Agent Workflow

The agent follows this intelligent workflow:

1. Relevance Check: Determines if the question relates to the project data
2. Schema Analysis: Loads entity schema and PostGraphile rules (once per session)
3. Query Construction: Builds GraphQL queries using PostGraphile patterns
4. Validation: Validates queries against the live GraphQL schema
5. Execution: Executes validated queries to get real data
6. Summarization: Provides user-friendly responses based on actual results

Development

# Development mode with auto-reload
pnpm dev

# Build the project
pnpm build

# Run tests
pnpm test

# Type checking
pnpm typecheck

Scripts

• dev - Run in development mode with file watching
• build - Compile TypeScript to JavaScript
• build:watch - Compile with file watching
• start - Run the compiled application
• test - Run tests
• test:watch - Run tests in watch mode
• typecheck - Run TypeScript type checking
• lint - Run ESLint (if configured)
• clean - Clean build output

Project Structure

sq-graphql-agent/
├── src/                    # Source code
│   ├── langchain-agent.ts  # Main agent implementation
│   ├── tools.ts            # GraphQL tools
│   ├── types.ts            # TypeScript type definitions
│   └── utils.ts            # Utility functions
├── examples/               # Usage examples
├── tests/                  # Test files
├── package.json            # Dependencies and scripts
└── tsconfig.json           # TypeScript configuration

Dependencies

Runtime Dependencies

• @langchain/community - LangChain community tools
• @langchain/core - LangChain core utilities
• @langchain/langgraph - LangGraph for agent workflows
• @langchain/openai - OpenAI integration
• graphql - GraphQL query library
• openai - OpenAI API client
• pino - Fast JSON logger
• zod - Schema validation

Development Dependencies

• typescript - TypeScript compiler
• tsx - TypeScript execution tool
• jest - Testing framework
• ts-jest - Jest TypeScript preset
• @types/node - Node.js type definitions

Error Handling

The toolkit includes comprehensive error handling:

Network Issues

• GraphQL endpoint connectivity problems
• Timeout handling for long-running queries
• Automatic retry for transient failures

Schema Introspection Issues

• Authorization error detection (e.g., missing headers)
• Invalid endpoint error handling
• Prevents caching of failed introspection results

Query Issues

• Invalid GraphQL syntax detection
• Schema validation with detailed error messages
• Field existence verification

Performance Considerations

Query Optimization

• Always use pagination (first: N) for collection queries
• Limit nested relationship depth to avoid expensive queries
• Use specific field selection rather than querying all fields

Caching Strategy

• GraphQL schema introspection results are cached (configurable TTL)
• Entity schema is loaded once per toolkit instance
• No query result caching (always fresh data)

Resource Management

• Connection pooling for HTTP requests
• Automatic cleanup of resources
• Memory-efficient schema processing

Model Performance Comparison

Based on comprehensive testing, here's how different LLM models perform with this GraphQL agent:

Model	Performance	Query Accuracy	Complex Reasoning	Cost Efficiency	Recommendation
Gemini-3-flash(openrouter)	Excellent	Excellent	Excellent	Good	Recommended
GLM-4.6	Very Good	Very Good	Excellent	Excellent	Cost-Effective
Kimi-k2	Good	Fair	Fair	Very Good	Cost-Effective

Recommendation Guidelines

For Production Use:

export LLM_MODEL="gpt-4o"  # Best reliability and accuracy

For Cost-Conscious Production:

export LLM_MODEL="deepseek-v3"  # Excellent value proposition

For Development/Testing:

export LLM_MODEL="gpt-4.1-mini"  # Good balance for non-production

Comparison with Alternatives

Feature	SubQL GraphQL Agent	LangChain GraphQL	LangChain SQL Agents
Schema Size Handling	Entity compression (500 tokens)	Full schema per query (50k+ tokens)	Table schemas (compact)
Domain Flexibility	SubQuery SDK only	Any GraphQL API	Any SQL database
Schema Learning	Learns once, reasons multiple queries	Requires schema in every query	Learns schema structure
Natural Language	Full support	Limited by context size	Full support
Query Construction	PostGraphile rules	Pattern matching only	Mature SQL generation
Cost Efficiency	Low token usage	Very high token usage	Very efficient
Security & Access	API-only, no DB access	API-only, no DB access	Requires DB credentials
Setup Complexity	Simple for SubQuery	Schema management overhead	DB access + permissions

License

Apache-2.0