Files

A file asset is a local file, folder or URL that you upload once and attach to any agent. To have an agent save its outputs as downloadable files, use the File manager tool.

Attached files are part of the agent's definition, so every run can read them with no per-run upload. For media that belongs to one run only, use attachments on agent.run() instead (see Agents).

Try it

from pathlib import Path
from aixplain import Aixplain

aix = Aixplain(api_key="YOUR_API_KEY")

Path("prices.csv").write_text("plan,monthly_price\nStarter,24\nTeam,99\nEnterprise,custom\n")

prices = aix.File("prices.csv").save()

agent = aix.Agent(
    name="Pricing assistant",
    description="Answers pricing questions from the attached price list.",
    instructions="Read the reference files attached to you before you answer. Quote the exact price.",
    files=[prices],
).save()

result = agent.run("How much is the Team plan per month?")
print(result.data.output)

Show output

The agent reads attached files with built-in file tools, under a reference_files/ folder. Tell it in instructions to read its reference files, or it may answer without opening them.

Save every file before you save the agent. An unsaved aix.File raises ValueError: All files must be saved before saving the agent.

Upload a folder

Pass a directory and the whole tree, including subfolders, is uploaded as one asset. aix.File.get() returns the tree.

Path("policies/regional").mkdir(parents=True, exist_ok=True)
Path("policies/security.txt").write_text("Use least privilege for every account.\n")
Path("policies/regional/eu.txt").write_text("Store EU customer data in EU regions only.\n")

handbook = aix.File("policies", name="Policy handbook").save()

def print_tree(item, indent=0):
    print("  " * indent + item.name + ("/" if item.is_dir else ""))
    for child in item.children:
        print_tree(child, indent + 1)

print_tree(aix.File.get(handbook.id))

Show output

You can also pass a public http or https URL as the source. The file is fetched and stored when you call .save().

Attach files to an agent

files takes File objects or file IDs. A folder gives the agent every file in it.

agent = aix.Agent(
    name="Policy assistant",
    description="Answers questions from the policy handbook.",
    instructions="Read the reference files attached to you before you answer. Quote the policy text.",
    files=[handbook],
).save()

print(aix.Agent.get(agent.id).files == [handbook.id])

result = agent.run("Where must EU customer data be stored?")
print(result.data.output)

Show output

Find and download files

aix.File.search() returns a page of your top-level file assets. Filter by name with query, or by kind with file_type.

page = aix.File.search(query="Policy", file_type=aix.FileType.FOLDER, page_size=5)
for item in page.results:
    print(item.name, item.file_type)

print(prices.download("downloads/prices.csv"))
print(handbook.download("downloads/policies"))

Show output

A folder downloads as one ZIP request and is extracted for you, with its subfolders intact.

Known limitations

• File.url can be None. Read a file's contents with download().
• There is no File.delete() method in the SDK.
• A file ID is not accepted as a run input. agent.run(attachments=[...]) takes URLs or local paths only. Attach file assets to the agent with files=[...].

Reference

Parameter	Type	Default	Description
source	str	required	A local file path, a local directory, or an http or https URL. Pass it positionally.
name	str	from source	Display name. Root file names must be unique in your workspace.

Attribute	Description
id	File ID, set by .save().
file_type	aix.FileType.FILE or aix.FileType.FOLDER.
is_dir	True for folders.
children	Files and subfolders, filled in by aix.File.get().
size, extension	Size in bytes and file suffix, for local files.

Method	What it does
aix.File(source, name=...).save()	Upload a file, folder or URL.
aix.File.get(id)	Get a file or a folder tree. Pass recursive=False for one level only.
aix.File.search(query=..., file_type=...)	List your file assets as a page.
file.download(path)	Save a file, or extract a folder, to disk.

Next steps

• Knowledge base: search large document sets by meaning instead of attaching them whole.
• Agents: combine files with tools, skills and an LLM.
• API reference: file: every parameter and method.