Resource Reference

# Resource Reference

Point to external data by URI instead of embedding it.

## Category
Tool Context

## Context
Large data that shouldn't be passed through the conversation.

## Problem
Large files or data blobs consume context window and slow processing.

## Solution
Use resource references:
- **URI-based**: Point to data, don't embed it
- **Resolvable**: Tools can fetch when needed
- **Typed**: Include content type
- **Cacheable**: Allow caching resolved content

## Example (Python)
```python
@tool
def upload_file(
    content: bytes,
    filename: str
) -> ResourceRef:
    """Upload a file and return a reference.
    
    Returns a resource URI that other tools can use
    to access the file without re-uploading.
    """
    file_id = storage.upload(content, filename)
    return ResourceRef(
        uri=f"resource://files/{file_id}",
        content_type=guess_mimetype(filename),
        size_bytes=len(content),
        filename=filename
    )

@tool
def analyze_document(resource_uri: str) -> Analysis:
    """Analyze a document by resource URI.
    
    Args:
        resource_uri: URI from upload_file() or similar
    """
    content = storage.resolve(resource_uri)
    return analyzer.analyze(content)
```

## Considerations
- Use URIs as the common reference format
- Include metadata (type, size) in the reference
- Handle expired or missing resources gracefully

## Related Patterns
- token-efficient-response
- async-job
- progressive-detail

---
Source: https://arcade.dev/patterns/resource-reference