Use a custom function in an AI agent

In this exercise you will explore creating an agent that can use custom functions as a tool to complete tasks.

You’ll build a simple technical support agent that can collect details of a technical problem and generate a support ticket.

This exercise should take approximately 30 minutes to complete.

Create an Azure AI Foundry project

Let’s start by creating an Azure AI Foundry project.

In a web browser, open the Azure AI Foundry portal at https://ai.azure.com and sign in using your Azure credentials. Close any tips or quick start panes that are opened the first time you sign in, and if necessary use the Azure AI Foundry logo at the top left to navigate to the home page, which looks similar to the following image:
In the home page, select + Create project.
In the Create a project wizard, enter a suitable project name (for example, my-ai-project) and if an existing hub is suggested, choose the option to create a new one. Then review the Azure resources that will be automatically created to support your hub and project.
Select Customize and specify the following settings for your hub:
- Hub name: A unique name - for example my-ai-hub
- Subscription: Your Azure subscription
- Resource group: Create a new resource group with a unique name (for example, my-ai-resources), or select an existing one
- Location: Select a region from the following:*
  - australiaeast
  - eastus
  - eastus2
  - francecentral
  - swedencentral
- Connect Azure AI Services or Azure OpenAI: Create a new AI Services resource with an appropriate name (for example, my-ai-services) or use an existing one
- Connect Azure AI Search: Skip connecting
* At the time of writing, these regions support the gpt-4 model for use in agents. Model quotas are constrained at the tenant level by regional quotas. In the event of a quota limit being reached later in the exercise, there’s a possibility you may need to create another project in a different region.
Select Next and review your configuration. Then select Create and wait for the process to complete.
When your project is created, close any tips that are displayed and review the project page in Azure AI Foundry portal, which should look similar to the following image:
In the project overview page, in the Project details area, note the Project connection string. Later, you’ll use this connection string to connect to your project in a client application.

Deploy a generative AI model

Now you’re ready to deploy a generative AI language model to support your agent.

In the pane on the left for your project, in the My assets section, select the Models + endpoints page.
In the Models + endpoints page, in the Model deployments tab, in the + Deploy model menu, select Deploy base model.
Search for the gpt-4 model in the list, and then select and confirm it.
Deploy the model with the following settings by selecting Customize in the deployment details:
- Deployment name: A unique name for your model deployment - for example gpt-4 (remember the name you choose - you’ll need it later)
- Deployment type: Standard
- Model version: 0613
- Connected AI resource: Select your Azure OpenAI resource connection
- Tokens per Minute Rate Limit (thousands): 5K
- Content filter: DefaultV2
- Enable dynamic quota: Disabled
Note: Reducing the TPM helps avoid over-using the quota available in the subscription you are using. 5,000 TPM is sufficient for the data used in this exercise.
Wait for the deployment to complete.

Develop an agent that uses function tools

Now that you’ve created your project in AI Foundry, let’s develop an app that implements an agent using custom function tools.

Clone the repo containing the application code

Open a new browser tab (keeping the Azure AI Foundry portal open in the existing tab). Then in the new tab, browse to the Azure portal at https://portal.azure.com; signing in with your Azure credentials if prompted.

Close any welcome notifications to see the Azure portal home page.
Use the [>_] button to the right of the search bar at the top of the page to create a new Cloud Shell in the Azure portal, selecting a PowerShell environment with no storage in your subscription.

The cloud shell provides a command line interface in a pane at the bottom of the Azure portal. You can resize or maximize this pane to make it easier to work in.

Note: If you have previously created a cloud shell that uses a Bash environment, switch it to PowerShell.
In the cloud shell toolbar, in the Settings menu, select Go to Classic version (this is required to use the code editor).

Ensure you've switched to the classic version of the cloud shell before continuing.
In the PowerShell pane, enter the following commands to clone the GitHub repo containing the code files for this exercise:
```
rm -r ai-agents -f
git clone https://github.com/MicrosoftLearning/mslearn-ai-agents ai-agents
```
Tip: As you enter commands into the cloudshell, the ouput may take up a large amount of the screen buffer and the cursor on the current line may be obscured. You can clear the screen by entering the cls command to make it easier to focus on each task.
Enter the following command to change the working directory to the folder containing the code files and list them all.
```
cd ai-agents/Labfiles/03-ai-agent-functions/Python
ls -a -l
```
The provided files include application code and a file for configuration settings.

Configure the application settings

In the cloud shell command line pane, enter the following command to install the libraries you’ll use:
```
pip install python-dotenv azure-identity azure-ai-projects
```
Note: You can ignore any warning or error messages displayed during the library installation.
Enter the following command to edit the configuration file that has been provided:
```
code .env
```
The file is opened in a code editor.
In the code file, replace the your_project_connection_string placeholder with the connection string for your project (copied from the project Overview page in the Azure AI Foundry portal), and the your_model_deployment placeholder with the name you assigned to your gpt-4 model deployment.
After you’ve replaced the placeholders, use the CTRL+S command to save your changes and then use the CTRL+Q command to close the code editor while keeping the cloud shell command line open.

Define a custom function

Enter the following command to edit the code file that has been provided for your function code:
```
code user_functions.py
```

Find the comment Create a function to submit a support ticket and add the following code, which generates a ticket number and saves a support ticket as a text file.

# Create a function to submit a support ticket
def submit_support_ticket(email_address: str, description: str) -> str:
     script_dir = Path(__file__).parent  # Get the directory of the script
     ticket_number = str(uuid.uuid4()).replace('-', '')[:6]
     file_name = f"ticket-{ticket_number}.txt"
     file_path = script_dir / file_name
     text = f"Support ticket: {ticket_number}\nSubmitted by: {email_address}\nDescription:\n{description}"
     file_path.write_text(text)
    
     message_json = json.dumps({"message": f"Support ticket {ticket_number} submitted. The ticket file is saved as {file_name}"})
     return message_json

Find the comment Define a set of callable functions and add the following code, which statically defines a set of callable functions in this code file (in this case, there’s only one - but in a real solution you may have multiple functions that your agent can call):
```
# Define a set of callable functions
user_functions: Set[Callable[..., Any]] = {
     submit_support_ticket
 }
```
Save the file (CTRL+S).

Write code to implement an agent that can use your function

Enter the following command to begin editing the agent code.
```
 code agent.py
```
Tip: As you add code to the code file, be sure to maintain the correct indentation.
Review the existing code, which retrieves the application configuration settings and sets up a loop in which the user can enter prompts for the agent. The rest of the file includes comments where you will add the necessary code to implement your technical support agent.

Find the comment Add references and add the following code to import the classes you will need to build an Azure AI agent that uses your function code as a tool:

# Add references
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import FunctionTool, ToolSet
from user_functions import user_functions

Find the comment Connect to the Azure AI Foundry project and add the following code to connect to the Azure AI project using the current Azure credentials.

Tip: Be careful to maintain the correct indentation level.

# Connect to the Azure AI Foundry project
project_client = AIProjectClient.from_connection_string(
     credential=DefaultAzureCredential
         (exclude_environment_credential=True,
          exclude_managed_identity_credential=True),
     conn_str=PROJECT_CONNECTION_STRING
)

Find the comment Define an agent that can use the custom functions section, and add the following code to add your function code to a toolset, and then create an agent that can use the toolset and a thread on which to run the chat session.

# Define an agent that can use the custom functions
with project_client:

     functions = FunctionTool(user_functions)
     toolset = ToolSet()
     toolset.add(functions)
            
     agent = project_client.agents.create_agent(
         model=MODEL_DEPLOYMENT,
         name="support-agent",
         instructions="""You are a technical support agent.
                         When a user has a technical issue, you get their email address and a description of the issue.
                         Then you use those values to submit a support ticket using the function available to you.
                         If a file is saved, tell the user the file name.
                      """,
         toolset=toolset
     )

     thread = project_client.agents.create_thread()
     print(f"You're chatting with: {agent.name} ({agent.id})")

Find the comment Send a prompt to the agent and add the following code to add the user’s prompt as a message and run the thread.
```
# Send a prompt to the agent
message = project_client.agents.create_message(
     thread_id=thread.id,
     role="user",
     content=user_prompt
)
run = project_client.agents.create_and_process_run(thread_id=thread.id, agent_id=agent.id)
```
Note: Using the create_and_process_run method to run the thread enables the agent to automatically find your functions and choose to use them based on their names and parameters. As an alternative, you could use the create_run method, in which case you would be responsible for writing code to poll for run status to determine when a function call is required, call the function, and return the results to the agent.

Find the comment Check the run status for failures and add the following code to show any errors that occur.

# Check the run status for failures
if run.status == "failed":
     print(f"Run failed: {run.last_error}")

Find the comment Show the latest response from the agent and add the following code to retrieve the messages from the completed thread and display the last one that was sent by the agent.

# Show the latest response from the agent
messages = project_client.agents.list_messages(thread_id=thread.id)
last_msg = messages.get_last_text_message_by_role("assistant")
if last_msg:
     print(f"Last Message: {last_msg.text.value}")

Find the comment Get the conversation history, which is after the loop ends, and add the following code to print out the messages from the conversation thread; reversing the order to show them in chronological sequence

# Get the conversation history
print("\nConversation Log:\n")
messages = project_client.agents.list_messages(thread_id=thread.id)
for message_data in reversed(messages.data):
     last_message_content = message_data.content[-1]
     print(f"{message_data.role}: {last_message_content.text.value}\n")

Find the comment Clean up and add the following code to delete the agent and thread when no longer needed.

# Clean up
project_client.agents.delete_agent(agent.id)
project_client.agents.delete_thread(thread.id)

Review the code, using the comments to understand how it:
- Adds your set of custom functions to a toolset
- Creates an agent that uses the toolset.
- Runs a thread with a prompt message from the user.
- Checks the status of the run in case there’s a failure
- Retrieves the messages from the completed thread and displays the last one sent by the agent.
- Displays the conversation history
- Deletes the agent and thread when they are no longer required.
Save the code file (CTRL+S) when you have finished. You can also close the code editor (CTRL+Q); though you may want to keep it open in case you need to make any edits to the code you added. In either case, keep the cloud shell command line pane open.

Sign into Azure and run the app

In the cloud shell command line pane, enter the following command to sign into Azure.
```
 az login
```
You must sign into Azure - even though the cloud shell session is already authenticated.
When prompted, follow the instructions to open the sign-in page in a new tab and enter the authentication code provided and your Azure credentials. Then complete the sign in process in the command line, selecting the subscription containing your Azure AI Foundry hub if prompted.
After you have signed in, enter the following command to run the application:
```
python agent.py
```
The application runs using the credentials for your authenticated Azure session to connect to your project and create and run the agent.
When prompted, enter a prompt such as:
```
I have a technical problem
```
Tip: If the app fails because the rate limit is exceeded. Wait a few seconds and try the prompt again.
View the response. The agent may ask for your email address and a description of the issue. You can use any email address (for example, alex@contoso.com) and any issue description (for example my computer won't start)

When it has enough information, the agent should choose to use your funtion as required.
You can continue the conversation if you like. The thread is stateful, so it retains the conversation history - meaning that the agent has the full context for each response. Enter quit when you’re done.
Review the conversation messages that were retrieved from the thread, and the tickets that were generated.
The tool should have saved support tickets in the app folder. You can use the ls command to check, and then use the cat command to view the file contents, like this:
```
cat ticket-<ticket_num>.txt
```

Clean up

Now that you’ve finished the exercise, you should delete the cloud resources you’ve created to avoid unnecessary resource usage.

Open the Azure portal at https://portal.azure.com and view the contents of the resource group where you deployed the hub resources used in this exercise.
On the toolbar, select Delete resource group.
Enter the resource group name and confirm that you want to delete it.