Tutorial 4: Downloading agent-generated files
=============================================

Overview
--------

This tutorial shows you how to use the **h2oGPTe** Python client to download files that `agents <https://docs.h2o.ai/enterprise-h2ogpte/guide/agents>`_ generate during chat sessions. You can use this process to retrieve documents, images, code, or other files that agents create.

What you'll learn
-----------------

- How to retrieve and download files generated by **h2oGPTe** agents
- How to handle file download errors
- How to manage local file storage

Prerequisites
-------------

Before you begin, make sure you have:

   - the h2oGPTe Python library installed
   - a global API key and endpoint URL
   - **h2oGPTe** v1.6.29 or later

Install the h2oGPTe library
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Install the library using pip:

.. code-block:: bash

   pip install h2ogpte

Get your API credentials
~~~~~~~~~~~~~~~~~~~~~~~~

Requirements:

   - An API key.
   - The endpoint URL for your h2oGPTe instance. The ``address`` should be where the API key was created.

To create a global API key, see `Create an API key <https://docs.h2o.ai/enterprise-h2ogpte/guide/apis#create-an-api-key>`_.

.. note::

   Make sure the agent tool you want to use is configured and available in your h2oGPTe environment. Some tools require additional setup.
   For more information, see `Agents tool documentation <https://docs.h2o.ai/enterprise-h2ogpte/guide/agents#toolss>`_ .

Download agent-generated files
------------------------------

1. Create a client connection
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   from h2ogpte import H2OGPTE
   import json

   client = H2OGPTE(
       address='https://h2ogpte.genai.h2o.ai',
       api_key='sk-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
   )

Replace the ``address`` and ``api_key`` values with your actual endpoint and API key.

2. Start a chat session
~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   chat_session_id = client.create_chat_session()

3. Send a prompt to generate a file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   with client.connect(chat_session_id) as session:
       reply = session.query(
           message='Generate an image of a zebra in a tophat', # The prompt for the agent
           timeout=60,
           llm_args={"use_agent": True}  # Enable agent tools for this query
       )

4. Get the file references
~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

   import json

   agent_files = client.list_chat_message_meta_part(reply.id, "agent_files").content
   agent_files = json.loads(agent_files)

The ``agent_files`` variable contains a list of dictionaries that map document IDs to filenames. For example:

.. code-block:: json

   [
       {"document_id1": "image_filename.png"},
       {"document_id2": "output.pdf"}
   ]

5. Download the files
~~~~~~~~~~~~~~~~~~

.. code-block:: python

   for f in agent_files:
    doc_id = list(f.keys())[0]
    doc_name = f[doc_id]

    print(f"Attempting to download: {doc_name} (ID: {doc_id})")
    
    try:
        client.download_document("./", doc_name, doc_id)
        print(f"SUCCESS: Downloaded {doc_name} to current folder.")
    except Exception as e:
        print(f"FAILED to download {doc_name}: {e}")


The ``download_document()`` method saves files to the specified directory. Make sure you have write permissions for the target directory.

.. note::

   **Important considerations**

   - The ``agent_files`` list might be empty if the agent didn't generate any files. Make sure the agent tool is enabled and configured correctly.
   - Always store API keys securely. Don't share your API key or expose it in client-side code.
   - You can change the download path by modifying the first parameter of ``download_document()``.


What's next
-----------

- Learn about `available agent tools <https://docs.h2o.ai/enterprise-h2ogpte/guide/agents#tools>`_
- Learn about `custom agent tools  <https://docs.h2o.ai/enterprise-h2ogpte/tutorials/tutorial-9>`_
- Read the `Agents documentation <https://docs.h2o.ai/enterprise-h2ogpte/guide/agents>`_
- Explore the `Python API reference <https://h2oai.github.io/h2ogpte/python_api.html>`_