Platform Quickstart

This guide will help you get started with the Tiptree Platform.

Installation

You will need Python 3.10 or later installed on a Unix-like environment (Linux, MacOS, or Windows WSL).

Make sure to activate your virtual environment, then install the Python client:

$ pip install tiptree
---> 100%
Successfully installed tiptree

Sign in or sign up for an account

You can sign up for an account from the command line using the signup command:

$ tiptree signup

During signup, you will be:

1. Asked for your email, first name, and optional last name
2. Sent a verification code to your email
3. Prompted to create an API key
4. Given the option to save your credentials to ~/.tiptreerc/credentials

Your API key will look like tiptree-<some-random-string>. Please make sure to save this key securely as it won’t be shown again.

If you already have an account, you can sign in using the signin command:

$ tiptree signin

You will have the option to create an API key and save your credentials.

Using the API

Using the official Python Client

Here is how you would create an agent and send a message to it using the Python client:

from tiptree import Agent

# Create an agent
agent = Agent.get_or_create()

# Create an agent session
session = agent.create_agent_session()

# Send message to session
sent_message = session.send_message("What's the weather like in Berlin right now?")

# Wait for the response
received_message = session.wait_for_next_message()
print(received_message.content)

Environment Variables

If you saved your API key to ~/.tiptreerc/credentials, the script above should work out-of-the-box. Otherwise, you will need to set the TIPTREE_API_KEY environment variable to your API key before running the script.

Let’s break this down. The first step is to create an agent:

agent = Agent.get_or_create()

This will create an agent if it doesn’t exist, otherwise it will return the existing agent.

Agents are the primary resource in the Agent Runtime Platform. Each agent can have multiple sessions, which are like “conversations” with the said agent. Each agent session can in turn have multiple messages.

Agent Sessions and Memory

Each agent session contributes to the agent’s global memory, which is accessible to all sessions. This means that the agent can use the memories created from previous sessions to inform its responses.

This is a powerful feature that allows the agent to learn from previous conversations and improve its responses over time. However, it also means that the agent’s responses can change over time as it learns from previous conversations.

Take a look at the memory use section to learn about about how you can control this behavior.

To create an agent session, you can use the create_agent_session method.

session = agent.create_agent_session()

This is also where you can optionally pass in special context for the session. For example:

session = agent.create_agent_session(
    initial_prompt="The user is an AI engineer interested in building agents."
)

We recommend using the initial_prompt to provide additional context for the session. Instructions for the agent are best passed in as a message to the session:

sent_message = session.send_message(
    "What's the weather like in Berlin right now?"
)

Finally, we wait for the response from the agent:

received_message = session.wait_for_next_message()
print(received_message.content)

This should print the response:

Currently in Berlin, it's 9.6°C (feels like 8.3°C) with clear skies. The conditions are:
- Wind: 2.7 m/s from the west-northwest
- Humidity: 25%
- Visibility: 10 km
- Air pressure: 1030 hPa

It's a sunny day with no cloud cover. The sun will set at around 18:15 local time.

How does this work?

The agent runtime equips all agents with a set of essential tasks, which include tasks to search the web, open websites, and in this case, fetch weather data. The agent finds the best task to use based on your request.

Task Whitelisting and Blacklisting

You can also choose to equip your agent with a subset of tasks by specifying a whitelist of tasks when creating the agent. For example, to create an agent equipped with only web search and web browsing tasks, you can do the following:

agent = Agent.create(
    name="My Agent",
    task_whitelist=[
        "tiptree-systems/web-search/search",
        "tiptree-systems/web-browser/answer-from-url",
    ]
)

This will equip the agent with only the specified tasks and prevent it from using any other tasks. This means that all sessions created by this agent will only have access to these tasks.

Of course, you may also update the task whitelist at any time. For example, to update the task whitelist to include all tasks, you can do the following:

agent.update(
    task_whitelist=["*/*/*"]
)

Finally, you can also choose to blacklist certain tasks. For example, to blacklist the tiptree-systems/web-browser/open-url task, you can do the following:

agent.update(
    task_blacklist=["tiptree-systems/web-browser/open-url"]
)

Memory Use

Agents in the runtime have two types of memory capabilities:

1. Basic Memory: The ability to read from and write to their memory store. This allows agents to maintain context across sessions and recall specific information when needed.

2. Associative Recall (Remembrance): A more sophisticated capability that allows agents to perform associative recall, similar to how humans naturally remember related concepts. This is based on the concept of Remembrance Agents.

You can control these capabilities independently:

• Setting enable_memory=False disables all memory operations (both read and write)
• Setting enable_remembrance=False disables only associative recall while preserving basic memory operations

For example, to completely disable memory:

agent.update(enable_memory=False)

To disable associative recall while preserving basic memory operations:

agent.update(enable_remembrance=False)

You may also set these options when creating an agent. For example:

agent = Agent.create(
    name="My Agent",
    enable_memory=False,
    enable_remembrance=False
)

This creates an agent that does not reuse any information between sessions.

Using cURL

The API itself is available via curl. API reference available here.