azure-ai-projects 1.0.0__tar.gz

azure_ai_projects-1.0.0/AGENTS_MIGRATION_GUIDE.md

@@ -0,0 +1,519 @@
+# Agents migration guide from Hub-based projects to Endpoint-based projects
+
+This guide describes migration from hub-based to Endpoint-based projects. To create a Endpoint-based project, please use one of the deployment scripts on [foundry samples repository](https://github.com/azure-ai-foundry/foundry-samples/tree/main/samples/microsoft/infrastructure-setup) appropriate for your scenario, also you can use Azure AI Foundry UI. The support of hub-based projects was dropped in `azure-ai-projects` version `1.0.0b11`. In this document, we show the operation implementation of before `1.0.0b11` in **Hub-based** section, followed by code for `azure-ai-projects` version `1.0.0b11` or later in **Endpoint-based**.
+
+## Import changes
+
+| Hub-based | Endpoint-based |
+|-|-|
+| `azure.ai.projects` | `azure.ai.projects` |
+| `azure.ai.projects.models` | `azure.ai.agents.models` |
+| Agents were moved to a new package. | `azure.ai.agents` |
+
+## Class structure changes
+
+Agents Operations
+
+| Hub-based | Endpoint-based |
+|-|-|
+| `project_client.agents.create_agent` | `project_client.agents.create_agent` |
+| `project_client.agents.list_agents` | `project_client.agents.list_agents` |
+| `project_client.agents.get_agent` | `project_client.agents.get_agent` |
+| `project_client.agents.update_agent` | `project_client.agents.update_agent` |
+| `project_client.agents.delete_agents` | `project_client.agents.delete_agent` |
+| `project_client.agents.create_thread_and_run` | `project_client.agents.create_thread_and_run` |
+| `project_client.agents.enable_auto_function_calls` | `project_client.agents.enable_auto_function_calls` |
+| The new method was added in new SDK version. | `project_client.agents.create_thread_and_process_run` |
+
+Threads Operations
+
+| Hub-based | Endpoint-based |
+|-|-|
+| `project_client.agents.create_thread` | `project_client.agents.threads.create` |
+| `project_client.agents.get_thread` | `project_client.agents.threads.get` |
+| `project_client.agents.update_thread` | `project_client.agents.threads.update` |
+| `project_client.agents.list_threads` | `project_client.agents.threads.list` |
+| `project_client.agents.delete_thread` | `project_client.agents.threads.delete` |
+
+Messages Operations
+
+| Hub-based | Endpoint-based |
+|-|-|
+| `project_client.agents.create_message` | `project_client.agents.messages.create` |
+| `project_client.agents.list_messages` | `project_client.agents.messages.list` |
+| `project_client.agents.get_message` | `project_client.agents.messages.get` |
+| `project_client.agents.update_message` | `project_client.agents.messages.update` |
+| `OpenAIPageableListOfThreadMessage.get_last_message_by_role` | `project_client.agents.messages.get_last_message_by_role` |
+| `OpenAIPageableListOfThreadMessage.get_last_text_message_by_role` | `project_client.agents.messages.get_last_message_text_by_role` |
+
+Runs Operations
+
+| Hub-based | Endpoint-based |
+|-|-|
+| `project_client.agents.create_run` | `project_client.agents.runs.create` |
+| `project_client.agents.get_run` | `project_client.agents.runs.get` |
+| `project_client.agents.list_run` | `project_client.agents.runs.list` |
+| `project_client.agents.update_run` | `project_client.agents.runs.update` |
+| `project_client.agents.create_and_process_run` | `project_client.agents.runs.create_and_process` |
+| `project_client.agents.create_stream` | `project_client.agents.runs.stream` |
+| `project_client.agents.submit_tool_outputs_to_run` | `project_client.agents.runs.submit_tool_outputs` |
+| `project_client.agents.submit_tool_outputs_to_run` | `project_client.agents.runs.submit_tool_outputs_stream` |
+| `project_client.agents.cancel_run` | `project_client.agents.runs.cancel` |
+
+Run Steps Operations
+
+| Hub-based | Endpoint-based |
+|-|-|
+| `project_client.agents.get_run_step` | `project_client.agents.run_steps.get` |
+| `project_client.agents.list_run_steps` | `project_client.agents.run_steps.list` |
+
+Vector Stores Operations
+
+| Hub-based | Endpoint-based |
+|-|-|
+| `project_client.agents.create_vector_store_and_poll` | `project_client.agents.vector_stores.create_and_poll |
+| `project_client.agents.create_vector_store` | `project_client.agents.vector_stores.create |
+| `project_client.agents.list_vector_stores` | `project_client.agents.vector_stores.list |
+| `project_client.agents.get_vector_store` | `project_client.agents.vector_stores.get |
+| `project_client.agents.modify_vector_store` | `project_client.agents.vector_stores.modify |
+| `project_client.agents.delete_vector_store` | `project_client.agents.vector_stores.delete |
+
+Vector Store Files Operations
+
+| Hub-based | Endpoint-based |
+|-|-|
+| `project_client.agents.create_vector_store_file_and_poll` | `project_client.agents.vector_store_files.create_and_poll` |
+| `project_client.agents.list_vector_store_files` | `project_client.agents.vector_store_files.list` |
+| `project_client.agents.create_vector_store_file` | `project_client.agents.vector_store_files.create` |
+| `project_client.agents.get_vector_store_file` | `project_client.agents.vector_store_files.get` |
+| `project_client.agents.delete_vector_store_file` | `project_client.agents.vector_store_files.delete` |
+
+Vector Store File Batches Operations
+
+| Hub-based | Endpoint-based |
+|-|-|
+| `project_client.agents.create_vector_store_file_and_poll` | `project_client.agents.vector_store_file_batches.create_and_poll`|
+| `project_client.agents.create_vector_store_file_batch` | `project_client.agents.vector_store_file_batches.create`|
+| `project_client.agents.get_vector_store_file_batch` | `project_client.agents.vector_store_file_batches.get`|
+| `project_client.agents.list_vector_store_file_batch_files` | `project_client.agents.vector_store_file_batches.list_files`|
+| `project_client.agents.cancel_vector_store_file_batch` | `project_client.agents.vector_store_file_batches.cancel`|
+
+Files Operations
+
+| Hub-based | Endpoint-based |
+|-|-|
+| `project_client.agents.upload_file_and_poll` | `project_client.agents.files.upload_and_poll` |
+| `project_client.agents.upload_file` | `project_client.agents.files.upload` |
+| `project_client.agents.save_file` | `project_client.agents.files.save` |
+| `project_client.agents.get_file` | `project_client.agents.files.get` |
+| `project_client.agents.list_files` | `project_client.agents.files.list` |
+| `project_client.agents.delete_file` | `project_client.agents.files.delete` |
+
+## API changes
+
+1. Create project. The connection string is replaced by the endpoint. The project endpoint URL has the form https://\<your-ai-services-account-name\>.services.ai.azure.com/api/projects/\<your-project-name\>. It can be found in your Azure AI Foundry Project overview page.
+
+    **Hub-based**
+
+    ```python
+    project_client = AIProjectClient.from_connection_string(
+        credential=DefaultAzureCredential(),
+        conn_str=connection_string,
+    )
+    ```
+
+    **Endpoint-based**
+
+    ```python
+    project_client = AIProjectClient(endpoint=endpoint, credential=DefaultAzureCredential())
+    ```
+
+2. Crate an agent. In the new versions of SDK, the agent can be created using project client or directly created by using `AgentsClient` constructor. In the code below, `project_client.agents`is an `AgentsClient` instance so `project_client.agents` and `agents_client` can be used interchangeably. For simplicity we will use ` project_client.agents `.
+
+    **Hub-based**
+
+    ```python
+    agent = project_client.agents.create_agent(
+        model= "gpt-4o",
+        name="my-assistant",
+        instructions="You are helpful assistant",
+    )
+    ```
+
+    **Endpoint-based**
+
+    Agent is instantiated using `AIProjectClient`
+
+    ```python
+    agent = project_client.agents.create_agent(
+        model="gpt-4o",
+        name="my-agent",
+        instructions="You are helpful agent",
+    )
+    ```
+
+    Agent is instantiated using `AgentsClient` constructor:
+
+    ```python
+    from azure.ai.agents import AgentsClient
+
+    agents_client = AgentsClient(
+        endpoint=connection_string,
+        credential=DefaultAzureCredential(),
+    )
+    agent = agents_client.create_agent(
+        model="gpt-4o",
+        name="my-agent",
+        instructions="You are helpful agent",
+    )
+    ```
+
+3. List agents. New version of SDK allows more convenient ways of listing threads, messages and agents by returning `ItemPaged` and `AsyncItemPaged`. The list of returned items is split by pages, which may be consequently returned to user. Below we will demonstrate this mechanism for agents. The `limit` parameter defines the number of items on the page. This example is also applicable for listing threads, runs, run steps, vector stores, files in vector store, and messages.
+
+    **Hub-based**
+
+    ```python
+    has_more = True
+    last_id = None
+    while has_more:
+        agents_list = project_client.agents.list_agents(after=last_id)
+        for agent in agents_list.data:
+            print(agent.id)
+        has_more = agents_list.has_more
+        last_id = agents_list.last_id
+    ```
+
+    **Endpoint-based**
+
+    ```python
+    agents = project_client.agents.list_agents(limit=2)
+     # Iterate items by page. Each page will be limited by two items.
+     for i, page in enumerate(agents.by_page()):
+             print(f"Items on page {i}")
+             for one_agent in page:
+                 print(one_agent.id)
+       
+    # Iterate over all agents. Note, the agent list object needs to be re instantiated, the same object cannot be reused after iteration.
+    agents = project_client.agents.list_agents(limit=2)
+    for one_agent in agents:
+             print(one_agent.id)
+    ```
+
+4. Delete agent. In versions azure-ai-projects 1.0.0b11, all deletion operations used to return deletion status, for example, deletion of agent was returning `AgentDeletionStatus`. In 1.0.0b11 and later, these operations do not return a value.
+
+    **Hub-based**
+
+    ```python
+    deletion_status = project_client.agents.delete_agent(agent.id)
+    print(deletion_status.deleted)
+    ```
+
+    **Endpoint-based**
+
+    ```python
+    project_client.agents.delete_agent(agent.id)
+    ```
+
+5. Create a thread.
+
+    **Hub-based**
+
+    ```python
+    thread = project_client.agents.create_thread()
+    ```
+
+    **Endpoint-based**
+
+    ```python
+    thread = project_client.agents.threads.create()
+    ```
+
+6. List threads.
+
+    **Hub-based**
+
+    ```python
+    with project_client:
+        last_id = None
+        has_more = True
+        page = 0
+        while has_more:
+            threads = project_client.agents.list_threads(limit=2, after=last_id)
+            print(f"Items on page {page}")
+            for thread in threads.data:
+                print(thread.id)
+            has_more = threads.has_more
+            last_id = threads.last_id
+            page += 1
+    ```
+
+    **Endpoint-based**
+
+    ```python
+    threads = project_client.agents.threads.list(limit=2)
+    # Iterate items by page. Each page will be limited by two items.
+    for i, page in enumerate(threads.by_page()):
+          print(f"Items on page {i}")
+          for thread in page:
+              print(thread.id)
+
+    # Iterate over all threads. Note, the thread list object needs to be re-instantiated, the same object cannot be reused after iteration.
+    threads = project_client.agents.threads.list(limit=2)
+    for thread in threads:
+        print(thread.id)
+    ```
+
+7. Delete the thread. In previous SDK thread deletion used to return ` ThreadDeletionStatus` object, while in new version it does not return value.
+
+    **Hub-based**
+
+    ```python
+    delete_status = project_client.agents.delete_thread(tread_id)
+    print(delete_status.deleted)
+    ```
+
+    **Endpoint-based**
+
+    ```python
+    project_client.agents.threads.delete(tread_id)
+    ```
+
+8. Create the message on a thread.
+
+    **Hub-based**
+
+    ```python
+    message = project_client.agents.create_message(thread_id=thread.id, role="user", content="The message text.")
+    ```
+
+    **Endpoint-based**
+
+    ```python
+    message = agents_client.messages.create(thread_id=thread.id, role="user", content=" The message text."")
+    ```
+
+9. Create and get the run.
+
+    **Hub-based**
+
+    ```python
+    run = project_client.agents.runs.create(thread_id=thread.id, agent_id=agent.id)
+    run = project_client.agents.get_run(thread_id=thread.id, run_id=run.id)
+    ```
+
+    **Endpoint-based**
+
+    ```python
+    run = project_client.agents.runs.create(thread_id=thread.id, agent_id=agent.id)
+    run = project_client.agents.runs.get(thread_id=thread.id, run_id=run.id)
+    ```
+
+10. List Runs.
+
+    **Hub-based**
+
+    ```python
+    has_more = True
+    last_id = None
+    while has_more:
+        runs_list = project_client.agents.list_runs(thread.id)
+        for one_run in runs_list.data:
+            print(one_run.id)
+        has_more = runs_list.has_more
+        last_id = runs_list.last_id
+    ```
+
+    **Endpoint-based**
+
+    ```python
+    runs = project_client.agents.runs.list(thread.id)
+    for one_run in runs:
+        print(one_run.id)
+    ```
+
+11. List Run steps.
+
+    **Hub-based**
+
+    ```python
+    has_more = True
+    last_id = None
+    while has_more:
+        runs_step_list = project_client.agents.list_run_steps(thread.id, run.id)
+        for one_run_step in runs_step_list.data:
+            print(one_run_step.id)
+        has_more = runs_step_list.has_more
+        last_id = runs_step_list.last_id
+    ```
+
+    **Endpoint-based**
+
+    ```python
+    run_steps = project_client.agents.run_steps.list(thread.id, run.id)
+    for one_run_step in run_steps:
+        print(one_run_step.id)
+    ```
+
+12. Using streams.
+
+    **Hub-based**
+
+    ```python
+    with project_client.agents.create_stream(thread_id=thread.id, agent_id=agent.id) as stream:
+        for event_type, event_data, func_return in stream:
+                print(f"Received data.")
+                print(f"Streaming receive Event Type: {event_type}")
+                print(f"Event Data: {str(event_data)[:100]}...")
+                print(f"Event Function return: {func_return}\n")
+    ```
+
+    **Endpoint-based**
+
+    ```python
+    with project_client.agents.runs.stream(thread_id=thread.id, agent_id=agent.id, event_handler=MyEventHandler()) as stream:
+            for event_type, event_data, func_return in stream:
+                print(f"Received data.")
+                print(f"Streaming receive Event Type: {event_type}")
+                print(f"Event Data: {str(event_data)[:100]}...")
+                print(f"Event Function return: {func_return}\n")
+    ```
+
+13. List messages.
+
+    **Hub-based**
+
+    ```python
+    messages = project_client.agents.list_messages(thread_id=thread.id)
+        # In code below we assume that the number of messages fits one page for brevity.
+        for data_point in reversed(messages.data):
+            last_message_content = data_point.content[-1]
+            if isinstance(last_message_content, MessageTextContent):
+                print(f"{data_point.role}: {last_message_content.text.value}")
+    ```
+
+    **Endpoint-based**
+
+    ```python
+    messages = project_client.agents.messages.list(thread_id=thread.id)
+        for msg in messages:
+            if msg.text_messages:
+                last_text = msg.text_messages[-1]
+                print(f"{msg.role}: {last_text.text.value}")
+    ```
+
+14. Create, list and delete files are now handled by file operations, again, delete call in new SDK version does not return a value.
+
+    **Hub-based**
+
+    ```python
+    # Create file
+    file = project_client.agents.upload_file_and_poll(file_path="product_info_1.md", purpose=FilePurpose.AGENTS)
+    # List and enumerate files
+    files = project_client.agents.list_files()
+        for one_file in files.data:
+            print(one_file.id)
+    # Delete file.
+    delete_status = project_client.agents.delete_file(file.id)
+    print(delete_status.deleted)
+    ```
+
+    **Endpoint-based**
+
+    ```python
+    # Create file
+    file = project_client.agents.files.upload_and_poll(file_path=asset_file_path, purpose=FilePurpose.AGENTS)
+    # List and enumerate files
+    files = project_client.agents.files.list()
+    for one_file in files.data:
+        print(one_file.id)
+    # Delete file.
+    project_client.agents.files.delete(file_id=file.id)
+    ```
+
+15. Create, list vector store files list and delete vector stores.
+
+    **Hub-based**
+
+    ```python
+    # Create a vector store with no file and wait for it to be processed
+        vector_store = project_client.agents.create_vector_store_and_poll(file_ids=[file.id], name="sample_vector_store")
+    # List vector stores
+    has_more = True
+    last_id = None
+    while has_more:
+        vector_store_list = project_client.agents.list_vector_stores(after=last_id)
+        for one_vector_store in vector_store_list.data:
+            print(one_vector_store.id)
+        has_more = vector_store_list.has_more
+        last_id = vector_store_list.last_id
+    # List files in the vector store.
+    has_more = True
+    last_id = None
+    while has_more:
+        vector_store_file_list = project_client.agents.list_vector_store_files(vector_store.id, after=last_id)
+        for one_file in vector_store_file_list.data:
+            print(one_file.id)
+        has_more = vector_store_file_list.has_more
+        last_id = vector_store_file_list.last_id
+    # Delete file from vector store
+    project_client.agents.delete_vector_store_file(vector_store.id, file.id)
+    # Delete vector store.
+    deletion_status = project_client.agents.delete_vector_store(vector_store.id)
+    print(deletion_status.deleted)
+    ```
+
+    **Endpoint-based**
+
+    ```python
+    # Create a vector store with no file and wait for it to be processed
+    vector_store = project_client.agents.vector_stores.create_and_poll(file_ids=[file.id], name="my_vectorstore")
+    # List vector stores
+    vector_store_list = project_client.agents.vector_stores.list()
+    for one_vector_store in vector_store_list:
+        print(one_vector_store.id)
+    # List files in the vector store.
+    vector_store_file_list = project_client.agents.vector_store_files.list(vector_store.id)
+    for one_file in vector_store_file_list:
+         print(one_file.id)
+    # Delete file from vector store
+    project_client.agents.vector_store_files.delete(vector_store.id, file.id)
+    # Delete vector store.
+    project_client.agents.vector_stores.delete(vector_store.id)
+    ```
+
+16. Vector store batch file search.
+
+    **Hub-based**
+
+    ```python
+    # Batch upload files
+    vector_store_file_batch = project_client.agents.create_vector_store_file_batch_and_poll(
+        vector_store_id=vector_store.id, file_ids=[file.id]
+    )
+    # List file in the batch
+    has_more = True
+    last_id = None
+    while has_more:
+        files = project_client.agents.list_vector_store_file_batch_files(vector_store.id, vector_store_file_batch.id, after=last_id)
+        for one_file in files.data:
+            print(one_file.id)
+        has_more = files.has_more
+        last_id = files.last_id
+    # Try to cancel batch upload
+    vector_store_file_batch = project_client.agents.cancel_vector_store_file_batch(vector_store.id, vector_store_file_batch.id)
+    ```
+
+    **Endpoint-based**
+
+    ```python
+    # Batch upload files
+    vector_store_file_batch = project_client.agents.vector_store_file_batches.create_and_poll(
+        vector_store_id=vector_store.id, file_ids=[file.id]
+    )
+    # List file in the batch
+    files = project_client.agents.vector_store_file_batches.list_files(vector_store.id, vector_store_file_batch.id)
+    for one_file in files:
+        print(one_file.id)
+    # Try to cancel batch upload
+    project_client.agents.vector_store_file_batches.cancel(vector_store.id, vector_store_file_batch.id)
+    ```