Define and customize tools

Letta has a native integration with Composio, which supports over 7000 pre-made tools to connect with popular services such as Slack, GitHub, Discord, etc. You can also create your own custom tools from scratch using Python.

Default Letta Tools

By default, agents in Letta are created with the following tools:

Tool	Description
`send_message`	Sends a message to the human user.
`core_memory_append`	Append to the contents of a block in core memory.
`core_memory_replace`	Replace the contents of a block in core memory.
`conversation_search`	Search prior conversation history (recall memory)
`archival_memory_insert`	Add a memory to archival memory
`archival_memory_search`	Search archival memory via embedding search

Letta also includes a set of pre-made tools designed for multi-agent interaction. See our guide on multi-agent for more information.

Custom Tools

You can create custom tools in Letta using the Python SDK, as well as via the ADE tool builder.

When you define the function for the tool, you must make sure to have a properly formatting docstring so the Letta Server can parse the function schema:

python

1 # install letta_client with `pip install letta-client`
2 from letta_client import Letta
3 
4 # create a client to connect to your local Letta Server
5 client = Letta(
6   base_url="http://localhost:8283"
7 )
8 
9 # define a function with a docstring
10 def roll_dice() -> str:
11     """
12     Simulate the roll of a 20-sided die (d20).
13 
14     This function generates a random integer between 1 and 20, inclusive,
15     which represents the outcome of a single roll of a d20.
16 
17     Returns:
18         str: The result of the die roll.
19     """
20     import random
21 
22     dice_role_outcome = random.randint(1, 20)
23     output_string = f"You rolled a {dice_role_outcome}"
24     return output_string
25 
26 # create the tool
27 tool = client.tools.create_from_function(
28     func=roll_dice
29 )
30 
31 print(f"Created tool {tool.name}")

Adding tools to agents in the Python SDK

Once the tool is created, you can add it to an agent by passing the tool name to the tools parameter in the agent creation.

python

1 # create a new agent
2 agent = client.agents.create(
3     memory_blocks=[
4         {"label": "human", "limit": 2000, "value": "Name: Bob"},
5         {"label": "persona", "limit": 2000, "value": "You are a friendly agent"}
6     ],
7     model="openai/gpt-4o-mini",
8     embedding="openai/text-embedding-3-small",
9     tool_ids=[tool.id]
10 )

Tool Environment Variables

You can set agent-scoped environment variables for your tools. These environment variables will be accessible in the sandboxed environment that any of the agent tools are run in.

For example, if you define a custom tool that requires an API key to run (e.g. EXAMPLE_TOOL_API_KEY), you can set the variable at time of agent creation by using the tool_exec_environment_variables parameter:

python

1 # create an agent with no tools
2 agent = client.agents.create(
3     memory_blocks=[
4         {"label": "human", "limit": 2000, "value": "Name: Bob"},
5         {"label": "persona", "limit": 2000, "value": "You are a friendly agent"}
6     ],
7     model="openai/gpt-4o-mini",
8     embedding="openai/text-embedding-3-small",
9     tool_exec_environment_variables={
10         "EXAMPLE_TOOL_API_KEY": "banana"
11     }
12 )

External Tool Libraries

Letta also has early support for adding tools from the external tool library Composio. This integrations works by converting the external library tools into Letta tools.

For more information on setting up Composio tools, see our Composio guide.

Excluding Default Tools

To skip adding default tools when creating a new agent, you can add in include_base_tools=False to the agent creation:

python

1 # create an agent with no tools
2 agent = client.agents.create(
3     memory_blocks=[
4         {"label": "human", "limit": 2000, "value": "Name: Bob"},
5         {"label": "persona", "limit": 2000, "value": "You are a friendly agent"}
6     ],
7     model="openai/gpt-4o-mini",
8     embedding="openai/text-embedding-3-small",
9     include_base_tools=False
10 )

Warning: this will create an agent with no tools, so the agent will have no ability to manage memory or search conversation history.

Tool Rules

Tool rules allow you to define graph-like constrains on your tools, such as requiring that a tool terminate agent execution or be followed by another tool.

Accessing Agent State

Tools that use agent_state currently do not work in the ADE live tool tester (they will error when you press “Run”), however if the tool is correct it will work once you attach it to an agent.

If you need to directly access the state of an agent inside a tool, you can use the reserved agent_state keyword argument, for example:

python

1 def get_agent_id(agent_state: "AgentState") -> str:
2     """
3     A custom tool that returns the agent ID
4 
5     Returns:
6         str: The agent ID
7     """
8     return agent_state.id

1	# install letta_client with `pip install letta-client`
2	from letta_client import Letta
3
4	# create a client to connect to your local Letta Server
5	client = Letta(
6	base_url="http://localhost:8283"
7	)
8
9	# define a function with a docstring
10	def roll_dice() -> str:
11	"""
12	Simulate the roll of a 20-sided die (d20).
13
14	This function generates a random integer between 1 and 20, inclusive,
15	which represents the outcome of a single roll of a d20.
16
17	Returns:
18	str: The result of the die roll.
19	"""
20	import random
21
22	dice_role_outcome = random.randint(1, 20)
23	output_string = f"You rolled a {dice_role_outcome}"
24	return output_string
25
26	# create the tool
27	tool = client.tools.create_from_function(
28	func=roll_dice
29	)
30
31	print(f"Created tool {tool.name}")

1	# create a new agent
2	agent = client.agents.create(
3	memory_blocks=[
4	{"label": "human", "limit": 2000, "value": "Name: Bob"},
5	{"label": "persona", "limit": 2000, "value": "You are a friendly agent"}
6	],
7	model="openai/gpt-4o-mini",
8	embedding="openai/text-embedding-3-small",
9	tool_ids=[tool.id]
10	)

1	# create an agent with no tools
2	agent = client.agents.create(
3	memory_blocks=[
4	{"label": "human", "limit": 2000, "value": "Name: Bob"},
5	{"label": "persona", "limit": 2000, "value": "You are a friendly agent"}
6	],
7	model="openai/gpt-4o-mini",
8	embedding="openai/text-embedding-3-small",
9	tool_exec_environment_variables={
10	"EXAMPLE_TOOL_API_KEY": "banana"
11	}
12	)

1	def get_agent_id(agent_state: "AgentState") -> str:
2	"""
3	A custom tool that returns the agent ID
4
5	Returns:
6	str: The agent ID
7	"""
8	return agent_state.id