Building Task Attachments in Astreus

Task attachments enable you to attach multiple file types to tasks for comprehensive analysis within the Astreus framework. Instead of manually extracting content or describing files in prompts, you can pass files directly to agents equipped with vision and processing capabilities. This transforms agents from text processors into sophisticated document analyzers.

You can either clone the complete example repository or install the package independently. Both approaches give you access to the task attachment functionality.

Bash
Copy
git clone https://github.com/astreus-ai/astreus
cd task-attachments
npm install

Alternatively, install just the package:

Bash
Copy
npm install @astreus-ai/astreus

Create a .env file with your configuration:

OPENAI_API_KEY=sk-your-openai-api-key-here
DB_URL=sqlite://./astreus.db

To process attachments, especially images, create an agent with vision capabilities enabled. The vision model handles image analysis while the main model processes text and code.

TypeScript
Copy
const agent = await Agent.create({
  name: 'AnalysisAgent',
  model: 'gpt-4o',
  visionModel: 'gpt-4o',
  vision: true
});

This configuration enables the agent to process both text-based files and visual content. The vision: true flag activates multimodal processing capabilities.

Each attachment requires specific properties to identify and process the file correctly. The type field categorizes the content, while path provides the location and name gives it a display identifier.

TypeScript
Copy
const attachment = {
  type: 'code',
  path: './src/auth/login.ts',
  name: 'Login Controller',
  language: 'typescript'
};

Supported types include code, image, json, and markdown. For code files, specify the language to enable syntax-aware analysis.

Tasks accept an array of attachments, allowing you to provide all necessary context in a single request. The agent can reason across different file types simultaneously.

TypeScript
Copy
const reviewTask = await agent.createTask({
  prompt: `Perform comprehensive analysis:
    1. Review code for security issues
    2. Evaluate design mockup usability
    3. Verify dependency currency
    4. Assess documentation completeness`,
  attachments: [
    { 
      type: 'code', 
      path: './src/auth/login.ts', 
      name: 'Login Controller',
      language: 'typescript' 
    },
    { 
      type: 'image', 
      path: './designs/login-ui.png', 
      name: 'Login UI Mockup' 
    },
    { 
      type: 'json', 
      path: './package.json', 
      name: 'Dependencies' 
    },
    { 
      type: 'markdown', 
      path: './docs/api.md', 
      name: 'API Documentation' 
    }
  ],
  metadata: {
    type: 'comprehensive-review',
    priority: 'high'
  }
});
more

This creates a task that processes code, design mockups, dependencies, and documentation together. The agent analyzes all materials and provides unified insights.

Once created, execute tasks by their ID to get the analysis results. The agent processes all attachments and returns a structured response.

TypeScript
Copy
const result = await agent.executeTask(reviewTask.id);
console.log('Analysis complete:', result.response);

The execution is asynchronous, allowing you to process multiple tasks concurrently. Results include the agent's analysis of all attached materials.

For cloned repositories, use the provided dev script to run examples:

Bash
Copy
npm run dev

For standalone implementations, create an index.ts file with your code and execute with tsx:

Bash
Copy
px tsx index.ts

Code attachments support language specification for syntax-aware analysis. The agent understands programming constructs and can identify patterns, issues, and improvements.

TypeScript
Copy
const codeReview = await agent.createTask({
  prompt: 'Review this authentication code for security vulnerabilities',
  attachments: [
    {
      type: 'code',
      path: './src/auth/handlers.ts',
      name: 'Auth Handlers',
      language: 'typescript'
    }
  ]
});

const result = await agent.executeTask(codeReview.id);
more

The language parameter helps the agent apply language-specific best practices and identify common vulnerabilities in that ecosystem.

Image attachments enable visual analysis when you have design mockups, screenshots, or diagrams. Vision-capable models process these directly without requiring text descriptions.

TypeScript
Copy
const designReview = await agent.createTask({
  prompt: 'Evaluate this UI design for accessibility and usability',
  attachments: [
    {
      type: 'image',
      path: './designs/dashboard.png',
      name: 'Dashboard Design'
    }
  ]
});

const result = await agent.executeTask(designReview.id);
more

The agent can identify UI elements, assess layout quality, and provide feedback on visual hierarchy and user experience principles.

JSON attachments are useful for analyzing configuration files, API responses, or structured data. The agent understands the data structure and can validate or extract information.

TypeScript
Copy
const dependencyCheck = await agent.createTask({
  prompt: 'Identify outdated dependencies and security vulnerabilities',
  attachments: [
    {
      type: 'json',
      path: './package.json',
      name: 'Package Dependencies'
    }
  ]
});

const result = await agent.executeTask(dependencyCheck.id);
more

This enables automated dependency audits, configuration validation, and data quality checks without manual inspection.

Markdown attachments allow you to include documentation, specifications, or written content. The agent can assess completeness, clarity, and accuracy.

TypeScript
Copy
const docReview = await agent.createTask({
  prompt: 'Review API documentation for completeness and clarity',
  attachments: [
    {
      type: 'markdown',
      path: './docs/api-reference.md',
      name: 'API Reference'
    }
  ]
});

const result = await agent.executeTask(docReview.id);
more

The agent understands markdown structure and can identify missing sections, unclear explanations, or inconsistencies in documentation.

The real power emerges when combining multiple file types in a single task. The agent correlates information across attachments to provide comprehensive insights.

TypeScript
Copy
const fullReview = await agent.createTask({
  prompt: 'Verify that the implementation matches the specification and design',
  attachments: [
    {
      type: 'markdown',
      path: './specs/feature-spec.md',
      name: 'Specification'
    },
    {
      type: 'image',
      path: './designs/feature-mockup.png',
      name: 'Design Mockup'
    },
    {
      type: 'code',
      path: './src/features/implementation.ts',
      name: 'Implementation',
      language: 'typescript'
    }
  ]
});

const result = await agent.executeTask(fullReview.id);
more

This enables requirement traceability, design-implementation verification, and comprehensive quality assurance in a single operation.

Metadata helps organize and categorize tasks for filtering, prioritization, and workflow management. Use it to track task types, priorities, or custom classifications.

TypeScript
Copy
const task = await agent.createTask({
  prompt: 'Security audit of authentication system',
  attachments: [/* ... */],
  metadata: {
    type: 'security-audit',
    priority: 'high',
    component: 'authentication',
    assignee: 'security-team'
  }
});

Metadata doesn't affect processing but provides context for task management systems and reporting tools.

Keep prompts specific about what to analyze in the attachments. Generic instructions lead to generic results, while focused questions produce actionable insights.

TypeScript
Copy
// Good: Specific analysis request
const task = await agent.createTask({
  prompt: 'Check for SQL injection vulnerabilities and missing input validation',
  attachments: [{ type: 'code', path: './database.ts', language: 'typescript' }]
});

// Avoid: Vague instructions
const task = await agent.createTask({
  prompt: 'Review this code',
  attachments: [{ type: 'code', path: './database.ts', language: 'typescript' }]
});
more

Clear prompts guide the agent's focus and ensure you get relevant, detailed feedback on the aspects that matter most.

When analyzing related files, use descriptive names to help the agent understand relationships. This improves the quality of cross-file analysis.

TypeScript
Copy
const task = await agent.createTask({
  prompt: 'Ensure test coverage matches implementation',
  attachments: [
    {
      type: 'code',
      path: './src/utils/validator.ts',
      name: 'Validator Implementation',
      language: 'typescript'
    },
    {
      type: 'code',
      path: './tests/validator.test.ts',
      name: 'Validator Tests',
      language: 'typescript'
    }
  ]
});
more

Descriptive names provide context that helps the agent understand each file's role in the analysis.

Handle task execution errors gracefully to build robust applications. Check for file access issues, format problems, or processing failures.

TypeScript
Copy
try {
  const result = await agent.executeTask(task.id);
  console.log('Success:', result.response);
} catch (error) {
  if (error.code === 'FILE_NOT_FOUND') {
    console.error('Attachment not found:', error.path);
  } else if (error.code === 'UNSUPPORTED_FORMAT') {
    console.error('Unsupported file format:', error.type);
  } else {
    console.error('Task execution failed:', error.message);
  }
}
more

Proper error handling prevents application crashes and provides clear feedback when attachments can't be processed.

Task attachments enable sophisticated workflows like automated code reviews. Attach source files and let the agent identify issues, suggest improvements, and verify best practices.

TypeScript
Copy
const codeReview = await agent.createTask({
  prompt: 'Comprehensive code review covering security, performance, and maintainability',
  attachments: [
    { type: 'code', path: './src/api/routes.ts', language: 'typescript' },
    { type: 'code', path: './src/api/middleware.ts', language: 'typescript' },
    { type: 'json', path: './package.json', name: 'Dependencies' }
  ],
  metadata: { type: 'code-review', severity: 'standard' }
});

This automates repetitive review tasks and ensures consistent quality standards across your codebase.

Verify that implementations match design specifications by attaching both design mockups and code. The agent identifies discrepancies and missing features.

TypeScript
Copy
const verification = await agent.createTask({
  prompt: 'Verify the implementation matches the approved design',
  attachments: [
    { type: 'image', path: './designs/approved-design.png', name: 'Approved Design' },
    { type: 'code', path: './src/components/Feature.tsx', language: 'typescript' },
    { type: 'markdown', path: './specs/requirements.md', name: 'Requirements' }
  ]
});

This catches design drift early and ensures the final product matches stakeholder expectations.

Ensure documentation stays synchronized with code by analyzing both together. The agent identifies outdated examples, missing documentation, or incomplete coverage.

TypeScript
Copy
const docCheck = await agent.createTask({
  prompt: 'Verify documentation accurately reflects the current API',
  attachments: [
    { type: 'code', path: './src/api/index.ts', language: 'typescript' },
    { type: 'markdown', path: './docs/api-guide.md', name: 'API Guide' }
  ]
});

Automated documentation checks maintain quality without manual cross-referencing between docs and code.

Perform security audits by attaching relevant code files and asking the agent to identify vulnerabilities. This complements traditional security tools with contextual analysis.

TypeScript
Copy
const securityAudit = await agent.createTask({
  prompt: 'Identify security vulnerabilities including injection attacks, authentication issues, and data exposure',
  attachments: [
    { type: 'code', path: './src/auth/login.ts', language: 'typescript' },
    { type: 'code', path: './src/database/queries.ts', language: 'typescript' },
    { type: 'json', path: './config/security.json', name: 'Security Config' }
  ],
  metadata: { type: 'security-audit', scope: 'authentication' }
});

The agent understands security principles and can identify issues that pattern-matching tools might miss.

The complete example repository demonstrates all features with runnable code. Explore different attachment types and processing patterns.

Repository: github.com/astreus-ai/astreus

The examples show real-world patterns you can adapt to your specific use cases. Each example includes comments explaining the approach and expected outcomes.

Task attachments support diverse file formats including code, images, structured data, and documentation. Language specification enables syntax-aware analysis for code files. Metadata organization facilitates task categorization and workflow management. Integration with vision-capable LLMs enables image processing without manual description.

These capabilities transform agents from text processors into comprehensive document analyzers that understand multiple content types and their relationships.

As Astreus evolves, task attachments will support additional file types and larger context windows. Future enhancements may include video processing, audio transcription, and more sophisticated multi-file reasoning. The attachment system provides a foundation for increasingly sophisticated document processing workflows.

This experiment is written for Astreus v0.5.37. Please ensure you are using a compatible version.