---
name: agent-seek
description: >
  Use Agent Seek for ranked web URLs/snippets (You.com + Jev).
  Default mode=deep (Stage A survivor fetch, cap 12; not a full-web crawl).
  Signals include prompt_injection (UI: Injection risk).
  Hard gates (order): subject_match → is_republisher → prompt_injection
  (0.55, fail-open). Do not ask Agent Seek to write answers.
---

# Agent Seek — search with taste

Agent Seek is a prototype search service: **You.com** discovers candidates, **Jev**
cascade-ranks them, and you get a tight scored JSON list (or a Google-simple UI).

**Live base URL:** `https://agentseek.dev`

(Alternate host still available: `https://gitmaxd-agent-seek.exe.xyz`.)

Product docs: `/docs` · Agent Seek API: `/developers` · OpenAPI Swagger: `/api/docs` · Schema: `/openapi.json`

## Install

Use this skill when you land on Agent Seek (or need ranked web sources) and want
the efficient path: **skill → `/llms.txt` → `/auth.md` → MCP or REST**.

Stable skill URLs (same file):

- `https://agentseek.dev/.well-known/agent-skills/agent-seek/SKILL.md`
- `https://agentseek.dev/skills/agent-seek/SKILL.md`
- Index: `https://agentseek.dev/.well-known/agent-skills/index.json`

**Cursor:** save this file as `.cursor/skills/agent-seek/SKILL.md` (project) or
`~/.cursor/skills/agent-seek/SKILL.md` (user). Or discover via the agent-skills index.

**Other coding agents:** download `SKILL.md` from the well-known URL, or link it
from the index.

Then: read `/llms.txt` → authenticate via `/auth.md` → call `POST /v1/search`
or MCP (`POST /mcp`, server card `/.well-known/mcp/server-card.json`).

## Sandbox (zero-auth)

Inspect the Agent Seek `SearchResponse` shape before you authenticate:

```http
GET /v1/sandbox
```

No API key. No You.com or Jev call. Also: `GET /health`, `GET /openapi.json`, `GET /v1`.

The live host does **not** mint self-serve API keys. Paths after sandbox:

1. OAuth 2.0 (`POST /oauth2/register` or `POST /agent/identity`) — see `/auth.md`
2. Local `AGENT_SEEK_API_KEY` in `.env` for self-host
3. Optional operator-issued live key (email is not a gate for local or OAuth)

## When to use

- You need **relevant web sources** (title, URL, snippet, score, signals) for research/RAG.
- Raw SERP top-10 looks SEO-spammy; you want judgment-ranked keepers.
- You do **not** need Agent Seek to generate an answer or chat.

## When not to use

- More than **100** candidates (hard cap).
- Replacing a generative answer engine.
- Expecting unbounded full-site crawl — `mode=deep` fetches **Stage A survivors only** (cap 12).

## Auth & base URL

Live prototype: `https://agentseek.dev` (alternate: `https://gitmaxd-agent-seek.exe.xyz`)  
Local default: `http://127.0.0.1:8787`

Env: **`AGENT_SEEK_API_KEY`** (and related `AGENT_SEEK_*`). No legacy product-name env vars.

OAuth 2.0 (`search:read`) is first-class — walkthrough `/auth.md`, metadata
`/.well-known/oauth-authorization-server` and
`/.well-known/oauth-protected-resource`. MCP Streamable HTTP: `POST /mcp`
(server card `/.well-known/mcp/server-card.json`). The API key remains a valid
alternate Bearer token.

```http
Authorization: Bearer $AGENT_SEEK_API_KEY
Content-Type: application/json
```

Public agent files on the same host: `/llms.txt`, `/agents.md`, `/auth.md`, `/openapi.json`, `/.well-known/agent-skills/index.json`.

## UI defaults vs API knobs

| | UI | API |
| --- | --- | --- |
| Mode | fixed `deep` | `mode=deep` (default) \| `snip` |
| k / max | fixed defaults | `k` 1–25, `max_candidates` 1–100 |
| Cache | normal | `nocache=true` forces discover miss |
| Auth | injected same-origin key | `Authorization: Bearer $AGENT_SEEK_API_KEY` |

Humans: open `/`, Enter to search; relevance meter + hover signal breakdown.

## `POST /v1/search`

**Request**

```json
{
  "q": "Introducing System One Models Jev",
  "k": 10,
  "max_candidates": 50,
  "mode": "deep",
  "nocache": false
}
```

| Field | Rules |
| --- | --- |
| `q` | required, 1–500 chars |
| `k` | 1–25, default 10 |
| `max_candidates` | 1–100, default 50 (clamped to 100) |
| `mode` | `deep` (default) or `snip` |
| `nocache` | optional bool; `true` forces discover cache miss (ranking still runs) |

**Modes**

- **`deep`** (default): Stage A on snips → prune survivors → fetch main page text for top survivors (**cap 12**; concurrency / timeout / bytes limits) → Stage B Jev on fuller text. Not a full-web crawl. Per-URL fetch failure falls back to snippet. Expect higher latency; response may include `meta.fetch_ms`.
- **`snip`**: Stage A + Stage B on title / URL / snippet (cheaper / lower latency). Opt in with `mode=snip`.

**Response (200)**

```json
{
  "results": [
    {
      "rank": 1,
      "url": "https://…",
      "title": "…",
      "snippet": "…",
      "score": 0.91,
      "flags": ["on_topic"],
      "raw_rank": 4,
      "provider": "you.com",
      "signals": {
        "answerability": 0.9,
        "authority": 0.8,
        "on_topic": 0.95,
        "states_sought_fact": 0.7,
        "subject_match": 0.9,
        "spam": 0.1,
        "prompt_injection": 0.12
      }
    }
  ],
  "meta": {
    "q": "…",
    "candidates_in": 50,
    "kept": 10,
    "latency_ms": 842,
    "mode": "deep",
    "provider": "you.com",
    "agent_seek_version": "0.1.39",
    "ranking": "jev",
    "fetch_ms": null,
    "cache_hit": false,
    "cache_scope": "discover"
  },
  "raw_results": []
}
```

### `signals` (on each result)

Optional 0–1 floats from the cascade (may be omitted on fallback paths):

| Key | Meaning |
| --- | --- |
| `answerability` | How well the page answers the query |
| `authority` | Source authority / first-party quality |
| `on_topic` | Topical relevance |
| `states_sought_fact` | Whether the sought fact is stated |
| `subject_match` | Entity / subject identity match |
| `spam` | Spamminess (higher = worse) |
| `prompt_injection` | Injection / instruction-hijack risk (higher = worse). UI label: **Injection risk** |

`meta.ranking`: `jev` | `raw` | `raw_fallback` (Jev failed → You.com order, still 200).

`meta.fetch_ms`: wall time for deep page fetches when `mode=deep` (null/omitted for snip).

`meta.cache_scope`: `"discover"` when a discover cache is used or attempted (even on miss). Ranking always recomputes; discover may cache unless `nocache=true`.

`raw_results` holds the same candidate set in discover order for A/B.

## Interpreting scores & flags

- **score** ∈ [0, 1] from Stage B answerability+fact composite with gated authority preference (and host boost only if authority Noul missing), then spam soft-demote.
- **flags**: `on_topic`, `spam_low`, `high_relevance`, `weak_signal`.
- Prefer high score + `on_topic`.
- **`spam_low` soft-demotes** (score × 0.75) — not a hard filter; UI chip stays warn-style.
- Prefer `raw_rank` only when comparing against unranked SERP.
- Use **signals** for hover/debug and agent routing — do not treat a single signal as the full score.

## Hard gates (summary)

Order (fail-open if a parse is missing; 0.55 thresholds): **subject_match → is_republisher → prompt_injection**.

- **subject_match**: Stage B `{cid}__subject_match` — parsed < 0.55 excluded from `results` (still in `raw_results`); missing parse fails open.
- **republisher**: Stage B `{cid}__is_republisher` — parsed ≥ 0.55 excluded; judges role (mirror/viewer vs canonical), not a domain deny list.
- **prompt_injection**: Stage B `{cid}__prompt_injection` — parsed ≥ 0.55 excluded; judges injection/hijack intent aimed at agents/LLMs (not educational pages about the attack); not a keyword deny list. UI label: **Injection risk**.
- If hard gates empty the scored list, pre-gate top-k is restored (`gates_relaxed`).

## Curl example (default deep)

```bash
export AGENT_SEEK_API_KEY=…   # from .env
curl -sS -X POST "http://127.0.0.1:8787/v1/search" \
  -H "Authorization: Bearer $AGENT_SEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"Introducing System One Models Jev","k":10,"max_candidates":50,"mode":"deep"}'
```

## Curl example (opt-in snip)

```bash
curl -sS -X POST "http://127.0.0.1:8787/v1/search" \
  -H "Authorization: Bearer $AGENT_SEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q":"when were langchain deep agents released","k":10,"max_candidates":50,"mode":"snip"}'
```

Also: `GET /v1/search?q=…&mode=deep` and `GET /health` → `{"ok":true,"version":"0.1.39"}`.

Human product page: `/docs`. OpenAPI: `/api/docs`. Auth walkthrough: `/auth.md`.

## Host prompt snippets

- “Use Agent Seek to search for X; return the top URLs with scores; then summarize yourself.”
- “Do not ask Agent Seek to write the answer.”
- “If meta.ranking is raw_fallback, note that ranking degraded to raw You.com order.”
- “Default is mode=deep (Stage A survivor fetch, cap 12). Pass mode=snip when latency/cost matter more than page text.”