Contesto

Gestione intelligente del contesto per conversazioni lunghe con compressione automatica

Panoramica#

La compressione automatica del contesto in Astreus fornisce una gestione intelligente della conversazione, occupandosi automaticamente delle cronologie lunghe. Il sistema comprime i messaggi più vecchi preservando le informazioni importanti, garantendo che gli agent possano mantenere conversazioni lunghe e coerenti senza superare i limiti di token del modello.

Utilizzo di base#

Abilita la compressione automatica del contesto per ottenere una gestione automatica della conversazione:

typescript
import { Agent } from '@astreus-ai/astreus';

// Create an agent with auto context compression enabled
const agent = await Agent.create({
  name: 'ContextAwareAgent',
  model: 'gpt-6-astra',
  autoContextCompression: true  // Enable smart context management
});

// Long conversations are automatically managed
for (let i = 1; i <= 50; i++) {
  const response = await agent.ask(`Tell me fact #${i} about TypeScript`);
  console.log(`Fact ${i}:`, response);
}

// Agent can still reference early conversation through compressed context
const summary = await agent.ask('What was the first fact you told me?');
console.log(summary); // System retrieves from compressed context

Esempio con Task#

La compressione automatica del contesto funziona sia con conversazioni dirette sia con i task:

typescript
const agent = await Agent.create({
  name: 'ResearchAgent',
  model: 'gpt-6-astra',
  autoContextCompression: true,
  memory: true // Often used together with memory
});

// Create multiple related tasks
const task1 = await agent.createTask({
  prompt: "Research the latest trends in AI development"
});

const result1 = await agent.executeTask(task1.id);

const task2 = await agent.createTask({
  prompt: "Based on the research, what are the key opportunities?"
});

const result2 = await agent.executeTask(task2.id);
// Task can reference previous context even if it was compressed

La compressione automatica del contesto garantisce che gli agent possano gestire conversazioni e task di qualsiasi lunghezza mantenendo la coerenza e rimanendo entro i limiti di token.

Opzioni di configurazione#

Puoi personalizzare il comportamento della compressione automatica del contesto con questi parametri:

typescript
const agent = await Agent.create({
  name: 'CustomContextAgent',
  model: 'gpt-6-astra',
  autoContextCompression: true,
  
  // Context compression configuration
  maxContextLength: 4000,           // Trigger compression at 4000 tokens
  preserveLastN: 5,                 // Keep last 5 messages uncompressed
  compressionRatio: 0.4,            // Target 40% size reduction
  compressionStrategy: 'hybrid',    // Use hybrid compression strategy
  
  memory: true,
});

Parametri di configurazione#

ParametroTipoPredefinitoDescrizione
autoContextCompressionbooleanfalseAbilita la compressione automatica del contesto
maxContextLengthnumber8000Limite di token prima che scatti la compressione
preserveLastNnumber3Numero di messaggi recenti da mantenere non compressi
compressionRationumber0.3Rapporto di compressione target (0.1 = riduzione del 90%)
compressionStrategystring'hybrid'Algoritmo di compressione da usare

Matematica della compressione#

Il rapporto di compressione determina di quanto viene ridotto il contesto:

Compression Ratio=compressed tokensoriginal tokens\text{Compression Ratio} = \frac{\text{compressed tokens}}{\text{original tokens}}

Ad esempio, con un rapporto di 0.3:

  • Originale: 1000 token
  • Compresso: 300 token
  • Riduzione: 70%

La percentuale di riduzione dei token viene calcolata come: Reduction %=(1−ratio)×100%\text{Reduction \%} = (1 - \text{ratio}) \times 100\%

Con compressionRatio = 0.3: Reduction=(1−0.3)×100%=70%\text{Reduction} = (1 - 0.3) \times 100\% = 70\%

Strategie di compressione#

Scegli la strategia di compressione più adatta al tuo caso d'uso:

'summarize' - Riepilogo del testo#

  • Ideale per: conversazioni generali, Q&A, discussioni
  • Come funziona: crea riepiloghi concisi di gruppi di messaggi
  • Pro: mantiene il flusso del contesto, adatto alla maggior parte dei casi d'uso
  • Contro: può perdere dettagli specifici
typescript
const agent = await Agent.create({
  name: 'SummarizingAgent',
  autoContextCompression: true,
  compressionStrategy: 'summarize',
  preserveLastN: 4
});

'selective' - Selezione dei messaggi importanti#

  • Ideale per: conversazioni orientate ai task, discussioni tecniche
  • Come funziona: usa l'AI per identificare e preservare i messaggi importanti
  • Pro: mantiene intatte le informazioni cruciali
  • Contro: può richiedere più risorse
typescript
const agent = await Agent.create({
  name: 'SelectiveAgent',
  autoContextCompression: true,
  compressionStrategy: 'selective',
  preserveLastN: 3
});

'hybrid' - Approccio combinato (consigliato)#

  • Ideale per: la maggior parte delle applicazioni, approccio bilanciato
  • Come funziona: combina riepilogo e preservazione selettiva
  • Pro: equilibrio tra preservazione del contesto ed efficienza
  • Contro: nessuno significativo
typescript
const agent = await Agent.create({
  name: 'HybridAgent',
  autoContextCompression: true,
  compressionStrategy: 'hybrid', // Default and recommended
});

Utilizzo avanzato#

Impostazioni di compressione personalizzate per caso d'uso#

Conversazioni ad alta frequenza#

Per chatbot o agent interattivi con molti messaggi brevi:

typescript
const chatbot = await Agent.create({
  name: 'Chatbot',
  autoContextCompression: true,
  maxContextLength: 2000,     // Compress more frequently
  preserveLastN: 8,           // Keep more recent messages
  compressionRatio: 0.5,      // More aggressive compression
  compressionStrategy: 'summarize'
});

Creazione di contenuti lunghi#

Per agent che lavorano con contenuti dettagliati:

typescript
const writer = await Agent.create({
  name: 'ContentWriter',
  autoContextCompression: true,
  maxContextLength: 12000,    // Allow longer context
  preserveLastN: 3,           // Keep recent context tight
  compressionRatio: 0.2,      // Gentle compression
  compressionStrategy: 'selective'
});

Documentazione tecnica#

Per agent che gestiscono discussioni tecniche complesse:

typescript
const techAgent = await Agent.create({
  name: 'TechnicalAssistant',
  autoContextCompression: true,
  maxContextLength: 6000,
  preserveLastN: 5,           
  compressionRatio: 0.3,      
  compressionStrategy: 'hybrid' // Best for mixed content
});

Come funziona la compressione del contesto#

Processo di compressione#

Monitoraggio dei token: l'agent monitora continuamente il conteggio totale dei token nella conversazione

Punto di attivazione: quando i token superano maxContextLength, viene attivata la compressione

Preservazione dei messaggi: gli ultimi preserveLastN messaggi vengono mantenuti non compressi

Analisi del contenuto: i messaggi più vecchi vengono analizzati in base alla strategia scelta

Compressione: i messaggi vengono compressi in riepiloghi o selezioni

Aggiornamento del contesto: il contesto compresso sostituisce i messaggi originali

Cosa viene preservato#

  • System prompt: sempre preservati
  • Messaggi recenti: gli ultimi N messaggi in base a preserveLastN
  • Contesto importante: informazioni chiave identificate dalla strategia di compressione
  • Riepiloghi compressi: versioni condensate delle conversazioni più vecchie

Esempio di flusso di compressione#

typescript
// Before compression (1200 tokens)
[
  { role: 'user', content: 'Tell me about TypeScript' },
  { role: 'assistant', content: 'TypeScript is...' },
  { role: 'user', content: 'What about interfaces?' },
  { role: 'assistant', content: 'Interfaces in TypeScript...' },
  { role: 'user', content: 'Show me an example' },
  { role: 'assistant', content: 'Here\'s an example...' },
]

// After compression (400 tokens)
[
  { role: 'system', content: '[Compressed] User asked about TypeScript basics, interfaces, and examples. Assistant provided comprehensive explanations...' },
  { role: 'user', content: 'Show me an example' },
  { role: 'assistant', content: 'Here\'s an example...' },
]

Monitoraggio e debug#

Informazioni sulla finestra di contesto#

Ottieni dettagli sullo stato attuale del contesto:

typescript
const contextWindow = agent.getContextWindow();

console.log({
  messageCount: contextWindow.messages.length,
  totalTokens: contextWindow.totalTokens,
  maxTokens: contextWindow.maxTokens,
  utilization: `${contextWindow.utilizationPercentage.toFixed(1)}%`
});

// Check if compression occurred
const hasCompression = contextWindow.messages.some(
  msg => msg.metadata?.type === 'summary'
);
console.log('Context compressed:', hasCompression);

Analisi del contesto#

Analizza il contesto per individuare opportunità di ottimizzazione:

typescript
const analysis = agent.analyzeContext();

console.log({
  compressionNeeded: analysis.compressionNeeded,
  averageTokensPerMessage: analysis.averageTokensPerMessage,
  suggestedCompressionRatio: analysis.suggestedCompressionRatio
});

Tipi di risposta#

I metodi di gestione del contesto restituiscono oggetti dettagliati per monitorare e controllare il contesto della conversazione.

Risposta della finestra di contesto#

Ottieni la finestra di contesto corrente con le metriche di utilizzo:

typescript
const window = agent.getContextWindow();

// Response structure:
{
  messages: [
    {
      role: "user",
      content: "How do I use TypeScript?",
      timestamp: Date('2024-01-15T10:00:00Z'),
      tokens: 8
    },
    {
      role: "assistant",
      content: "TypeScript is a typed superset of JavaScript that compiles to plain JavaScript...",
      timestamp: Date('2024-01-15T10:00:05Z'),
      tokens: 50
    }
    // ... more messages
  ],
  totalTokens: 3500,
  maxTokens: 8000,
  utilizationPercentage: 43.75
}

Risposta dell'analisi del contesto#

Analizza l'utilizzo attuale del contesto e le necessità di compressione:

typescript
const analysis = agent.analyzeContext();

// Response structure:
{
  totalTokens: 6500,
  messageCount: 15,
  averageTokensPerMessage: 433,
  contextUtilization: 0.8125,              // 81.25% of max context used
  compressionNeeded: true,
  suggestedCompressionRatio: 0.5           // Suggest 50% compression
}

Risposta del risultato di compressione#

Comprimi il contesto e ottieni metriche di compressione dettagliate:

typescript
const compression = await agent.compressContext();

// Response structure:
{
  success: true,
  compressedMessages: [
    {
      role: "system",
      content: "Summary: User asked about TypeScript features. Discussed types, interfaces, and generics...",
      timestamp: Date('2024-01-15T10:05:00Z'),
      tokens: 35
    },
    {
      role: "user",
      content: "Can you explain decorators?",
      timestamp: Date('2024-01-15T10:10:00Z'),
      tokens: 8
    }
    // ... compressed messages (8 instead of 15)
  ],
  tokensReduced: 3250,                     // Tokens saved
  compressionRatio: 0.5,                   // 50% reduction achieved
  strategy: "summarize"                    // Strategy used
}

// On failure:
{
  success: false,
  compressedMessages: [],
  tokensReduced: 0,
  compressionRatio: 0,
  error: "Compression failed: Minimum context threshold not reached"
}

Risposta del riepilogo del contesto#

Genera un riepilogo della conversazione basato sull'AI:

typescript
const summary = await agent.generateContextSummary();

// Response structure:
{
  mainTopics: [
    "TypeScript development",
    "API design patterns",
    "Testing strategies"
  ],
  keyEntities: [
    "Express.js",
    "Jest",
    "PostgreSQL",
    "Docker"
  ],
  conversationFlow: "Discussion started with TypeScript setup and configuration. Moved to API design patterns using Express.js. Covered database integration with PostgreSQL. Concluded with comprehensive testing strategies using Jest and continuous integration.",
  importantFacts: [
    "User prefers functional programming style",
    "Project deadline is March 15th, 2024",
    "Must support Node.js 18+",
    "Team size is 5 developers"
  ],
  actionItems: [
    "Set up Jest test framework with coverage reporting",
    "Create API documentation using OpenAPI/Swagger",
    "Configure Docker containers for development environment",
    "Implement CI/CD pipeline with GitHub Actions"
  ]
}

Risposta di Get Context Messages#

Recupera tutti i messaggi di contesto come array:

typescript
const messages = agent.getContext();
// OR
const messages = agent.getContextMessages();

// Response structure:
[
  {
    role: "user",
    content: "How do I use async/await?",
    timestamp: Date('2024-01-15T09:30:00Z'),
    tokens: 10
  },
  {
    role: "assistant",
    content: "Async/await is syntactic sugar for promises...",
    timestamp: Date('2024-01-15T09:30:15Z'),
    tokens: 85
  }
  // ... more messages
]

Risposta di Export Context#

L'esportazione del contesto restituisce una stringa JSON:

typescript
const exported = agent.exportContext();

// Response: JSON string
'{"messages":[{"role":"user","content":"...","timestamp":"2024-01-15T10:00:00.000Z","tokens":10},...],"metadata":{"exportedAt":"2024-01-15T11:00:00.000Z","totalTokens":3500}}'

Risposta di Import/Clear Context#

Le operazioni di import e clear restituiscono void:

typescript
// Import context
agent.importContext(jsonString);
// Returns: void

// Clear context
agent.clearContext();
// Returns: void