Geef een agent kennis uit eigen bedrijfsinformatie¶

Aan het eind van deze tutorial beantwoordt de agent support vragen uit het handboek van Noordwind, met een bronvermelding bij het antwoord. Je hebt het handboek in een collectie gezet, er een index over gemaakt en de agent een zoektool gegeven.

De weg van document naar antwoord heeft vier schakels. Een collectie bewaart de documenten. Een index maakt ze doorzoekbaar. Een zoektool geeft een zoekopdracht over die index een naam. De agent krijgt die tool en beslist per vraag of hij zoekt.

1. Maak een collectie¶

curl -s -X POST "$CORE_URL/knowledge/collections" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"name": "handboek", "description": "Handboek klantenservice van Noordwind"}'

Het antwoord is 201 met de collectie; het id begint met col_.

export COLLECTION_ID=col_2Pf7...

Je maakt een eigen collectie per soort inhoud, omdat de policy van een sleutel collecties op naam toestaat of weigert. Het handboek en bijvoorbeeld de contracten van Noordwind horen daarom niet in dezelfde collectie.

2. Maak een index over de collectie¶

curl -s -X POST "$CORE_URL/knowledge/indexes" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"name": "handboek", "collection_ids": [{"collection_id": "'"$COLLECTION_ID"'"}]}'

export INDEX_ID=idx_8Bd3...

De schrijfwijze "'"$COLLECTION_ID"'" zet de waarde van de variabele tussen aanhalingstekens in de JSON. Je kunt het id er ook gewoon in typen.

Je maakt de index vóór je documenten toevoegt. Een bron die je daarna in de collectie zet, wordt vanzelf verwerkt. Bronnen die er al stonden toen je de collectie koppelde, verwerkt Core pas nadat je POST /knowledge/indexes/$INDEX_ID/reindex stuurt.

Zonder verdere velden gebruikt de index de standaardpipeline en het standaard embedding-model van je installatie. Dat is voor een handboek met tekst genoeg.

3. Zet het handboek erin¶

Tekst die je al als string hebt, stuur je als bron van de soort text:

curl -s -X POST "$CORE_URL/knowledge/collections/$COLLECTION_ID/sources" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"kind": "text", "title": "Retourbeleid",
         "text": "Een klant kan een bestelling binnen 30 dagen na levering retourneren. Het product moet ongebruikt zijn en in de originele verpakking zitten. De klant betaalt de verzendkosten van de retour, behalve bij een defect product. Het aankoopbedrag wordt binnen 5 werkdagen na ontvangst teruggestort."}'

Een bestand, zoals een PDF of een Word-document, stuur je in één aanroep:

curl -s -X POST "$CORE_URL/knowledge/collections/$COLLECTION_ID/sources/upload" \
    -H "Authorization: Bearer $CORE_KEY" \
    -F "file=@handboek.pdf"

Elke bron is één document en hoort bij precies één collectie. Staat het handboek van je klant in SharePoint, Google Drive of een ander systeem, dan kan de collectie het daar zelf ophalen (Een collectie synchroniseren).

4. Wacht tot de bron is verwerkt¶

curl -s "$CORE_URL/knowledge/indexes/$INDEX_ID/sources" \
    -H "Authorization: Bearer $CORE_KEY"

Verwerken gebeurt op de achtergrond. Herhaal de aanroep tot elke bron ready is (ingekort):

{
  "items": [
    { "source_id": "src_9Qd2...", "title": "Retourbeleid", "status": "ready", "chunk_count": 1 }
  ]
}

De statussen zijn queued, processing, ready en failed. Bij failed staat er een vaste error_code bij.

5. Doorzoek de index zelf¶

curl -s -X POST "$CORE_URL/knowledge/indexes/$INDEX_ID/search" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"query": "hoe lang mag een klant retourneren", "top_k": 3}'

{
  "items": [
    { "chunk_id": "chk_0KQ...", "source_id": "src_9Qd2...", "score": 0.83,
      "text": "Een klant kan een bestelling binnen 30 dagen na levering retourneren. ..." }
  ]
}

De waarde van score is een voorbeeld. Deze stap is er om te scheiden wat je test: vindt een zoekopdracht de passage hier niet, dan ligt het aan de inhoud of de index en niet aan de agent.

6. Maak een zoekpipeline¶

Een zoektool draait een versie van een pipeline van jezelf. Je kopieert daarvoor een ingebouwd sjabloon en vult in welke index het doorzoekt:

curl -s -X POST "$CORE_URL/knowledge/pipelines/from-template" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"template": "retrieval/hybrid", "name": "handboek-zoeken",
         "sources": {"index": "'"$INDEX_ID"'"}}'

Je krijgt de pipeline terug met versie 1.

export PIPELINE_ID=pip_...

retrieval/hybrid zoekt op trefwoord en op betekenis en voegt beide ranglijsten samen. Dat vindt zowel een exacte term als een vraag in andere woorden. Een sjabloon kun je niet rechtstreeks op een tool noemen, omdat het pas iets bereikt nadat jij de index hebt ingevuld.

7. Registreer de zoektool¶

curl -s -X POST "$CORE_URL/knowledge/retrieval-tools" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"name": "handboek",
         "description": "Doorzoekt het handboek klantenservice van Noordwind: retouren, levering, betaling en garantie.",
         "pipeline": {"pipeline_id": "'"$PIPELINE_ID"'", "version": 1}}'

Het model ziet deze tool als knowledge__handboek. De omschrijving is wat het model leest om te bepalen wanneer het zoekt, dus noem de onderwerpen die in het handboek staan. De tool staat vast op versie 1 van de pipeline: een latere versie verandert niets tot je de tool erop zet.

In de console maak je de collectie, de index en de zoektool onder Kennis (Collecties, Indexen in de console, Zoektools).

8. Geef de agent de zoektool¶

curl -s -X POST "$CORE_URL/agents/$AGENT_ID/versions" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"model": "<een model-id>",
         "instructions": "Je bent de supportassistent van Noordwind. Antwoord kort en in het Nederlands. Zoek bij elke vraag over beleid eerst in het handboek en verwijs naar de passage met [n]. Staat het antwoord er niet in, zeg dat dan.",
         "temperature": 0.2,
         "tools": [{"type": "tool", "name": "knowledge__handboek"}]}'

Dit is een nieuwe versie van de agent, dus je stuurt de hele definitie mee. De instructie zegt wanneer de agent moet zoeken en wat hij doet als het handboek geen antwoord geeft. Zonder die zin vult een model een gat eerder met een eigen vermoeden.

9. Stel een vraag¶

curl -s -X POST "$CORE_URL/responses" \
    -H "Authorization: Bearer $CORE_KEY" -H "Content-Type: application/json" \
    -d '{"agent": {"id": "support"},
         "input": "Hoe lang heb ik om een bestelling terug te sturen, en wie betaalt de verzending?"}'

Controleer of het werkt¶

Het antwoord (ingekort) bevat twee items in output:

{
  "status": "completed",
  "output": [
    { "type": "mcp_call", "name": "knowledge__handboek", "server_label": "knowledge",
      "status": "completed" },
    { "type": "message", "role": "assistant",
      "content": [{
        "type": "output_text",
        "text": "Je kunt een bestelling binnen 30 dagen na levering terugsturen [1]. ...",
        "annotations": [
          { "type": "file_citation", "file_id": "chk_0KQ...", "filename": "Retourbeleid", "index": 71 }
        ]
      }] }
  ]
}

• Het item mcp_call met name: knowledge__handboek bewijst dat de agent heeft gezocht. Zo toont een antwoord elke tool die Core voor je uitvoerde.
• De file_citation met filename: Retourbeleid bewijst dat het antwoord op jouw document steunt. index is de positie van [1] in de tekst; de waarde hier is een voorbeeld.

Een file_citation staat er alleen als het model zelf [n] in zijn antwoord schrijft. Daarom vraagt de instructie uit stap 8 daarom. Zie je wel een mcp_call maar geen annotatie, dan heeft de agent gezocht en de markering weggelaten; het antwoord steunt dan nog steeds op wat de tool teruggaf. Maak de zin over [n] in de instructie dan dwingender.

Ontbreekt de mcp_call, dan heeft het model niet gezocht. Lees dan de trace van de beurt: GET /responses/{id}/trace en daarna GET /traces/{call_id} laten onder document.interpretation.tools zien of de tool is aangeboden (Een trace lezen).

Als het niet werkt¶

Verder¶

• Kennis: de onderdelen en wanneer je een index of een graaf kiest.
• Kennis via de API: brontypen, gekoppelde bronnen, filters en eigen pipelines.
• Waar de bronnen van een antwoord staan: de annotaties tonen in je eigen interface.
• Bouwen voor personen: bepalen welke bronnen één persoon terugvindt.

Volgende tutorial: Laat een agent een actie uitvoeren met een tool.