The Complete Production SOP: How to Deploy and Run ChatGPT Retrieval Plugin Standard OpenAPI Spec in Autonomous AI Agents
Step-by-step SOP to install and run the ChatGPT Retrieval Plugin Scaffold in Codex, Claude Code, and Cursor. OpenAPI specs, schemas, and sandbox rules.
Technical Overview & Architectural Context
When autonomous AI agents are tasked with creating retrieval endpoints or ChatGPT-compatible plugins, they routinely fail by generating arbitrary REST payloads, hallucinating non-standard query structures, or omitting tenant-scoped security filters. Traditional LLM outputs often invent unverified endpoints like `/search` or `/v1/documents` rather than adhering strictly to the official OpenAI specification: `/upsert`, `/upsert-file`, `/query`, and `/delete`. Furthermore, agents frequently neglect the mandatory `.well-known/ai-plugin.json` schema layout, misconfigure CORS headers, and fail to implement bearer token auth schemas required by plugin orchestrators. The `chatgpt-retrieval-plugin-scaffold` skill solves this by establishing a deterministic contract within Codex, Claude Code, Cursor, and Windsurf. By constraining the agent's filesystem writes to validated OpenAPI schemas, typing chunk boundaries (`DocumentChunk`, `DocumentMetadataFilter`), and enforcing multi-tenant isolation, the skill prevents context-poisoning and hallucinated vector store adapters. Agents operate within a strictly governed execution loop, producing production-ready FastAPI or Express retrieval services that pass OpenAPI linting on the first pass.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Create the local skill manifest directory and inject verified procedural rules into your workspace.
Agent runtimes locate custom skills by parsing specific hidden directories (`.agents/skills`, `.cursor/skills`, or global paths). Mounting `chatgpt-retrieval-plugin-scaffold` ensures that any time triggers such as 'build retrieval plugin' or 'implement /query endpoint' are encountered, the runtime preloads the OpenAPI specification boundaries and stops hallucinated REST signatures.
mkdir -p .agents/skills/chatgpt-retrieval-plugin-scaffold && curl -fsSL https://askills.dev/api/skills/chatgpt-retrieval-plugin-scaffold/raw -o .agents/skills/chatgpt-retrieval-plugin-scaffold/SKILL.md---
name: "chatgpt-retrieval-plugin-scaffold"
description: "Build standardized document retrieval plugins and semantic search endpoints."
metadata:
author: "OpenAI"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "build retrieval plugin"
- "implement /query endpoint"
- "setup chatgpt plugin manifest"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---Keep the SKILL.md scoped locally within `.agents/skills/` to prevent polluting global system prompts across unrelated agent workflows.
Ensure `shell_exec: false` remains intact in the frontmatter. The retrieval scaffolding skill relies purely on declarative code generation, preventing unauthorized shell operations.
Environment Secrets & Dependency Validation
Inject required environment variables safely without leaking secrets into conversation history.
Standard retrieval plugins interact with embedding models and vector datastores. Instead of allowing the agent to hardcode dummy tokens or ask for raw API keys in plain text prompts, define a `.env.template` and `.env.local` file containing empty stubs for `BEARER_TOKEN`, `OPENAI_API_KEY`, and `DATASTORE_TYPE`.
echo 'BEARER_TOKEN=prod_retrieval_sec_test
OPENAI_API_KEY=sk-local-mock
DATASTORE=qdrant
QDRANT_URL=http://localhost:6333' >> .env.local && git check-ignore -q .env.local || echo '.env.local' >> .gitignoreimport os
from pydantic_settings import BaseSettings
class Settings(BaseSettings):
bearer_token: str = os.getenv("BEARER_TOKEN", "default_insecure_token")
openai_api_key: str = os.getenv("OPENAI_API_KEY", "")
datastore: str = os.getenv("DATASTORE", "qdrant")
class Config:
env_file = ".env.local"
settings = Settings()Reference `settings.bearer_token` via Pydantic settings models rather than reading raw `os.environ` throughout routing files.
Never feed actual OpenAI or Pinecone production keys into interactive agent prompts; agents log context steps in local state databases.
Intent Matching & Trigger Invocation
Verify deterministic activation using tested natural language prompts.
Trigger the skill deterministically by formulating requests that match frontmatter triggers: `build retrieval plugin`, `implement /query endpoint`, or `setup chatgpt plugin manifest`. When the runtime flags this intent, it will execute against OpenAPI strict constraints rather than improvising generic CRUD APIs.
claude-code "build retrieval plugin: implement /query endpoint and OpenAPI manifest for Qdrant"{
"schema_version": "v1",
"name_for_model": "retrieval_plugin",
"name_for_human": "Retrieval Service",
"description_for_model": "Plugin for searching semantic document chunks and contextual embeddings.",
"description_for_human": "Search internal organization documents.",
"auth": {
"type": "user_http",
"authorization_type": "bearer"
},
"api": {
"type": "openapi",
"url": "/.well-known/openapi.yaml",
"has_user_authentication": true
},
"logo_url": "https://example.com/logo.png",
"contact_email": "[email protected]",
"legal_info_url": "https://example.com/legal"
}Instruct the agent to provide both `.well-known/ai-plugin.json` and `.well-known/openapi.yaml` in tandem to ensure zero validation drift.
ChatGPT plugin discovery strictly mandates that `.well-known` endpoints serve valid JSON/YAML without redirects or dynamic trailing slashes.
Verification, Linting & Output Quality Gate
Execute automated self-healing checks before accepting agent deliverables.
Before closing the agent task, run an OpenAPI validator and schema verification pass. If schemas fail standard retrieval conventions (e.g., missing `DocumentMetadataFilter` or invalid `/upsert` formats), force the agent to self-correct.
npx @redocly/cli lint .well-known/openapi.yaml && pytest tests/test_retrieval_endpoints.pyfrom fastapi.testclient import TestClient
from server.main import app
client = TestClient(app)
def test_query_schema_conformance():
headers = {"Authorization": "Bearer prod_retrieval_sec_test"}
payload = {
"queries": [
{
"query": "quarterly earnings report",
"filter": {"source": "notion"},
"top_k": 3
}
]
}
response = client.post("/query", json=payload, headers=headers)
assert response.status_code == 200
assert "results" in response.json()Run OpenAPI linter as a pre-commit hook so the autonomous coding agent cannot push code when endpoint specifications violate schema specs.
Do not skip authentication assertions in tests; missing the `Authorization: Bearer <token>` check in endpoints will result in ChatGPT plugin registration failure.
Real-World Scenario: Scaffold Standard Retrieval Plugin with FastAPI and Pinecone Vector Connector
“Using chatgpt-retrieval-plugin-scaffold, build retrieval plugin service in FastAPI. Implement /query endpoint, /upsert endpoint, and setup chatgpt plugin manifest with tenant-based metadata filtering.”
Runtime Troubleshooting & Failure Modes
Root Cause: The agent generated an arbitrary query interface (e.g. `{'query': '...', 'limit': 5}`) instead of conforming to the ChatGPT Retrieval Plugin specification, which demands an array of query objects under the key `queries`.
class QueryRequest(BaseModel):
queries: List[QueryWithFilter]
@app.post("/query", response_model=QueryResponse)
async def query_documents(request: QueryRequest, token: str = Depends(verify_token)):
return await datastore.query(request.queries)Root Cause: The agent applied the global Bearer token security middleware to all endpoints, accidentally locking down the public `.well-known` discovery directory.
# Exclude manifest discovery routes from auth dependency:
app.include_router(public_manifest_router, prefix="/.well-known", tags=["manifest"])
app.include_router(retrieval_router, dependencies=[Depends(verify_bearer_token)])Frequently Asked Questions (ChatGPT Retrieval Plugin Standard OpenAPI Spec SOP)
Q:Can I use ChatGPT Retrieval Plugin Standard OpenAPI Spec across Codex, Claude Code, and Cursor simultaneously?
Yes. The skill conforms to the universal SKILL.md specification. When placed in `.agents/skills/chatgpt-retrieval-plugin-scaffold`, it is automatically parsed by Claude Code CLI, Cursor Composer, Windsurf Cascades, and Codex workspaces without any runtime-specific modifications.
Q:How does ChatGPT Retrieval Plugin Standard OpenAPI Spec prevent context window overflow during long agent sessions?
Instead of passing hundreds of lines of vector store documentation or OpenAPI specifications into the prompt history, the skill enforces targeted, modular rules and loads strict endpoint signatures only when designated triggers (like 'implement /query endpoint') are encountered.
Q:Does this skill require escalated root or container permissions?
No. The skill has an audited security score of 98/100. It explicitly enforces `shell_exec: false` and `net_access: false` inside the metadata permissions block, allowing file modifications solely within your designated workspace.
Ready to equip your autonomous agent with ChatGPT Retrieval Plugin Standard OpenAPI Spec?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.