Agentize Websites

Agentize Websites

Use Agentize only inside a website repository controlled by the publisher. It turns owner-declared public content or a shared-access intranet corpus into an authoritative semantic index; it is not a command for crawling someone else's domain.

Ground the integration

Before changing anything, inspect the target repository for its package manager, Node version, framework, build scripts, existing agentize.config.*, and intended content sources. Determine whether the interface is public or protected. For protected interfaces, confirm that every admitted caller may read every indexed resource.

Require Node.js 22 or newer. Follow the target repository's package-manager convention; examples below may use pnpm, but do not introduce pnpm into an npm or Yarn project solely for Agentize.

Check whether the @nicolasakf/agentize package and matching @nicolasakf/agentize-* packages are available from the configured registry or already linked in the workspace. Agentize's packages are versioned together. In a development checkout, prefer workspace linking; do not pack only the @nicolasakf/agentize CLI because its internal workspace dependencies are also required.

Install and configure

When the user authorizes installation:

1. Add @nicolasakf/agentize as a production dependency because the deployed /agents/* handler needs its runtime.
2. Run agentize init from the website root. Preserve existing files; if configuration or a route handler already exists, inspect and update it instead of overwriting it.
3. Replace the generated site placeholder with the canonical production origin, name, and a useful description.
4. Declare only authoritative sources. Prefer Markdown/static output adapters for file-backed content and defineResources for CMS or database entities. A protected index must exclude resources with narrower permissions.
5. Run agentize check and resolve errors. Treat privacy warnings and uncovered authenticated routes as blockers until reviewed.
6. Run agentize build; the first build downloads the pinned local embedding model, while later builds reuse content-addressed embeddings.

Read references/configuration.md when creating or editing configuration, adding a Vercel, Next.js, or sidecar deployment, validating endpoints, or troubleshooting a build/runtime failure.

Deployment

Choose the integration that matches the website:

• Next.js App Router: import runtime helpers from @nicolasakf/agentize/next, keep the catch-all route on runtime = "nodejs", wrap Next config with withAgentize, and build Agentize before next build.
• Static sites on Vercel: add a Node function for the Agentize runtime, include .agentize/output/** in that function, and place /agents rewrites before any extensionless-page or SPA fallback.
• Other Node stacks: run agentize serve beside the application and route the owner's /agents/* path to it through the existing reverse proxy.

Protected deployments must gate /agents and every path below it. Pass the host's request gate as authorizeRequest, or set trustUpstreamProtection only when framework middleware or a reverse proxy already enforces access. The standalone CLI uses --trust-upstream-protection. Protected bundles refuse to start without one of these safeguards.

Do not target an edge-only or static runtime for v0.2: semantic query embedding and the local vector index require server-side Node compute. Deploy .agentize/output/ with the server artifact, while keeping .agentize/cache/ out of source control and production artifacts. Treat protected bundles as private application data.

For a Vercel-hosted static site, read references/configuration.md. Prefer a production-target candidate with domain assignment skipped, verify the exact deployment, and only then promote it to the production domain.

Verification

Verify observable behavior after installation:

• GET /agents returns protocol version 0.2, an access mode, and same-origin endpoint paths.
• GET /agents/index exposes collections rather than dumping every route.
• A paraphrased POST /agents/search query returns the intended resource first.
• GET /agents/resources/:id returns JSON and text/markdown when requested.
• Excluded, draft, admin, account, checkout, authentication, and internal API content is absent from index and search results. Public sources also exclude noindex; protected sources include it only through includeNoindex: true.
• A protected deployment denies every Agentize endpoint without host credentials and completes discovery, search, and retrieval with valid credentials.
• Rebuilding unchanged content reports embedding cache hits.

Do not claim success from a build alone. Exercise the deployed handler or standalone server with at least one real semantic query.

Boundaries

• Never add arbitrary remote-URL crawling as an installation shortcut.
• Never place a resource in a protected shared corpus unless every admitted caller may read it.
• Do not switch to hosted embeddings or transmit site content/query text to a third party; v0.2 uses the pinned local model.
• Do not advertise /llms.txt unless the publisher actually maintains one and configures its path.
• If the request is explanatory only, report the commands and configuration without modifying the repository.