How to Run an AI GraphQL Agent with OE Runtime

Query any GraphQL API with natural language. OE Runtime introspects your schema, constructs type-safe queries with variables, executes them against your API, and returns structured results — no GraphQL expertise required.

What You Need

• Node.js 18+ installed, or the OE Runtime binary from openenthrium.com/runtime
• An API key from OpenAI, Anthropic, or any supported LLM provider
• A GraphQL API endpoint URL (public or private — the example uses the public SpaceX API)
• A text editor — nothing else

Create the Project Folder

Create a folder called graphql/ and add these two files:

The Skill Files

Create SKILL.md inside a graphql/ directory. This is the portable skill — it follows the agentskills.io format and runs unchanged on Claude, Cursor, Windsurf, or OE Runtime:

---
name: graphql
description: Run GraphQL queries and mutations
license: Apache-2.0
metadata:
  author: Open Enthrium
  version: "1.0"
---

You are a GraphQL API agent. Run queries to fetch data and mutations to create or update records.
Always use variables for dynamic values — never interpolate directly into queries.
Complete all steps fully before writing your report.

## Step 1: Introspect Schema
Call the GraphQL introspection query to understand the available types, queries, and mutations.
List the key types and operations available.

## Step 2: Execute Operation
Based on the schema, run a sample query to fetch a list of records from the most relevant type.
Use variables for any dynamic values. Return the raw result.

## Step 3: Report
Summarize what was returned:
- Operation executed (query or mutation)
- Fields fetched
- Number of records returned
- Key values from the first 3 records

Create agent.yaml in the same directory to wire the skill to your connector:

name: GraphQL Agent
description: Run GraphQL queries and mutations
connectors:
  - connection_name: My GraphQL API
    connection_type: graphql
skills:
  - path: ./
    trigger_type: auto

The Config File

Create oe-config.json in the same directory:

{
  "llm": {
    "provider": "openai",
    "model": "gpt-4o",
    "apiKey": "YOUR_OPENAI_API_KEY"
  },
  "server": {
    "enabled": false,
    "port": 3333,
    "apiKey": "your-secret-api-key"
  },
  "connectors": [
    {
      "connection_name": "My GraphQL API",
      "connection_type": "graphql",
      "endpoint": "https://api.example.com/graphql",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  ]
}

Replace the endpoint with your GraphQL API URL and set the Authorization header with your API token. The agent works with any GraphQL API including GitHub, Shopify, Hasura, and custom APIs.

Download OE Runtime

Run the Agent

From the parent folder containing your skill directory:

1 npx recommended

npx -y @openenthrium/oe-runtime@latest ./graphql

2 Windows

oe-runtime-win.exe ./graphql

3 macOS

chmod +x oe-runtime-macos
./oe-runtime-macos ./graphql

First run blocked? System Settings → Privacy & Security → Allow Anyway.

4 Linux

chmod +x oe-runtime-linux
./oe-runtime-linux ./graphql

5 API Server integration

Add a "server" block to oe-config.json, then start with --serve:

{
  "llm": { ... },
  "server": { "enabled": true, "port": 3333, "apiKey": "your-secret-key" },
  "connectors": [ ... ]
}

npx -y @openenthrium/oe-runtime@latest --serve --config oe-config.json

Run with inline YAML:

curl -X POST http://localhost:3333/run \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{"yaml": "...", "params": {}}'

Or run from a file on the server:

curl -X POST http://localhost:3333/run-file \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-key" \
  -d '{"file": "/path/to/agent.yaml", "params": {}}'

Use Cases

• API exploration and documentation — Point the agent at any GraphQL API to automatically introspect its full schema and produce a human-readable summary of available types, queries, and mutations. This is particularly useful when onboarding to a new API or auditing what a third-party service exposes.
• E-commerce data retrieval — Query a Shopify or WooCommerce GraphQL API to fetch product listings, order statuses, inventory levels, and customer data without writing custom integration code. The agent handles schema introspection and query construction automatically.
• CMS content fetching — Pull content from a headless CMS like Contentful, Sanity, or Strapi via their GraphQL API to generate reports or feed data into downstream workflows. The agent can extract structured content fields and format them for whatever output format you need.
• GitHub repository analysis — Use the GitHub GraphQL API to query repository stats, pull request details, issue lists, and contributor activity in a single structured request. GraphQL allows fetching exactly the fields needed, making it far more efficient than the REST API for complex data shapes.
• Hasura database queries — Query a Hasura-powered database using natural language and let the agent translate it into the correct GraphQL query with the right filters, sorting, and pagination. This gives non-technical teams access to database data without SQL knowledge.
• Data federation across services — Use a GraphQL federation gateway to query data from multiple microservices in a single request. The agent handles the complexity of the federated schema and returns a unified response from what would otherwise require multiple separate API calls.
• Mutation testing and verification — Run create, update, or delete mutations against a staging or development GraphQL API to verify that data is being written correctly. The agent checks the mutation response and confirms that the expected changes are reflected in a subsequent query.
• Automated reporting from internal APIs — Schedule the agent to query your internal GraphQL API daily and produce business metric reports from the latest data. No need to build a separate reporting layer — the agent reads from the same API your product uses and formats the output for stakeholders.