Ga naar inhoud

Gestructureerde antwoorden, artefacten en pagina's

Een modelaanroep geeft standaard tekst terug. Veel toepassingen hebben meer nodig: een formulier dat je interface zelf invult, een grafiek die een tool maakte, een rapport dat een klant in de browser opent en dat bij elke nieuwe versie hetzelfde adres houdt. Core heeft daar drie onderdelen voor: gestructureerde uitvoer, artefacten en pagina's.

Je wilt Gebruik Wat je terugkrijgt
velden die je eigen code leest en opmaakt gestructureerde uitvoer JSON die aan jouw schema voldoet, in het antwoord zelf
een bestand dat een agent tijdens een beurt maakt een artefact een verwijzing in het antwoord; de bytes download je apart
een HTML-rapport dat mensen in een browser openen een pagina, of een HTML-bestand dat je toont een weergaveadres dat je opent, of een deellink voor iemand buiten je organisatie

Gestructureerde uitvoer

Je geeft in het veld text van een beurt een JSON Schema mee, en het model antwoordt met JSON die eraan voldoet: {"format": {"type": "json_schema", "name": "...", "schema": {...}}}. Je interface leest de velden en toont ze op haar eigen manier, als een tabel, een kaart of een ingevuld formulier, in plaats van tekst te ontleden.

Ondersteunt het model een schema zelf, dan gaat het schema naar de leverancier. Anders vraagt Core het model om JSON volgens het schema en controleert het antwoord zelf. Voldoet dat antwoord niet, dan mislukt de beurt met invalid_structured_output en krijg je geen half antwoord. Het schema bepaalt alleen het eindantwoord; toolaanroepen onderweg vallen erbuiten.

Gebruik gestructureerde uitvoer wanneer je code iets met het antwoord doet: een veld opslaan, een beslissing nemen, een scherm vullen. Voor een antwoord dat een persoon alleen leest, is tekst genoeg.

Artefacten

Een artefact is een bestand dat een tool tijdens een beurt maakt: een grafiek uit een script, een afbeelding van een beeldmodel, of een document dat het model schreef met de tool builtin__create_artifact, zoals een HTML-rapport, Markdown of CSV. Het model krijgt een verwijzing naar het bestand, niet de bytes. Elk artefact noemt het antwoord, de toolaanroep en de tool waaruit het ontstond, zodat je applicatie de bestanden van één antwoord kan opvragen en downloaden. Het begint met de labels van dat antwoord.

Een artefact is een opgeslagen bestand zoals een upload. Het blijft staan zolang het bewaarvenster van je organisatie dat toelaat, tenzij je het markeert om te bewaren. Een artefact downloaden vraagt de capabilities artifacts en files, en een regel in de policy die downloaden toestaat. Zo kies je per sleutel of wat een tool maakte de organisatie mag verlaten.

Pagina's

Een opgeslagen HTML-bestand, een upload of een artefact, kun je in een browser tonen in plaats van het te downloaden. Er zijn twee adressen:

  • een weergaveadres, enkele minuten geldig, voor jezelf of de gebruiker van je applicatie. Je opent het in een eigen tabblad of venster. Het in een frame binnen je eigen product tonen kan alleen als je installatie de origin van je product toestaat, met de instelling artifacts_view_frame_ancestors. Standaard staat die geen enkele origin toe; je operator zet hem;
  • een deellink, dagen geldig, voor iemand buiten je organisatie zonder account. Die vraagt een regel in de policy die delen met een link toestaat, en je kunt hem op elk moment intrekken.

Wie een adres heeft, opent het bestand zonder sleutel. Behandel een adres daarom als een geheim. Een model krijgt nooit een adres: je eigen code vraagt het aan.

Een rapport wordt bijgewerkt, en elke versie is een nieuw bestand. Een pagina is een vaste naam boven die versies. Publiceer een nieuwe versie, en elk weergaveadres en elke deellink van de pagina toont die, op het adres dat mensen al hebben. Een vorige versie zet je terug met één aanroep.

Hoe het samenhangt

  • Gestructureerde uitvoer is een veld van een modelaanroep en werkt met elke agent.
  • Artefacten komen uit tools; de tool die een document schrijft, zet je per sleutel aan.
  • Artefacten en pagina's zijn opgeslagen bestanden van je organisatie, vallen onder haar bewaartermijn en onder de policy van de sleutel. Een artefact dat een beurt voor een persoon maakte, is van die persoon.

Verder