Adicionando arquivos

Você pode fornecer arquivos ao seu agente fazendo upload deles por meio da Files API e montando-os no sandbox da sessão.

Fazendo upload de arquivos

Primeiro, faça upload de um arquivo usando a Files API:

file = client.files.upload(file=Path("data.csv"))
print(f"File ID: {file.id}")

Montando arquivos em uma sessão

Monte os arquivos enviados no sandbox adicionando-os ao array resources ao criar uma sessão:

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "file",
            "file_id": file.id,
            "mount_path": "/data.csv",
        },
    ],
)

Com o mount_path anterior, o agente lê o arquivo em /mnt/session/uploads/data.csv (consulte Caminhos de arquivos).

Um novo file_id é criado, referenciando a instância do arquivo na sessão. Essas cópias não contam para os seus limites de armazenamento.

Múltiplos arquivos

Monte múltiplos arquivos adicionando entradas ao array resources:

resources = [
    {"type": "file", "file_id": "file_abc123", "mount_path": "/data.csv"},
    {"type": "file", "file_id": "file_def456", "mount_path": "/config.json"},
    {"type": "file", "file_id": "file_ghi789", "mount_path": "/src/main.py"},
]

É suportado um máximo de 500 arquivos por sessão.

Gerenciando arquivos em uma sessão em execução

Você pode adicionar ou remover arquivos de uma sessão após a criação usando a API de recursos da sessão. Cada recurso tem um id retornado quando é adicionado (ou listado), que você usa para exclusões.

resource = client.beta.sessions.resources.add(
    session.id,
    type="file",
    file_id=file.id,
)
print(resource.id)  # "sesrsc_01ABC..."

Liste todos os recursos de uma sessão com resources.list. Para remover um arquivo, chame resources.delete com o ID do recurso:

listed = client.beta.sessions.resources.list(session.id)
for entry in listed.data:
    print(entry.id, entry.type)

client.beta.sessions.resources.delete(resource.id, session_id=session.id)

Listando e baixando arquivos da sessão

Use a Files API para listar arquivos com escopo de uma sessão e baixá-los. Os arquivos que o agente grava em /mnt/session/outputs/ aparecem na lista pouco depois de o agente terminar de gravá-los, às vezes alguns segundos após a sessão ficar ociosa. Se um arquivo de saída esperado estiver faltando, liste novamente após um breve intervalo; assim que ele aparecer na lista, seu upload terá sido concluído.

Filtrar por scope_id requer o cabeçalho beta managed-agents-2026-04-01, portanto os exemplos de listagem usam o namespace beta de arquivos e passam esse cabeçalho explicitamente.

# Listar arquivos associados a uma sessão
files = client.beta.files.list(
    scope_id="sesn_abc123",
    betas=["managed-agents-2026-04-01"],
)
for file in files:
    print(file.id, file.filename)

# Baixar um arquivo
content = client.files.download(files.data[0].id)
content.write_to_file("output.txt")

Tipos de arquivo suportados

O agente pode trabalhar com qualquer tipo de arquivo, incluindo:

• Código-fonte (.py, .js, .ts, .go, .rs e outros)
• Arquivos de dados (.csv, .json, .xml, .yaml)
• Documentos (.txt, .md)
• Arquivos compactados (.zip, .tar.gz) - o agente pode extraí-los usando bash
• Arquivos binários - o agente pode processá-los com as ferramentas apropriadas

Caminhos de arquivos

• O caminho que você especifica tem como raiz o diretório de uploads da sessão: um mount_path de /data.csv coloca o arquivo em /mnt/session/uploads/data.csv no sandbox
• Se você omitir mount_path, o arquivo é colocado em /mnt/session/uploads/<file_id>
• Os diretórios pai são criados automaticamente
• Os caminhos devem ser absolutos (começando com /)
• Os arquivos que o agente grava em /mnt/session/outputs/ ficam disponíveis por meio da Files API, com escopo da sessão; consulte Listando e baixando arquivos da sessão