Loading...
Skip to main content

Getting Started with Fixie

Fixie consists of several components:

  • The Fixie console, which provides a web interface to create, manage, and debug Fixie Agents.
  • A set of APIs, which provide a programmatic interface to the Fixie platform.
  • The Fixie CLI, which provides a command-line interface to the Fixie platform.
  • The Fixie SDK, which provides a set of JavaScript interfaces for building Fixie Agents and client applications.

In the following sections, we'll show you how to get started building Fixie Agents directly from the web console, without having to write any code. In other sections of the tutorial, we'll show you how to build and deploy custom Agents using your own code.

Basic Concepts​

There are a few things that may be helpful to know before you start diving in to building with Fixie.

Fixie Agents​

A Fixie Agent is an AI-powered conversational agent that can answer questions, call APIs, fetch live data, or take actions requested by a user. An Agent can be accessed through a variety of means -- through a chat widget embedded on a website, or via a REST API.

The Fixie platform takes care of all of the details of deploying, managing, and monitoring your Agents, as well as connecting Agents to both static data sources (see Document Collections, below), APIs, and large language models such as GPT-4 or Llama2. Fixie also stores the conversational history between an end user and the agent, ensuring that the Agent can access the full state of the conversation when responding to the user.

While it is possible to deploy Fixie Agents on your own infrastructure, for this tutorial we'll focus on deploying Agents on the Fixie platform itself.

Document Collections​

A Document Collection, also called a Corpus, is a set of static documents that can be accessed by a Fixie Agent. Think of a Document Collection as a knowledge base that your Agent has access to and can consult when responding to a user. (This approach is often called Retrieval Augmented Generation, or RAG, in the AI community.)

Document Collections can be created from web pages, PDFs, text documents, Word documents, or other types of content. Fixie takes care of crawling the content, extracting the text, and storing it for use by your Agent.

A Document Collection consists of one or more Sources, where each Source represents a set of rules for how to collect and process data to include in the Document Collection. For example, a Document Collection consisting of a company's knowledge base might have a Source for its internal documents, another Source for its external-facing website, and a third Source with specific files that have been uploaded for inclusion.

Agent Runtimes​

Every Fixie Agent is powered by a Runtime, which is a program that handles messages from the user, calls out to large language models and other APIs to fetch data, and generates responses. An Agent Runtime can be implemented in any language and use any set of APIs or tools, as long it as conforms to the Fixie Agent conversation protocol.

By default, Fixie Agents use a Default Runtime that is provided by the Fixie platform and provides a suite of commonly-used capabilities for accessing data from Document Collections, calling optional external APIs, and so forth. If you create an Agent using the Default Runtime, there is no need to write any code -- all aspects of the Agent's behavior are determined through its configuration.

Conversations​

A Conversation represents a single conversational session between a Fixie Agent and an end user. The Conversation consists of a series of messages, either from the user to the Agent or from the Agent to the user.

Fixie stores the full history of each Conversation, providing the Agent with the full conversational context, so that it can reference the past messages in the Conversation when genrating its next reply to the user.

Setting up your account​

Head on over to console.fixie.ai and sign up for a free account. You can login with Google or GitHub. Once you have logged in and accepted the terms of service, your account is ready to go.

Creating your first Agent​

On the Fixie Console, you will see a list of Agents and a list of Document Collections. If you just set up your account, these sections will, of course, be empty. The first step is to create a Fixie Agent and start chatting with it.

Click on the New Agent button in the Console. You will see a window that lets you specify the agent display name, an optional description, a Document Collection, and an optional system prompt.

  • The display name is a human-readable name for the Agent. It is only used to help identify the agent on the console, so you can use whatever you want here.

  • The description is a short description of the Agent's purpose. Again, this is only used to help identify the Agent on the console, so feel free to leave this blank.

  • The Document Collection is the set of documents that the Agent will have access to when answering questions from the user. For now, leave this field blank, as we are going to create an Agent without access to any Document Collection for now.

  • Finally, the system prompt gives the Agent its basic instructions in terms of how it should respond to the user. For now, leave this field blank as well, as we are going to tinker with the system prompt below.

Once you click the Create Agent button, you will be taken to a page that allows you to chat with your new Agent. The Agent has no special knowledge, of course, and will generally only respond in generic ways to questions, although you can do things like ask it to write a poem or tell you a joke.

Under the hood, this basic starter Agent is simply a thin wrapper on top of a large language model. On the Agent chat page, you can change the model used by the Agent, for example, by selecting between models like GPT-4, GPT-3.5, and Claude.

The other thing you can do here is change the Agent's System Prompt. The System Prompt is the text provided to the Agent's language model for each message it receives from the user, and can be used to tailor the Agent's behavior. For example, you might try something like:

Respond to the user as an erudite professor from the 19th century, using somewhat pompous language and lots of flowery turns of phrase.

Change the system prompt, hit the Save button, and ask the same question of the Agent to see how its responses change.

Creating a Document Collection​

So far, we have created an Agent that can respond to generic questions, but it doesn't have any special knowledge of the world beyond that in the underlying Large Language Model. Next, we're going to augment the Agent with a Document Collection so it can answer questions grounded in some knowledge that we give it.

Go back to the main Fixie Console page and click on the New Document Collection button. Give the Document collection a name, like "Wikipedia Article about Foxes". On the next screen, you need to add a Source to the Document Collection. Add the URL https://en.wikipedia.org/wiki/Fox to the Source, and click the Add button.

You should now see that the Document Collection has a single Source, which is listed as Processing on the console. At this point, Fixie will go and crawl the Wikipedia page, along with other pages that it finds linked to the original page that start with the pattern https://en.wikipedia.org/wiki/Fox*. Be patient! Crawling and indexing these pages will take a little while, but go get a cup of coffee and it should be done within 10-15 minutes or so.

Once the Document Collection has finished processing, you should get an email notification, and its status on the console should change from Processing to Ready.

Creating a new Agent with a Document Collection​

Now that we have the Document Collection, let's create a new Agent that uses it to answer questions. Go back to the Fixie Console and click on New Agent again. This time, be sure to select the Document Collection that you just created in the drop-down box when you create the Agent.

Now, when you ask the Agent a question related to foxes, it should be able to answer it, but will also cite the Wikipedia article in the Document Collection as part of its answer. While the underlying LLM almost certainly has lots of knowledge about foxes already, we know that the Agent is using the specific information in these Wikipedia articles, rather than just relying on its internal knowledge.

In this example, you can also ask questions related to other fox-related topics, such as Fox News, the town of Fox, Oregon, or the sport of fox hunting. This is because the Document Collection gathered other, related Wikipedia articles in its crawl. (It is possible to control this behavior more precisely using the Fixie CLI and SDK.)

Embedding your Agent​

Okay, it's great that you can chat with your Agent on the Fixie Console, but ideally you want to make the Agent available for others to use from another website.

There are a few options to embedding your Agent on another website or app:

  • You can embed the Agent UI directly, as an <iframe>, on a website.
  • You can embed the Agent UI as a React component.
  • You can invoke the Agent directly through a REST API, providing your own UI.

For now, let's show how to do this using the simplest approach, which is to embed the Agent as an <iframe> on a website. On the Fixie Console, click on the Embed tab, and you will see a snippet of HTML that you can copy and paste into your website. For example, you can embed the mdw/fox-agent Agent using:

<iframe src="https://embed.fixie.ai/embed/mdw/fox-agent" width="400" height="800"></iframe>

You can also customize the agent UI, including changing the agent title, colors, and so forth. Instructions are provided on the Agent's Embed page on the Fixie Console.