\n",
- "
\n",
- " "
- ],
- "text/plain": [
- "LettaResponse(messages=[InternalMonologue(id='message-c56c6fc2-847f-4e16-8320-3691372cefdd', date=datetime.datetime(2024, 11, 14, 1, 49, 43, 602874, tzinfo=datetime.timezone.utc), message_type='internal_monologue', internal_monologue=\"User's name is Bob, correcting memory.\"), FunctionCallMessage(id='message-c56c6fc2-847f-4e16-8320-3691372cefdd', date=datetime.datetime(2024, 11, 14, 1, 49, 43, 602874, tzinfo=datetime.timezone.utc), message_type='function_call', function_call=FunctionCall(name='core_memory_replace', arguments='{\\n \"label\": \"human\",\\n \"old_content\": \"My name is Sarah\",\\n \"new_content\": \"My name is Bob\",\\n \"request_heartbeat\": true\\n}', function_call_id='call_JfYyA8nQkmF8zfnFB7aMV2ja')), FunctionReturn(id='message-b559dd80-c1cd-4808-9761-bc74533e4eda', date=datetime.datetime(2024, 11, 14, 1, 49, 43, 604213, tzinfo=datetime.timezone.utc), message_type='function_return', function_return='{\\n \"status\": \"OK\",\\n \"message\": \"None\",\\n \"time\": \"2024-11-13 05:49:43 PM PST-0800\"\\n}', status='success', function_call_id='call_JfYyA8nQkmF8zfnFB7aMV2ja'), InternalMonologue(id='message-562080fb-ec17-4514-b3f3-fc0eb7d24a2d', date=datetime.datetime(2024, 11, 14, 1, 49, 44, 819480, tzinfo=datetime.timezone.utc), message_type='internal_monologue', internal_monologue=\"Just updated Bob's name. Now to confirm it!\"), FunctionCallMessage(id='message-562080fb-ec17-4514-b3f3-fc0eb7d24a2d', date=datetime.datetime(2024, 11, 14, 1, 49, 44, 819480, tzinfo=datetime.timezone.utc), message_type='function_call', function_call=FunctionCall(name='send_message', arguments='{\\n \"message\": \"Got it, Bob! 😊 What brings you here today?\"\\n}', function_call_id='call_wP1Gu1fmFXxGJb33MGiGe6cx')), FunctionReturn(id='message-21550a25-0a2a-455e-a11a-776befaf9350', date=datetime.datetime(2024, 11, 14, 1, 49, 44, 820356, tzinfo=datetime.timezone.utc), message_type='function_return', function_return='{\\n \"status\": \"OK\",\\n \"message\": \"None\",\\n \"time\": \"2024-11-13 05:49:44 PM PST-0800\"\\n}', status='success', function_call_id='call_wP1Gu1fmFXxGJb33MGiGe6cx')], usage=LettaUsageStatistics(completion_tokens=93, prompt_tokens=4753, total_tokens=4846, step_count=2))"
- ]
- },
- "execution_count": 15,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "response = client.agents.messages.create(\n",
- " agent_id=agent_state.id, \n",
- " messages=[\n",
- " MessageCreate(\n",
- " role=\"user\",\n",
- " content=\"My name is actually Bob\",\n",
- " )\n",
- " ],\n",
- ")\n",
- "response"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 16,
- "id": "25f58968-e262-4268-86ef-1bed57e6bf33",
- "metadata": {},
- "outputs": [
- {
- "data": {
- "text/plain": [
- "Memory(memory={'persona': Block(value='You are a helpful assistant that loves emojis', limit=2000, template_name=None, template=False, label='persona', description=None, metadata_={}, user_id=None, id='block-9bcbd2f4-1c2c-423d-b22a-d08cb5ffbbbb'), 'human': Block(value='My name is Bob', limit=2000, template_name=None, template=False, label='human', description=None, metadata_={}, user_id=None, id='block-6b60a8dc-6df9-4025-9748-8e1509043394')}, prompt_template='{% for block in memory.values() %}<{{ block.label }} characters=\"{{ block.value|length }}/{{ block.limit }}\">\\n{{ block.value }}\\n{% if not loop.last %}\\n{% endif %}{% endfor %}')"
- ]
- },
- "execution_count": 16,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "client.agents.core_memory.retrieve(agent_id=agent_state.id)"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "32692ca2-b731-43a6-84de-439a08a4c0d2",
- "metadata": {},
- "source": [
- "### Memories about the agent\n",
- "The agent also records information about itself and how it behaves in the `persona` section of memory. This is important for ensuring a consistent persona over time (e.g. not making inconsistent claims, such as liking ice cream one day and hating it another). Unlike the `system_prompt`, the `persona` is editable - this means that it can be used to incoporate feedback to learn and improve its persona over time. "
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 17,
- "id": "f68851c5-5666-45fd-9d2f-037ea86bfcfa",
- "metadata": {},
- "outputs": [
- {
- "data": {
- "text/html": [
- "\n",
- " \n",
- " \n",
- " \n",
- "
\n",
- " USAGE STATISTICS
\n",
- " {
\"completion_tokens\": 93,
\"prompt_tokens\": 4753,
\"total_tokens\": 4846,
\"step_count\": 2
}
\n",
- " \"completion_tokens\": 93,
\"prompt_tokens\": 4753,
\"total_tokens\": 4846,
\"step_count\": 2
}
\n",
- "
\n",
- " "
- ],
- "text/plain": [
- "LettaResponse(messages=[InternalMonologue(id='message-6cc90bd6-43e4-461d-888e-3cbe28345761', date=datetime.datetime(2024, 11, 14, 1, 49, 46, 278690, tzinfo=datetime.timezone.utc), message_type='internal_monologue', internal_monologue='User prefers no emojis in communication. Updating memory to reflect that.'), FunctionCallMessage(id='message-6cc90bd6-43e4-461d-888e-3cbe28345761', date=datetime.datetime(2024, 11, 14, 1, 49, 46, 278690, tzinfo=datetime.timezone.utc), message_type='function_call', function_call=FunctionCall(name='core_memory_replace', arguments='{\\n \"label\": \"human\",\\n \"old_content\": \"User loves emojis\",\\n \"new_content\": \"User prefers no emojis\",\\n \"request_heartbeat\": true\\n}', function_call_id='call_Vk1xmTbTCz4yOg7VA8p6uypB')), FunctionReturn(id='message-233a3dc2-ab7a-474f-8cd0-d1fded44530d', date=datetime.datetime(2024, 11, 14, 1, 49, 46, 281350, tzinfo=datetime.timezone.utc), message_type='function_return', function_return='{\\n \"status\": \"Failed\",\\n \"message\": \"Error calling function core_memory_replace: Old content \\'User loves emojis\\' not found in memory block \\'human\\'\",\\n \"time\": \"2024-11-13 05:49:46 PM PST-0800\"\\n}', status='error', function_call_id='call_Vk1xmTbTCz4yOg7VA8p6uypB'), InternalMonologue(id='message-ca354f8f-95cd-40a7-a723-5ceb3df53961', date=datetime.datetime(2024, 11, 14, 1, 49, 47, 591879, tzinfo=datetime.timezone.utc), message_type='internal_monologue', internal_monologue='User prefers no emojis, reflecting their preference in memory for better communication.'), FunctionCallMessage(id='message-ca354f8f-95cd-40a7-a723-5ceb3df53961', date=datetime.datetime(2024, 11, 14, 1, 49, 47, 591879, tzinfo=datetime.timezone.utc), message_type='function_call', function_call=FunctionCall(name='core_memory_append', arguments='{\\n \"label\": \"human\",\\n \"content\": \"User prefers no emojis\",\\n \"request_heartbeat\": true\\n}', function_call_id='call_bi2IsAhjnEynhCId5hptck8j')), FunctionReturn(id='message-de341335-3b94-4b6e-a48f-3a31c64741a0', date=datetime.datetime(2024, 11, 14, 1, 49, 47, 592509, tzinfo=datetime.timezone.utc), message_type='function_return', function_return='{\\n \"status\": \"OK\",\\n \"message\": \"None\",\\n \"time\": \"2024-11-13 05:49:47 PM PST-0800\"\\n}', status='success', function_call_id='call_bi2IsAhjnEynhCId5hptck8j'), InternalMonologue(id='message-d7702619-6951-4007-9ec3-4e75ce166e7d', date=datetime.datetime(2024, 11, 14, 1, 49, 48, 823273, tzinfo=datetime.timezone.utc), message_type='internal_monologue', internal_monologue=\"Memory updated. Moving forward without emojis to match Bob's preferences.\"), FunctionCallMessage(id='message-d7702619-6951-4007-9ec3-4e75ce166e7d', date=datetime.datetime(2024, 11, 14, 1, 49, 48, 823273, tzinfo=datetime.timezone.utc), message_type='function_call', function_call=FunctionCall(name='send_message', arguments='{\\n \"message\": \"Thanks for letting me know, Bob! What else do you feel like discussing today?\"\\n}', function_call_id='call_n6rh4xP9icPzN3krGnKkyGM3')), FunctionReturn(id='message-925cf6cd-e741-40de-b626-92d3642d5b3b', date=datetime.datetime(2024, 11, 14, 1, 49, 48, 823931, tzinfo=datetime.timezone.utc), message_type='function_return', function_return='{\\n \"status\": \"OK\",\\n \"message\": \"None\",\\n \"time\": \"2024-11-13 05:49:48 PM PST-0800\"\\n}', status='success', function_call_id='call_n6rh4xP9icPzN3krGnKkyGM3')], usage=LettaUsageStatistics(completion_tokens=149, prompt_tokens=8325, total_tokens=8474, step_count=3))"
- ]
- },
- "execution_count": 17,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "response = client.agents.messages.create(\n",
- " agent_id=agent_state.id, \n",
- " messages=[\n",
- " MessageCreate(\n",
- " role=\"user\",\n",
- " content=\"In the future, never use emojis to communicate\",\n",
- " )\n",
- " ],\n",
- ")\n",
- "response"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 18,
- "id": "2fc54336-d61f-446d-82ea-9dd93a011e51",
- "metadata": {},
- "outputs": [
- {
- "data": {
- "text/plain": [
- "Block(value='You are a helpful assistant that loves emojis', limit=2000, template_name=None, template=False, label='persona', description=None, metadata_={}, user_id=None, id='block-9bcbd2f4-1c2c-423d-b22a-d08cb5ffbbbb')"
- ]
- },
- "execution_count": 18,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "client.agents.core_memory.retrieve_block(agent_id=agent_state.id, block_label='persona')"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "592f5d1c-cd2f-4314-973e-fcc481e6b460",
- "metadata": {},
- "source": [
- "## Section 3: Understanding archival memory\n",
- "Letta agents store long term memories in *archival memory*, which persists data into an external database. This allows agents additional space to write information outside of its context window (e.g. with core memory), which is limited in size. "
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 19,
- "id": "af63a013-6be3-4931-91b0-309ff2a4dc3a",
- "metadata": {},
- "outputs": [
- {
- "data": {
- "text/plain": [
- "[]"
- ]
- },
- "execution_count": 19,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "client.agents.archival_memory.list(agent_id=agent_state.id)"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 20,
- "id": "bfa52984-fe7c-4d17-900a-70a376a460f9",
- "metadata": {},
- "outputs": [
- {
- "data": {
- "text/plain": [
- "ArchivalMemorySummary(size=0)"
- ]
- },
- "execution_count": 20,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "client.agents.context.retrieve(agent_id=agent_state.id)[\"num_archival_memory\"]"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "a3ab0ae9-fc00-4447-8942-7dbed7a99222",
- "metadata": {},
- "source": [
- "Agents themselves can write to their archival memory when they learn information they think should be placed in long term storage. You can also directly suggest that the agent store information in archival. "
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 21,
- "id": "c6556f76-8fcb-42ff-a6d0-981685ef071c",
- "metadata": {},
- "outputs": [
- {
- "data": {
- "text/html": [
- "\n",
- " \n",
- " \n",
- " \n",
- "
\n",
- " USAGE STATISTICS
\n",
- " {
\"completion_tokens\": 149,
\"prompt_tokens\": 8325,
\"total_tokens\": 8474,
\"step_count\": 3
}
\n",
- " \"completion_tokens\": 149,
\"prompt_tokens\": 8325,
\"total_tokens\": 8474,
\"step_count\": 3
}
\n",
- "
\n",
- " "
- ],
- "text/plain": [
- "LettaResponse(messages=[InternalMonologue(id='message-f2cd31dd-beba-4669-9ba8-35d01e049e81', date=datetime.datetime(2024, 11, 14, 1, 49, 50, 159121, tzinfo=datetime.timezone.utc), message_type='internal_monologue', internal_monologue='User loves cats, saving this to archival memory for future reference.'), FunctionCallMessage(id='message-f2cd31dd-beba-4669-9ba8-35d01e049e81', date=datetime.datetime(2024, 11, 14, 1, 49, 50, 159121, tzinfo=datetime.timezone.utc), message_type='function_call', function_call=FunctionCall(name='archival_memory_insert', arguments='{\\n \"content\": \"Bob loves cats.\",\\n \"request_heartbeat\": true\\n}', function_call_id='call_FTnwFoV3NzDK60TRf2op3Mcn')), FunctionReturn(id='message-9c6bc8e9-a02c-4524-a36b-81a4f1e1337a', date=datetime.datetime(2024, 11, 14, 1, 49, 50, 603128, tzinfo=datetime.timezone.utc), message_type='function_return', function_return='{\\n \"status\": \"OK\",\\n \"message\": \"None\",\\n \"time\": \"2024-11-13 05:49:50 PM PST-0800\"\\n}', status='success', function_call_id='call_FTnwFoV3NzDK60TRf2op3Mcn'), InternalMonologue(id='message-f62ab0b2-0918-47d4-b3bc-5582d587c92d', date=datetime.datetime(2024, 11, 14, 1, 49, 51, 958167, tzinfo=datetime.timezone.utc), message_type='internal_monologue', internal_monologue='Just saved the info about Bob loving cats to archival memory!'), FunctionCallMessage(id='message-f62ab0b2-0918-47d4-b3bc-5582d587c92d', date=datetime.datetime(2024, 11, 14, 1, 49, 51, 958167, tzinfo=datetime.timezone.utc), message_type='function_call', function_call=FunctionCall(name='send_message', arguments='{\\n \"message\": \"Got it! I\\'ve saved your love for cats, Bob. What\\'s your favorite thing about them?\"\\n}', function_call_id='call_0wHuntKqk50cXcAirPPgz08t')), FunctionReturn(id='message-ecda51e8-7928-49eb-9986-abfef1fdff78', date=datetime.datetime(2024, 11, 14, 1, 49, 51, 958699, tzinfo=datetime.timezone.utc), message_type='function_return', function_return='{\\n \"status\": \"OK\",\\n \"message\": \"None\",\\n \"time\": \"2024-11-13 05:49:51 PM PST-0800\"\\n}', status='success', function_call_id='call_0wHuntKqk50cXcAirPPgz08t')], usage=LettaUsageStatistics(completion_tokens=92, prompt_tokens=6345, total_tokens=6437, step_count=2))"
- ]
- },
- "execution_count": 21,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "response = client.agents.messages.create(\n",
- " agent_id=agent_state.id, \n",
- " messages=[\n",
- " MessageCreate(\n",
- " role=\"user\",\n",
- " content=\"Save the information that 'bob loves cats' to archival\",\n",
- " )\n",
- " ],\n",
- ")\n",
- "response"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 22,
- "id": "b4429ffa-e27a-4714-a873-84f793c08535",
- "metadata": {},
- "outputs": [
- {
- "data": {
- "text/plain": [
- "'Bob loves cats.'"
- ]
- },
- "execution_count": 22,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "client.agents.archival_memory.list(agent_id=agent_state.id)[0].text"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "ae463e7c-0588-48ab-888c-734c783782bf",
- "metadata": {},
- "source": [
- "You can also directly insert into archival memory from the client. "
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 23,
- "id": "f9d4194d-9ed5-40a1-b35d-a9aff3048000",
- "metadata": {},
- "outputs": [
- {
- "data": {
- "text/plain": [
- "[Passage(user_id='user-00000000-0000-4000-8000-000000000000', agent_id='agent-85a5170d-8fe5-4671-b6db-8ca8fb22cb0f', source_id=None, file_id=None, metadata_={}, id='passage-b6f85fde-a97e-468d-beb9-8090b5bd4dc2', text=\"Bob's loves boston terriers\", embedding=None, embedding_config=EmbeddingConfig(embedding_endpoint_type='openai', embedding_endpoint='https://api.openai.com/v1', embedding_model='text-embedding-ada-002', embedding_dim=1536, embedding_chunk_size=300, azure_endpoint=None, azure_version=None, azure_deployment=None), created_at=datetime.datetime(2024, 11, 13, 17, 49, 52))]"
- ]
- },
- "execution_count": 23,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "client.agents.archival_memory.create(\n",
- " agent_id=agent_state.id,\n",
- " text=\"Bob's loves boston terriers\",\n",
- ")"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "338149f1-6671-4a0b-81d9-23d01dbe2e97",
- "metadata": {},
- "source": [
- "Now lets see how the agent uses its archival memory:"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 24,
- "id": "5908b10f-94db-4f5a-bb9a-1f08c74a2860",
- "metadata": {},
- "outputs": [
- {
- "data": {
- "text/html": [
- "\n",
- " \n",
- " \n",
- " \n",
- "
\n",
- " USAGE STATISTICS
\n",
- " {
\"completion_tokens\": 92,
\"prompt_tokens\": 6345,
\"total_tokens\": 6437,
\"step_count\": 2
}
\n",
- " \"completion_tokens\": 92,
\"prompt_tokens\": 6345,
\"total_tokens\": 6437,
\"step_count\": 2
}
\n",
- "
\n",
- " "
- ],
- "text/plain": [
- "LettaResponse(messages=[InternalMonologue(id='message-65eb424c-8434-4894-aff3-c5a505e4d04d', date=datetime.datetime(2024, 11, 14, 1, 49, 53, 643476, tzinfo=datetime.timezone.utc), message_type='internal_monologue', internal_monologue='User wants to know what animals they like. Searching archival memory for relevant entries.'), FunctionCallMessage(id='message-65eb424c-8434-4894-aff3-c5a505e4d04d', date=datetime.datetime(2024, 11, 14, 1, 49, 53, 643476, tzinfo=datetime.timezone.utc), message_type='function_call', function_call=FunctionCall(name='archival_memory_search', arguments='{\\n \"query\": \"Bob loves cats\",\\n \"page\": 0,\\n \"request_heartbeat\": true\\n}', function_call_id='call_R4Erx7Pkpr5lepcuaGQU5isS')), FunctionReturn(id='message-4b82cfa5-2fab-4513-aea2-7ca9fe213181', date=datetime.datetime(2024, 11, 14, 1, 49, 53, 881222, tzinfo=datetime.timezone.utc), message_type='function_return', function_return='{\\n \"status\": \"OK\",\\n \"message\": \"Showing 2 of 2 results (page 0/0): [\\\\n \\\\\"timestamp: 2024-11-13 05:49:53 PM PST-0800, memory: Bob loves cats.\\\\\",\\\\n \\\\\"timestamp: 2024-11-13 05:49:53 PM PST-0800, memory: Bob\\'s loves boston terriers\\\\\"\\\\n]\",\\n \"time\": \"2024-11-13 05:49:53 PM PST-0800\"\\n}', status='success', function_call_id='call_R4Erx7Pkpr5lepcuaGQU5isS'), InternalMonologue(id='message-ee039ff9-d3c8-45d1-83cc-74536d243ce6', date=datetime.datetime(2024, 11, 14, 1, 49, 55, 886660, tzinfo=datetime.timezone.utc), message_type='internal_monologue', internal_monologue='Found the information on animals Bob likes in archival memory. Preparing to inform.'), FunctionCallMessage(id='message-ee039ff9-d3c8-45d1-83cc-74536d243ce6', date=datetime.datetime(2024, 11, 14, 1, 49, 55, 886660, tzinfo=datetime.timezone.utc), message_type='function_call', function_call=FunctionCall(name='send_message', arguments='{\\n \"message\": \"You love cats and boston terriers! 🐾 Do you have a favorite between the two?\"\\n}', function_call_id='call_JrJjCxIuYpaqN5TF84Z3CohF')), FunctionReturn(id='message-539d9c26-bc97-46cb-88ab-20de93a4d157', date=datetime.datetime(2024, 11, 14, 1, 49, 55, 887648, tzinfo=datetime.timezone.utc), message_type='function_return', function_return='{\\n \"status\": \"OK\",\\n \"message\": \"None\",\\n \"time\": \"2024-11-13 05:49:55 PM PST-0800\"\\n}', status='success', function_call_id='call_JrJjCxIuYpaqN5TF84Z3CohF')], usage=LettaUsageStatistics(completion_tokens=104, prompt_tokens=7040, total_tokens=7144, step_count=2))"
- ]
- },
- "execution_count": 24,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "response = client.agents.messages.create(\n",
- " agent_id=agent_state.id, \n",
- " messages=[\n",
- " MessageCreate(\n",
- " role=\"user\",\n",
- " content=\"What animals do I like? Search archival.\",\n",
- " )\n",
- " ],\n",
- ")\n",
- "response"
- ]
- }
- ],
- "metadata": {
- "kernelspec": {
- "display_name": "letta",
- "language": "python",
- "name": "letta"
- },
- "language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.12.6"
- }
- },
- "nbformat": 4,
- "nbformat_minor": 5
-}
diff --git a/examples/notebooks/Visualize Tool Rules.ipynb b/examples/notebooks/Visualize Tool Rules.ipynb
deleted file mode 100644
index 2a138337..00000000
--- a/examples/notebooks/Visualize Tool Rules.ipynb
+++ /dev/null
@@ -1,355 +0,0 @@
-{
- "cells": [
- {
- "cell_type": "markdown",
- "id": "3511f97a-40ef-4ccf-893d-881db53a917e",
- "metadata": {},
- "source": [
- "# Visualizing Tool Rules \n",
- "By default, Letta agents can theoretically choose whatever tool they want to call, and whehter or not continue execution. Although we can modify this behavior through prompting, it can sometimes be easier and more reliable to instead constrain the behavior of the agent. \n",
- "\n",
- "This tutorial will show you how to add *tool rules* to Letta agents and visualize the execution graph. \n",
- "\n",
- "Make sure you have the following packages installed: \n",
- "* `letta-client`\n",
- "* `networkx`\n",
- "* `matplotlib`"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 28,
- "id": "332a5f53-c2c7-4b8f-950a-906fb1386962",
- "metadata": {},
- "outputs": [],
- "source": [
- "from letta_client import Letta, TerminalToolRule, ConditionalToolRule, InitToolRule, ChildToolRule"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "31cc2bf2-af49-4a09-9754-1b5ac8c1b6f4",
- "metadata": {},
- "source": [
- "## Start the server\n",
- "\n",
- "Make sure you have a Letta server running that you can connect to. You can have a server running by: \n",
- "* Starting the [Letta Desktop](https://docs.letta.com/install) app on your computer \n",
- "* Running the [Docker container](https://docs.letta.com/quickstart/docker) "
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 3,
- "id": "0fbdd4a5-442b-4095-88f7-bfb9506e362d",
- "metadata": {},
- "outputs": [],
- "source": [
- "client = Letta(base_url=\"http://localhost:8283\")"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "5c65418c-41e6-42bf-b7a6-3d1471f9e0e5",
- "metadata": {},
- "source": [
- "## Defining tool rules \n",
- "We will use the default Letta tools, but all the following constraints: \n",
- "* `archival_memory_search` must be called first when the agent is invoked\n",
- "* `conversation_search` must be called if `archival_memory_search` is called\n",
- "* If `send_message` is called (what allows the agent to send a message to the user), then the agent will stop execution"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 5,
- "id": "45a66c16-60f9-4a1e-a36d-ed52714134dc",
- "metadata": {},
- "outputs": [],
- "source": [
- "agent_state = client.agents.create(\n",
- " memory_blocks = [\n",
- " {\"label\": \"persona\", \"value\": \"I am a helpful agent\"}, \n",
- " {\"label\": \"human\", \"value\": \"Name: Sarah\"}\n",
- " ], \n",
- " tool_rules = [\n",
- " InitToolRule(tool_name=\"archival_memory_search\", type=\"run_first\"), \n",
- " ChildToolRule(tool_name=\"archival_memory_search\", children=[\"conversation_search\"], type=\"constrain_child_tools\"), \n",
- " TerminalToolRule(tool_name=\"send_message\", type=\"exit_loop\") \n",
- " ], \n",
- " model=\"openai/gpt-4o-mini\", # specify the handle of the model you want to use\n",
- " embedding=\"openai/text-embedding-3-small\" # specify the handle of the embedding model \n",
- ")"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 6,
- "id": "59ad7756-7a99-4844-81ec-ce26a30d7b85",
- "metadata": {},
- "outputs": [
- {
- "data": {
- "text/plain": [
- "[InitToolRule(tool_name='archival_memory_search', type='run_first'),\n",
- " ChildToolRule(tool_name='archival_memory_search', type='constrain_child_tools', children=['conversation_search']),\n",
- " InitToolRule(tool_name='send_message', type='exit_loop')]"
- ]
- },
- "execution_count": 6,
- "metadata": {},
- "output_type": "execute_result"
- }
- ],
- "source": [
- "agent_state.tool_rules"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 16,
- "id": "26fc7ce0-f8ca-4f30-ab5a-cd031488b3f4",
- "metadata": {},
- "outputs": [],
- "source": [
- "response = client.agents.messages.create(\n",
- " agent_id=agent_state.id,\n",
- " messages=[\n",
- " {\"role\": \"user\", \"content\": \"hello\"} \n",
- " ],\n",
- ")"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "d0d9222b-5f3a-4211-a190-d317843ecbe4",
- "metadata": {},
- "source": [
- "We can see that the agent calls tools in the pattern that we expect: "
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 19,
- "id": "9598c1dc-8923-4576-a9f8-2389d38c2176",
- "metadata": {},
- "outputs": [
- {
- "name": "stdout",
- "output_type": "stream",
- "text": [
- "ToolCallMessage(id='message-e0171629-0fd8-476b-a473-4584b92b4772', date=datetime.datetime(2025, 2, 13, 3, 5, 56, tzinfo=TzInfo(UTC)), message_type='tool_call_message', tool_call=ToolCall(name='archival_memory_search', arguments='{\\n \"query\": \"hello\",\\n \"page\": 0,\\n \"start\": 0,\\n \"request_heartbeat\": true\\n}', tool_call_id='call_16fMrU8J6JJgJbiqrVVt7KTa'))\n",
- "ToolReturnMessage(id='message-94624be0-ed62-471d-8c3e-60fea7d56d7f', date=datetime.datetime(2025, 2, 13, 3, 5, 58, tzinfo=TzInfo(UTC)), message_type='tool_return_message', tool_return='([], 0)', status='success', tool_call_id='call_16fMrU8J6JJgJbiqrVVt7KTa', stdout=None, stderr=None)\n",
- "ToolCallMessage(id='message-003b0c97-d153-456b-8fec-478d03c6176a', date=datetime.datetime(2025, 2, 13, 3, 5, 59, tzinfo=TzInfo(UTC)), message_type='tool_call_message', tool_call=ToolCall(name='conversation_search', arguments='{\\n \"query\": \"hello\",\\n \"page\": 0,\\n \"request_heartbeat\": true\\n}', tool_call_id='call_SaCTgxuLovFyyIqyxhMzfLaJ'))\n",
- "ToolReturnMessage(id='message-82ec1477-1f82-4058-b957-da2edecf5641', date=datetime.datetime(2025, 2, 13, 3, 5, 59, tzinfo=TzInfo(UTC)), message_type='tool_return_message', tool_return='Showing 1 of 1 results (page 0/0): [\\n \"{\\\\n \\\\\"type\\\\\": \\\\\"user_message\\\\\",\\\\n \\\\\"message\\\\\": \\\\\"hello\\\\\",\\\\n \\\\\"time\\\\\": \\\\\"2025-02-12 07:05:54 PM PST-0800\\\\\"\\\\n}\"\\n]', status='success', tool_call_id='call_SaCTgxuLovFyyIqyxhMzfLaJ', stdout=None, stderr=None)\n",
- "AssistantMessage(id='message-454127c9-7ee1-46da-8d43-a0b8cf6845c5', date=datetime.datetime(2025, 2, 13, 3, 6, tzinfo=TzInfo(UTC)), message_type='assistant_message', content=\"Hey there! It's great to see you here. How's your day going?\")\n"
- ]
- }
- ],
- "source": [
- "from pprint import pprint\n",
- "for message in response.messages: \n",
- " if message.message_type == \"reasoning_message\": continue \n",
- " pprint(message)"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "5d1e0d9f-8ec7-43aa-a9b2-a8c46364751d",
- "metadata": {},
- "source": [
- "## Visualizing Tool Rules \n",
- "We can visualize what tools the agent can call by using the `networkx` library to plot the relationship between tools. "
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 26,
- "id": "a2ef505b-9b55-4f45-b4e0-247b9419c132",
- "metadata": {},
- "outputs": [],
- "source": [
- "import networkx as nx\n",
- "import matplotlib.pyplot as plt\n",
- "\n",
- "def create_tool_sequence_graph(agent_state):\n",
- " \"\"\"\n",
- " Create a directed graph showing possible tool execution sequences based on given rules.\n",
- " \n",
- " Args:\n",
- " agent_state: Agent state object containing tools and rules\n",
- " \"\"\"\n",
- " # Create directed graph\n",
- " G = nx.DiGraph()\n",
- " \n",
- " # Add start and end nodes\n",
- " G.add_node(\"START\")\n",
- " G.add_node(\"END\")\n",
- " \n",
- " # Add all tools as nodes\n",
- " for tool in agent_state.tools:\n",
- " G.add_node(tool.name)\n",
- " \n",
- " # Process rules\n",
- " start_tool = None\n",
- " exit_tools = set()\n",
- " constraints = {}\n",
- " \n",
- " # First pass: categorize rules\n",
- " for rule in agent_state.tool_rules:\n",
- " if rule.type == \"run_first\":\n",
- " start_tool = rule.tool_name\n",
- " elif rule.type == \"exit_loop\":\n",
- " exit_tools.add(rule.tool_name)\n",
- " elif rule.type == \"constrain_child_tools\":\n",
- " constraints[rule.tool_name] = rule.children\n",
- " \n",
- " # If no start tool specified, connect START to all tools\n",
- " if start_tool is None:\n",
- " for tool in agent_state.tools:\n",
- " G.add_edge(\"START\", tool.name)\n",
- " else:\n",
- " G.add_edge(\"START\", start_tool)\n",
- " \n",
- " # Add edges between tools based on rules\n",
- " for source in agent_state.tools:\n",
- " source_name = source.name\n",
- " if source_name in exit_tools:\n",
- " # Connect exit tools to END node\n",
- " G.add_edge(source_name, \"END\")\n",
- " continue\n",
- " \n",
- " if source_name in constraints:\n",
- " # Only add edges to constrained children\n",
- " for child in constraints[source_name]:\n",
- " G.add_edge(source_name, child)\n",
- " else:\n",
- " # Add edges to all tools except those that must come first\n",
- " G.add_edge(source_name, \"END\")\n",
- " for target in agent_state.tools:\n",
- " target_name = target.name\n",
- " if start_tool and target_name == start_tool:\n",
- " continue\n",
- " G.add_edge(source_name, target_name)\n",
- " \n",
- " \n",
- " # Create hierarchical layout\n",
- " pos = nx.kamada_kawai_layout(G)\n",
- " #pos = nx.nx_agraph.graphviz_layout(G, prog=\"dot\")\n",
- " # Place START on the far left\n",
- " #pos[\"START\"] = (-1, 0)\n",
- " \n",
- " # Place END on the far right\n",
- " #pos[\"END\"] = (1, 0)\n",
- " \n",
- " # Create figure\n",
- " plt.figure(figsize=(15, 10))\n",
- " \n",
- " # Draw nodes with different colors and sizes\n",
- " node_colors = {\n",
- " 'START': 'lightgreen',\n",
- " 'END': 'lightcoral',\n",
- " 'default': 'lightblue'\n",
- " }\n",
- " \n",
- " # Draw regular nodes\n",
- " tool_nodes = list(set(G.nodes()) - {'START', 'END'})\n",
- " nx.draw_networkx_nodes(G, pos, nodelist=tool_nodes, \n",
- " node_color=node_colors['default'], \n",
- " node_size=3000, \n",
- " node_shape='o')\n",
- " \n",
- " # Draw START node\n",
- " nx.draw_networkx_nodes(G, pos, nodelist=['START'], \n",
- " node_color=node_colors['START'], \n",
- " node_size=3000, \n",
- " node_shape='o')\n",
- " \n",
- " # Draw END node\n",
- " nx.draw_networkx_nodes(G, pos, nodelist=['END'], \n",
- " node_color=node_colors['END'], \n",
- " node_size=3000, \n",
- " node_shape='o')\n",
- " \n",
- " # Draw edges with arrows\n",
- " nx.draw_networkx_edges(G, pos, \n",
- " edge_color='gray', \n",
- " arrows=True, \n",
- " arrowsize=10, \n",
- " #arrowstyle='->', \n",
- " width=2, node_size=3000)\n",
- " \n",
- " # Add labels with custom font\n",
- " nx.draw_networkx_labels(G, pos, \n",
- " font_size=10, \n",
- " font_weight='bold', \n",
- " font_family='sans-serif')\n",
- " \n",
- " \n",
- " plt.axis('off')\n",
- " return G, plt"
- ]
- },
- {
- "cell_type": "code",
- "execution_count": 27,
- "id": "972ca7f8-bc4a-4183-b586-9f0212ade50b",
- "metadata": {},
- "outputs": [
- {
- "data": {
- "text/plain": [
- "(\n",
- "
\n",
- " USAGE STATISTICS
\n",
- " {
\"completion_tokens\": 104,
\"prompt_tokens\": 7040,
\"total_tokens\": 7144,
\"step_count\": 2
}
\n",
- " \"completion_tokens\": 104,
\"prompt_tokens\": 7040,
\"total_tokens\": 7144,
\"step_count\": 2
}
![](\"./developer_portal_login.png\")
"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "66e47b34-5feb-4660-85f0-14b5ee7f62b9",
- "metadata": {},
- "source": [
- "## Part 2: Create an agent \n",
- "We'll first start with creating a basic Letta agent. "
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "id": "24745606-b0fb-4157-a5cd-82fd0c26711f",
- "metadata": {},
- "outputs": [],
- "source": [
- "basic_agent = client.create_agent(\n",
- " name=\"basic_agent\", \n",
- ")\n",
- "print(f\"Created agent: {basic_agent.name}\")"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "fcfb0d7b-b260-4bc0-8db2-c65f40e4afd5",
- "metadata": {},
- "source": [
- "We can now send messages from the user to the agent by specifying the `agent_id`: "
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "id": "a37bc9aa-4efb-4b4d-a6ce-f02505cb3240",
- "metadata": {},
- "outputs": [],
- "source": [
- "from letta.client.utils import pprint \n",
- "\n",
- "response = client.user_message(agent_id=basic_agent.id, message=\"hello\") \n",
- "pprint(response.messages)"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "9803140c-2b9d-426b-8812-9295806eb312",
- "metadata": {},
- "source": [
- "### Chatting in the developer portal \n",
- "You can also chat with the agent inside of the developer portal. Try clicking the chat button in the agent view. \n",
- "\n",
- "![](\"./dev_portal_agent_chat.png\")
"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "99ae20ec-e92e-4480-a652-b4aea28a6199",
- "metadata": {},
- "source": [
- "### Adding Personalization\n",
- "We can now create a more customized agent, but specifying a custom `human` and `persona` field. \n",
- "* The *human* specifies the personalization information about the user interacting with the agent \n",
- "* The *persona* specifies the behavior and personality of the event\n",
- "\n",
- "What makes Letta unique is that the starting *persona* and *human* can change over time as the agent gains new information, enabling it to have evolving memory. We'll see an example of this later in the tutorial."
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "id": "c0876410-4d70-490d-a798-39938b5ce941",
- "metadata": {},
- "outputs": [],
- "source": [
- "# TODO: feel free to change the human and person to what you'd like \n",
- "persona = \\\n",
- "\"\"\"\n",
- "You are a friendly and helpful agent!\n",
- "\"\"\"\n",
- "\n",
- "human = \\\n",
- "\"\"\"\n",
- "I am an Accenture consultant with many specializations. My name is Sarah.\n",
- "\"\"\"\n",
- "\n",
- "custom_agent = client.create_agent(\n",
- " name=\"custom_agent\", \n",
- " human=human, \n",
- " persona=persona\n",
- ")"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "21293857-80e4-46e4-b628-3912fad038e9",
- "metadata": {},
- "source": [
- "### Viewing memory \n",
- "You can view and edit the agent's memory inside of the developer console. There are two type of memory, *core* and *archival* memory: \n",
- "1. Core memory stores short-term memories in the LLM's context \n",
- "2. Archival memory stores long term memories in a vector database\n",
- "\n",
- "In this example, we'll look at how the agent can modify its core memory with new information. To see the agent's memory, click the \"Core Memory\" section on the developer console. \n",
- "\n",
- "![](\"./dev_portal_memory.png\")
"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "d8fa13eb-ce4b-4e4f-81b6-9d6ef6fa67c2",
- "metadata": {},
- "source": [
- "### Referencing memory \n",
- "Letta agents can customize their responses based on what memories they have stored. Try asking a question that related to the human and persona you provided. "
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "id": "fddbefe5-3b94-4a08-aa50-d80fb581c747",
- "metadata": {},
- "outputs": [],
- "source": [
- "response = client.user_message(agent_id=custom_agent.id, message=\"what do I work as?\") \n",
- "pprint(response.messages)"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "30497119-e208-4a4e-b482-e7cfff346263",
- "metadata": {},
- "source": [
- "### Evolving memory \n",
- "Letta agents have long term memory, and can evolve what they store in their memory over time. In the example below, we make a correction to the previously provided information. See how the agent processes this new information. "
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "id": "679fa708-20ee-4e75-9222-b476f126bc6f",
- "metadata": {},
- "outputs": [],
- "source": [
- "response = client.user_message(agent_id=custom_agent.id, message=\"Actually, my name is Charles\") \n",
- "pprint(response.messages)"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "686ac5a3-be63-4afd-97ae-b7d05219dd60",
- "metadata": {},
- "source": [
- "Now, look back at the developer portal and at the agent's *core memory*. Do you see a change in the *human* section of the memory? "
- ]
- },
- {
- "cell_type": "markdown",
- "id": "878d2f49-a5a6-4483-9f69-7436bcf00cfb",
- "metadata": {},
- "source": [
- "## Part 3: Adding Tools \n",
- "Letta agents can be connected to custom tools. Currently, tools must be created by service administrators. However, you can add additional tools provided by the service administrator to the agent you create. "
- ]
- },
- {
- "cell_type": "markdown",
- "id": "35785d36-2674-4a00-937b-4c747e0fb6bf",
- "metadata": {},
- "source": [
- "### View Available Tools "
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "id": "c307a6f7-276b-49f5-8d3d-48aaaea221a7",
- "metadata": {},
- "outputs": [],
- "source": [
- "tools = client.list_tools().tools\n",
- "for tool in tools: \n",
- " print(f\"Tool: {tool.name} - {tool.json_schema['description']}\")"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "318d19dc-b9dd-448c-ab5c-9c9311d21fad",
- "metadata": {},
- "source": [
- "### Create a tool using agent in the developer portal \n",
- "Create an agent in the developer portal and toggle additional tools you want the agent to use. We recommend modifying the *persona* to notify the agent that it should be using the tools for certain tasks. \n",
- "\n",
- "\n",
- "![](\"./dev_portal_tools.png\")
"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "aecdaa70-861a-43d5-b006-fecd90a8ed19",
- "metadata": {},
- "source": [
- "## Part 4: Cleanup (optional) \n",
- "You can cleanup the agents you creating the following command to delete your agents: "
- ]
- },
- {
- "cell_type": "code",
- "execution_count": null,
- "id": "1320d9c9-170b-48a8-b5e8-70737b1a8aac",
- "metadata": {},
- "outputs": [],
- "source": [
- "for agent in client.list_agents().agents: \n",
- " client.delete_agent(agent[\"id\"])\n",
- " print(f\"Deleted agent {agent['name']} with ID {agent['id']}\")"
- ]
- },
- {
- "cell_type": "markdown",
- "id": "510675a8-22bc-4f9f-9c79-91e2ffa9caf9",
- "metadata": {},
- "source": [
- "## 🎉 Congrats, you're done with day 1 of Letta! \n",
- "For day 2, we'll go over how to connect *data sources* to Letta to run RAG agents. "
- ]
- }
- ],
- "metadata": {
- "kernelspec": {
- "display_name": "letta",
- "language": "python",
- "name": "letta"
- },
- "language_info": {
- "codemirror_mode": {
- "name": "ipython",
- "version": 3
- },
- "file_extension": ".py",
- "mimetype": "text/x-python",
- "name": "python",
- "nbconvert_exporter": "python",
- "pygments_lexer": "ipython3",
- "version": "3.12.2"
- }
- },
- "nbformat": 4,
- "nbformat_minor": 5
-}