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:
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:
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 dietaskAssignment-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-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:
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-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:
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 foundTask-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 falseClear-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)