Skip to main content

​
Overview

The Resources APIs provide tools for working with MCP resources, including loading files, creating embedded resources, and managing resource content. These utilities make it easy to attach files, images, and other data to your agent conversations.

​
Resource Loading

​
load_resource_content()

Load a resource file and determine its MIME type. 
from fast_agent.mcp.resource_utils import load_resource_content
from pathlib import Path

content, mime_type, is_binary = load_resource_content(
    resource_path="data.csv",
    prompt_files=[Path("prompt_template.txt")]
)

if is_binary:
    # content is base64-encoded
    decoded = base64.b64decode(content)
else:
    # content is plain text
    print(content)
​
resource_path
str
required
Path to the resource file (relative to prompt files)
​
prompt_files
list[Path]
required
List of prompt files used to resolve relative paths
​
content
str
File content (text string or base64-encoded for binary)
​
mime_type
str
MIME type of the resource
​
is_binary
bool
True if content is binary (and base64-encoded)
Raises FileNotFoundError if the resource cannot be found relative to any of the prompt files.

​
Creating Resources

​
create_embedded_resource()

Create an embedded resource content object for messages. 
from fast_agent.mcp.resource_utils import create_embedded_resource

resource = create_embedded_resource(
    resource_path="document.pdf",
    content=base64_content,
    mime_type="application/pdf",
    is_binary=True
)

# Use in message
msg = Prompt.user("Review this document:", resource)
​
resource_path
str
required
Path identifier for the resource
​
content
str
required
Resource content (plain text or base64-encoded)
​
mime_type
str
required
MIME type of the content
​
is_binary
bool
default:"False"
Whether content is binary (and base64-encoded)
​
resource
EmbeddedResource
MCP embedded resource object

​
create_text_resource()

Create an embedded resource for text data. 
from fast_agent.mcp.resource_utils import create_text_resource

resource = create_text_resource(
    resource_path="file:///data/config.json",
    content=json_string,
    mime_type="application/json"
)
​
resource_path
str | AnyUrl
required
URI or path for the resource
​
content
str
required
Text content of the resource
​
mime_type
str
required
MIME type (e.g., “text/plain”, “application/json”)
​
resource
EmbeddedResource
Embedded resource with text content

​
create_blob_resource()

Create an embedded resource for binary data. 
from fast_agent.mcp.resource_utils import create_blob_resource
import base64

# Read binary file
with open("image.png", "rb") as f:
    binary_data = f.read()
    base64_data = base64.b64encode(binary_data).decode("utf-8")

resource = create_blob_resource(
    resource_path="file:///images/image.png",
    content=base64_data,
    mime_type="image/png"
)
​
resource_path
str | AnyUrl
required
URI or path for the resource
​
content
str
required
Base64-encoded binary content
​
mime_type
str
required
MIME type (e.g., “image/png”, “application/pdf”)
​
resource
EmbeddedResource
Embedded resource with binary content

​
create_image_content()

Create an image content object from base64 data. 
from fast_agent.mcp.resource_utils import create_image_content
import base64

# Load and encode image
with open("photo.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

image = create_image_content(
    data=image_data,
    mime_type="image/jpeg"
)

msg = Prompt.user("What's in this image?", image)
​
data
str
required
Base64-encoded image data
​
mime_type
str
required
Image MIME type (e.g., “image/jpeg”, “image/png”)
​
image
ImageContent
MCP image content object

​
Resource References

​
create_resource_reference()

Create a reference to a resource without embedding its content. 
from fast_agent.mcp.resource_utils import create_resource_reference

# Reference external resource
ref = create_resource_reference(
    uri="https://example.com/large-file.pdf",
    mime_type="application/pdf"
)

msg = Prompt.user("Summarize this document:", ref)
​
uri
AnyUrl | str
required
URI for the resource (will be fetched separately)
​
mime_type
str
required
MIME type of the referenced resource
​
reference
EmbeddedResource
Resource reference (client will fetch content via URI)
Resource references create an EmbeddedResource that points to the URI. The MCP client will make a separate request to fetch the resource content when needed.

​
URI Utilities

​
normalize_uri()

Normalize a URI or filename to ensure it’s a valid URI. 
from fast_agent.mcp.resource_utils import normalize_uri

# Convert filename to file:// URI
uri = normalize_uri("document.pdf")
# Result: "file:///document.pdf"

# Handle absolute paths
uri = normalize_uri("/home/user/file.txt")
# Result: "file:///home/user/file.txt"

# Pass through existing URIs
uri = normalize_uri("https://example.com/file.pdf")
# Result: "https://example.com/file.pdf"
​
uri_or_filename
str
required
URI string or simple filename
​
uri
str
Properly formatted URI string

​
create_resource_uri()

Create a resource URI from a file path. 
from fast_agent.mcp.resource_utils import create_resource_uri

uri = create_resource_uri("data/config.json")
# Result: resource://fast-agent/config.json
​
path
str
required
File path to convert to resource URI
​
uri
AnyUrl
Resource URI for the path

​
extract_title_from_uri()

Extract a readable title from a URI. 
from fast_agent.mcp.resource_utils import extract_title_from_uri
from pydantic import AnyUrl

uri = AnyUrl("https://example.com/docs/guide.pdf")
title = extract_title_from_uri(uri)
# Result: "guide.pdf"

uri = AnyUrl("file:///home/user/report.docx")
title = extract_title_from_uri(uri)
# Result: "report.docx"
​
uri
AnyUrl
required
URI to extract title from
​
title
str
Readable title (typically the filename)

​
MIME Type Detection

​
guess_mime_type()

Guess MIME type from file path or URL. 
from fast_agent.mcp.mime_utils import guess_mime_type

mime = guess_mime_type("document.pdf")
# Result: "application/pdf"

mime = guess_mime_type("image.png")
# Result: "image/png"

mime = guess_mime_type("data.json")
# Result: "application/json"
​
path
str
required
File path or URL to analyze
​
mime_type
str
Guessed MIME type (defaults to “application/octet-stream”)

​
is_image_mime_type()

Check if a MIME type represents an image. 
from fast_agent.mcp.mime_utils import is_image_mime_type

if is_image_mime_type("image/jpeg"):
    # Handle as image
    pass
​
mime_type
str
required
MIME type to check
​
is_image
bool
True if MIME type is an image type

​
is_binary_content()

Check if a MIME type represents binary content. 
from fast_agent.mcp.mime_utils import is_binary_content

if is_binary_content("application/pdf"):
    # Read as binary and base64 encode
    pass
else:
    # Read as text
    pass
​
mime_type
str
required
MIME type to check
​
is_binary
bool
True if content should be treated as binary

​
Reading MCP Resources

​
get_resource_text()

Extract text from a ReadResourceResult. 
from fast_agent.mcp import get_resource_text

# Read resource from MCP server
result = await session.read_resource(uri="file:///data.txt")

# Extract text content
text = get_resource_text(result, index=0)
if text:
    print(text)
​
result
ReadResourceResult
required
Result from reading an MCP resource
​
index
int
default:"0"
Index of content to extract (if multiple contents)
​
text
str | None
Extracted text content, or None if not text
Raises IndexError if index is out of bounds for the contents list.

​
Resource Markers

​
parse_resource_marker()

Parse resource marker text into an embedded resource. 
from fast_agent.mcp.resource_utils import parse_resource_marker

# Parse marker text from message
marker_text = """[Resource: file.json, MIME: application/json]
{"key": "value"}"""

resource = parse_resource_marker(marker_text)
if resource:
    # Use the embedded resource
    pass
​
text
str
required
Marker text to parse (format: [Resource: path, MIME: type]\ncontent)
​
resource
EmbeddedResource | None
Parsed embedded resource, or None if not a valid marker

​
Example: Complete Resource Workflow

from fast_agent import Prompt
from fast_agent.mcp.resource_utils import (
    load_resource_content,
    create_embedded_resource,
    create_image_content
)
from pathlib import Path
import base64

# Load a text resource
text_content, mime, is_binary = load_resource_content(
    resource_path="config.json",
    prompt_files=[Path("prompt.txt")]
)
text_resource = create_embedded_resource(
    resource_path="config.json",
    content=text_content,
    mime_type=mime,
    is_binary=False
)

# Load an image
with open("diagram.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")
image = create_image_content(
    data=image_data,
    mime_type="image/png"
)

# Create message with both resources
message = Prompt.user(
    "Analyze this configuration and diagram:",
    text_resource,
    image
)

# Use in agent
response = await agent.run(message)

​
Example: Resource References for Large Files

from fast_agent import Prompt
from fast_agent.mcp.resource_utils import create_resource_reference

# Reference large external files without embedding
file_ref = create_resource_reference(
    uri="https://cdn.example.com/large-dataset.csv",
    mime_type="text/csv"
)

video_ref = create_resource_reference(
    uri="https://example.com/training-video.mp4",
    mime_type="video/mp4"
)

# Client will fetch these separately as needed
message = Prompt.user(
    "Analyze this dataset and watch the training video:",
    file_ref,
    video_ref
)

​
Example: Reading from MCP Servers

from fast_agent.mcp.gen_client import connect
from fast_agent.mcp import get_resource_text

# Connect to MCP server
session = await connect("filesystem", registry)

# Read resource
result = await session.read_resource(
    uri="file:///workspace/README.md"
)

# Extract text
readme_text = get_resource_text(result)
if readme_text:
    # Use in agent
    message = Prompt.user(
        f"Here's the README:\n\n{readme_text}\n\nSummarize it."
    )
    response = await agent.run(message)

​
Best Practices

Use create_resource_reference() for large files to avoid embedding the entire content in messages. The MCP client will fetch the content only when needed.
Always base64-encode binary content before passing it to create_blob_resource() or create_image_content(). Use Python’s base64.b64encode() for this.
When using load_resource_content(), the function automatically determines if content is binary based on MIME type and handles encoding appropriately.

​
Common MIME Types

File TypeMIME Type
Texttext/plain
JSONapplication/json
PDFapplication/pdf
JPEG Imageimage/jpeg
PNG Imageimage/png
MP4 Videovideo/mp4
MP3 Audioaudio/mpeg
CSVtext/csv
HTMLtext/html
Markdowntext/markdown

MCP Client

Connect to MCP servers

Prompts

Create conversation messages

Build docs developers (and LLMs) love

Get started for freeTalk to us