Creating Custom Agents
Guide for Power User and Org Admin Roles on creating Custom Agents.
All About Custom Agents
Note that creating standalone Custom Agents is not available to all users, and generally speaking is only an available/visible option if you have the roles Power User, or Org Admin. Regular User accounts should use Projects, which are just as powerful as Custom Agents, and in some ways more powerful. Make sure you read these articles to learn about those: —>
Overview
In Sapience, like all objects/resources, Agents have a ‘scope’, which controls who can see them and use them. If you haven’t already, you must read the Sapience Objects & Resources article linked above, or the rest of this article will not make sense.
Agents can have these scopes:
- Global: built by the Sapience team, and made available to all users. The Web Research Agent is a good example of this.
- Org: these are Agents built for your Organization, that all Users within your Organization can see/use. These are usually created by your Org Admin, or by one of the Sapience team on behalf of your Org. When you first login to Sapience, you probably had a combination of Global and Org-scoped Agents available to you in the Agent Selector and Agent Browser.
- User: these are Agents created by you, for use by you, and only available to you. You technically can share these, just like other Sapience objects, but we’ll address that in a separate article. For now, think of User-scoped Agents as Agents that you create, own, use, and delete when you want.
Creating Custom Agent Walkthrough:
Lets walk through it:
The screen above is the 1st step to defining your custom Agent. You can see here we are logged in as a Power User, not Org Admin. Org Admins can select if they want to create a User-scoped Agent or an Org-scoped Agent.
Core Agent Meta-Data
On this screen you have some decisions to make:
- Name: this is what will show in the Agent Selector and the Chat interface. You can change this later, but try to pick something that makes it clear what this Agent is for, and what it does - particularly if you are creating an Org-scoped Agent for others to use.
- AI Model: this is where you choose which “engine” you want powering your Agent. There are many options and different models from different vendors are good at different things. If you want the “flagship” model from Opean AI, then select GPT-X.Y, and pick the highest number there is. That will give you the same model that powers ChatGPT. Note also that as you select different models, the GUI will tell you about the model and what its good at.
- Description: this text will display in the header area of the main Chat interface, but crucially it also displays in the Agent Browser. Therefore, you want to write a clear description that tells users what to expect from the Agent and when to use it.
- Welcome Message: this is the message that is printed at the top of a new Chat when a User starts a Conversation with your Agent. You can re-use what you wrote in the Description, or you can provide more detail on the data and behavior that users can expect from this Agent. See screenshots below:
- Starter Questions: you can leave these blank but that is usually not a good idea. The Starter Questions are the clickable questions that the Agent prints as part of its welcome message sequence to the user. Its a good idea to program in some starter questions that demonstrate what your Agent can do. If you built it for a purpose, then pre-seed it with some clickable questions that make sense for this Agent’s context.
Pro tip: its worth noting that OTHER AGENTS also read the name and description data on any Agent you create, and use this to decide if they want “help” from this Agent in a Team-of-Agents approach. Therefore, you should think through what the core details of your Agent are, and make them very clear, to both human and AI readers.
Because in this walkthrough we are building an Agent that is an expert on AI Engineering, we have pre-seeded the Agent with questions relating to the field:
Adding Knowledge to your Agent
Next we’re goign to add knowledge to the Agent. In User-scoped Agents, you can add knowledge from files (RAG Agents) as well as from the web with specific webpage URLs that you add. Remember that Agents have access to the Web Research Agent as a tool, so adding specific URLs will focus the Agent on those pages, but doesn’t prevent the Agent from doing Web Research more broadly.
In the screenshot below, you can see that we’ve added one file (in this case a 250,000 word document all about the Open AI Agents SDK) and we’ve given the Agent a URL that it should ground itself on (the Open AI cookbook):
Seeing Your Grounded Agent in Action
Once the Agent is created, if we then look at the Chat interface, you will see the different data items from above present throughout the Sapience interface. Going from top to bottom and left to right in the next screenshot you can see: 1) Agent Description; 2) Agent Name; 3) Welcome Message; 4) Starter Questions being displayed in the new Conversation we started.
A note on email: you can also see that the Agent was automatically given an email address, and you can email with the Agent immediately.
In action: Now it gets to work, leveraging the file data provided (RAG) as well as live web research (using Web Research Agent) as well as fetching URLs provided as a starting point:
After a little while, I get a great answer, where my Custom Agent has used the data I gave it, combined with data living on live websites I told it about, as well as its own use of the Web Research Agent. Its focussed on the area that I told the Agent to be focussed on, and the results are great:
Checking sources:
The whole idea of creating a custom Agent is to create a focussed and grounded Agent that’s expert in the data you want it to be. So lets check the chat with the Agent we had above. If we inspect the sources relied upon you can see its using both sets of data:
