Update GraphQL Agent documentation #668
Conversation
- Comprehensive GraphQL Agent documentation with technical architecture - Free tier integration in Network App with rate limiting - Paid MCP service announcement (coming soon)
WalkthroughRemoved most of the SubQuery AI Apps Framework documentation and sidebar entries, added a new "SubQuery GraphQL Agent" doc, updated navbar/sidebar to reference it, and switched a hard-coded CloudFront distribution in the staging workflow to use a workflow variable. No runtime code or public API signatures changed. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant User as User (NL)
participant Agent as GraphQL Agent
participant Schema as Schema Analyzer
participant Validator as Query Validator
participant Endpoint as GraphQL Endpoint
participant Summarizer as Result Summarizer
rect rgb(249,250,252)
User->>Agent: Ask natural-language question
Agent->>Schema: Analyze & compress schema
Schema-->>Agent: Relevant types/fields
Agent->>Agent: Generate candidate GraphQL query(ies)
Agent->>Validator: Validate queries
Validator-->>Agent: Validation results
end
rect rgb(247,255,250)
Agent->>Endpoint: Execute validated query(ies)
Endpoint-->>Agent: Raw results
Agent->>Summarizer: Aggregate & summarize results
Summarizer-->>Agent: Summarized answer
Agent-->>User: Return final response
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
📜 Recent review detailsConfiguration used: CodeRabbit UI Review profile: CHILL Plan: Pro 📒 Files selected for processing (1)
🚧 Files skipped from review as they are similar to previous changes (1)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (25)
docs/.vuepress/config.ts(1 hunks)docs/ai/ai-app-framework.md(0 hunks)docs/ai/api/api.md(0 hunks)docs/ai/build/app.md(0 hunks)docs/ai/build/function_tools.md(0 hunks)docs/ai/build/other.md(0 hunks)docs/ai/build/rag.md(0 hunks)docs/ai/graphql_agent.md(1 hunks)docs/ai/guides/delegation-helper.md(0 hunks)docs/ai/guides/fancy-greeter.md(0 hunks)docs/ai/guides/subquery-docs-rag.md(0 hunks)docs/ai/publish/publish.md(0 hunks)docs/ai/run/cli.md(0 hunks)docs/ai/run/docker.md(0 hunks)docs/ai/run/local.md(0 hunks)docs/ai/snippets/add-a-function-tool.md(0 hunks)docs/ai/snippets/configure-app-logic.md(0 hunks)docs/ai/snippets/configure-manifest-file.md(0 hunks)docs/ai/snippets/create-a-new-app.md(0 hunks)docs/ai/snippets/install-the-framework.md(0 hunks)docs/ai/snippets/prerequisites.md(0 hunks)docs/ai/snippets/run-the-ai-app.md(0 hunks)docs/ai/snippets/summary.md(0 hunks)docs/ai/snippets/update-system-prompt.md(0 hunks)docs/ai/welcome.md(0 hunks)
💤 Files with no reviewable changes (23)
- docs/ai/snippets/create-a-new-app.md
- docs/ai/snippets/run-the-ai-app.md
- docs/ai/snippets/update-system-prompt.md
- docs/ai/api/api.md
- docs/ai/run/local.md
- docs/ai/snippets/summary.md
- docs/ai/build/other.md
- docs/ai/build/app.md
- docs/ai/snippets/prerequisites.md
- docs/ai/run/cli.md
- docs/ai/snippets/install-the-framework.md
- docs/ai/snippets/configure-manifest-file.md
- docs/ai/run/docker.md
- docs/ai/guides/subquery-docs-rag.md
- docs/ai/build/rag.md
- docs/ai/build/function_tools.md
- docs/ai/snippets/configure-app-logic.md
- docs/ai/ai-app-framework.md
- docs/ai/snippets/add-a-function-tool.md
- docs/ai/publish/publish.md
- docs/ai/guides/fancy-greeter.md
- docs/ai/welcome.md
- docs/ai/guides/delegation-helper.md
🧰 Additional context used
🪛 LanguageTool
docs/ai/graphql_agent.md
[style] ~7-~7: Consider a different adjective to strengthen your wording.
Context: ...itional GraphQL query building requires deep understanding of: - GraphQL schema stru...
(DEEP_PROFOUND)
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
documentation/docs/.vuepress/sidebar.ts
Lines 724 to 728 in 30f78d0
Update AI sidebar to reference existing documentation
The commit deletes every file under docs/ai/ except graphql_agent.md, yet the AI section of the sidebar still links to now‑missing pages such as ai/welcome.md and the guides/build/run subpages. After this change every sidebar link in that section will 404 and the new GraphQL Agent page is not discoverable from the sidebar at all. The sidebar should be updated to point at the surviving page(s) or the section removed to avoid broken navigation.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
docs/ai/graphql_agent.md (2)
7-7: Consider alternative wording (optional).The phrase "deep understanding" is common but could be strengthened with a more specific term if desired.
Based on static analysis tools.
231-232: Expand placeholder content for better user experience.The "Pricing and Billing" section contains only "Coming soon" which provides minimal information. Consider adding a brief note about when pricing information will be available or directing users to sign up for updates.
Apply this diff:
## Pricing and Billing -Coming soon + +Detailed pricing information will be announced when the paid MCP service launches. Sign up for our newsletter at [subquery.network](https://subquery.network) to be notified of pricing updates and availability.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
docs/.vuepress/config.ts(1 hunks)docs/.vuepress/sidebar.ts(1 hunks)docs/ai/graphql_agent.md(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/.vuepress/config.ts
🧰 Additional context used
🪛 LanguageTool
docs/ai/graphql_agent.md
[style] ~7-~7: Consider a different adjective to strengthen your wording.
Context: ...itional GraphQL query building requires deep understanding of: - GraphQL schema stru...
(DEEP_PROFOUND)
🔇 Additional comments (2)
docs/ai/graphql_agent.md (1)
1-252: Excellent comprehensive documentation!This documentation provides a thorough and well-structured overview of the SubQuery GraphQL Agent. The technical architecture section is particularly strong, with clear explanations of the innovative schema compression technology and practical examples. The distinction between free and paid tiers is clearly communicated.
docs/.vuepress/sidebar.ts (1)
722-727: LGTM! Sidebar navigation correctly updated.The sidebar configuration properly reflects the documentation restructuring, consolidating the AI section into a single GraphQL Agent entry with the correct link path.
| 4. Type your question in natural language | ||
| 5. Receive instant answers with data insights | ||
|
|
||
| ## Paid Service - Graphql Agent as MCP (Coming Soon) |
There was a problem hiding this comment.
Fix capitalization: "Graphql" should be "GraphQL".
For consistency with the rest of the document where "GraphQL" is always capitalized.
Apply this diff:
-## Paid Service - Graphql Agent as MCP (Coming Soon)
+## Paid Service - GraphQL Agent as MCP (Coming Soon)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ## Paid Service - Graphql Agent as MCP (Coming Soon) | |
| ## Paid Service - GraphQL Agent as MCP (Coming Soon) |
🤖 Prompt for AI Agents
In docs/ai/graphql_agent.md around line 93, the heading uses "Graphql" instead
of the correct "GraphQL"; update the heading text to replace "Graphql" with
"GraphQL" so it matches the document's capitalization and style.
| You can ask any question that can be answered by the data in the SubQuery project, from simple counts to complex analytical queries. | ||
|
|
||
| **Can I use the GraphQL Agent with my own SubQuery/SubGraph projects?** | ||
| Yes, the GraphQL Agent can be used as an MCP (Model Context Protocol) with custom SubQuery/SubGraph projects. Configure the agent to point to your GraphQL endpoint and include the project schema and any required authentication settings. |
There was a problem hiding this comment.
Fix inconsistent capitalization: "SubGraph" should be "Subgraph".
For consistency with lines 3 and 17 where "Subgraph" is used.
Apply this diff:
-Yes, the GraphQL Agent can be used as an MCP (Model Context Protocol) with custom SubQuery/SubGraph projects. Configure the agent to point to your GraphQL endpoint and include the project schema and any required authentication settings.
+Yes, the GraphQL Agent can be used as an MCP (Model Context Protocol) with custom SubQuery/Subgraph projects. Configure the agent to point to your GraphQL endpoint and include the project schema and any required authentication settings.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Yes, the GraphQL Agent can be used as an MCP (Model Context Protocol) with custom SubQuery/SubGraph projects. Configure the agent to point to your GraphQL endpoint and include the project schema and any required authentication settings. | |
| Yes, the GraphQL Agent can be used as an MCP (Model Context Protocol) with custom SubQuery/Subgraph projects. Configure the agent to point to your GraphQL endpoint and include the project schema and any required authentication settings. |
🤖 Prompt for AI Agents
In docs/ai/graphql_agent.md around line 246, the term "SubGraph" is
inconsistently capitalized; change "SubGraph" to "Subgraph" to match usage on
lines 3 and 17 and maintain consistent capitalization across the document.
docs/.vuepress/sidebar.ts
Outdated
| // "/ai/": [ | ||
| // { | ||
| // text: "SubQuery GraphQL Agent", | ||
| // link: `${locale}/ai/graphql_agent.md`, | ||
| // }, | ||
| // ], |
There was a problem hiding this comment.
🧩 Analysis chain
Clarify whether the AI sidebar section should be active.
The "/ai/" sidebar section is commented out, which means users won't see the "SubQuery GraphQL Agent" entry in the sidebar navigation. According to the AI summary, the navbar was updated to link to this documentation. If the navbar points to /ai/graphql_agent.md but the sidebar entry is disabled, this creates a navigation inconsistency—users can reach the page via the navbar but won't see it listed in the sidebar.
Questions:
- Should this section be uncommented to make the documentation discoverable via the sidebar?
- If it's intentionally disabled, consider adding a comment explaining why (e.g.,
// TODO: Enable after reviewor// Temporarily disabled pending content approval). - If this code is not needed, remove it entirely rather than leaving commented code.
Run the following script to check whether the navbar references this GraphQL Agent documentation:
🏁 Script executed:
#!/bin/bash
# Description: Check if navbar in config.ts references the GraphQL Agent doc
# Search for graphql_agent references in config.ts
rg -n "graphql_agent" docs/.vuepress/config.ts
# Also check if there's an active navbar item pointing to /ai/
rg -n -C2 '"/ai/|ai/graphql' docs/.vuepress/config.tsLength of output: 158
Uncomment the AI sidebar section to match the active navbar entry.
Verification confirms the navbar in config.ts (lines 72-76) contains an active "SubQuery GraphQL Agent" link pointing to /ai/graphql_agent.md. However, the identical sidebar entry in sidebar.ts (lines 722-727) is commented out, creating a navigation inconsistency. Users can reach the documentation via the navbar but won't discover it through the sidebar menu.
Fix: Uncomment lines 722-727 in sidebar.ts to enable the sidebar entry and maintain navigation consistency.
🤖 Prompt for AI Agents
In docs/.vuepress/sidebar.ts around lines 722 to 727, the AI sidebar entry is
commented out causing a mismatch with the active navbar; uncomment the block so
the sidebar contains the "SubQuery GraphQL Agent" entry pointing to
`${locale}/ai/graphql_agent.md` (remove the leading // from the three lines and
ensure the surrounding array/object remains syntactically correct).
Summary by CodeRabbit
Documentation
Chores