Agent with a Function Tool

Learn how to create an agent with a custom function tool.

Weather Agent Example

In this example, we have a weather agent equipped with a custom function tool. This is also known as a function calling agent.

With function tools an agent can use custom-written, locally-defined functions as tools. Function tools are flexible and particularly useful for enterprise use cases because of their local processing, easy authentication, and seamless integration with existing functionality features.

---

Info: Function tools run locally on your side.

What's sent to the remote agent on the OCI server side is the function definition (function name, function parameters, and their descriptions). OCI servers do not access the function implementation.

---

weather_agent.py

from typing import Dict, Any
from oci.addons.adk import Agent, AgentClient, tool

@tool
def get_weather(location: str) -> Dict[str, Any]:
    """Get the weather for a given location.

    Args:
      location(str): The location for which weather is queried
    """
    return {"location": location, "temperature": 72, "unit": "F"}


def main():
    client = AgentClient(
        auth_type="api_key",
        profile="DEFAULT",
        region="us-chicago-1"
    )

    agent = Agent(
        client=client,
        agent_endpoint_id="ocid1...",
        instructions="Perform weather queries using the given tools",
        tools=[get_weather]
    )

    agent.setup()

    input = "Is it cold in Seattle?"
    response = agent.run(input)

    response.pretty_print()

if __name__ == "__main__":
    main()

You write a plain function get_weather, decorate it with @tool, and use standard docstring to write function description and parameter descriptions.

Your function can return anything that can be converted to a string. Here we just return a Dict simulating a JSON object we get from database, cache, or API endpoint.

You then pass that function to the tools list when creating the Agent object. This registers the function as a tool to the agent locally.

When you run the agent.setup() method, the ADK applies the local agent setup to the remote agent instance, which includes the agent instructions and the function tool. The ADK automatically generates the function JSON schema that's needed to set up the custom function tool on the server.

When you run the agent.run() method, the ADK handles the client-server interaction necessary for function calling, which includes invoking the get_weather function.

How it works

When the remote agent decides to use the get_weather tool, it replies with a response that contains a required action the client needs to take. In this case, the required action for the client is to invoke the get_weather function tool, with an argument location=Seattle.

The remote agent applies the intent classification to use the get_weather tool, and the argument slot filling, based on the natural language query Is it cold in Seattle?.

The ADK parses the required action, locates the local function registered, executes this function with the given arguments, captures the function call output, and submits the output back to the remote agent. The agent can use that output to generate an answer to the user's question.