From a89adc78768e4381f313f514092869e9cc081e6f Mon Sep 17 00:00:00 2001 From: Rick Blalock Date: Fri, 24 Oct 2025 14:42:43 -0400 Subject: [PATCH 1/2] add docs for coding agents --- common/js/AGENTS.md | 160 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 156 insertions(+), 4 deletions(-) diff --git a/common/js/AGENTS.md b/common/js/AGENTS.md index 8cb7db9..e7af868 100644 --- a/common/js/AGENTS.md +++ b/common/js/AGENTS.md @@ -16,8 +16,12 @@ This guide provides comprehensive instructions for developing AI agents using th ```typescript import type { AgentRequest, AgentResponse, AgentContext } from "@agentuity/sdk"; -export default async function Agent(req: AgentRequest, resp: AgentResponse, ctx: AgentContext) { - return resp.json({hello: 'world'}); +export default async function Agent( + req: AgentRequest, + resp: AgentResponse, + ctx: AgentContext, +) { + return resp.json({ hello: "world" }); } ``` @@ -31,7 +35,7 @@ The main handler function type for an agent: type AgentHandler = ( request: AgentRequest, response: AgentResponse, - context: AgentContext + context: AgentContext, ) => Promise; ``` @@ -107,4 +111,152 @@ Access through `context.logger`: - Use the storage APIs for persisting data - Consider agent communication for complex workflows -For complete documentation, visit: https://agentuity.dev/SDKs/javascript/api-reference +## 6. How to use the documentation site, it's API's, etc. + +The Agentuity documentation site provides API endpoints that AI agents can use to search and read documentation programmatically. + +For the complete docs: https://agentuity.dev +The public repo markdown files are here: https://github.com/agentuity/docs/tree/main/content +For complete JS SDK documentation, visit: https://agentuity.dev/SDKs/javascript/api-reference + +With that in mind, here are some helpful things you can do to find the right doc information: + +**Base URL:** `https://agentuity.dev` + +### Quick Reference + +```bash +# Set base URL once per session +BASE="https://agentuity.dev" + +# Ask a question (AI-powered with RAG) +curl -sG "$BASE/api/rag-search" --data-urlencode "query=How do I create an agent?" + +# Search documentation (keyword search) +curl -sG "$BASE/api/search" --data-urlencode "query=environment variables" + +# Read full page content +curl -sG "$BASE/api/page-content" --data-urlencode "path=Introduction/getting-started" +``` + +### API Endpoints + +#### 1. RAG Search (Recommended for Questions) + +**Use when:** You have a natural-language question and want an AI-generated answer with supporting documentation. + +```bash +curl -sG "https://agentuity.dev/api/rag-search" \ + --data-urlencode "query=How do I use KV?" +``` + +**Response Format:** + +```json +[ + { + "id": "ai-answer-...", + "url": "#ai-answer", + "title": "AI Answer", + "content": "AI-generated answer to your question...", + "type": "ai-answer" + }, + { + "id": "doc-...", + "url": "/getting-started/installation", + "title": "Installation Guide", + "content": "Brief snippet of the document...", + "type": "document" + } +] +``` + +**Workflow:** + +1. Get the `ai-answer` item for a quick response +2. Extract `document` items for supporting documentation +3. Use the `url` field to read full page content (see Page Content API) + +#### 2. Keyword Search (Deterministic) + +**Use when:** You need exact keyword matches or when RAG is unavailable. + +```bash +curl -sG "https://agentuity.dev/api/search" \ + --data-urlencode "query=agent create" +``` + +**Response Format:** + +```json +[ + { + "id": "/guide/agents", + "type": "page", + "content": "Creating Agents", + "url": "/guide/agents" + }, + { + "id": "/guide/agents-12", + "type": "text", + "content": "Use the CLI to create a new agent...", + "url": "/guide/agents#create" + } +] +``` + +#### 3. Page Content (Full Markdown) + +**Use when:** You need the complete markdown content of a specific documentation page. + +```bash +curl -sG "https://agentuity.dev/api/page-content" \ + --data-urlencode "path=getting-started/quickstart" +``` + +**Path Format:** + +- Remove leading slash: `/getting-started/quickstart` → `getting-started/quickstart` +- Remove trailing slashes +- Remove URL fragments: `guide/install#linux` → `guide/install` +- For index pages, use just the folder name: `getting-started` resolves to `getting-started/index.mdx` + +**Convert URL to Path (one-liner):** + +```bash +PATH="$(echo "$URL" | sed -E 's#^/##; s#/+$##; s/#.*$//')" +``` + +**Response Format:** + +```json +{ + "content": "# Quickstart\n\nFull markdown content here...", + "title": "Quickstart Guide", + "description": "Get started quickly with Agentuity", + "path": "getting-started/quickstart" +} +``` + +**Path Validation:** + +- Paths cannot contain `..`, `\`, or start with `/` +- Returns 404 if page not found + +### When to Use Which API + +| Scenario | Recommended API | Reason | +| ----------------------- | ------------------------------------------ | ------------------------------------- | +| "How do I..." questions | `/api/rag-search` | AI-generated answer + supporting docs | +| Exact term search | `/api/search` | Fast, deterministic keyword matching | +| Reading specific page | `/api/page-content` | Full markdown with proper formatting | +| Error message lookup | `/api/search` | Exact text matching | +| Multi-step tutorials | `/api/rag-search` then `/api/page-content` | Get overview, then deep dive | + +### Best Practices + +1. **Start with RAG for questions:** It provides both answers and relevant documentation links +2. **Use keyword search for known terms:** When you know exactly what you're looking for +3. **Fetch full content for citations:** Always read the complete page when citing documentation +4. **Cache results:** Avoid repeated API calls for the same content +5. **Handle fallbacks:** If RAG fails, fall back to keyword search From 88a0085dbf3f9931db74d7601cfa24afa478b700 Mon Sep 17 00:00:00 2001 From: Rick Blalock <211819+rblalock@users.noreply.github.com> Date: Fri, 24 Oct 2025 14:52:12 -0400 Subject: [PATCH 2/2] Update common/js/AGENTS.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- common/js/AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common/js/AGENTS.md b/common/js/AGENTS.md index e7af868..cfcc0dc 100644 --- a/common/js/AGENTS.md +++ b/common/js/AGENTS.md @@ -111,7 +111,7 @@ Access through `context.logger`: - Use the storage APIs for persisting data - Consider agent communication for complex workflows -## 6. How to use the documentation site, it's API's, etc. +## 6. How to use the documentation site, its APIs, etc. The Agentuity documentation site provides API endpoints that AI agents can use to search and read documentation programmatically.