Add agent index discovery endpoint#403
Conversation
Deploying with
|
| Status | Name | Latest Commit | Preview URL | Updated (UTC) |
|---|---|---|---|---|
| ✅ Deployment successful! View logs |
et3 | 30fac45 | Commit Preview URL Branch Preview URL |
Jan 15 2026, 06:10 AM |
Summary of ChangesHello @zz-plant, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the API's discoverability for agent-based systems by introducing a dedicated, centralized index. This new endpoint aims to streamline how agents locate and interact with various API services, providing a consistent and versionable entry point for tooling. The changes facilitate better integration and reproducibility for automated clients by offering a structured overview of available resources and recommended starting points. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![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
Here are some automated review suggestions for this pull request.
Reviewed commit: 30fac452a2
ℹ️ 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".
| findings: `${normalizedBase}/findings.json`, | ||
| diagnosticResults: `${normalizedBase}/diagnostic-results.json`, | ||
| ragCorpus: `${normalizedBase}/rag-corpus.jsonl`, | ||
| research: `${normalizedBase}/research.json`, |
There was a problem hiding this comment.
The new research entry is built by concatenating basePath for every index. The versioned agent/site index routes pass basePath: "/api/v/2026.01", but there is no src/pages/api/v/2026.01/research.json.ts, so /api/v/2026.01/research.json will 404 and any consumer following the discovery metadata will break. Consider either adding the versioned research endpoint or mapping research to the unversioned /api/research.json when generating versioned indexes.
Useful? React with 👍 / 👎.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a new agent index discovery endpoint, which is a great addition for improving the discoverability of the API for tooling. The implementation is clean and follows a good structure by creating new API routes in Astro and centralizing the response creation logic in src/utils/api-responses.ts.
The new buildEndpointMap helper is a good step towards better organization. My review includes a few suggestions to further improve maintainability by reducing code duplication and eliminating magic strings/numbers. Specifically, I've pointed out opportunities to:
- Create a single source of truth for the endpoint definitions to be shared between
buildEndpointMapandbuildEndpoints. - Extract hardcoded paths and numbers into named constants for better readability and easier updates.
Overall, this is a solid contribution that enhances the API. Addressing the feedback will make the new code even more robust and easier to maintain.
| const buildEndpointMap = ( | ||
| basePath: string, | ||
| options?: { includeReleaseEndpoints?: boolean }, | ||
| ) => { | ||
| const normalizedBase = basePath.replace(/\/$/, ""); | ||
|
|
||
| return { | ||
| agentIndex: `${normalizedBase}/agent-index.json`, | ||
| siteIndex: `${normalizedBase}/site-index.json`, | ||
| standards: `${normalizedBase}/standards.json`, | ||
| clauses: `${normalizedBase}/clauses.json`, | ||
| mechanisms: `${normalizedBase}/mechanisms.json`, | ||
| validators: `${normalizedBase}/validators.json`, | ||
| glossary: `${normalizedBase}/glossary.json`, | ||
| antiPatterns: `${normalizedBase}/anti-patterns.json`, | ||
| evidencePacks: `${normalizedBase}/evidence-packs.json`, | ||
| findings: `${normalizedBase}/findings.json`, | ||
| diagnosticResults: `${normalizedBase}/diagnostic-results.json`, | ||
| ragCorpus: `${normalizedBase}/rag-corpus.jsonl`, | ||
| research: `${normalizedBase}/research.json`, | ||
| ...(options?.includeReleaseEndpoints | ||
| ? { | ||
| releases: `${normalizedBase}/releases.json`, | ||
| changelog: `${normalizedBase}/changelog.json`, | ||
| } | ||
| : {}), | ||
| }; | ||
| }; |
There was a problem hiding this comment.
This new buildEndpointMap function is a good abstraction. However, it introduces duplication with the buildEndpoints function, as both now maintain separate but similar lists of endpoints. This could lead to maintenance issues, such as forgetting to update one list when an endpoint is added or changed.
To create a single source of truth, you could define the endpoint information in a shared data structure. This would improve maintainability and reduce the risk of inconsistencies.
Here's an example of how you could refactor this:
// Define endpoints in a single place
const ENDPOINTS = {
core: {
agentIndex: 'agent-index.json',
siteIndex: 'site-index.json',
standards: 'standards.json',
clauses: 'clauses.json',
mechanisms: 'mechanisms.json',
validators: 'validators.json',
glossary: 'glossary.json',
antiPatterns: 'anti-patterns.json',
evidencePacks: 'evidence-packs.json',
findings: 'findings.json',
diagnosticResults: 'diagnostic-results.json',
ragCorpus: 'rag-corpus.jsonl',
research: 'research.json',
},
release: {
releases: 'releases.json',
changelog: 'changelog.json',
},
};
// Refactored buildEndpointMap
const buildEndpointMap = (
basePath: string,
options?: { includeReleaseEndpoints?: boolean },
) => {
const normalizedBase = basePath.replace(/\/$/, '');
const files = { ...ENDPOINTS.core };
if (options?.includeReleaseEndpoints) {
Object.assign(files, ENDPOINTS.release);
}
return Object.fromEntries(
Object.entries(files).map(([key, file]) => [key, `${normalizedBase}/${file}`])
) as Record<keyof typeof ENDPOINTS.core & keyof typeof ENDPOINTS.release, string>;
};
// Refactored buildEndpoints
const buildEndpoints = (
basePath: string,
options?: { includeReleaseEndpoints?: boolean },
) => {
const normalizedBase = basePath.replace(/\/$/, '');
let files = Object.values(ENDPOINTS.core);
if (options?.includeReleaseEndpoints) {
files.push(...Object.values(ENDPOINTS.release));
}
return files.map((endpoint) => `${normalizedBase}/${endpoint}`);
};This approach would also make the quickStart list in createAgentIndexResponse more robust, as you could define it based on the keys of the ENDPOINTS object, preventing runtime errors from typos.
| discovery: { | ||
| sitemap: "/sitemap.xml", | ||
| robots: "/robots.txt", | ||
| }, | ||
| docs: { | ||
| apiReference: "/api", | ||
| agentObjectModel: "/agents/spec", | ||
| agentObjectSchema: "/agents/spec.json", | ||
| }, |
There was a problem hiding this comment.
The hardcoded paths for discovery and docs are magic strings. It would be beneficial to define these as constants at a higher scope. This improves maintainability and ensures consistency if these paths are used elsewhere.
For example:
const DISCOVERY_PATHS = {
SITEMAP: '/sitemap.xml',
ROBOTS: '/robots.txt',
};
const DOCS_PATHS = {
API_REFERENCE: '/api',
AGENT_OBJECT_MODEL: '/agents/spec',
AGENT_OBJECT_SCHEMA: '/agents/spec.json',
};| endpointMap.glossary, | ||
| endpointMap.research, | ||
| ], | ||
| ragCorpusPreview: `${endpointMap.ragCorpus}?limit=200`, |
There was a problem hiding this comment.
The limit 200 is a magic number. It would be better to define it as a named constant (e.g., RAG_CORPUS_PREVIEW_LIMIT) at a suitable scope for improved readability and maintainability.
1 participant
Motivation
Description
buildEndpointMaphelper andcreateAgentIndexResponseinsrc/utils/api-responses.tsthat assemble discovery metadata, a recommended quick-start list, and a full endpoint mapping.agent-index.jsonandresearch.jsonin the API endpoint lists and updatebuildEndpointsto emit the expanded set of exports.src/pages/api/agent-index.json.tsandsrc/pages/api/v/2026.01/agent-index.json.tsthat expose the current and versioned agent index.src/pages/api/index.astroand docsdocs/agent-metadata.mdto document the new�/api/agent-index.jsonendpoint.Testing
bun run check, which runs Lint, Unit Tests, Typecheck, Astro Check,Validate JSON, andValidate Glossary, and all checks passed.Codex Task