Tarea
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-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);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 mapeotaskAssignment'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-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()}`);
}
});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-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
}
}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 foundRespuesta de eliminación de tarea#
Eliminar una tarea devuelve un booleano que indica éxito:
const deleted = await agent.deleteTask("task-uuid");
// Returns: true or falseRespuesta 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)