File Processing

Attach files to agent runs, reuse artifacts from prior attachments, and manage chunk IDs for long-form analysis. Reach for this guide when agents need to consume documents, transcripts, or datasets with the Python SDK. CLI support exists for common flows. REST is reference-only.

File-handling support is summarised in the AIP capability matrix. The main limitation today is regenerating presigned URLs. Use the REST reference endpoint when a URL expires.

aip agents run accepts either an agent ID or a unique name. Use --select to pick from partial name matches or provide the ID directly when scripting.

Attach Files to an Agent Run

When to use: Collect fresh documents from users or pipelines and supply them during execution.

Local Document Processing: For local execution, you can use document loader tools like PDFReaderTool, DocxReaderTool, and ExcelReaderTool from aip-agents to read files directly from disk without uploading to the server. Attach the file in the same run so the tool has access to it. See the Local vs Remote guide for the document loader tools quickstart and example (main_with_docproc_pdf.py).

Python SDK

from glaip_sdk import Agent

agent = Agent(name="analysis-agent", instruction="You analyze documents.")

response = agent.run(
    "Summarise the document and extract key metrics",
    files=["./reports/q1.pdf", "./reports/q2.pdf"],
)
print(response)

CLI

aip agents run analysis-agent \
  --input "Summarise these reports" \
  --file reports/q1.pdf \
  --file reports/q2.pdf \
  --view json > summary.json

Common attachment errors

Symptom	Likely cause	Fix
413 Payload Too Large	File exceeds backend attachment/upload limits.	Compress the file or split it into smaller chunks.
Missing file in run logs	File path incorrect or permissions denied.	Double-check the path, ensure the process can read the file, or use absolute paths.
Duplicate chunks created	Run attaches files without reusing artifact_id.	Pass the stored chunk IDs using the reuse workflows in the next section.
Unsupported media type errors	File type not allowed for ingestion.	Convert to a supported format (PDF, TXT, DOCX) or register a custom ingestion pipeline.

Reuse Chunk IDs from Prior Attachments

When to use: Avoid re-ingesting the same files while keeping chunk IDs stable across runs.

When the backend returns chunk_ids, store them for later runs:

chunk_ids = ["chunk-abc", "chunk-def"]
agent.run(
    "Compare the latest reports with previous attachments",
    chunk_ids=chunk_ids,
)

CLI support for passing chunk_ids is coming soon. Use the SDK today to avoid re-attaching large files (REST is reference-only).

Retrieve Artifacts and Output

When to use: Capture the processed results, enriched files, or generated reports after execution.

1. Capture the run ID from the streaming response (X-Run-ID).

2. List run history with the SDK:

   from glaip_sdk import Client
   
   client = Client()
   runs = client.agents.runs.list_runs(agent_id="agent-id", limit=20, page=1)
   print([r.id for r in runs.data])

3. Download artifacts directly from the presigned URLs in the response. If a URL has expired, regenerate it using the REST reference utilities (internal integrations only): Utilities.

Best Practices

When to use: Create organisation-wide guardrails for storage, retention, and compliance.

• Compress large files — keep attachments efficient and within allowable limits.

• Track chunk IDs — store them alongside run metadata so you can reference prior attachments without retransmitting data.

• Sanitise inputs — redaction or PII masking should occur before attaching sensitive documents; see the Security & privacy guide.

• Automate clean-up — if you are storing artifacts locally for auditing, ensure rotation policies are in place.

Related Documentation

• Local vs Remote — local vs remote file processing comparison and built-in tools overview.

• Agents guide — streaming behaviour and runtime overrides.

• Automation & scripting — capture outputs in CI pipelines.

• Configuration management — export/import agents that rely on file workflows.