Tarefa

Execução estruturada de tarefas com rastreamento de status e integração de ferramentas Aprenda os padrões de configuração, as APIs e os exemplos práticos...

Execução estruturada de tarefas com rastreamento de status e integração de ferramentas

Visão Geral

Tasks (tarefas) fornecem uma forma de organizar e executar operações complexas com seus agentes. Elas suportam rastreamento de status, uso de ferramentas e podem ser compostas em fluxos de trabalho maiores. Cada tarefa pode ter dependências, executar ações específicas e manter seu próprio estado durante toda a execução.

Criando Tarefas

Tarefas são criadas através de agentes usando uma abordagem simples baseada em prompt:

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

Atributos da Tarefa

Tarefas podem ser configuradas com os seguintes atributos:

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

Detalhes dos Atributos

prompt: A instrução ou consulta principal para a tarefa. Este é o único campo obrigatório.
graphId: UUID do grafo ao qual esta tarefa pertence. Usado quando as tarefas fazem parte de um fluxo de trabalho em grafo.
graphNodeId: UUID do nó do grafo que criou esta tarefa. Usado para rastrear a origem da tarefa em fluxos de trabalho em grafo.
useTools: Controla se a tarefa pode usar ferramentas/plugins. O padrão é true (herda do agente se não especificado).
mcpServers: Servidores MCP (Model Context Protocol) específicos da tarefa a serem habilitados para esta tarefa.
plugins: Plugins específicos da tarefa a serem registrados para esta execução de tarefa.
attachments: Array de arquivos a anexar à tarefa. Suporta imagens, PDFs, arquivos de texto, arquivos de código e mais.
schedule: String de agendamento simples para execução baseada em tempo (ex.: 'daily@07:00', 'weekly@monday@09:00'). Campo opcional que habilita o agendamento automático quando usado com grafos.
metadata: Pares chave-valor personalizados para organizar e rastrear tarefas (ex.: categoria, prioridade, tags).
executionContext: Metadados de execução adicionais como um registro de pares chave-valor. Útil para passar informações de contexto em tempo de execução.

Integração com Sub-Agentes

useSubAgents: Habilita a delegação a sub-agentes para esta tarefa específica. Quando true, o agente principal delegará de forma inteligente partes da tarefa aos seus sub-agentes registrados.
subAgentDelegation: Estratégia para delegação de tarefas:
- 'auto': Distribuição inteligente de tarefas orientada por IA com base nas capacidades dos sub-agentes
- 'manual': Atribuição explícita de tarefas usando o mapeamento taskAssignment
- 'sequential': Sub-agentes trabalham em sequência, construindo sobre os resultados anteriores
subAgentCoordination: Padrão de coordenação para a execução dos sub-agentes:
- 'parallel': Sub-agentes trabalham simultaneamente para máxima eficiência
- 'sequential': Sub-agentes trabalham em ordem, com passagem de contexto entre eles
taskAssignment: Mapeamento de atribuição manual de tarefas (usado apenas com subAgentDelegation: 'manual'). Mapeia IDs de agentes para instruções de tarefa específicas.

Ciclo de Vida da Tarefa

As tarefas passam por vários estados durante a execução:

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

Pending (Pendente)

A tarefa foi criada, mas ainda não iniciada. Aguardando execução ou dependências.

In Progress (Em Andamento)

A tarefa está sendo executada ativamente pelo agente. Ferramentas podem ser usadas durante esta fase.

Completed (Concluída)

A tarefa foi finalizada com sucesso e os resultados estão disponíveis.

Failed (Falhou)

A tarefa encontrou um erro durante a execução. Detalhes do erro estão disponíveis.

Exemplo com Anexos e Ferramentas

Aqui está um exemplo completo mostrando tarefas com anexos de arquivo e integração de ferramentas:

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

Delegação de Tarefas para Sub-Agentes

Tarefas agora suportam delegação de sub-agentes diretamente através da criação e execução de tarefas:

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

Alternativa: Métodos do Agente para Execução com Sub-Agentes

Você também pode usar sub-agentes através dos métodos do agente para execução imediata:

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

Benefícios da Delegação de Sub-Agentes em Nível de Tarefa

Configuração Persistente: As configurações de sub-agente são armazenadas com a tarefa e persistem entre sessões
Fluxos de Trabalho Reproduzíveis: Definições de tarefa podem ser reutilizadas com comportamento consistente dos sub-agentes
Execução Flexível: Tarefas podem ser executadas imediatamente ou agendadas para depois com a mesma coordenação de sub-agentes
Trilha de Auditoria: Os metadados da tarefa incluem o histórico de delegação de sub-agentes para rastreamento e depuração

Gerenciando Tarefas

Tarefas podem ser gerenciadas e rastreadas ao longo de todo o seu ciclo de vida:

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

Tipos de Resposta

Entender as respostas de tarefa ajuda a tratar os resultados de execução e rastrear o ciclo de vida da tarefa.

Resposta do Objeto Task

Criar ou recuperar uma tarefa retorna um objeto Task completo:

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
}

Resposta de Execução da Tarefa

Executar uma tarefa retorna um TaskResponse com detalhes da execução:

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

Resposta de Lista de Tarefas

Listar tarefas retorna um array de objetos Task:

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

Resposta de Atualização de Tarefa

Atualizar uma tarefa retorna o objeto Task atualizado ou null se não encontrado:

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

Resposta de Obtenção de Tarefa

Recuperar uma tarefa específica retorna o objeto Task ou null:

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

// Returns: Task object or null if not found

Resposta de Exclusão de Tarefa

Excluir uma tarefa retorna um booleano indicando sucesso:

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

Resposta de Limpeza de Tarefas

Limpar todas as tarefas retorna a contagem de tarefas excluídas:

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

Última atualização: 6 de julho de 2026

Nesta seção

Introdução

Framework de agentes de IA open-source para construir sistemas autônomos que resolvem tarefas do mundo real de forma eficaz.

Instalação

Instale o Astreus com npm, yarn ou pnpm, confirme a versão necessária do Node.js e prepare um projeto local para construir agentes de IA com o framework.

Início Rápido

Construa seu primeiro agente de IA com Astreus em menos de 2 minutos Aprenda os padrões de configuração, as APIs e os exemplos práticos necessários para...

Agente

Entidade central de IA com capacidades modulares e composição baseada em decorators Aprenda os padrões de configuração, as APIs e os exemplos práticos...

Contexto

Grafo