Pijplijnen voor agentgeheugen

Een geheugenpijplijn bouwt langetermijngeheugen op uit eerdere gesprekken van je agent. Het leest gespreksgeschiedenis uit een sessieopslag en distilleert langetermijnherinneringen, zoals feiten, voorkeuren en procedures, in een geheugenopslag. Je agent haalt die herinneringen vervolgens weer op in latere gesprekken, net zoals hij herinneringen oproept die hij zelf heeft opgeslagen.

Een agent die herinneringen opslaat tijdens een gesprek schrijft ze één gesprek tegelijk, met alleen de context van dat gesprek. In veel gesprekken verzamelt zijn geheugen overlappende en tegenstrijdige vermeldingen, en feiten die de agent niet eraan dacht op te slaan, bereiken het geheugen niet. Een geheugenpijplijn werkt achteraf, met alle gesprekken en bestaand geheugen van een gebruiker beschikbaar, zodat het kan vastleggen wat de agent gemist heeft en het geheugen kan consolideren.

Gebruik een geheugenpijplijn wanneer je wilt:

• Bouw langetermijngeheugen op uit gesprekken zonder geheugenschrijftools aan je agent toe te voegen.
• Vul het geheugen aan vanuit de gespreksgeschiedenis die een sessieopslag al bevat.
• Houd het geheugen georganiseerd door overlappende vermeldingen samen te voegen en oversized items te splitsen.

Je kunt een geheugenpijplijn alleen gebruiken of samen met geheugentools die je agent oproept tijdens een gesprek.

Requirements

• Een sessie-opslag waar de gesprekken van je agent worden opgeslagen, en een memory store om herinneringen naar te schrijven.
• Toegang tot beide opslagruimten voor de identiteit die de pijplijn aanmaakt, inclusief de toestemming om tabellen te maken in de database van de geheugenopslag. Pipeline-runs worden uitgevoerd met die identiteit.
• Toestemming om het model dat de pijplijn gebruikt voor destillatie te bevragen. Zonder dit falen de runs van de pipeline.
• Om de CLI te gebruiken, installeer databricks-agentbricks 0.6.0 en hoger. Je kunt de REST API ook direct aanroepen vanuit elke taal.

Hoe geheugenpijplijnen werken

Een memory pipeline is een agentgeheugenresource die één sessieopslag verbindt met één geheugenopslag. Het heeft niets te maken met Lakeflow-pijpleidingen. Een sessieopslag kan meer dan één geheugenopslag voeden, maar elk paar sessieopslag en geheugenopslag kan slechts één pijplijn hebben.

• Modelaanroepen via Unity Gateway: De pijplijn roept zijn destillatiemodel aan via Unity Gateway.
• Je keuze van model: Je kiest het model wanneer je een pipeline aanmaakt en kunt het later wijzigen. Als je er geen kiest, gebruikt de pijplijn een standaardmodel.
• Handmatige of geplande runs op serverless compute: Je start zelf runs, of configureert de pipeline om ongeveer elke 24 uur volgens een schema te draaien. Hoe dan ook, elke run wordt uitgevoerd als een taak op serverless compute, met de identiteit waarmee de pipeline is gemaakt.

Elke run van de pipeline verwerkt elke actor in de sessieopslag apart:

1. Distill: De pipeline leest de nieuwe gesprekken van de actor en gebruikt een LLM om daaruit duurzame feiten te halen.
2. Samenvoegen: De pijplijn dedupliceert de nieuwe feiten en voegt ze samen in topic-gebaseerde geheugenvermeldingen onder dezelfde actor_id in de geheugenopslag.
3. Behouden: De pijplijn reorganiseert het geheugen van de actor. Het voegt overlapende vermeldingen samen en splitst vermeldingen die te groot worden.

Runs van de geheugenpijplijn houden een checkpoint voor elke actor-ID bij. Een run verwerkt alle sessies van een actor sinds de laatste succesvolle run van die actor, dus de eerste run verwerkt de volledige geschiedenis van de actor. Als een run faalt voor één actor, gaat deze verder met de andere actors, en de volgende run probeert de mislukte actor opnieuw vanaf zijn checkpoint.

Het actor_id verbindt de twee winkels. Een pijplijn verwerkt alleen actoren die sessies in de sessieopslag hebben, en schrijft de herinneringen van elke actor onder dezelfde actor_id die de sessies van de actor gebruiken. Standaard draait een pipeline alleen wanneer je een run start. Je kunt het ook gepland uitvoeren.

Wat een pijplijn bewaart

Een pipeline haalt individuele, duurzame feiten uit gesprekken. Het is ontworpen om ervoor te zorgen dat het volgende behouden blijft:

• Feiten die de gebruiker expliciet aangeeft en voorkeuren die hij of zij uitdrukt, zonder verder af te leiden dan wat er in het gesprek staat.
• Correcties en expliciete feedback, zoals welke bron gebruikt moet worden voor de omzetcijfers.
• Duurzame domeinkennis, zoals gezaghebbende bronnen, metriekdefinities, terminologie en teamconventies, evenals workflows en lopende projecten.

Het is ontworpen om het volgende over te slaan:

• Waarden van live bronnen die in de loop van de tijd veranderen, zoals het huidige aantal rijen in een tabel. In plaats daarvan registreert het hoe de waarde gevonden of berekend moet worden.
• Details die de agent met zijn tools kan opzoeken, zoals het schema van een tabel.
• Geheimen, zoals wachtwoorden, API-sleutels en tokens.

Get started

Deze voorbeelden creëren een geheugenpijplijn voor de sessie- en geheugenopslag van een supportagent, starten een run en controleren het resultaat. Identificeer elke winkel aan de hand van zijn ID, de identifier die je koos bij het aanmaken van de store, of met de naam van de resource, zoals memory-stores/support-agent-memory. Kies de klant die bij jouw project past.

Agent Bricks

De Agent Bricks CLI gebruikt je opgeslagen Databricks CLI-profiel om te authenticeren.

1. Installeer de Agent Bricks CLI, of upgrade deze naar 0.6.0 en hoger:

   pip install --upgrade databricks-agentbricks
   

2. Maak een pipeline die de support-agent-sessions sessieopslag samenvat in de support-agent-memory geheugenopslag. --model is een optie. Als je het weglaat, gebruikt de pipeline een standaardmodel:

   agentbricks memory pipeline create \
     --session-store support-agent-sessions \
     --memory-store support-agent-memory \
     --model system.ai.claude-sonnet-5
   

   Het commando geeft de resourcenaam van de pijplijn terug, in de vorm memory-pipelines/<pipeline-id>.

3. Start een run van de pipeline:

   agentbricks memory pipeline run <pipeline-id>
   

   Het commando geeft de resourcenaam van de run terug, in de vorm memory-pipelines/<pipeline-id>/runs/<run-id>, en de RUNNING-status ervan.

4. De CLI rapporteert het resultaat van een run niet. Om dit te controleren, stel je DATABRICKS_HOST in op de hostnaam van je workspace, genereer je een OAuth-token en roep je de REST API aan:

   export DATABRICKS_TOKEN=$(databricks auth token --profile <profile> | jq -r .access_token)
   curl "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>/runs/<run-id>" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}"
   

REST API

De CLI roept de REST API aan onder /api/2.0/agents/memory-pipelines. Roep het rechtstreeks aan vanuit welke taal dan ook.

1. Genereer een OAuth-token met de Databricks CLI:

   databricks auth login --host ${DATABRICKS_HOST}
   export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)
   

2. Maak een pipeline die herinneringen uit support-agent-sessions distilleert en opslaat in support-agent-memory. dreamer_policy.model is een optie. Als je het weglaat, gebruikt de pipeline een standaardmodel:

   curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
     -d '{"session_store": "support-agent-sessions", "memory_store": "support-agent-memory", "dreamer_policy": {"model": "system.ai.claude-sonnet-5"}}'
   

   Het veld name van de respons bevat de resourcenaam van de pijplijn, in de vorm memory-pipelines/<pipeline-id>.

3. Start een run van de pipeline:

   curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>/run" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
     -d '{}'
   

   Het veld name van het antwoord bevat de resourcenaam van de run, in de vorm memory-pipelines/<pipeline-id>/runs/<run-id>.

4. Bekijk het resultaat van de run:

   curl "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>/runs/<run-id>" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}"
   

Nadat een run succesvol is voltooid, kan je agent de nieuwe herinneringen oproepen met de lijst- en zoekoperaties van de geheugenopslag. Zie Agentgeheugen.

Pijplijnuitvoeringen controleren

De state van een run is een van de volgende:

Stuur de destillatie met instructies

Instructies geven aan wat de pipeline moet bewaren en hoe deze moet worden georganiseerd. De pipeline past ze in elke fase toe. Gebruik ze voor advies op hoog niveau, zoals:

• De onderwerpen waarop je je moet richten, zoals klantvoorkeuren en accountdetails.
• De inhoud om over te slaan, zoals eenmalige stappen voor probleemoplossing.
• De paden waaronder de vermeldingen worden geordend.

Zonder layout-instructies volgt de pipeline de lay-out van de bestaande vermeldingen van de winkel, of leidt een topic-based layout af wanneer de winkel leeg is. Het hernoemt bestaande vermeldingen niet om bij een nieuwe lay-out te passen. Om een specifieke invoer te wijzigen, bewerk deze met de update-operatie van de geheugenopslag in plaats van met instructies.

Je kunt instructies instellen wanneer je een pipeline aanmaakt en die later wijzigen. De volgende run gebruikt de nieuwe instructies.

Agent Bricks

Om instructies in te stellen wanneer je een pipeline maakt, geef je --instructions op:

agentbricks memory pipeline create \
  --session-store support-agent-sessions \
  --memory-store support-agent-memory \
  --instructions "Focus on durable customer preferences and account details. Ignore one-off troubleshooting steps. Organize entries under /preferences/ and /account/."

Om langere instructies uit een UTF-8-bestand te laden, geef je --instructions @<path-to-file> in plaats daarvan door.

Om de instructies van een bestaande pijplijn te wijzigen, voer je het volgende uit:

agentbricks memory pipeline update <pipeline-id> \
  --instructions "Keep only durable customer preferences."

REST API

In de REST API bevat het dreamer_policy object van een pijplijn zijn destillatie-instellingen: instructions, trigger, en model. Om instructies in te stellen wanneer je een pipeline aanmaakt, neem je ze op in dreamer_policy.instructions:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"session_store": "support-agent-sessions", "memory_store": "support-agent-memory", "dreamer_policy": {"instructions": "Focus on durable customer preferences and account details. Ignore one-off troubleshooting steps. Organize entries under /preferences/ and /account/."}}'

Om de instructies van een bestaande pijplijn te wijzigen, update dreamer_policy.instructions:

curl -X PATCH "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>?update_mask=dreamer_policy.instructions" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"dreamer_policy": {"instructions": "Keep only durable customer preferences."}}'

Voer een pipeline uit volgens een schema

Een geplande pipeline draait automatisch ongeveer elke 24 uur. Je kunt de trigger instellen wanneer je een pipeline aanmaakt, of de trigger later aanpassen. De planner bepaalt wanneer de eerste geplande run begint. Om bestaande gesprekken direct samen te vatten, start handmatig een run.

Agent Bricks

Om een geplande pijplijn te maken, geef --trigger scheduled door. De standaardwaarde is --trigger manual:

agentbricks memory pipeline create \
  --session-store support-agent-sessions \
  --memory-store support-agent-memory \
  --trigger scheduled

Om de trigger van een bestaande pijplijn te wijzigen, voer je het volgende uit:

agentbricks memory pipeline update <pipeline-id> --trigger scheduled

Als je een geplande pipeline hebt, kun je deze pauzeren:

agentbricks memory pipeline pause <pipeline-id>

Om geplande runs opnieuw te starten, hervat je ze:

agentbricks memory pipeline resume <pipeline-id>

REST API

Om een geplande pijplijn te maken, stel dreamer_policy.trigger in op SCHEDULED:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"session_store": "support-agent-sessions", "memory_store": "support-agent-memory", "dreamer_policy": {"trigger": "SCHEDULED"}}'

Om de trigger van een bestaande pijplijn te wijzigen, update dreamer_policy.trigger naar SCHEDULED of MANUAL_ONLY:

curl -X PATCH "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>?update_mask=dreamer_policy.trigger" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"dreamer_policy": {"trigger": "SCHEDULED"}}'

Je kunt ook handmatig een run van een geplande pipeline starten, zolang er geen andere run gaande is.

Pijplijnen beheren

De volgende commando's geven een lijst van, inspecteren, updaten en verwijderen pijplijnen. Elk CLI-commando accepteert ofwel de pijplijn-ID of de volledige memory-pipelines/<pipeline-id> resourcenaam.

Als je geen weergavenaam instelt, krijgt de pipeline er een op basis van de namen van de sessie- en geheugenstore. Om een pijplijn terug te schakelen naar het standaardmodel, werkt u het model bij naar een lege waarde, zoals --model "". Model- en instructiewijzigingen gelden voor de volgende run.

Het verwijderen van een pipeline verwijdert de onderliggende taak en stopt toekomstige runs. Een run die al bezig is, wordt voltooid. Geheugenvermeldingen die de pipeline al heeft geschreven, blijven in de geheugenopslag.

Limitations

• De sessieopslag en geheugenopslag liggen vast wanneer je een pipeline aanmaakt. Om een van beide te wijzigen, verwijder je de pijplijn en maak je een nieuwe aan. Een nieuwe pipeline hergebruikt de checkpoints van de oude pipeline niet, dus de eerste run verwerkt de volledige geschiedenis van elke actor, zelfs voor hetzelfde paar stores.
• Als een pipeline al dezelfde sessieopslag en geheugenopslag verbindt, faalt het aanmaken van een nieuwe met ALREADY_EXISTS.
• Een pijplijn heeft tegelijk slechts één actieve run. Een run starten terwijl een andere run bezig is, mislukt met een ABORTED foutmelding.
• Geplande pipelines draaien ongeveer elke 24 uur. Je kunt geen ander interval of cron-schema instellen.
• Een pipeline verwerkt alleen actoren die sessies in de sessieopslag hebben. Geheugenvermeldingen voor actoren zonder sessies blijven ongewijzigd.
• Als de sessieopslag meer dan ongeveer 1.200 actors met UUID-actor-ID's heeft, mislukt de uitvoering. De limiet is 48 KiB aan geserialiseerde actor-ID's, dus kortere IDs maken meer actoren mogelijk.

Aanvullende bronnen

• Agentgeheugen
• Agentsessies
• Agentgeheugen en sessies
• Agent API-referentie