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 mesmo depois que o ambiente expirar.

Enviar arquivos

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

Use type: "file_id" com um file_id da API de arquivos ou type: "inline" com os dados codificados em base64 no campo data. As duas opções exigem um path.

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

Resolver erros de envio

Ao verificar os arquivos durante a criação de uma sessão ou ao anexar um arquivo, a API pode retornar HTTP 429 com files_api_rate_limit_exceeded. Consulte os limites de taxa da API de arquivos para ver a resposta e saber como prosseguir.

Se a API retornar HTTP 400, use error.param e error.message para identificar qual entrada corrigir. Por exemplo, se o destino estiver fora de /workspace, a API retornará a resposta abaixo.

12345678{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request_error",
    "message": "path must be an absolute POSIX path inside /workspace",
    "param": "path"
  }
}

O parâmetro segue a estrutura da requisição. Na tabela, i representa o índice do arquivo. O primeiro arquivo tem índice 0.

Use dados base64 e IDs de arquivo válidos e escolha um caminho absoluto dentro de /workspace. Confira os limites de arquivos. A API retorna HTTP 400 se o destino já existir, se o caminho passar por um link simbólico ou se algum componente do caminho for longo demais.

Se ocorrer um erro inesperado durante a instalação de um arquivo, a API retornará HTTP 500. Antes de tentar novamente, verifique se o destino foi criado e siga as orientações para novas tentativas.

Recuperar seus arquivos

Do seu próprio ambiente

Peça ao agente para gravar o resultado em um caminho conhecido. Quando 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 que você o exclua.

A API de artefatos não publica arquivos de ambientes auto-hospedados, inclusive os que estão em /workspace/outputs. Consulte Provedores de sandbox para saber como acessar arquivos com 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. Quando o turno termina, a OpenAI publica os arquivos de saída como artefatos imutáveis.

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

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}")

Para conhecer os campos de requisição e resposta, consulte a documentação das operações Listar artefatos, Recuperar metadados e Baixar conteúdo.

Baixar vários arquivos

A API permite baixar um artefato por requisição e não oferece um endpoint para 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 dentro de /workspace/outputs. Depois, baixe o ZIP como um único artefato.

Tempo de retenção dos arquivos

Os artefatos publicados continuam disponíveis depois que o ambiente expira. Antes de excluir a sessão, baixe tudo o que precisar guardar.

Esta API não permite enviar nem editar artefatos. 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