Tarea

Ejecución estructurada de tareas con seguimiento de estado e integración de herramientas Aprende los patrones de configuración, las APIs y los ejemplos...

Ejecución estructurada de tareas con seguimiento de estado e integración de herramientas

Descripción general

Las tareas proporcionan una forma de organizar y ejecutar operaciones complejas con tus agentes. Soportan seguimiento de estado, uso de herramientas y pueden componerse en flujos de trabajo más grandes. Cada tarea puede tener dependencias, ejecutar acciones específicas y mantener su propio estado durante toda la ejecución.

Crear tareas

Las tareas se crean a través de los agentes mediante un enfoque simple basado en prompts:

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 de la tarea

Las tareas pueden configurarse con los siguientes 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)
}

Detalle de los atributos

prompt: la instrucción o consulta principal de la tarea. Es el único campo obligatorio.
graphId: UUID del grafo al que pertenece esta tarea. Se usa cuando las tareas forman parte de un flujo de trabajo con grafo.
graphNodeId: UUID del nodo del grafo que creó esta tarea. Se usa para rastrear el origen de la tarea en flujos de trabajo con grafo.
useTools: controla si la tarea puede usar herramientas/plugins. Por defecto es true (hereda del agente si no se especifica).
mcpServers: servidores MCP (Model Context Protocol) específicos de la tarea que se habilitan para esta tarea.
plugins: plugins específicos de la tarea que se registran para esta ejecución.
attachments: array de archivos que se adjuntan a la tarea. Admite imágenes, PDFs, archivos de texto, archivos de código y más.
schedule: cadena de programación simple para ejecución basada en tiempo (por ejemplo, 'daily@07:00', 'weekly@monday@09:00'). Campo opcional que habilita la programación automática cuando se usa junto con grafos.
metadata: pares clave-valor personalizados para organizar y rastrear tareas (por ejemplo, categoría, prioridad, etiquetas).
executionContext: metadatos de ejecución adicionales como un registro de pares clave-valor. Útil para pasar información de contexto en tiempo de ejecución.

Integración con sub-agentes

useSubAgents: habilita la delegación a sub-agentes para esta tarea específica. Cuando es true, el agente principal delegará inteligentemente partes de la tarea a sus sub-agentes registrados.
subAgentDelegation: estrategia para la delegación de tareas:
- 'auto': distribución inteligente de tareas impulsada por IA según las capacidades de los sub-agentes
- 'manual': asignación explícita de tareas mediante el mapeo taskAssignment
- 'sequential': los sub-agentes trabajan en secuencia, construyendo sobre los resultados anteriores
subAgentCoordination: patrón de coordinación para la ejecución de sub-agentes:
- 'parallel': los sub-agentes trabajan simultáneamente para lograr la máxima eficiencia
- 'sequential': los sub-agentes trabajan en orden, pasándose el contexto entre ellos
taskAssignment: mapeo de asignación manual de tareas (solo se usa con subAgentDelegation: 'manual'). Mapea los IDs de agente a instrucciones de tarea específicas.

Ciclo de vida de la tarea

Las tareas pasan por varios estados durante su ejecución:

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

Pending

La tarea se ha creado pero aún no se ha iniciado. Está esperando ejecución o dependencias.

In Progress

La tarea está siendo ejecutada activamente por el agente. Es posible que se usen herramientas durante esta fase.

Completed

La tarea ha finalizado con éxito y hay resultados disponibles.

Failed

La tarea encontró un error durante la ejecución. Los detalles del error están disponibles.

Ejemplo con archivos adjuntos y herramientas

Aquí tienes un ejemplo completo que muestra tareas con archivos adjuntos e integración de herramientas:

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

Delegación de tareas a sub-agentes

Las tareas ahora soportan delegación a sub-agentes directamente a través de la creación y ejecución de tareas:

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 del agente para la ejecución con sub-agentes

También puedes aprovechar los sub-agentes mediante métodos del agente para una ejecución inmediata:

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

Ventajas de la delegación a sub-agentes a nivel de tarea

Configuración persistente: los ajustes de sub-agentes se almacenan junto con la tarea y persisten entre sesiones
Flujos de trabajo reproducibles: las definiciones de tareas pueden reutilizarse con un comportamiento de sub-agente consistente
Ejecución flexible: las tareas pueden ejecutarse inmediatamente o programarse para más tarde con la misma coordinación de sub-agentes
Registro de auditoría: los metadatos de la tarea incluyen el historial de delegación a sub-agentes para seguimiento y depuración

Gestión de tareas

Las tareas pueden gestionarse y rastrearse a lo largo de todo su 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 respuesta

Entender las respuestas de las tareas te ayuda a manejar los resultados de ejecución y rastrear el ciclo de vida de la tarea.

Respuesta de objeto Task

Crear o recuperar una tarea devuelve un 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
}

Respuesta de ejecución de tarea

Ejecutar una tarea devuelve un TaskResponse con los detalles de la ejecución:

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

Respuesta de lista de tareas

Listar tareas devuelve un 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(...)
  }
]

Respuesta de actualización de tarea

Actualizar una tarea devuelve el objeto Task actualizado o null si no se encuentra:

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

Respuesta de obtención de tarea

Recuperar una tarea específica devuelve el objeto Task o null:

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

// Returns: Task object or null if not found

Respuesta de eliminación de tarea

Eliminar una tarea devuelve un booleano que indica éxito:

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

Respuesta de limpieza de tareas

Limpiar todas las tareas devuelve el número de tareas eliminadas:

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

Última actualización: 6 de julio de 2026

En esta sección

Introducción

Framework de agentes de IA de código abierto para construir sistemas autónomos que resuelven tareas del mundo real de forma eficaz.

Instalación

Instala Astreus con npm, yarn o pnpm, confirma la versión de Node.js requerida y prepara un proyecto local para construir agentes de IA con el framework.

Inicio rápido

Construye tu primer agente de IA con Astreus en menos de 2 minutos Aprende los patrones de configuración, las APIs y los ejemplos prácticos necesarios para...

Agente

Entidad de IA principal con capacidades modulares y composición basada en decoradores Aprende los patrones de configuración, las APIs y los ejemplos...

Contexto

Grafo