Knowledge Base research¶

Career Chat can transfer a company-knowledge question to a dedicated Deep Agent in src/chatbot/agentic/agents/knowledge_base_agent.py. It is a sibling module of the other agents, and a child node of the Career Chat graph. The main supervisor continues to select Career Chat for these questions.

Career Chat selects research only when the answer needs a specific fact about the company or its configured resources. Reflection questions and adaptable coaching suggestions can use the conversation directly, without looking for an internal coaching procedure. An unavailable profile does not create a research requirement. Coaching must not invent personal facts or present general practices as company policies or approved methods. This distinction is enforced through the agent prompt and tool description, without an additional routing model call.

flowchart TD
    A[Guardrails] -->|allow| B[Supervisor]
    B --> C[Career Chat]
    C -->|transfer_to_knowledge_base| D[Knowledge Base Deep Agent]
    D --> E[Search RAG and public pages concurrently]
    E --> D
    D -->|select discovered page or section| W[Read bounded public evidence]
    W --> D
    D -->|supported synthesis| F[Deliver exact answer and end turn]
    D -->|miss or unavailable| G[Career Chat explains and asks one follow-up]

The handoff tool only records a graph transition. It does not run an agent. The Knowledge Base node owns its research, compares evidence and produces one structured KnowledgeAnswer. A supported nonempty answer with valid retrieved source IDs becomes the final assistant message unchanged. There is no additional Career Chat model call after success. Internal source identifiers and filenames are not exposed to the user. Public pages may be cited using retrieved URLs.

A miss returns to Career Chat for an honest explanation and one contextual follow-up. An unavailable source is distinguished from an empty search. Available sources can still support an answer when another source fails, provided the answer acknowledges the limitation. Conflicting sources must be described as conflicting; the model must not silently select a winner or invent missing facts. These semantic requirements are also checked by the evaluation judge.

Research must answer the requested subject and operation: a related process is not sufficient evidence. If a lead is tangential, the agent is instructed to inspect another plausible page or section while the existing budgets permit. It stops as soon as direct evidence is sufficient; no minimum number of reads is required. It must not infer site-wide absence from an irrelevant page, a truncated excerpt or a failed request. Structural source validation checks retrieved citations; semantic relevance remains a model responsibility, evaluated by the judge.

After a tangential page, further exploration requires another reasonably relevant lead for the requested operation. An unvisited link or unused budget alone does not require another read. For reimbursement, a link described only as a course catalogue and enrolment is not automatically relevant; a funding or reimbursement lead is. Neither the agent nor the evaluation judge imposes a minimum page count. Stopping without direct evidence produces an unanswerable result, not a claim that the company has no such policy.

On a retry or correction, both agents use earlier user messages to recover the intended question. Previous assistant claims are not evidence. Knowledge Base uses a self-contained search query for such follow-ups. Questions explaining a documented capability belong here; requests to analyze a specific uploaded document still use Career Chat's document tool.

When correcting an earlier answer, Knowledge Base withdraws unsupported claims without automatically asserting their opposite. It may acknowledge that an earlier requirement was unsupported or absent from the consulted guidance; stating that the requirement is unnecessary needs direct evidence. Supported procedural steps remain clear and direct rather than becoming uncertain merely because another part of the earlier answer was unsupported. The correction is explicit: replacing an incorrect answer with supported steps alone does not withdraw the earlier claim. For example: "My earlier statement about a manager invitation was not supported by the guidance I found. Contact the Service Desk, complete an identity check, and have your second factor reset." This withdraws the unsupported requirement and gives the documented recovery steps without deciding whether an invitation could be required in another context. No fixed apology or wording is required.

The correction rubric evaluates the scope of negative statements. For example, "the documented recovery process does not call for a manager invitation" describes the consulted procedure and is acceptable when that guidance specifies no such step. It is not automatically a company-wide exemption. An unqualified assertion such as "you do not need a manager invitation" still requires direct evidence. Evaluation does not require the exact verb "mention" for a source-scoped statement.

Each turn permits one handoff. A return to Career Chat removes the transfer tool from its offered tools. The next user message resets this bookkeeping and follows the ordinary guardrails and supervisor path. Guardrails and long-term memory do not rerun during internal transfers.

Sources and configuration¶

Before each Career Chat turn, a deterministic check decides whether to expose the handoff. It makes no model, embedding or public-page request:

When RAG is enabled, the check reads at most one chunk identifier in the current tenant store, with a two-second deadline. MongoDB projects only _id; PostgreSQL uses the existing tenant-index prefix and LIMIT 1. No count, vector search or new index is needed. Readiness is refreshed each turn so newly indexed files become available without restarting the application. A storage failure is marked unavailable, not empty; active web sources can still permit research.

Calling the Knowledge Base entrypoint directly with no available source also returns an unanswerable result with empty evidence/source IDs, without invoking its model or embeddings. The usual guardrail, supervisor and Career Chat calls remain. For company-policy questions, Career Chat explains the lack of accessible sources and asks one contextual clarification, without claiming to have searched or inventing a policy. Ordinary career conversations are unaffected.

An active URL is a potential source: an empty or unreachable page can only be discovered during retrieval. That case still permits a handoff and follows the ordinary miss/unavailability path. The readiness check never crawls websites.

File RAG keeps chatbot.rag, its existing MongoDB/PostgreSQL retrieval, cache, embedding selector and five-passage limit. Research never requests a reindex and does not generate an intermediate RAG answer. All currently indexed document sources participate through the existing tenant retrieval index.

Public web is independent of chatbot.rag.enabled. It can supplement files or answer questions when no files are indexed. Configure it in the tenant config_file using the shape in src/templates/config_file.json:

{
  "chatbot": {
    "knowledge_base": {
      "web": {
        "enabled": true,
        "sources": [
          {
            "url": "https://www.example.org/policies/",
            "allowed_path_prefixes": ["/policies"]
          }
        ],
        "follow_links": true,
        "max_depth": 1,
        "max_pages_per_source": 3,
        "max_pages": 8,
        "refresh_interval_seconds": 900
      }
    }
  }
}

Use real public, unauthenticated URLs in place of the example. Disabling web or leaving sources empty makes no HTTP requests. The seed is depth zero. Links and redirects must remain on its exact host and within an allowed path subtree; /policies does not permit /policies-other. Without explicit prefixes the seed's parent directory is used. HTTP sources may upgrade to HTTPS. Once HTTPS is used, same-host HTTP redirects and subsequent links are resolved as HTTPS; the crawler never retries them over HTTP if HTTPS fails. For example, a configured https://www.example.org/docs redirecting to http://www.example.org/docs/ is fetched as https://www.example.org/docs/. This handles reverse proxies that advertise HTTP in a redirect without requiring a configuration update. Trailing slashes are taken from server redirects, never appended blindly to file or page URLs. Other hosts, including a different www hostname, remain outside the source scope. These corrections are request-local and do not rewrite the tenant configuration. Redirect and link validation still applies before every request, including when a cached page established the HTTPS destination.

Only HTTP/HTTPS on standard ports is supported. Credentials, query strings, ambiguous encoded paths and non-public addresses are rejected. DNS is checked at connection time, including every redirected target. Cookies, environment proxies, user credentials and conversation data are never forwarded to websites. A page request contains the configured URL and technical headers only. The crawler does not run JavaScript, log in, submit forms, use a general search engine or fetch arbitrary URLs supplied by the user/model. PDF and other binary web documents are not supported by this path; continue using file RAG for them.

The first search reads only the configured entry pages and returns their allowed links with labels, permitted paths and nearby prose/list/table context (at most 240 characters). Empty or icon-only links and same-page controls are omitted; same-page headings remain accessible through the section index. A later contextual occurrence can enrich a link first seen in a menu. Malformed individual links are ignored without discarding the page's usable content. Before calling read_knowledge_page, the agent is instructed to compare discovered links against the exact subject and requested operation, preferring direct matches over neighboring topics regardless of their position or a generic label. It must copy the page_id from the selected entry, check that the handle and public progress message refer to that same target, and respect the source's remaining page budget. For example, an expense question can select a guide labelled "Overview" using its path and description without fetching preceding menu links. The tool accepts opaque discovered page handles, never arbitrary model-supplied URLs.

Extraction prefers the main article and removes navigation from answer evidence while retaining link labels for discovery. Each read returns at most 6,000 characters, a heading/section index, and a continuation offset when applicable. The agent can read a named section or continue the same page without another HTTP request or RAG search. Links and headings are hints, not proof of the linked content: only delivered excerpts are eligible answer evidence. Anchors select the corresponding heading when present.

Pages are read on demand. Successful extracted pages are cached in process for the configured interval, with tenant and configuration in the key; a restart empties the cache. It holds at most 128 pages. An unavailable refresh never serves expired content. No URL content is added to persistent RAG indexes, and no new background synchronization worker or database index is introduced.

Execution bounds and isolation¶

The first search reads RAG and web entry pages concurrently. A refinement reuses web evidence and can query RAG again. Source work is bounded by 20 seconds; entry page discovery stops after 18 seconds and retains completed pages. Later page reads are serialized within the request and keep the per-request HTTP timeout and overall 45-second research deadline. Pages, including failed attempts, count toward the same per-source and global budgets for the entire run. Repeated reads reuse fetched content; failed pages are not retried during that run. Reading another section does not consume another page attempt. Link depth and page counts are enforced in code, not left to prompt compliance. Tool results expose web_budget: used and remaining page attempts, per-source remaining attempts and remaining explicit reads. Failed attempts consume budget; cached section reads do not consume another page attempt.

The four model invocations include navigation choices and final synthesis. A typical path is discovery, one selected page, an optional targeted section, and the final answer. More complicated exploration can exhaust this budget and must report insufficient evidence honestly. No native provider web-search service or additional classification call is introduced.

Both Career Chat and Knowledge Base use the shared mini profile. Model and reasoning settings come from provider/AIProviders configuration. Deep Agents receives the initialized AIHub model; its SDK defaults do not choose a provider. The SDK's general-purpose subagent, filesystem tools, execution tools and automatic summarization are disabled. Its backend is request-state storage, with no host filesystem or shell access. Research scratch messages and evidence remain outside conversation checkpoints; only the handoff result and final answer join the conversation. Internal model stream tokens are filtered from client SSE events; progress labels, intentional public search comments and the final response remain available. Comments describe the action underway in the resolved locale, are limited to 240 characters and disappear from the frontend at run termination. They are not hidden reasoning, source excerpts or durable history. They use the existing search/navigation tool call, without an extra model call. The final research answer is delivered complete after source validation, unchanged by Career Chat. The public stream nests Knowledge Base under Career Chat and reports document research, public-page consultation, source comparison and answer preparation only when performed. See the streaming contract and frontend migration.

The request owns source tasks and HTTP resources. Cancellation drains child tasks and closes clients. Source errors are isolated so successful siblings remain usable. A synthesis failure or deadline returns an unavailable result to Career Chat rather than exposing raw errors.

Page-failure warnings retain request/client correlation and report the source number, page attempt, stable code, exception error_type, and http_status when available. Codes distinguish redirect_out_of_scope, redirect_limit, redirect_missing_location, invalid_url, non_public_address, http_error, timeout, dns_error, tls_error, network_error, unsupported content type or encoding, oversized pages, and unexpected errors. Logs contain no page URL, response body, headers, or raw exception text. A 503 remains an unavailable source; automatic URL correction does not retry a site that is still preparing its documentation. The chat stream can complete successfully with Career Chat's honest follow-up even when optional knowledge retrieval is unavailable.

Successful searches also log source statuses and evidence counts. Navigation logs report the source ordinal, opaque page/section IDs, a short hash of the target URL, depth, outcome, returned character count, continuation availability and consumed page/read counts. Rejected reads report a controlled reason such as page_limit, read_limit or invalid_section. Research completion logs distinguish the model's declared answerability from structural acceptance and report cited/evidence counts. These logs retain request/client correlation and never include the question, raw URL, page title, retrieved text, or unvalidated model-supplied identifiers. The URL hash permits correlation; it does not disclose the destination or prove relevance.

The pinned SDK introduces transitive LangChain vendor adapters, including Google, but AIHub does not enable a Google provider or send requests through that adapter. Its transitive dependency currently requires the compatible tenacity <9.2 line. See the authoritative dependency list.

Evaluation and rollout¶

The chatbot.knowledge evaluations run the real Deep Agent with frozen RAG rows and HTML pages. They cover RAG-only, web-only, complementary and contradictory sources, linked pages, out-of-scope links, unavailable linked pages and embedded malicious instructions. Career Chat evaluations exercise the real transfer graph, successful delivery, miss/unavailability follow-ups, English/French behavior, and direct responses with disabled or empty RAG and no active URLs. Technical tests verify cancellation, budgets, source isolation, provider protocols and turn reset separately. HTTP tests also cover slash redirects, HTTPS upgrades and preservation, unsafe destinations, redirect limits, cache behavior and sanitized failure diagnostics. These transport corrections preserve the existing semantic rubrics for web-only research, linked pages, out-of-scope links and unavailable linked pages; they require no new judge-only scenarios or model/profile change.

No live website or paid provider call is needed for the technical suites. Live quality/cost calibration is a separate authorized campaign; existing cost observations for the former RAG synthesis are historical evidence, not a measured cost for this new research graph. See AI evaluations.

Navigation evaluations include an ambiguous tenth link under a two-page budget, a useful section beyond the initial excerpt, complementary RAG and linked web evidence, and an unavailable linked page. Additional cases distinguish reimbursement from course enrolment, handle truly absent information, recover access-recovery questions from retries/corrections, and explain document-delivery capabilities without analyzing a personal document. English/French cold starts use English sources. Out-of-scope and prompt-injection cases retain their original expectations. Offline graph replays verify execution contracts; they do not establish the quality of live model choices.