Aufgabe

Strukturierte Task-Ausführung mit Statusverfolgung und Tool-Integration

Übersicht#

Tasks bieten eine Möglichkeit, komplexe Operationen mit deinen Agenten zu organisieren und auszuführen. Sie unterstützen Statusverfolgung, Tool-Nutzung und können zu größeren Workflows zusammengesetzt werden. Jeder Task kann Abhängigkeiten haben, bestimmte Aktionen ausführen und während der Ausführung seinen eigenen Zustand beibehalten.

Tasks erstellen#

Tasks werden über Agenten mit einem einfachen, promptbasierten Ansatz erstellt:

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

const agent = await Agent.create({
  name: 'TaskAgent',
  model: 'gpt-6-astra'
});

// Create a task
const task = await agent.createTask({
  prompt: 'Analyze the TypeScript code and suggest performance improvements'
});

// Execute the task
const result = await agent.executeTask(task.id);
console.log(result.response);

Task-Attribute#

Tasks können mit folgenden Attributen konfiguriert werden:

typescript
interface TaskRequest {
  prompt: string;              // The task instruction or query
  graphId?: string;            // UUID - Graph this task belongs to
  graphNodeId?: string;        // UUID - Graph node creating this task
  useTools?: boolean;          // Enable/disable tool usage (default: true)
  mcpServers?: MCPServerDefinition[]; // Task-level MCP servers
  plugins?: Array<{            // Task-level plugins
    plugin: Plugin;
    config?: PluginConfig;
  }>;
  attachments?: Array<{        // Files to attach to the task
    type: 'image' | 'pdf' | 'text' | 'markdown' | 'code' | 'json' | 'file';
    path: string;              // File path
    name?: string;             // Display name
    language?: string;         // Programming language (for code files)
  }>;
  schedule?: string;           // Simple schedule string (e.g., 'daily@07:00', 'weekly@monday@09:00')
  metadata?: MetadataObject;   // Custom metadata for tracking
  executionContext?: Record<string, unknown>; // Additional execution metadata
  useSubAgents?: boolean;                        // Enable sub-agent delegation for this task
  subAgentDelegation?: 'auto' | 'manual' | 'sequential'; // Delegation strategy
  subAgentCoordination?: 'parallel' | 'sequential';      // How sub-agents coordinate
  taskAssignment?: Record<string, string>;               // Manual task assignment (agentId UUID -> task)
}

Attribut-Details#

  • prompt: Die Hauptanweisung oder Abfrage für den Task. Dies ist das einzige erforderliche Feld.
  • graphId: UUID des Graphen, zu dem dieser Task gehört. Wird verwendet, wenn Tasks Teil eines Graph-Workflows sind.
  • graphNodeId: UUID des Graph-Nodes, der diesen Task erstellt hat. Dient der Nachverfolgung des Task-Ursprungs in Graph-Workflows.
  • useTools: Steuert, ob der Task Tools/Plugins verwenden kann. Standardmäßig true (wird vom Agenten übernommen, wenn nicht angegeben).
  • mcpServers: Task-spezifische MCP-Server (Model Context Protocol), die für diesen Task aktiviert werden.
  • plugins: Task-spezifische Plugins, die für diese Task-Ausführung registriert werden.
  • attachments: Array von Dateien, die dem Task angehängt werden. Unterstützt Bilder, PDFs, Textdateien, Code-Dateien und mehr.
  • schedule: Einfacher Zeitplan-String für zeitbasierte Ausführung (z. B. 'daily@07:00', 'weekly@monday@09:00'). Optionales Feld, das automatische Zeitplanung aktiviert, wenn es mit Graphs verwendet wird.
  • metadata: Benutzerdefinierte Schlüssel-Wert-Paare zur Organisation und Nachverfolgung von Tasks (z. B. Kategorie, Priorität, Tags).
  • executionContext: Zusätzliche Ausführungsmetadaten als Schlüssel-Wert-Paare. Nützlich, um Laufzeitkontext-Informationen zu übergeben.

Sub-Agent-Integration#

  • useSubAgents: Aktiviert Sub-Agent-Delegation für diesen spezifischen Task. Wenn true, delegiert der Hauptagent intelligent Teile des Tasks an seine registrierten Sub-Agents.
  • subAgentDelegation: Strategie für die Task-Delegation:
    • 'auto': KI-gestützte, intelligente Aufgabenverteilung basierend auf den Fähigkeiten der Sub-Agents
    • 'manual': Explizite Aufgabenzuweisung über die taskAssignment-Zuordnung
    • 'sequential': Sub-Agents arbeiten nacheinander und bauen auf vorherigen Ergebnissen auf
  • subAgentCoordination: Koordinationsmuster für die Ausführung der Sub-Agents:
    • 'parallel': Sub-Agents arbeiten gleichzeitig für maximale Effizienz
    • 'sequential': Sub-Agents arbeiten der Reihe nach mit Kontextweitergabe untereinander
  • taskAssignment: Manuelle Aufgabenzuweisungszuordnung (nur bei subAgentDelegation: 'manual' verwendet). Ordnet Agent-IDs bestimmten Aufgabenanweisungen zu.

Task-Lebenszyklus#

Tasks durchlaufen während der Ausführung mehrere Zustände:

typescript
type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed';

Pending#

Task wurde erstellt, aber noch nicht gestartet. Wartet auf Ausführung oder Abhängigkeiten.

In Progress#

Task wird aktiv vom Agenten ausgeführt. In dieser Phase können Tools verwendet werden.

Completed#

Task wurde erfolgreich abgeschlossen, Ergebnisse sind verfügbar.

Failed#

Bei der Ausführung des Tasks ist ein Fehler aufgetreten. Fehlerdetails sind verfügbar.

Beispiel mit Anhängen und Tools#

Hier ist ein vollständiges Beispiel, das Tasks mit Dateianhängen und Tool-Integration zeigt:

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

// Create an agent
const agent = await Agent.create({
  name: 'CodeReviewAssistant',
  model: 'gpt-6-astra',
  vision: true // Enable vision for screenshots
});

// Code review task with multiple file types
const codeReviewTask = await agent.createTask({
  prompt: `Please perform a comprehensive code review:
    1. Check for security vulnerabilities
    2. Identify performance issues
    3. Suggest improvements for code quality
    4. Review the UI mockup for usability issues`,
  attachments: [
    { 
      type: 'code', 
      path: './src/auth/login.ts', 
      name: 'Login Controller',
      language: 'typescript' 
    },
    { 
      type: 'code', 
      path: './src/middleware/security.js', 
      name: 'Security Middleware',
      language: 'javascript' 
    },
    { 
      type: 'json', 
      path: './package.json', 
      name: 'Package Dependencies' 
    },
    { 
      type: 'image', 
      path: './designs/login-mockup.png', 
      name: 'Login UI Mockup' 
    },
    { 
      type: 'markdown', 
      path: './docs/security-requirements.md', 
      name: 'Security Requirements' 
    }
  ],
  metadata: {
    type: 'code-review',
    priority: 'high',
    reviewer: 'ai-assistant'
  }
});

// Execute task with streaming
const result = await agent.executeTask(codeReviewTask.id, {
  model: 'gpt-6-astra',  // Override model for this task
  stream: true      // Enable streaming response
});

console.log('Code review completed:', result.response);

// Documentation task with text files
const docTask = await agent.createTask({
  prompt: 'Update the API documentation based on the latest code changes',
  attachments: [
    { type: 'text', path: '/api/routes.txt', name: 'API Routes' },
    { type: 'markdown', path: '/README.md', name: 'Current Documentation' }
  ]
});

// List tasks with attachments
const tasksWithFiles = await agent.listTasks({
  orderBy: 'createdAt',
  order: 'desc'
});

tasksWithFiles.forEach(task => {
  console.log(`Task ${task.id}: ${task.status}`);
  if (task.metadata?.attachments) {
    console.log(`  - Has attachments`);
  }
  if (task.completedAt) {
    console.log(`  - Completed: ${task.completedAt.toISOString()}`);
  }
});

Sub-Agent-Task-Delegation#

Tasks unterstützen jetzt Sub-Agent-Delegation direkt über die Task-Erstellung und -Ausführung:

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

// Create specialized sub-agents
const researcher = await Agent.create({
  name: 'ResearchBot',
  systemPrompt: 'You are an expert researcher who gathers comprehensive information.'
});

const writer = await Agent.create({
  name: 'WriterBot', 
  systemPrompt: 'You create engaging, well-structured content.'
});

const mainAgent = await Agent.create({
  name: 'ContentCoordinator',
  subAgents: [researcher, writer]
});

// Create task with automatic sub-agent delegation
const autoTask = await mainAgent.createTask({
  prompt: 'Research renewable energy trends and write a comprehensive report',
  useSubAgents: true,
  subAgentDelegation: 'auto',
  subAgentCoordination: 'sequential',
  metadata: { type: 'research-report', priority: 'high' }
});

// Create task with manual sub-agent assignment
const manualTask = await mainAgent.createTask({
  prompt: 'Create market analysis presentation',
  useSubAgents: true,
  subAgentDelegation: 'manual',
  subAgentCoordination: 'parallel',
  taskAssignment: {
    [researcher.id]: 'Research market data and competitor analysis',
    [writer.id]: 'Create presentation slides and executive summary'
  },
  metadata: { type: 'presentation', deadline: '2024-12-01' }
});

// Execute tasks - sub-agent coordination happens automatically
const autoResult = await mainAgent.executeTask(autoTask.id);
const manualResult = await mainAgent.executeTask(manualTask.id);

console.log('Auto-delegated result:', autoResult.response);
console.log('Manually-assigned result:', manualResult.response);

Alternative: Agent-Methoden für Sub-Agent-Ausführung#

Du kannst Sub-Agents auch über Agent-Methoden für die sofortige Ausführung nutzen:

typescript
// Direct execution with sub-agent delegation via agent.ask()
const result = await mainAgent.ask('Research renewable energy trends and write report', {
  useSubAgents: true,
  delegation: 'auto',
  coordination: 'sequential'
});

// Manual delegation with specific task assignments
const manualResult = await mainAgent.ask('Create market analysis presentation', {
  useSubAgents: true,
  delegation: 'manual',
  coordination: 'parallel',
  taskAssignment: {
    [researcher.id]: 'Research market data and competitor analysis',
    [writer.id]: 'Create presentation slides and executive summary'
  }
});

Vorteile der Sub-Agent-Delegation auf Task-Ebene#

  • Persistente Konfiguration: Sub-Agent-Einstellungen werden mit dem Task gespeichert und bleiben über Sitzungen hinweg erhalten
  • Reproduzierbare Workflows: Task-Definitionen können mit konsistentem Sub-Agent-Verhalten wiederverwendet werden
  • Flexible Ausführung: Tasks können sofort ausgeführt oder für später mit derselben Sub-Agent-Koordination geplant werden
  • Audit-Trail: Task-Metadaten enthalten den Verlauf der Sub-Agent-Delegation zur Nachverfolgung und zum Debugging

Tasks verwalten#

Tasks können während ihres gesamten Lebenszyklus verwaltet und nachverfolgt werden:

typescript
// Update task with additional metadata
await agent.updateTask(task.id, {
  metadata: {
    ...task.metadata,
    progress: 50,
    estimatedCompletion: new Date()
  }
});

// Delete a specific task
await agent.deleteTask(task.id);

// Clear all tasks for an agent
const deletedCount = await agent.clearTasks();
console.log(`Deleted ${deletedCount} tasks`);

// Search tasks with filters
const pendingTasks = await agent.listTasks({
  status: 'pending',
  limit: 5
});

const recentTasks = await agent.listTasks({
  orderBy: 'completedAt',
  order: 'desc',
  limit: 10
});

// Filter tasks by graph
const graphTasks = await agent.listTasks({
  graphId: 'graph-uuid-123',
  orderBy: 'createdAt',
  order: 'asc'
});

Antworttypen#

Das Verständnis der Task-Antworten hilft dir, Ausführungsergebnisse zu verarbeiten und den Task-Lebenszyklus nachzuverfolgen.

Task-Objekt-Antwort#

Das Erstellen oder Abrufen eines Tasks gibt ein vollständiges Task-Objekt zurück:

typescript
const task = await agent.createTask({
  prompt: "Analyze this data",
  useTools: true,
  metadata: { priority: "high" }
});

// Response structure (Task interface):
{
  id: "550e8400-e29b-41d4-a716-446655440000",  // UUID string
  agentId: "agent-uuid-123",                    // UUID string
  graphId?: "graph-uuid-456",                   // UUID string if part of a graph
  graphNodeId?: "node-uuid-789",                // UUID string if created by graph node
  prompt: "Analyze this data",
  response?: "Analysis result...",              // Filled after execution
  status: "pending",                            // 'pending' | 'in_progress' | 'completed' | 'failed'
  metadata?: {
    priority: "high"
  },
  executionContext?: {},                        // Additional execution metadata
  createdAt: Date('2024-01-15T10:30:00Z'),
  updatedAt: Date('2024-01-15T10:30:00Z'),
  completedAt?: Date('2024-01-15T10:35:00Z')   // Filled after completion
}

Task-Ausführungs-Antwort#

Das Ausführen eines Tasks gibt eine TaskResponse mit Ausführungsdetails zurück:

typescript
const result = await agent.executeTask("task-uuid-123", {
  model: "gpt-6-astra",
  stream: false
});

// Response structure (TaskResponse interface):
{
  task: {
    id: "task-uuid-123",
    agentId: "agent-uuid",
    graphId?: "graph-uuid",           // If part of a graph
    graphNodeId?: "node-uuid",        // If created by graph node
    prompt: "Analyze this data",
    response: "Analysis complete: The data shows a 15% increase...",
    status: "completed",
    metadata?: { priority: "high" },
    executionContext?: {},            // Additional execution metadata
    createdAt: Date('2024-01-15T10:30:00Z'),
    updatedAt: Date('2024-01-15T10:35:00Z'),
    completedAt: Date('2024-01-15T10:35:00Z')
  },
  response: "Analysis complete: The data shows a 15% increase in user engagement...",
  model?: "gpt-6-astra",
  usage?: {
    promptTokens: 150,
    completionTokens: 300,
    totalTokens: 450
  }
}

Task-Listen-Antwort#

Das Auflisten von Tasks gibt ein Array von Task-Objekten zurück:

typescript
const tasks = await agent.listTasks({
  status: 'completed',
  orderBy: 'completedAt',
  order: 'desc',
  limit: 10,
  offset: 0,           // Pagination offset
  graphId: 'optional'  // Filter by graph ID (UUID)
});

// Response structure (Task[] array):
[
  {
    id: "task-uuid-1",
    agentId: "agent-uuid",
    graphId?: "graph-uuid",        // If part of a graph
    graphNodeId?: "node-uuid",     // If created by graph node
    prompt: "First task",
    response?: "First task completed",
    status: "completed",
    metadata?: {},
    executionContext?: {},
    createdAt: Date(...),
    updatedAt: Date(...),
    completedAt?: Date(...)
  },
  {
    id: "task-uuid-2",
    agentId: "agent-uuid",
    graphId?: "graph-uuid",
    graphNodeId?: "node-uuid",
    prompt: "Second task",
    response?: "Second task completed",
    status: "completed",
    metadata?: {},
    executionContext?: {},
    createdAt: Date(...),
    updatedAt: Date(...),
    completedAt?: Date(...)
  }
]

Task-Aktualisierungs-Antwort#

Das Aktualisieren eines Tasks gibt das aktualisierte Task-Objekt oder null zurück, wenn es nicht gefunden wurde:

typescript
const updated = await agent.updateTask("task-uuid", {
  metadata: { progress: 50, estimatedCompletion: new Date() }
});

// Response: Task object with updated fields or null
{
  id: "task-uuid",
  agentId: "agent-uuid",
  prompt: "Original prompt",
  status: "in_progress",
  metadata: {
    priority: "high",
    progress: 50,
    estimatedCompletion: Date('2024-01-15T12:00:00Z')
  },
  updatedAt: Date('2024-01-15T10:40:00Z'),
  ...
}

Task-Abruf-Antwort#

Das Abrufen eines bestimmten Tasks gibt das Task-Objekt oder null zurück:

typescript
const task = await agent.getTask("task-uuid");

// Returns: Task object or null if not found

Task-Löschungs-Antwort#

Das Löschen eines Tasks gibt einen booleschen Wert zurück, der den Erfolg anzeigt:

typescript
const deleted = await agent.deleteTask("task-uuid");
// Returns: true or false

Clear-Tasks-Antwort#

Das Löschen aller Tasks gibt die Anzahl der gelöschten Tasks zurück:

typescript
const deletedCount = await agent.clearTasks();
// Returns: 25 (number of tasks deleted)