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 set 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.


1import os
2from superagent.client import Superagent
3
4client = Superagent(
5 base_url="https://api.beta.superagent.sh",
6 token=os.environ["SUPERAGENT_API_KEY"]
7)
8
9llm = client.llm.create(request={
10 "provider": "OPENAI",
11 "apiKey": os.environ["OPENAI_API_KEY"]
12})
13
14agent = client.agent.create(
15 name="Stock Assistant",
16 description="An Assistant that can fetch stock prices",
17 avatar="https://mylogo.com/logo.png", # Replace with a real image
18 is_active=True,
19 llm_model="GPT_3_5_TURBO_16K_0613",
20 initial_message="Hi there, how can I help you?",
21 prompt="Use the Stock API to answer the users question."
22)
23
24client.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 tool = client.tool.create(
2 name="Stock API",
3 description="Useful for answering questions about a specific stock",
4 type="FUNCTION",
5 return_direct=False,
6 metadata={
7 "functionName": "get-stock",
8 "args": {
9 "ticker": {
10 "type": "string",
11 "description": "The stock ticker to search for"
12 }
13 }
14 }
15)
16
17client.agent.add_tool(agent_id=agent.data.id, tool_id=tool.data.id)
  1. Invoke the agent
1prediction = client.agent.invoke(
2 agent_id=agent.data.id,
3 enable_streaming=False,
4 input="What's the current stock price of Apple?",
5 session_id="my_session_id"
6)
7
8output = prediction.data.get("output")
9steps = prediction.data.get("intermediate_steps")
  1. Check the intermediate steps and execute the local function.
1# Implementation of the get_stock function
2def get_stock(ticker):
3 print(f"Getting stock information for {ticker}")
4
5# Create a dispatch table
6tool_dispatch = {
7 "get-stock": get_stock,
8 # Add more tools here as needed
9}
10
11# Check the steps and run the function
12def handle_tool_actions(steps):
13 for item, _ in steps:
14 tool_name = item.get('tool')
15 tool_function = tool_dispatch.get(tool_name)
16
17 if tool_function:
18 tool_input = item.get('tool_input', {})
19 tool_function(**tool_input)
20 else:
21 print(f"No function defined for tool: {tool_name}")
22
23# Run your custom tool
24handle_tool_actions(steps)

Full code

1import os
2from superagent.client import Superagent
3
4client = Superagent(
5 base_url="https://api.beta.superagent.sh",
6 token=os.environ["SUPERAGENT_API_KEY"]
7)
8
9llm = client.llm.create(request={
10 "provider": "OPENAI",
11 "apiKey": os.environ["OPENAI_API_KEY"]
12})
13
14agent = client.agent.create(
15 name="Stock Assistant",
16 description="An Assistant that can fetch stock prices",
17 avatar="https://mylogo.com/logo.png", # Replace with a real image
18 is_active=True,
19 llm_model="GPT_3_5_TURBO_16K_0613",
20 initial_message="Hi there, how can I help you?",
21 prompt="Use the Stock API to answer the users question."
22)
23
24# Create your custom tool
25tool = client.tool.create(
26 name="Stock API",
27 description="Useful for answering questions about a specific stock",
28 type="FUNCTION",
29 return_direct=False,
30 metadata={
31 "functionName": "get-stock",
32 "args": {
33 "ticker": {
34 "type": "string",
35 "description": "The stock ticker to search for"
36 }
37 }
38 }
39)
40
41client.agent.add_llm(agent_id=agent.data.id, llm_id=llm.data.id)
42client.agent.add_tool(agent_id=agent.data.id, tool_id=tool.data.id)
43
44prediction = client.agent.invoke(
45 agent_id=agent.data.id,
46 enable_streaming=False,
47 input="What's the current stock price of Apple?",
48 session_id="my_session_id"
49)
50
51output = prediction.data.get("output")
52steps = prediction.data.get("intermediate_steps")
53
54# Implementation of the get_stock function
55def get_stock(ticker):
56 print(f"Getting stock information for {ticker}")
57
58# Create a dispatch table
59tool_dispatch = {
60 "get-stock": get_stock,
61 # Add more tools here as needed
62}
63
64# Check the steps and run the function
65def handle_tool_actions(steps):
66 for item, _ in steps:
67 tool_name = item.get('tool')
68 tool_function = tool_dispatch.get(tool_name)
69
70 if tool_function:
71 tool_input = item.get('tool_input', {})
72 tool_function(**tool_input)
73 else:
74 print(f"No function defined for tool: {tool_name}")
75
76# Run your custom tool
77handle_tool_actions(steps)