# web-agentic — complete library (all audiences)

_Generated whole-library download. See `agent-manifest.json` → `library` for discovery._

## Table of contents

- **Overview** (`00-overview`, developers)

---

# Overview — developers

# Overview — Developers

**Audience:** Engineers installing and integrating `web-agentic`.  
**Related:** root [README.md](../../../README.md) · Memorix product docs via `npx memorix-docs`

---

## 1. What it is

`web-agentic` fetches any URL as clean Markdown (Playwright), classifies the page, and parses it into typed JSON. It also searches the public web through Serper.dev and can explicitly fetch selected result pages.

Surfaces share one SDK (`WebAgentClient`):

- CLI (`webagent`)
- REST host (`@x12i/web-agentic-api`, bin `web-agentic-api`)
- MCP server (`search_web`, `fetch_url`, …)
- Playground UI (endpoint dropdown → tool inputs)

---

## 2. Install

```bash
pnpm add @x12i/sdk
# HTTP host in another monorepo:
pnpm add @x12i/web-agentic-api
npx playwright install chromium
```

Node.js 20+. Full SERP types: `import { … } from "@x12i/search"`.

---

## 3. Web search

Requires `SERPER_API_KEY` (or lowercase `serper_api_key` in `.env`). See `.env.example`.

| Surface | How |
|---|---|
| SDK | `client.search()`, `client.searchAndFetch()`, `client.fetchSearchResults()` |
| CLI | `webagent search "…"`, `webagent search-and-fetch "…" --top 2` |
| API | `POST /search`, `POST /search-and-fetch` |
| MCP | tools `search_web`, `search_and_fetch_web` |
| Playground | Endpoint **Search** or **Search and fetch** |

```bash
node packages/cli/dist/index.js search "apple inc" --limit 5
node packages/cli/dist/index.js search-and-fetch "apple inc" --top 2 --json
```

`search` discovers URLs. `searchAndFetch` / `fetchSearchResults` explicitly fetch pages — search never auto-fetches.

---

## 4. HTTP process compliance

Aligned with `@x12i/memorix-docs` use case **`http-process-compliance`** (Building Services → HTTP process compliance):

| Contract | This repo |
|---|---|
| Base kit | `@x12i/core-service` (`attachCoreFastify`) |
| Ports | `@x12i/ports-manager` zone **`web-agentic-tools`** → API **7080**, UI **7081** |
| Health | `GET /health` → `{ ok, service: "@x12i/web-agentic-api", capabilities.search }` |
| Live | `GET /_live` via `@x12i/api-live-view` |
| Correlation | `x-correlation-id` |

Do **not** default to avoided ports `3000` / `5173`. Override with `WEB_AGENTIC_API_PORT` / `WEB_AGENTIC_UI_PORT` if needed (still in-zone).

```bash
npx memorix-docs use-case http-process-compliance
npx x12i-ports zone web-agentic-tools
pnpm ui   # API :7080 + playground :7081
```

---

## 5. Host in another monorepo

```bash
pnpm add @x12i/web-agentic-api
npx playwright install chromium
npx web-agentic-api
```

```ts
import { buildApp, startWebAgentApi } from "@x12i/web-agentic-api";

await startWebAgentApi(); // zone :7080, /health, /_live

// Or embed:
const app = buildApp({ registerHealth: false });
```

---

## 6. Docify / memorix-docs pins

DevDependencies pin:

- `@x12i/memorix-docs` — product books / use cases for agents
- `@x12i/docify-core` / `docify-sdk` / `docify-web` / `docify-export` / `docify-theme` / `docify-render`
- `@x12i/ports-manager` / `@x12i/core-service` — HTTP compliance
- `@x12i/web-agentic-api-docs` — this product’s knowledge package

> Note: the `@x12i/docify` CLI tarball currently publishes broken `file:../` sibling deps on npm. Prefer `memorix-docs` + working packages: `@x12i/docify-export@1.4.1` (1.5+/1.6 also ship broken `file:` deps), plus `docify-core` / `docify-sdk` / `docify-web` / `docify-theme` / `docify-render`. Use `pnpm docs:bundle` / `pnpm docs:publish`.