Getting started

Custom tools

In addition to running the pre-made tools offered by the framework, you can also add custom tools/functions to your agent. This is particularily useful when you want the LLM to run custom code in your application that is not directly supported by the preset of tools in Superagent.

Step-by-step guide

  1. Start by creating an LLM and an Agent. Note that you can use already created LLMs or Agents.

Note that you usually only need to create the llm object once and re-use it for subsequent agents you create.


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
import os
from superagent.client import Superagent

client = Superagent(
    base_url="https://api.beta.superagent.sh",
    token=os.environ["SUPERAGENT_API_KEY"]
)

llm = client.llm.create(request={
    "provider": "OPENAI",
    "apiKey": os.environ["OPENAI_API_KEY"]
})

agent = client.agent.create(request={
    "name": "Stock Assistant",
    "description": "An Assistant that can fetch Stock prices",
    "avatar": "https://mylogo.com/logo.png", # Replace with a real image
    "isActive": True,
    "llmModel": "GPT_3_5_TURBO_16K_0613",
    "initialMessage": "Hi there, how can I help you?",
    "prompt": "Use the Stock API to answer the users question."
})

client.agent.add_llm(agent_id=agent.data.id, llm_id=llm.data.id)
  1. Next, let's create a custom tool that will fetch stock info for a specific ticker.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
tool = client.tool.create({
    "name": "Stock API",
    "description": "Useful for answering questions about a specific stock",
    "type": "FUNCTION",
    "returnDirect": False,
    "metadata": {
        "functionName": "get_stock",
        "args": {
            "ticker": {
                "type": "string",
                "description": "The stock ticker to search for"
            }
        }
    }
})

client.agent.add_tool(agent_id=agent.data.id, tool_id=tool.data.id)
  1. Invoke the agent
1
2
3
4
5
6
7
8
9
prediction = client.agent.invoke(
    agent_id=agent_id,
    enable_streaming=False,
    input="What's the current stock price of Apple?",
    session_id="my_session_id"
)

output = prediction.data.get("output")
steps = preduction.data.get("intermediate_steps")
  1. Check the intermediate steps and execute the local function.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# Implementation of the get_stock function
def get_stock(ticker):
    print(f"Getting stock information for {ticker}")

# Create a dispatch table
tool_dispatch = {
    "get_stock": get_stock,
    # Add more tools here as needed
}

# Check the steps and run the function
def handle_tool_actions(steps):
    for item, _ in data:
        tool_name = item.get('tool')
        tool_function = tool_dispatch.get(tool_name)
        if tool_function:
            tool_input = item.get('tool_input', {})
            tool_function(**tool_input)
        else:
            print(f"No function defined for tool: {tool_name}")

# Run your custom tool
handle_tool_actions(steps)

Full code

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
import os
from superagent.client import Superagent

client = Superagent(
    base_url="https://api.beta.superagent.sh",
    token=os.environ["SUPERAGENT_API_KEY"]
)

llm = client.llm.create(request={
    "provider": "OPENAI",
    "apiKey": os.environ["OPENAI_API_KEY"]
})

agent = client.agent.create(request={
    "name": "Stock Assistant",
    "description": "Useful for answering questions about a specific stock",
    "avatar": "https://mylogo.com/logo.png", # Replace with a real image
    "isActive": True,
    "llmModel": "GPT_3_5_TURBO_16K_0613",
    "initialMessage": "Hi there, how can I help you?",
    "prompt": "Use the Stock API to answer the users question."
})

# Create your custom tool
tool = client.tool.create({
    "name": "Stock API",
    "description": "Useful for answering questions about a specific stock",
    "type": "FUNCTION",
    "returnDirect": False,
    "metadata": {
        "functionName": "get_stock",
        "args": {
            "ticker": {
                "type": "string",
                "description": "The stock ticker to search for"
            }
        }
    }
})

client.agent.add_llm(agent_id=agent.data.id, llm_id=llm.data.id)
client.agent.add_tool(agent_id=agent.data.id, tool_id=tool.data.id)

prediction = client.agent.invoke(
    agent_id=agent_id,
    enable_streaming=False,
    input="What's the current stock price of Apple?",
    session_id="my_session_id"
)

output = prediction.data.get("output")
steps = preduction.data.get("intermediate_steps")

# Implementation of the get_stock function
def get_stock(ticker):
    print(f"Getting stock information for {ticker}")

# Create a dispatch table
tool_dispatch = {
    "get_stock": get_stock,
    # Add more tools here as needed
}

# Check the steps and run the function
def handle_tool_actions(steps):
    for item, _ in data:
        tool_name = item.get('tool')
        tool_function = tool_dispatch.get(tool_name)

        if tool_function:
            tool_input = item.get('tool_input', {})
            tool_function(**tool_input)
        else:
            print(f"No function defined for tool: {tool_name}")

# Run your custom tool
handle_tool_actions(steps)