superface_agent_hub_anthropic_example.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "qabP5mEbU86f"
      },
      "source": [
        "# Superface Hub API - Anthropic Claude3 Example\n",
        "\n",
        "This notebook demonstrates how to use Superface's Hub API to with the function calling capability of the Claude3 LLMs."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 2,
      "metadata": {
        "id": "iGEDJkt9VCxe"
      },
      "outputs": [],
      "source": [
        "%pip install anthropic --quiet"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "D6uZXG6lU4xG"
      },
      "source": [
        "## Setup and configuration"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 3,
      "metadata": {
        "id": "v5uK6K_oWMP1"
      },
      "outputs": [],
      "source": [
        "import anthropic\n",
        "import json\n",
        "import requests as r\n",
        "from IPython.display import display, Markdown\n",
        "\n",
        "# Set a random number of your choice, but don't change it\n",
        "# once you have run the notebook, otherwise you will create another user.\n",
        "SUPERFACE_USER_ID_CONSTANT = 123456789\n",
        "\n",
        "# Use the number to create a unique ID\n",
        "SUPERFACE_USER_ID = \"sfclaudedemo|\" + str(SUPERFACE_USER_ID_CONSTANT)\n",
        "\n",
        "# Default URL for Superface\n",
        "SUPERFACE_BASE_URL = \"https://pod.superface.ai/api/hub\"\n",
        "\n",
        "# Set the Superface authentication token\n",
        "SUPERFACE_AUTH_TOKEN=\"<your-superface-api-token>\"\n",
        "\n",
        "# Set the OpenAI API Key\n",
        "ANTHROPIC_API_KEY=\"<your-anthropic-api-key>\"\n",
        "\n",
        "client = anthropic.Anthropic(api_key=ANTHROPIC_API_KEY)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "TSkiGsdSVSHx"
      },
      "source": [
        "## Helper functions\n",
        "Defines helpers for communicating with the Superface HUB API, and also with Claude.\n",
        "\n",
        "Anthropic expects a slightly different JSON schema for function definition than that used by OpenAI, MistralAI and LangChain, which is what Hub API delivers by default.\n",
        "\n",
        "To combat this, the `get_formatted_tools()` function is required to alter the structure and keep Claude happy."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 6,
      "metadata": {
        "id": "De6vpHZuW6rk"
      },
      "outputs": [],
      "source": [
        "# Helper function to return the tool function descriptors\n",
        "def get_superface_tools():\n",
        "  headers = {\"Authorization\": \"Bearer \"+ SUPERFACE_AUTH_TOKEN}\n",
        "  tools = r.get(SUPERFACE_BASE_URL + \"/fd\", headers=headers)\n",
        "  return tools.json()\n",
        "\n",
        "# Helper function to perform the action for all the functions.\n",
        "# This is the only API call required regardless of what the function is.\n",
        "def perform_action(tool_name=None, tool_body=None):\n",
        "  headers = {\"Authorization\": \"Bearer \"+ SUPERFACE_AUTH_TOKEN, \"x-superface-user-id\": SUPERFACE_USER_ID}\n",
        "  perform = r.post(SUPERFACE_BASE_URL + \"/perform/\" + tool_name, headers=headers, json=tool_body)\n",
        "  return json.dumps(perform.json())\n",
        "\n",
        "# Anthropic uses a slightly different schema, so reformat the function definitions JSON to suit\n",
        "def get_formatted_tools():\n",
        "  original_tools = get_superface_tools()\n",
        "  formatted_tools = []\n",
        "\n",
        "  for tool in original_tools:\n",
        "    formatted_tools.append(tool['function'])\n",
        "\n",
        "  for tool in formatted_tools:\n",
        "    tool['input_schema'] = tool.pop(\"parameters\")\n",
        "\n",
        "  return formatted_tools\n",
        "\n",
        "def talk_to_claude(role=None, message=None):\n",
        "  messages.append({\"role\": role, \"content\": message})\n",
        "  response = client.beta.tools.messages.create(\n",
        "    model=\"claude-3-opus-20240229\",\n",
        "    max_tokens=1024,\n",
        "    system=\"Today is April 5, 2024\",\n",
        "    tools=get_formatted_tools(),\n",
        "    messages=messages,\n",
        "  )\n",
        "  return response"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "T-KIowX7V7IU"
      },
      "source": [
        "## Message history\n",
        "The cell below sets up the message history. If you want to start your session again, you can just re-run this cell. There is no need to start again from the top of the notebook."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 7,
      "metadata": {
        "id": "Wnm_GgOUznxT"
      },
      "outputs": [],
      "source": [
        "messages = []"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "KrHGHmIwWI8V"
      },
      "source": [
        "## Submit an initial prompt"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 8,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "AynWL3B0WvGq",
        "outputId": "0fbd120a-84e2-4816-fc2a-8499cbb16fca"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "ToolsBetaMessage(id='msg_01KL4PHnAeMiY13AaV3fLMQN', content=[TextBlock(text='<thinking>\\nTo get the current weather forecast for Prague, I should use the weather__current-weather__CurrentWeather function. Let\\'s check if I have the required parameters:\\n\\ncity: The user provided \"Prague\" as the city. To be more precise, I\\'ll specify \"Prague, Czech Republic\".\\nunits: This is an optional parameter. The user did not specify units, so I can omit this and the function will use the default of Celsius.\\n\\nI have the required city parameter, so I can proceed with calling the function.\\n</thinking>', type='text'), ToolUseBlock(id='toolu_01SBw1Bov8VnjnL7Q6u16hYG', input={'city': 'Prague, Czech Republic'}, name='weather__current-weather__CurrentWeather', type='tool_use')], model='claude-3-opus-20240229', role='assistant', stop_reason='tool_use', stop_sequence=None, type='message', usage=Usage(input_tokens=4595, output_tokens=179))\n"
          ]
        }
      ],
      "source": [
        "response = talk_to_claude(\"user\", \"What's the weather like in Prague?\")\n",
        "print(response)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "T-ViCHmwoWMv"
      },
      "source": [
        "## Find out what Claude is thinking"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 9,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "LatXYvG7lrPQ",
        "outputId": "75aec956-793f-4a71-d74e-5d4a627684cc"
      },
      "outputs": [
        {
          "name": "stdout",
          "output_type": "stream",
          "text": [
            "<thinking>\n",
            "To get the current weather forecast for Prague, I should use the weather__current-weather__CurrentWeather function. Let's check if I have the required parameters:\n",
            "\n",
            "city: The user provided \"Prague\" as the city. To be more precise, I'll specify \"Prague, Czech Republic\".\n",
            "units: This is an optional parameter. The user did not specify units, so I can omit this and the function will use the default of Celsius.\n",
            "\n",
            "I have the required city parameter, so I can proceed with calling the function.\n",
            "</thinking>\n"
          ]
        }
      ],
      "source": [
        "print(response.content[0].text)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "JV4TlECh6v1m"
      },
      "source": [
        "## Run the tool Claude chose with Hub API"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 10,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 53
        },
        "id": "Ft8sKHApo-jz",
        "outputId": "91b47aaa-949d-445e-95c9-a3d534fcc5fc"
      },
      "outputs": [
        {
          "data": {
            "application/vnd.google.colaboratory.intrinsic+json": {
              "type": "string"
            },
            "text/plain": [
              "'{\"status\": \"success\", \"assistant_hint\": \"Format the result in \\'result\\' field to the user. If the user asked for a specific format, respect it\", \"result\": {\"description\": \"Partly cloudy\", \"feelsLike\": 16, \"temperature\": 16}}'"
            ]
          },
          "execution_count": 10,
          "metadata": {},
          "output_type": "execute_result"
        }
      ],
      "source": [
        "if (response.content[1] and response.content[1].type == \"tool_use\"):\n",
        "  claude_response = response.content[1]\n",
        "  messages.append({\n",
        "      \"role\": \"assistant\",\n",
        "      \"content\": [\n",
        "          {\n",
        "              \"type\": \"text\",\n",
        "              \"text\": response.content[0].text\n",
        "          },\n",
        "          {\n",
        "              \"type\": claude_response.type,\n",
        "              \"id\": claude_response.id,\n",
        "              \"name\": claude_response.name,\n",
        "              \"input\": claude_response.input\n",
        "          }\n",
        "      ]\n",
        "  })\n",
        "\n",
        "  function_name = claude_response.name\n",
        "  function_inputs = claude_response.input\n",
        "  tool_use_id = claude_response.id\n",
        "\n",
        "  superface_response = perform_action(function_name, function_inputs)\n",
        "\n",
        "superface_response"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 11,
      "metadata": {
        "id": "2IWPuDVjsVOr"
      },
      "outputs": [],
      "source": [
        "tool_response_content = [{\n",
        "    \"type\": \"tool_result\",\n",
        "    \"tool_use_id\": tool_use_id,\n",
        "    \"content\": superface_response\n",
        "\n",
        "}]\n",
        "claude_response = talk_to_claude(\"user\", tool_response_content)\n",
        "messages.append({\"role\": \"assistant\", \"content\": claude_response.content[0].text})"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "qCAaNj4THGGp"
      },
      "source": [
        "## Final response"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": 12,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/",
          "height": 46
        },
        "id": "wN0oxy24zHRo",
        "outputId": "ea3de838-bbb0-46e7-bc94-adf607415424"
      },
      "outputs": [
        {
          "data": {
            "text/markdown": [
              "Current weather in Prague, Czech Republic:\n",
              "Temperature: 16°C\n",
              "Feels like: 16°C\n",
              "Description: Partly cloudy"
            ],
            "text/plain": [
              "<IPython.core.display.Markdown object>"
            ]
          },
          "metadata": {},
          "output_type": "display_data"
        }
      ],
      "source": [
        "display(Markdown(claude_response.content[0].text))"
      ]
    }
  ],
  "metadata": {
    "colab": {
      "provenance": []
    },
    "kernelspec": {
      "display_name": "Python 3",
      "name": "python3"
    },
    "language_info": {
      "name": "python"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}