From 404e31f1006575eb49426d914f06f81a502ca607 Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 20:05:23 -0300 Subject: [PATCH 01/19] docs: align usage contracts and discovery surfaces --- .changeset/bright-urls-redirect.md | 5 + .changeset/quiet-errors-guide.md | 6 + .doc-bridge/capabilities.json | 2 +- .doc-bridge/index.json | 6 +- CONTRIBUTING.md | 2 +- README.md | 2 +- apps/docs-next/README.md | 49 ++--- apps/docs-next/app/(home)/page.tsx | 12 +- apps/docs-next/app/integrations/layout.tsx | 7 + apps/docs-next/app/integrations/page.tsx | 149 ++++++++++++++ apps/docs-next/app/layout.config.tsx | 3 + apps/docs-next/app/llms.txt/route.ts | 4 + apps/docs-next/app/publications/layout.tsx | 7 + apps/docs-next/app/publications/page.tsx | 108 ++++++++++ apps/docs-next/app/recipes/layout.tsx | 7 + apps/docs-next/app/recipes/page.tsx | 104 ++++++++++ apps/docs-next/app/resources/page.tsx | 9 +- apps/docs-next/app/sitemap.ts | 50 +++-- apps/docs-next/content/docs/agents/hitl.mdx | 7 +- .../content/docs/agents/skills/index.mdx | 2 +- .../content/docs/agents/skills/summarizer.mdx | 19 +- .../content/docs/agents/tools/index.mdx | 6 +- .../docs/agents/tools/integrations/index.mdx | 9 +- .../content/docs/cookbook/error-boundary.mdx | 24 ++- apps/docs-next/content/docs/cookbook/rag.mdx | 2 +- .../docs/data/memory/auto-summarize.mdx | 27 ++- .../content/docs/data/memory/file-vector.mdx | 8 +- .../content/docs/data/memory/index.mdx | 2 +- .../content/docs/data/memory/virtualized.mdx | 24 ++- .../docs/data/providers/deepseek-embedder.mdx | 2 +- .../content/docs/data/providers/embedders.mdx | 13 +- .../docs/data/providers/grok-embedder.mdx | 7 +- .../content/docs/data/providers/grok.mdx | 9 +- .../content/docs/data/providers/index.mdx | 2 +- .../docs/data/providers/kimi-embedder.mdx | 4 +- .../providers/openai-compatible-embedder.mdx | 7 +- .../docs/data/providers/openai-embedder.mdx | 4 +- .../content/docs/data/rag/chunking.mdx | 27 ++- .../docs/data/rag/context-injection.mdx | 6 +- .../content/docs/data/rag/create-rag.mdx | 24 ++- .../content/docs/data/rag/hybrid.mdx | 14 +- .../docs-next/content/docs/data/rag/index.mdx | 10 +- .../content/docs/data/rag/loaders.mdx | 29 ++- .../content/docs/data/rag/rerank.mdx | 18 +- .../docs-next/content/docs/for-agents/rag.mdx | 10 +- .../docs/get-started/concepts/errors.mdx | 44 +++- .../get-started/concepts/implementations.mdx | 14 +- .../docs/get-started/concepts/retriever.mdx | 2 +- .../get-started/migrating/from-llamaindex.mdx | 2 +- .../migrating/from-vercel-ai-sdk.mdx | 4 +- .../content/docs/production/cli/index.mdx | 2 +- .../docs/reference/contribute/rfc-process.mdx | 2 +- .../content/docs/reference/packages/cli.mdx | 4 +- .../content/docs/reference/packages/core.mdx | 33 ++- .../docs/reference/packages/overview.mdx | 12 +- .../content/docs/reference/packages/rag.mdx | 10 +- .../content/docs/reference/specs/index.mdx | 2 +- .../content/docs/reference/stability.mdx | 49 +++-- apps/docs-next/content/docs/ui/use-chat.mdx | 38 ++-- apps/docs-next/legacy-404-redirects.mjs | 10 +- apps/docs-next/lib/reference-journey.ts | 4 +- apps/docs-next/next.config.mjs | 2 +- apps/docs-next/scripts/gen-api.mjs | 5 +- .../tests/documentation-contracts.test.ts | 89 ++++++++ apps/docs-next/tests/legacy-redirects.test.ts | 58 ++++++ apps/docs-next/tests/seo-surfaces.test.ts | 191 ++++++++++++++++++ apps/docs-next/vitest.config.ts | 15 ++ packages/adapters/README.md | 8 +- packages/adapters/package.json | 2 +- packages/angular/README.md | 6 +- packages/angular/package.json | 2 +- packages/cli/README.md | 4 +- packages/cli/package.json | 2 +- packages/cli/src/init.ts | 4 +- packages/core/README.md | 25 ++- packages/core/package.json | 2 +- packages/core/src/errors.ts | 12 +- packages/core/tests/errors.test.ts | 27 ++- packages/eval-braintrust/README.md | 4 +- packages/eval-braintrust/package.json | 2 +- packages/eval/README.md | 4 +- packages/eval/package.json | 2 +- packages/ink/README.md | 4 +- packages/ink/package.json | 2 +- packages/integrations/README.md | 4 +- packages/integrations/package.json | 2 +- packages/mcp/README.md | 2 +- packages/mcp/package.json | 2 +- packages/memory/README.md | 16 +- packages/memory/package.json | 2 +- packages/observability-langfuse/README.md | 4 +- packages/observability-langfuse/package.json | 2 +- packages/observability/README.md | 4 +- packages/observability/package.json | 2 +- packages/rag/README.md | 8 +- packages/rag/package.json | 2 +- packages/rag/src/errors.ts | 4 +- packages/rag/tests/errors.test.ts | 1 + packages/react-native/README.md | 6 +- packages/react-native/package.json | 2 +- packages/react/CONVENTIONS.md | 2 +- packages/react/README.md | 4 +- packages/react/package.json | 2 +- packages/runtime/README.md | 12 +- packages/runtime/package.json | 2 +- packages/sandbox/README.md | 4 +- packages/sandbox/package.json | 2 +- packages/skills/README.md | 4 +- packages/skills/package.json | 2 +- packages/solid/README.md | 6 +- packages/solid/package.json | 2 +- packages/statechart/README.md | 2 +- packages/statechart/package.json | 2 +- packages/svelte/README.md | 6 +- packages/svelte/package.json | 2 +- packages/templates/README.md | 4 +- packages/templates/package.json | 2 +- packages/tools/README.md | 8 +- packages/tools/package.json | 2 +- packages/validation/README.md | 4 +- packages/validation/package.json | 2 +- packages/vue/README.md | 6 +- packages/vue/package.json | 2 +- 123 files changed, 1326 insertions(+), 373 deletions(-) create mode 100644 .changeset/bright-urls-redirect.md create mode 100644 .changeset/quiet-errors-guide.md create mode 100644 apps/docs-next/app/integrations/layout.tsx create mode 100644 apps/docs-next/app/integrations/page.tsx create mode 100644 apps/docs-next/app/publications/layout.tsx create mode 100644 apps/docs-next/app/publications/page.tsx create mode 100644 apps/docs-next/app/recipes/layout.tsx create mode 100644 apps/docs-next/app/recipes/page.tsx create mode 100644 apps/docs-next/tests/documentation-contracts.test.ts create mode 100644 apps/docs-next/tests/legacy-redirects.test.ts create mode 100644 apps/docs-next/tests/seo-surfaces.test.ts create mode 100644 apps/docs-next/vitest.config.ts diff --git a/.changeset/bright-urls-redirect.md b/.changeset/bright-urls-redirect.md new file mode 100644 index 00000000..17f0470c --- /dev/null +++ b/.changeset/bright-urls-redirect.md @@ -0,0 +1,5 @@ +--- +'@agentskit/integrations': patch +--- + +Point the package homepage and README at the canonical integration guide and preserve the legacy docs URL with a direct redirect. diff --git a/.changeset/quiet-errors-guide.md b/.changeset/quiet-errors-guide.md new file mode 100644 index 00000000..78fae9f6 --- /dev/null +++ b/.changeset/quiet-errors-guide.md @@ -0,0 +1,6 @@ +--- +'@agentskit/core': patch +'@agentskit/rag': patch +--- + +Point built-in and RAG errors at canonical documentation routes, and align the package and site usage guides with the current public contracts. diff --git a/.doc-bridge/capabilities.json b/.doc-bridge/capabilities.json index 820ec00f..87a1d105 100644 --- a/.doc-bridge/capabilities.json +++ b/.doc-bridge/capabilities.json @@ -7,7 +7,7 @@ "name": "AgentsKit", "root": "." }, - "contentHash": "2397c3f50a9f60e40015728086533bae9a52f8abf1079a0e11c743980d93b1b7", + "contentHash": "d1f7b23a81a82259948a00cfb2e8830fdf6e83f20c38471d7d4152f37bdafa23", "artifacts": { "index": ".doc-bridge/index.json", "llmsTxt": "llms.txt" diff --git a/.doc-bridge/index.json b/.doc-bridge/index.json index cb7a8aa4..d44c3604 100644 --- a/.doc-bridge/index.json +++ b/.doc-bridge/index.json @@ -1,8 +1,8 @@ { "schemaVersion": 1, - "contentHash": "2397c3f50a9f60e40015728086533bae9a52f8abf1079a0e11c743980d93b1b7", + "contentHash": "d1f7b23a81a82259948a00cfb2e8830fdf6e83f20c38471d7d4152f37bdafa23", "contentHashAlgo": "sha256-normalized-v1", - "generatedAt": "2026-07-17T21:27:21.575Z", + "generatedAt": "2026-08-12T22:27:54.998Z", "project": { "name": "AgentsKit", "root": "." @@ -110,7 +110,7 @@ "type": "agent-doc", "title": "rag", "path": "apps/docs-next/content/docs/for-agents/rag.mdx", - "body": "Install Primary exports - createRAG({ embed, store, chunkSize, chunkOverlap, topK, threshold }) — ingest(docs) + retrieve(request) + search(query) . - chunkText({ chunkSize, chunkOverlap, split }) — lower-level splitter. - createRerankedRetriever(base, { candidatePool, topK, rerank }) — pluggable reranker (BM25 default). See . - createHybridRetriever(base, { vectorWeight, bm25Weight }) — vector + BM25 hybrid. - bm25Score , bm25Rerank — standalone helpers. - voyageReranker(config) — Voyage AI reranker. - jinaReranker(config) — Jina AI reranker. - RagError / RagErrorCodes — typed error (extends AgentsKitError ) thrown by loaders + rerankers; narrow on error.code ( AK RAG LOAD FAILED , AK RAG PEER MISSING , AK RAG RERANK FAILED ). Document loaders - loadUrl , loadGitHubFile , loadGitHubTree , loadNotionPage , loadConfluencePage , loadGoogleDriveFile , loadPdf (BYO parser). See . - Cloud storage: loadS3 , loadGcs , loadDropbox , loadOneDrive . Failure and cancellation contract - Loader request, response-body, pagination, and total-download failures throw RagError with AK RAG LOAD FAILED . Tree loaders may return partial success only after at least one eligible document loaded. - Loader options accept signal?: AbortSignal ; Voyage and Jina reranker options accept the same additive field. - Notion and OneDrive follow provider pagination and reject repeated or missing continuation cursors instead of returning truncated content. - Scoreless Retriever results keep their order. If any score is present, all scores must be finite and the result is ordered descending; malformed mixed score sets throw. - Hybrid retrieval min-max normalizes candidate scores and normalizes relative weights before blending. Minimal example Related - — vector stores. - — embedders. Source - npm: https://www.npmjs.com/package/@agentskit/rag - repo: https://github.com/AgentsKit-io/agentskit/tree/main/packages/rag" + "body": "Install Primary exports - createRAG({ embed, store, chunkSize, chunkOverlap, topK, threshold }) — ingest(InputDocument[]) + retrieve({ query, messages }) + search(query, { topK?, threshold? }) . InputDocument uses content , not text . Chunk defaults: 512 / 50. - chunkText(text, { chunkSize, chunkOverlap, split? }) — lower-level splitter. split is (text: string) = string[] . - createRerankedRetriever(base, { candidatePool, topK, rerank }) — pluggable reranker (BM25 default). See . - createHybridRetriever(base, { vectorWeight?, bm25Weight?, topK?, candidatePool? }) — vector + BM25 hybrid; defaults to 0.6 / 0.4 , 20 candidates, and 5 results. - bm25Score , bm25Rerank — standalone helpers. - voyageReranker(config) — Voyage AI reranker. - jinaReranker(config) — Jina AI reranker. - RagError / RagErrorCodes — typed error (extends AgentsKitError ) thrown by loaders + rerankers; narrow on error.code ( AK RAG LOAD FAILED , AK RAG PEER MISSING , AK RAG RERANK FAILED ). Document loaders - loadUrl(url) — raw response text as InputDocument.content . loadGitHubFile(owner, repo, path, opts) , loadGitHubTree(owner, repo, { filter?, ... }) , loadNotionPage(pageId, { token }) , loadConfluencePage(pageId, { baseUrl, token?, authorization? }) , loadGoogleDriveFile(fileId, { accessToken }) , loadPdf(url, { parsePdf }) . All return InputDocument[] . See . - Cloud storage: loadS3 , loadGcs , loadDropbox , loadOneDrive . Failure and cancellation contract - Loader request, response-body, pagination, and total-download failures throw RagError with AK RAG LOAD FAILED . Tree loaders may return partial success only after at least one eligible document loaded. - Loader options accept signal?: AbortSignal ; Voyage and Jina reranker options accept the same additive field. - Notion and OneDrive follow provider pagination and reject repeated or missing continuation cursors instead of returning truncated content. - Scoreless Retriever results keep their order. If any score is present, all scores must be finite and the result is ordered descending; malformed mixed score sets throw. - Hybrid retrieval min-max normalizes candidate scores and normalizes relative weights before blending. Minimal example Related - — vector stores. - — embedders. Source - npm: https://www.npmjs.com/package/@agentskit/rag - repo: https://github.com/AgentsKit-io/agentskit/tree/main/packages/rag" }, { "id": "react-native", diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9876d905..116894e5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -210,7 +210,7 @@ CI runs all of these on every PR. Run them locally first to avoid burning CI min If your change affects what a consumer sees or does: - Update the relevant page in `apps/docs-next/content/docs/` -- Add a recipe if you've added a new building block (`apps/docs-next/content/docs/recipes/`) +- Add a recipe if you've added a new building block (`apps/docs-next/content/docs/reference/recipes/`) - Update the relevant ADR if you've changed how a contract behaves (rare — usually a new ADR superseding the old one) - Update the package's `README.md` if its public surface changed diff --git a/README.md b/README.md index b40f2c0f..112ba14f 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ **The agent toolkit JavaScript actually deserves.** -A 10 KB core budget. Twenty-five focused packages. Zero lock-in. Six formal contracts that make every adapter, tool, skill, memory, retriever, and runtime substitutable. +A 10 KB core budget. Twenty-two published packages. Zero lock-in. Six formal contracts that make every adapter, tool, skill, memory, retriever, and runtime substitutable. [![npm](https://img.shields.io/npm/v/@agentskit/react?label=npm)](https://www.npmjs.com/package/@agentskit/react) [![bundle](https://img.shields.io/bundlephobia/minzip/@agentskit/react?label=react%20bundle)](https://bundlephobia.com/package/@agentskit/react) diff --git a/apps/docs-next/README.md b/apps/docs-next/README.md index 00ca2476..7d637a98 100644 --- a/apps/docs-next/README.md +++ b/apps/docs-next/README.md @@ -43,27 +43,23 @@ See [CONTRIBUTING.md](../../CONTRIBUTING.md) and [LICENSE](../../LICENSE). Profile: public-app -**Spike**: Fumadocs-based documentation site, evaluated as the replacement for the existing Docusaurus app at `apps/docs`. - -Tracked by [#238](https://github.com/AgentsKit-io/agentskit/issues/238) in the Phase 0 roadmap. +Canonical Fumadocs-based documentation site for the AgentsKit package contracts, +usage guides, recipes, integrations, and ecosystem hubs. The legacy Docusaurus +app at `apps/docs` is being retired; keep new public documentation here. ## What's here -A minimal but real Fumadocs site demonstrating: +The app provides: - Next.js 16 app router with Fumadocs UI 16.x and Fumadocs MDX 14.x -- Home page (`app/(home)/page.tsx`) with hero + 3-feature grid +- Home, ecosystem, integrations, recipes, publications, and resources hubs - Docs shell (`app/docs/layout.tsx`) with Fumadocs sidebar and search - Catch-all docs page renderer (`app/docs/[[...slug]]/page.tsx`) -- Search API (`app/api/search/route.ts`) -- Real content: `index`, `getting-started/quickstart`, `getting-started/installation`, `concepts/mental-model`, plus 6 concept stub pages +- Search API (`app/api/search/route.ts`) plus `llms.txt`, sitemap, canonical metadata, and JSON-LD +- 400+ maintained MDX pages, including package guides, for-agents handoffs, recipes, and provider/integration references Tailwind v4 + `fumadocs-ui/css/preset.css` + neutral theme. -## Why parallel to `apps/docs` - -Spike, not migration. The existing Docusaurus site keeps serving traffic at the current URL. Once this Fumadocs spike is approved, a follow-up PR migrates remaining content and the `apps/docs` directory is replaced. - ## Run locally ```bash @@ -79,30 +75,15 @@ pnpm --filter @agentskit/docs-next build pnpm --filter @agentskit/docs-next start ``` -## Decision criteria for migration - -Compare against `apps/docs` (Docusaurus): - -| Criteria | Docusaurus | Fumadocs (this) | -| --- | --- | --- | -| Tech stack | React + custom build | Next.js 16 + Tailwind v4 | -| MDX rendering | OK | Excellent (server components, streaming) | -| Visual polish out-of-box | Generic | Modern, opinionated | -| Search | Algolia (paid for OSS via partner) | Built-in (Fumadocs `createFromSource`) | -| Customization | CSS hacks | Tailwind + React, native | -| Deploy target | Static (anywhere) | Vercel/Cloudflare Pages (Next.js-native) | -| i18n | Mature plugin | DIY (acceptable trade) | -| Build speed | Slow on big sites | Fast (Next.js + Turbopack) | -| Node 25 compat | Currently broken on `main` | Works | - -## Next steps if approved +## Maintainer checks -1. Port remaining sections from `apps/docs` (adapters, agents, chat-uis, components, data-layer, examples, hooks, infrastructure, packages, theming, contributing) -2. Decide i18n strategy (Crowdin? freeze pt-BR/es/zh-Hans until EN stabilizes?) -3. Set up `docs.agentskit.io` deployment on Vercel -4. Archive `apps/docs` -5. Add chat-with-docs (RAG over the docs themselves) — dogfooding moment +- `pnpm --filter @agentskit/docs-next lint:mdx` validates the MDX surface. +- `pnpm --filter @agentskit/docs-next check:links` validates internal references. +- `pnpm docs:build` runs the production build from the repository root. +- Keep package READMEs, `/docs/reference/packages`, and `/docs/for-agents` aligned when an API changes. ## Status -Not wired into root `pnpm dev` / `pnpm build` yet — install + run manually until the approach is approved. See PR description. +The app is maintained as the canonical docs surface and is available through the +root `pnpm docs` / `pnpm docs:build` scripts. Deployment remains an explicit +release action; local documentation changes do not publish automatically. diff --git a/apps/docs-next/app/(home)/page.tsx b/apps/docs-next/app/(home)/page.tsx index 7f2ae30a..21799589 100644 --- a/apps/docs-next/app/(home)/page.tsx +++ b/apps/docs-next/app/(home)/page.tsx @@ -17,7 +17,7 @@ import { alternatesFor } from '@/lib/locales' import softwareIdentity from '@/lib/software-identity.generated.json' export const metadata = { - title: `${agentsKitIdentity.name}.js — ${agentsKitIdentity.promise}`, + title: 'TypeScript AI agent framework', description: `${agentsKitIdentity.promise} A composable TypeScript foundation for runtime, tools, memory, RAG, and chat interfaces.`, alternates: { canonical: canonicalUrl('/'), @@ -131,6 +131,16 @@ function Hero() {

Built for {agentsKitIdentity.audience}

+
+ {agentsKitIdentity.role} + + {agentsKitIdentity.maturity} + {agentsKitIdentity.proof.length > 0 && ( + + {agentsKitIdentity.proof.map((claim) => `${claim.value} ${claim.noun}`).join(' · ')} + + )} +
diff --git a/apps/docs-next/app/integrations/layout.tsx b/apps/docs-next/app/integrations/layout.tsx new file mode 100644 index 00000000..a7828a39 --- /dev/null +++ b/apps/docs-next/app/integrations/layout.tsx @@ -0,0 +1,7 @@ +import { HomeLayout } from 'fumadocs-ui/layouts/home' +import type { ReactNode } from 'react' +import { baseOptions } from '../layout.config' + +export default function IntegrationsLayout({ children }: { children: ReactNode }) { + return {children} +} diff --git a/apps/docs-next/app/integrations/page.tsx b/apps/docs-next/app/integrations/page.tsx new file mode 100644 index 00000000..ec0b5df6 --- /dev/null +++ b/apps/docs-next/app/integrations/page.tsx @@ -0,0 +1,149 @@ +import type { Metadata } from 'next' +import Link from 'next/link' +import { JsonLd } from '@/components/seo/json-ld' +import { canonicalUrl } from '@/lib/canonical-url' +import { lists } from '@/lib/ecosystem-stats' +import { source } from '@/lib/source' + +const DESCRIPTION = + '50-service integration catalog for TypeScript AI agents: GitHub, Slack, Stripe, Postgres, Gmail, Notion, and more with one tool contract.' +const URL = canonicalUrl('/integrations') +const PREFIX = 'agents/tools/integrations' + +export const metadata: Metadata = { + title: 'AI agent integrations for TypeScript', + description: DESCRIPTION, + alternates: { canonical: URL }, +} + +function integrations() { + return source + .getPages() + .filter((page) => page.slugs.length === 4 && page.slugs.slice(0, 3).join('/') === PREFIX) + .sort((a, b) => a.data.title.localeCompare(b.data.title)) + .map((page) => ({ + href: page.url, + slug: page.slugs[3], + title: page.data.title, + description: page.data.description ?? 'A verified AgentsKit tool integration.', + })) +} + +export default function IntegrationsPage() { + const entries = integrations() + const guidesBySlug = new Map(entries.map((entry) => [entry.slug, entry])) + const catalog = lists.integrations.map((slug) => ({ slug, guide: guidesBySlug.get(slug) })) + const catalogGuideCount = catalog.filter((entry) => entry.guide).length + const structuredData = { + '@context': 'https://schema.org', + '@type': 'CollectionPage', + '@id': `${URL}#collection`, + url: URL, + name: 'AgentsKit integrations', + description: DESCRIPTION, + isPartOf: { '@type': 'WebSite', name: 'AgentsKit.js', url: canonicalUrl('/') }, + breadcrumb: { + '@type': 'BreadcrumbList', + itemListElement: [ + { '@type': 'ListItem', position: 1, name: 'Home', url: canonicalUrl('/') }, + { '@type': 'ListItem', position: 2, name: 'Integrations', url: canonicalUrl('/integrations') }, + ], + }, + mainEntity: { + '@type': 'ItemList', + name: 'AgentsKit documented integration guides', + numberOfItems: entries.length, + itemListElement: entries.map((entry, index) => ({ + '@type': 'ListItem', + position: index + 1, + item: { + '@type': 'TechArticle', + name: entry.title, + description: entry.description, + url: canonicalUrl(entry.href), + }, + })), + }, + additionalProperty: [ + { + '@type': 'PropertyValue', + name: 'catalogServiceCount', + value: catalog.length, + }, + { + '@type': 'PropertyValue', + name: 'documentedGuideCount', + value: catalogGuideCount, + }, + ], + } + + return ( +
+ +
+

/integrations

+

+ AI agent integrations for TypeScript +

+

+ Connect an agent to the services it already uses. Each integration follows the same install, config, and + execute contract, with the implementation details kept on its canonical documentation page. +

+

+ {catalog.length} catalog services · {catalogGuideCount} dedicated guides ·{' '} + + integration package contract + {' '} + · + tool contract + {' '} + · + author your own + +

+
+ +
    + {entries.map((entry) => ( +
  • + +

    + {entry.title} +

    +

    {entry.description}

    + Read integration → + +
    • + ))} +
+ +
+

+ Canonical service catalog +

+

+ The count below is generated from @agentskit/integrations. A linked + name has a dedicated guide on this site; an unlinked name is a catalog descriptor covered by the package + contract above, not an invented documentation page. +

+
    + {catalog.map(({ slug, guide }) => ( +
  • + {guide ? ( + + {slug} + + ) : ( + {slug} + )} +
    • + ))} +
+
+
+ ) +} diff --git a/apps/docs-next/app/layout.config.tsx b/apps/docs-next/app/layout.config.tsx index cb56d733..3b5c0456 100644 --- a/apps/docs-next/app/layout.config.tsx +++ b/apps/docs-next/app/layout.config.tsx @@ -37,6 +37,9 @@ export const baseOptions: BaseLayoutProps = { text: 'Resources', items: [ { text: 'Ecosystem resources', url: '/resources' }, + { text: 'Integrations', url: '/integrations' }, + { text: 'Recipes', url: '/recipes' }, + { text: 'Publications', url: '/publications' }, { text: 'Examples', url: '/docs/reference/examples' }, { text: 'Learn', url: '/learn' }, { text: 'Stack builder', url: '/stack' }, diff --git a/apps/docs-next/app/llms.txt/route.ts b/apps/docs-next/app/llms.txt/route.ts index 56a70947..321223d2 100644 --- a/apps/docs-next/app/llms.txt/route.ts +++ b/apps/docs-next/app/llms.txt/route.ts @@ -85,6 +85,10 @@ export function GET() { lines.push('## Optional') lines.push('') + lines.push(`- [Ecosystem hub](${SITE}/ecosystem): canonical product mesh and package matrix`) + lines.push(`- [Integrations hub](${SITE}/integrations): verified connectors for TypeScript AI agents`) + lines.push(`- [Recipes hub](${SITE}/recipes): copy-paste implementation patterns for production agents`) + lines.push(`- [Publications hub](${SITE}/publications): first-party releases and engineering deep dives`) lines.push(`- [Ecosystem resources](${SITE}/resources): verified tools, MCP registries, publications, directories, trust signals, and contributor surfaces`) lines.push(`- [Public resources JSON](${SITE}/resources.json): machine-readable projection of the curated resource catalog`) lines.push(`- [Full markdown index](${SITE}/llms-full.txt): complete text of every docs page in one file`) diff --git a/apps/docs-next/app/publications/layout.tsx b/apps/docs-next/app/publications/layout.tsx new file mode 100644 index 00000000..fc563755 --- /dev/null +++ b/apps/docs-next/app/publications/layout.tsx @@ -0,0 +1,7 @@ +import { HomeLayout } from 'fumadocs-ui/layouts/home' +import type { ReactNode } from 'react' +import { baseOptions } from '../layout.config' + +export default function PublicationsLayout({ children }: { children: ReactNode }) { + return {children} +} diff --git a/apps/docs-next/app/publications/page.tsx b/apps/docs-next/app/publications/page.tsx new file mode 100644 index 00000000..6b1d62a0 --- /dev/null +++ b/apps/docs-next/app/publications/page.tsx @@ -0,0 +1,108 @@ +import type { Metadata } from 'next' +import Link from 'next/link' +import { JsonLd } from '@/components/seo/json-ld' +import { allBlogPosts, slugOf } from '@/lib/blog' +import { canonicalUrl } from '@/lib/canonical-url' + +const DESCRIPTION = + 'Canonical AgentsKit technical publications: releases, design decisions, and engineering deep dives from the team.' +const URL = canonicalUrl('/publications') + +export const metadata: Metadata = { + title: 'AgentsKit technical publications', + description: DESCRIPTION, + alternates: { canonical: URL }, +} + +function formatDate(date: string): string { + return new Date(`${date}T00:00:00Z`).toLocaleDateString('en-US', { + year: 'numeric', + month: 'long', + day: 'numeric', + }) +} + +export default function PublicationsPage() { + const posts = allBlogPosts() + const structuredData = { + '@context': 'https://schema.org', + '@type': 'CollectionPage', + '@id': `${URL}#collection`, + url: URL, + name: 'AgentsKit technical publications', + description: DESCRIPTION, + isPartOf: { '@type': 'WebSite', name: 'AgentsKit.js', url: canonicalUrl('/') }, + breadcrumb: { + '@type': 'BreadcrumbList', + itemListElement: [ + { '@type': 'ListItem', position: 1, name: 'Home', url: canonicalUrl('/') }, + { '@type': 'ListItem', position: 2, name: 'Publications', url: canonicalUrl('/publications') }, + ], + }, + mainEntity: { + '@type': 'ItemList', + name: 'AgentsKit publications', + numberOfItems: posts.length, + itemListElement: posts.map((post, index) => ({ + '@type': 'ListItem', + position: index + 1, + item: { + '@type': 'TechArticle', + headline: post.title, + description: post.description, + datePublished: post.date, + author: { '@type': 'Person', name: post.author }, + url: canonicalUrl(`/blog/${slugOf(post)}`), + }, + })), + }, + } + + return ( +
+ +
+

/publications

+

+ Technical publications +

+

{DESCRIPTION}

+

+ First-party writing lives here. For independently published profiles, registries, and trust evidence, use{' '} + + the verified resources index + + . +

+
+ +
    + {posts.map((post) => { + const slug = slugOf(post) + return ( +
  • + +
    + {formatDate(post.date)} + · + {post.author} + {post.tags.length ? ( + <> + · + {post.tags.join(' / ')} + + ) : null} +
    +

    {post.title}

    + {post.description ?

    {post.description}

    : null} + +
    • + ) + })} +
+
+ ) +} diff --git a/apps/docs-next/app/recipes/layout.tsx b/apps/docs-next/app/recipes/layout.tsx new file mode 100644 index 00000000..1b1d808f --- /dev/null +++ b/apps/docs-next/app/recipes/layout.tsx @@ -0,0 +1,7 @@ +import { HomeLayout } from 'fumadocs-ui/layouts/home' +import type { ReactNode } from 'react' +import { baseOptions } from '../layout.config' + +export default function RecipesLayout({ children }: { children: ReactNode }) { + return {children} +} diff --git a/apps/docs-next/app/recipes/page.tsx b/apps/docs-next/app/recipes/page.tsx new file mode 100644 index 00000000..983c7ce2 --- /dev/null +++ b/apps/docs-next/app/recipes/page.tsx @@ -0,0 +1,104 @@ +import type { Metadata } from 'next' +import Link from 'next/link' +import { JsonLd } from '@/components/seo/json-ld' +import { canonicalUrl } from '@/lib/canonical-url' +import { source } from '@/lib/source' + +const DESCRIPTION = + 'Copy-paste TypeScript recipes for AI agents: provider swaps, RAG, memory, tools, MCP, multi-agent workflows, security, and evals.' +const URL = canonicalUrl('/recipes') +const PREFIX = 'reference/recipes' + +export const metadata: Metadata = { + title: 'AI agent recipes for TypeScript', + description: DESCRIPTION, + alternates: { canonical: URL }, +} + +function recipes() { + return source + .getPages() + .filter((page) => page.slugs.length === 3 && page.slugs.slice(0, 2).join('/') === PREFIX) + .sort((a, b) => a.data.title.localeCompare(b.data.title)) + .map((page) => ({ + href: page.url, + title: page.data.title, + description: page.data.description ?? 'A standalone AgentsKit implementation recipe.', + })) +} + +export default function RecipesPage() { + const entries = recipes() + const structuredData = { + '@context': 'https://schema.org', + '@type': 'CollectionPage', + '@id': `${URL}#collection`, + url: URL, + name: 'AgentsKit recipes', + description: DESCRIPTION, + isPartOf: { '@type': 'WebSite', name: 'AgentsKit.js', url: canonicalUrl('/') }, + breadcrumb: { + '@type': 'BreadcrumbList', + itemListElement: [ + { '@type': 'ListItem', position: 1, name: 'Home', url: canonicalUrl('/') }, + { '@type': 'ListItem', position: 2, name: 'Recipes', url: canonicalUrl('/recipes') }, + ], + }, + mainEntity: { + '@type': 'ItemList', + name: 'AgentsKit implementation recipes', + numberOfItems: entries.length, + itemListElement: entries.map((entry, index) => ({ + '@type': 'ListItem', + position: index + 1, + item: { + '@type': 'TechArticle', + name: entry.title, + description: entry.description, + url: canonicalUrl(entry.href), + }, + })), + }, + } + + return ( +
+ +
+

/recipes

+

+ AI agent recipes for TypeScript +

+

+ Small, end-to-end solutions for the moments that make an agent production-ready. Pick a recipe, copy the + code, and keep the underlying package contracts visible. +

+

+ {entries.length} standalone recipes · + full reference + {' '} + · + choose a use case + +

+
+ +
    + {entries.map((entry) => ( +
  • + +

    + {entry.title} +

    +

    {entry.description}

    + Open recipe → + +
    • + ))} +
+
+ ) +} diff --git a/apps/docs-next/app/resources/page.tsx b/apps/docs-next/app/resources/page.tsx index 364217a1..899b0f9b 100644 --- a/apps/docs-next/app/resources/page.tsx +++ b/apps/docs-next/app/resources/page.tsx @@ -37,7 +37,7 @@ const RESOURCE_LABELS: Record ({ url: `${SITE}/blog/${slug}`, - lastModified: now, changeFrequency: 'monthly' as const, priority: 0.6, })), ...STEPS.map((s) => ({ url: `${SITE}/learn/${s.slug}`, - lastModified: now, changeFrequency: 'weekly' as const, priority: 0.7, })), ...SHOWCASE.map((s) => ({ url: `${SITE}/showcase/${s.slug}`, - lastModified: now, changeFrequency: 'monthly' as const, priority: 0.6, })), @@ -58,7 +57,6 @@ export default function sitemap(): MetadataRoute.Sitemap { const url = slug ? `${SITE}/docs/${slug}` : `${SITE}/docs` return { url, - lastModified: now, changeFrequency: 'weekly', priority: priorityFor(slug), } diff --git a/apps/docs-next/content/docs/agents/hitl.mdx b/apps/docs-next/content/docs/agents/hitl.mdx index 14021a99..f5e9bdbf 100644 --- a/apps/docs-next/content/docs/agents/hitl.mdx +++ b/apps/docs-next/content/docs/agents/hitl.mdx @@ -1,8 +1,11 @@ --- -title: Human-in-the-loop -description: Gate tool calls behind approval. Surface reviews to humans before execution. +title: Human-in-the-loop patterns for AI agents +description: 'Practical approval patterns for TypeScript AI agents: gated tool calls, review queues, approver policies, and safe resume flows.' --- +This page is the canonical guide to human-in-the-loop approval patterns for TypeScript AI agents. +For a copy-paste recipe and UI wiring, see [HITL approvals](/docs/reference/recipes/hitl-approvals) and [ToolConfirmation](/docs/ui/tool-confirmation). + ## Gate a tool ```ts diff --git a/apps/docs-next/content/docs/agents/skills/index.mdx b/apps/docs-next/content/docs/agents/skills/index.mdx index f5d389b6..d2fa4e00 100644 --- a/apps/docs-next/content/docs/agents/skills/index.mdx +++ b/apps/docs-next/content/docs/agents/skills/index.mdx @@ -27,7 +27,7 @@ Skills with built-in refusal contracts for high-stakes use cases: - Semver range syntax: `1.2.3` / `^` / `~` / `>=` / `*`. - [Recipe: Skill marketplace](/docs/reference/recipes/skill-marketplace). -*Per-skill + marketplace deep dives land in step 6 of the docs IA rollout.* +Skill guides are linked throughout this section; use the [skill marketplace recipe](/docs/reference/recipes/skill-marketplace) for installation and versioning. ## Related diff --git a/apps/docs-next/content/docs/agents/skills/summarizer.mdx b/apps/docs-next/content/docs/agents/skills/summarizer.mdx index 5be54575..4a402a98 100644 --- a/apps/docs-next/content/docs/agents/skills/summarizer.mdx +++ b/apps/docs-next/content/docs/agents/skills/summarizer.mdx @@ -31,12 +31,19 @@ await runtime.run('Summarize this 40-page PDF into 10 bullets.') Use alongside `createAutoSummarizingMemory` to fold old turns automatically: ```ts -import { createAutoSummarizingMemory } from '@agentskit/memory' - -const memory = createAutoSummarizingMemory({ - summarize: async (msgs) => runtime.run({ input: msgs, skill: summarizer }), - triggerAt: 30, - keep: 10, +import { createAutoSummarizingMemory } from '@agentskit/core/auto-summarize' +import { createInMemoryMemory } from '@agentskit/core' + +const memory = createAutoSummarizingMemory(createInMemoryMemory(), { + maxTokens: 8_000, + keepRecent: 10, + summarizer: async msgs => ({ + id: crypto.randomUUID(), + role: 'system', + content: msgs.map(m => `${m.role}: ${m.content}`).join('\\n'), + status: 'complete', + createdAt: new Date(), + }), }) ``` diff --git a/apps/docs-next/content/docs/agents/tools/index.mdx b/apps/docs-next/content/docs/agents/tools/index.mdx index 080275c9..c92bc336 100644 --- a/apps/docs-next/content/docs/agents/tools/index.mdx +++ b/apps/docs-next/content/docs/agents/tools/index.mdx @@ -1,6 +1,6 @@ --- -title: Tools -description: Every function the agent can call. Built-ins, integrations, MCP bridge, composers. +title: AI agent tools for TypeScript +description: 'Tools for TypeScript AI agents: built-ins, integrations, MCP, and composers in @agentskit/tools.' --- ## Authoring @@ -31,7 +31,7 @@ Browser: `browserAgent` - `createMcpServer` — publish AgentsKit tools to any MCP host. - [Recipe: MCP bridge](/docs/reference/recipes/mcp-bridge). -*Per-integration pages + authoring deep dives land in step 6 of the docs IA rollout.* +Browse the [canonical integration catalog](/integrations) for all 50 service descriptors, or read the [integration package contract](/docs/for-agents/integrations) before implementing a connector. Dedicated service guides are linked from the catalog where available. ## Related diff --git a/apps/docs-next/content/docs/agents/tools/integrations/index.mdx b/apps/docs-next/content/docs/agents/tools/integrations/index.mdx index 5d8c4a06..d322d427 100644 --- a/apps/docs-next/content/docs/agents/tools/integrations/index.mdx +++ b/apps/docs-next/content/docs/agents/tools/integrations/index.mdx @@ -1,8 +1,13 @@ --- -title: Integrations -description: 50 verified connectors for the services agents actually need. Each follows the same contract — install, config, execute — and ships granular sub-tools alongside a bundled set. +title: AI agent integrations for TypeScript +description: '50-service catalog for TypeScript AI agents. Dedicated guides, package contracts, and compatibility notes for tools, connectors, and triggers.' --- +The canonical `@agentskit/integrations` package contains **50 service descriptors**. This page covers the detailed +guides available in the tools documentation; the [for-agents package guide](/docs/for-agents/integrations) describes +the full descriptor registry and projection contract. The top-level [integrations hub](/integrations) keeps both +surfaces discoverable without creating placeholder pages for services that do not yet have a dedicated guide. + ## Categories | Category | Integrations | diff --git a/apps/docs-next/content/docs/cookbook/error-boundary.mdx b/apps/docs-next/content/docs/cookbook/error-boundary.mdx index 89765ae0..ff885ab3 100644 --- a/apps/docs-next/content/docs/cookbook/error-boundary.mdx +++ b/apps/docs-next/content/docs/cookbook/error-boundary.mdx @@ -5,8 +5,11 @@ description: Surface LLM and tool errors without crashing the UI or silently hid Agents fail in interesting ways: timeouts, malformed tool args, provider outages, budget exceeded. Show the user something useful instead of a spinning loader that never ends. +`useChat` exposes `error: Error | null`. There is no `ChatError` type — narrow with `AgentsKitError` and `ErrorCodes`. + ```tsx -import { useChat, type ChatError } from '@agentskit/react' +import { useChat } from '@agentskit/react' +import { AgentsKitError, ErrorCodes } from '@agentskit/core' export function Chat() { const { messages, error, retry } = useChat({ adapter }) @@ -21,14 +24,19 @@ export function Chat() { ) } -function ErrorBox({ error, onRetry }: { error: ChatError; onRetry: () => void }) { - if (error.code === 'budget_exceeded') { - return

You hit your daily token limit. Resets at midnight UTC.

- } - if (error.code === 'tool_failed') { +function ErrorBox({ error, onRetry }: { error: Error; onRetry: () => void }) { + if (error instanceof AgentsKitError) { + if (error.code === ErrorCodes.AK_TOOL_EXEC_FAILED) { + return ( +

+ A tool couldn't run. {error.hint ?? error.message}{' '} + +

+ ) + } return (

- Action {error.toolName} couldn't run. + {error.message}

) } @@ -37,5 +45,5 @@ function ErrorBox({ error, onRetry }: { error: ChatError; onRetry: () => void }) ``` -`ChatError` is a **discriminated union**. Let TypeScript narrow each branch — never `catch (e: any)` and render `String(e)`. +`ChatReturn.error` is `Error | null`. Use `instanceof AgentsKitError` and compare `error.code` to `ErrorCodes` — never `catch (e: any)` and render `String(e)`. diff --git a/apps/docs-next/content/docs/cookbook/rag.mdx b/apps/docs-next/content/docs/cookbook/rag.mdx index 2167f832..40e6aa5c 100644 --- a/apps/docs-next/content/docs/cookbook/rag.mdx +++ b/apps/docs-next/content/docs/cookbook/rag.mdx @@ -12,7 +12,7 @@ import { fileVectorMemory } from '@agentskit/memory' const rag = createRAG({ embed: openaiEmbedder({ apiKey: process.env.OPENAI_API_KEY! }), - store: fileVectorMemory({ path: './vectors.json' }), + store: fileVectorMemory({ path: './vectors' }), }) await rag.ingest([ diff --git a/apps/docs-next/content/docs/data/memory/auto-summarize.mdx b/apps/docs-next/content/docs/data/memory/auto-summarize.mdx index 0bf6fe1f..438418cd 100644 --- a/apps/docs-next/content/docs/data/memory/auto-summarize.mdx +++ b/apps/docs-next/content/docs/data/memory/auto-summarize.mdx @@ -4,17 +4,32 @@ description: Fold oldest messages into a running summary. Token-budget-friendly. --- ```ts -import { createAutoSummarizingMemory } from '@agentskit/memory' +import { createAutoSummarizingMemory } from '@agentskit/core/auto-summarize' +import { createInMemoryMemory } from '@agentskit/core' -const memory = createAutoSummarizingMemory({ - summarize: async (msgs) => adapter.complete({ - messages: [{ role: 'system', content: 'Summarize tersely' }, ...msgs], +const memory = createAutoSummarizingMemory(createInMemoryMemory(), { + maxTokens: 8_000, + keepRecent: 6, + summarizer: async (msgs) => ({ + id: crypto.randomUUID(), + role: 'system', + content: msgs.map(m => `${m.role}: ${m.content}`).join('\n'), + status: 'complete', + createdAt: new Date(), }), - triggerAt: 30, - keep: 10, }) ``` +`createAutoSummarizingMemory` is not exported from `@agentskit/memory`. Import it from `@agentskit/core/auto-summarize` and pass a backing `ChatMemory` as the first argument. + +## Options + +| Option | Default | Purpose | +|--------|---------|---------| +| `maxTokens` | required | Budget trigger | +| `summarizer` | required | `(messages) => Message` — your compaction prompt | +| `keepRecent` | `4` | Messages always kept verbatim at the tail | + ## Related - [Recipe: auto-summarize](/docs/reference/recipes/auto-summarize) diff --git a/apps/docs-next/content/docs/data/memory/file-vector.mdx b/apps/docs-next/content/docs/data/memory/file-vector.mdx index 1bc5ea4b..75e1875a 100644 --- a/apps/docs-next/content/docs/data/memory/file-vector.mdx +++ b/apps/docs-next/content/docs/data/memory/file-vector.mdx @@ -6,7 +6,7 @@ description: Pure-JS file-persisted vector store. Zero infra. ```ts import { fileVectorMemory } from '@agentskit/memory' -const store = fileVectorMemory({ path: '.agentskit/vectors.json', dim: 1536 }) +const store = fileVectorMemory({ path: '.agentskit/vectors' }) ``` ## Options @@ -14,8 +14,10 @@ const store = fileVectorMemory({ path: '.agentskit/vectors.json', dim: 1536 }) | Option | Type | Default | |---|---|---| | `path` | `string` | required | -| `dim` | `number` | required | -| `metric` | `'cosine' \| 'dot' \| 'euclidean'` | `cosine` | +| `store` | `VectorStore` | Vectra-backed on-disk store | + +`path` names a Vectra index directory. Install the optional `vectra` peer for +the default on-disk store, or provide a custom `VectorStore` implementation. ## Scale diff --git a/apps/docs-next/content/docs/data/memory/index.mdx b/apps/docs-next/content/docs/data/memory/index.mdx index 16ebc03b..8a18084d 100644 --- a/apps/docs-next/content/docs/data/memory/index.mdx +++ b/apps/docs-next/content/docs/data/memory/index.mdx @@ -29,7 +29,7 @@ description: Chat memory + vector stores + wrappers that make long-running agent - `createInMemoryGraph` — knowledge graph (nodes + edges). [Recipe](/docs/reference/recipes/graph-memory). - `createInMemoryPersonalization` — per-subject profile. [Recipe](/docs/reference/recipes/personalization). -*Per-backend deep dives land in step 4 of the docs IA rollout.* +Backend-specific guides are available in this section; start with the [vector memory adapters recipe](/docs/reference/recipes/vector-adapters) when you need a provider-neutral path. ## Related diff --git a/apps/docs-next/content/docs/data/memory/virtualized.mdx b/apps/docs-next/content/docs/data/memory/virtualized.mdx index 6f793e67..5ea066c4 100644 --- a/apps/docs-next/content/docs/data/memory/virtualized.mdx +++ b/apps/docs-next/content/docs/data/memory/virtualized.mdx @@ -4,15 +4,29 @@ description: Hot-window + cold retriever. Keep recent messages; retrieve old one --- ```ts -import { createVirtualizedMemory } from '@agentskit/memory' +import { createInMemoryMemory, createVirtualizedMemory } from '@agentskit/core' -const memory = createVirtualizedMemory({ - window: 20, - cold: vectorStore, - embed: openaiEmbedder({ apiKey }), +const backing = createInMemoryMemory() +const memory = createVirtualizedMemory(backing, { + maxActive: 50, + maxRetrieved: 5, + retriever: async ({ hot, cold, maxRetrieved }) => { + // return up to maxRetrieved older messages to splice back in + return cold.slice(-maxRetrieved) + }, }) ``` +`createVirtualizedMemory` ships in `@agentskit/core`, not `@agentskit/memory`. The first argument is the backing `ChatMemory`. + +## Options + +| Option | Default | Purpose | +|--------|---------|---------| +| `maxActive` | `50` | Recent messages always loaded | +| `retriever` | — | `( { hot, cold, maxRetrieved } ) => Message[]` — optional cold lookup | +| `maxRetrieved` | `10` | Cap on retrieved cold messages | + ## When to use Long-running sessions where most context is stale but some old turns diff --git a/apps/docs-next/content/docs/data/providers/deepseek-embedder.mdx b/apps/docs-next/content/docs/data/providers/deepseek-embedder.mdx index a4ac3f79..6dfe0e67 100644 --- a/apps/docs-next/content/docs/data/providers/deepseek-embedder.mdx +++ b/apps/docs-next/content/docs/data/providers/deepseek-embedder.mdx @@ -16,7 +16,7 @@ const embed = deepseekEmbedder({ | Option | Type | Default | |---|---|---| | `apiKey` | `string` | required | -| `model` | `string` | provider default | +| `model` | `string` | required | | `baseUrl` | `string` | `https://api.deepseek.com` | ## Related diff --git a/apps/docs-next/content/docs/data/providers/embedders.mdx b/apps/docs-next/content/docs/data/providers/embedders.mdx index 23fc6e9e..43b03800 100644 --- a/apps/docs-next/content/docs/data/providers/embedders.mdx +++ b/apps/docs-next/content/docs/data/providers/embedders.mdx @@ -8,18 +8,15 @@ description: Turn text into vectors. Used by RAG + vector memory. | [OpenAI](./openai-embedder) | `openaiEmbedder` | `text-embedding-3-small`, `...-large` | | [Gemini](./gemini-embedder) | `geminiEmbedder` | `text-embedding-004` | | [Ollama](./ollama-embedder) | `ollamaEmbedder` | `nomic-embed-text`, `mxbai-embed-large` | -| [DeepSeek](./deepseek-embedder) | `deepseekEmbedder` | provider defaults | -| [Grok](./grok-embedder) | `grokEmbedder` | provider defaults | -| [Kimi](./kimi-embedder) | `kimiEmbedder` | provider defaults | +| [DeepSeek](./deepseek-embedder) | `deepseekEmbedder` | pass the provider model | +| [Grok](./grok-embedder) | `grokEmbedder` | pass the provider model | +| [Kimi](./kimi-embedder) | `kimiEmbedder` | pass the provider model | | [OpenAI-compatible](./openai-compatible-embedder) | `createOpenAICompatibleEmbedder` | any `/v1/embeddings` endpoint | ## Contract ```ts -type Embedder = { - embed: (texts: string[]) => Promise - dim: number -} +type EmbedFn = (text: string) => Promise ``` ## Usage @@ -27,7 +24,7 @@ type Embedder = { ```ts import { openaiEmbedder } from '@agentskit/adapters' -const embed = openaiEmbedder({ +const embed: EmbedFn = openaiEmbedder({ apiKey: process.env.OPENAI_API_KEY!, model: 'text-embedding-3-small', }) diff --git a/apps/docs-next/content/docs/data/providers/grok-embedder.mdx b/apps/docs-next/content/docs/data/providers/grok-embedder.mdx index d22233f6..d212bf5c 100644 --- a/apps/docs-next/content/docs/data/providers/grok-embedder.mdx +++ b/apps/docs-next/content/docs/data/providers/grok-embedder.mdx @@ -1,6 +1,6 @@ --- title: grokEmbedder -description: xAI embedding model. +description: xAI embedding models through the OpenAI-compatible embeddings API. --- ```ts @@ -8,6 +8,7 @@ import { grokEmbedder } from '@agentskit/adapters' const embed = grokEmbedder({ apiKey: process.env.XAI_API_KEY!, + model: 'grok-embed-model', }) ``` @@ -16,8 +17,8 @@ const embed = grokEmbedder({ | Option | Type | Default | |---|---|---| | `apiKey` | `string` | required | -| `model` | `string` | provider default | -| `baseUrl` | `string` | `https://api.x.ai/v1` | +| `model` | `string` | required | +| `baseUrl` | `string` | `https://api.x.ai` | ## Related diff --git a/apps/docs-next/content/docs/data/providers/grok.mdx b/apps/docs-next/content/docs/data/providers/grok.mdx index 15d07990..2588acef 100644 --- a/apps/docs-next/content/docs/data/providers/grok.mdx +++ b/apps/docs-next/content/docs/data/providers/grok.mdx @@ -1,6 +1,6 @@ --- -title: grok -description: xAI Grok — streaming chat + tool calls. OpenAI-compatible API surface. +title: Grok provider for TypeScript AI agents +description: Use xAI Grok with a TypeScript AI agent using AgentsKit's OpenAI-compatible adapter, streaming, and tool calls. --- ```ts @@ -18,8 +18,9 @@ const adapter = grok({ |---|---|---| | `apiKey` | `string` | required | | `model` | `string` | required | -| `baseUrl` | `string` | `https://api.x.ai/v1` | -| `fetch` | `typeof fetch` | global | +| `baseUrl` | `string` | `https://api.x.ai` | +| `includeUsage` | `boolean` | adapter default | +| `retry` | `RetryOptions` | adapter defaults | ## Model examples diff --git a/apps/docs-next/content/docs/data/providers/index.mdx b/apps/docs-next/content/docs/data/providers/index.mdx index 825ec5ef..bce4266d 100644 --- a/apps/docs-next/content/docs/data/providers/index.mdx +++ b/apps/docs-next/content/docs/data/providers/index.mdx @@ -31,7 +31,7 @@ Numbers on this site always mean one of those layers — never mix them without - `createEnsembleAdapter` — fan-out + merge. [Recipe](/docs/reference/recipes/adapter-ensemble). - `createFallbackAdapter` — ordered try-next. [Recipe](/docs/reference/recipes/fallback-chain). -*Per-provider pages land in step 4 of the docs IA rollout.* +Provider-specific pages are available in this section; start with [choosing an adapter](./choosing) when the model or hosting surface is not decided yet. ## Related diff --git a/apps/docs-next/content/docs/data/providers/kimi-embedder.mdx b/apps/docs-next/content/docs/data/providers/kimi-embedder.mdx index 7ca62b1b..d18cfc4e 100644 --- a/apps/docs-next/content/docs/data/providers/kimi-embedder.mdx +++ b/apps/docs-next/content/docs/data/providers/kimi-embedder.mdx @@ -16,8 +16,8 @@ const embed = kimiEmbedder({ | Option | Type | Default | |---|---|---| | `apiKey` | `string` | required | -| `model` | `string` | provider default | -| `baseUrl` | `string` | `https://api.moonshot.cn/v1` | +| `model` | `string` | required | +| `baseUrl` | `string` | `https://api.moonshot.ai` | ## Related diff --git a/apps/docs-next/content/docs/data/providers/openai-compatible-embedder.mdx b/apps/docs-next/content/docs/data/providers/openai-compatible-embedder.mdx index fa93617f..ff05b9e5 100644 --- a/apps/docs-next/content/docs/data/providers/openai-compatible-embedder.mdx +++ b/apps/docs-next/content/docs/data/providers/openai-compatible-embedder.mdx @@ -6,9 +6,8 @@ description: Escape hatch for any OpenAI-compatible `/v1/embeddings` endpoint ```ts import { createOpenAICompatibleEmbedder } from '@agentskit/adapters' -const embed = createOpenAICompatibleEmbedder({ +const embed = createOpenAICompatibleEmbedder('Voyage', 'https://api.voyageai.com')({ apiKey: process.env.VOYAGE_API_KEY!, - baseUrl: 'https://api.voyageai.com/v1', model: 'voyage-3-large', }) ``` @@ -18,10 +17,8 @@ const embed = createOpenAICompatibleEmbedder({ | Option | Type | Default | |---|---|---| | `apiKey` | `string` | required (unless the endpoint is keyless) | -| `baseUrl` | `string` | required | +| `baseUrl` | `string` | provider default; omit or override | | `model` | `string` | required | -| `dimensions` | `number` | — | -| `fetch` | `typeof fetch` | global | ## Use cases diff --git a/apps/docs-next/content/docs/data/providers/openai-embedder.mdx b/apps/docs-next/content/docs/data/providers/openai-embedder.mdx index 946e1493..7173f309 100644 --- a/apps/docs-next/content/docs/data/providers/openai-embedder.mdx +++ b/apps/docs-next/content/docs/data/providers/openai-embedder.mdx @@ -18,9 +18,7 @@ const embed = openaiEmbedder({ |---|---|---| | `apiKey` | `string` | required | | `model` | `string` | `text-embedding-3-small` | -| `dimensions` | `number` | model default | -| `baseUrl` | `string` | `https://api.openai.com/v1` | -| `fetch` | `typeof fetch` | global | +| `baseUrl` | `string` | `https://api.openai.com` | ## Models diff --git a/apps/docs-next/content/docs/data/rag/chunking.mdx b/apps/docs-next/content/docs/data/rag/chunking.mdx index c5a3fa63..277ea05e 100644 --- a/apps/docs-next/content/docs/data/rag/chunking.mdx +++ b/apps/docs-next/content/docs/data/rag/chunking.mdx @@ -9,7 +9,16 @@ import { chunkText } from '@agentskit/rag' const chunks = chunkText(longDoc, { chunkSize: 800, chunkOverlap: 120, - split: 'paragraph', +}) +``` + +`chunkText(text, options)` returns `string[]`. Pass a custom `split` when you want your own boundaries instead of the default sliding window: + +```ts +const paragraphs = chunkText(longDoc, { + chunkSize: 800, + chunkOverlap: 120, + split: text => text.split(/\n\n+/), }) ``` @@ -17,15 +26,19 @@ const chunks = chunkText(longDoc, { | Option | Type | Default | |---|---|---| -| `chunkSize` | `number` | `1000` | -| `chunkOverlap` | `number` | `100` | -| `split` | `'sentence' \| 'paragraph' \| 'markdown' \| 'code' \| 'char'` | `paragraph` | +| `chunkSize` | `number` | required (`createRAG` default: `512`) | +| `chunkOverlap` | `number` | required (`createRAG` default: `50`) | +| `split` | `(text: string) => string[]` | omitted — sliding window over whitespace | + +Standalone `chunkText` has no built-in size defaults. When you go through [createRAG](./create-rag), unspecified `chunkSize` / `chunkOverlap` become 512 / 50. + +If `split` is provided, its return value is used as-is (empty strings dropped). `chunkSize` and `chunkOverlap` then apply only to the default splitter. ## Rules of thumb -- Prose: `paragraph`, 800/120. -- Markdown: `markdown`, 1200/150. -- Code: `code`, 1500/0. +- Prose: 800 / 120. +- Markdown: 1200 / 150. +- Code: 1500 / 0. ## Related diff --git a/apps/docs-next/content/docs/data/rag/context-injection.mdx b/apps/docs-next/content/docs/data/rag/context-injection.mdx index 03a4e39b..c51b0a08 100644 --- a/apps/docs-next/content/docs/data/rag/context-injection.mdx +++ b/apps/docs-next/content/docs/data/rag/context-injection.mdx @@ -30,7 +30,7 @@ import { fileVectorMemory } from '@agentskit/memory' const rag = createRAG({ embed: openaiEmbedder({ apiKey: process.env.OPENAI_API_KEY! }), - store: fileVectorMemory({ path: '.agentskit/vec.json', dim: 1536 }), + store: fileVectorMemory({ path: '.agentskit/vectors' }), }) function formatContext(hits: Awaited>): string { @@ -52,7 +52,7 @@ const systemPrompt = [ ].filter(Boolean).join('\n\n') ``` -Pass `systemPrompt` as the `system` field to your adapter or `createRuntime` call. +Pass `systemPrompt` as the `systemPrompt` field to your adapter or `createRuntime` call. ## Runtime integration — pass `retriever` directly @@ -68,7 +68,7 @@ await rag.ingest(myDocs) const runtime = createRuntime({ adapter, retriever: rag, // implements Retriever contract - system: 'You are a helpful assistant.', + systemPrompt: 'You are a helpful assistant.', }) const result = await runtime.run('How does token budgeting work?') diff --git a/apps/docs-next/content/docs/data/rag/create-rag.mdx b/apps/docs-next/content/docs/data/rag/create-rag.mdx index 13339489..d74b76a9 100644 --- a/apps/docs-next/content/docs/data/rag/create-rag.mdx +++ b/apps/docs-next/content/docs/data/rag/create-rag.mdx @@ -10,26 +10,32 @@ import { fileVectorMemory } from '@agentskit/memory' const rag = createRAG({ embed: openaiEmbedder({ apiKey: process.env.OPENAI_API_KEY! }), - store: fileVectorMemory({ path: '.agentskit/vec.json', dim: 1536 }), + store: fileVectorMemory({ path: '.agentskit/vectors' }), }) -await rag.ingest([{ id: 'doc-1', text: longDoc }]) -const hits = await rag.retrieve('How does token budgeting work?') +await rag.ingest([{ id: 'doc-1', content: longDoc }]) +const hits = await rag.retrieve({ + query: 'How does token budgeting work?', + messages: [], +}) ``` +`ingest` takes `InputDocument[]` — the text field is `content`, not `text`. + ## API | Method | Purpose | |---|---| -| `ingest(docs, opts?)` | chunk + embed + store | -| `retrieve(query, opts?)` | vector top-k | -| `search(query, opts?)` | alias for retrieve with filters | -| `delete(ids)` | remove docs | +| `ingest(docs)` | chunk + embed + store | +| `retrieve({ query, messages })` | `Retriever` contract — uses `query` | +| `search(query, { topK?, threshold? })` | vector search with optional overrides | + +`retrieve` and `search` both return `RetrievedDocument[]`. Use `retrieve` when you need the contract (runtime, rerank wrappers). Use `search` when you already have a query string. ## Options -- `chunkSize` / `chunkOverlap` / `split` — passed to [chunking](./chunking). -- `topK` — default retrieve count. +- `chunkSize` / `chunkOverlap` / `split` — passed to [chunking](./chunking). Defaults: `chunkSize` 512, `chunkOverlap` 50. `split` is an optional `(text: string) => string[]`. +- `topK` / `threshold` — defaults for `search` (and therefore `retrieve`). ## Related diff --git a/apps/docs-next/content/docs/data/rag/hybrid.mdx b/apps/docs-next/content/docs/data/rag/hybrid.mdx index 3019fe85..c665260c 100644 --- a/apps/docs-next/content/docs/data/rag/hybrid.mdx +++ b/apps/docs-next/content/docs/data/rag/hybrid.mdx @@ -3,13 +3,19 @@ title: Hybrid search description: Vector + BM25 blend with weighted normalization. --- +`baseRetriever` is any Retriever that already produces vector candidates. + +`createHybridRetriever(base, { vectorWeight?, bm25Weight?, topK?, candidatePool? })` +returns a Retriever. Weights are relative and normalized before blending (defaults +to `0.6` vector / `0.4` BM25); it considers up to 20 candidates and returns 5 by +default. If both weights are zero, the blend uses `0.5` / `0.5`. + ```ts import { createHybridRetriever } from '@agentskit/rag' -const retriever = createHybridRetriever({ - vector: rag, - lexical: bm25Index, - weights: { vector: 0.7, lexical: 0.3 }, +const hybrid = createHybridRetriever(baseRetriever, { + vectorWeight: 0.7, + bm25Weight: 0.3, }) ``` diff --git a/apps/docs-next/content/docs/data/rag/index.mdx b/apps/docs-next/content/docs/data/rag/index.mdx index 824bd771..9dea07ba 100644 --- a/apps/docs-next/content/docs/data/rag/index.mdx +++ b/apps/docs-next/content/docs/data/rag/index.mdx @@ -7,21 +7,21 @@ Want a working RAG agent rather than wiring the pipeline yourself? The [Registry ## Core pipeline -- `createRAG({ embed, store })` — one-liner ingest + retrieve + search. -- `chunkText({ chunkSize, chunkOverlap, split })` — standalone splitter. +- `createRAG({ embed, store })` — one-liner ingest + retrieve + search. Defaults: `chunkSize` 512, `chunkOverlap` 50. +- `chunkText(text, { chunkSize, chunkOverlap, split? })` — standalone splitter. `split` is an optional `(text: string) => string[]`. ## Reranking + hybrid -- `createRerankedRetriever` — plug in Cohere Rerank, BGE, or the built-in BM25. +- `createRerankedRetriever(base, { candidatePool?, topK?, rerank? })` — plug in `voyageReranker`, `jinaReranker`, or the built-in `bm25Rerank`. - `createHybridRetriever` — vector + BM25 blend with weighted normalization. - [Recipe: RAG reranking](/docs/reference/recipes/rag-reranking). ## Document loaders -- `loadUrl`, `loadGitHubFile`, `loadGitHubTree`, `loadNotionPage`, `loadConfluencePage`, `loadGoogleDriveFile`, `loadPdf` (BYO parser). +- `loadUrl` (raw response text), `loadGitHubFile`, `loadGitHubTree`, `loadNotionPage`, `loadConfluencePage`, `loadGoogleDriveFile`, `loadPdf` (BYO parser). All return `InputDocument[]`. - [Recipe: Document loaders](/docs/reference/recipes/doc-loaders). -*Per-loader + per-reranker deep dives land in step 4 of the docs IA rollout.* +Loader and reranker guides are available through the [document loaders recipe](/docs/reference/recipes/doc-loaders) and [RAG reranking recipe](/docs/reference/recipes/rag-reranking). ## Related diff --git a/apps/docs-next/content/docs/data/rag/loaders.mdx b/apps/docs-next/content/docs/data/rag/loaders.mdx index 9710d4b6..44f4deff 100644 --- a/apps/docs-next/content/docs/data/rag/loaders.mdx +++ b/apps/docs-next/content/docs/data/rag/loaders.mdx @@ -3,7 +3,7 @@ title: Document loaders description: Fetch + normalize documents from URLs, GitHub, Notion, Confluence, Google Drive, S3, GCS, Dropbox, OneDrive, PDFs. --- -All loaders return `LoadedDocument[]` ready for `rag.ingest`. +All loaders return `InputDocument[]` ready for `rag.ingest`. `loadUrl` puts the raw response body in `content` — no boilerplate stripping. ## URL @@ -12,15 +12,18 @@ import { loadUrl } from '@agentskit/rag' const docs = await loadUrl('https://example.com/post') ``` -Strips boilerplate; keeps main content + title. +`docs[0].content` is the raw response text (HTML or otherwise). Pipe it into `rag.ingest` as-is, or clean it first. ## GitHub ```ts import { loadGitHubFile, loadGitHubTree } from '@agentskit/rag' -const single = await loadGitHubFile({ owner, repo, path: 'README.md', ref: 'main' }) -const tree = await loadGitHubTree({ owner, repo, ref: 'main', include: ['**/*.md'] }) +const single = await loadGitHubFile(owner, repo, 'README.md', { ref: 'main' }) +const tree = await loadGitHubTree(owner, repo, { + ref: 'main', + filter: path => path.endsWith('.md'), +}) ``` Requires `GITHUB_TOKEN` for private repos. @@ -29,21 +32,24 @@ Requires `GITHUB_TOKEN` for private repos. ```ts import { loadNotionPage } from '@agentskit/rag' -const docs = await loadNotionPage({ token: process.env.NOTION_TOKEN!, pageId }) +const docs = await loadNotionPage(pageId, { token: process.env.NOTION_TOKEN! }) ``` ## Confluence ```ts import { loadConfluencePage } from '@agentskit/rag' -const docs = await loadConfluencePage({ baseUrl, auth, pageId }) +const docs = await loadConfluencePage(pageId, { + baseUrl, + token, // or authorization +}) ``` ## Google Drive ```ts import { loadGoogleDriveFile } from '@agentskit/rag' -const docs = await loadGoogleDriveFile({ fileId, accessToken }) +const docs = await loadGoogleDriveFile(fileId, { accessToken }) ``` ## S3 (and S3-compatible: R2, MinIO) @@ -112,7 +118,14 @@ Walks the drive children recursively, follows `@microsoft.graph.downloadUrl` for ```ts import { loadPdf } from '@agentskit/rag' -const docs = await loadPdf({ buffer, parse: myPdfParse }) +import pdfParse from 'pdf-parse' + +const docs = await loadPdf('https://example.com/report.pdf', { + parsePdf: async bytes => { + const result = await pdfParse(Buffer.from(bytes)) + return { text: result.text, pages: result.numpages } + }, +}) ``` BYO parser (e.g. `pdf-parse`, `unpdf`) to keep core deps zero. diff --git a/apps/docs-next/content/docs/data/rag/rerank.mdx b/apps/docs-next/content/docs/data/rag/rerank.mdx index 82557dfc..8f9d2b67 100644 --- a/apps/docs-next/content/docs/data/rag/rerank.mdx +++ b/apps/docs-next/content/docs/data/rag/rerank.mdx @@ -1,26 +1,28 @@ --- title: Rerank -description: Post-retrieval reranker. Cohere / BGE / built-in BM25. +description: Post-retrieval reranker. Voyage / Jina / built-in BM25. --- ```ts -import { createRerankedRetriever, cohereReranker } from '@agentskit/rag' +import { createRerankedRetriever, voyageReranker } from '@agentskit/rag' -const retriever = createRerankedRetriever({ - retriever: rag, - rerank: cohereReranker({ apiKey: process.env.COHERE_API_KEY! }), - topN: 5, +const retriever = createRerankedRetriever(rag, { + candidatePool: 20, + topK: 5, + rerank: voyageReranker({ apiKey: process.env.VOYAGE_API_KEY! }), }) ``` +`createRerankedRetriever(base, { candidatePool?, topK?, rerank? })` pulls `candidatePool` hits from the base retriever (default 20), re-scores them, and returns `topK` (default 5). Omit `rerank` and the default is `bm25Rerank`. + ## Rerankers -- `cohereReranker({ apiKey, model? })` — Cohere Rerank. -- `bgeReranker({ url, model? })` — self-hosted BGE cross-encoder. - `voyageReranker({ apiKey, model? })` — Voyage AI; defaults to `rerank-2`. Pass `rerank-2-lite` for cheaper / faster runs. - `jinaReranker({ apiKey, model? })` — Jina AI; defaults to `jina-reranker-v2-base-multilingual`. - `bm25Rerank` — zero-dep fallback. +There is no `cohereReranker` or `bgeReranker` export. To call Cohere, BGE, or anything else, pass a custom `RerankFn` — see [Recipe: RAG reranking](/docs/reference/recipes/rag-reranking). + All rerankers are drop-in `RerankFn` values — they share the same `createRerankedRetriever` API so you can swap them without changing call sites. ## Related diff --git a/apps/docs-next/content/docs/for-agents/rag.mdx b/apps/docs-next/content/docs/for-agents/rag.mdx index 254d9b95..2afff562 100644 --- a/apps/docs-next/content/docs/for-agents/rag.mdx +++ b/apps/docs-next/content/docs/for-agents/rag.mdx @@ -11,10 +11,10 @@ npm install @agentskit/rag ## Primary exports -- `createRAG({ embed, store, chunkSize, chunkOverlap, topK, threshold })` — `ingest(docs)` + `retrieve(request)` + `search(query)`. -- `chunkText({ chunkSize, chunkOverlap, split })` — lower-level splitter. +- `createRAG({ embed, store, chunkSize, chunkOverlap, topK, threshold })` — `ingest(InputDocument[])` + `retrieve({ query, messages })` + `search(query, { topK?, threshold? })`. `InputDocument` uses `content`, not `text`. Chunk defaults: 512 / 50. +- `chunkText(text, { chunkSize, chunkOverlap, split? })` — lower-level splitter. `split` is `(text: string) => string[]`. - `createRerankedRetriever(base, { candidatePool, topK, rerank })` — pluggable reranker (BM25 default). See [RAG reranking](/docs/reference/recipes/rag-reranking). -- `createHybridRetriever(base, { vectorWeight, bm25Weight })` — vector + BM25 hybrid. +- `createHybridRetriever(base, { vectorWeight?, bm25Weight?, topK?, candidatePool? })` — vector + BM25 hybrid; defaults to `0.6` / `0.4`, 20 candidates, and 5 results. - `bm25Score`, `bm25Rerank` — standalone helpers. - `voyageReranker(config)` — Voyage AI reranker. - `jinaReranker(config)` — Jina AI reranker. @@ -22,7 +22,7 @@ npm install @agentskit/rag ### Document loaders -- `loadUrl`, `loadGitHubFile`, `loadGitHubTree`, `loadNotionPage`, `loadConfluencePage`, `loadGoogleDriveFile`, `loadPdf` (BYO parser). See [Doc loaders](/docs/reference/recipes/doc-loaders). +- `loadUrl(url)` — raw response text as `InputDocument.content`. `loadGitHubFile(owner, repo, path, opts)`, `loadGitHubTree(owner, repo, { filter?, ... })`, `loadNotionPage(pageId, { token })`, `loadConfluencePage(pageId, { baseUrl, token?, authorization? })`, `loadGoogleDriveFile(fileId, { accessToken })`, `loadPdf(url, { parsePdf })`. All return `InputDocument[]`. See [Doc loaders](/docs/reference/recipes/doc-loaders). - Cloud storage: `loadS3`, `loadGcs`, `loadDropbox`, `loadOneDrive`. ## Failure and cancellation contract @@ -49,7 +49,7 @@ import { openaiEmbedder } from '@agentskit/adapters' const rag = createRAG({ embed: openaiEmbedder({ apiKey }), - store: fileVectorMemory({ path: './kb.json' }), + store: fileVectorMemory({ path: './kb-vectors' }), }) await rag.ingest(await loadGitHubTree('org', 'repo', { token })) diff --git a/apps/docs-next/content/docs/get-started/concepts/errors.mdx b/apps/docs-next/content/docs/get-started/concepts/errors.mdx index 66058175..a9ec50cb 100644 --- a/apps/docs-next/content/docs/get-started/concepts/errors.mdx +++ b/apps/docs-next/content/docs/get-started/concepts/errors.mdx @@ -23,7 +23,7 @@ class AgentsKitError extends Error { ``` error[AK_ADAPTER_MISSING]: No adapter provided --> Hint: Pass an adapter when creating the chat controller, e.g. - createChatController({ adapter: openaiAdapter() }) + createChatController({ adapter: openai({ apiKey, model: 'gpt-4o' }) }) --> Docs: https://www.agentskit.io/docs/data/providers ``` @@ -33,10 +33,13 @@ All errors extend `AgentsKitError`. The subclasses set a default `docsUrl` for t | Class | Default docs link | Thrown when | |-------|-------------------|-------------| -| `AdapterError` | `/docs/data/providers` | Adapter is missing or a stream call fails | -| `ToolError` | `/docs/agents/tools` | A tool is not found or `execute` throws | -| `MemoryError` | `/docs/data/memory` | Memory load, save, or deserialization fails | -| `ConfigError` | `/docs/get-started/getting-started/installation` | Required configuration is absent or invalid | +| `AdapterError` | `/docs/data/providers` | An adapter is missing or a provider stream fails | +| `ToolError` | `/docs/agents/tools` | A tool is missing, forbidden, invalid, or its `execute` call fails | +| `MemoryError` | `/docs/data/memory` | Memory load, save, deserialization, or backend access fails | +| `ConfigError` | `/docs/get-started/concepts/errors` | Required configuration is absent or invalid | +| `RuntimeError` | `/docs/agents/runtime` | Runtime input, step, or delegation fails | +| `SandboxError` | `/docs/production/security/mandatory-sandbox` | Sandbox policy, backend, or peer setup fails | +| `SkillError` | `/docs/agents/skills` | A skill is invalid or duplicated | ## ErrorCodes @@ -52,14 +55,45 @@ ErrorCodes.AK_ADAPTER_STREAM_FAILED // provider streaming call failed // Tool errors ErrorCodes.AK_TOOL_NOT_FOUND // tool name not registered ErrorCodes.AK_TOOL_EXEC_FAILED // execute() threw +ErrorCodes.AK_TOOL_PEER_MISSING // optional tool peer is not installed +ErrorCodes.AK_TOOL_INVALID_INPUT // tool arguments or proposal are invalid +ErrorCodes.AK_TOOL_QUOTA_EXCEEDED // tool execution exceeds its configured quota +ErrorCodes.AK_TOOL_FORBIDDEN // tool execution is denied by policy // Memory errors ErrorCodes.AK_MEMORY_LOAD_FAILED // memory.load() failed ErrorCodes.AK_MEMORY_SAVE_FAILED // memory.save() failed ErrorCodes.AK_MEMORY_DESERIALIZE_FAILED // persisted state is corrupt +ErrorCodes.AK_MEMORY_PEER_MISSING // optional memory backend is not installed +ErrorCodes.AK_MEMORY_REMOTE_HTTP // remote memory request failed // Config errors ErrorCodes.AK_CONFIG_INVALID // missing or wrong type in config + +// Runtime errors +ErrorCodes.AK_RUNTIME_INVALID_INPUT // runtime input is invalid +ErrorCodes.AK_RUNTIME_STEP_FAILED // a runtime step failed +ErrorCodes.AK_RUNTIME_DELEGATE_FAILED // delegated agent execution failed + +// Sandbox errors +ErrorCodes.AK_SANDBOX_DENIED // sandbox policy denied execution +ErrorCodes.AK_SANDBOX_INVALID_TOOL // tool is not valid for the sandbox +ErrorCodes.AK_SANDBOX_PEER_MISSING // optional sandbox backend is not installed +ErrorCodes.AK_SANDBOX_BACKEND_FAILED // sandbox backend failed + +// Skill errors +ErrorCodes.AK_SKILL_INVALID // skill definition is invalid +ErrorCodes.AK_SKILL_DUPLICATE // skill identity is duplicated +``` + +RAG-specific failures are exported by `@agentskit/rag`, not by core: + +```ts +import { RagErrorCodes } from '@agentskit/rag' + +RagErrorCodes.AK_RAG_LOAD_FAILED // loader request, body, or pagination failed +RagErrorCodes.AK_RAG_PEER_MISSING // optional loader peer is not installed +RagErrorCodes.AK_RAG_RERANK_FAILED // reranker request or output was invalid ``` ## Catching and narrowing diff --git a/apps/docs-next/content/docs/get-started/concepts/implementations.mdx b/apps/docs-next/content/docs/get-started/concepts/implementations.mdx index 500bf7b7..6fb2f34a 100644 --- a/apps/docs-next/content/docs/get-started/concepts/implementations.mdx +++ b/apps/docs-next/content/docs/get-started/concepts/implementations.mdx @@ -78,16 +78,18 @@ and the [tool ecosystem](/docs/agents/tools/integrations). [chroma](/docs/data/memory/chroma) · [upstash](/docs/data/memory/upstash-vector) -**Wrappers:** `createEncryptedMemory`, `createHierarchicalMemory`, -`createVirtualizedMemory`, `createAutoSummarizingMemory`, +**Wrappers (memory):** `createEncryptedMemory`, `createHierarchicalMemory`, `createInMemoryGraph`, `createInMemoryPersonalization` — [encrypted](/docs/data/memory/encrypted) · [hierarchical](/docs/data/memory/hierarchical) · -[virtualized](/docs/data/memory/virtualized) · -[auto-summarize](/docs/data/memory/auto-summarize) · [graph](/docs/data/memory/graph) · [personalization](/docs/data/memory/personalization) +**Wrappers (core):** `createVirtualizedMemory` from `@agentskit/core`; +`createAutoSummarizingMemory` from `@agentskit/core/auto-summarize` — +[virtualized](/docs/data/memory/virtualized) · +[auto-summarize](/docs/data/memory/auto-summarize) + ## Retriever — RAG pipeline **Contract:** [concepts/retriever](./retriever) · **Package:** [@agentskit/rag](/docs/reference/packages/rag) @@ -95,8 +97,8 @@ and the [tool ecosystem](/docs/agents/tools/integrations). **Core:** `createRAG`, `chunkText` — [createRAG](/docs/data/rag/create-rag) · [chunking](/docs/data/rag/chunking) -**Rerankers:** `createRerankedRetriever`, `cohereReranker`, -`bgeReranker`, `bm25Reranker` — [deep dive](/docs/data/rag/rerank) +**Rerankers:** `createRerankedRetriever`, `voyageReranker`, +`jinaReranker`, `bm25Rerank` — [deep dive](/docs/data/rag/rerank) **Hybrid:** `createHybridRetriever` — [deep dive](/docs/data/rag/hybrid) diff --git a/apps/docs-next/content/docs/get-started/concepts/retriever.mdx b/apps/docs-next/content/docs/get-started/concepts/retriever.mdx index 022c8c05..35bb4922 100644 --- a/apps/docs-next/content/docs/get-started/concepts/retriever.mdx +++ b/apps/docs-next/content/docs/get-started/concepts/retriever.mdx @@ -42,7 +42,7 @@ import { fileVectorMemory } from '@agentskit/memory' import { openaiEmbedder } from '@agentskit/adapters' const rag = createRAG({ - store: fileVectorMemory({ path: './embeddings.json' }), + store: fileVectorMemory({ path: './vectors' }), embed: openaiEmbedder({ apiKey: KEY, model: 'text-embedding-3-small' }), topK: 5, }) diff --git a/apps/docs-next/content/docs/get-started/migrating/from-llamaindex.mdx b/apps/docs-next/content/docs/get-started/migrating/from-llamaindex.mdx index 8d13b2cf..4af5ebf4 100644 --- a/apps/docs-next/content/docs/get-started/migrating/from-llamaindex.mdx +++ b/apps/docs-next/content/docs/get-started/migrating/from-llamaindex.mdx @@ -27,7 +27,7 @@ Stay with LlamaIndex when: | `index.as_retriever()` | The `RAG` instance itself implements `Retriever` | Use it as `retriever:` on the runtime. | | `index.as_query_engine()` | `runtime.run(query)` with `retriever` set | Retrieval per-turn is automatic. | | `Document(text, metadata)` | `{ content, metadata }` | Same shape, plain object. | -| `SimpleNodeParser`, `SentenceSplitter` | `chunkText({ chunkSize, chunkOverlap })` | Lower-level helper if you want to chunk yourself. | +| `SimpleNodeParser`, `SentenceSplitter` | `chunkText(text, { chunkSize, chunkOverlap, split? })` | `split` is `(text: string) => string[]`. `createRAG` defaults 512 / 50. | | `OpenAIEmbedding` | `openaiEmbedder({ apiKey, model })` | Embedders are first-class adapters. | | `Chroma`, `Pinecone`, `Qdrant`, `Weaviate` | `chroma`, `pinecone`, `qdrant`, `weaviateVectorStore` | All in `@agentskit/memory`. | | `OpenAIAgent.from_tools(tools)` | `createRuntime({ adapter, tools })` | Same idea; one runtime for every model. | diff --git a/apps/docs-next/content/docs/get-started/migrating/from-vercel-ai-sdk.mdx b/apps/docs-next/content/docs/get-started/migrating/from-vercel-ai-sdk.mdx index 0399e029..55eed28e 100644 --- a/apps/docs-next/content/docs/get-started/migrating/from-vercel-ai-sdk.mdx +++ b/apps/docs-next/content/docs/get-started/migrating/from-vercel-ai-sdk.mdx @@ -1,6 +1,6 @@ --- -title: From Vercel AI SDK -description: Side-by-side migration guide. Map your Vercel AI SDK code to AgentsKit — with honest callouts about where each wins. +title: Migrate from Vercel AI SDK to AgentsKit +description: Migrate from Vercel AI SDK to AgentsKit with side-by-side TypeScript patterns for providers, UI, tools, and runtimes. --- import { ContributeCallout } from '@/components/contribute/contribute-callout' diff --git a/apps/docs-next/content/docs/production/cli/index.mdx b/apps/docs-next/content/docs/production/cli/index.mdx index 306a3cbe..97ef8c0c 100644 --- a/apps/docs-next/content/docs/production/cli/index.mdx +++ b/apps/docs-next/content/docs/production/cli/index.mdx @@ -17,7 +17,7 @@ description: Nine commands wrapping every part of AgentsKit — init, chat, run, | `agentskit rag` | Local RAG helpers (ingest / search). | | `agentskit config` | Read / write local config. | -*Per-command deep dives land in step 6 of the docs IA rollout.* +Each command has a dedicated guide in this section; start with [agentskit ai](./ai) for scaffolding or [agentskit dev](./dev) for the local development loop. ## Related diff --git a/apps/docs-next/content/docs/reference/contribute/rfc-process.mdx b/apps/docs-next/content/docs/reference/contribute/rfc-process.mdx index 967b22ee..29c0b484 100644 --- a/apps/docs-next/content/docs/reference/contribute/rfc-process.mdx +++ b/apps/docs-next/content/docs/reference/contribute/rfc-process.mdx @@ -31,4 +31,4 @@ Keep it short. A great RFC is 200–500 words, not 3000. ## Examples of good RFCs -Coming soon — link to merged RFCs here. +For the public architectural record, see the [AgentsKit ADRs](https://github.com/AgentsKit-io/agentskit/tree/main/docs/architecture/adrs). diff --git a/apps/docs-next/content/docs/reference/packages/cli.mdx b/apps/docs-next/content/docs/reference/packages/cli.mdx index 95e0b592..92d13a1f 100644 --- a/apps/docs-next/content/docs/reference/packages/cli.mdx +++ b/apps/docs-next/content/docs/reference/packages/cli.mdx @@ -1,6 +1,6 @@ --- -title: '@agentskit/cli' -description: The agentskit CLI — init, chat, run, dev, doctor, ai, tunnel, rag, config. +title: AgentsKit CLI for TypeScript agents +description: 'AgentsKit CLI for TypeScript agents: scaffold, run, chat, dev, doctor, RAG, and MCP from the terminal.' --- `@agentskit/cli` is the operational front door to the ecosystem. It is how you bootstrap a project, run an agent, inspect your setup, and keep moving without writing scaffolding code first. diff --git a/apps/docs-next/content/docs/reference/packages/core.mdx b/apps/docs-next/content/docs/reference/packages/core.mdx index f4e7bf2c..56d81310 100644 --- a/apps/docs-next/content/docs/reference/packages/core.mdx +++ b/apps/docs-next/content/docs/reference/packages/core.mdx @@ -73,7 +73,7 @@ Heavy backends live in [`@agentskit/memory`](/docs/reference/packages/memory); v | `AdapterError` | Thrown on adapter/stream failures; links to adapter docs | | `ToolError` | Thrown on tool lookup or execution failures; links to tool docs | | `MemoryError` | Thrown on memory load/save/deserialize failures; links to memory docs | -| `ConfigError` | Thrown on invalid configuration; links to configuration docs | +| `ConfigError` | Thrown on invalid configuration; links to [error handling](/docs/get-started/concepts/errors) | | `ErrorCodes` | `as const` map of all `AK_*` error code strings | See [Error handling](#error-handling-1) below for usage examples. @@ -144,6 +144,9 @@ import { ToolError, MemoryError, ConfigError, + RuntimeError, + SandboxError, + SkillError, ErrorCodes, } from '@agentskit/core' ``` @@ -152,9 +155,12 @@ import { |-------|-------------| | `AgentsKitError` | Base class — all errors extend this | | `AdapterError` | Adapter is missing or a stream call fails | -| `ToolError` | A tool is not found or its `execute` throws | -| `MemoryError` | Memory load, save, or deserialization fails | +| `ToolError` | A tool is missing, forbidden, invalid, or its `execute` call fails | +| `MemoryError` | Memory load, save, deserialization, or backend access fails | | `ConfigError` | Required configuration is absent or invalid | +| `RuntimeError` | Runtime input, step, or delegation fails | +| `SandboxError` | Sandbox policy, backend, or peer setup fails | +| `SkillError` | A skill is invalid or duplicated | ### Error shape @@ -172,7 +178,7 @@ class AgentsKitError extends Error { ``` error[AK_ADAPTER_MISSING]: No adapter provided --> Hint: Pass an adapter when creating the chat controller, e.g. - createChatController({ adapter: openaiAdapter() }) + createChatController({ adapter: openai({ apiKey, model: 'gpt-4o' }) }) --> Docs: https://www.agentskit.io/docs/data/providers ``` @@ -185,12 +191,31 @@ ErrorCodes.AK_ADAPTER_MISSING // adapter not provided ErrorCodes.AK_ADAPTER_STREAM_FAILED // streaming call failed ErrorCodes.AK_TOOL_NOT_FOUND // tool name not registered ErrorCodes.AK_TOOL_EXEC_FAILED // execute() threw +ErrorCodes.AK_TOOL_PEER_MISSING // optional tool peer is not installed +ErrorCodes.AK_TOOL_INVALID_INPUT // tool arguments or proposal are invalid +ErrorCodes.AK_TOOL_QUOTA_EXCEEDED // tool execution exceeds its quota +ErrorCodes.AK_TOOL_FORBIDDEN // tool execution is denied by policy ErrorCodes.AK_MEMORY_LOAD_FAILED // memory.load() failed ErrorCodes.AK_MEMORY_SAVE_FAILED // memory.save() failed ErrorCodes.AK_MEMORY_DESERIALIZE_FAILED // corrupt persisted state +ErrorCodes.AK_MEMORY_PEER_MISSING // optional memory backend is not installed +ErrorCodes.AK_MEMORY_REMOTE_HTTP // remote memory request failed ErrorCodes.AK_CONFIG_INVALID // missing or bad config +ErrorCodes.AK_RUNTIME_INVALID_INPUT // runtime input is invalid +ErrorCodes.AK_RUNTIME_STEP_FAILED // a runtime step failed +ErrorCodes.AK_RUNTIME_DELEGATE_FAILED // delegated agent execution failed +ErrorCodes.AK_SANDBOX_DENIED // sandbox policy denied execution +ErrorCodes.AK_SANDBOX_INVALID_TOOL // tool is invalid for the sandbox +ErrorCodes.AK_SANDBOX_PEER_MISSING // optional sandbox backend is not installed +ErrorCodes.AK_SANDBOX_BACKEND_FAILED // sandbox backend failed +ErrorCodes.AK_SKILL_INVALID // skill definition is invalid +ErrorCodes.AK_SKILL_DUPLICATE // skill identity is duplicated ``` +RAG loader and reranker errors are package-specific. Import +`RagError` / `RagErrorCodes` from `@agentskit/rag` for +`AK_RAG_LOAD_FAILED`, `AK_RAG_PEER_MISSING`, and `AK_RAG_RERANK_FAILED`. + ### Catching and narrowing errors ```ts diff --git a/apps/docs-next/content/docs/reference/packages/overview.mdx b/apps/docs-next/content/docs/reference/packages/overview.mdx index a8cf7aea..34cf382a 100644 --- a/apps/docs-next/content/docs/reference/packages/overview.mdx +++ b/apps/docs-next/content/docs/reference/packages/overview.mdx @@ -5,10 +5,11 @@ description: Every AgentsKit package at a glance — what it does, when to reach import { ContributeCallout } from '@/components/contribute/contribute-callout' -Twenty-one focused packages under `@agentskit/*`. Install what you need; every UI and runtime layer composes against the zero-dep **[@agentskit/core](./core)**. +Twenty-two published packages under `@agentskit/*`, plus private workspace implementations that back public subpaths. Install what you need; every UI and runtime layer composes against the zero-dep **[@agentskit/core](./core)**. :::tip API reference -Full signatures: **[TypeDoc HTML](pathname:///agentskit/api-reference/)** (generated on `pnpm --filter @agentskit/docs build`; for local dev run `pnpm --filter @agentskit/docs docs:api` once). +Full package contracts: start with each package guide below, then follow its +generated API links when you need declaration-level signatures. ::: ## Foundation @@ -45,9 +46,11 @@ Full signatures: **[TypeDoc HTML](pathname:///agentskit/api-reference/)** (gener | Package | One-liner | |---|---| -| [@agentskit/tools](./tools) | Built-in tools + 50 integrations + MCP bridge. | +| [@agentskit/tools](./tools) | Built-in tools + integration tools + MCP bridge. | +| [@agentskit/integrations](/docs/for-agents/integrations) | Fetch-only service descriptors and integration catalog. | +| [@agentskit/mcp](/docs/agents/tools/mcp) | MCP tool bridge and bounded registry transport. | | [@agentskit/memory](./memory) | Chat + vector + hierarchical + encrypted + graph memory. | -| [@agentskit/rag](./rag) | Chunk + retrieve + rerank + hybrid + six loaders. | +| [@agentskit/rag](./rag) | Chunk + retrieve + rerank + hybrid + document loaders. | | [@agentskit/skills](./skills) | Ready-made personas + marketplace. | ## Observability + evaluation @@ -66,6 +69,7 @@ Full signatures: **[TypeDoc HTML](pathname:///agentskit/api-reference/)** (gener | [@agentskit/sandbox](./sandbox) | Secure code execution + mandatory-sandbox policy. | | [@agentskit/cli](./cli) | `agentskit init / chat / run / ai / dev / doctor`. | | [@agentskit/templates](./templates) | Starter templates used by `agentskit init`. | +| [@agentskit/statechart](./statechart) | Serializable interaction state for host-managed UI flows. | ## See also diff --git a/apps/docs-next/content/docs/reference/packages/rag.mdx b/apps/docs-next/content/docs/reference/packages/rag.mdx index 506dd851..4041df18 100644 --- a/apps/docs-next/content/docs/reference/packages/rag.mdx +++ b/apps/docs-next/content/docs/reference/packages/rag.mdx @@ -1,12 +1,12 @@ --- title: '@agentskit/rag' -description: Plug-and-play RAG. Chunk, embed, retrieve, rerank, hybrid — plus six document loaders. +description: Plug-and-play RAG. Chunk, embed, retrieve, rerank, hybrid, and document loaders. --- ## When to reach for it - You want retrieval-augmented generation in a few lines. -- You need rerankers (BM25 / Cohere / BGE) or hybrid vector+keyword search. +- You need rerankers (BM25, Voyage, Jina, or a custom function) or hybrid vector+keyword search. - You want document loaders for URL / GitHub / Notion / Confluence / Google Drive / PDF. ## Install @@ -24,7 +24,7 @@ import { openaiEmbedder } from '@agentskit/adapters' const rag = createRAG({ embed: openaiEmbedder({ apiKey: process.env.OPENAI_API_KEY! }), - store: fileVectorMemory({ path: './kb.json' }), + store: fileVectorMemory({ path: './kb-vectors' }), }) await rag.ingest([{ content: 'AgentsKit is a toolkit for AI agents.', source: 'intro' }]) const hits = await rag.search('what is agentskit') @@ -46,8 +46,8 @@ const hits = await rag.search('what is agentskit') ## Stability -- **Version:** `0.2.1` -- **Tier:** alpha +- **Version:** `0.5.2` +- **Tier:** beta - **Contract:** evolving - **Roadmap:** see [packages roadmap](./roadmap) for what this package needs to reach v1.0. diff --git a/apps/docs-next/content/docs/reference/specs/index.mdx b/apps/docs-next/content/docs/reference/specs/index.mdx index 4148cb31..2c3122b7 100644 --- a/apps/docs-next/content/docs/reference/specs/index.mdx +++ b/apps/docs-next/content/docs/reference/specs/index.mdx @@ -9,7 +9,7 @@ Small, stable, versioned JSON shapes. Each is a subpath of `@agentskit/core`: ty - **Manifest** — packaging format for skills + tools. Tool entries mirror MCP `inputSchema` so manifests round-trip. - **Eval Format** — portable eval dataset + run-result. `matchesExpectation` supports literal / regex / normalized / semantic similarity. -*Per-spec deep dives land in step 6 of the docs IA rollout.* +Read the [A2A](./a2a), [Manifest](./manifest), and [Eval Format](./eval-format) deep dives for the individual contracts. ## Related diff --git a/apps/docs-next/content/docs/reference/stability.mdx b/apps/docs-next/content/docs/reference/stability.mdx index 791bec24..d4e1908e 100644 --- a/apps/docs-next/content/docs/reference/stability.mdx +++ b/apps/docs-next/content/docs/reference/stability.mdx @@ -23,25 +23,31 @@ the existing surface. | Package | Level | Note | |---|---|---| -| `@agentskit/core` | stable | Sacred — every other package depends on its contracts. | -| `@agentskit/adapters` | stable | 29 provider factories; the contract is locked per ADR 0001. | -| `@agentskit/runtime` | stable | ReAct loop + delegation per ADR 0006. | -| `@agentskit/memory` | stable | Per ADR 0003. | -| `@agentskit/rag` | stable | Per ADR 0004. | -| `@agentskit/skills` | stable | Per ADR 0005. | -| `@agentskit/tools` | stable | Per ADR 0002. | -| `@agentskit/react` | stable | `useChat` shape locked. | -| `@agentskit/ink` | stable | Mirrors React contract. | -| `@agentskit/cli` | stable | `chat`, `init`, `run` commands stable. | -| `@agentskit/templates` | stable | Scaffolding contract stable. | -| `@agentskit/observability` | beta | Sink set still growing (Datadog, Axiom, New Relic shipped — Splunk / Honeycomb on roadmap). | -| `@agentskit/eval` | beta | LLM-judge pipeline shipped; broader benchmarks queued. | -| `@agentskit/sandbox` | beta | E2B backend stable; alternative backends (WebContainer, MicroVM) queued. | -| `@agentskit/vue` | alpha | Composable contract mirrors React; promotion blocked on coverage gate. | -| `@agentskit/svelte` | alpha | Store contract mirrors React; promotion blocked on coverage gate. | -| `@agentskit/solid` | alpha | Hook contract mirrors React; promotion blocked on coverage gate. | -| `@agentskit/angular` | alpha | Service contract; promotion blocked on coverage gate. | -| `@agentskit/react-native` | alpha | Hook mirrors React; promotion blocked on coverage gate. | +| `@agentskit/core` | stable | Sacred package; contract-stable per ADRs 0001–0006. | +| `@agentskit/adapters` | beta | Provider contract and resilience hardening continue toward 1.0. | +| `@agentskit/runtime` | beta | ReAct, topology, and durable APIs are still settling. | +| `@agentskit/tools` | beta | Core tools are usable; integrations and MCP ergonomics evolve. | +| `@agentskit/memory` | beta | Main backends work; vector-store surface is sharpening. | +| `@agentskit/skills` | beta | Catalog and contract hardening continue toward promotion. | +| `@agentskit/observability` | beta | Lifecycle, cost-guard, and provider coverage continue to grow. | +| `@agentskit/react` | beta | Production-ready; shared `ChatReturn` remains pre-1.0. | +| `@agentskit/ink` | beta | Terminal parity and keyboard UX continue to mature. | +| `@agentskit/cli` | beta | Core commands are useful; programmatic surface is settling. | +| `@agentskit/rag` | beta | Retriever, loader, and resilience contracts are hardening. | +| `@agentskit/eval` | beta | Suite, replay, snapshot, and CI surfaces are still pre-1.0. | +| `@agentskit/sandbox` | beta | Lifecycle, config, and backend surfaces are still pre-1.0. | +| `@agentskit/templates` | beta | Scaffold and validation surfaces are still pre-1.0. | +| `@agentskit/validation` | beta | Private implementation behind the public tools validation surface. | +| `@agentskit/statechart` | beta | Serializable interaction-state contract is hardened but pre-1.0. | +| `@agentskit/eval-braintrust` | beta | Private implementation exposed through the public eval surface. | +| `@agentskit/observability-langfuse` | beta | Private workspace implementation exposed through observability. | +| `@agentskit/integrations` | beta | Fetch-only catalog and execution boundaries are still pre-1.0. | +| `@agentskit/mcp` | beta | Tool bridge and bounded registry surfaces are still pre-1.0. | +| `@agentskit/vue` | beta | Framework binding at headless parity, still pre-1.0. | +| `@agentskit/svelte` | beta | Framework binding at headless parity, still pre-1.0. | +| `@agentskit/solid` | beta | Framework binding at headless parity, still pre-1.0. | +| `@agentskit/react-native` | beta | Framework binding at headless parity, still pre-1.0. | +| `@agentskit/angular` | beta | Framework binding at headless parity, still pre-1.0. | ## Promotion criteria @@ -87,9 +93,8 @@ If you depend on an `alpha` or `beta` package today, do the following: ## Roadmap -The 5 alpha UI bindings are the most concrete near-term promotion target. -Once their coverage thresholds are at 70+ (real tests, not the placeholder -existence checks), promotion follows. The 3 beta packages graduate when +The framework bindings are the most concrete near-term promotion target. +Once their coverage thresholds and release evidence are complete, promotion follows. The beta packages graduate when their respective ADRs are written + locked. ## Related diff --git a/apps/docs-next/content/docs/ui/use-chat.mdx b/apps/docs-next/content/docs/ui/use-chat.mdx index eec4e3ac..7bf3773b 100644 --- a/apps/docs-next/content/docs/ui/use-chat.mdx +++ b/apps/docs-next/content/docs/ui/use-chat.mdx @@ -13,15 +13,20 @@ signal, Angular service, React Native hook, Ink hook). ```ts type ChatReturn = { messages: Message[] - status: 'idle' | 'streaming' | 'error' | 'awaiting-tool' + status: 'idle' | 'streaming' | 'complete' | 'error' + input: string + usage: TokenUsage error: Error | null - send: (text: string, opts?: SendOptions) => Promise + send: (text: string) => Promise retry: () => Promise stop: () => void - clear: () => void - approve: (toolCallId: string, result?: unknown) => void - deny: (toolCallId: string, reason?: string) => void - edit: (messageId: string, text: string) => Promise + clear: () => Promise + approve: (toolCallId: string) => Promise + deny: (toolCallId: string, reason?: string) => Promise + edit: (messageId: string, text: string, opts?: EditOptions) => Promise + regenerate: (messageId?: string) => Promise + setInput: (value: string) => void + proposeToolCall: (proposal: Pick) => Promise } ``` @@ -29,14 +34,14 @@ type ChatReturn = { ```ts type ChatConfig = { - adapter: Adapter - tools?: Tool[] - skills?: Skill[] - memory?: Memory - rag?: Retriever - system?: string - onEvent?: (e: ChatEvent) => void + adapter: AdapterFactory + tools?: ToolDefinition[] + skills?: SkillDefinition[] + memory?: ChatMemory + retriever?: Retriever + systemPrompt?: string onError?: (e: Error) => void + onMessage?: (message: Message) => void } ``` @@ -60,10 +65,11 @@ safe and has no additional effect. | Angular | `import { AgentskitChat } from '@agentskit/angular'` | `constructor(private chat: AgentskitChat)` — `Signal` + `RxJS` | | Ink | `import { useChat } from '@agentskit/ink'` | Terminal-safe | -## Events (`onEvent`) +## Events and observers -`chat.start` · `message.append` · `message.update` · `tool.call` · -`tool.result` · `error` · `status.change` · `chat.end`. +Use `onMessage` for per-message updates or `observers` for the shared +`AgentEvent` stream. The controller does not expose an `onEvent` option on +`ChatConfig`; framework bindings mirror the same core contract. Full schema: [Concepts → mental model](/docs/get-started/concepts/mental-model). diff --git a/apps/docs-next/legacy-404-redirects.mjs b/apps/docs-next/legacy-404-redirects.mjs index c7510d1b..d49856e7 100644 --- a/apps/docs-next/legacy-404-redirects.mjs +++ b/apps/docs-next/legacy-404-redirects.mjs @@ -1,7 +1,9 @@ -// AUTO-GENERATED from GSC "Not found (404)" export (2026-05-19). -// 226 crawled-but-404 URLs from doc IA churn. Each destination verified -// against the live sitemap (or its nearest live ancestor section). -// Junk (code-snippet file paths, unbuilt locales) intentionally left to 404. +// AUTO-GENERATED from GSC "Not found (404)" exports (latest source: 2026-06-03). +// 203 explicit crawled-but-404 candidates from doc IA churn. Grok CLI +// classification: 42 extension-normalization, 87 same-leaf IA moves, 30 +// API-symbol-to-ancestor moves, and 44 dead-page-to-ancestor fallbacks. +// The remaining 23 URLs (code-snippet paths, unbuilt locales, and junk) are +// intentionally left to 404. Every destination below is a current docs route. // Prepended before the wildcard rules so first-match wins over stale chains. export const LEGACY_404_REDIRECTS = [ // From GSC "Not found (404)" export 2026-06-03: reference recipes moved under /recipes; a2a spec moved under /specs. diff --git a/apps/docs-next/lib/reference-journey.ts b/apps/docs-next/lib/reference-journey.ts index 232d6bc2..3ba5585e 100644 --- a/apps/docs-next/lib/reference-journey.ts +++ b/apps/docs-next/lib/reference-journey.ts @@ -32,6 +32,7 @@ function productById(id: string): ManifestProduct { } const agentskit = productById('agentskit') +const ecosystemNext = agentskit.navigation.next.map(productById) export const agentsKitIdentity = { name: agentskit.name, @@ -42,9 +43,8 @@ export const agentsKitIdentity = { proof: claimsFor('agentskit'), } as const -export const ecosystemShowcase = manifest.products +export const ecosystemShowcase = ecosystemNext .filter(hasShowcase) - .sort((a, b) => a.navigation.order - b.navigation.order) .map((product) => ({ id: product.id, name: product.name, diff --git a/apps/docs-next/next.config.mjs b/apps/docs-next/next.config.mjs index d7ca604d..7bb46abe 100644 --- a/apps/docs-next/next.config.mjs +++ b/apps/docs-next/next.config.mjs @@ -35,7 +35,6 @@ const DOC_REDIRECTS = [ { source: '/docs/tools', destination: '/docs/agents/tools', permanent: true }, { source: '/docs/skills/:slug*', destination: '/docs/agents/skills/:slug*', permanent: true }, { source: '/docs/skills', destination: '/docs/agents/skills', permanent: true }, - { source: '/docs/agents/tools', destination: '/docs/agents/tools', permanent: false }, // self no-op retained for old redirect fallback // Tab restructure — Production { source: '/docs/observability/:slug*', destination: '/docs/production/observability/:slug*', permanent: true }, @@ -52,6 +51,7 @@ const DOC_REDIRECTS = [ { source: '/docs/infrastructure/:slug*', destination: '/docs/reference/packages/:slug*', permanent: true }, // Tab restructure — Reference + { source: '/docs/packages/integrations', destination: '/docs/for-agents/integrations', permanent: true }, { source: '/docs/packages/:slug*', destination: '/docs/reference/packages/:slug*', permanent: true }, { source: '/docs/packages', destination: '/docs/reference/packages', permanent: true }, // For agents is its own top-level tab — keep the short legacy path working diff --git a/apps/docs-next/scripts/gen-api.mjs b/apps/docs-next/scripts/gen-api.mjs index 80bd4fc7..e60ae314 100644 --- a/apps/docs-next/scripts/gen-api.mjs +++ b/apps/docs-next/scripts/gen-api.mjs @@ -107,7 +107,10 @@ function postprocess(dir, pkgName) { const raw = readFileSync(p, 'utf8') const isReadme = entry.name === 'README.md' const title = isReadme ? `@agentskit/${pkgName}` : entry.name.replace(/\.md$/, '') - const description = `Auto-generated API reference for ${title}.` + const description = + pkgName === 'core' && title === 'ArgsValidator' + ? 'ArgsValidator contract for validating TypeScript AI agent tool arguments against JSON Schema before execution.' + : `Auto-generated API reference for ${title}.` const frontmatter = `---\ntitle: ${JSON.stringify(title)}\ndescription: ${JSON.stringify(description)}\n---\n\n` const body = escapeMdx(raw) const newPath = isReadme ? join(d, 'index.md') : p diff --git a/apps/docs-next/tests/documentation-contracts.test.ts b/apps/docs-next/tests/documentation-contracts.test.ts new file mode 100644 index 00000000..415363c6 --- /dev/null +++ b/apps/docs-next/tests/documentation-contracts.test.ts @@ -0,0 +1,89 @@ +import { readFileSync } from 'node:fs' +import { resolve } from 'node:path' +import { describe, expect, it } from 'vitest' + +const repoRoot = resolve(__dirname, '../../..') +const docsRoot = resolve(__dirname, '../content/docs') + +function read(relativePath: string): string { + return readFileSync(resolve(repoRoot, relativePath), 'utf8') +} + +describe('documentation and package contract surfaces', () => { + it('keeps built-in error docs links canonical and documented', () => { + const source = read('packages/core/src/errors.ts') + const docs = read('apps/docs-next/content/docs/get-started/concepts/errors.mdx') + const coreReference = read('apps/docs-next/content/docs/reference/packages/core.mdx') + + expect(source).toContain("${DOCS_BASE}/data/providers") + expect(source).toContain("${DOCS_BASE}/agents/tools") + expect(source).toContain("${DOCS_BASE}/data/memory") + expect(source).toContain("${DOCS_BASE}/get-started/concepts/errors") + + for (const code of source.matchAll(/\n\s+(AK_[A-Z0-9_]+):/g)) { + expect(docs).toContain(code[1]!) + expect(coreReference).toContain(code[1]!) + } + + expect(docs).toContain('RuntimeError') + expect(docs).toContain('SandboxError') + expect(docs).toContain('SkillError') + expect(docs).toContain('RagErrorCodes.AK_RAG_RERANK_FAILED') + expect(docs).not.toContain('openaiAdapter()') + }) + + it('keeps package README and metadata links on current guide routes', () => { + const packageDirs = [ + 'adapters', 'angular', 'cli', 'core', 'eval-braintrust', 'eval', 'ink', 'mcp', + 'memory', 'observability-langfuse', 'observability', 'rag', 'react-native', 'react', + 'runtime', 'sandbox', 'skills', 'solid', 'statechart', 'svelte', 'templates', 'tools', + 'validation', 'vue', + ] + + for (const packageDir of packageDirs) { + const readme = read(`packages/${packageDir}/README.md`) + const manifest = JSON.parse(read(`packages/${packageDir}/package.json`)) as { homepage?: string } + expect(readme).not.toMatch(/https:\/\/www\.agentskit\.io\/docs\/(packages|recipes|tools|adapters|memory|configuration)\b/) + expect(manifest.homepage).not.toMatch(/https:\/\/www\.agentskit\.io\/docs\/packages\//) + } + + expect(read('packages/mcp/README.md')).toContain('/docs/agents/tools/mcp') + expect(read('packages/integrations/README.md')).toContain('/docs/for-agents/integrations') + const cliTemplate = read('packages/cli/src/init.ts') + expect(cliTemplate).toContain('https://www.agentskit.io/docs/get-started/concepts/skill') + expect(cliTemplate).toContain('https://www.agentskit.io/docs/reference/recipes/rag-chat') + expect(cliTemplate).not.toContain('https://www.agentskit.io/docs/concepts/skill') + expect(cliTemplate).not.toContain('https://www.agentskit.io/docs/recipes/rag-chat') + }) + + it('keeps high-use RAG and UI pages free of known invented signatures', () => { + const pages = [ + 'data/rag/create-rag.mdx', + 'data/rag/rerank.mdx', + 'data/rag/loaders.mdx', + 'data/rag/chunking.mdx', + 'data/providers/embedders.mdx', + 'ui/use-chat.mdx', + ].map((path) => readFileSync(resolve(docsRoot, path), 'utf8')).join('\n') + const executableSnippets = [...pages.matchAll(/```(?:ts|tsx)\n([\s\S]*?)```/g)] + .map((match) => match[1]!) + .join('\n') + + expect(executableSnippets).not.toContain('cohereReranker') + expect(executableSnippets).not.toContain('bgeReranker') + expect(executableSnippets).not.toContain("split: 'paragraph'") + expect(pages).not.toContain('LoadedDocument[]') + expect(pages).not.toContain('awaiting-tool') + expect(pages).not.toContain('rag?: Retriever') + expect(pages).not.toContain('system?: string') + expect(pages).toContain('createRerankedRetriever(base,') + expect(pages).toContain('chunkText(text,') + expect(pages).toContain('type EmbedFn = (text: string) => Promise') + }) + + it('keeps contributor and package handoff paths on the current docs tree', () => { + expect(read('CONTRIBUTING.md')).not.toContain('content/docs/recipes/') + expect(read('packages/react/CONVENTIONS.md')).not.toContain('content/docs/recipes/') + expect(read('packages/react/CONVENTIONS.md')).toContain('content/docs/reference/recipes/custom-adapter.mdx') + }) +}) diff --git a/apps/docs-next/tests/legacy-redirects.test.ts b/apps/docs-next/tests/legacy-redirects.test.ts new file mode 100644 index 00000000..9385268d --- /dev/null +++ b/apps/docs-next/tests/legacy-redirects.test.ts @@ -0,0 +1,58 @@ +import { readdirSync, statSync } from 'node:fs' +import { resolve } from 'node:path' +import { describe, expect, it } from 'vitest' +import { LEGACY_404_REDIRECTS } from '../legacy-404-redirects.mjs' + +type LegacyRedirect = { + source: string + destination: string + permanent: boolean +} + +const redirects = LEGACY_404_REDIRECTS as LegacyRedirect[] + +function docRoutes(): Set { + const root = resolve(__dirname, '../content/docs') + const routes = new Set(['/docs']) + + function walk(directory: string): void { + for (const name of readdirSync(directory)) { + const path = resolve(directory, name) + if (statSync(path).isDirectory()) { + walk(path) + continue + } + if (!/\.(md|mdx)$/.test(name)) continue + + const relative = path + .slice(root.length + 1) + .replaceAll('\\', '/') + .replace(/\.(md|mdx)$/, '') + routes.add(relative.endsWith('/index') ? `/docs/${relative.slice(0, -6)}` : `/docs/${relative}`) + } + } + + walk(root) + return routes +} + +describe('legacy 404 redirects', () => { + it('keeps the importable queue unique, permanent, and one-hop', () => { + const sources = redirects.map((redirect) => redirect.source) + const sourceSet = new Set(sources) + + expect(sources.length).toBe(203) + expect(sourceSet.size).toBe(sources.length) + expect(redirects.every((redirect) => redirect.permanent)).toBe(true) + expect(redirects.every((redirect) => !sourceSet.has(redirect.destination))).toBe(true) + }) + + it('keeps every queued destination backed by a current docs route', () => { + const routes = docRoutes() + const missing = redirects + .map((redirect) => redirect.destination) + .filter((destination) => !routes.has(destination)) + + expect(missing).toEqual([]) + }) +}) diff --git a/apps/docs-next/tests/seo-surfaces.test.ts b/apps/docs-next/tests/seo-surfaces.test.ts new file mode 100644 index 00000000..1706b2e0 --- /dev/null +++ b/apps/docs-next/tests/seo-surfaces.test.ts @@ -0,0 +1,191 @@ +import { readFileSync } from 'node:fs' +import { resolve } from 'node:path' +import { describe, expect, it, vi } from 'vitest' +import { counts, lists } from '../lib/ecosystem-stats' + +vi.mock('@/lib/source', () => ({ + source: { getPages: () => [] }, +})) +vi.mock('@/lib/blog', () => ({ slugsOfAll: () => [] })) +vi.mock('@/lib/learn-steps', () => ({ STEPS: [] })) +vi.mock('@/lib/showcase', () => ({ SHOWCASE: [] })) + +import sitemap from '../app/sitemap' + +describe('SEO discovery surfaces', () => { + it('publishes the ecosystem hub without synthetic modification dates', () => { + const entries = sitemap() + const urls = entries.map((entry) => entry.url) + + expect(urls).toContain('https://www.agentskit.io/ecosystem') + expect(urls).toContain('https://www.agentskit.io/integrations') + expect(urls).toContain('https://www.agentskit.io/recipes') + expect(urls).toContain('https://www.agentskit.io/publications') + expect(new Set(urls).size).toBe(urls.length) + expect(entries.every((entry) => entry.lastModified === undefined)).toBe(true) + }) + + it('links the ecosystem hub from the LLM index route', () => { + const route = readFileSync(resolve(__dirname, '../app/llms.txt/route.ts'), 'utf8') + + expect(route).toContain('/ecosystem): canonical product mesh and package matrix') + expect(route).toContain('/integrations): verified connectors for TypeScript AI agents') + expect(route).toContain('/recipes): copy-paste implementation patterns for production agents') + expect(route).toContain('/publications): first-party releases and engineering deep dives') + expect(route).toContain('/resources): verified tools, MCP registries') + }) + + it('keeps the canonical integration catalog count aligned with its generated list', () => { + expect(counts.integrations).toBe(50) + expect(lists.integrations).toHaveLength(counts.integrations) + expect(new Set(lists.integrations).size).toBe(lists.integrations.length) + }) + + it('keeps package integration links on the canonical guide instead of the dead package alias', () => { + const packageJson = readFileSync(resolve(__dirname, '../../../packages/integrations/package.json'), 'utf8') + const readme = readFileSync(resolve(__dirname, '../../../packages/integrations/README.md'), 'utf8') + const nextConfig = readFileSync(resolve(__dirname, '../next.config.mjs'), 'utf8') + const specificRedirect = nextConfig.indexOf("source: '/docs/packages/integrations'") + const wildcardRedirect = nextConfig.indexOf("source: '/docs/packages/:slug*'") + + expect(packageJson).toContain('https://www.agentskit.io/docs/for-agents/integrations') + expect(readme).not.toContain('https://www.agentskit.io/docs/packages/integrations') + expect(readme).toContain('https://www.agentskit.io/docs/for-agents/integrations') + expect(specificRedirect).toBeGreaterThan(-1) + expect(specificRedirect).toBeLessThan(wildcardRedirect) + }) + + it('keeps the resources title concise while preserving proof intent', () => { + const page = readFileSync(resolve(__dirname, '../app/resources/page.tsx'), 'utf8') + + expect(page).toContain("title: 'Resources: proofs, registries, publications'") + expect('Resources: proofs, registries, publications | AgentsKit.js'.length).toBeLessThanOrEqual(60) + }) + + it('embeds a two-item BreadcrumbList on the canonical hubs', () => { + const hubs = [ + ['../app/ecosystem/page.tsx', '/ecosystem'], + ['../app/integrations/page.tsx', '/integrations'], + ['../app/recipes/page.tsx', '/recipes'], + ['../app/publications/page.tsx', '/publications'], + ['../app/resources/page.tsx', '/resources'], + ] as const + + for (const [relativePath, hubPath] of hubs) { + const page = readFileSync(resolve(__dirname, relativePath), 'utf8') + + expect(page).toContain('BreadcrumbList') + expect(page).toContain("canonicalUrl('/')") + expect(page).toContain(`canonicalUrl('${hubPath}')`) + } + }) + + it('keeps the HITL agent guide title, description, and canonical deep links', () => { + const page = readFileSync(resolve(__dirname, '../content/docs/agents/hitl.mdx'), 'utf8') + + expect(page).toContain('title: Human-in-the-loop patterns for AI agents') + expect(page).toMatch( + /description: ['"]?Practical approval patterns for TypeScript AI agents: gated tool calls, review queues, approver policies, and safe resume flows\.['"]?/, + ) + expect(page).toContain('/docs/reference/recipes/hitl-approvals') + expect(page).toContain('/docs/ui/tool-confirmation') + }) + + it('points the tools guide at the live integration catalog instead of the stale IA rollout note', () => { + const page = readFileSync(resolve(__dirname, '../content/docs/agents/tools/index.mdx'), 'utf8') + + expect(page).toContain('/integrations') + expect(page).toContain('/docs/for-agents/integrations') + expect(page).toContain('50 service descriptors') + expect(page).not.toContain('land in step 6') + }) + + it('overrides the ArgsValidator API description without changing the generated fallback', () => { + const page = readFileSync( + resolve(__dirname, '../content/docs/api/core/type-aliases/ArgsValidator.md'), + 'utf8', + ) + const script = readFileSync(resolve(__dirname, '../scripts/gen-api.mjs'), 'utf8') + const description = + 'ArgsValidator contract for validating TypeScript AI agent tool arguments against JSON Schema before execution.' + + expect(page).toContain(`description: ${JSON.stringify(description)}`) + expect(script).toContain(`pkgName === 'core' && title === 'ArgsValidator'`) + expect(script).toContain(description) + expect(script).toContain('Auto-generated API reference for ${title}.') + }) + + it('does not declare a self-redirect for /docs/agents/tools and filters source === destination', () => { + const nextConfig = readFileSync(resolve(__dirname, '../next.config.mjs'), 'utf8') + + expect(nextConfig).not.toContain( + "{ source: '/docs/agents/tools', destination: '/docs/agents/tools'", + ) + expect(nextConfig).toContain('r.source !== r.destination') + }) + + it('documents grokEmbedder with an explicit required model', () => { + const page = readFileSync( + resolve(__dirname, '../content/docs/data/providers/grok-embedder.mdx'), + 'utf8', + ) + + expect(page).toContain("model: 'grok-embed-model'") + expect(page.replaceAll('`', '')).toContain('| model | string | required |') + expect(page).toContain( + 'description: xAI embedding models through the OpenAI-compatible embeddings API.', + ) + expect(page).not.toContain('provider default') + }) + + it('documents createHybridRetriever with the real Retriever-first signature', () => { + const page = readFileSync(resolve(__dirname, '../content/docs/data/rag/hybrid.mdx'), 'utf8') + const snippet = page.match(/```ts\n([\s\S]*?)```/)?.[1] ?? '' + + expect(page).toContain('createHybridRetriever(baseRetriever') + expect(page).toContain('vectorWeight') + expect(page).toContain('bm25Weight') + expect(snippet).not.toContain('lexical') + expect(snippet).not.toContain('weights:') + expect(snippet).not.toContain('vector: rag') + }) + + it('replaces stale IA rollout notes with live section links', () => { + const pages = [ + [ + '../content/docs/agents/skills/index.mdx', + ['/docs/reference/recipes/skill-marketplace'], + ], + [ + '../content/docs/data/memory/index.mdx', + ['/docs/reference/recipes/vector-adapters'], + ], + ['../content/docs/data/providers/index.mdx', ['./choosing']], + [ + '../content/docs/data/rag/index.mdx', + ['/docs/reference/recipes/doc-loaders', '/docs/reference/recipes/rag-reranking'], + ], + ['../content/docs/production/cli/index.mdx', ['./ai', './dev']], + [ + '../content/docs/reference/specs/index.mdx', + ['./a2a', './manifest', './eval-format'], + ], + [ + '../content/docs/reference/contribute/rfc-process.mdx', + ['https://github.com/AgentsKit-io/agentskit/tree/main/docs/architecture/adrs'], + ], + ] as const + + for (const [relativePath, links] of pages) { + const page = readFileSync(resolve(__dirname, relativePath), 'utf8') + + expect(page).not.toContain('land in step') + expect(page).not.toContain('Coming soon') + expect(page).not.toContain('docs IA rollout') + + for (const link of links) { + expect(page).toContain(link) + } + } + }) +}) diff --git a/apps/docs-next/vitest.config.ts b/apps/docs-next/vitest.config.ts new file mode 100644 index 00000000..0c0ee3ac --- /dev/null +++ b/apps/docs-next/vitest.config.ts @@ -0,0 +1,15 @@ +import { resolve } from 'node:path' +import { defineConfig } from 'vitest/config' + +export default defineConfig({ + root: __dirname, + resolve: { + alias: { + '@': resolve(__dirname), + }, + }, + test: { + environment: 'node', + include: ['tests/**/*.test.ts'], + }, +}) diff --git a/packages/adapters/README.md b/packages/adapters/README.md index fc3cb1e3..a4ff5ce0 100644 --- a/packages/adapters/README.md +++ b/packages/adapters/README.md @@ -18,7 +18,7 @@ Connect to any LLM provider — and swap between them — without touching your ## Verified proof - Package metadata and tests live under `packages/adapters/`. -- Package guide: https://www.agentskit.io/docs/packages/adapters +- Package guide: https://www.agentskit.io/docs/reference/packages/adapters - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -30,12 +30,12 @@ Connect to any LLM provider — and swap between them — without touching your - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/adapters) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/adapters) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why adapters - **Vendor independence** — switch from OpenAI to Anthropic to a local Ollama model by changing one line; your hooks, runtime, and tools stay untouched -- **20+ providers included** — Anthropic, OpenAI, Gemini, Ollama, DeepSeek, Grok, Kimi, Mistral, Cohere, Together, Groq, Fireworks, OpenRouter, Hugging Face, LM Studio, vLLM, llama.cpp, LangChain, Vercel AI SDK, and any raw `ReadableStream` +- **25 native adapters in the catalog** — Anthropic, OpenAI, Gemini, Ollama, DeepSeek, Grok, Kimi, Mistral, Cohere, Together, Groq, Fireworks, OpenRouter, Hugging Face, LM Studio, vLLM, llama.cpp, LangChain, Vercel AI SDK, and additional compatible providers - **Embedder functions built in** — the same adapter pattern covers text embeddings, so you can reuse provider config for both chat and RAG - **One-line local AI** — `ollama({ model: 'llama3.1' })` for fully offline agents with no API key required @@ -110,7 +110,7 @@ const router = createRouter({ }) ``` -See [Adapter router](https://www.agentskit.io/docs/recipes/adapter-router), [Ensemble](https://www.agentskit.io/docs/recipes/adapter-ensemble), and [Fallback chain](https://www.agentskit.io/docs/recipes/fallback-chain). +See [Adapter router](https://www.agentskit.io/docs/reference/recipes/adapter-router), [Ensemble](https://www.agentskit.io/docs/reference/recipes/adapter-ensemble), and [Fallback chain](https://www.agentskit.io/docs/reference/recipes/fallback-chain). ## Ecosystem diff --git a/packages/adapters/package.json b/packages/adapters/package.json index d036729b..f41043f1 100644 --- a/packages/adapters/package.json +++ b/packages/adapters/package.json @@ -89,7 +89,7 @@ "stabilityNote": "Contract v1 is mechanically covered across fetch adapters and provider-specific resilience suites; stable promotion awaits soak and qualifying minor releases." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/adapters", + "homepage": "https://www.agentskit.io/docs/reference/packages/adapters", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/angular/README.md b/packages/angular/README.md index 8853ef39..a1b71644 100644 --- a/packages/angular/README.md +++ b/packages/angular/README.md @@ -18,7 +18,7 @@ Angular 18+ service (Signal + RxJS) + headless chat components. Same `ChatReturn ## Verified proof - Package metadata and tests live under `packages/angular/`. -- Package guide: https://www.agentskit.io/docs/packages/angular +- Package guide: https://www.agentskit.io/docs/reference/packages/angular - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -30,7 +30,7 @@ Angular 18+ service (Signal + RxJS) + headless chat components. Same `ChatReturn - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/angular) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/angular) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why @@ -117,7 +117,7 @@ MIT — see [LICENSE](../../LICENSE). ## Docs -[Full documentation](https://www.agentskit.io/docs/packages/angular) · [GitHub](https://github.com/AgentsKit-io/agentskit) +[Full documentation](https://www.agentskit.io/docs/reference/packages/angular) · [GitHub](https://github.com/AgentsKit-io/agentskit) ## Maturity and compatibility diff --git a/packages/angular/package.json b/packages/angular/package.json index 2c1ba54c..a5b8eeae 100644 --- a/packages/angular/package.json +++ b/packages/angular/package.json @@ -77,7 +77,7 @@ "stabilityNote": "AgentskitChat service (ChatReturn contract) + full headless component parity with @agentskit/react (standalone, partial-Ivy AOT/APF)." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/angular", + "homepage": "https://www.agentskit.io/docs/reference/packages/angular", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/cli/README.md b/packages/cli/README.md index 6393c18f..9462d72f 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -20,7 +20,7 @@ Chat with any LLM, scaffold projects, and run agents — all from your terminal. ## Verified proof - Package metadata and tests live under `packages/cli/`. -- Package guide: https://www.agentskit.io/docs/packages/cli +- Package guide: https://www.agentskit.io/docs/reference/packages/cli - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -32,7 +32,7 @@ Chat with any LLM, scaffold projects, and run agents — all from your terminal. - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/cli) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/cli) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why cli diff --git a/packages/cli/package.json b/packages/cli/package.json index 97e256f7..15833d9b 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -84,7 +84,7 @@ "stabilityNote": "chat, init, run commands stable." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/cli", + "homepage": "https://www.agentskit.io/docs/reference/packages/cli", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/cli/src/init.ts b/packages/cli/src/init.ts index 4289f90a..6adf5ff5 100644 --- a/packages/cli/src/init.ts +++ b/packages/cli/src/init.ts @@ -1501,8 +1501,8 @@ ${runCmd} ## Next steps - Open the AgentsKit docs at https://www.agentskit.io/docs -- Add a custom skill: https://www.agentskit.io/docs/concepts/skill -- Wire up RAG: https://www.agentskit.io/docs/recipes/rag-chat +- Add a custom skill: https://www.agentskit.io/docs/get-started/concepts/skill +- Wire up RAG: https://www.agentskit.io/docs/reference/recipes/rag-chat ## License diff --git a/packages/core/README.md b/packages/core/README.md index 5cb99821..af1cf33d 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -18,7 +18,7 @@ The zero-dependency foundation that every AgentsKit package builds on — 5 KB g ## Verified proof - Package metadata and tests live under `packages/core/`. -- Package guide: https://www.agentskit.io/docs/packages/core +- Package guide: https://www.agentskit.io/docs/reference/packages/core - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -30,7 +30,7 @@ The zero-dependency foundation that every AgentsKit package builds on — 5 KB g - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/core) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/core) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why core @@ -90,11 +90,11 @@ try { if (err instanceof ToolError) { // err.code → 'AK_TOOL_EXEC_FAILED' // err.hint → actionable suggestion - // err.docsUrl → https://www.agentskit.io/docs/tools + // err.docsUrl → https://www.agentskit.io/docs/agents/tools console.error(err.toString()) // error[AK_TOOL_EXEC_FAILED]: ... // --> Hint: ... - // --> Docs: https://www.agentskit.io/docs/tools + // --> Docs: https://www.agentskit.io/docs/agents/tools } } ``` @@ -107,10 +107,25 @@ Available error codes (via `ErrorCodes`): | `AK_ADAPTER_STREAM_FAILED` | streaming call to the provider fails | | `AK_TOOL_NOT_FOUND` | requested tool name is not registered | | `AK_TOOL_EXEC_FAILED` | `execute()` throws | +| `AK_TOOL_PEER_MISSING` | optional tool peer dependency is not installed | +| `AK_TOOL_INVALID_INPUT` | tool arguments or proposal are invalid | +| `AK_TOOL_QUOTA_EXCEEDED` | tool execution exceeds its configured quota | +| `AK_TOOL_FORBIDDEN` | tool execution is denied by policy | | `AK_MEMORY_LOAD_FAILED` | memory.load() fails | | `AK_MEMORY_SAVE_FAILED` | memory.save() fails | | `AK_MEMORY_DESERIALIZE_FAILED` | persisted state is corrupt | +| `AK_MEMORY_PEER_MISSING` | optional memory backend is not installed | +| `AK_MEMORY_REMOTE_HTTP` | remote memory request fails | | `AK_CONFIG_INVALID` | required config is missing or wrong type | +| `AK_RUNTIME_INVALID_INPUT` | runtime input is invalid | +| `AK_RUNTIME_STEP_FAILED` | a runtime step fails | +| `AK_RUNTIME_DELEGATE_FAILED` | delegated agent execution fails | +| `AK_SANDBOX_DENIED` | sandbox policy denies execution | +| `AK_SANDBOX_INVALID_TOOL` | tool is not valid for the sandbox | +| `AK_SANDBOX_PEER_MISSING` | optional sandbox backend is not installed | +| `AK_SANDBOX_BACKEND_FAILED` | sandbox backend fails | +| `AK_SKILL_INVALID` | skill definition is invalid | +| `AK_SKILL_DUPLICATE` | skill identity is duplicated | ## Type-safe tools with `defineTool` @@ -151,7 +166,7 @@ Use `InferSchemaType` to reference the inferred type elsewhere in | `@agentskit/core/manifest` | Skill + tool manifest format (MCP-compatible) | | `@agentskit/core/eval-format` | Portable eval dataset + run-result JSON | -See each page under [docs.agentskit.io / for-agents](https://www.agentskit.io/docs/for-agents/core) for the full contract. +See the [core guide for agents](https://www.agentskit.io/docs/for-agents/core) for the full contract. ## Ecosystem diff --git a/packages/core/package.json b/packages/core/package.json index f10fd6e3..bcf8f0e3 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -135,7 +135,7 @@ "stabilityNote": "Sacred package. Contract-stable per ADRs 0001-0006." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/core", + "homepage": "https://www.agentskit.io/docs/reference/packages/core", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/core/src/errors.ts b/packages/core/src/errors.ts index 0a34c734..11def489 100644 --- a/packages/core/src/errors.ts +++ b/packages/core/src/errors.ts @@ -11,8 +11,8 @@ const DOCS_BASE = 'https://www.agentskit.io/docs' * ``` * error[AK_ADAPTER_MISSING]: No adapter provided * --> Hint: Pass an adapter when creating the chat controller, e.g. - * createChatController({ adapter: openaiAdapter() }) - * --> Docs: https://www.agentskit.io/docs/adapters + * createChatController({ adapter: openai({ apiKey, model: 'gpt-4o' }) }) + * --> Docs: https://www.agentskit.io/docs/data/providers * ``` */ function formatError(code: string, message: string, hint?: string, docsUrl?: string): string { @@ -64,7 +64,7 @@ export class AdapterError extends AgentsKitError { docsUrl?: string cause?: unknown }) { - super({ docsUrl: `${DOCS_BASE}/adapters`, ...options }) + super({ docsUrl: `${DOCS_BASE}/data/providers`, ...options }) this.name = 'AdapterError' } } @@ -77,7 +77,7 @@ export class ToolError extends AgentsKitError { docsUrl?: string cause?: unknown }) { - super({ docsUrl: `${DOCS_BASE}/tools`, ...options }) + super({ docsUrl: `${DOCS_BASE}/agents/tools`, ...options }) this.name = 'ToolError' } } @@ -90,7 +90,7 @@ export class MemoryError extends AgentsKitError { docsUrl?: string cause?: unknown }) { - super({ docsUrl: `${DOCS_BASE}/memory`, ...options }) + super({ docsUrl: `${DOCS_BASE}/data/memory`, ...options }) this.name = 'MemoryError' } } @@ -103,7 +103,7 @@ export class ConfigError extends AgentsKitError { docsUrl?: string cause?: unknown }) { - super({ docsUrl: `${DOCS_BASE}/configuration`, ...options }) + super({ docsUrl: `${DOCS_BASE}/get-started/concepts/errors`, ...options }) this.name = 'ConfigError' } } diff --git a/packages/core/tests/errors.test.ts b/packages/core/tests/errors.test.ts index 80595dad..d0a9e33d 100644 --- a/packages/core/tests/errors.test.ts +++ b/packages/core/tests/errors.test.ts @@ -5,6 +5,9 @@ import { ToolError, MemoryError, ConfigError, + RuntimeError, + SandboxError, + SkillError, ErrorCodes, } from '../src/errors' @@ -84,7 +87,7 @@ describe('AdapterError', () => { code: ErrorCodes.AK_ADAPTER_STREAM_FAILED, message: 'stream broke', }) - expect(err.docsUrl).toContain('/adapters') + expect(err.docsUrl).toBe('https://www.agentskit.io/docs/data/providers') }) it('allows overriding docsUrl', () => { @@ -106,7 +109,7 @@ describe('ToolError', () => { expect(err).toBeInstanceOf(AgentsKitError) expect(err).toBeInstanceOf(ToolError) expect(err.name).toBe('ToolError') - expect(err.docsUrl).toContain('/tools') + expect(err.docsUrl).toBe('https://www.agentskit.io/docs/agents/tools') }) }) @@ -119,7 +122,7 @@ describe('MemoryError', () => { expect(err).toBeInstanceOf(AgentsKitError) expect(err).toBeInstanceOf(MemoryError) expect(err.name).toBe('MemoryError') - expect(err.docsUrl).toContain('/memory') + expect(err.docsUrl).toBe('https://www.agentskit.io/docs/data/memory') }) }) @@ -133,11 +136,25 @@ describe('ConfigError', () => { expect(err).toBeInstanceOf(AgentsKitError) expect(err).toBeInstanceOf(ConfigError) expect(err.name).toBe('ConfigError') - expect(err.docsUrl).toContain('/configuration') + expect(err.docsUrl).toBe('https://www.agentskit.io/docs/get-started/concepts/errors') expect(err.hint).toBe('check your config object') }) }) +describe('domain docs links', () => { + it('uses canonical docs routes for every built-in error subclass', () => { + expect(new RuntimeError({ code: 'AK_TEST', message: 'runtime' }).docsUrl).toBe( + 'https://www.agentskit.io/docs/agents/runtime', + ) + expect(new SandboxError({ code: 'AK_TEST', message: 'sandbox' }).docsUrl).toBe( + 'https://www.agentskit.io/docs/production/security/mandatory-sandbox', + ) + expect(new SkillError({ code: 'AK_TEST', message: 'skill' }).docsUrl).toBe( + 'https://www.agentskit.io/docs/agents/skills', + ) + }) +}) + describe('ErrorCodes', () => { it('contains namespaced error codes', () => { expect(ErrorCodes.AK_ADAPTER_MISSING).toBe('AK_ADAPTER_MISSING') @@ -162,6 +179,6 @@ describe('toString() multiline format', () => { expect(lines).toHaveLength(3) expect(lines[0]).toBe('error[AK_TOOL_NOT_FOUND]: Tool "webSearch" not found or has no execute function') expect(lines[1]).toBe(' --> Hint: Register the tool in your ChatConfig, e.g. { tools: [webSearchTool] }.') - expect(lines[2]).toMatch(/^ {2}--> Docs: https:\/\/www\.agentskit\.io\/docs\/tools$/) + expect(lines[2]).toMatch(/^ {2}--> Docs: https:\/\/www\.agentskit\.io\/docs\/agents\/tools$/) }) }) diff --git a/packages/eval-braintrust/README.md b/packages/eval-braintrust/README.md index 03fe5130..dd69f9db 100644 --- a/packages/eval-braintrust/README.md +++ b/packages/eval-braintrust/README.md @@ -17,7 +17,7 @@ Braintrust scoring pipeline for AgentsKit. Ships **8 scorers** in two families a ## Verified proof - Package metadata and tests live under `packages/eval-braintrust/`. -- Package guide: https://www.agentskit.io/docs/packages/eval-braintrust +- Package guide: https://www.agentskit.io/docs/for-agents/eval-braintrust - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -29,7 +29,7 @@ Braintrust scoring pipeline for AgentsKit. Ships **8 scorers** in two families a - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/eval-braintrust) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/for-agents/eval-braintrust) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Install diff --git a/packages/eval-braintrust/package.json b/packages/eval-braintrust/package.json index 7c0491d3..43cc5bb3 100644 --- a/packages/eval-braintrust/package.json +++ b/packages/eval-braintrust/package.json @@ -66,7 +66,7 @@ "stabilityNote": "Scorer API stable; Braintrust SDK is peer-resolved at runtime." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/eval-braintrust", + "homepage": "https://www.agentskit.io/docs/for-agents/eval-braintrust", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/eval/README.md b/packages/eval/README.md index cdb1a26b..f80d2550 100644 --- a/packages/eval/README.md +++ b/packages/eval/README.md @@ -18,7 +18,7 @@ Measure agent quality with numbers, not vibes — ship with confidence. ## Verified proof - Package metadata and tests live under `packages/eval/`. -- Package guide: https://www.agentskit.io/docs/packages/eval +- Package guide: https://www.agentskit.io/docs/reference/packages/eval - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -30,7 +30,7 @@ Measure agent quality with numbers, not vibes — ship with confidence. - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/eval) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/eval) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why eval diff --git a/packages/eval/package.json b/packages/eval/package.json index 015e911b..c2551d9e 100644 --- a/packages/eval/package.json +++ b/packages/eval/package.json @@ -127,7 +127,7 @@ "stabilityNote": "Core APIs stable; richer metrics and reporters coming." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/eval", + "homepage": "https://www.agentskit.io/docs/reference/packages/eval", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/ink/README.md b/packages/ink/README.md index c4c6895b..b5ce8dbf 100644 --- a/packages/ink/README.md +++ b/packages/ink/README.md @@ -20,7 +20,7 @@ Build terminal AI chat interfaces with the exact same API as `@agentskit/react`. ## Verified proof - Package metadata and tests live under `packages/ink/`. -- Package guide: https://www.agentskit.io/docs/packages/ink +- Package guide: https://www.agentskit.io/docs/reference/packages/ink - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -32,7 +32,7 @@ Build terminal AI chat interfaces with the exact same API as `@agentskit/react`. - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/ink) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/ink) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why ink diff --git a/packages/ink/package.json b/packages/ink/package.json index 9795f13e..e546cd30 100644 --- a/packages/ink/package.json +++ b/packages/ink/package.json @@ -70,7 +70,7 @@ "stabilityNote": "Terminal UI at parity with @agentskit/react." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/ink", + "homepage": "https://www.agentskit.io/docs/reference/packages/ink", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/integrations/README.md b/packages/integrations/README.md index 7fc3162e..1a03bebc 100644 --- a/packages/integrations/README.md +++ b/packages/integrations/README.md @@ -17,7 +17,7 @@ integration is HTTP/`fetch`-only: no vendor SDKs are bundled or required ## Verified proof - Package metadata and tests live under `packages/integrations/`. -- Package guide: https://www.agentskit.io/docs/packages/integrations +- Package guide: https://www.agentskit.io/docs/for-agents/integrations - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -29,7 +29,7 @@ integration is HTTP/`fetch`-only: no vendor SDKs are bundled or required - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/integrations) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/for-agents/integrations) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Install diff --git a/packages/integrations/package.json b/packages/integrations/package.json index 6dc1a3a4..230bf3e3 100644 --- a/packages/integrations/package.json +++ b/packages/integrations/package.json @@ -66,7 +66,7 @@ "stabilityNote": "Canonical descriptor/registry/projection contract shipped; 50-service fetch-only catalog; auth/actions/triggers/testing; packed API gates; execution boundaries explicit (ADR-0026). Not yet stable." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/integrations", + "homepage": "https://www.agentskit.io/docs/for-agents/integrations", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/mcp/README.md b/packages/mcp/README.md index 73b7df92..f409d9c9 100644 --- a/packages/mcp/README.md +++ b/packages/mcp/README.md @@ -27,7 +27,7 @@ them from Codex, Claude Code, Cursor, or any MCP host. - **Playbook**: use [playbook.agentskit.io](https://playbook.agentskit.io) for safe tool design, approvals, and agent handoff patterns. - **AKOS**: run the same model with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/mcp) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/agents/tools/mcp) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ```bash diff --git a/packages/mcp/package.json b/packages/mcp/package.json index 4540b2d3..eaa87dd4 100644 --- a/packages/mcp/package.json +++ b/packages/mcp/package.json @@ -59,7 +59,7 @@ "provenance": true }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/mcp", + "homepage": "https://www.agentskit.io/docs/agents/tools/mcp", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/memory/README.md b/packages/memory/README.md index 8fda3dc3..b93ad593 100644 --- a/packages/memory/README.md +++ b/packages/memory/README.md @@ -18,7 +18,7 @@ Persist conversations and add vector search to your agents — swap backends wit ## Verified proof - Package metadata and tests live under `packages/memory/`. -- Package guide: https://www.agentskit.io/docs/packages/memory +- Package guide: https://www.agentskit.io/docs/reference/packages/memory - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -30,7 +30,7 @@ Persist conversations and add vector search to your agents — swap backends wit - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/memory) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/memory) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why memory @@ -116,12 +116,12 @@ Same 3-method `VectorStore` contract — swap without touching agent code. ### Higher-order wrappers (6) -- `createHierarchicalMemory` — MemGPT-style tiers: working / recall / archival. [Recipe](https://www.agentskit.io/docs/recipes/hierarchical-memory). -- `createVirtualizedMemory` — hot window + cold retriever for long sessions. [Recipe](https://www.agentskit.io/docs/recipes/virtualized-memory). -- `createAutoSummarizingMemory` *(via `@agentskit/core/auto-summarize`)* — fold oldest turns into a running summary. [Recipe](https://www.agentskit.io/docs/recipes/auto-summarize). -- `createEncryptedMemory` — AES-GCM-256 envelope over any `ChatMemory`; keys never leave the caller. [Recipe](https://www.agentskit.io/docs/recipes/encrypted-memory). -- `createInMemoryGraph` — knowledge graph (nodes + edges + BFS). [Recipe](https://www.agentskit.io/docs/recipes/graph-memory). -- `createInMemoryPersonalization` + `renderProfileContext` — per-user trait profile. [Recipe](https://www.agentskit.io/docs/recipes/personalization). +- `createHierarchicalMemory` — MemGPT-style tiers: working / recall / archival. [Recipe](https://www.agentskit.io/docs/reference/recipes/hierarchical-memory). +- `createVirtualizedMemory` — hot window + cold retriever for long sessions. [Recipe](https://www.agentskit.io/docs/reference/recipes/virtualized-memory). +- `createAutoSummarizingMemory` *(via `@agentskit/core/auto-summarize`)* — fold oldest turns into a running summary. [Recipe](https://www.agentskit.io/docs/reference/recipes/auto-summarize). +- `createEncryptedMemory` — AES-GCM-256 envelope over any `ChatMemory`; keys never leave the caller. [Recipe](https://www.agentskit.io/docs/reference/recipes/encrypted-memory). +- `createInMemoryGraph` — knowledge graph (nodes + edges + BFS). [Recipe](https://www.agentskit.io/docs/reference/recipes/graph-memory). +- `createInMemoryPersonalization` + `renderProfileContext` — per-user trait profile. [Recipe](https://www.agentskit.io/docs/reference/recipes/personalization). Memory contract v1 (ADR 0003) — substitutable across `runtime`, `useChat`, and every framework binding. diff --git a/packages/memory/package.json b/packages/memory/package.json index e92f8366..5045590f 100644 --- a/packages/memory/package.json +++ b/packages/memory/package.json @@ -76,7 +76,7 @@ "stabilityNote": "File/SQLite/Redis backends — Memory contract v1." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/memory", + "homepage": "https://www.agentskit.io/docs/reference/packages/memory", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/observability-langfuse/README.md b/packages/observability-langfuse/README.md index 1dcee70e..ac81cbe1 100644 --- a/packages/observability-langfuse/README.md +++ b/packages/observability-langfuse/README.md @@ -14,7 +14,7 @@ Langfuse tracing adapter for AgentsKit. Emits one trace per agent run with neste ## Verified proof - Package metadata and tests live under `packages/observability-langfuse/`. -- Package guide: https://www.agentskit.io/docs/packages/observability-langfuse +- Package guide: https://www.agentskit.io/docs/for-agents/observability-langfuse - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -26,7 +26,7 @@ Langfuse tracing adapter for AgentsKit. Emits one trace per agent run with neste - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/observability-langfuse) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/for-agents/observability-langfuse) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Install diff --git a/packages/observability-langfuse/package.json b/packages/observability-langfuse/package.json index a22cdcad..b278ba28 100644 --- a/packages/observability-langfuse/package.json +++ b/packages/observability-langfuse/package.json @@ -56,7 +56,7 @@ "stabilityNote": "Adapter contract stable; Langfuse SDK is peer-resolved at runtime." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/observability-langfuse", + "homepage": "https://www.agentskit.io/docs/for-agents/observability-langfuse", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/observability/README.md b/packages/observability/README.md index 30ff0d6d..e1f6e10d 100644 --- a/packages/observability/README.md +++ b/packages/observability/README.md @@ -18,7 +18,7 @@ See exactly what your agent does — every LLM call, tool execution, and reasoni ## Verified proof - Package metadata and tests live under `packages/observability/`. -- Package guide: https://www.agentskit.io/docs/packages/observability +- Package guide: https://www.agentskit.io/docs/reference/packages/observability - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -30,7 +30,7 @@ See exactly what your agent does — every LLM call, tool execution, and reasoni - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/observability) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/observability) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why observability diff --git a/packages/observability/package.json b/packages/observability/package.json index c79cc8cd..8ed8b408 100644 --- a/packages/observability/package.json +++ b/packages/observability/package.json @@ -105,7 +105,7 @@ "stabilityNote": "Observer contract stable; integration coverage growing." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/observability", + "homepage": "https://www.agentskit.io/docs/reference/packages/observability", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/rag/README.md b/packages/rag/README.md index 9f8b620b..c35a0431 100644 --- a/packages/rag/README.md +++ b/packages/rag/README.md @@ -18,7 +18,7 @@ Plug-and-play retrieval-augmented generation: chunk documents, embed them, and r ## Verified proof - Package metadata and tests live under `packages/rag/`. -- Package guide: https://www.agentskit.io/docs/packages/rag +- Package guide: https://www.agentskit.io/docs/reference/packages/rag - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -30,7 +30,7 @@ Plug-and-play retrieval-augmented generation: chunk documents, embed them, and r - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/rag) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/rag) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why rag @@ -94,8 +94,8 @@ You can also call `rag.retrieve({ query, messages })` to satisfy the core `Retri - `rag.retrieve({ query, messages })` — `Retriever` contract v1 for runtime/controller injection. - Configurable chunking: `chunkSize`, `chunkOverlap`, custom `split`. - Works with any `EmbedFn` and any `VectorMemory`. -- **Rerankers:** `createRerankedRetriever` (Cohere Rerank, BGE, BM25 default), `createHybridRetriever` (vector + BM25 blend), standalone `bm25Score`. [Recipe](https://www.agentskit.io/docs/recipes/rag-reranking). -- **Document loaders:** `loadUrl`, `loadGitHubFile`, `loadGitHubTree`, `loadNotionPage`, `loadConfluencePage`, `loadGoogleDriveFile`, `loadPdf` (BYO parser). [Recipe](https://www.agentskit.io/docs/recipes/doc-loaders). +- **Rerankers:** `createRerankedRetriever` (Voyage, Jina, custom `RerankFn`, BM25 default), `createHybridRetriever` (vector + BM25 blend), standalone `bm25Score`. [Recipe](https://www.agentskit.io/docs/reference/recipes/rag-reranking). +- **Document loaders:** `loadUrl`, `loadGitHubFile`, `loadGitHubTree`, `loadNotionPage`, `loadConfluencePage`, `loadGoogleDriveFile`, `loadPdf` (BYO parser). [Recipe](https://www.agentskit.io/docs/reference/recipes/doc-loaders). - **Loader resilience:** HTTP/network and response-body read/parse failures surface as `RagError` (`AK_RAG_LOAD_FAILED`). Optional `signal` aborts (including mid-body reads) are never swallowed as a per-object skip. Tree/list loaders may return partial success when at least one eligible download succeeded; if every attempted eligible download failed, they throw. Missing/invalid S3 object bodies count as failed downloads. Pagination that reports more data without a new cursor/token throws (no silent truncation). `loadNotionPage` follows Notion `has_more` / `next_cursor` with `start_cursor` until complete (preserving block order; incomplete or repeated cursors throw). Non-positive / non-finite `maxFiles` yields `[]`. - **Score contracts:** scoreless search/rerank results keep order. When any score is present, every result must have a finite numeric score and is sorted descending — mixed or non-finite scores throw (never fabricate `-Infinity`). Malformed Voyage/Jina/custom reranker output throws `AK_RAG_RERANK_FAILED`. Optional `signal` on `voyageReranker` / `jinaReranker` is forwarded to `fetch`; request/body aborts remain `AK_RAG_RERANK_FAILED`. `bm25Score` sanitizes invalid `k1`/`b` to documented defaults and always emits finite scores. Hybrid relative weights are normalized to a finite pair that sums to 1 (both zero → 0.5/0.5). - **Chunk/config safety:** invalid `chunkSize` / `chunkOverlap` / `topK` values are sanitized so chunking always terminates and search never sends non-finite limits to the store. diff --git a/packages/rag/package.json b/packages/rag/package.json index ce748f56..2397d05a 100644 --- a/packages/rag/package.json +++ b/packages/rag/package.json @@ -76,7 +76,7 @@ "stabilityNote": "Retriever contract v1. Ingest + retrieve shipped." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/rag", + "homepage": "https://www.agentskit.io/docs/reference/packages/rag", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/rag/src/errors.ts b/packages/rag/src/errors.ts index 1186ca28..0c90e34d 100644 --- a/packages/rag/src/errors.ts +++ b/packages/rag/src/errors.ts @@ -1,5 +1,7 @@ import { AgentsKitError } from '@agentskit/core' +const RAG_DOCS_URL = 'https://www.agentskit.io/docs/data/rag' + /** * Error codes raised by `@agentskit/rag` loaders and rerankers. Kept local to * the package (rather than in core's `ErrorCodes`) because they describe RAG @@ -23,7 +25,7 @@ export type RagErrorCode = (typeof RagErrorCodes)[keyof typeof RagErrorCodes] */ export class RagError extends AgentsKitError { constructor(options: { code: RagErrorCode; message: string; hint?: string; cause?: unknown }) { - super(options) + super({ docsUrl: RAG_DOCS_URL, ...options }) this.name = 'RagError' } } diff --git a/packages/rag/tests/errors.test.ts b/packages/rag/tests/errors.test.ts index 2513b658..b62c2be3 100644 --- a/packages/rag/tests/errors.test.ts +++ b/packages/rag/tests/errors.test.ts @@ -8,6 +8,7 @@ describe('RagError', () => { expect(err).toBeInstanceOf(AgentsKitError) expect(err).toBeInstanceOf(Error) expect(err.name).toBe('RagError') + expect(err.docsUrl).toBe('https://www.agentskit.io/docs/data/rag') }) it('carries the code and message', () => { diff --git a/packages/react-native/README.md b/packages/react-native/README.md index 5d45ec43..020031ce 100644 --- a/packages/react-native/README.md +++ b/packages/react-native/README.md @@ -18,7 +18,7 @@ React Native / Expo hook + headless chat components. Metro-safe (no DOM deps). S ## Verified proof - Package metadata and tests live under `packages/react-native/`. -- Package guide: https://www.agentskit.io/docs/packages/react-native +- Package guide: https://www.agentskit.io/docs/reference/packages/react-native - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -30,7 +30,7 @@ React Native / Expo hook + headless chat components. Metro-safe (no DOM deps). S - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/react-native) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/react-native) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why @@ -108,7 +108,7 @@ MIT — see [LICENSE](../../LICENSE). ## Docs -[Full documentation](https://www.agentskit.io/docs/packages/react-native) · [GitHub](https://github.com/AgentsKit-io/agentskit) +[Full documentation](https://www.agentskit.io/docs/reference/packages/react-native) · [GitHub](https://github.com/AgentsKit-io/agentskit) ## Maturity and compatibility diff --git a/packages/react-native/package.json b/packages/react-native/package.json index 00c68a12..b06985b2 100644 --- a/packages/react-native/package.json +++ b/packages/react-native/package.json @@ -73,7 +73,7 @@ "stabilityNote": "React Native / Expo binding — full headless component parity with @agentskit/react (8 components), rendered with RN primitives and a testID-based headless convention." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/react-native", + "homepage": "https://www.agentskit.io/docs/reference/packages/react-native", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/react/CONVENTIONS.md b/packages/react/CONVENTIONS.md index 1a7edc42..00051620 100644 --- a/packages/react/CONVENTIONS.md +++ b/packages/react/CONVENTIONS.md @@ -45,7 +45,7 @@ React hooks and headless UI components for AgentsKit. Everything here runs in a - Use `@testing-library/react` + `happy-dom` (already configured). - Test observable behavior: what the user sees, not what the component does internally. -- Use a mock `AdapterFactory` (see [Recipe: Custom adapter](../../apps/docs-next/content/docs/recipes/custom-adapter.mdx)) for hook tests. +- Use a mock `AdapterFactory` (see [Recipe: Custom adapter](../../apps/docs-next/content/docs/reference/recipes/custom-adapter.mdx)) for hook tests. - Snapshot tests for components are acceptable; snapshot tests for LLM output are not. ## Common pitfalls diff --git a/packages/react/README.md b/packages/react/README.md index 71b734c5..c8667fc1 100644 --- a/packages/react/README.md +++ b/packages/react/README.md @@ -18,7 +18,7 @@ Add streaming AI chat to any React app in 10 lines of code. ## Verified proof - Package metadata and tests live under `packages/react/`. -- Package guide: https://www.agentskit.io/docs/packages/react +- Package guide: https://www.agentskit.io/docs/reference/packages/react - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -30,7 +30,7 @@ Add streaming AI chat to any React app in 10 lines of code. - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/react) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/react) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why react diff --git a/packages/react/package.json b/packages/react/package.json index 8cb0f297..6869e52d 100644 --- a/packages/react/package.json +++ b/packages/react/package.json @@ -78,7 +78,7 @@ "stabilityNote": "Production-ready hooks and headless components." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/react", + "homepage": "https://www.agentskit.io/docs/reference/packages/react", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/runtime/README.md b/packages/runtime/README.md index 4216e33e..640c0dca 100644 --- a/packages/runtime/README.md +++ b/packages/runtime/README.md @@ -18,7 +18,7 @@ Run autonomous agents in 5 lines — no UI, no boilerplate, just results. ## Verified proof - Package metadata and tests live under `packages/runtime/`. -- Package guide: https://www.agentskit.io/docs/packages/runtime +- Package guide: https://www.agentskit.io/docs/reference/packages/runtime - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -30,7 +30,7 @@ Run autonomous agents in 5 lines — no UI, no boilerplate, just results. - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/runtime) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/runtime) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why runtime @@ -94,10 +94,10 @@ console.log(result.content) | Primitive | Purpose | Docs | |-----------|---------|------| -| `createDurableRunner` + `createFileStepLog` | Temporal-style step log; resume on crash | [Durable execution](https://www.agentskit.io/docs/recipes/durable-execution) | -| `supervisor` / `swarm` / `hierarchical` / `blackboard` | Ready-made multi-agent topologies | [Topologies](https://www.agentskit.io/docs/recipes/multi-agent-topologies) | -| `speculate` | Fan-out N adapters, race + abort losers | [Speculative execution](https://www.agentskit.io/docs/recipes/speculative-execution) | -| `createCronScheduler` + `createWebhookHandler` | Background agents, cron + webhooks | [Background agents](https://www.agentskit.io/docs/recipes/background-agents) | +| `createDurableRunner` + `createFileStepLog` | Temporal-style step log; resume on crash | [Durable execution](https://www.agentskit.io/docs/reference/recipes/durable-execution) | +| `supervisor` / `swarm` / `hierarchical` / `blackboard` | Ready-made multi-agent topologies | [Topologies](https://www.agentskit.io/docs/reference/recipes/multi-agent-topologies) | +| `speculate` | Fan-out N adapters, race + abort losers | [Speculative execution](https://www.agentskit.io/docs/reference/recipes/speculative-execution) | +| `createCronScheduler` + `createWebhookHandler` | Background agents, cron + webhooks | [Background agents](https://www.agentskit.io/docs/reference/recipes/background-agents) | ## Ecosystem diff --git a/packages/runtime/package.json b/packages/runtime/package.json index 8530374f..46a1a0ae 100644 --- a/packages/runtime/package.json +++ b/packages/runtime/package.json @@ -67,7 +67,7 @@ "stabilityNote": "ReAct loop and delegation per ADR 0006." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/runtime", + "homepage": "https://www.agentskit.io/docs/reference/packages/runtime", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/sandbox/README.md b/packages/sandbox/README.md index 0ad81306..f6870b23 100644 --- a/packages/sandbox/README.md +++ b/packages/sandbox/README.md @@ -18,7 +18,7 @@ Let agents write and run code safely — in isolated cloud VMs (E2B), constraine ## Verified proof - Package metadata and tests live under `packages/sandbox/`. -- Package guide: https://www.agentskit.io/docs/packages/sandbox +- Package guide: https://www.agentskit.io/docs/reference/packages/sandbox - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) - Graduation track: [RFC 0013](../../rfcs/0013-sandbox-stable.md) (Proposed — not stable) @@ -31,7 +31,7 @@ Let agents write and run code safely — in isolated cloud VMs (E2B), constraine - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/sandbox) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/sandbox) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why sandbox diff --git a/packages/sandbox/package.json b/packages/sandbox/package.json index 7e944ed6..0dfe21e6 100644 --- a/packages/sandbox/package.json +++ b/packages/sandbox/package.json @@ -87,7 +87,7 @@ "stabilityNote": "Lifecycle/config/runtime hardening complete on the beta line; E2B peer optional; Web Worker is thread+DOM only (not WebContainer). Stable promotion awaits soak and qualifying releases." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/sandbox", + "homepage": "https://www.agentskit.io/docs/reference/packages/sandbox", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/skills/README.md b/packages/skills/README.md index 050fcb1a..66306cc2 100644 --- a/packages/skills/README.md +++ b/packages/skills/README.md @@ -18,7 +18,7 @@ Reusable agent personas and behavioral instructions — skills describe what you ## Verified proof - Package metadata and tests live under `packages/skills/`. -- Package guide: https://www.agentskit.io/docs/packages/skills +- Package guide: https://www.agentskit.io/docs/reference/packages/skills - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -30,7 +30,7 @@ Reusable agent personas and behavioral instructions — skills describe what you - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/skills) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/skills) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why skills diff --git a/packages/skills/package.json b/packages/skills/package.json index 1102a952..0ca8e8d6 100644 --- a/packages/skills/package.json +++ b/packages/skills/package.json @@ -62,7 +62,7 @@ "stabilityNote": "ADR-0005 contract and 26-skill catalog hardened; remains beta pending the post-0.9 soak, a second minor line, Accepted RFC/evidence, and 1.0.0." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/skills", + "homepage": "https://www.agentskit.io/docs/reference/packages/skills", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/solid/README.md b/packages/solid/README.md index 43cd8bf5..6db2a493 100644 --- a/packages/solid/README.md +++ b/packages/solid/README.md @@ -18,7 +18,7 @@ SolidJS hook + headless chat components. Same `ChatReturn` contract every Agents ## Verified proof - Package metadata and tests live under `packages/solid/`. -- Package guide: https://www.agentskit.io/docs/packages/solid +- Package guide: https://www.agentskit.io/docs/reference/packages/solid - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -30,7 +30,7 @@ SolidJS hook + headless chat components. Same `ChatReturn` contract every Agents - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/solid) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/solid) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why @@ -107,7 +107,7 @@ MIT — see [LICENSE](../../LICENSE). ## Docs -[Full documentation](https://www.agentskit.io/docs/packages/solid) · [GitHub](https://github.com/AgentsKit-io/agentskit) +[Full documentation](https://www.agentskit.io/docs/reference/packages/solid) · [GitHub](https://github.com/AgentsKit-io/agentskit) ## Maturity and compatibility diff --git a/packages/solid/package.json b/packages/solid/package.json index 64f07b1d..b9f8219f 100644 --- a/packages/solid/package.json +++ b/packages/solid/package.json @@ -72,7 +72,7 @@ "stabilityNote": "Solid binding with full headless component parity with @agentskit/react — same ChatReturn contract and data-ak-* attributes." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/solid", + "homepage": "https://www.agentskit.io/docs/reference/packages/solid", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/statechart/README.md b/packages/statechart/README.md index e37e7f8a..0f7a0d6d 100644 --- a/packages/statechart/README.md +++ b/packages/statechart/README.md @@ -20,7 +20,7 @@ Use Runtime flows for durable execution, DAGs, tools, and effects. Use this pack ## Verified proof - Package metadata and tests live under `packages/statechart/`. -- Package guide: https://www.agentskit.io/docs/packages/statechart +- Package guide: https://www.agentskit.io/docs/reference/packages/statechart - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## Install diff --git a/packages/statechart/package.json b/packages/statechart/package.json index 6148962d..98b99e14 100644 --- a/packages/statechart/package.json +++ b/packages/statechart/package.json @@ -52,7 +52,7 @@ "stabilityNote": "Deterministic transition and hostile-input boundaries hardened for beta (ADR-0020, ADR-0027)." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/statechart", + "homepage": "https://www.agentskit.io/docs/reference/packages/statechart", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/svelte/README.md b/packages/svelte/README.md index e636d621..fdd344ba 100644 --- a/packages/svelte/README.md +++ b/packages/svelte/README.md @@ -18,7 +18,7 @@ Svelte 5 store + headless chat components. Same `ChatReturn` contract every Agen ## Verified proof - Package metadata and tests live under `packages/svelte/`. -- Package guide: https://www.agentskit.io/docs/packages/svelte +- Package guide: https://www.agentskit.io/docs/reference/packages/svelte - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -30,7 +30,7 @@ Svelte 5 store + headless chat components. Same `ChatReturn` contract every Agen - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/svelte) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/svelte) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why @@ -100,7 +100,7 @@ MIT — see [LICENSE](../../LICENSE). ## Docs -[Full documentation](https://www.agentskit.io/docs/packages/svelte) · [GitHub](https://github.com/AgentsKit-io/agentskit) +[Full documentation](https://www.agentskit.io/docs/reference/packages/svelte) · [GitHub](https://github.com/AgentsKit-io/agentskit) ## Quick start diff --git a/packages/svelte/package.json b/packages/svelte/package.json index 502b0ca0..69ef587a 100644 --- a/packages/svelte/package.json +++ b/packages/svelte/package.json @@ -70,7 +70,7 @@ "stabilityNote": "createChatStore (ChatReturn contract) + full headless component parity with @agentskit/react (Svelte 5 runes)." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/svelte", + "homepage": "https://www.agentskit.io/docs/reference/packages/svelte", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/templates/README.md b/packages/templates/README.md index 4ebdc493..8e1c062b 100644 --- a/packages/templates/README.md +++ b/packages/templates/README.md @@ -20,7 +20,7 @@ and publish. ## Verified proof - Package metadata and tests live under `packages/templates/`. -- Package guide: https://www.agentskit.io/docs/packages/templates +- Package guide: https://www.agentskit.io/docs/reference/packages/templates - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -33,7 +33,7 @@ and package starters without inventing package shape from scratch. - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/templates) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/templates) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why templates diff --git a/packages/templates/package.json b/packages/templates/package.json index 63030eeb..682b96d1 100644 --- a/packages/templates/package.json +++ b/packages/templates/package.json @@ -60,7 +60,7 @@ "stabilityNote": "Scaffold/validation hardening complete; remains beta until promotion gates in RFC 0014." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/templates", + "homepage": "https://www.agentskit.io/docs/reference/packages/templates", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/tools/README.md b/packages/tools/README.md index 31bd76fb..edf226c3 100644 --- a/packages/tools/README.md +++ b/packages/tools/README.md @@ -18,7 +18,7 @@ Give your agents real-world capabilities without writing a single integration. ## Verified proof - Package metadata and tests live under `packages/tools/`. -- Package guide: https://www.agentskit.io/docs/packages/tools +- Package guide: https://www.agentskit.io/docs/reference/packages/tools - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -30,7 +30,7 @@ Give your agents real-world capabilities without writing a single integration. - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/tools) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/tools) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why tools @@ -151,8 +151,8 @@ or a custom loop. | Subpath | Contents | |---------|----------| -| `@agentskit/tools/mcp` | `createMcpClient`, `createMcpServer`, `toolsFromMcpClient`, stdio + in-memory transports. [MCP bridge recipe](https://www.agentskit.io/docs/recipes/mcp-bridge). | -| `@agentskit/tools/integrations` | `github`, `linear`, `slack`, `notion`, `discord`, `gmail`, `googleCalendar`, `stripe`, `postgres`, `s3`, `firecrawl`, `reader`, `documentParsers`, `openaiImages`, `elevenlabs`, `whisper`, `deepgram`, `maps`, `weather`, `coingecko`, `browserAgent`. [Integrations recipe](https://www.agentskit.io/docs/recipes/integrations) + [More integrations](https://www.agentskit.io/docs/recipes/more-integrations). | +| `@agentskit/tools/mcp` | `createMcpClient`, `createMcpServer`, `toolsFromMcpClient`, stdio + in-memory transports. [MCP bridge recipe](https://www.agentskit.io/docs/reference/recipes/mcp-bridge). | +| `@agentskit/tools/integrations` | `github`, `linear`, `slack`, `notion`, `discord`, `gmail`, `googleCalendar`, `stripe`, `postgres`, `s3`, `firecrawl`, `reader`, `documentParsers`, `openaiImages`, `elevenlabs`, `whisper`, `deepgram`, `maps`, `weather`, `coingecko`, `browserAgent`. [Integrations recipe](https://www.agentskit.io/docs/reference/recipes/integrations) + [More integrations](https://www.agentskit.io/docs/reference/recipes/more-integrations). | ## Ecosystem diff --git a/packages/tools/package.json b/packages/tools/package.json index aadf6aac..921b41d4 100644 --- a/packages/tools/package.json +++ b/packages/tools/package.json @@ -96,7 +96,7 @@ "stabilityNote": "Web search, filesystem, shell tools — Tool contract v1." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/tools", + "homepage": "https://www.agentskit.io/docs/reference/packages/tools", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/validation/README.md b/packages/validation/README.md index 71531a98..c14430f1 100644 --- a/packages/validation/README.md +++ b/packages/validation/README.md @@ -20,7 +20,7 @@ Validation is not automatic. You must pass the validator as `validateArgs`; tool - Adversarial tests cover nested objects, arrays, local references, structured paths, coercion, custom Ajv instances, schema failures, caching, and strict-extra behavior. - Public consumers import `@agentskit/tools/validation`; `@agentskit/validation` is a private workspace implementation. -- Package guide: https://www.agentskit.io/docs/packages/validation +- Package guide: https://www.agentskit.io/docs/for-agents/validation - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -32,7 +32,7 @@ Validation is not automatic. You must pass the validator as `validateArgs`; tool - **Playbook**: learn production validation patterns at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: apply the same boundary with enterprise governance at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/validation) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/for-agents/validation) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Install diff --git a/packages/validation/package.json b/packages/validation/package.json index 1fc25059..8bf35125 100644 --- a/packages/validation/package.json +++ b/packages/validation/package.json @@ -54,7 +54,7 @@ "stabilityNote": "Private Ajv implementation hardened behind @agentskit/tools/validation; graduation is coupled to the public tools surface (ADR-0008, RFC-0015)." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/validation", + "homepage": "https://www.agentskit.io/docs/for-agents/validation", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", diff --git a/packages/vue/README.md b/packages/vue/README.md index 418cf6bc..a11eacdc 100644 --- a/packages/vue/README.md +++ b/packages/vue/README.md @@ -18,7 +18,7 @@ Vue 3 composable + headless chat components. Same `ChatReturn` contract every Ag ## Verified proof - Package metadata and tests live under `packages/vue/`. -- Package guide: https://www.agentskit.io/docs/packages/vue +- Package guide: https://www.agentskit.io/docs/reference/packages/vue - Stability map: [docs/STABILITY.md](../../docs/STABILITY.md) ## How this fits the ecosystem @@ -30,7 +30,7 @@ Vue 3 composable + headless chat components. Same `ChatReturn` contract every Ag - **Playbook**: learn the production patterns behind this layer at [playbook.agentskit.io](https://playbook.agentskit.io). - **AKOS**: run the same concepts with enterprise deployment, governance, and observability at [akos.agentskit.io](https://akos.agentskit.io). -Docs: [package guide](https://www.agentskit.io/docs/packages/vue) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) +Docs: [package guide](https://www.agentskit.io/docs/reference/packages/vue) · [agent handoff](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt) ## Why @@ -105,7 +105,7 @@ MIT — see [LICENSE](../../LICENSE). ## Docs -[Full documentation](https://www.agentskit.io/docs/packages/vue) · [GitHub](https://github.com/AgentsKit-io/agentskit) +[Full documentation](https://www.agentskit.io/docs/reference/packages/vue) · [GitHub](https://github.com/AgentsKit-io/agentskit) ## Quick start diff --git a/packages/vue/package.json b/packages/vue/package.json index 90c459f7..ab959b62 100644 --- a/packages/vue/package.json +++ b/packages/vue/package.json @@ -69,7 +69,7 @@ "stabilityNote": "useChat (ChatReturn contract) + full headless component parity with @agentskit/react; 100% component coverage." }, "license": "MIT", - "homepage": "https://www.agentskit.io/docs/packages/vue", + "homepage": "https://www.agentskit.io/docs/reference/packages/vue", "repository": { "type": "git", "url": "git+https://github.com/AgentsKit-io/agentskit.git", From 378ea67324d1fb5752e1defc804ebb1eedb17354 Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 20:06:17 -0300 Subject: [PATCH 02/19] docs: refresh documentation quality attestation --- .../agentskit.json | 111 +++++++++++++++--- .../doc-bridge/agentskit.json | 2 +- 2 files changed, 98 insertions(+), 15 deletions(-) diff --git a/docs/evidence/ecosystem-documentation-quality/agentskit.json b/docs/evidence/ecosystem-documentation-quality/agentskit.json index 83ecabb1..c5613f65 100644 --- a/docs/evidence/ecosystem-documentation-quality/agentskit.json +++ b/docs/evidence/ecosystem-documentation-quality/agentskit.json @@ -4,19 +4,42 @@ "profileVersion": 1, "productId": "agentskit", "repo": "AgentsKit-io/agentskit", - "commit": "69a850403dd08619ded6d191dbb190f0a4a3dd99", - "auditedOn": "2026-07-28", + "commit": "12ab72e14db59c860c19ccfa2693b0998f776cf4", + "auditedOn": "2026-08-12", "docBridge": { "artifact": "docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json", "doctorScore": 100, - "coverage": { "agent": { "ready": 25, "total": 25 }, "human": { "ready": 25, "total": 25 } }, - "conformance": { "requiredPassed": 7, "requiredTotal": 7, "requiredExcepted": 0, "recommendedPassed": 2, "recommendedTotal": 2, "recommendedExcepted": 0 } + "coverage": { + "agent": { + "ready": 25, + "total": 25 + }, + "human": { + "ready": 25, + "total": 25 + } + }, + "conformance": { + "requiredPassed": 7, + "requiredTotal": 7, + "requiredExcepted": 0, + "recommendedPassed": 2, + "recommendedTotal": 2, + "recommendedExcepted": 0 + } + }, + "attestation": { + "sourceMode": "commit", + "contentDigest": "sha256:ee18a9880e9e8020e3cb754678396b7854228323963176e28b4d2e3811481b1b" }, - "attestation": { "sourceMode": "commit", "contentDigest": "sha256:79521950d640005a0594c28e3d1d7493981621cdb35641a0a538a875661470e5" }, "machineSurfaces": { "llmsTxt": "llms.txt", "llmsFullTxt": "apps/docs-next/app/llms-full.txt/route.ts", - "rawSources": ["README.md", "apps/docs-next/content/docs/get-started/getting-started/build-your-first-agent.mdx", "apps/docs-next/content/docs/for-agents/index.mdx"], + "rawSources": [ + "README.md", + "apps/docs-next/content/docs/get-started/getting-started/build-your-first-agent.mdx", + "apps/docs-next/content/docs/for-agents/index.mdx" + ], "forAgents": "apps/docs-next/content/docs/for-agents/index.mdx" }, "narrative": { @@ -25,18 +48,78 @@ "humanDocs": "apps/docs-next/content/docs/index.mdx", "forAgents": "apps/docs-next/content/docs/for-agents/index.mdx", "keyJourneys": [ - { "id": "build-first-agent", "path": "apps/docs-next/content/docs/get-started/getting-started/build-your-first-agent.mdx", "wordCount": 353, "visualDecision": "diagram", "evidence": ["apps/docs-next/content/docs/get-started/getting-started/build-your-first-agent.mdx#execution-flow"] }, - { "id": "architecture-at-a-glance", "path": "apps/docs-next/content/docs/get-started/architecture-at-a-glance.mdx", "wordCount": 372, "visualDecision": "diagram", "evidence": ["apps/docs-next/content/docs/get-started/architecture-at-a-glance.mdx#the-stack-in-one-view"] }, - { "id": "deterministic-docs-answers", "path": "apps/docs-next/content/docs/cookbook/deterministic-docs-answers.mdx", "wordCount": 337, "visualDecision": "diagram", "evidence": ["apps/docs-next/content/docs/cookbook/deterministic-docs-answers.mdx#architecture"] } + { + "id": "build-first-agent", + "path": "apps/docs-next/content/docs/get-started/getting-started/build-your-first-agent.mdx", + "wordCount": 353, + "visualDecision": "diagram", + "evidence": [ + "apps/docs-next/content/docs/get-started/getting-started/build-your-first-agent.mdx#execution-flow" + ] + }, + { + "id": "architecture-at-a-glance", + "path": "apps/docs-next/content/docs/get-started/architecture-at-a-glance.mdx", + "wordCount": 372, + "visualDecision": "diagram", + "evidence": [ + "apps/docs-next/content/docs/get-started/architecture-at-a-glance.mdx#the-stack-in-one-view" + ] + }, + { + "id": "deterministic-docs-answers", + "path": "apps/docs-next/content/docs/cookbook/deterministic-docs-answers.mdx", + "wordCount": 337, + "visualDecision": "diagram", + "evidence": [ + "apps/docs-next/content/docs/cookbook/deterministic-docs-answers.mdx#architecture" + ] + } ] }, "discovery": { - "globalProductIds": ["agentskit", "registry", "agentskit-chat", "playbook", "doc-bridge", "code-review", "akos"], - "siblingProductIds": ["registry", "agentskit-chat", "playbook", "doc-bridge", "code-review", "akos"], + "globalProductIds": [ + "agentskit", + "registry", + "agentskit-chat", + "playbook", + "doc-bridge", + "code-review", + "akos" + ], + "siblingProductIds": [ + "registry", + "agentskit-chat", + "playbook", + "doc-bridge", + "code-review", + "akos" + ], "contextualHooks": [ - { "id": "documentation", "status": "linked", "targetProductId": "doc-bridge", "evidence": ["apps/docs-next/content/docs/get-started/getting-started/build-your-first-agent.mdx"] }, - { "id": "chat", "status": "linked", "targetProductId": "agentskit-chat", "evidence": ["apps/docs-next/content/docs/get-started/getting-started/build-your-first-agent.mdx"] }, - { "id": "enterprise", "status": "linked", "targetProductId": "akos", "evidence": ["apps/docs-next/content/docs/get-started/getting-started/build-your-first-agent.mdx"] } + { + "id": "documentation", + "status": "linked", + "targetProductId": "doc-bridge", + "evidence": [ + "apps/docs-next/content/docs/get-started/getting-started/build-your-first-agent.mdx" + ] + }, + { + "id": "chat", + "status": "linked", + "targetProductId": "agentskit-chat", + "evidence": [ + "apps/docs-next/content/docs/get-started/getting-started/build-your-first-agent.mdx" + ] + }, + { + "id": "enterprise", + "status": "linked", + "targetProductId": "akos", + "evidence": [ + "apps/docs-next/content/docs/get-started/getting-started/build-your-first-agent.mdx" + ] + } ] } } diff --git a/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json b/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json index 23ab4a00..91d36926 100644 --- a/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json +++ b/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json @@ -1 +1 @@ -{"schemaVersion":1,"protocol":"agentskit.doc-bridge.attestation","productId":"agentskit","repo":"AgentsKit-io/agentskit","commit":"69a850403dd08619ded6d191dbb190f0a4a3dd99","sourceMode":"commit","contentDigest":"sha256:79521950d640005a0594c28e3d1d7493981621cdb35641a0a538a875661470e5","command":"pnpm docs:bridge:doctor && pnpm docs:bridge:gate","metrics":{"doctorScore":100,"coverage":{"agent":{"ready":25,"total":25},"human":{"ready":25,"total":25}},"conformance":{"requiredPassed":7,"requiredTotal":7,"requiredExcepted":0,"recommendedPassed":2,"recommendedTotal":2,"recommendedExcepted":0}}} +{"schemaVersion":1,"protocol":"agentskit.doc-bridge.attestation","productId":"agentskit","repo":"AgentsKit-io/agentskit","commit":"12ab72e14db59c860c19ccfa2693b0998f776cf4","sourceMode":"commit","contentDigest":"sha256:ee18a9880e9e8020e3cb754678396b7854228323963176e28b4d2e3811481b1b","command":"pnpm docs:bridge:doctor && pnpm docs:bridge:gate","metrics":{"doctorScore":100,"coverage":{"agent":{"ready":25,"total":25},"human":{"ready":25,"total":25}},"conformance":{"requiredPassed":7,"requiredTotal":7,"requiredExcepted":0,"recommendedPassed":2,"recommendedTotal":2,"recommendedExcepted":0}}} From 39a5951cf7634ec9f6703e4c91ef2e3476bd35f2 Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 20:23:41 -0300 Subject: [PATCH 03/19] docs: refresh README freshness --- readme-standard-v1.json | 170 ++++++++++++++++++++-------------------- 1 file changed, 85 insertions(+), 85 deletions(-) diff --git a/readme-standard-v1.json b/readme-standard-v1.json index 8ce2b6e2..240948d1 100644 --- a/readme-standard-v1.json +++ b/readme-standard-v1.json @@ -208,7 +208,7 @@ "ecosystem.json", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:df79aca16932a0a7196b236c2c34b65fbdc9a2f2b596851517c017da89a89271" + "sourceHash": "sha256:ceb7f02917f8b6ff95a8947d1c5924ed7e1c98b91077d4a7a745a16e24fea8ec" }, "exceptions": [] }, @@ -278,8 +278,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2026-11-17", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2026-12-10", "sources": [ "packages/adapters/README.md", "packages/adapters/package.json", @@ -287,7 +287,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:d210b9657181c5e6cc761fcd6e39dee8b1a8b8b631a3fe711a62f0c3956edc4b" + "sourceHash": "sha256:3e0f5c2fc9211dad117a669571d77b3e517f78bf19568851ee249264836e2bb7" }, "exceptions": [] }, @@ -357,8 +357,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2027-02-08", "sources": [ "packages/angular/README.md", "packages/angular/package.json", @@ -366,7 +366,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:0ef7164ab76c0f18ba1a5b3517a2c6fe53f70b2f27c3c00183bb724441e15599" + "sourceHash": "sha256:f445e0021f391023214c9643d11d852b00d8ae699c374fb34f98b8dacfcf5d27" }, "exceptions": [] }, @@ -436,8 +436,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-28", - "reviewDueOn": "2026-11-25", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2026-12-10", "sources": [ "packages/cli/README.md", "packages/cli/package.json", @@ -445,7 +445,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:42fe7b5e1df07f27683694b8d95a51f99732aefb8dde1aa95d854d687fb9ec7c" + "sourceHash": "sha256:2182ac668e98622ee6170585722d0a96850c66262745d12a126c8a974b561b59" }, "exceptions": [] }, @@ -515,8 +515,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2026-11-17", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2026-12-10", "sources": [ "packages/core/README.md", "packages/core/package.json", @@ -524,7 +524,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:8de6f0d7621dc1d4ed10fc1ae165a5401e15d89b82544aa4a53d92d5aafe5c91" + "sourceHash": "sha256:ecf32bf19c7546d4112c643b0cb3a6269bd288bf10d9ba58657013f404b1f307" }, "exceptions": [] }, @@ -594,8 +594,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2027-02-08", "sources": [ "packages/eval/README.md", "packages/eval/package.json", @@ -603,7 +603,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:90b8535e0876338044424d0e136ba612a7b4b0e5839fcc37161bfe008d1d7cb8" + "sourceHash": "sha256:58d01d8ae2b516e98c96b4ff626c71d6dbe041cc06ed8b66144e082093ab56a3" }, "exceptions": [] }, @@ -673,8 +673,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2027-02-08", "sources": [ "packages/eval-braintrust/README.md", "packages/eval-braintrust/package.json", @@ -682,7 +682,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:91b800cd7f2cadc121c0b80bc42cf38d92f11e5351e02f0e4cf6032bfb877216" + "sourceHash": "sha256:2e3f2e9fea80dc95286ca4ed990962e9c8b18da6902155b8889e38189a8657bb" }, "exceptions": [] }, @@ -752,8 +752,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2027-02-08", "sources": [ "packages/ink/README.md", "packages/ink/package.json", @@ -761,7 +761,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:aa2fdb8f2a006fcaa4ac358723acf953741d4ae5e1c0f0b3c4b485163fafb50a" + "sourceHash": "sha256:e6d954f6053a69f397155c90ca82fdfe9337d0750eeec284a73126c254d453df" }, "exceptions": [] }, @@ -831,8 +831,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2026-11-17", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2026-12-10", "sources": [ "packages/integrations/README.md", "packages/integrations/package.json", @@ -840,7 +840,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:0eda648d3d5a44761028c7b658325256d5375a8c3d57a487e18fed2eb010c808" + "sourceHash": "sha256:a6a4fdfa8dd64c70115522d4c2b63b5197b9bf5a0d2c418998cd7d747c60b242" }, "exceptions": [] }, @@ -910,8 +910,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2026-11-17", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2026-12-10", "sources": [ "packages/mcp/README.md", "packages/mcp/package.json", @@ -919,7 +919,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:54590fcf40da4c7cd63ef9054a4b84acb9d09330dd0d60b3b2e29118bb8860ba" + "sourceHash": "sha256:fb7a5443d36528d7276ee152673731daa823fb7d79551d3e6c5a85ab516ef3e0" }, "exceptions": [] }, @@ -989,8 +989,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-28", - "reviewDueOn": "2026-11-25", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2026-12-10", "sources": [ "packages/memory/README.md", "packages/memory/package.json", @@ -998,7 +998,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:9a84389349e686a9cfbd7237080017793b9ae078d2d330687efdb76600af3a0a" + "sourceHash": "sha256:ac280726873cb4f0f347591918b7bf0db1c53452db84ae4799e872428f5b6512" }, "exceptions": [] }, @@ -1068,8 +1068,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-28", - "reviewDueOn": "2026-11-25", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2026-12-10", "sources": [ "packages/observability/README.md", "packages/observability/package.json", @@ -1077,7 +1077,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:e510a7f3c13d19112c394047f5ccc1ac7ae983c0d3e77825499bb5ef1ea13e1e" + "sourceHash": "sha256:4332cab74ffc54975a4b3096ca19a802b36915b294912c4d64b45cbf94ef7b4d" }, "exceptions": [] }, @@ -1147,8 +1147,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2027-02-08", "sources": [ "packages/observability-langfuse/README.md", "packages/observability-langfuse/package.json", @@ -1156,7 +1156,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:1e94e42166e72c3f8559275f298cd408a303d9176fab496c5d8d1e8bb4810061" + "sourceHash": "sha256:c6d61cc19b7dfff687de01f97eaa32ff43366b6e919fb70468938cd60fa81b6c" }, "exceptions": [] }, @@ -1226,8 +1226,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2026-11-17", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2026-12-10", "sources": [ "packages/rag/README.md", "packages/rag/package.json", @@ -1235,7 +1235,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:ed3d75fc6f5658fd180e114ca6e16bdef5e02854c2c894a3693f09f7b2bdece8" + "sourceHash": "sha256:02474b9b3d7962acdd002b1111134703800ea6b435a09e4c64e97ae8516f904a" }, "exceptions": [] }, @@ -1305,8 +1305,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-28", - "reviewDueOn": "2026-11-25", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2026-12-10", "sources": [ "packages/react/README.md", "packages/react/package.json", @@ -1314,7 +1314,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:2ff3f560a4906ef294fda390417af24ed6f433d26ee215770c2e6ec1ef793494" + "sourceHash": "sha256:7532732c218d4a9a3e35b4d08a194978a4f37a11e099db6f5d7a51e1809dfc94" }, "exceptions": [] }, @@ -1384,8 +1384,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2027-02-08", "sources": [ "packages/react-native/README.md", "packages/react-native/package.json", @@ -1393,7 +1393,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:5b596e6cbd1bb3749b9bfec4e12cb9b1e0e9d4eeda9d3a1619e2a2da65fa51ed" + "sourceHash": "sha256:9ca050b9974158cb5cf3d64b5f41bac76ca2963267277a9a970beb4916a04836" }, "exceptions": [] }, @@ -1463,8 +1463,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2026-11-17", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2026-12-10", "sources": [ "packages/runtime/README.md", "packages/runtime/package.json", @@ -1472,7 +1472,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:be3638e6e04690b89c2528a053d5c944293ba1e0a4618358b2d1f068cdaba41c" + "sourceHash": "sha256:c92700b6714342d5e3f927e729b190c35b2ac36cc2309c808c3176b8aaa07930" }, "exceptions": [] }, @@ -1542,8 +1542,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-22", - "reviewDueOn": "2027-01-18", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2027-02-08", "sources": [ "packages/sandbox/README.md", "packages/sandbox/package.json", @@ -1551,7 +1551,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:3f6322359bed0ba799b5b9deb90a0287bb4346bd343b1fd90b059e6ddff29dc9" + "sourceHash": "sha256:69bd84da3d8093aa7a25b0b4e8ec3bcfe2c73d76f9188d999b89f69cb2576fe8" }, "exceptions": [] }, @@ -1621,8 +1621,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2026-11-17", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2026-12-10", "sources": [ "packages/skills/README.md", "packages/skills/package.json", @@ -1630,7 +1630,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:fabd0f2bc0a771594028b6c6d99b504691d37c3a258f9eb352c5f52622e278df" + "sourceHash": "sha256:6365951bd4ea4ea7db98f491400d02021ca0afe3dcaae99c3c9239da56e8d497" }, "exceptions": [] }, @@ -1700,8 +1700,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2027-02-08", "sources": [ "packages/solid/README.md", "packages/solid/package.json", @@ -1709,7 +1709,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:92ee2f92676c1874dad5a868279274ba8619cce22436bc4466a261aa66f5e60f" + "sourceHash": "sha256:1443fc9c032cc0ff5832f9f7ab0d7c3c9581ac98e99a36ac9fd34b17d611452e" }, "exceptions": [] }, @@ -1779,8 +1779,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2027-02-08", "sources": [ "packages/statechart/README.md", "packages/statechart/package.json", @@ -1788,7 +1788,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:562d74814a2bb95f11ee67cfff9a29681dae94462018dd8f9b24780df8992b73" + "sourceHash": "sha256:7836f701edb76985ca029595ea2c6812ade398661d6de992b07cd60cdc0044c2" }, "exceptions": [] }, @@ -1858,8 +1858,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2027-02-08", "sources": [ "packages/svelte/README.md", "packages/svelte/package.json", @@ -1867,7 +1867,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:232098e75f48cc94df287903e4bef2aa4822ef541817f1bf63130555ef0f8534" + "sourceHash": "sha256:19a166cdb815cc53171d0ef7e15682fbe9f8b50b32e306b27a0b67712eaf935a" }, "exceptions": [] }, @@ -1937,8 +1937,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2027-02-08", "sources": [ "packages/templates/README.md", "packages/templates/package.json", @@ -1946,7 +1946,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:398a3b9d317731ef92e99e6f68b6e2807e74588f6f8551fd8dd80395649eb802" + "sourceHash": "sha256:112c7b4f895a091f0a0e159c0db5ec98cd9968e64ca433663f0ad2fd640fc81c" }, "exceptions": [] }, @@ -2016,8 +2016,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-28", - "reviewDueOn": "2026-11-25", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2026-12-10", "sources": [ "packages/tools/README.md", "packages/tools/package.json", @@ -2025,7 +2025,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:a5251a9052206dad693d7f6da664e67ab7b406741a1d117172111d29247aea1f" + "sourceHash": "sha256:2f6a0d385f4e5e81bfc7bef94bc8722fdf789d85e30723e4e7a4cd5c2cbc75d3" }, "exceptions": [] }, @@ -2095,8 +2095,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2027-02-08", "sources": [ "packages/validation/README.md", "packages/validation/package.json", @@ -2104,7 +2104,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:76ad3551fb175d0a55ad2433f27e68b430a6c412e5424232beae1f150473db76" + "sourceHash": "sha256:37a81ee5daa0526f67ae4df369e6ef621820a05a6bcd9ed0738466517c23cbe4" }, "exceptions": [] }, @@ -2174,8 +2174,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2027-02-08", "sources": [ "packages/vue/README.md", "packages/vue/package.json", @@ -2183,7 +2183,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:2e6c1ffff6f3f8dcf50a2d6b4c5ebd5505bcc6ff7d936005bc32318fbdad91c4" + "sourceHash": "sha256:309c6a365e121e508d4c5d8b2b9a5f9fdbe4702c9872268e91ddeec9d99afda1" }, "exceptions": [] }, @@ -2244,8 +2244,8 @@ } ], "freshness": { - "reviewedOn": "2026-08-11", - "reviewDueOn": "2026-11-09", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2026-11-10", "sources": [ "apps/docs-next/README.md", "apps/docs-next/package.json", @@ -2253,7 +2253,7 @@ "ecosystem-claims.json", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:b4460dd699f2541c366da2777110d9c4c125aaa8ac2d68fc78a50d12b6b97d2e" + "sourceHash": "sha256:18342bbfb89af21155a3cb99a7b72f2759dd7eac3e0a00b219cbb169d2bd2a10" }, "exceptions": [ { @@ -2329,8 +2329,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-28", - "reviewDueOn": "2026-10-26", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2026-11-10", "sources": [ "apps/landing/README.md", "apps/landing/package.json", @@ -2414,8 +2414,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-28", - "reviewDueOn": "2026-10-26", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2026-11-10", "sources": [ "apps/registry/README.md", "apps/registry/package.json", @@ -2499,8 +2499,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-28", - "reviewDueOn": "2026-10-26", + "reviewedOn": "2026-08-12", + "reviewDueOn": "2026-11-10", "sources": [ "apps/ask-backend/README.md", "apps/ask-backend/package.json", From 598c65547e5abda690f210a7b7de0311dd5e596a Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 20:24:16 -0300 Subject: [PATCH 04/19] docs: refresh documentation quality attestation --- docs/evidence/ecosystem-documentation-quality/agentskit.json | 2 +- .../ecosystem-documentation-quality/doc-bridge/agentskit.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/evidence/ecosystem-documentation-quality/agentskit.json b/docs/evidence/ecosystem-documentation-quality/agentskit.json index c5613f65..d60c8f39 100644 --- a/docs/evidence/ecosystem-documentation-quality/agentskit.json +++ b/docs/evidence/ecosystem-documentation-quality/agentskit.json @@ -4,7 +4,7 @@ "profileVersion": 1, "productId": "agentskit", "repo": "AgentsKit-io/agentskit", - "commit": "12ab72e14db59c860c19ccfa2693b0998f776cf4", + "commit": "39a5951cf7634ec9f6703e4c91ef2e3476bd35f2", "auditedOn": "2026-08-12", "docBridge": { "artifact": "docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json", diff --git a/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json b/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json index 91d36926..17365b9d 100644 --- a/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json +++ b/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json @@ -1 +1 @@ -{"schemaVersion":1,"protocol":"agentskit.doc-bridge.attestation","productId":"agentskit","repo":"AgentsKit-io/agentskit","commit":"12ab72e14db59c860c19ccfa2693b0998f776cf4","sourceMode":"commit","contentDigest":"sha256:ee18a9880e9e8020e3cb754678396b7854228323963176e28b4d2e3811481b1b","command":"pnpm docs:bridge:doctor && pnpm docs:bridge:gate","metrics":{"doctorScore":100,"coverage":{"agent":{"ready":25,"total":25},"human":{"ready":25,"total":25}},"conformance":{"requiredPassed":7,"requiredTotal":7,"requiredExcepted":0,"recommendedPassed":2,"recommendedTotal":2,"recommendedExcepted":0}}} +{"schemaVersion":1,"protocol":"agentskit.doc-bridge.attestation","productId":"agentskit","repo":"AgentsKit-io/agentskit","commit":"39a5951cf7634ec9f6703e4c91ef2e3476bd35f2","sourceMode":"commit","contentDigest":"sha256:ee18a9880e9e8020e3cb754678396b7854228323963176e28b4d2e3811481b1b","command":"pnpm docs:bridge:doctor && pnpm docs:bridge:gate","metrics":{"doctorScore":100,"coverage":{"agent":{"ready":25,"total":25},"human":{"ready":25,"total":25}},"conformance":{"requiredPassed":7,"requiredTotal":7,"requiredExcepted":0,"recommendedPassed":2,"recommendedTotal":2,"recommendedExcepted":0}}} From cedc924307f8d6f0488a1d051020ceb97e76da78 Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 20:27:10 -0300 Subject: [PATCH 05/19] docs: add ecosystem breadcrumb metadata --- apps/docs-next/app/ecosystem/page.tsx | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/apps/docs-next/app/ecosystem/page.tsx b/apps/docs-next/app/ecosystem/page.tsx index 7d044307..5b8cc294 100644 --- a/apps/docs-next/app/ecosystem/page.tsx +++ b/apps/docs-next/app/ecosystem/page.tsx @@ -36,9 +36,22 @@ function accessLabel(accessModel: string): string { const ECOSYSTEM_JSON_LD = { '@context': 'https://schema.org', '@type': 'ItemList', - '@id': 'https://www.agentskit.io/ecosystem#products', + '@id': `${canonicalUrl('/ecosystem')}#products`, + url: canonicalUrl('/ecosystem'), name: 'AgentsKit ecosystem', description: `${ecosystem.positioning.canonicalDescription} ${ecosystem.positioning.commercialBoundary}`, + isPartOf: { + '@type': 'WebSite', + name: 'AgentsKit.js', + url: canonicalUrl('/'), + }, + breadcrumb: { + '@type': 'BreadcrumbList', + itemListElement: [ + { '@type': 'ListItem', position: 1, name: 'Home', url: canonicalUrl('/') }, + { '@type': 'ListItem', position: 2, name: 'Ecosystem', url: canonicalUrl('/ecosystem') }, + ], + }, numberOfItems: ecosystem.products.length, itemListElement: ecosystem.products.map((product, index) => ({ '@type': 'ListItem', From 5d819d1eda158576c7cc8c9a885ebb2ca3076683 Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 20:28:10 -0300 Subject: [PATCH 06/19] docs: refresh documentation quality attestation --- docs/evidence/ecosystem-documentation-quality/agentskit.json | 2 +- .../ecosystem-documentation-quality/doc-bridge/agentskit.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/evidence/ecosystem-documentation-quality/agentskit.json b/docs/evidence/ecosystem-documentation-quality/agentskit.json index d60c8f39..9dfe8388 100644 --- a/docs/evidence/ecosystem-documentation-quality/agentskit.json +++ b/docs/evidence/ecosystem-documentation-quality/agentskit.json @@ -4,7 +4,7 @@ "profileVersion": 1, "productId": "agentskit", "repo": "AgentsKit-io/agentskit", - "commit": "39a5951cf7634ec9f6703e4c91ef2e3476bd35f2", + "commit": "cedc9246f40b64716b2369282533c16b4c1f36d6", "auditedOn": "2026-08-12", "docBridge": { "artifact": "docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json", diff --git a/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json b/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json index 17365b9d..5f47d2e3 100644 --- a/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json +++ b/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json @@ -1 +1 @@ -{"schemaVersion":1,"protocol":"agentskit.doc-bridge.attestation","productId":"agentskit","repo":"AgentsKit-io/agentskit","commit":"39a5951cf7634ec9f6703e4c91ef2e3476bd35f2","sourceMode":"commit","contentDigest":"sha256:ee18a9880e9e8020e3cb754678396b7854228323963176e28b4d2e3811481b1b","command":"pnpm docs:bridge:doctor && pnpm docs:bridge:gate","metrics":{"doctorScore":100,"coverage":{"agent":{"ready":25,"total":25},"human":{"ready":25,"total":25}},"conformance":{"requiredPassed":7,"requiredTotal":7,"requiredExcepted":0,"recommendedPassed":2,"recommendedTotal":2,"recommendedExcepted":0}}} +{"schemaVersion":1,"protocol":"agentskit.doc-bridge.attestation","productId":"agentskit","repo":"AgentsKit-io/agentskit","commit":"cedc9246f40b64716b2369282533c16b4c1f36d6","sourceMode":"commit","contentDigest":"sha256:ee18a9880e9e8020e3cb754678396b7854228323963176e28b4d2e3811481b1b","command":"pnpm docs:bridge:doctor && pnpm docs:bridge:gate","metrics":{"doctorScore":100,"coverage":{"agent":{"ready":25,"total":25},"human":{"ready":25,"total":25}},"conformance":{"requiredPassed":7,"requiredTotal":7,"requiredExcepted":0,"recommendedPassed":2,"recommendedTotal":2,"recommendedExcepted":0}}} From e7a6da612c0635736e0b2f7b0657860949cca618 Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 20:28:43 -0300 Subject: [PATCH 07/19] docs: correct attestation commit identity --- docs/evidence/ecosystem-documentation-quality/agentskit.json | 2 +- .../ecosystem-documentation-quality/doc-bridge/agentskit.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/evidence/ecosystem-documentation-quality/agentskit.json b/docs/evidence/ecosystem-documentation-quality/agentskit.json index 9dfe8388..07ca72c8 100644 --- a/docs/evidence/ecosystem-documentation-quality/agentskit.json +++ b/docs/evidence/ecosystem-documentation-quality/agentskit.json @@ -4,7 +4,7 @@ "profileVersion": 1, "productId": "agentskit", "repo": "AgentsKit-io/agentskit", - "commit": "cedc9246f40b64716b2369282533c16b4c1f36d6", + "commit": "cedc924307f8d6f0488a1d051020ceb97e76da78", "auditedOn": "2026-08-12", "docBridge": { "artifact": "docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json", diff --git a/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json b/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json index 5f47d2e3..5020b2ad 100644 --- a/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json +++ b/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json @@ -1 +1 @@ -{"schemaVersion":1,"protocol":"agentskit.doc-bridge.attestation","productId":"agentskit","repo":"AgentsKit-io/agentskit","commit":"cedc9246f40b64716b2369282533c16b4c1f36d6","sourceMode":"commit","contentDigest":"sha256:ee18a9880e9e8020e3cb754678396b7854228323963176e28b4d2e3811481b1b","command":"pnpm docs:bridge:doctor && pnpm docs:bridge:gate","metrics":{"doctorScore":100,"coverage":{"agent":{"ready":25,"total":25},"human":{"ready":25,"total":25}},"conformance":{"requiredPassed":7,"requiredTotal":7,"requiredExcepted":0,"recommendedPassed":2,"recommendedTotal":2,"recommendedExcepted":0}}} +{"schemaVersion":1,"protocol":"agentskit.doc-bridge.attestation","productId":"agentskit","repo":"AgentsKit-io/agentskit","commit":"cedc924307f8d6f0488a1d051020ceb97e76da78","sourceMode":"commit","contentDigest":"sha256:ee18a9880e9e8020e3cb754678396b7854228323963176e28b4d2e3811481b1b","command":"pnpm docs:bridge:doctor && pnpm docs:bridge:gate","metrics":{"doctorScore":100,"coverage":{"agent":{"ready":25,"total":25},"human":{"ready":25,"total":25}},"conformance":{"requiredPassed":7,"requiredTotal":7,"requiredExcepted":0,"recommendedPassed":2,"recommendedTotal":2,"recommendedExcepted":0}}} From 504c7fd712191937f2f569bdcda689264889e8d6 Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 20:38:47 -0300 Subject: [PATCH 08/19] docs: refresh deterministic knowledge artifact --- apps/docs-next/lib/deterministic-knowledge.generated.json | 4 ++-- apps/docs-next/lib/deterministic-site.generated.json | 4 ++-- ...9eacf29c4d6ca1964ca5488e0157fd1a39b3a1ccdfd1d542cfd4.json} | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) rename apps/docs-next/public/deterministic-knowledge/{ce7d63954d1c58c4c3dbe5b425f6768be3b7eb499df843c8e67ab0eefadda8b5.json => 290b63ff03009eacf29c4d6ca1964ca5488e0157fd1a39b3a1ccdfd1d542cfd4.json} (99%) diff --git a/apps/docs-next/lib/deterministic-knowledge.generated.json b/apps/docs-next/lib/deterministic-knowledge.generated.json index d9e88894..4178b684 100644 --- a/apps/docs-next/lib/deterministic-knowledge.generated.json +++ b/apps/docs-next/lib/deterministic-knowledge.generated.json @@ -3,7 +3,7 @@ "version": 1, "artifactId": "agentskit-docs-v1", "siteId": "agentskit-docs", - "generatedAt": "2026-08-12T14:49:32-03:00", + "generatedAt": "2026-08-12T20:23:17-03:00", "entries": [ { "id": "claim.catalog-models", @@ -2260,5 +2260,5 @@ } } ], - "contentHash": "sha256:ce7d63954d1c58c4c3dbe5b425f6768be3b7eb499df843c8e67ab0eefadda8b5" + "contentHash": "sha256:290b63ff03009eacf29c4d6ca1964ca5488e0157fd1a39b3a1ccdfd1d542cfd4" } diff --git a/apps/docs-next/lib/deterministic-site.generated.json b/apps/docs-next/lib/deterministic-site.generated.json index 75c18d56..cbac0be4 100644 --- a/apps/docs-next/lib/deterministic-site.generated.json +++ b/apps/docs-next/lib/deterministic-site.generated.json @@ -3,8 +3,8 @@ "version": 1, "siteId": "agentskit-docs", "artifact": { - "href": "/deterministic-knowledge/ce7d63954d1c58c4c3dbe5b425f6768be3b7eb499df843c8e67ab0eefadda8b5.json", - "contentHash": "sha256:ce7d63954d1c58c4c3dbe5b425f6768be3b7eb499df843c8e67ab0eefadda8b5" + "href": "/deterministic-knowledge/290b63ff03009eacf29c4d6ca1964ca5488e0157fd1a39b3a1ccdfd1d542cfd4.json", + "contentHash": "sha256:290b63ff03009eacf29c4d6ca1964ca5488e0157fd1a39b3a1ccdfd1d542cfd4" }, "fallback": { "mode": "backend" diff --git a/apps/docs-next/public/deterministic-knowledge/ce7d63954d1c58c4c3dbe5b425f6768be3b7eb499df843c8e67ab0eefadda8b5.json b/apps/docs-next/public/deterministic-knowledge/290b63ff03009eacf29c4d6ca1964ca5488e0157fd1a39b3a1ccdfd1d542cfd4.json similarity index 99% rename from apps/docs-next/public/deterministic-knowledge/ce7d63954d1c58c4c3dbe5b425f6768be3b7eb499df843c8e67ab0eefadda8b5.json rename to apps/docs-next/public/deterministic-knowledge/290b63ff03009eacf29c4d6ca1964ca5488e0157fd1a39b3a1ccdfd1d542cfd4.json index d9e88894..4178b684 100644 --- a/apps/docs-next/public/deterministic-knowledge/ce7d63954d1c58c4c3dbe5b425f6768be3b7eb499df843c8e67ab0eefadda8b5.json +++ b/apps/docs-next/public/deterministic-knowledge/290b63ff03009eacf29c4d6ca1964ca5488e0157fd1a39b3a1ccdfd1d542cfd4.json @@ -3,7 +3,7 @@ "version": 1, "artifactId": "agentskit-docs-v1", "siteId": "agentskit-docs", - "generatedAt": "2026-08-12T14:49:32-03:00", + "generatedAt": "2026-08-12T20:23:17-03:00", "entries": [ { "id": "claim.catalog-models", @@ -2260,5 +2260,5 @@ } } ], - "contentHash": "sha256:ce7d63954d1c58c4c3dbe5b425f6768be3b7eb499df843c8e67ab0eefadda8b5" + "contentHash": "sha256:290b63ff03009eacf29c4d6ca1964ca5488e0157fd1a39b3a1ccdfd1d542cfd4" } From 239c299a141b0d6521e1242b5d103cfb0f5ee3c5 Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 20:46:35 -0300 Subject: [PATCH 09/19] docs: use canonical URL for integration hub links --- apps/docs-next/content/docs/agents/tools/index.mdx | 2 +- apps/docs-next/content/docs/agents/tools/integrations/index.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/docs-next/content/docs/agents/tools/index.mdx b/apps/docs-next/content/docs/agents/tools/index.mdx index c92bc336..a5d34d97 100644 --- a/apps/docs-next/content/docs/agents/tools/index.mdx +++ b/apps/docs-next/content/docs/agents/tools/index.mdx @@ -31,7 +31,7 @@ Browser: `browserAgent` - `createMcpServer` — publish AgentsKit tools to any MCP host. - [Recipe: MCP bridge](/docs/reference/recipes/mcp-bridge). -Browse the [canonical integration catalog](/integrations) for all 50 service descriptors, or read the [integration package contract](/docs/for-agents/integrations) before implementing a connector. Dedicated service guides are linked from the catalog where available. +Browse the [canonical integration catalog](https://www.agentskit.io/integrations) for all 50 service descriptors, or read the [integration package contract](/docs/for-agents/integrations) before implementing a connector. Dedicated service guides are linked from the catalog where available. ## Related diff --git a/apps/docs-next/content/docs/agents/tools/integrations/index.mdx b/apps/docs-next/content/docs/agents/tools/integrations/index.mdx index d322d427..70f6fe2b 100644 --- a/apps/docs-next/content/docs/agents/tools/integrations/index.mdx +++ b/apps/docs-next/content/docs/agents/tools/integrations/index.mdx @@ -5,7 +5,7 @@ description: '50-service catalog for TypeScript AI agents. Dedicated guides, pac The canonical `@agentskit/integrations` package contains **50 service descriptors**. This page covers the detailed guides available in the tools documentation; the [for-agents package guide](/docs/for-agents/integrations) describes -the full descriptor registry and projection contract. The top-level [integrations hub](/integrations) keeps both +the full descriptor registry and projection contract. The top-level [integrations hub](https://www.agentskit.io/integrations) keeps both surfaces discoverable without creating placeholder pages for services that do not yet have a dedicated guide. ## Categories From cb7704aad8f6bc1bf3f3ea4c8b3b01049f0b0536 Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 20:52:57 -0300 Subject: [PATCH 10/19] build: tolerate Vercel source archives in knowledge generator --- .../scripts/gen-deterministic-knowledge.mjs | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/apps/docs-next/scripts/gen-deterministic-knowledge.mjs b/apps/docs-next/scripts/gen-deterministic-knowledge.mjs index dea43a2b..65e579f3 100644 --- a/apps/docs-next/scripts/gen-deterministic-knowledge.mjs +++ b/apps/docs-next/scripts/gen-deterministic-knowledge.mjs @@ -16,11 +16,16 @@ import { const appRoot = join(dirname(fileURLToPath(import.meta.url)), '..') const repoRoot = join(appRoot, '../..') -const generatedAt = process.env.DETERMINISTIC_KNOWLEDGE_GENERATED_AT ?? execFileSync( - 'git', - ['log', '-1', '--format=%cI', '--', '.doc-bridge/index.json', 'ecosystem-claims.json', 'ecosystem.json', 'apps/docs-next/scripts/gen-deterministic-knowledge.mjs'], - { cwd: repoRoot, encoding: 'utf8' }, -).trim() +const gitValue = (args) => { + try { + return execFileSync('git', args, { cwd: repoRoot, encoding: 'utf8' }).trim() + } catch { + return '' + } +} +const generatedAt = (process.env.DETERMINISTIC_KNOWLEDGE_GENERATED_AT + ?? gitValue(['log', '-1', '--format=%cI', '--', '.doc-bridge/index.json', 'ecosystem-claims.json', 'ecosystem.json', 'apps/docs-next/scripts/gen-deterministic-knowledge.mjs'])) + || '1970-01-01T00:00:00.000Z' const budgetBytes = 96 * 1024 const readJson = async path => JSON.parse(await readFile(join(repoRoot, path), 'utf8')) @@ -177,5 +182,5 @@ await Promise.all([ writeFile(join(publicDir, `${contentHash.slice('sha256:'.length)}.json`), serializedArtifact), ]) -const revision = execFileSync('git', ['rev-parse', '--short', 'HEAD'], { cwd: repoRoot, encoding: 'utf8' }).trim() +const revision = process.env.VERCEL_GIT_COMMIT_SHA?.slice(0, 7) || gitValue(['rev-parse', '--short', 'HEAD']) || 'source-archive' console.log(`deterministic knowledge: ${entries.length} entries, ${byteLength}/${budgetBytes} bytes, ${contentHash}, source ${revision}`) From 4fbc4a491b9bcb8598a2a39b97e4771cb0a400a5 Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 21:04:04 -0300 Subject: [PATCH 11/19] docs: clarify integration catalog entry point --- apps/docs-next/content/docs/agents/tools/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/docs-next/content/docs/agents/tools/index.mdx b/apps/docs-next/content/docs/agents/tools/index.mdx index a5d34d97..633605ef 100644 --- a/apps/docs-next/content/docs/agents/tools/index.mdx +++ b/apps/docs-next/content/docs/agents/tools/index.mdx @@ -31,7 +31,7 @@ Browser: `browserAgent` - `createMcpServer` — publish AgentsKit tools to any MCP host. - [Recipe: MCP bridge](/docs/reference/recipes/mcp-bridge). -Browse the [canonical integration catalog](https://www.agentskit.io/integrations) for all 50 service descriptors, or read the [integration package contract](/docs/for-agents/integrations) before implementing a connector. Dedicated service guides are linked from the catalog where available. +Use the [canonical integration catalog](https://www.agentskit.io/integrations) to browse all 50 service descriptors, or read the [integration package contract](/docs/for-agents/integrations) before implementing a connector. Dedicated service guides are linked from the catalog where available. ## Related From 5af5bd6888f9f5c98bea3b0cea820428836a808f Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 21:17:47 -0300 Subject: [PATCH 12/19] docs: refresh bridge and README attestations --- .doc-bridge/capabilities.json | 2 +- .doc-bridge/index.json | 6 +- readme-standard-v1.json | 174 +++++++++++++++++----------------- 3 files changed, 91 insertions(+), 91 deletions(-) diff --git a/.doc-bridge/capabilities.json b/.doc-bridge/capabilities.json index 7545f091..bb396ee3 100644 --- a/.doc-bridge/capabilities.json +++ b/.doc-bridge/capabilities.json @@ -7,7 +7,7 @@ "name": "AgentsKit", "root": "." }, - "contentHash": "38a4b61ecbad8f1dfebda378eb40982e0a3a7415f05cb15030c1a998c2135d8e", + "contentHash": "1f8b5acbeeaeeb2c6beb992d62d7cb7833542d2a82e3693295359245ca304feb", "artifacts": { "index": ".doc-bridge/index.json", "llmsTxt": "llms.txt" diff --git a/.doc-bridge/index.json b/.doc-bridge/index.json index ccfa405c..8bd8cb9c 100644 --- a/.doc-bridge/index.json +++ b/.doc-bridge/index.json @@ -1,8 +1,8 @@ { "schemaVersion": 1, - "contentHash": "38a4b61ecbad8f1dfebda378eb40982e0a3a7415f05cb15030c1a998c2135d8e", + "contentHash": "1f8b5acbeeaeeb2c6beb992d62d7cb7833542d2a82e3693295359245ca304feb", "contentHashAlgo": "sha256-normalized-v1", - "generatedAt": "2026-08-12T23:34:15.267Z", + "generatedAt": "2026-08-13T00:16:05.827Z", "project": { "name": "AgentsKit", "root": "." @@ -110,7 +110,7 @@ "type": "agent-doc", "title": "rag", "path": "apps/docs-next/content/docs/for-agents/rag.mdx", - "body": "Install Primary exports - createRAG({ embed, store, chunkSize, chunkOverlap, topK, threshold }) — ingest(docs) + retrieve(request) + search(query) . - chunkText({ chunkSize, chunkOverlap, split }) — lower-level splitter. - createRerankedRetriever(base, { candidatePool, topK, rerank }) — pluggable reranker (BM25 default). See . - createHybridRetriever(base, { vectorWeight, bm25Weight }) — vector + BM25 hybrid. - bm25Score , bm25Rerank — standalone helpers. - voyageReranker(config) — Voyage AI reranker. - jinaReranker(config) — Jina AI reranker. - RagError / RagErrorCodes — typed error (extends AgentsKitError ) thrown by loaders + rerankers; narrow on error.code ( AK RAG LOAD FAILED , AK RAG PEER MISSING , AK RAG RERANK FAILED ). Document loaders - loadUrl , loadGitHubFile , loadGitHubTree , loadNotionPage , loadConfluencePage , loadGoogleDriveFile , loadPdf (BYO parser). See . - Cloud storage: loadS3 , loadGcs , loadDropbox , loadOneDrive . Failure and cancellation contract - Loader request, response-body, pagination, and total-download failures throw RagError with AK RAG LOAD FAILED . Tree loaders may return partial success only after at least one eligible document loaded. - Loader options accept signal?: AbortSignal ; Voyage and Jina reranker options accept the same additive field. - Notion and OneDrive follow provider pagination and reject repeated or missing continuation cursors instead of returning truncated content. - Scoreless Retriever results keep their order. If any score is present, all scores must be finite and the result is ordered descending; malformed mixed score sets throw. - Hybrid retrieval min-max normalizes candidate scores and normalizes relative weights before blending. Minimal example Related - — vector stores. - — embedders. Source - npm: https://www.npmjs.com/package/@agentskit/rag - repo: https://github.com/AgentsKit-io/agentskit/tree/main/packages/rag" + "body": "Install Primary exports - createRAG({ embed, store, chunkSize, chunkOverlap, topK, threshold }) — ingest(InputDocument[]) + retrieve({ query, messages }) + search(query, { topK?, threshold? }) . InputDocument uses content , not text . Chunk defaults: 512 / 50. - chunkText(text, { chunkSize, chunkOverlap, split? }) — lower-level splitter. split is (text: string) = string[] . - createRerankedRetriever(base, { candidatePool, topK, rerank }) — pluggable reranker (BM25 default). See . - createHybridRetriever(base, { vectorWeight?, bm25Weight?, topK?, candidatePool? }) — vector + BM25 hybrid; defaults to 0.6 / 0.4 , 20 candidates, and 5 results. - bm25Score , bm25Rerank — standalone helpers. - voyageReranker(config) — Voyage AI reranker. - jinaReranker(config) — Jina AI reranker. - RagError / RagErrorCodes — typed error (extends AgentsKitError ) thrown by loaders + rerankers; narrow on error.code ( AK RAG LOAD FAILED , AK RAG PEER MISSING , AK RAG RERANK FAILED ). Document loaders - loadUrl(url) — raw response text as InputDocument.content . loadGitHubFile(owner, repo, path, opts) , loadGitHubTree(owner, repo, { filter?, ... }) , loadNotionPage(pageId, { token }) , loadConfluencePage(pageId, { baseUrl, token?, authorization? }) , loadGoogleDriveFile(fileId, { accessToken }) , loadPdf(url, { parsePdf }) . All return InputDocument[] . See . - Cloud storage: loadS3 , loadGcs , loadDropbox , loadOneDrive . Failure and cancellation contract - Loader request, response-body, pagination, and total-download failures throw RagError with AK RAG LOAD FAILED . Tree loaders may return partial success only after at least one eligible document loaded. - Loader options accept signal?: AbortSignal ; Voyage and Jina reranker options accept the same additive field. - Notion and OneDrive follow provider pagination and reject repeated or missing continuation cursors instead of returning truncated content. - Scoreless Retriever results keep their order. If any score is present, all scores must be finite and the result is ordered descending; malformed mixed score sets throw. - Hybrid retrieval min-max normalizes candidate scores and normalizes relative weights before blending. Minimal example Related - — vector stores. - — embedders. Source - npm: https://www.npmjs.com/package/@agentskit/rag - repo: https://github.com/AgentsKit-io/agentskit/tree/main/packages/rag" }, { "id": "react-native", diff --git a/readme-standard-v1.json b/readme-standard-v1.json index aad36d84..342f08eb 100644 --- a/readme-standard-v1.json +++ b/readme-standard-v1.json @@ -198,8 +198,8 @@ } ], "freshness": { - "reviewedOn": "2026-08-12", - "reviewDueOn": "2026-11-10", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2026-11-11", "sources": [ "README.md", "apps/docs-next/fixtures/first-agent/agent.ts", @@ -208,7 +208,7 @@ "ecosystem.json", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:df79aca16932a0a7196b236c2c34b65fbdc9a2f2b596851517c017da89a89271" + "sourceHash": "sha256:ceb7f02917f8b6ff95a8947d1c5924ed7e1c98b91077d4a7a745a16e24fea8ec" }, "exceptions": [] }, @@ -278,8 +278,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2026-11-17", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2026-12-11", "sources": [ "packages/adapters/README.md", "packages/adapters/package.json", @@ -287,7 +287,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:d210b9657181c5e6cc761fcd6e39dee8b1a8b8b631a3fe711a62f0c3956edc4b" + "sourceHash": "sha256:3e0f5c2fc9211dad117a669571d77b3e517f78bf19568851ee249264836e2bb7" }, "exceptions": [] }, @@ -357,8 +357,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2027-02-09", "sources": [ "packages/angular/README.md", "packages/angular/package.json", @@ -366,7 +366,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:0ef7164ab76c0f18ba1a5b3517a2c6fe53f70b2f27c3c00183bb724441e15599" + "sourceHash": "sha256:f445e0021f391023214c9643d11d852b00d8ae699c374fb34f98b8dacfcf5d27" }, "exceptions": [] }, @@ -436,8 +436,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-28", - "reviewDueOn": "2026-11-25", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2026-12-11", "sources": [ "packages/cli/README.md", "packages/cli/package.json", @@ -445,7 +445,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:42fe7b5e1df07f27683694b8d95a51f99732aefb8dde1aa95d854d687fb9ec7c" + "sourceHash": "sha256:2182ac668e98622ee6170585722d0a96850c66262745d12a126c8a974b561b59" }, "exceptions": [] }, @@ -515,8 +515,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2026-11-17", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2026-12-11", "sources": [ "packages/core/README.md", "packages/core/package.json", @@ -524,7 +524,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:8de6f0d7621dc1d4ed10fc1ae165a5401e15d89b82544aa4a53d92d5aafe5c91" + "sourceHash": "sha256:ecf32bf19c7546d4112c643b0cb3a6269bd288bf10d9ba58657013f404b1f307" }, "exceptions": [] }, @@ -594,8 +594,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2027-02-09", "sources": [ "packages/eval/README.md", "packages/eval/package.json", @@ -603,7 +603,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:90b8535e0876338044424d0e136ba612a7b4b0e5839fcc37161bfe008d1d7cb8" + "sourceHash": "sha256:58d01d8ae2b516e98c96b4ff626c71d6dbe041cc06ed8b66144e082093ab56a3" }, "exceptions": [] }, @@ -673,8 +673,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2027-02-09", "sources": [ "packages/eval-braintrust/README.md", "packages/eval-braintrust/package.json", @@ -682,7 +682,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:91b800cd7f2cadc121c0b80bc42cf38d92f11e5351e02f0e4cf6032bfb877216" + "sourceHash": "sha256:2e3f2e9fea80dc95286ca4ed990962e9c8b18da6902155b8889e38189a8657bb" }, "exceptions": [] }, @@ -752,8 +752,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2027-02-09", "sources": [ "packages/ink/README.md", "packages/ink/package.json", @@ -761,7 +761,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:aa2fdb8f2a006fcaa4ac358723acf953741d4ae5e1c0f0b3c4b485163fafb50a" + "sourceHash": "sha256:e6d954f6053a69f397155c90ca82fdfe9337d0750eeec284a73126c254d453df" }, "exceptions": [] }, @@ -831,8 +831,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2026-11-17", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2026-12-11", "sources": [ "packages/integrations/README.md", "packages/integrations/package.json", @@ -840,7 +840,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:0eda648d3d5a44761028c7b658325256d5375a8c3d57a487e18fed2eb010c808" + "sourceHash": "sha256:a6a4fdfa8dd64c70115522d4c2b63b5197b9bf5a0d2c418998cd7d747c60b242" }, "exceptions": [] }, @@ -910,8 +910,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2026-11-17", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2026-12-11", "sources": [ "packages/mcp/README.md", "packages/mcp/package.json", @@ -919,7 +919,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:60dd3eaef1138dfd77da94d75435ee93c562ae9203bea014d733805a94f64a00" + "sourceHash": "sha256:5e4df85a3e1096bb4ff6ddcae5f8b97b16340549b47be674582f7e9952a6afa3" }, "exceptions": [] }, @@ -989,8 +989,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-28", - "reviewDueOn": "2026-11-25", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2026-12-11", "sources": [ "packages/memory/README.md", "packages/memory/package.json", @@ -998,7 +998,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:9a84389349e686a9cfbd7237080017793b9ae078d2d330687efdb76600af3a0a" + "sourceHash": "sha256:ac280726873cb4f0f347591918b7bf0db1c53452db84ae4799e872428f5b6512" }, "exceptions": [] }, @@ -1068,8 +1068,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-28", - "reviewDueOn": "2026-11-25", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2026-12-11", "sources": [ "packages/observability/README.md", "packages/observability/package.json", @@ -1077,7 +1077,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:e510a7f3c13d19112c394047f5ccc1ac7ae983c0d3e77825499bb5ef1ea13e1e" + "sourceHash": "sha256:4332cab74ffc54975a4b3096ca19a802b36915b294912c4d64b45cbf94ef7b4d" }, "exceptions": [] }, @@ -1147,8 +1147,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2027-02-09", "sources": [ "packages/observability-langfuse/README.md", "packages/observability-langfuse/package.json", @@ -1156,7 +1156,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:1e94e42166e72c3f8559275f298cd408a303d9176fab496c5d8d1e8bb4810061" + "sourceHash": "sha256:c6d61cc19b7dfff687de01f97eaa32ff43366b6e919fb70468938cd60fa81b6c" }, "exceptions": [] }, @@ -1226,8 +1226,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2026-11-17", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2026-12-11", "sources": [ "packages/rag/README.md", "packages/rag/package.json", @@ -1235,7 +1235,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:ed3d75fc6f5658fd180e114ca6e16bdef5e02854c2c894a3693f09f7b2bdece8" + "sourceHash": "sha256:02474b9b3d7962acdd002b1111134703800ea6b435a09e4c64e97ae8516f904a" }, "exceptions": [] }, @@ -1305,8 +1305,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-28", - "reviewDueOn": "2026-11-25", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2026-12-11", "sources": [ "packages/react/README.md", "packages/react/package.json", @@ -1314,7 +1314,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:2ff3f560a4906ef294fda390417af24ed6f433d26ee215770c2e6ec1ef793494" + "sourceHash": "sha256:7532732c218d4a9a3e35b4d08a194978a4f37a11e099db6f5d7a51e1809dfc94" }, "exceptions": [] }, @@ -1384,8 +1384,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2027-02-09", "sources": [ "packages/react-native/README.md", "packages/react-native/package.json", @@ -1393,7 +1393,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:5b596e6cbd1bb3749b9bfec4e12cb9b1e0e9d4eeda9d3a1619e2a2da65fa51ed" + "sourceHash": "sha256:9ca050b9974158cb5cf3d64b5f41bac76ca2963267277a9a970beb4916a04836" }, "exceptions": [] }, @@ -1463,8 +1463,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2026-11-17", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2026-12-11", "sources": [ "packages/runtime/README.md", "packages/runtime/package.json", @@ -1472,7 +1472,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:be3638e6e04690b89c2528a053d5c944293ba1e0a4618358b2d1f068cdaba41c" + "sourceHash": "sha256:c92700b6714342d5e3f927e729b190c35b2ac36cc2309c808c3176b8aaa07930" }, "exceptions": [] }, @@ -1542,8 +1542,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-22", - "reviewDueOn": "2027-01-18", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2027-02-09", "sources": [ "packages/sandbox/README.md", "packages/sandbox/package.json", @@ -1551,7 +1551,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:3f6322359bed0ba799b5b9deb90a0287bb4346bd343b1fd90b059e6ddff29dc9" + "sourceHash": "sha256:69bd84da3d8093aa7a25b0b4e8ec3bcfe2c73d76f9188d999b89f69cb2576fe8" }, "exceptions": [] }, @@ -1621,8 +1621,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2026-11-17", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2026-12-11", "sources": [ "packages/skills/README.md", "packages/skills/package.json", @@ -1630,7 +1630,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:fabd0f2bc0a771594028b6c6d99b504691d37c3a258f9eb352c5f52622e278df" + "sourceHash": "sha256:6365951bd4ea4ea7db98f491400d02021ca0afe3dcaae99c3c9239da56e8d497" }, "exceptions": [] }, @@ -1700,8 +1700,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2027-02-09", "sources": [ "packages/solid/README.md", "packages/solid/package.json", @@ -1709,7 +1709,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:92ee2f92676c1874dad5a868279274ba8619cce22436bc4466a261aa66f5e60f" + "sourceHash": "sha256:1443fc9c032cc0ff5832f9f7ab0d7c3c9581ac98e99a36ac9fd34b17d611452e" }, "exceptions": [] }, @@ -1779,8 +1779,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2027-02-09", "sources": [ "packages/statechart/README.md", "packages/statechart/package.json", @@ -1788,7 +1788,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:562d74814a2bb95f11ee67cfff9a29681dae94462018dd8f9b24780df8992b73" + "sourceHash": "sha256:7836f701edb76985ca029595ea2c6812ade398661d6de992b07cd60cdc0044c2" }, "exceptions": [] }, @@ -1858,8 +1858,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2027-02-09", "sources": [ "packages/svelte/README.md", "packages/svelte/package.json", @@ -1867,7 +1867,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:232098e75f48cc94df287903e4bef2aa4822ef541817f1bf63130555ef0f8534" + "sourceHash": "sha256:19a166cdb815cc53171d0ef7e15682fbe9f8b50b32e306b27a0b67712eaf935a" }, "exceptions": [] }, @@ -1937,8 +1937,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2027-02-09", "sources": [ "packages/templates/README.md", "packages/templates/package.json", @@ -1946,7 +1946,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:398a3b9d317731ef92e99e6f68b6e2807e74588f6f8551fd8dd80395649eb802" + "sourceHash": "sha256:112c7b4f895a091f0a0e159c0db5ec98cd9968e64ca433663f0ad2fd640fc81c" }, "exceptions": [] }, @@ -2016,8 +2016,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-28", - "reviewDueOn": "2026-11-25", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2026-12-11", "sources": [ "packages/tools/README.md", "packages/tools/package.json", @@ -2025,7 +2025,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:a5251a9052206dad693d7f6da664e67ab7b406741a1d117172111d29247aea1f" + "sourceHash": "sha256:2f6a0d385f4e5e81bfc7bef94bc8722fdf789d85e30723e4e7a4cd5c2cbc75d3" }, "exceptions": [] }, @@ -2095,8 +2095,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2027-02-09", "sources": [ "packages/validation/README.md", "packages/validation/package.json", @@ -2104,7 +2104,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:76ad3551fb175d0a55ad2433f27e68b430a6c412e5424232beae1f150473db76" + "sourceHash": "sha256:37a81ee5daa0526f67ae4df369e6ef621820a05a6bcd9ed0738466517c23cbe4" }, "exceptions": [] }, @@ -2174,8 +2174,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-20", - "reviewDueOn": "2027-01-16", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2027-02-09", "sources": [ "packages/vue/README.md", "packages/vue/package.json", @@ -2183,7 +2183,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:2e6c1ffff6f3f8dcf50a2d6b4c5ebd5505bcc6ff7d936005bc32318fbdad91c4" + "sourceHash": "sha256:309c6a365e121e508d4c5d8b2b9a5f9fdbe4702c9872268e91ddeec9d99afda1" }, "exceptions": [] }, @@ -2244,8 +2244,8 @@ } ], "freshness": { - "reviewedOn": "2026-08-11", - "reviewDueOn": "2026-11-09", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2026-11-11", "sources": [ "apps/docs-next/README.md", "apps/docs-next/package.json", @@ -2253,7 +2253,7 @@ "ecosystem-claims.json", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:b4460dd699f2541c366da2777110d9c4c125aaa8ac2d68fc78a50d12b6b97d2e" + "sourceHash": "sha256:18342bbfb89af21155a3cb99a7b72f2759dd7eac3e0a00b219cbb169d2bd2a10" }, "exceptions": [ { @@ -2329,8 +2329,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-28", - "reviewDueOn": "2026-10-26", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2026-11-11", "sources": [ "apps/landing/README.md", "apps/landing/package.json", @@ -2414,8 +2414,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-28", - "reviewDueOn": "2026-10-26", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2026-11-11", "sources": [ "apps/registry/README.md", "apps/registry/package.json", @@ -2499,8 +2499,8 @@ } ], "freshness": { - "reviewedOn": "2026-07-28", - "reviewDueOn": "2026-10-26", + "reviewedOn": "2026-08-13", + "reviewDueOn": "2026-11-11", "sources": [ "apps/ask-backend/README.md", "apps/ask-backend/package.json", From 9fe50b9ddf50e5d3dc9d72ab91a00a8f28750b62 Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 21:21:38 -0300 Subject: [PATCH 13/19] docs: refresh deterministic knowledge artifact --- apps/docs-next/lib/deterministic-knowledge.generated.json | 4 ++-- apps/docs-next/lib/deterministic-site.generated.json | 4 ++-- ...9b8bfebdbd57eaee711acd081e1b93f0e5c28d8cad5593640353.json} | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) rename apps/docs-next/public/deterministic-knowledge/{290b63ff03009eacf29c4d6ca1964ca5488e0157fd1a39b3a1ccdfd1d542cfd4.json => 12949c8c35359b8bfebdbd57eaee711acd081e1b93f0e5c28d8cad5593640353.json} (99%) diff --git a/apps/docs-next/lib/deterministic-knowledge.generated.json b/apps/docs-next/lib/deterministic-knowledge.generated.json index 4178b684..05f86e30 100644 --- a/apps/docs-next/lib/deterministic-knowledge.generated.json +++ b/apps/docs-next/lib/deterministic-knowledge.generated.json @@ -3,7 +3,7 @@ "version": 1, "artifactId": "agentskit-docs-v1", "siteId": "agentskit-docs", - "generatedAt": "2026-08-12T20:23:17-03:00", + "generatedAt": "2026-08-12T21:17:47-03:00", "entries": [ { "id": "claim.catalog-models", @@ -2260,5 +2260,5 @@ } } ], - "contentHash": "sha256:290b63ff03009eacf29c4d6ca1964ca5488e0157fd1a39b3a1ccdfd1d542cfd4" + "contentHash": "sha256:12949c8c35359b8bfebdbd57eaee711acd081e1b93f0e5c28d8cad5593640353" } diff --git a/apps/docs-next/lib/deterministic-site.generated.json b/apps/docs-next/lib/deterministic-site.generated.json index cbac0be4..09282b76 100644 --- a/apps/docs-next/lib/deterministic-site.generated.json +++ b/apps/docs-next/lib/deterministic-site.generated.json @@ -3,8 +3,8 @@ "version": 1, "siteId": "agentskit-docs", "artifact": { - "href": "/deterministic-knowledge/290b63ff03009eacf29c4d6ca1964ca5488e0157fd1a39b3a1ccdfd1d542cfd4.json", - "contentHash": "sha256:290b63ff03009eacf29c4d6ca1964ca5488e0157fd1a39b3a1ccdfd1d542cfd4" + "href": "/deterministic-knowledge/12949c8c35359b8bfebdbd57eaee711acd081e1b93f0e5c28d8cad5593640353.json", + "contentHash": "sha256:12949c8c35359b8bfebdbd57eaee711acd081e1b93f0e5c28d8cad5593640353" }, "fallback": { "mode": "backend" diff --git a/apps/docs-next/public/deterministic-knowledge/290b63ff03009eacf29c4d6ca1964ca5488e0157fd1a39b3a1ccdfd1d542cfd4.json b/apps/docs-next/public/deterministic-knowledge/12949c8c35359b8bfebdbd57eaee711acd081e1b93f0e5c28d8cad5593640353.json similarity index 99% rename from apps/docs-next/public/deterministic-knowledge/290b63ff03009eacf29c4d6ca1964ca5488e0157fd1a39b3a1ccdfd1d542cfd4.json rename to apps/docs-next/public/deterministic-knowledge/12949c8c35359b8bfebdbd57eaee711acd081e1b93f0e5c28d8cad5593640353.json index 4178b684..05f86e30 100644 --- a/apps/docs-next/public/deterministic-knowledge/290b63ff03009eacf29c4d6ca1964ca5488e0157fd1a39b3a1ccdfd1d542cfd4.json +++ b/apps/docs-next/public/deterministic-knowledge/12949c8c35359b8bfebdbd57eaee711acd081e1b93f0e5c28d8cad5593640353.json @@ -3,7 +3,7 @@ "version": 1, "artifactId": "agentskit-docs-v1", "siteId": "agentskit-docs", - "generatedAt": "2026-08-12T20:23:17-03:00", + "generatedAt": "2026-08-12T21:17:47-03:00", "entries": [ { "id": "claim.catalog-models", @@ -2260,5 +2260,5 @@ } } ], - "contentHash": "sha256:290b63ff03009eacf29c4d6ca1964ca5488e0157fd1a39b3a1ccdfd1d542cfd4" + "contentHash": "sha256:12949c8c35359b8bfebdbd57eaee711acd081e1b93f0e5c28d8cad5593640353" } From 5fabd28cd8210495f09f24437a425f2ac726b809 Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 21:28:20 -0300 Subject: [PATCH 14/19] test: anchor documentation route assertions --- apps/docs-next/tests/documentation-contracts.test.ts | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/apps/docs-next/tests/documentation-contracts.test.ts b/apps/docs-next/tests/documentation-contracts.test.ts index 415363c6..f9ac576d 100644 --- a/apps/docs-next/tests/documentation-contracts.test.ts +++ b/apps/docs-next/tests/documentation-contracts.test.ts @@ -43,8 +43,13 @@ describe('documentation and package contract surfaces', () => { for (const packageDir of packageDirs) { const readme = read(`packages/${packageDir}/README.md`) const manifest = JSON.parse(read(`packages/${packageDir}/package.json`)) as { homepage?: string } - expect(readme).not.toMatch(/https:\/\/www\.agentskit\.io\/docs\/(packages|recipes|tools|adapters|memory|configuration)\b/) - expect(manifest.homepage).not.toMatch(/https:\/\/www\.agentskit\.io\/docs\/packages\//) + expect(readme.includes('https://www.agentskit.io/docs/packages/')).toBe(false) + expect(readme.includes('https://www.agentskit.io/docs/recipes/')).toBe(false) + expect(readme.includes('https://www.agentskit.io/docs/tools/')).toBe(false) + expect(readme.includes('https://www.agentskit.io/docs/adapters/')).toBe(false) + expect(readme.includes('https://www.agentskit.io/docs/memory/')).toBe(false) + expect(readme.includes('https://www.agentskit.io/docs/configuration/')).toBe(false) + expect(manifest.homepage?.includes('https://www.agentskit.io/docs/packages/')).toBe(false) } expect(read('packages/mcp/README.md')).toContain('/docs/agents/tools/mcp') From 661939618005c763ad47c0390241139c07b13a21 Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 21:46:27 -0300 Subject: [PATCH 15/19] test: align mcp README attestation --- readme-standard-v1.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/readme-standard-v1.json b/readme-standard-v1.json index 818c5563..a13fa2fb 100644 --- a/readme-standard-v1.json +++ b/readme-standard-v1.json @@ -896,7 +896,7 @@ "commands": [ { "id": "install", - "command": "npx -y @agentskit/mcp@0.3.4 --tools fetch,search", + "command": "npx -y @agentskit/mcp@0.3.5 --tools fetch,search", "test": "packages/mcp/tests/server.test.ts", "testCommand": "pnpm --filter @agentskit/mcp test" } From 54a5e7c9e179729e2c5f968d9a81131ae293cf1d Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 21:53:05 -0300 Subject: [PATCH 16/19] docs: refresh post-merge knowledge snapshot --- apps/docs-next/lib/deterministic-knowledge.generated.json | 4 ++-- apps/docs-next/lib/deterministic-site.generated.json | 4 ++-- ...f912c81fce84e5c5f54b2bfb66193352efba70c06d25e6171a63.json} | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) rename apps/docs-next/public/deterministic-knowledge/{12949c8c35359b8bfebdbd57eaee711acd081e1b93f0e5c28d8cad5593640353.json => a8976e98efc0f912c81fce84e5c5f54b2bfb66193352efba70c06d25e6171a63.json} (99%) diff --git a/apps/docs-next/lib/deterministic-knowledge.generated.json b/apps/docs-next/lib/deterministic-knowledge.generated.json index 05f86e30..d866a0a5 100644 --- a/apps/docs-next/lib/deterministic-knowledge.generated.json +++ b/apps/docs-next/lib/deterministic-knowledge.generated.json @@ -3,7 +3,7 @@ "version": 1, "artifactId": "agentskit-docs-v1", "siteId": "agentskit-docs", - "generatedAt": "2026-08-12T21:17:47-03:00", + "generatedAt": "2026-08-12T21:41:58-03:00", "entries": [ { "id": "claim.catalog-models", @@ -2260,5 +2260,5 @@ } } ], - "contentHash": "sha256:12949c8c35359b8bfebdbd57eaee711acd081e1b93f0e5c28d8cad5593640353" + "contentHash": "sha256:a8976e98efc0f912c81fce84e5c5f54b2bfb66193352efba70c06d25e6171a63" } diff --git a/apps/docs-next/lib/deterministic-site.generated.json b/apps/docs-next/lib/deterministic-site.generated.json index 09282b76..12781307 100644 --- a/apps/docs-next/lib/deterministic-site.generated.json +++ b/apps/docs-next/lib/deterministic-site.generated.json @@ -3,8 +3,8 @@ "version": 1, "siteId": "agentskit-docs", "artifact": { - "href": "/deterministic-knowledge/12949c8c35359b8bfebdbd57eaee711acd081e1b93f0e5c28d8cad5593640353.json", - "contentHash": "sha256:12949c8c35359b8bfebdbd57eaee711acd081e1b93f0e5c28d8cad5593640353" + "href": "/deterministic-knowledge/a8976e98efc0f912c81fce84e5c5f54b2bfb66193352efba70c06d25e6171a63.json", + "contentHash": "sha256:a8976e98efc0f912c81fce84e5c5f54b2bfb66193352efba70c06d25e6171a63" }, "fallback": { "mode": "backend" diff --git a/apps/docs-next/public/deterministic-knowledge/12949c8c35359b8bfebdbd57eaee711acd081e1b93f0e5c28d8cad5593640353.json b/apps/docs-next/public/deterministic-knowledge/a8976e98efc0f912c81fce84e5c5f54b2bfb66193352efba70c06d25e6171a63.json similarity index 99% rename from apps/docs-next/public/deterministic-knowledge/12949c8c35359b8bfebdbd57eaee711acd081e1b93f0e5c28d8cad5593640353.json rename to apps/docs-next/public/deterministic-knowledge/a8976e98efc0f912c81fce84e5c5f54b2bfb66193352efba70c06d25e6171a63.json index 05f86e30..d866a0a5 100644 --- a/apps/docs-next/public/deterministic-knowledge/12949c8c35359b8bfebdbd57eaee711acd081e1b93f0e5c28d8cad5593640353.json +++ b/apps/docs-next/public/deterministic-knowledge/a8976e98efc0f912c81fce84e5c5f54b2bfb66193352efba70c06d25e6171a63.json @@ -3,7 +3,7 @@ "version": 1, "artifactId": "agentskit-docs-v1", "siteId": "agentskit-docs", - "generatedAt": "2026-08-12T21:17:47-03:00", + "generatedAt": "2026-08-12T21:41:58-03:00", "entries": [ { "id": "claim.catalog-models", @@ -2260,5 +2260,5 @@ } } ], - "contentHash": "sha256:12949c8c35359b8bfebdbd57eaee711acd081e1b93f0e5c28d8cad5593640353" + "contentHash": "sha256:a8976e98efc0f912c81fce84e5c5f54b2bfb66193352efba70c06d25e6171a63" } From b0db765251610bdbba06b26b91f1a3da3124bb9f Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 22:04:08 -0300 Subject: [PATCH 17/19] test: parse legacy documentation URLs safely --- .../tests/documentation-contracts.test.ts | 30 ++++++++++++++----- 1 file changed, 23 insertions(+), 7 deletions(-) diff --git a/apps/docs-next/tests/documentation-contracts.test.ts b/apps/docs-next/tests/documentation-contracts.test.ts index f9ac576d..8524ebaf 100644 --- a/apps/docs-next/tests/documentation-contracts.test.ts +++ b/apps/docs-next/tests/documentation-contracts.test.ts @@ -9,6 +9,27 @@ function read(relativePath: string): string { return readFileSync(resolve(repoRoot, relativePath), 'utf8') } +const legacyGuidePaths = new Set([ + '/docs/packages/', + '/docs/recipes/', + '/docs/tools/', + '/docs/adapters/', + '/docs/memory/', + '/docs/configuration/', +]) + +function hasLegacyGuideUrl(value: string): boolean { + const candidates = value.match(/https?:\/\/[^\s<>)"']+/g) ?? [] + return candidates.some((candidate) => { + try { + const url = new URL(candidate) + return url.host === 'www.agentskit.io' && [...legacyGuidePaths].some((path) => url.pathname.startsWith(path)) + } catch { + return false + } + }) +} + describe('documentation and package contract surfaces', () => { it('keeps built-in error docs links canonical and documented', () => { const source = read('packages/core/src/errors.ts') @@ -43,13 +64,8 @@ describe('documentation and package contract surfaces', () => { for (const packageDir of packageDirs) { const readme = read(`packages/${packageDir}/README.md`) const manifest = JSON.parse(read(`packages/${packageDir}/package.json`)) as { homepage?: string } - expect(readme.includes('https://www.agentskit.io/docs/packages/')).toBe(false) - expect(readme.includes('https://www.agentskit.io/docs/recipes/')).toBe(false) - expect(readme.includes('https://www.agentskit.io/docs/tools/')).toBe(false) - expect(readme.includes('https://www.agentskit.io/docs/adapters/')).toBe(false) - expect(readme.includes('https://www.agentskit.io/docs/memory/')).toBe(false) - expect(readme.includes('https://www.agentskit.io/docs/configuration/')).toBe(false) - expect(manifest.homepage?.includes('https://www.agentskit.io/docs/packages/')).toBe(false) + expect(hasLegacyGuideUrl(readme)).toBe(false) + expect(hasLegacyGuideUrl(manifest.homepage ?? '')).toBe(false) } expect(read('packages/mcp/README.md')).toContain('/docs/agents/tools/mcp') From f7affa991c1720fa4eaba382d51628174516defd Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 23:18:03 -0300 Subject: [PATCH 18/19] docs: align usage contracts and deterministic artifacts --- .changeset/tidy-vectra-peer.md | 5 ++ .doc-bridge/capabilities.json | 2 +- .doc-bridge/index.json | 8 +-- README.md | 2 +- .../content/docs/agents/skills/summarizer.mdx | 26 ++++++--- .../docs/data/memory/auto-summarize.mdx | 25 ++++++--- .../docs/data/providers/deepseek-embedder.mdx | 8 +++ .../content/docs/data/providers/embedders.mdx | 1 + .../docs/data/providers/huggingface.mdx | 2 +- .../docs/data/providers/kimi-embedder.mdx | 8 +++ .../content/docs/data/providers/kimi.mdx | 2 +- .../docs/data/rag/context-injection.mdx | 4 +- .../content/docs/data/rag/rerank.mdx | 2 +- .../content/docs/for-agents/memory.mdx | 2 +- .../docs/get-started/concepts/memory.mdx | 2 +- .../get-started/migrating/from-langchain.mdx | 2 +- .../get-started/migrating/from-llamaindex.mdx | 4 +- .../get-started/migrating/from-mastra.mdx | 4 +- .../migrating/from-openai-assistants.mdx | 2 +- .../migrating/from-vercel-ai-sdk.mdx | 2 +- .../docs/reference/recipes/auto-summarize.mdx | 10 ++-- .../docs/reference/recipes/doc-loaders.mdx | 2 +- .../reference/recipes/hierarchical-memory.mdx | 2 +- .../content/docs/reference/recipes/pdf-qa.mdx | 4 +- .../docs/reference/recipes/rag-chat.mdx | 4 +- .../docs/reference/recipes/rag-reranking.mdx | 4 +- .../deterministic-knowledge.generated.json | 12 ++--- .../lib/deterministic-site.generated.json | 4 +- apps/docs-next/package.json | 4 +- ...0669cce1bff59cc8dc39c8b3e761cf54f7b0.json} | 12 ++--- .../scripts/gen-deterministic-knowledge.mjs | 30 +++++++++-- .../tests/deterministic-docs-answers.test.mjs | 5 +- apps/docs-next/tests/site-icons.test.ts | 3 +- apps/docs-next/vitest.config.ts | 2 +- packages/cli/README.md | 2 +- packages/memory/package.json | 8 +++ pnpm-lock.yaml | 3 ++ readme-standard-v1.json | 54 +++++++++---------- 38 files changed, 184 insertions(+), 94 deletions(-) create mode 100644 .changeset/tidy-vectra-peer.md rename apps/docs-next/public/deterministic-knowledge/{a8976e98efc0f912c81fce84e5c5f54b2bfb66193352efba70c06d25e6171a63.json => 70679069128f2f8f0f8facd3c57f0669cce1bff59cc8dc39c8b3e761cf54f7b0.json} (99%) diff --git a/.changeset/tidy-vectra-peer.md b/.changeset/tidy-vectra-peer.md new file mode 100644 index 00000000..151e3f50 --- /dev/null +++ b/.changeset/tidy-vectra-peer.md @@ -0,0 +1,5 @@ +--- +'@agentskit/memory': patch +--- + +Declare Vectra as an optional peer dependency for the on-disk vector memory backend. diff --git a/.doc-bridge/capabilities.json b/.doc-bridge/capabilities.json index 9344a8a0..3dd27305 100644 --- a/.doc-bridge/capabilities.json +++ b/.doc-bridge/capabilities.json @@ -7,7 +7,7 @@ "name": "AgentsKit", "root": "." }, - "contentHash": "4b8372dc800cc78266ddc77be7184f5451bcfa6a91c36f3ef631f6119733c5e6", + "contentHash": "cfa57ad9da1ec022f65144e749091be3fc89d27a360a3c580ab4f3c0658145b2", "artifacts": { "index": ".doc-bridge/index.json", "llmsTxt": "llms.txt" diff --git a/.doc-bridge/index.json b/.doc-bridge/index.json index 3e94a918..50183382 100644 --- a/.doc-bridge/index.json +++ b/.doc-bridge/index.json @@ -1,8 +1,8 @@ { "schemaVersion": 1, - "contentHash": "4b8372dc800cc78266ddc77be7184f5451bcfa6a91c36f3ef631f6119733c5e6", + "contentHash": "cfa57ad9da1ec022f65144e749091be3fc89d27a360a3c580ab4f3c0658145b2", "contentHashAlgo": "sha256-normalized-v1", - "generatedAt": "2026-08-13T01:23:01.529Z", + "generatedAt": "2026-08-13T02:11:22.456Z", "project": { "name": "AgentsKit", "root": "." @@ -89,7 +89,7 @@ "type": "agent-doc", "title": "memory", "path": "apps/docs-next/content/docs/for-agents/memory.mdx", - "body": "Install Primary exports Chat memory (ordered history) - fileChatMemory({ path }) — JSON file. - sqliteChatMemory — SQLite-backed. - redisChatMemory — Redis-backed. - tursoChatMemory — Turso / libSQL. - createWebStorageMemory from @agentskit/memory/web-storage — injected, SSR-safe localStorage / sessionStorage with runtime validation, byte/message bounds, cancellation, and host-owned legacy migration. Vector memory - fileVectorMemory({ path }) — JSON file. - redisVectorMemory — Redis Vector. - pgvector , pinecone , qdrant , chroma , upstashVector — BYO-client / HTTP vector adapters. See . - supabaseVectorStore , weaviateVectorStore , milvusVectorStore , mongoAtlasVectorStore — managed / cluster backends. - matchesFilter(record, filter) — utility for evaluating vector-store filter predicates outside an adapter. Higher-order memory - createVirtualizedMemory (from @agentskit/core ) — hot window + cold retriever. - createHierarchicalMemory — MemGPT tiers (working / recall / archival). - createAutoSummarizingMemory (from @agentskit/core/auto-summarize ) — fold oldest into a summary. - createEncryptedMemory — AES-GCM over any ChatMemory . See . - createInMemoryGraph — knowledge graph (nodes + edges + BFS). See . - createInMemoryPersonalization + renderProfileContext — per-subject profile. See . - wrapChatMemoryWithRedaction(mem, { rules, mode?, vault?, allowedRoles? }) — redact (or tokenize) PII at save() time on any ChatMemory . Pairs with @agentskit/core/security tokenize / reveal for role-gated read. - wrapVectorMemoryWithRedaction(mem, { rules, mode?, vault?, allowedRoles? }) — same for VectorMemory.store() . Embeddings pass through verbatim; redact the input to your embedder separately if it is a hosted provider. - forgetSubject(memory, subjectId) / makeForgettable(memory) — GDPR-style right-to-erasure helpers that purge all records for a subject across ChatMemory and VectorMemory . Key-value store ( AgentskitMemoryStore ) A generic get(key) / set(key,value) store with TTL + max-key eviction, complementing the conversation ChatMemory model — for agent scratchpad, pipeline state, and arbitrary JSON keyed by string. - createInMemoryStore(config) / createFileStore(config) / createLocalStorageStore({ config, storage? }) — zero-dependency backends. - createSqliteStore({ config, open }) — open is a better-sqlite3-style opener; tryDefaultSqliteOpener() lazy-imports better-sqlite3 . - createRedisStore({ config, client }) — client is a RedisLike ; adaptIoredis(io) bridges ioredis, tryDefaultRedisClient(url) lazy-imports node-redis. - createVectorStore({ config, vectorStore, embedder }) — exact-key get / set plus a recall(query, k) similarity search. - createKvMemoryFromConfig({ config, sqlite?, redis?, vectorStore?, embedder? }) / createKvMemoryFromConfigAuto(config) — dispatch over a KvMemoryConfig ( in-memory / file / sqlite / localstorage / redis / vector ); the auto form lazy-loads optional drivers. MEMORY BACKEND SUPPORT / isMemoryBackendSupported / MemoryBackendNotImplementedError describe coverage. Minimal example Related - — embedders + retrievers on top of vector memory. - — the ChatMemory / VectorMemory contracts. Source - npm: https://www.npmjs.com/package/@agentskit/memory - repo: https://github.com/AgentsKit-io/agentskit/tree/main/packages/memory" + "body": "Install Primary exports Chat memory (ordered history) - fileChatMemory({ path }) — JSON file. - sqliteChatMemory — SQLite-backed. - redisChatMemory — Redis-backed. - tursoChatMemory — Turso / libSQL. - createWebStorageMemory from @agentskit/memory/web-storage — injected, SSR-safe localStorage / sessionStorage with runtime validation, byte/message bounds, cancellation, and host-owned legacy migration. Vector memory - fileVectorMemory({ path }) — Vectra-backed index directory (optional vectra peer). - redisVectorMemory — Redis Vector. - pgvector , pinecone , qdrant , chroma , upstashVector — BYO-client / HTTP vector adapters. See . - supabaseVectorStore , weaviateVectorStore , milvusVectorStore , mongoAtlasVectorStore — managed / cluster backends. - matchesFilter(record, filter) — utility for evaluating vector-store filter predicates outside an adapter. Higher-order memory - createVirtualizedMemory (from @agentskit/core ) — hot window + cold retriever. - createHierarchicalMemory — MemGPT tiers (working / recall / archival). - createAutoSummarizingMemory (from @agentskit/core/auto-summarize ) — fold oldest into a summary. - createEncryptedMemory — AES-GCM over any ChatMemory . See . - createInMemoryGraph — knowledge graph (nodes + edges + BFS). See . - createInMemoryPersonalization + renderProfileContext — per-subject profile. See . - wrapChatMemoryWithRedaction(mem, { rules, mode?, vault?, allowedRoles? }) — redact (or tokenize) PII at save() time on any ChatMemory . Pairs with @agentskit/core/security tokenize / reveal for role-gated read. - wrapVectorMemoryWithRedaction(mem, { rules, mode?, vault?, allowedRoles? }) — same for VectorMemory.store() . Embeddings pass through verbatim; redact the input to your embedder separately if it is a hosted provider. - forgetSubject(memory, subjectId) / makeForgettable(memory) — GDPR-style right-to-erasure helpers that purge all records for a subject across ChatMemory and VectorMemory . Key-value store ( AgentskitMemoryStore ) A generic get(key) / set(key,value) store with TTL + max-key eviction, complementing the conversation ChatMemory model — for agent scratchpad, pipeline state, and arbitrary JSON keyed by string. - createInMemoryStore(config) / createFileStore(config) / createLocalStorageStore({ config, storage? }) — zero-dependency backends. - createSqliteStore({ config, open }) — open is a better-sqlite3-style opener; tryDefaultSqliteOpener() lazy-imports better-sqlite3 . - createRedisStore({ config, client }) — client is a RedisLike ; adaptIoredis(io) bridges ioredis, tryDefaultRedisClient(url) lazy-imports node-redis. - createVectorStore({ config, vectorStore, embedder }) — exact-key get / set plus a recall(query, k) similarity search. - createKvMemoryFromConfig({ config, sqlite?, redis?, vectorStore?, embedder? }) / createKvMemoryFromConfigAuto(config) — dispatch over a KvMemoryConfig ( in-memory / file / sqlite / localstorage / redis / vector ); the auto form lazy-loads optional drivers. MEMORY BACKEND SUPPORT / isMemoryBackendSupported / MemoryBackendNotImplementedError describe coverage. Minimal example Related - — embedders + retrievers on top of vector memory. - — the ChatMemory / VectorMemory contracts. Source - npm: https://www.npmjs.com/package/@agentskit/memory - repo: https://github.com/AgentsKit-io/agentskit/tree/main/packages/memory" }, { "id": "observability-langfuse", @@ -110,7 +110,7 @@ "type": "agent-doc", "title": "rag", "path": "apps/docs-next/content/docs/for-agents/rag.mdx", - "body": "Install Primary exports - createRAG({ embed, store, chunkSize, chunkOverlap, topK, threshold }) — ingest(docs) + retrieve(request) + search(query) . - chunkText({ chunkSize, chunkOverlap, split }) — lower-level splitter. - createRerankedRetriever(base, { candidatePool, topK, rerank }) — pluggable reranker (BM25 default). See . - createHybridRetriever(base, { vectorWeight, bm25Weight }) — vector + BM25 hybrid. - bm25Score , bm25Rerank — standalone helpers. - voyageReranker(config) — Voyage AI reranker. - jinaReranker(config) — Jina AI reranker. - RagError / RagErrorCodes — typed error (extends AgentsKitError ) thrown by loaders + rerankers; narrow on error.code ( AK RAG LOAD FAILED , AK RAG PEER MISSING , AK RAG RERANK FAILED ). Document loaders - loadUrl , loadGitHubFile , loadGitHubTree , loadNotionPage , loadConfluencePage , loadGoogleDriveFile , loadPdf (BYO parser). See . - Cloud storage: loadS3 , loadGcs , loadDropbox , loadOneDrive . Failure and cancellation contract - Loader request, response-body, pagination, and total-download failures throw RagError with AK RAG LOAD FAILED . Tree loaders may return partial success only after at least one eligible document loaded. - Loader options accept signal?: AbortSignal ; Voyage and Jina reranker options accept the same additive field. - Notion and OneDrive follow provider pagination and reject repeated or missing continuation cursors instead of returning truncated content. - Scoreless Retriever results keep their order. If any score is present, all scores must be finite and the result is ordered descending; malformed mixed score sets throw. - Hybrid retrieval min-max normalizes candidate scores and normalizes relative weights before blending. Minimal example Related - — vector stores. - — embedders. Source - npm: https://www.npmjs.com/package/@agentskit/rag - repo: https://github.com/AgentsKit-io/agentskit/tree/main/packages/rag" + "body": "Install Primary exports - createRAG({ embed, store, chunkSize, chunkOverlap, topK, threshold }) — ingest(InputDocument[]) + retrieve({ query, messages }) + search(query, { topK?, threshold? }) . InputDocument uses content , not text . Chunk defaults: 512 / 50. - chunkText(text, { chunkSize, chunkOverlap, split? }) — lower-level splitter. split is (text: string) = string[] . - createRerankedRetriever(base, { candidatePool, topK, rerank }) — pluggable reranker (BM25 default). See . - createHybridRetriever(base, { vectorWeight?, bm25Weight?, topK?, candidatePool? }) — vector + BM25 hybrid; defaults to 0.6 / 0.4 , 20 candidates, and 5 results. - bm25Score , bm25Rerank — standalone helpers. - voyageReranker(config) — Voyage AI reranker. - jinaReranker(config) — Jina AI reranker. - RagError / RagErrorCodes — typed error (extends AgentsKitError ) thrown by loaders + rerankers; narrow on error.code ( AK RAG LOAD FAILED , AK RAG PEER MISSING , AK RAG RERANK FAILED ). Document loaders - loadUrl(url) — raw response text as InputDocument.content . loadGitHubFile(owner, repo, path, opts) , loadGitHubTree(owner, repo, { filter?, ... }) , loadNotionPage(pageId, { token }) , loadConfluencePage(pageId, { baseUrl, token?, authorization? }) , loadGoogleDriveFile(fileId, { accessToken }) , loadPdf(url, { parsePdf }) . All return InputDocument[] . See . - Cloud storage: loadS3 , loadGcs , loadDropbox , loadOneDrive . Failure and cancellation contract - Loader request, response-body, pagination, and total-download failures throw RagError with AK RAG LOAD FAILED . Tree loaders may return partial success only after at least one eligible document loaded. - Loader options accept signal?: AbortSignal ; Voyage and Jina reranker options accept the same additive field. - Notion and OneDrive follow provider pagination and reject repeated or missing continuation cursors instead of returning truncated content. - Scoreless Retriever results keep their order. If any score is present, all scores must be finite and the result is ordered descending; malformed mixed score sets throw. - Hybrid retrieval min-max normalizes candidate scores and normalizes relative weights before blending. Minimal example Related - — vector stores. - — embedders. Source - npm: https://www.npmjs.com/package/@agentskit/rag - repo: https://github.com/AgentsKit-io/agentskit/tree/main/packages/rag" }, { "id": "react-native", diff --git a/README.md b/README.md index 112ba14f..998b7f1a 100644 --- a/README.md +++ b/README.md @@ -394,7 +394,7 @@ See the [stability policy](./docs/STABILITY.md), [core v1 release notes](./docs/ AgentsKit is built in the open and ships because contributors show up. Every package, every doc, every example is fair game. -- **[How to contribute →](https://www.agentskit.io/docs/contribute)** — start here +- **[How to contribute →](https://www.agentskit.io/docs/reference/contribute)** — start here - **[Public roadmap board](https://github.com/orgs/AgentsKit-io/projects/1)** — what's planned, in flight, and shipped - **[Good-first-issues](https://github.com/AgentsKit-io/agentskit/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)** — curated, tractable tickets - **[Help-wanted](https://github.com/AgentsKit-io/agentskit/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)** — larger scoped work diff --git a/apps/docs-next/content/docs/agents/skills/summarizer.mdx b/apps/docs-next/content/docs/agents/skills/summarizer.mdx index 4a402a98..7cebdd3e 100644 --- a/apps/docs-next/content/docs/agents/skills/summarizer.mdx +++ b/apps/docs-next/content/docs/agents/skills/summarizer.mdx @@ -4,6 +4,7 @@ description: Compresses long inputs into short, faithful summaries. Length-aware --- ```ts +import { createRuntime } from '@agentskit/runtime' import { summarizer } from '@agentskit/skills' const runtime = createRuntime({ @@ -33,17 +34,28 @@ Use alongside `createAutoSummarizingMemory` to fold old turns automatically: ```ts import { createAutoSummarizingMemory } from '@agentskit/core/auto-summarize' import { createInMemoryMemory } from '@agentskit/core' +import { createRuntime } from '@agentskit/runtime' + +const summaryRuntime = createRuntime({ + adapter, + systemPrompt: 'Summarize the following chat transcript in 3 bullet points.', + maxTokens: 512, +}) const memory = createAutoSummarizingMemory(createInMemoryMemory(), { maxTokens: 8_000, keepRecent: 10, - summarizer: async msgs => ({ - id: crypto.randomUUID(), - role: 'system', - content: msgs.map(m => `${m.role}: ${m.content}`).join('\\n'), - status: 'complete', - createdAt: new Date(), - }), + summarizer: async msgs => { + const src = msgs.map(m => `${m.role}: ${m.content}`).join('\n') + const result = await summaryRuntime.run(src) + return { + id: crypto.randomUUID(), + role: 'system', + content: result.content, + status: 'complete', + createdAt: new Date(), + } + }, }) ``` diff --git a/apps/docs-next/content/docs/data/memory/auto-summarize.mdx b/apps/docs-next/content/docs/data/memory/auto-summarize.mdx index 438418cd..0d57a906 100644 --- a/apps/docs-next/content/docs/data/memory/auto-summarize.mdx +++ b/apps/docs-next/content/docs/data/memory/auto-summarize.mdx @@ -6,17 +6,28 @@ description: Fold oldest messages into a running summary. Token-budget-friendly. ```ts import { createAutoSummarizingMemory } from '@agentskit/core/auto-summarize' import { createInMemoryMemory } from '@agentskit/core' +import { createRuntime } from '@agentskit/runtime' + +const summaryRuntime = createRuntime({ + adapter, + systemPrompt: 'Summarize the following chat transcript in 3 bullet points.', + maxTokens: 512, +}) const memory = createAutoSummarizingMemory(createInMemoryMemory(), { maxTokens: 8_000, keepRecent: 6, - summarizer: async (msgs) => ({ - id: crypto.randomUUID(), - role: 'system', - content: msgs.map(m => `${m.role}: ${m.content}`).join('\n'), - status: 'complete', - createdAt: new Date(), - }), + summarizer: async (msgs) => { + const src = msgs.map(m => `${m.role}: ${m.content}`).join('\n') + const result = await summaryRuntime.run(src) + return { + id: crypto.randomUUID(), + role: 'system', + content: result.content, + status: 'complete', + createdAt: new Date(), + } + }, }) ``` diff --git a/apps/docs-next/content/docs/data/providers/deepseek-embedder.mdx b/apps/docs-next/content/docs/data/providers/deepseek-embedder.mdx index 6dfe0e67..4acf9906 100644 --- a/apps/docs-next/content/docs/data/providers/deepseek-embedder.mdx +++ b/apps/docs-next/content/docs/data/providers/deepseek-embedder.mdx @@ -8,6 +8,7 @@ import { deepseekEmbedder } from '@agentskit/adapters' const embed = deepseekEmbedder({ apiKey: process.env.DEEPSEEK_API_KEY!, + model: process.env.DEEPSEEK_EMBED_MODEL!, }) ``` @@ -19,6 +20,13 @@ const embed = deepseekEmbedder({ | `model` | `string` | required | | `baseUrl` | `string` | `https://api.deepseek.com` | +## Env + +| Var | Purpose | +|---|---| +| `DEEPSEEK_API_KEY` | API key | +| `DEEPSEEK_EMBED_MODEL` | Embedding model | + ## Related - [Embedders overview](./embedders) · [deepseek](./deepseek) diff --git a/apps/docs-next/content/docs/data/providers/embedders.mdx b/apps/docs-next/content/docs/data/providers/embedders.mdx index 43b03800..8dc10cef 100644 --- a/apps/docs-next/content/docs/data/providers/embedders.mdx +++ b/apps/docs-next/content/docs/data/providers/embedders.mdx @@ -22,6 +22,7 @@ type EmbedFn = (text: string) => Promise ## Usage ```ts +import type { EmbedFn } from '@agentskit/core' import { openaiEmbedder } from '@agentskit/adapters' const embed: EmbedFn = openaiEmbedder({ diff --git a/apps/docs-next/content/docs/data/providers/huggingface.mdx b/apps/docs-next/content/docs/data/providers/huggingface.mdx index 66a5797d..322435f4 100644 --- a/apps/docs-next/content/docs/data/providers/huggingface.mdx +++ b/apps/docs-next/content/docs/data/providers/huggingface.mdx @@ -18,7 +18,7 @@ const adapter = huggingface({ |---|---|---| | `apiKey` | `string` | required | | `model` | `string` | required | -| `baseUrl` | `string` | `https://api-inference.huggingface.co` | +| `baseUrl` | `string` | `https://router.huggingface.co/v1` | | `fetch` | `typeof fetch` | global | ## Env diff --git a/apps/docs-next/content/docs/data/providers/kimi-embedder.mdx b/apps/docs-next/content/docs/data/providers/kimi-embedder.mdx index d18cfc4e..bd38911f 100644 --- a/apps/docs-next/content/docs/data/providers/kimi-embedder.mdx +++ b/apps/docs-next/content/docs/data/providers/kimi-embedder.mdx @@ -8,6 +8,7 @@ import { kimiEmbedder } from '@agentskit/adapters' const embed = kimiEmbedder({ apiKey: process.env.KIMI_API_KEY!, + model: process.env.KIMI_EMBED_MODEL!, }) ``` @@ -19,6 +20,13 @@ const embed = kimiEmbedder({ | `model` | `string` | required | | `baseUrl` | `string` | `https://api.moonshot.ai` | +## Env + +| Var | Purpose | +|---|---| +| `KIMI_API_KEY` | API key | +| `KIMI_EMBED_MODEL` | Embedding model | + ## Related - [Embedders overview](./embedders) · [kimi](./kimi) diff --git a/apps/docs-next/content/docs/data/providers/kimi.mdx b/apps/docs-next/content/docs/data/providers/kimi.mdx index 7f2c113d..a2beb9db 100644 --- a/apps/docs-next/content/docs/data/providers/kimi.mdx +++ b/apps/docs-next/content/docs/data/providers/kimi.mdx @@ -18,7 +18,7 @@ const adapter = kimi({ |---|---|---| | `apiKey` | `string` | required | | `model` | `string` | required | -| `baseUrl` | `string` | `https://api.moonshot.cn/v1` | +| `baseUrl` | `string` | `https://api.moonshot.ai` | | `fetch` | `typeof fetch` | global | ## Model examples diff --git a/apps/docs-next/content/docs/data/rag/context-injection.mdx b/apps/docs-next/content/docs/data/rag/context-injection.mdx index c51b0a08..77a6ff5e 100644 --- a/apps/docs-next/content/docs/data/rag/context-injection.mdx +++ b/apps/docs-next/content/docs/data/rag/context-injection.mdx @@ -52,7 +52,7 @@ const systemPrompt = [ ].filter(Boolean).join('\n\n') ``` -Pass `systemPrompt` as the `systemPrompt` field to your adapter or `createRuntime` call. +Pass `systemPrompt` as `context.systemPrompt` when calling `adapter.createSource`, or use it as the `systemPrompt` field in `createRuntime`. ## Runtime integration — pass `retriever` directly @@ -74,7 +74,7 @@ const runtime = createRuntime({ const result = await runtime.run('How does token budgeting work?') ``` -The runtime appends the context block after your base `system` string, separated by a blank line. +The runtime appends the context block after your base `systemPrompt` string, separated by a blank line. ## Controlling what gets injected diff --git a/apps/docs-next/content/docs/data/rag/rerank.mdx b/apps/docs-next/content/docs/data/rag/rerank.mdx index 8f9d2b67..8023e254 100644 --- a/apps/docs-next/content/docs/data/rag/rerank.mdx +++ b/apps/docs-next/content/docs/data/rag/rerank.mdx @@ -1,6 +1,6 @@ --- title: Rerank -description: Post-retrieval reranker. Voyage / Jina / built-in BM25. +description: Post-retrieval reranker. Voyage / Jina / custom functions / built-in BM25. --- ```ts diff --git a/apps/docs-next/content/docs/for-agents/memory.mdx b/apps/docs-next/content/docs/for-agents/memory.mdx index 7aa89f65..1acfa132 100644 --- a/apps/docs-next/content/docs/for-agents/memory.mdx +++ b/apps/docs-next/content/docs/for-agents/memory.mdx @@ -23,7 +23,7 @@ npm install @agentskit/memory ### Vector memory -- `fileVectorMemory({ path })` — JSON file. +- `fileVectorMemory({ path })` — Vectra-backed index directory (optional `vectra` peer). - `redisVectorMemory` — Redis Vector. - `pgvector`, `pinecone`, `qdrant`, `chroma`, `upstashVector` — BYO-client / HTTP vector adapters. See [Vector adapters](/docs/reference/recipes/vector-adapters). - `supabaseVectorStore`, `weaviateVectorStore`, `milvusVectorStore`, `mongoAtlasVectorStore` — managed / cluster backends. diff --git a/apps/docs-next/content/docs/get-started/concepts/memory.mdx b/apps/docs-next/content/docs/get-started/concepts/memory.mdx index b6d44b68..ebc48c1c 100644 --- a/apps/docs-next/content/docs/get-started/concepts/memory.mdx +++ b/apps/docs-next/content/docs/get-started/concepts/memory.mdx @@ -57,7 +57,7 @@ export interface VectorMemory { import { fileVectorMemory } from '@agentskit/memory' import { openaiEmbedder } from '@agentskit/adapters' -const store = fileVectorMemory({ path: './embeddings.json' }) +const store = fileVectorMemory({ path: '.agentskit/vectors' }) const embed = openaiEmbedder({ apiKey: KEY, model: 'text-embedding-3-small' }) await store.store([ diff --git a/apps/docs-next/content/docs/get-started/migrating/from-langchain.mdx b/apps/docs-next/content/docs/get-started/migrating/from-langchain.mdx index 523d7a18..42723c1d 100644 --- a/apps/docs-next/content/docs/get-started/migrating/from-langchain.mdx +++ b/apps/docs-next/content/docs/get-started/migrating/from-langchain.mdx @@ -355,7 +355,7 @@ import { createRAG } from '@agentskit/rag' import { fileVectorMemory } from '@agentskit/memory' const rag = createRAG({ - store: fileVectorMemory({ path: './embeddings.json' }), + store: fileVectorMemory({ path: '.agentskit/vectors' }), embed: openaiEmbedder({ apiKey: KEY, model: 'text-embedding-3-small' }), }) diff --git a/apps/docs-next/content/docs/get-started/migrating/from-llamaindex.mdx b/apps/docs-next/content/docs/get-started/migrating/from-llamaindex.mdx index 4af5ebf4..ff13e300 100644 --- a/apps/docs-next/content/docs/get-started/migrating/from-llamaindex.mdx +++ b/apps/docs-next/content/docs/get-started/migrating/from-llamaindex.mdx @@ -63,7 +63,7 @@ import { join } from 'node:path' const rag = createRAG({ embed: openaiEmbedder({ apiKey: KEY, model: 'text-embedding-3-small' }), - store: fileVectorMemory({ path: './embeddings.json' }), + store: fileVectorMemory({ path: '.agentskit/vectors' }), }) const docs = await Promise.all( @@ -196,7 +196,7 @@ Memory load + save, retrieval per turn, tool resolution — all handled. The run | Backend | Import | Notes | |---|---|---| | In-memory | `createInMemoryMemory` (core) | Tests, demos. | -| File JSON | `fileVectorMemory({ path })` | Vectra-backed; one process. | +| File vector index | `fileVectorMemory({ path })` | Vectra-backed index directory; one process. | | Postgres | `pgvector(...)` | Bring your own client (`pg` Pool, Neon, Supabase RPC). | | Pinecone | `pinecone({ indexUrl, apiKey })` | HTTP only; no SDK dep. | | Qdrant | `qdrant({ url, apiKey?, collection })` | HTTP only. | diff --git a/apps/docs-next/content/docs/get-started/migrating/from-mastra.mdx b/apps/docs-next/content/docs/get-started/migrating/from-mastra.mdx index 0d784cdc..902211d9 100644 --- a/apps/docs-next/content/docs/get-started/migrating/from-mastra.mdx +++ b/apps/docs-next/content/docs/get-started/migrating/from-mastra.mdx @@ -194,7 +194,7 @@ import { sqliteChatMemory, fileVectorMemory } from '@agentskit/memory' import { createRAG } from '@agentskit/rag' const rag = createRAG({ - store: fileVectorMemory({ path: './embeddings.json' }), + store: fileVectorMemory({ path: '.agentskit/vectors' }), embed: openaiEmbedder({ apiKey: KEY, model: 'text-embedding-3-small' }), topK: 3, }) @@ -232,7 +232,7 @@ import { createRAG } from '@agentskit/rag' import { fileVectorMemory } from '@agentskit/memory' const rag = createRAG({ - store: fileVectorMemory({ path: './embeddings.json' }), + store: fileVectorMemory({ path: '.agentskit/vectors' }), embed: openaiEmbedder({ apiKey: KEY, model: 'text-embedding-3-small' }), }) diff --git a/apps/docs-next/content/docs/get-started/migrating/from-openai-assistants.mdx b/apps/docs-next/content/docs/get-started/migrating/from-openai-assistants.mdx index 9341dc29..c51168fe 100644 --- a/apps/docs-next/content/docs/get-started/migrating/from-openai-assistants.mdx +++ b/apps/docs-next/content/docs/get-started/migrating/from-openai-assistants.mdx @@ -96,7 +96,7 @@ import { openaiEmbedder } from '@agentskit/adapters' const rag = createRAG({ embed: openaiEmbedder({ apiKey: KEY, model: 'text-embedding-3-small' }), - store: fileVectorMemory({ path: './kb.json' }), + store: fileVectorMemory({ path: '.agentskit/vectors' }), }) await rag.ingest([ diff --git a/apps/docs-next/content/docs/get-started/migrating/from-vercel-ai-sdk.mdx b/apps/docs-next/content/docs/get-started/migrating/from-vercel-ai-sdk.mdx index 55eed28e..fddb8b6e 100644 --- a/apps/docs-next/content/docs/get-started/migrating/from-vercel-ai-sdk.mdx +++ b/apps/docs-next/content/docs/get-started/migrating/from-vercel-ai-sdk.mdx @@ -256,7 +256,7 @@ import { fileVectorMemory } from '@agentskit/memory' import { openaiEmbedder } from '@agentskit/adapters' const rag = createRAG({ - store: fileVectorMemory({ path: './embeddings.json' }), + store: fileVectorMemory({ path: '.agentskit/vectors' }), embed: openaiEmbedder({ apiKey: KEY, model: 'text-embedding-3-small' }), }) diff --git a/apps/docs-next/content/docs/reference/recipes/auto-summarize.mdx b/apps/docs-next/content/docs/reference/recipes/auto-summarize.mdx index a45e61e8..d2cd0e34 100644 --- a/apps/docs-next/content/docs/reference/recipes/auto-summarize.mdx +++ b/apps/docs-next/content/docs/reference/recipes/auto-summarize.mdx @@ -25,18 +25,22 @@ import { createInMemoryMemory } from '@agentskit/core' import { createRuntime } from '@agentskit/runtime' import { anthropic } from '@agentskit/adapters' -const summarizerAdapter = anthropic({ apiKey: process.env.ANTHROPIC_API_KEY!, model: 'claude-haiku-4-5' }) +const summaryRuntime = createRuntime({ + adapter: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY!, model: 'claude-haiku-4-5' }), + systemPrompt: 'Summarize the following chat transcript in 3 bullet points.', + maxTokens: 512, +}) const memory = createAutoSummarizingMemory(createInMemoryMemory(), { maxTokens: 8_000, keepRecent: 6, summarizer: async messages => { const src = messages.map(m => `${m.role}: ${m.content}`).join('\n') - const result = await runOnce(summarizerAdapter, `Summarize the following chat transcript in 3 bullet points:\n\n${src}`) + const result = await summaryRuntime.run(src) return { id: crypto.randomUUID(), role: 'system', - content: result, + content: result.content, status: 'complete', createdAt: new Date(), } diff --git a/apps/docs-next/content/docs/reference/recipes/doc-loaders.mdx b/apps/docs-next/content/docs/reference/recipes/doc-loaders.mdx index 63b9e5ac..38f7ae2b 100644 --- a/apps/docs-next/content/docs/reference/recipes/doc-loaders.mdx +++ b/apps/docs-next/content/docs/reference/recipes/doc-loaders.mdx @@ -49,7 +49,7 @@ const docs = await loadGitHubTree('my-org', 'my-repo', { const rag = createRAG({ embed: openaiEmbedder({ apiKey: process.env.OPENAI_API_KEY! }), - store: fileVectorMemory({ path: './kb.json' }), + store: fileVectorMemory({ path: '.agentskit/vectors' }), }) await rag.ingest(docs) ``` diff --git a/apps/docs-next/content/docs/reference/recipes/hierarchical-memory.mdx b/apps/docs-next/content/docs/reference/recipes/hierarchical-memory.mdx index 408fb597..320cd822 100644 --- a/apps/docs-next/content/docs/reference/recipes/hierarchical-memory.mdx +++ b/apps/docs-next/content/docs/reference/recipes/hierarchical-memory.mdx @@ -29,7 +29,7 @@ import { const archival = fileChatMemory({ path: './sessions/user-42.json' }) const working = fileChatMemory({ path: './sessions/user-42.hot.json' }) -const vectorStore = fileVectorMemory({ path: './sessions/user-42.vectors.json' }) +const vectorStore = fileVectorMemory({ path: '.agentskit/vectors' }) const memory = createHierarchicalMemory({ working, diff --git a/apps/docs-next/content/docs/reference/recipes/pdf-qa.mdx b/apps/docs-next/content/docs/reference/recipes/pdf-qa.mdx index 5522899d..96808c89 100644 --- a/apps/docs-next/content/docs/reference/recipes/pdf-qa.mdx +++ b/apps/docs-next/content/docs/reference/recipes/pdf-qa.mdx @@ -52,7 +52,7 @@ function chunk(text: string, size = 500): string[] { // 3. Index in-memory (per-PDF, ephemeral) const rag = createRAG({ - store: fileVectorMemory({ path: `./.cache/${pdfPath}.embeddings.json` }), + store: fileVectorMemory({ path: `./.cache/vectors/${pdfPath}` }), embed: openaiEmbedder({ apiKey: KEY, model: 'text-embedding-3-small' }), topK: 4, }) @@ -86,7 +86,7 @@ npx tsx ask-pdf.ts paper.pdf "What is the main contribution of this work?" ## Why this works -- **Per-PDF cache** at `./.cache/.embeddings.json` — second run is instant +- **Per-PDF index** at `./.cache/vectors/` — second run is instant - **Source citations** because `RetrievedDocument.source` makes it into the prompt - **No memory** — each invocation is independent; perfect for one-shot Q&A diff --git a/apps/docs-next/content/docs/reference/recipes/rag-chat.mdx b/apps/docs-next/content/docs/reference/recipes/rag-chat.mdx index 9d8ab1c6..9240cc3f 100644 --- a/apps/docs-next/content/docs/reference/recipes/rag-chat.mdx +++ b/apps/docs-next/content/docs/reference/recipes/rag-chat.mdx @@ -23,7 +23,7 @@ import { readFileSync, readdirSync } from 'node:fs' import { join } from 'node:path' const rag = createRAG({ - store: fileVectorMemory({ path: './embeddings.json' }), + store: fileVectorMemory({ path: '.agentskit/vectors' }), embed: openaiEmbedder({ apiKey: KEY, model: 'text-embedding-3-small' }), }) @@ -51,7 +51,7 @@ import { openaiEmbedder } from '@agentskit/adapters' import '@agentskit/react/theme' const rag = createRAG({ - store: fileVectorMemory({ path: './embeddings.json' }), + store: fileVectorMemory({ path: '.agentskit/vectors' }), embed: openaiEmbedder({ apiKey: KEY, model: 'text-embedding-3-small' }), }) diff --git a/apps/docs-next/content/docs/reference/recipes/rag-reranking.mdx b/apps/docs-next/content/docs/reference/recipes/rag-reranking.mdx index bc3c34ac..c935693d 100644 --- a/apps/docs-next/content/docs/reference/recipes/rag-reranking.mdx +++ b/apps/docs-next/content/docs/reference/recipes/rag-reranking.mdx @@ -1,6 +1,6 @@ --- title: RAG reranking + hybrid search -description: Wrap your vector retriever with BM25 hybrid scoring and pluggable rerankers (Cohere Rerank, BGE, etc.). +description: Wrap your vector retriever with BM25 hybrid scoring and custom rerank functions. --- Vector search is fast, but often misses exact-keyword matches and @@ -22,7 +22,7 @@ import { openaiEmbedder } from '@agentskit/adapters' const base = createRAG({ embed: openaiEmbedder({ apiKey: process.env.OPENAI_API_KEY! }), - store: fileVectorMemory({ path: './kb.vectors.json' }), + store: fileVectorMemory({ path: '.agentskit/vectors' }), topK: 20, }) diff --git a/apps/docs-next/lib/deterministic-knowledge.generated.json b/apps/docs-next/lib/deterministic-knowledge.generated.json index d866a0a5..0fa0b3ed 100644 --- a/apps/docs-next/lib/deterministic-knowledge.generated.json +++ b/apps/docs-next/lib/deterministic-knowledge.generated.json @@ -3,12 +3,12 @@ "version": 1, "artifactId": "agentskit-docs-v1", "siteId": "agentskit-docs", - "generatedAt": "2026-08-12T21:41:58-03:00", + "generatedAt": "2026-08-12T22:55:06-03:00", "entries": [ { "id": "claim.catalog-models", "kind": "restricted-faq", - "label": "5162 models", + "label": "6293 models", "match": { "type": "exact", "values": [ @@ -18,7 +18,7 @@ ] }, "answer": { - "markdown": "The verified AgentsKit ledger currently reports **5162 models**. The public conservative floor is 5000.", + "markdown": "The verified AgentsKit ledger currently reports **6293 models**. The public conservative floor is 6000.", "citations": [ { "id": "claim-catalog-models", @@ -31,7 +31,7 @@ { "id": "claim.catalog-providers", "kind": "restricted-faq", - "label": "140 providers", + "label": "184 providers", "match": { "type": "exact", "values": [ @@ -41,7 +41,7 @@ ] }, "answer": { - "markdown": "The verified AgentsKit ledger currently reports **140 providers**. The public conservative floor is 140.", + "markdown": "The verified AgentsKit ledger currently reports **184 providers**. The public conservative floor is 180.", "citations": [ { "id": "claim-catalog-providers", @@ -2260,5 +2260,5 @@ } } ], - "contentHash": "sha256:a8976e98efc0f912c81fce84e5c5f54b2bfb66193352efba70c06d25e6171a63" + "contentHash": "sha256:70679069128f2f8f0f8facd3c57f0669cce1bff59cc8dc39c8b3e761cf54f7b0" } diff --git a/apps/docs-next/lib/deterministic-site.generated.json b/apps/docs-next/lib/deterministic-site.generated.json index 12781307..8b163636 100644 --- a/apps/docs-next/lib/deterministic-site.generated.json +++ b/apps/docs-next/lib/deterministic-site.generated.json @@ -3,8 +3,8 @@ "version": 1, "siteId": "agentskit-docs", "artifact": { - "href": "/deterministic-knowledge/a8976e98efc0f912c81fce84e5c5f54b2bfb66193352efba70c06d25e6171a63.json", - "contentHash": "sha256:a8976e98efc0f912c81fce84e5c5f54b2bfb66193352efba70c06d25e6171a63" + "href": "/deterministic-knowledge/70679069128f2f8f0f8facd3c57f0669cce1bff59cc8dc39c8b3e761cf54f7b0.json", + "contentHash": "sha256:70679069128f2f8f0f8facd3c57f0669cce1bff59cc8dc39c8b3e761cf54f7b0" }, "fallback": { "mode": "backend" diff --git a/apps/docs-next/package.json b/apps/docs-next/package.json index f89ff8cf..4fbcce00 100644 --- a/apps/docs-next/package.json +++ b/apps/docs-next/package.json @@ -17,6 +17,7 @@ "docs": "next dev --turbo", "start": "next start", "lint": "node scripts/gen-ask-context.mjs && tsc --noEmit", + "test": "vitest run", "lint:mdx": "node scripts/lint-mdx.mjs", "check:links": "node scripts/check-links.mjs", "gen:api": "node scripts/gen-api.mjs", @@ -68,6 +69,7 @@ "tsx": "^4.23.5", "typedoc": "^0.28.20", "typedoc-plugin-markdown": "^4.12.0", - "typescript": "^6.0.3" + "typescript": "^6.0.3", + "vitest": "^4.1.10" } } diff --git a/apps/docs-next/public/deterministic-knowledge/a8976e98efc0f912c81fce84e5c5f54b2bfb66193352efba70c06d25e6171a63.json b/apps/docs-next/public/deterministic-knowledge/70679069128f2f8f0f8facd3c57f0669cce1bff59cc8dc39c8b3e761cf54f7b0.json similarity index 99% rename from apps/docs-next/public/deterministic-knowledge/a8976e98efc0f912c81fce84e5c5f54b2bfb66193352efba70c06d25e6171a63.json rename to apps/docs-next/public/deterministic-knowledge/70679069128f2f8f0f8facd3c57f0669cce1bff59cc8dc39c8b3e761cf54f7b0.json index d866a0a5..0fa0b3ed 100644 --- a/apps/docs-next/public/deterministic-knowledge/a8976e98efc0f912c81fce84e5c5f54b2bfb66193352efba70c06d25e6171a63.json +++ b/apps/docs-next/public/deterministic-knowledge/70679069128f2f8f0f8facd3c57f0669cce1bff59cc8dc39c8b3e761cf54f7b0.json @@ -3,12 +3,12 @@ "version": 1, "artifactId": "agentskit-docs-v1", "siteId": "agentskit-docs", - "generatedAt": "2026-08-12T21:41:58-03:00", + "generatedAt": "2026-08-12T22:55:06-03:00", "entries": [ { "id": "claim.catalog-models", "kind": "restricted-faq", - "label": "5162 models", + "label": "6293 models", "match": { "type": "exact", "values": [ @@ -18,7 +18,7 @@ ] }, "answer": { - "markdown": "The verified AgentsKit ledger currently reports **5162 models**. The public conservative floor is 5000.", + "markdown": "The verified AgentsKit ledger currently reports **6293 models**. The public conservative floor is 6000.", "citations": [ { "id": "claim-catalog-models", @@ -31,7 +31,7 @@ { "id": "claim.catalog-providers", "kind": "restricted-faq", - "label": "140 providers", + "label": "184 providers", "match": { "type": "exact", "values": [ @@ -41,7 +41,7 @@ ] }, "answer": { - "markdown": "The verified AgentsKit ledger currently reports **140 providers**. The public conservative floor is 140.", + "markdown": "The verified AgentsKit ledger currently reports **184 providers**. The public conservative floor is 180.", "citations": [ { "id": "claim-catalog-providers", @@ -2260,5 +2260,5 @@ } } ], - "contentHash": "sha256:a8976e98efc0f912c81fce84e5c5f54b2bfb66193352efba70c06d25e6171a63" + "contentHash": "sha256:70679069128f2f8f0f8facd3c57f0669cce1bff59cc8dc39c8b3e761cf54f7b0" } diff --git a/apps/docs-next/scripts/gen-deterministic-knowledge.mjs b/apps/docs-next/scripts/gen-deterministic-knowledge.mjs index 65e579f3..62e40cc2 100644 --- a/apps/docs-next/scripts/gen-deterministic-knowledge.mjs +++ b/apps/docs-next/scripts/gen-deterministic-knowledge.mjs @@ -23,9 +23,33 @@ const gitValue = (args) => { return '' } } -const generatedAt = (process.env.DETERMINISTIC_KNOWLEDGE_GENERATED_AT - ?? gitValue(['log', '-1', '--format=%cI', '--', '.doc-bridge/index.json', 'ecosystem-claims.json', 'ecosystem.json', 'apps/docs-next/scripts/gen-deterministic-knowledge.mjs'])) - || '1970-01-01T00:00:00.000Z' +const isValidGeneratedAt = (value) => { + if (typeof value !== 'string' || value.trim() === '') return false + const timestamp = Date.parse(value) + return Number.isFinite(timestamp) && timestamp !== 0 +} +const existingGeneratedAt = async () => { + try { + return JSON.parse(await readFile(join(appRoot, 'lib/deterministic-knowledge.generated.json'), 'utf8')).generatedAt + } catch { + return '' + } +} +const resolveGeneratedAt = async () => { + const generatedAt = [ + process.env.DETERMINISTIC_KNOWLEDGE_GENERATED_AT, + await existingGeneratedAt(), + gitValue(['log', '-1', '--format=%cI', '--', '.doc-bridge/index.json', 'ecosystem-claims.json', 'ecosystem.json']), + process.env.VERCEL_GIT_COMMIT_COMMITTED_DATE, + ].find(isValidGeneratedAt) + if (!generatedAt) { + throw new Error( + 'Missing deterministic knowledge generatedAt. Set DETERMINISTIC_KNOWLEDGE_GENERATED_AT or VERCEL_GIT_COMMIT_COMMITTED_DATE, keep a valid generatedAt in the checked-in artifact, or run from a git checkout.', + ) + } + return generatedAt +} +const generatedAt = await resolveGeneratedAt() const budgetBytes = 96 * 1024 const readJson = async path => JSON.parse(await readFile(join(repoRoot, path), 'utf8')) diff --git a/apps/docs-next/tests/deterministic-docs-answers.test.mjs b/apps/docs-next/tests/deterministic-docs-answers.test.mjs index 81989c60..d6c82a35 100644 --- a/apps/docs-next/tests/deterministic-docs-answers.test.mjs +++ b/apps/docs-next/tests/deterministic-docs-answers.test.mjs @@ -54,9 +54,12 @@ test('the generated artifact is schema-valid, hash-anchored, compact, and conten test('generation is byte-identical for unchanged canonical inputs', () => { const beforeArtifact = readFileSync(artifactPath, 'utf8') const beforeSite = readFileSync(sitePath, 'utf8') + const env = { ...process.env, VERCEL_GIT_COMMIT_COMMITTED_DATE: '2099-01-01T00:00:00.000Z' } + delete env.DETERMINISTIC_KNOWLEDGE_GENERATED_AT const generated = spawnSync('pnpm', ['--filter', '@agentskit/docs-next', 'gen:deterministic-knowledge'], { cwd: REPO_ROOT, encoding: 'utf8', + env, }) assert.equal(generated.status, 0, generated.stderr) assert.equal(readFileSync(artifactPath, 'utf8'), beforeArtifact) @@ -150,7 +153,7 @@ test('the real widget composes published AgentsChat local-first contracts', () = assert.match(widget, /choiceSubmission: adapter\.resolveChoiceSubmission/) assert.match(widget, /fallbackMode: deterministicSite\.fallback\.mode/) assert.match(widget, /data-ak-answer-path/) - assert.match(docsPackage, /"@agentskit\/chat": "0\.3\.0"/) + assert.match(docsPackage, /"@agentskit\/chat": "0\.4\.0"/) assert.doesNotMatch(docsPackage, /"@agentskit\/chat-(?:protocol|react)":/) assert.doesNotMatch(rootPackage, /"@agentskit\/chat(?:-protocol)?":/) assert.doesNotMatch(widget, /function normalizeDeterministic|new Map { it.each([ diff --git a/apps/docs-next/vitest.config.ts b/apps/docs-next/vitest.config.ts index 0c0ee3ac..bfa4843e 100644 --- a/apps/docs-next/vitest.config.ts +++ b/apps/docs-next/vitest.config.ts @@ -10,6 +10,6 @@ export default defineConfig({ }, test: { environment: 'node', - include: ['tests/**/*.test.ts'], + include: ['tests/**/*.test.ts', 'tests/**/*.test.mjs'], }, }) diff --git a/packages/cli/README.md b/packages/cli/README.md index f0c5db28..50001bc6 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -94,7 +94,7 @@ agentskit run --help - Built-in live providers include OpenAI, Anthropic, Gemini, DeepSeek, Grok, Kimi, Groq, and OpenRouter; Ollama remains local and keyless - `agentskit init --provider deepseek|grok|kimi|groq|openrouter` — scaffold a starter already wired to the selected provider -Full reference: [docs/infrastructure/cli](https://www.agentskit.io/docs/infrastructure/cli) · [ARCHITECTURE.md](./ARCHITECTURE.md) +Full reference: [docs/production/cli](https://www.agentskit.io/docs/production/cli) · [ARCHITECTURE.md](./ARCHITECTURE.md) ### agentskit doctor diff --git a/packages/memory/package.json b/packages/memory/package.json index 5045590f..a616b801 100644 --- a/packages/memory/package.json +++ b/packages/memory/package.json @@ -61,6 +61,14 @@ "dependencies": { "@agentskit/core": "workspace:*" }, + "peerDependencies": { + "vectra": "^0.15.0" + }, + "peerDependenciesMeta": { + "vectra": { + "optional": true + } + }, "devDependencies": { "@types/better-sqlite3": "^7.6.13", "@types/node": "^25.9.5", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 560d81b4..7f3734ed 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -262,6 +262,9 @@ importers: typescript: specifier: ^6.0.3 version: 6.0.3 + vitest: + specifier: ^4.1.10 + version: 4.1.10(@opentelemetry/api@1.9.1)(@types/node@25.9.5)(@vitest/coverage-v8@4.1.10)(happy-dom@20.10.6)(jsdom@29.1.1(@noble/hashes@2.2.0))(msw@2.15.0(@types/node@25.9.5)(typescript@6.0.3))(vite@8.1.4(@types/node@25.9.5)(esbuild@0.28.1)(jiti@2.7.0)(less@4.6.7)(sass@1.101.0)(terser@5.48.0)(tsx@4.23.0)(yaml@2.9.0)) apps/example-discord-bot: dependencies: diff --git a/readme-standard-v1.json b/readme-standard-v1.json index 8f21d78c..76775e0d 100644 --- a/readme-standard-v1.json +++ b/readme-standard-v1.json @@ -208,7 +208,7 @@ "ecosystem.json", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:ffaad71cc9e84856581b1ea28271599d3248e3ced280fb154654058a5218c6d5" + "sourceHash": "sha256:f1fcac65d645d87448c4e17ab4c22eb1ccdfb549712fd2522dbc7daabd574b14" }, "exceptions": [] }, @@ -287,7 +287,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:d210b9657181c5e6cc761fcd6e39dee8b1a8b8b631a3fe711a62f0c3956edc4b" + "sourceHash": "sha256:3e0f5c2fc9211dad117a669571d77b3e517f78bf19568851ee249264836e2bb7" }, "exceptions": [] }, @@ -366,7 +366,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:0ef7164ab76c0f18ba1a5b3517a2c6fe53f70b2f27c3c00183bb724441e15599" + "sourceHash": "sha256:f445e0021f391023214c9643d11d852b00d8ae699c374fb34f98b8dacfcf5d27" }, "exceptions": [] }, @@ -445,7 +445,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:23dd7b213770e99bd91586df05e1c879fc8e01991f1800b1eb426cdb02cb8e77" + "sourceHash": "sha256:09c87d48b5eee82ce7713a4f74296025eb25c32461a4a1f1c9d1e42a708ad79a" }, "exceptions": [] }, @@ -524,7 +524,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:8de6f0d7621dc1d4ed10fc1ae165a5401e15d89b82544aa4a53d92d5aafe5c91" + "sourceHash": "sha256:ecf32bf19c7546d4112c643b0cb3a6269bd288bf10d9ba58657013f404b1f307" }, "exceptions": [] }, @@ -603,7 +603,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:90b8535e0876338044424d0e136ba612a7b4b0e5839fcc37161bfe008d1d7cb8" + "sourceHash": "sha256:58d01d8ae2b516e98c96b4ff626c71d6dbe041cc06ed8b66144e082093ab56a3" }, "exceptions": [] }, @@ -682,7 +682,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:91b800cd7f2cadc121c0b80bc42cf38d92f11e5351e02f0e4cf6032bfb877216" + "sourceHash": "sha256:2e3f2e9fea80dc95286ca4ed990962e9c8b18da6902155b8889e38189a8657bb" }, "exceptions": [] }, @@ -761,7 +761,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:aa2fdb8f2a006fcaa4ac358723acf953741d4ae5e1c0f0b3c4b485163fafb50a" + "sourceHash": "sha256:e6d954f6053a69f397155c90ca82fdfe9337d0750eeec284a73126c254d453df" }, "exceptions": [] }, @@ -840,7 +840,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:0eda648d3d5a44761028c7b658325256d5375a8c3d57a487e18fed2eb010c808" + "sourceHash": "sha256:a6a4fdfa8dd64c70115522d4c2b63b5197b9bf5a0d2c418998cd7d747c60b242" }, "exceptions": [] }, @@ -919,7 +919,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:2d97834a2fbb3c87c87465d8d4486e9f296958d446df1745a9965b2f7f359f12" + "sourceHash": "sha256:e7295cda7b5b2995cd6a7352f3920faa3567c1b31a7b5ed28db670ff25bb04f3" }, "exceptions": [] }, @@ -998,7 +998,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:9a84389349e686a9cfbd7237080017793b9ae078d2d330687efdb76600af3a0a" + "sourceHash": "sha256:b25f46950697316b71a26078c39c0729e352da0751a1c7013e1f33303a63f20e" }, "exceptions": [] }, @@ -1077,7 +1077,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:e510a7f3c13d19112c394047f5ccc1ac7ae983c0d3e77825499bb5ef1ea13e1e" + "sourceHash": "sha256:4332cab74ffc54975a4b3096ca19a802b36915b294912c4d64b45cbf94ef7b4d" }, "exceptions": [] }, @@ -1156,7 +1156,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:1e94e42166e72c3f8559275f298cd408a303d9176fab496c5d8d1e8bb4810061" + "sourceHash": "sha256:c6d61cc19b7dfff687de01f97eaa32ff43366b6e919fb70468938cd60fa81b6c" }, "exceptions": [] }, @@ -1235,7 +1235,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:ed3d75fc6f5658fd180e114ca6e16bdef5e02854c2c894a3693f09f7b2bdece8" + "sourceHash": "sha256:02474b9b3d7962acdd002b1111134703800ea6b435a09e4c64e97ae8516f904a" }, "exceptions": [] }, @@ -1314,7 +1314,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:2ff3f560a4906ef294fda390417af24ed6f433d26ee215770c2e6ec1ef793494" + "sourceHash": "sha256:7532732c218d4a9a3e35b4d08a194978a4f37a11e099db6f5d7a51e1809dfc94" }, "exceptions": [] }, @@ -1393,7 +1393,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:5b596e6cbd1bb3749b9bfec4e12cb9b1e0e9d4eeda9d3a1619e2a2da65fa51ed" + "sourceHash": "sha256:9ca050b9974158cb5cf3d64b5f41bac76ca2963267277a9a970beb4916a04836" }, "exceptions": [] }, @@ -1472,7 +1472,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:be3638e6e04690b89c2528a053d5c944293ba1e0a4618358b2d1f068cdaba41c" + "sourceHash": "sha256:c92700b6714342d5e3f927e729b190c35b2ac36cc2309c808c3176b8aaa07930" }, "exceptions": [] }, @@ -1551,7 +1551,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:3f6322359bed0ba799b5b9deb90a0287bb4346bd343b1fd90b059e6ddff29dc9" + "sourceHash": "sha256:69bd84da3d8093aa7a25b0b4e8ec3bcfe2c73d76f9188d999b89f69cb2576fe8" }, "exceptions": [] }, @@ -1630,7 +1630,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:fabd0f2bc0a771594028b6c6d99b504691d37c3a258f9eb352c5f52622e278df" + "sourceHash": "sha256:6365951bd4ea4ea7db98f491400d02021ca0afe3dcaae99c3c9239da56e8d497" }, "exceptions": [] }, @@ -1709,7 +1709,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:92ee2f92676c1874dad5a868279274ba8619cce22436bc4466a261aa66f5e60f" + "sourceHash": "sha256:1443fc9c032cc0ff5832f9f7ab0d7c3c9581ac98e99a36ac9fd34b17d611452e" }, "exceptions": [] }, @@ -1788,7 +1788,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:562d74814a2bb95f11ee67cfff9a29681dae94462018dd8f9b24780df8992b73" + "sourceHash": "sha256:7836f701edb76985ca029595ea2c6812ade398661d6de992b07cd60cdc0044c2" }, "exceptions": [] }, @@ -1867,7 +1867,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:232098e75f48cc94df287903e4bef2aa4822ef541817f1bf63130555ef0f8534" + "sourceHash": "sha256:19a166cdb815cc53171d0ef7e15682fbe9f8b50b32e306b27a0b67712eaf935a" }, "exceptions": [] }, @@ -1946,7 +1946,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:398a3b9d317731ef92e99e6f68b6e2807e74588f6f8551fd8dd80395649eb802" + "sourceHash": "sha256:112c7b4f895a091f0a0e159c0db5ec98cd9968e64ca433663f0ad2fd640fc81c" }, "exceptions": [] }, @@ -2025,7 +2025,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:a5251a9052206dad693d7f6da664e67ab7b406741a1d117172111d29247aea1f" + "sourceHash": "sha256:2f6a0d385f4e5e81bfc7bef94bc8722fdf789d85e30723e4e7a4cd5c2cbc75d3" }, "exceptions": [] }, @@ -2104,7 +2104,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:76ad3551fb175d0a55ad2433f27e68b430a6c412e5424232beae1f150473db76" + "sourceHash": "sha256:37a81ee5daa0526f67ae4df369e6ef621820a05a6bcd9ed0738466517c23cbe4" }, "exceptions": [] }, @@ -2183,7 +2183,7 @@ "docs/STABILITY.md", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:2e6c1ffff6f3f8dcf50a2d6b4c5ebd5505bcc6ff7d936005bc32318fbdad91c4" + "sourceHash": "sha256:309c6a365e121e508d4c5d8b2b9a5f9fdbe4702c9872268e91ddeec9d99afda1" }, "exceptions": [] }, @@ -2253,7 +2253,7 @@ "ecosystem-claims.json", "scripts/readme-fixtures.test.mjs" ], - "sourceHash": "sha256:c555bbde331247679f340b7343b65df9bfb0df98bb4aeccfaf5d808b0b889c3f" + "sourceHash": "sha256:95589b5ca70bdf3aea410f7e70b6e8520742f9c944a989265e03b6b4d10a84e7" }, "exceptions": [ { From fa6697d8423c45685b1190d25f60b436c21e3e67 Mon Sep 17 00:00:00 2001 From: EmersonBraun Date: Wed, 12 Aug 2026 23:18:56 -0300 Subject: [PATCH 19/19] docs: refresh documentation quality attestation --- .../evidence/ecosystem-documentation-quality/agentskit.json | 6 +++--- .../doc-bridge/agentskit.json | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/evidence/ecosystem-documentation-quality/agentskit.json b/docs/evidence/ecosystem-documentation-quality/agentskit.json index 07ca72c8..cd310304 100644 --- a/docs/evidence/ecosystem-documentation-quality/agentskit.json +++ b/docs/evidence/ecosystem-documentation-quality/agentskit.json @@ -4,8 +4,8 @@ "profileVersion": 1, "productId": "agentskit", "repo": "AgentsKit-io/agentskit", - "commit": "cedc924307f8d6f0488a1d051020ceb97e76da78", - "auditedOn": "2026-08-12", + "commit": "f7affa991c1720fa4eaba382d51628174516defd", + "auditedOn": "2026-08-13", "docBridge": { "artifact": "docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json", "doctorScore": 100, @@ -30,7 +30,7 @@ }, "attestation": { "sourceMode": "commit", - "contentDigest": "sha256:ee18a9880e9e8020e3cb754678396b7854228323963176e28b4d2e3811481b1b" + "contentDigest": "sha256:a992df46d9e5e4267abcb99edc6059d62b9c887a88c905c21e3fbda2bdb6b5d9" }, "machineSurfaces": { "llmsTxt": "llms.txt", diff --git a/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json b/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json index 5020b2ad..09410c58 100644 --- a/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json +++ b/docs/evidence/ecosystem-documentation-quality/doc-bridge/agentskit.json @@ -1 +1 @@ -{"schemaVersion":1,"protocol":"agentskit.doc-bridge.attestation","productId":"agentskit","repo":"AgentsKit-io/agentskit","commit":"cedc924307f8d6f0488a1d051020ceb97e76da78","sourceMode":"commit","contentDigest":"sha256:ee18a9880e9e8020e3cb754678396b7854228323963176e28b4d2e3811481b1b","command":"pnpm docs:bridge:doctor && pnpm docs:bridge:gate","metrics":{"doctorScore":100,"coverage":{"agent":{"ready":25,"total":25},"human":{"ready":25,"total":25}},"conformance":{"requiredPassed":7,"requiredTotal":7,"requiredExcepted":0,"recommendedPassed":2,"recommendedTotal":2,"recommendedExcepted":0}}} +{"schemaVersion":1,"protocol":"agentskit.doc-bridge.attestation","productId":"agentskit","repo":"AgentsKit-io/agentskit","commit":"f7affa991c1720fa4eaba382d51628174516defd","sourceMode":"commit","contentDigest":"sha256:a992df46d9e5e4267abcb99edc6059d62b9c887a88c905c21e3fbda2bdb6b5d9","command":"pnpm docs:bridge:doctor && pnpm docs:bridge:gate","metrics":{"doctorScore":100,"coverage":{"agent":{"ready":25,"total":25},"human":{"ready":25,"total":25}},"conformance":{"requiredPassed":7,"requiredTotal":7,"requiredExcepted":0,"recommendedPassed":2,"recommendedTotal":2,"recommendedExcepted":0}}}