Görev

Durum takibi ve araç entegrasyonuna sahip yapılandırılmış görev yürütme

Genel Bakış#

Görevler (Tasks), ajanlarınızla karmaşık işlemleri organize etmenin ve yürütmenin bir yolunu sağlar. Durum takibini ve araç kullanımını destekler ve daha büyük iş akışları halinde birleştirilebilir. Her görev bağımlılıklara sahip olabilir, belirli eylemleri yürütebilir ve yürütme boyunca kendi durumunu koruyabilir.

Görev Oluşturma#

Görevler, basit bir prompt tabanlı yaklaşımla ajanlar aracılığıyla oluşturulur:

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);

Görev Nitelikleri#

Görevler aşağıdaki niteliklerle yapılandırılabilir:

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)
}

Nitelik Detayları#

  • prompt: Görev için ana talimat veya sorgu. Bu, tek zorunlu alandır.
  • graphId: Bu görevin ait olduğu grafiğin UUID'si. Görevler bir graph iş akışının parçası olduğunda kullanılır.
  • graphNodeId: Bu görevi oluşturan graph düğümünün UUID'si. Graph iş akışlarında görev kökenini izlemek için kullanılır.
  • useTools: Görevin araç/eklenti kullanıp kullanamayacağını kontrol eder. Varsayılan true'dur (belirtilmezse ajandan devralır).
  • mcpServers: Bu görev için etkinleştirilecek göreve özgü MCP (Model Context Protocol) sunucuları.
  • plugins: Bu görev yürütmesi için kaydedilecek göreve özgü eklentiler.
  • attachments: Göreve eklenecek dosyaların dizisi. Görüntüleri, PDF'leri, metin dosyalarını, kod dosyalarını ve daha fazlasını destekler.
  • schedule: Zaman tabanlı yürütme için basit bir zamanlama dizesi (ör. 'daily@07:00', 'weekly@monday@09:00'). Graph'larla kullanıldığında otomatik zamanlamayı etkinleştiren isteğe bağlı alan.
  • metadata: Görevleri organize etmek ve izlemek için özel anahtar-değer çiftleri (ör. kategori, öncelik, etiketler).
  • executionContext: Anahtar-değer çiftlerinden oluşan bir kayıt olarak ek yürütme meta verisi. Çalışma zamanı bağlam bilgisi iletmek için kullanışlıdır.

Alt Ajan Entegrasyonu#

  • useSubAgents: Bu belirli görev için alt ajan devrini etkinleştirir. true olduğunda, ana ajan görevin bölümlerini kayıtlı alt ajanlarına akıllıca devreder.
  • subAgentDelegation: Görev devri stratejisi:
    • 'auto': Alt ajan yeteneklerine dayalı AI destekli akıllı görev dağıtımı
    • 'manual': taskAssignment eşlemesi kullanılarak açık görev ataması
    • 'sequential': Alt ajanlar sırayla çalışır ve önceki sonuçların üzerine inşa eder
  • subAgentCoordination: Alt ajan yürütmesi için koordinasyon deseni:
    • 'parallel': Alt ajanlar maksimum verimlilik için eş zamanlı çalışır
    • 'sequential': Alt ajanlar aralarında bağlam aktararak sırayla çalışır
  • taskAssignment: Manuel görev atama eşlemesi (yalnızca subAgentDelegation: 'manual' ile kullanılır). Ajan kimliklerini belirli görev talimatlarıyla eşler.

Görev Yaşam Döngüsü#

Görevler, yürütme sırasında birkaç durumdan geçer:

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

Beklemede#

Görev oluşturuldu ancak henüz başlamadı. Yürütme veya bağımlılıklar bekleniyor.

Devam Ediyor#

Görev, ajan tarafından aktif olarak yürütülüyor. Bu aşamada araçlar kullanılabilir.

Tamamlandı#

Görev başarıyla tamamlandı ve sonuçlar kullanılabilir.

Başarısız#

Görev yürütme sırasında bir hatayla karşılaştı. Hata detayları kullanılabilir.

Ek Dosyalar ve Araçlarla Örnek#

Dosya eklerine ve araç entegrasyonuna sahip görevleri gösteren eksiksiz bir örnek:

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()}`);
  }
});

Alt Ajan Görev Devri#

Görevler artık görev oluşturma ve yürütme sırasında doğrudan alt ajan devrini destekler:

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);

Alternatif: Alt Ajan Yürütmesi için Ajan Metodları#

Anında yürütme için alt ajanlardan ajan metodları aracılığıyla da yararlanabilirsiniz:

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'
  }
});

Görev Düzeyinde Alt Ajan Devrinin Faydaları#

  • Kalıcı Yapılandırma: Alt ajan ayarları görevle birlikte saklanır ve oturumlar arasında kalıcı olur
  • Tekrarlanabilir İş Akışları: Görev tanımları, tutarlı alt ajan davranışıyla yeniden kullanılabilir
  • Esnek Yürütme: Görevler anında yürütülebilir veya aynı alt ajan koordinasyonuyla daha sonraya zamanlanabilir
  • Denetim İzi: Görev meta verisi, izleme ve hata ayıklama için alt ajan devir geçmişini içerir

Görevleri Yönetme#

Görevler, yaşam döngüleri boyunca yönetilebilir ve izlenebilir:

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'
});

Yanıt Tipleri#

Görev yanıtlarını anlamak, yürütme sonuçlarını işlemenize ve görev yaşam döngüsünü izlemenize yardımcı olur.

Görev Nesnesi Yanıtı#

Bir görev oluşturmak veya almak eksiksiz bir Task nesnesi döndürür:

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
}

Görev Yürütme Yanıtı#

Bir görevi yürütmek, yürütme detaylarına sahip bir TaskResponse döndürür:

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
  }
}

Görev Listesi Yanıtı#

Görevleri listelemek, Task nesnelerinden oluşan bir dizi döndürür:

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(...)
  }
]

Görev Güncelleme Yanıtı#

Bir görevi güncellemek, güncellenmiş Task nesnesini veya bulunamazsa null döndürür:

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'),
  ...
}

Görev Alma Yanıtı#

Belirli bir görevi almak, Task nesnesini veya null döndürür:

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

// Returns: Task object or null if not found

Görev Silme Yanıtı#

Bir görevi silmek, başarıyı gösteren bir boolean döndürür:

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

Görevleri Temizleme Yanıtı#

Tüm görevleri temizlemek, silinen görevlerin sayısını döndürür:

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