Arquivos e artefatos

Arquivos e artefatos publicados

Os arquivos ficam no ambiente do agente. Um artefato é uma cópia publicada de um arquivo de um ambiente hospedado pela OpenAI. Você pode baixar essa cópia depois que o ambiente expirar.

Enviar arquivos

Para um ambiente hospedado pela OpenAI, forneça os arquivos de entrada em environment.files ao criar a sessão. Escolha o destino de cada arquivo dentro de /workspace.

Use type: "file_id" com um file_id da API Files, ou type: "inline" com data codificado em base64. Ambas as formas exigem um path.

Para adicionar arquivos depois que o ambiente se conectar, use a API Files do ambiente.

Recuperar seus arquivos

Do seu próprio ambiente

Peça ao agente para gravar a saída em um caminho conhecido. Depois que o turno terminar, recupere o arquivo por meio do seu provedor ou da sua infraestrutura. Salve o arquivo no armazenamento do seu aplicativo antes que o ambiente expire ou você o exclua.

Arquivos de ambientes auto-hospedados não são publicados pela API Artifacts, incluindo os arquivos em /workspace/outputs. Consulte Provedores de sandbox para saber como acessar arquivos em cada provedor.

De um ambiente hospedado pela OpenAI

Peça ao agente para salvar o arquivo em /workspace/outputs, por exemplo, em /workspace/outputs/report.pdf. A OpenAI publica as saídas como artefatos imutáveis quando o turno termina.

Passe o cliente da API, o ID da sessão, o ID do turno concluído, o caminho do artefato e o destino local para esta função. Ela lista os artefatos e baixa o arquivo que corresponde tanto ao turno quanto ao caminho:

1
2
3
4
5
6
7
8
9
10
11# Pass the saved session ID, completed turn ID, artifact path, and local destination.
def download_artifact(client, session_id, turn_id, path, destination):
    for artifact in client.beta.agents.sessions.artifacts.list(session_id):
        if artifact.turn_id != turn_id or artifact.path != path:
            continue
        with client.beta.agents.sessions.artifacts.with_streaming_response.content(
            artifact.id, session_id=session_id
        ) as response:
            response.stream_to_file(destination)
        return
    raise FileNotFoundError(f"No artifact for {path!r} in turn {turn_id}")

Consulte as referências de Listar artefatos, Recuperar metadados e Baixar conteúdo para ver os campos de requisição e resposta.

Baixar vários arquivos

A API baixa um artefato por requisição; ela não oferece um endpoint de download em lote. Para baixar vários arquivos, liste os artefatos e solicite o content de cada arquivo. Para fazer um único download, peça ao agente para reunir os resultados em um arquivo ZIP em /workspace/outputs e depois baixe esse arquivo como um único artefato.

Tempo de vida dos arquivos

Os artefatos publicados continuam disponíveis depois que o ambiente expira. Baixe tudo o que você precisa manter antes de excluir a sessão.

Não é possível enviar ou editar artefatos por meio desta API. Para publicar uma nova versão, peça ao agente para atualizar o arquivo e concluir outro turno. Use o ID do turno e o caminho para distinguir as versões.

Exclua um artefato quando não precisar mais da cópia publicada. A exclusão mantém intacto o arquivo no ambiente.

Limites de arquivos