Building Task Attachments in Astreus

## What Are Task Attachments?

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.

## Getting Started

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

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

Alternatively, install just the package:

```bash
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
```

## Creating an Agent with Vision

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

## Attachment Structure

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

## Creating Tasks with Multiple Attachments

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

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

## Executing Tasks

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

```typescript
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.

## Running Your Implementation

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

```bash
npm run dev
```

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

```bash
px tsx index.ts
```

## Processing Code Files

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

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

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

## Image Analysis

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

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

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

## Structured Data Processing

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

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

## Documentation Analysis

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

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

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

## Cross-File Analysis

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

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

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

## Task Metadata

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

```typescript
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.

## Best Practices

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

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

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

## Organizing Related Files

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

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

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

## Error Handling

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

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

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

## Real-World Use Cases

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

## Design-Implementation Verification

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

```typescript
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.

## Documentation Quality Assurance

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

```typescript
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.

## Security Audits

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

```typescript
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.

## Working with the Repository

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

Repository: [github.com/astreus-ai/task-attachments](https://github.com/astreus-ai/task-attachments)

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

## Key Features Summary

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.

## Future Possibilities

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.