Attachments

Attach PDFs, audio, text, video, URLs and Path objects to an agent — no silent drops

Pass any file — image, PDF, audio, text, video, a URL, a data: URI, or a pathlib.Path — to agent.start(...) and the router turns it into a model-visible part or tells you why it could not.

from praisonaiagents import Agent

agent = Agent(instructions="Describe what you are given.", llm="gpt-4o")
agent.start("What is in this image?", attachments=["photo.png"])

An attachment is never dropped silently: it either becomes a content part the model sees, or it raises, or it warns and leaves a marker part in the prompt so the model can say it answered without the file.

Quick Start

1. Attach an image at start()

   from praisonaiagents import Agent
   
   agent = Agent(instructions="Describe images.", llm="gpt-4o")
   agent.start("What landmark is this?", attachments=["photo.png"])

2. Attach a PDF at chat()

   from praisonaiagents import Agent
   
   agent = Agent(instructions="Summarise documents.", llm="gpt-4o")
   agent.chat("Summarise this report.", attachments=["report.pdf"])

   A PDF-capable model receives the document as a file part; a non-PDF model gets locally-extracted text, labelled as extracted.

3. Mix file types in one list

   from pathlib import Path
   from praisonaiagents import Agent
   
   agent = Agent(instructions="Analyse everything I send.", llm="gpt-4o")
   agent.chat(
       "Review these together.",
       attachments=[
           Path("report.pdf"),
           "clip.mp3",
           "https://example.com/photo.png",
       ],
   )

   Each entry is routed independently by its type — a Path, a local file, and a URL in the same call.

How the router decides

The router inspects each attachment’s extension, checks the target model’s capability, and picks one of three outcomes.

What each file type does

The outcome depends on the file type and the target model’s capability.

What raises vs what warns

Two failure classes are treated differently on purpose.

from praisonaiagents import Agent
from praisonaiagents.agent.attachments import AttachmentError

agent = Agent(instructions="Describe files.", llm="gpt-4o")

# Missing path, a directory, an unreadable file, or an unsupported
# Python type all raise AttachmentError — a caller mistake with no
# useful degraded answer.
try:
    agent.start("Describe it", attachments=["does-not-exist.png"])
except AttachmentError as e:
    print(e)
    # does-not-exist.png: no such file (attachment paths are resolved
    # relative to the current working directory '/home/you/project')

from praisonaiagents import Agent

# gpt-4o cannot accept audio. The file is fine; the model can't ingest it.
# The router logs a warning AND injects a marker part so the model can
# answer and say the audio was withheld — the run still succeeds.
agent = Agent(instructions="Transcribe or describe.", llm="gpt-4o")
agent.start("What does the clip say?", attachments=["clip.mp3"])
# WARNING ... model 'gpt-4o' cannot accept audio input (use an
#   audio-capable model such as gpt-4o-audio-preview or a Gemini model,
#   or transcribe the file first)
# Prompt gains: [Attachment omitted: clip.mp3 - audio was not sent ...]

Capability helpers

Check what a model can ingest before you attach — the same probes the router uses.

from praisonaiagents.llm.model_capabilities import (
    supports_vision,
    supports_pdf_input,
    supports_audio_input,
)

supports_pdf_input("gpt-4o")                  # False
supports_pdf_input("gemini/gemini-1.5-pro")   # True
supports_audio_input("gpt-4o-audio-preview")  # True
supports_vision("gpt-4o")                     # True

Error handling

AttachmentError subclasses ValueError, so any existing except ValueError around chat() keeps catching it.

from praisonaiagents import Agent
from praisonaiagents.agent.attachments import AttachmentError

agent = Agent(instructions="Batch describe files.", llm="gpt-4o")

paths = ["a.png", "missing.png", "b.png"]
for path in paths:
    try:
        print(agent.chat("Describe this.", attachments=[path]))
    except AttachmentError as e:
        # Message names the path AND the current working directory:
        #   missing.png: no such file (attachment paths are resolved
        #   relative to the current working directory '/home/you/project')
        print(f"Skipping {path}: {e}")

Best Practices

Related