|
| 1 | +--- |
| 2 | +manager: nitinme |
| 3 | +author: aahill |
| 4 | +ms.author: aahi |
| 5 | +ms.service: azure |
| 6 | +ms.topic: include |
| 7 | +ms.date: 11/13/2024 |
| 8 | +--- |
| 9 | + |
| 10 | + |
| 11 | +| [Reference documentation](https://platform.openai.com/docs/api-reference/assistants?lang=python) | [Library source code](https://github.com/openai/openai-python) | [Package (PyPi)](https://pypi.org/project/openai/) | |
| 12 | + |
| 13 | +## Prerequisites |
| 14 | + |
| 15 | +* An Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services). |
| 16 | +* [Python 3.13 or later](https://www.python.org/) |
| 17 | +* Make sure you have the **Azure AI Developer** [RBAC role](../../../ai-studio/concepts/rbac-ai-studio.md) assigned at the appropriate level. |
| 18 | + |
| 19 | +[!INCLUDE [bicep-setup](bicep-setup.md)] |
| 20 | + |
| 21 | +## Configure and run an agent |
| 22 | + |
| 23 | +| Component | Description | |
| 24 | +| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 25 | +| Agent | Custom AI that uses AI models in conjunction with tools. | |
| 26 | +| Tool | Tools help extend an agent’s ability to reliably and accurately respond during conversation. Such as connecting to user-defined knowledge bases to ground the model, or enabling web search to provide current information. | |
| 27 | +| Thread | A conversation session between an agent and a user. Threads store Messages and automatically handle truncation to fit content into a model’s context. | |
| 28 | +| Message | A message created by an agent or a user. Messages can include text, images, and other files. Messages are stored as a list on the Thread. | |
| 29 | +| Run | Activation of an agent to begin running based on the contents of Thread. The agent uses its configuration and Thread’s Messages to perform tasks by calling models and tools. As part of a Run, the agent appends Messages to the Thread. | |
| 30 | +| Run Step | A detailed list of steps the agent took as part of a Run. An agent can call tools or create Messages during its run. Examining Run Steps allows you to understand how the agent is getting to its results. | |
| 31 | + |
| 32 | +Run the following commands to install the python packages. |
| 33 | + |
| 34 | +```console |
| 35 | +pip install azure-ai-projects |
| 36 | +pip install azure-identity |
| 37 | +pip install openai |
| 38 | +``` |
| 39 | + |
| 40 | +Use the following code to create and run an agent. To run this code, you will need to create a connection string using information from your project. This string is in the format: |
| 41 | + |
| 42 | +`<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>` |
| 43 | + |
| 44 | +`HostName` can be found by navigating to your `discovery_url` and removing the leading `https://` and trailing `/discovery`. To find your `discovery_url`, run this CLI command: |
| 45 | + |
| 46 | +```azurecli |
| 47 | +az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url |
| 48 | +``` |
| 49 | + |
| 50 | +For example, your connection string may look something like: |
| 51 | + |
| 52 | +`eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name` |
| 53 | + |
| 54 | +Set this connection string as an environment variable named `PROJECT_CONNECTION_STRING`. |
| 55 | + |
| 56 | +```python |
| 57 | +import os, time |
| 58 | +from azure.ai.projects import AIProjectClient |
| 59 | +from azure.identity import DefaultAzureCredential |
| 60 | +from openai import AzureOpenAI |
| 61 | + |
| 62 | + |
| 63 | +with AIProjectClient.from_connection_string( |
| 64 | + credential=DefaultAzureCredential(), |
| 65 | + conn_str=os.environ["PROJECT_CONNECTION_STRING"], |
| 66 | +) as project_client: |
| 67 | + |
| 68 | + # Explicit type hinting for IntelliSense |
| 69 | + client: AzureOpenAI = project_client.inference.get_azure_openai_client() |
| 70 | + |
| 71 | + with client: |
| 72 | + agent = client.beta.assistants.create( |
| 73 | + model="gpt-4o-mini", name="my-agent", instructions="You are a helpful agent" |
| 74 | + ) |
| 75 | + print(f"Created agent, agent ID: {agent.id}") |
| 76 | + |
| 77 | + thread = client.beta.threads.create() |
| 78 | + print(f"Created thread, thread ID: {thread.id}") |
| 79 | + |
| 80 | + message = client.beta.threads.messages.create(thread_id=thread.id, role="user", content="Hello, tell me a joke") |
| 81 | + print(f"Created message, message ID: {message.id}") |
| 82 | + |
| 83 | + run = client.beta.threads.runs.create(thread_id=thread.id, assistant_id=agent.id) |
| 84 | + |
| 85 | + # Poll the run while run status is queued or in progress |
| 86 | + while run.status in ["queued", "in_progress", "requires_action"]: |
| 87 | + time.sleep(1) # Wait for a second |
| 88 | + run = client.beta.threads.runs.retrieve(thread_id=thread.id, run_id=run.id) |
| 89 | + print(f"Run status: {run.status}") |
| 90 | + |
| 91 | + client.beta.assistants.delete(agent.id) |
| 92 | + print("Deleted agent") |
| 93 | + |
| 94 | + messages = client.beta.threads.messages.list(thread_id=thread.id) |
| 95 | + print(f"Messages: {messages}") |
| 96 | +``` |
0 commit comments