Graph

Workflow-Orchestrierung mit Abhängigkeitsverwaltung und paralleler Ausführung

Übersicht#

Das Graph-System ermöglicht dir, komplexe Workflows zu erstellen, indem du Tasks und Agenten mit Abhängigkeiten, Bedingungen und parallelen Ausführungsfunktionen verbindest. Es bietet eine visuelle und programmatische Möglichkeit, mehrstufige Prozesse zu orchestrieren, Verzweigungslogik zu handhaben und mehrere zusammenarbeitende Agenten zu koordinieren.

Einen Graphen erstellen#

Graphen bestehen aus Nodes (Tasks oder Agenten) und Edges (Verbindungen zwischen ihnen):

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

// Create a workflow graph with agent reference
const agent = await Agent.create({
  name: 'ContentAgent',
  model: 'gpt-6-astra'
});

const graph = new Graph({
  name: 'content-creation-pipeline',
  description: 'Research and write technical content'
}, agent);  // Pass agent as second parameter

// Add task nodes
const researchNodeId = graph.addTaskNode({
  prompt: 'Research the latest TypeScript features and summarize key findings',
  model: 'gpt-6-astra',
  priority: 10,
  metadata: { type: 'research' }
});

const writeNodeId = graph.addTaskNode({
  prompt: 'Write a comprehensive blog post based on the research findings',
  model: 'gpt-6-astra',
  dependencies: [researchNodeId],  // Depends on research completion
  priority: 5,
  metadata: { type: 'writing' }
});

// Execute the graph
const results = await graph.run();

console.log('Success:', results.success);
console.log('Completed nodes:', results.completedNodes);
console.log('Failed nodes:', results.failedNodes);
console.log('Duration:', results.duration, 'ms');
console.log('Results:', results.results);

Graph-Ausführungsablauf#

Node-Auflösung#

Der Graph analysiert alle Nodes und ihre Abhängigkeiten, um die Ausführungsreihenfolge zu bestimmen.

Parallele Ausführung#

Unabhängige Nodes laufen für optimale Performance gleichzeitig.

Warten auf Abhängigkeiten#

Abhängige Nodes warten darauf, dass ihre Voraussetzungen abgeschlossen sind, bevor sie starten.

Ergebnissammlung#

Alle Node-Ausgaben werden gesammelt und im Endergebnis verfügbar gemacht.

Fortgeschrittenes Beispiel#

Hier ist ein komplexer Workflow mit Abhängigkeiten, paralleler Ausführung und Fehlerbehandlung:

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

// Create workflow graph with default agent
const agent = await Agent.create({
  name: 'OptimizationAgent',
  model: 'gpt-6-astra'
});

const graph = new Graph({
  name: 'code-optimization-pipeline',
  description: 'Analyze and optimize codebase',
  maxConcurrency: 3,   // Allow 3 parallel nodes
  timeout: 300000,     // 5 minute timeout
  retryAttempts: 2     // Retry failed nodes twice
}, agent);  // Pass agent as second parameter

// Add task nodes with proper configuration
const analysisNodeId = graph.addTaskNode({
  prompt: 'Analyze the codebase for performance issues and categorize them by severity',
  model: 'gpt-6-astra',
  priority: 10,  // High priority
  metadata: { step: 'analysis', category: 'review' }
});

const optimizationNodeId = graph.addTaskNode({
  prompt: 'Based on the analysis, implement performance optimizations',
  model: 'gpt-6-astra',
  dependencies: [analysisNodeId],  // Depends on analysis
  priority: 8,
  metadata: { step: 'optimization', category: 'implementation' }
});

const testNodeId = graph.addTaskNode({
  prompt: 'Run performance tests and validate the optimizations',
  model: 'gpt-6-astra',
  dependencies: [optimizationNodeId],  // Depends on optimization
  priority: 6,
  stream: true,  // Enable streaming for real-time feedback
  metadata: { step: 'testing', category: 'validation' }
});

const documentationNodeId = graph.addTaskNode({
  prompt: 'Document all changes and performance improvements',
  model: 'gpt-6-astra',
  dependencies: [analysisNodeId],  // Can run parallel to optimization
  priority: 5,  // Lower priority
  metadata: { step: 'documentation', category: 'docs' }
});

// Add edges (optional, as dependencies already create edges)
graph.addEdge(analysisNodeId, optimizationNodeId);
graph.addEdge(analysisNodeId, documentationNodeId);
graph.addEdge(optimizationNodeId, testNodeId);

// Execute the graph
const results = await graph.run();

console.log('Pipeline results:', results);
console.log('Completed nodes:', results.completedNodes);
console.log('Failed nodes:', results.failedNodes);
console.log('Duration:', results.duration, 'ms');

// Access individual node results
Object.entries(results.results).forEach(([nodeId, result]) => {
  console.log(`Node ${nodeId}:`, result);
});

// Check for errors
if (results.errors && Object.keys(results.errors).length > 0) {
  console.log('Errors:', results.errors);
}

Graph-Konfiguration#

Graphen unterstützen verschiedene Konfigurationsoptionen:

typescript
interface GraphConfig {
  id?: string;                 // Optional graph ID (UUID)
  name: string;                // Graph name (required)
  description?: string;        // Graph description
  maxConcurrency?: number;     // Max parallel execution (default: 1)
  timeout?: number;            // Execution timeout in ms
  retryAttempts?: number;      // Retry attempts for failed nodes
  autoLink?: boolean;          // Automatically link nodes based on dependencies
  maxContextTokens?: number;   // Maximum context tokens for the graph
  contextWarningThreshold?: number; // Warning threshold for context usage (0-1, e.g., 0.8 = 80%)
  subAgentNodeTimeout?: number;     // Extended timeout for sub-agent nodes (default: 5 minutes)
  metadata?: MetadataObject;   // Custom metadata
  subAgentAware?: boolean;                           // Enable sub-agent awareness and optimization
  optimizeSubAgentUsage?: boolean;                   // Optimize sub-agent delegation patterns
  subAgentCoordination?: 'parallel' | 'sequential' | 'adaptive'; // Default sub-agent coordination
}

// Note: The default agent is passed as the second parameter to the constructor:
// new Graph(config, agent)
// The graph's defaultAgentId is automatically set from the agent's ID.

// Example with full configuration including sub-agent support
const graph = new Graph({
  name: 'advanced-pipeline',
  description: 'Complex workflow with error handling and sub-agent coordination',
  maxConcurrency: 5,
  timeout: 600000,  // 10 minutes
  retryAttempts: 3,
  subAgentAware: true,
  optimizeSubAgentUsage: true,
  subAgentCoordination: 'adaptive',
  metadata: { project: 'automation', version: '1.0' }
}, agent);  // Agent passed as second parameter

Node-Typen und Optionen#

Task-Nodes#

typescript
interface AddTaskNodeOptions {
  name?: string;               // Node name for easy referencing
  prompt: string;              // Task prompt (required)
  model?: string;              // Override model for this task
  agentId?: string;            // Override default agent (UUID)
  stream?: boolean;            // Enable streaming for this task
  schedule?: string;           // Simple schedule string (e.g., 'daily@09:00', 'after:5s')
  dependencies?: string[];     // Node IDs this task depends on
  dependsOn?: string[];        // Node names this task depends on (easier than IDs)
  priority?: number;           // Execution priority (higher = earlier)
  metadata?: MetadataObject;   // Custom metadata
  useSubAgents?: boolean;                        // Force enable/disable sub-agent usage for this task
  subAgentDelegation?: 'auto' | 'manual' | 'sequential'; // Sub-agent delegation strategy
  subAgentCoordination?: 'parallel' | 'sequential';      // Sub-agent coordination pattern
}

Agent-Nodes#

typescript
interface AddAgentNodeOptions {
  agentId: string;             // Agent ID (required, UUID)
  dependencies?: string[];     // Node IDs this agent depends on
  priority?: number;           // Execution priority
  metadata?: MetadataObject;   // Custom metadata
}

Sub-Agent-Konfigurationsoptionen#

Bei der Konfiguration von Graphen mit Sub-Agent-Unterstützung hast du umfassende Kontrolle über Delegation und Koordination:

Sub-Agent-Konfiguration auf Graph-Ebene#

  • subAgentAware: Aktiviert die automatische Erkennung und Optimierung von Sub-Agent-Möglichkeiten im gesamten Graphen
  • optimizeSubAgentUsage: Aktiviert Echtzeit-Leistungsüberwachung und automatische Strategieanpassung für bessere Effizienz
  • subAgentCoordination: Legt das Standard-Koordinationsmuster fest:
    • 'parallel': Sub-Agents arbeiten gleichzeitig über verschiedene Nodes hinweg
    • 'sequential': Sub-Agents arbeiten in Abhängigkeitsreihenfolge und geben Kontext zwischen Ausführungen weiter
    • 'adaptive': Wählt dynamisch das beste Koordinationsmuster basierend auf Aufgabenkomplexität und Abhängigkeiten

Sub-Agent-Konfiguration auf Node-Ebene#

Jeder Task-Node kann Graph-Ebenen-Einstellungen mit spezifischem Sub-Agent-Verhalten überschreiben:

  • useSubAgents: Erzwingt das Aktivieren oder Deaktivieren der Sub-Agent-Delegation für bestimmte Nodes
  • subAgentDelegation: Steuert, wie Aufgaben auf Node-Ebene an Sub-Agents verteilt werden
  • subAgentCoordination: Überschreibt das Standard-Koordinationsmuster des Graphen für bestimmte Nodes

Erweiterter Graph-Workflow mit Sub-Agents#

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

// Create specialized sub-agents
const researcher = await Agent.create({
  name: 'DataResearcher',
  systemPrompt: 'You specialize in gathering and analyzing data from multiple sources.'
});

const analyst = await Agent.create({
  name: 'TechnicalAnalyst', 
  systemPrompt: 'You provide technical insights and recommendations.'
});

const writer = await Agent.create({
  name: 'TechnicalWriter',
  systemPrompt: 'You create clear, comprehensive technical documentation.'
});

// Main coordinator with sub-agents
const coordinator = await Agent.create({
  name: 'ProjectCoordinator',
  systemPrompt: 'You orchestrate complex projects using specialized team members.',
  subAgents: [researcher, analyst, writer]
});

// Create sub-agent optimized graph
// Note: defaultAgentId is automatically set from the coordinator agent passed as second parameter
const projectGraph = new Graph({
  name: 'Technical Documentation Pipeline',
  description: 'Automated technical documentation creation with specialized agents',
  maxConcurrency: 3,
  subAgentAware: true,
  optimizeSubAgentUsage: true,
  subAgentCoordination: 'adaptive'
}, coordinator);  // The coordinator's ID becomes the graph's defaultAgentId

// Research phase with automatic sub-agent delegation
const researchNode = projectGraph.addTaskNode({
  name: 'Market Research',
  prompt: 'Research current trends in cloud computing and serverless architecture',
  useSubAgents: true,
  subAgentDelegation: 'auto',
  priority: 10,
  metadata: { phase: 'research', category: 'data-gathering' }
});

// Analysis phase with sequential sub-agent coordination
const analysisNode = projectGraph.addTaskNode({
  name: 'Technical Analysis',
  prompt: 'Analyze research findings and identify key technical patterns',
  dependencies: [researchNode],
  useSubAgents: true,
  subAgentDelegation: 'auto',
  subAgentCoordination: 'sequential',
  priority: 8,
  metadata: { phase: 'analysis', category: 'insights' }
});

// Documentation phase with parallel sub-agent work
const docNode = projectGraph.addTaskNode({
  name: 'Documentation Creation',
  prompt: 'Create comprehensive technical documentation and executive summary',
  dependencies: [analysisNode],
  useSubAgents: true,
  subAgentDelegation: 'manual',
  subAgentCoordination: 'parallel',
  priority: 6,
  metadata: { phase: 'documentation', category: 'deliverables' }
});

// Execute the graph
const result = await projectGraph.run();

console.log('Pipeline completed:', result.success);
console.log('Node results:', result.results);

Antworttypen#

Die Graph-Ausführung gibt umfassende Ergebnisse zurück, einschließlich Node-Resultaten, Nutzungsstatistiken und Leistungsmetriken.

Graph-Ausführungsergebnis#

Die Methode graph.run() gibt ein detailliertes GraphExecutionResult zurück:

typescript
const result = await graph.run({ timeout: 60000 });

// Response structure:
{
  graph: {
    id: "graph-uuid-123",
    defaultAgentId: "agent-uuid",  // Set from the agent passed to constructor
    config: {
      name: "code-optimization-pipeline",
      description: "Analyze and optimize codebase",
      maxConcurrency: 3,
      timeout: 300000,
      retryAttempts: 2
    },
    nodes: [ /* GraphNode[] */ ],
    edges: [ /* GraphEdge[] */ ],
    status: "completed",  // 'idle' | 'running' | 'completed' | 'failed' | 'paused'
    startedAt: Date('2024-01-15T10:00:00Z'),
    completedAt: Date('2024-01-15T10:12:30Z'),
    executionLog: [ /* GraphExecutionLogEntry[] */ ],
    usage: { /* GraphUsage */ },
    createdAt: Date('2024-01-15T09:55:00Z'),
    updatedAt: Date('2024-01-15T10:12:30Z')
  },
  success: true,                // Overall success status
  completedNodes: 5,            // Number of successfully completed nodes
  failedNodes: 0,               // Number of failed nodes
  duration: 12500,              // Total execution time in milliseconds
  results: {
    "node_abc12345-...": "Analysis complete: Found 15 performance issues categorized by severity...",
    "node_def67890-...": "Optimization implemented: 40% performance improvement...",
    "node_ghi11111-...": "Tests passed: All optimizations validated...",
    "node_jkl22222-...": "Documentation updated with all changes...",
    "node_mno33333-...": "Final review completed..."
  },
  errors: {},  // Empty if all nodes succeeded
  usage: {
    totalPromptTokens: 1500,
    totalCompletionTokens: 3000,
    totalTokens: 4500,
    totalContextTokens: 500,
    totalCost: 0.045,
    nodeUsages: {
      "node_abc12345-...": {
        promptTokens: 200,
        completionTokens: 400,
        totalTokens: 600,
        contextTokens: 100,
        model: "gpt-6-astra",
        cost: 0.012
      },
      "node_def67890-...": {
        promptTokens: 300,
        completionTokens: 600,
        totalTokens: 900,
        contextTokens: 150,
        model: "gpt-6-astra",
        cost: 0.018
      }
      // ... more node usages
    },
    modelsUsed: ["gpt-6-astra", "gpt-5.4-mini"]
  }
}

Graph-Ausführung mit Fehlern#

Wenn Nodes fehlschlagen, werden Fehler in die Antwort aufgenommen:

typescript
const result = await graph.run();

// Response with failures:
{
  graph: { /* ... */ },
  success: false,
  completedNodes: 3,
  failedNodes: 2,
  duration: 8500,
  results: {
    "node_abc12345-...": "Successfully completed...",
    "node_def67890-...": "Partial completion...",
    "node_ghi11111-...": "Task completed..."
  },
  errors: {
    "node_jkl22222-...": "Error: Timeout exceeded after 5000ms",
    "node_mno33333-...": "Error: Dependency node_jkl22222-... failed, skipping execution"
  },
  usage: { /* ... */ }
}

Node-hinzufügen-Antwort#

Das Hinzufügen von Nodes gibt die Node-ID zurück (Format: node_<uuid>):

typescript
const nodeId = graph.addTaskNode({
  name: "Analyze Data",
  prompt: "Analyze the following data...",
  model: "gpt-6-astra",
  priority: 10
});

// Response: "node_a1b2c3d4-e5f6-7890-abcd-ef1234567890" (node ID string)

Node-Nutzungsdetails#

Die Nutzung jedes Nodes wird individuell erfasst:

typescript
// Access individual node usage from result
const nodeUsage = result.usage.nodeUsages["node_abc12345-..."];

// Structure:
{
  promptTokens: 200,
  completionTokens: 400,
  totalTokens: 600,
  contextTokens: 100,      // Optional: tokens from context/memory
  model: "gpt-6-astra",
  cost: 0.012              // Optional: calculated cost
}

Graph-Nutzungszusammenfassung#

Gesamtnutzung über alle Nodes hinweg:

Ab Version 0.6.0 können result.usage.totalCost und graph.getTotalCost() den Wert undefined haben, wenn vollständige Kosteninformationen fehlen. undefined bedeutet nicht null Kosten; ein explizites 0 steht für bekannte Kosten von null. Prüfe vor der Formatierung, etwa mit .toFixed(), dass der Wert nicht undefined ist; das folgende Zahlenbeispiel setzt bekannte Kosten voraus.

typescript
const totalUsage = result.usage;

// Structure:
{
  totalPromptTokens: 1500,        // Sum of all prompt tokens
  totalCompletionTokens: 3000,    // Sum of all completion tokens
  totalTokens: 4500,              // Total tokens used
  totalContextTokens: 500,        // Total context tokens loaded
  totalCost: 0.045,               // Total estimated cost
  nodeUsages: { /* ... */ },      // Per-node breakdown
  modelsUsed: ["gpt-6-astra", "gpt-5.4-mini"]  // All models used in execution
}