GovUK.Dfe.AI.Agents.AISearch 0.0.1-prerelease.316

GovUK.Dfe.AI.Agents.AISearch

Gives your GovUK.Dfe.AI.Agents agents evidence from Azure AI Search. Results are numbered, so agents must cite them as [Evidence n].

Set up

dotnet add package GovUK.Dfe.AI.Agents.AISearch

"AiAgents": {
  "AISearch": {
    "Endpoint": "https://<search>.search.windows.net",
    "Indexes": [ { "Name": "ofsted_index", "ContentFields": [ "title", "content" ] } ]
  }
}

builder.Services.AddAgents(builder.Configuration, agents => agents
    .AddAgents(BriefingAgents.All)
    .AddAISearch());

Give the app's identity the Search Index Data Reader role. To use a different identity for search, add AISearch:Authentication, or set one in code with agents.UseAISearchCredential(credential).

Search without agents

An app that only needs search results, e.g. a search page, can add search on its own. It needs no Foundry settings and no agents:

builder.Services.AddAISearch(builder.Configuration, new ManagedIdentityCredential());

It reads the same AiAgents:AISearch section. Pass a credential, or leave it out and set a complete AiAgents:AISearch:Authentication block (TenantId, ClientId, ClientSecret). If you later add agents with agents.AddAISearch(), search is still registered only once.

Use

Inject IContextRetriever, search, and pass the result as evidence:

var evidence = await search.GetContextAsync("ofsted_index", $"Ofsted inspection {urn}", size: 10,
    filter: $"urn eq {urn}", cancellationToken: ct);

var result = await agents.RunAsync(BriefingAgents.Ofsted, "Summarise the latest inspection.", evidence, ct);

Pass the result itself, not evidence.Text, so its citation sources come with it.

• Filter every search to the record you mean, e.g. one school. Relevance alone also returns similarly named ones.
• Filters are escaped for you: write them as interpolated strings, and every {value} is escaped, so a value can't change what the filter matches. A plain or concatenated string won't compile. If you already have an escaped filter (e.g. from SearchFilter.Create), pass it with ODataFilter.Raw(filter).
• Set ContentFields on each index. Otherwise every string field, including ids and URLs, is sent to the model.
• Weak matches are dropped: results scoring below half the top score are removed. Change this with AISearch:MinimumRelevanceFilter (default 0.5).
• Large results: evidence is capped at AISearch:MaxEvidenceCharacters (default 190,000, just under core's 200,000). Whole results are kept, most relevant first, and the rest are left out with a note, so no result is cut mid-way and citations still match. Raise both limits together for a larger model. To fetch less, lower size.

Citations

Agents cite results as [Evidence n]. Each one reaches your app as something a reader can use, with no settings:

• The text is the start of the result itself, on one line and cut at about 80 characters. Square brackets set each citation apart from the answer's own text.
• The link is the first field whose whole value is a full https or http address. That field isn't sent to the model, so it can't write links itself. With ContentFields set, only those fields come back, so include the address field to get links.
• No citations for an agent with RequiredCitations = false: they aren't asked for, and any the model writes are removed.
• After the checks: citations change only once the answer passes, so each refers to real evidence. Validate and run observers still see [Evidence n].
• Your app shows HTML: render the answer as HTML, or as Markdown that allows inline HTML. It's safe: the citation links are the only HTML in an answer, as any the model writes is shown as text.
• Works for RunAsync, RunStreamingAsync and RunParallelAsync (return the search result from resolveEvidence). Evidence joined from several searches keeps [Evidence n], as their numbers would clash.

Better matches: semantic and hybrid search

Keyword search misses documents that use different words, e.g. "safeguarding concerns" and "child protection issues". Set either or both of these on an index:

"Indexes": [ {
  "Name": "ofsted_index",
  "ContentFields": [ "title", "content" ],
  "SemanticConfiguration": "default",
  "VectorFields": [ "contentVector" ]
} ]

Your filter is applied before the vector search, so hybrid results still match only the record you asked about.