Aufgabe

Strukturierte Task-Ausführung mit Statusverfolgung und Tool-Integration Lerne die Einrichtungsmuster, APIs und praktischen Beispiele kennen, die du zum...

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:

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

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

// 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:

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:

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:

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

// Create an agent
const agent = await Agent.create({
  name: 'CodeReviewAssistant',
  model: 'gpt-4o',
  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-4o',  // 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:

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:

// 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:

// 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:

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:

const result = await agent.executeTask("task-uuid-123", {
  model: "gpt-4",
  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-4",
  usage?: {
    promptTokens: 150,
    completionTokens: 300,
    totalTokens: 450
  }
}

Task-Listen-Antwort

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

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:

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:

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:

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:

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

Zuletzt aktualisiert: 6. Juli 2026

In diesem Abschnitt

Einführung

Open-Source-KI-Agent-Framework zum Erstellen autonomer Systeme, die reale Aufgaben effektiv lösen.

Installation

Installiere Astreus mit npm, yarn oder pnpm, überprüfe die erforderliche Node.js-Version und bereite ein lokales Projekt für die Entwicklung von KI-Agenten...

Schnellstart

Erstelle deinen ersten KI-Agenten mit Astreus in unter 2 Minuten Lerne die Einrichtungsmuster, APIs und praktischen Beispiele kennen, die du zum Aufbau...

Agent

Zentrale KI-Entität mit modularen Fähigkeiten und dekoratorbasierter Komposition Lerne die Einrichtungsmuster, APIs und praktischen Beispiele kennen, die du...