diff --git a/docs/docs/01-overview.md b/docs/docs/01-overview.md index 2584591e..16cb7b5a 100644 --- a/docs/docs/01-overview.md +++ b/docs/docs/01-overview.md @@ -5,7 +5,7 @@ slug: / import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -Otto8 is an open source enterprise agent platform. Key features include: +Obot is an open source enterprise agent platform. Key features include: - Ability to build agents to support a variety of usecases including copilots, assistants, and autonomous agentic workflows. - Integration with leading LLM providers - Built-in RAG for your data @@ -13,15 +13,20 @@ Otto8 is an open source enterprise agent platform. Key features include: - OAuth 2.0 authentication ### Getting Started -Launch Otto8 via docker: + +Launch Obot via Docker: + ```bash -docker run -d -p 8080:8080 -e "OPENAI_API_KEY=" ghcr.io/otto8-ai/otto8:latest +docker run -d -p 8080:8080 -e "OPENAI_API_KEY=" ghcr.io/obot-platform/obot:main ``` + Then visit http://localhost:8080. -The `otto8` CLI can be installed via brew on MacOS or Linux: +The `Obot` CLI can be installed via brew on macOS or Linux: + ```bash -brew tap otto8-ai/tap -brew install otto8 +brew tap obot-platform/tap +brew install obot ``` -or by downloading the binary for your platform from our [latest release](https://github.com/otto8-ai/otto8/releases/latest). + +or by downloading the binary for your platform from our [latest release](https://github.com/obot-platform/obot/releases/latest). diff --git a/docs/docs/02-concepts/01-agents.md b/docs/docs/02-concepts/01-agents.md index 7d2f9f49..4b0a8723 100644 --- a/docs/docs/02-concepts/01-agents.md +++ b/docs/docs/02-concepts/01-agents.md @@ -1,12 +1,15 @@ # Agents -An agent is a program that combines AI, a set of instructions, and access to your services and data to perform tasks, answer questions, and interact with its environment. Administrators create agents for end-users to interact with. Below are the key concepts and fields you need to understand to build an agent. +An agent is a program that combines AI, a set of instructions, and access to your services and data to perform tasks, answer questions, and interact with its environment. +Administrators create agents for end-users to interact with. Below are the key concepts and fields you need to understand to build an agent. ### Name and Description These fields will be shown to your end-users to help them identify and understand your agents. ### Instructions -Instructions let you guide your agent's behavior. You should use this field to specify things like the agent's objectives, goals, personality, and anything special it should know about its users or use cases. Here is an example set of instructions for a HR Assistant designed to answer employee's HR-related questions and requests: +Instructions let you guide your agent's behavior. +You should use this field to specify things like the agent's objectives, goals, personality, and anything special it should know about its users or use cases. +Here is an example set of instructions for a HR Assistant designed to answer employee's HR-related questions and requests: > You are an HR assistant for Acme Corporation. Employees of Acme Corporation will chat with you to get answers to HR related questions. If an employee seems unsatisfied with your answers, you can direct them to email hr@acmecorp.com. @@ -14,29 +17,44 @@ Instructions let you guide your agent's behavior. You should use this field to s You can specify the model each agent will use. If you make no selection, the system default will be used. For more on models, see our [Models concept](models). ### Tools -Tools dictate what an agent can do and how it can interact with the rest of the world. The tools shipped with Otto8 help make their purpose clear. A few examples include: +Tools dictate what an agent can do and how it can interact with the rest of the world. The tools shipped with Obot help make their purpose clear. A few examples include: - Creating an email draft - Sending a Slack message - Getting the contents of a web page You can configure an agent with **Agent Tools** and **User Tools**, described below: - **Agent Tools** will always be enabled on an agent. The agent will always be able to call them. -- **User Tools** are optional. They are available for a user to add to their chat with the agent. Users can add and remove these tools at will. +- **User Tools** are optional. They are available for a user to add to their chat with the agent. Users can add and remove these tools at will. ### Knowledge -Knowledge lets you supply your agent with information unique to its use case. You can upload files directly or pull in data from Notion, OneDrive, or a website. If you've configured your agent with knowledge, it will make queries to its knowledge database to help respond to the users' requests. +Knowledge lets you supply your agent with information unique to its use case. +You can upload files directly or pull in data from Notion, OneDrive, or a website. +If you've configured your agent with knowledge, it will make queries to its knowledge database to help respond to the users' requests. -You should supply a useful **Knowledge Description** to help the agent determine when it should make a query. Here is an example knowledge description for an HR Assistant that has documents regarding a companies HR policies and procedures: +You should supply a useful **Knowledge Description** to help the agent determine when it should make a query. +Here is an example knowledge description for an HR Assistant that has documents regarding a companies HR policies and procedures: > Detailed documentation about the human resource policies and procedures for Acme Corporation. ### Preview Chat and Threads -When creating an agent, you can chat with it to see how it behaves based on how you've configured it. You can even create access past preview threads to compare behavior as your iterate on it. +When creating an agent, you can chat with it to see how it behaves based on how you've configured it. +You can even create access past preview threads to compare behavior as your iterate on it. ### Publishing -When you publish an agent, you make it available for end-users to chat with. You'll first be asked to specify an alias for the agent. This alias will be used to generate a unique URL for the agent. Only alphanumeric characters and hyphens are allowed. Once you've picked an alias and hit the publish button, the agent will immediately be available for users to discover and chat with. - -The end-user chat interface is available at the root of the domain on which otto8 is running. For example, if you accessed the admin UI at `https://otto8.acmecorp.com/admin`, the end-user chat UI is available at `https://otto8.acmecorp.com/`. A publish agent will be available in the agent dropdown on this page as well as at its own dedicated page based on its alias. For example, if you gave your agent the alias `hr-assistant`, it would be available at https://otto8.acmecorp.com/hr-assistant`. - -It is possible to request the same alias for two agents. This is to allow you to seamlessly swap agents out without your users noticing. For example, suppose you've published your first agent with the alias `hr-assistant` and it's available at `https://otto8.acmecorp.com/hr-assistant`. If you want to experiment with a new version of your agent, you can create a brand new one, refine its behavior, and when you're ready, set its alias to `hr-assistant` as well. When you're ready to switch your users to the new agent, just unpublish your first agent. Users will be swapped over to the new agent without losing any of their chat history. \ No newline at end of file +When you publish an agent, you make it available for end-users to chat with. +You'll first be asked to specify an alias for the agent. This alias will be used to generate a unique URL for the agent. +Only alphanumeric characters and hyphens are allowed. +Once you've picked an alias and hit the publish button, the agent will immediately be available for users to discover and chat with. + +The end-user chat interface is available at the root of the domain on which Obot is running. +For example, if you accessed the admin UI at `https://obot.acmecorp.com/admin`, the end-user chat UI is available at `https://obot.acmecorp.com/`. +A published agent will be available in the agent dropdown on this page as well as at its own dedicated page based on its alias. +For example, if you gave your agent the alias `hr-assistant`, it would be available at https://obot.acmecorp.com/hr-assistant`. + +It is possible to request the same alias for two agents. +This is to allow you to seamlessly swap agents out without your users noticing. +For example, suppose you've published your first agent with the alias `hr-assistant` and it's available at `https://obot.acmecorp.com/hr-assistant`. +If you want to experiment with a new version of your agent, you can create a brand new one, refine its behavior, and when you're ready, set its alias to `hr-assistant` as well. +When you're ready to switch your users to the new agent, just unpublish your first agent. +Users will be swapped over to the new agent without losing any of their chat history. diff --git a/docs/docs/02-concepts/02-threads.md b/docs/docs/02-concepts/02-threads.md index c90efda4..eb664460 100644 --- a/docs/docs/02-concepts/02-threads.md +++ b/docs/docs/02-concepts/02-threads.md @@ -1,5 +1,8 @@ # Threads -A thread represents each chat conversation between an agent and a user or the execution of a workflow. On the Threads page, you'll find a list of all threads within your system. Clicking on a thread will display all related messages and metadata, such as files created or uploaded by the user. +A thread represents each chat conversation between an agent and a user or the execution of a workflow. +On the Threads page, you'll find a list of all threads within your system. +Clicking on a thread will display all related messages and metadata, such as files created or uploaded by the user. -Deleting a thread will permanently remove it from the system. If a deleted thread was associated with an agent, the user's chat history with that agent will be lost, and any new conversation will start afresh. \ No newline at end of file +Deleting a thread will permanently remove it from the system. +If a deleted thread was associated with an agent, the user's chat history with that agent will be lost, and any new conversation will start afresh. diff --git a/docs/docs/02-concepts/03-tools.md b/docs/docs/02-concepts/03-tools.md index edef4a7f..6b36a63b 100644 --- a/docs/docs/02-concepts/03-tools.md +++ b/docs/docs/02-concepts/03-tools.md @@ -1,10 +1,10 @@ # Tools -Tools define an agent's capabilities and determine how it interacts with the world. Otto8 includes a wide range of built-in tools. To help illustrate what tools can do, here are a few examples: +Tools define an agent's capabilities and determine how it interacts with the world. Obot includes a wide range of built-in tools. To help illustrate what tools can do, here are a few examples: - Creating email drafts - Sending Slack messages - Retrieving the contents of a web page -The **Tools** page displays all built-in tools available in Otto8, along with any custom tools you've added. The built-in tools are open source and can be accessed [here](https://github.com/otto8-ai/tools). +The **Tools** page displays all built-in tools available in Obot, along with any custom tools you've added. The built-in tools are open source and can be accessed [here](https://github.com/obot-platform/tools). For instructions on creating your own tools, refer to our [Tool Authoring Guide](/tools/first-tool). \ No newline at end of file diff --git a/docs/docs/02-concepts/04-users.md b/docs/docs/02-concepts/04-users.md index 01e8808f..4fc0b01f 100644 --- a/docs/docs/02-concepts/04-users.md +++ b/docs/docs/02-concepts/04-users.md @@ -1,3 +1,5 @@ # Users -The **Users** page displays all the users in your system. Users can be configured as admins by following our [configuration guide](/configuration/general). Non-admin users, referred to as "end-users" in this documentation, only have access to the chat interface available at the root of the domain where Otto8 is running. For example, if the admin interface is accessed at `https://otto8.acmecorp.com/admin`, the end-user chat interface would be available at `https://otto8.acmecorp.com/`. +The **Users** page displays all the users in your system. Users can be configured as admins by following our [configuration guide](/configuration/general). +Non-admin users, referred to as "end-users" in this documentation, only have access to the chat interface available at the root of the domain where Obot is running. +For example, if the admin interface is accessed at `https://obot.acmecorp.com/admin`, the end-user chat interface would be available at `https://obot.acmecorp.com/`. diff --git a/docs/docs/02-concepts/05-oauth-apps.md b/docs/docs/02-concepts/05-oauth-apps.md index a38ab0c4..a25357c8 100644 --- a/docs/docs/02-concepts/05-oauth-apps.md +++ b/docs/docs/02-concepts/05-oauth-apps.md @@ -1,15 +1,23 @@ # OAuth Apps -OAuth 2.0 (hereon referred to as simply OAuth) is an open standard for authorization, designed to allow applications to access a user’s resources on another service without sharing their password. It enables a secure and standardized way for apps to connect to external services. +OAuth 2.0 (hereafter referred to as simply OAuth) is an open standard for authorization, designed to allow applications to access a user’s resources on another service without sharing their password. +It enables a secure and standardized way for apps to connect to external services. -Otto8 makes use of OAuth to allow agents to interact with systems and services on behalf of the user. For example, through OAuth, an agent can check a user's Slack messages or even send a message as the user. +Obot makes use of OAuth to allow agents to interact with systems and services on behalf of the user. +For example, through OAuth, an agent can check a user's Slack messages or even send a message as the user. -If an Otto8 tool needs to talk to an external service and wants to use Oauth to do so, it will need a corresponding Oauth App. The built-in OAuth Apps corresponding to our built-in tools. +If an Obot tool needs to talk to an external service and wants to use Oauth to do so, it will need a corresponding Oauth App. +The built-in OAuth Apps corresponding to our built-in tools. -Because configuring an OAuth integration can be complicated, Otto8's built-in Oauth Apps are pre-configured to use a public gateway and ran by Acorn Labs. We've configured a corresponding OAuth application in each service provider (ie, GitHub, Google, and Microsoft) so that you can start using the tools without any additional configuration. Any of these integrations can be overridden to use your own custom integration. Each service provider is different, but you just need to follow the in-app instructions to configure them properly. +Because configuring an OAuth integration can be complicated, Obot's built-in OAuth Apps are pre-configured to use a public gateway and ran by Acorn Labs. +We've configured a corresponding OAuth application in each service provider (i.e., GitHub, Google, and Microsoft) so that you can start using the tools without any additional configuration. +Any of these integrations can be overridden to use your own custom integration. +Each service provider is different, but you just need to follow the in-app instructions to configure them properly. ### Custom OAuth Apps -You can configure a custom OAuth app to integrate with any service provider that supports OAuth. You can then use this when authoring your own custom tools that call that service. For more details, see our [Tool Authoring Guide](/tools/integrating-oauth). +You can configure a custom OAuth app to integrate with any service provider that supports OAuth. +You can then use this when authoring your own custom tools that call that service. +For more details, see our [Tool Authoring Guide](/tools/integrating-oauth). When configuring a custom OAuth App, you'll first be asked to provide the following values: - **Name** - This is just the friendly name you'll use to identify your app diff --git a/docs/docs/02-concepts/06-workflows.md b/docs/docs/02-concepts/06-workflows.md index b3634121..ef07a7fb 100644 --- a/docs/docs/02-concepts/06-workflows.md +++ b/docs/docs/02-concepts/06-workflows.md @@ -4,7 +4,7 @@ A workflow is a series of steps that can be easily expressed through natural lan **Parameters** are optional and allow you to specify inputs to your workflow. This is particularly useful when another workflow or an agent is calling your workflow. -**Steps** represent instructions to be carried out by the workflow. A step can have it's own set of tools and can even call out to other workflows or agents. Otto8 supports two special types of steps: **If Statements** and **While Loops**. +**Steps** represent instructions to be carried out by the workflow. A step can have it's own set of tools and can even call out to other workflows or agents. Obot supports two special types of steps: **If Statements** and **While Loops**. **If Statements** allow you to specify a condition and different actions to take based on whether that condition is true or false. @@ -12,16 +12,16 @@ A workflow is a series of steps that can be easily expressed through natural lan ### Triggering Workflows -You can trigger a workflow in a few ways. The firest is via the **invoke** cli command. Here's an example that invokes a workflow that has two parameters: +You can trigger a workflow in a few ways. The first is via the **invoke** cli command. Here's an example that invokes a workflow that has two parameters: ``` -otto8 --debug invoke w1km9xw "name='John Doe', address='123 Main Street'" +obot --debug invoke w1km9xw "name='John Doe', address='123 Main Street'" ``` You can find the workflow id by listing workflows: ``` -otto8 workflows +obot workflows ``` -Another way to trigger a workflow is via a **webhook**. This feature is still under development and doesn't yet have a corresponding CLI commmand, but you can create a webhook via **curl**. Here's an example: +Another way to trigger a workflow is via a **webhook**. This feature is still under development and doesn't yet have a corresponding CLI command, but you can create a webhook via **curl**. Here's an example: ``` curl -X POST 'http://127.0.0.1:8080/api/webhooks' -d '{ \ "description": "Webhook to respond to pagerduty events", \ @@ -47,11 +47,10 @@ If any of these headers are seen in the webhook request, they'll be passed to th } ``` -Services that offer webhook integration typically supply a shared secret used to compute a signature for the request and expect the webhook receiver to verify the signature, which otto8 does. Two such services are GitHub and PagerDuty. To understand how to set these fields, you can find their webhook documentation here: +Services that offer webhook integration typically supply a shared secret used to compute a signature for the request and expect the webhook receiver to verify the signature, which Obot does. +Two such services are GitHub and PagerDuty. To understand how to set these fields, you can find their webhook documentation here: - https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries - https://developer.pagerduty.com/docs/28e906a0e4f36-verifying-signatures Refer to your service's webhook documentation to find the values to set for these fields. - - diff --git a/docs/docs/02-concepts/07-models.md b/docs/docs/02-concepts/07-models.md index 84519b5b..a6f11a80 100644 --- a/docs/docs/02-concepts/07-models.md +++ b/docs/docs/02-concepts/07-models.md @@ -2,12 +2,13 @@ A model is an AI program that has been trained on data to perform tasks, recognize patterns, and make decisions. Popular examples include OpenAI's GPT-4o and Anthropic's Claude 3.5 Sonnet. -Otto8 comes with popular models for OpenAI preconfigured, but admins can modify them or create new ones. Agents, workflows, and tools can specify what model they should use. If they do not specify one, the system's default model is used. +Obot comes with popular models for OpenAI preconfigured, but admins can modify them or create new ones. +Agents, workflows, and tools can specify what model they should use. If they do not specify one, the system's default model is used. -To create a model for a provider other than OpenAI, you must first enable the corresponding **Model Provider**. Otto8 currently supports four model providers: +To create a model for a provider other than OpenAI, you must first enable the corresponding **Model Provider**. Obot currently supports four model providers: - OpenAI - Azure OpenAI - Anthropic - Ollama -You can learn more about how to configure Model providers in our [Model Provider Configuration Guide](/configuration/model-providers) \ No newline at end of file +You can learn more about how to configure Model providers in our [Model Provider Configuration Guide](/configuration/model-providers) diff --git a/docs/docs/03-tools/01-first-tool.mdx b/docs/docs/03-tools/01-first-tool.mdx index 6cb2f8f1..df2e8c87 100644 --- a/docs/docs/03-tools/01-first-tool.mdx +++ b/docs/docs/03-tools/01-first-tool.mdx @@ -11,11 +11,11 @@ import GoHashToolReadme from '../../snippets/go-hash-tool-readme.md.mdx'; # Writing your First Tool -While Otto8 ships with a robust library of built-in [Tools](../02-concepts/03-tools.md), building custom -Tools tailored to your ecosystem will supercharge your Agents. +While Obot ships with a robust library of built-in [Tools](../02-concepts/03-tools.md), building custom +tools tailored to your ecosystem will supercharge your Agents. -The following guides will show you how to write and package custom Tools in Python, Node.js, and Go; -unleashing the full potential of your Agents by enabling them to integrate with any data source, service, +The following guides will show you how to write and package custom tools in Python, Node.js, and Go; +unleashing the full potential of your agents by enabling them to integrate with any data source, service, or platform with just a few lines of code. diff --git a/docs/docs/03-tools/02-integrating-oauth.md b/docs/docs/03-tools/02-integrating-oauth.md index 9d2654d6..cebceccf 100644 --- a/docs/docs/03-tools/02-integrating-oauth.md +++ b/docs/docs/03-tools/02-integrating-oauth.md @@ -1,6 +1,7 @@ # Integrating Tools with OAuth -One of the most powerful features of Otto8 is its ability to integrate agents with your services using custom tools and OAuth apps. This guide will walk you through the process of creating and using these. We'll be integrating with [GitLab](https://about.gitlab.com/). +One of the most powerful features of Obot is its ability to integrate agents with your services using custom tools and OAuth apps. +This guide will walk you through the process of creating and using these. We'll be integrating with [GitLab](https://about.gitlab.com/). The high-level steps we'll follow are: 1. Create our custom tool @@ -13,7 +14,10 @@ The high-level steps we'll follow are: You'll need a [GitLab](https://gitlab.com/) account with at least one project (their equivalent of a GitHub repo). ### Create our custom tool -The source for the tool we are creating can be found at https://github.com/otto8-ai/gitlab-example-tool. This guide won't cover writing the python code for the tool, so feel free to clone or fork this repo. We will review the **tool.gpt** file: +The source for the tool we are creating can be found at https://github.com/otto8-ai/gitlab-example-tool. +This guide won't cover writing the Python code for the tool, so feel free to clone or fork this repo. +We will review the **tool.gpt** file: + ``` Name: List Projects Description: List the user's GitLab Projects @@ -29,27 +33,39 @@ GitLab !metadata:*:icon https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/gitlab-logo-duotone.svg ``` -This tool.gpt file just has a single tool name "List Projects" defined. You can define more tools by separating them with `---`. You can see that this tool defines a name, description, credential (we'll revisit this in a later step), and a command that is the actual code to be run. If you review the repository, you'll notice that `projects.py` is one of the files in the repository. -There are two metadata sections: one for category and one for icon. These will be used to display the tool in the Otto8 UI. +This tool.gpt file just has a single tool name "List Projects" defined. +You can define more tools by separating them with `---`. +You can see that this tool defines a name, description, credential (we'll revisit this in a later step), and a command that is the actual code to be run. +If you review the repository, you'll notice that `projects.py` is one of the files in the repository. + +There are two metadata sections: one for category and one for icon. These will be used to display the tool in the Obot UI. ### Create our OAuth App -Next we need to create our OAuth app in Otto8. This always involves also creating an equivalent resource in the service provider (GitLab in this case). Each service differs in how you do this. For GitLab, the guide is [here](https://docs.gitlab.com/ee/integration/oauth_provider.html). For this guide, follow the [Create a User Owned Application](https://docs.gitlab.com/ee/integration/oauth_provider.html#create-a-user-owned-application) instructions. +Next we need to create our OAuth app in Obot. This always involves also creating an equivalent resource in the service provider (GitLab in this case). +Each service differs in how you do this. For GitLab, the guide is [here](https://docs.gitlab.com/ee/integration/oauth_provider.html). +For this guide, follow the [Create a User Owned Application](https://docs.gitlab.com/ee/integration/oauth_provider.html#create-a-user-owned-application) instructions. -Once you get to the step where you're asked to supply a Redirect URL, go to your Otto8 installation, navigate to OAuth Apps, and click **Create a Custom OAuth App**. You're then asked to supply a name, integration (which will be auto-filled), authorization URL, and token URL. Set the name to "GitLab Example". This will cause the Integration field to be set to **gitlab-example**. +Once you get to the step where you're asked to supply a Redirect URL, go to your Obot installation, navigate to OAuth Apps, and click **Create a Custom OAuth App**. +You're then asked to supply a name, integration (which will be auto-filled), authorization URL, and token URL. Set the name to "GitLab Example". +This will cause the Integration field to be set to **gitlab-example**. GitLab's documentation doesn't make this clear, but the authorization and token URLs are as follows: - Authorization: https://gitlab.com/oauth/authorize - Token: https://gitlab.com/oauth/token -Set these values accordingly and click Next. You'll now be presented with a Redirect URL and be asked to supply a Client ID and Client Secret. First, return to GitLab, supply the Redirect URL, select the scopes **read_api* and **read_user**, and click **Save application**. You'll then be presented with the Client ID (which they call Application ID) and Client Secret (which they just call Secret). Return to Otto8, enter these values, and click Submit. This will create the OAuth app. +Set these values accordingly and click Next. You'll now be presented with a Redirect URL and be asked to supply a Client ID and Client Secret. +First, return to GitLab, supply the Redirect URL, select the scopes **read_api** and **read_user**, and click **Save application**. +You'll then be presented with the Client ID (which they call Application ID) and Client Secret (which they just call Secret). +Return to Obot, enter these values, and click Submit. This will create the OAuth app. ### Configure a credential tool that integrates our custom tool and OAuth app The credential tool can be found in our example repo at https://github.com/otto8-ai/gitlab-example-tool/blob/main/credential/tool.gpt. Here's the contents: + ``` Name: GitLab OAuth Credential -Share Credential: github.com/otto8-ai/tools/oauth2/tool.gpt as gitlab-example +Share Credential: github.com/obot-platform/tools/oauth2/tool.gpt as gitlab-example with GITLAB_OAUTH_TOKEN as env and gitlab-example as integration and "read_api read_user" as scope @@ -58,24 +74,31 @@ Type: credential Here is a breakdown of the above: - `Name` is not too important. It can be whatever name you choose -- `Share Credential: github.com/otto8-ai/tools/oauth2/tool.gpt as gitlab-example` causes this tool to use Otto8's OAuth framework. +- `Share Credential: github.com/obot-platform/tools/oauth2/tool.gpt as gitlab-example` causes this tool to use Obot's OAuth framework. - `gitlab-example as integration` ties this tool to the OAuth app we created because it matches the value set for the **integration** field. - `"read_api read_user" as scope` indicates the scopes that will be requested. They need to be the same as or a subset of the scopes granted when creating the OAuth application in GitLab. -- `Type: credential` tells Otto8 that this is a credential tool +- `Type: credential` tells Obot that this is a credential tool Returning to our custom tool, we use this credential tool via this line: + ``` Credential: ./credential ``` + That is a relative path reference to the credential directory where the credential tool is defined. -Once you've finished with all this, the tool must be pushed to a GitHub repository. Again, the original version of this tool is at https://github.com/otto8-ai/gitlab-example-tool. You can use this value directly if you did not choose to fork the repo. +Once you've finished with all this, the tool must be pushed to a GitHub repository. +Again, the original version of this tool is at https://github.com/otto8-ai/gitlab-example-tool. +You can use this value directly if you did not choose to fork the repo. ### Register the tool -Next we need to register the tool in your Otto8 installation. Go to the Tools page and click **Register New Tool**. Then, drop in the github repo where your tool lives. If you're using ours, you would drop in **github.com/otto8-ai/gitlab-example-tool**. After a few moments of processing, you should see a new GitLab section with one "List Projects" tool list at the bottom of the page. The tool is now ready for use. +Next we need to register the tool in your Obot installation. Go to the Tools page and click **Register New Tool**. +Then, drop in the GitHub repo where your tool lives. If you're using ours, you would drop in **github.com/otto8-ai/gitlab-example-tool**. +After a few moments of processing, you should see a new GitLab section with one "List Projects" tool list at the bottom of the page. The tool is now ready for use. ### Use the tool in an agent -Now, we can use the tool in an agent. Create a new agent, click **Add Tool** under the Agent Tools section, find your GitLab tool, and add it. After that, just ask "what are my gitlab projects?" in the chat. You should see the List Projects tool begin to get invoked and then be prompted to authenticate with GitLab. Authenticate with GitLab and you'll see the tool call complete successfully and your projects listed. +Now, we can use the tool in an agent. Create a new agent, click **Add Tool** under the Agent Tools section, find your GitLab tool, and add it. +After that, just ask "what are my gitlab projects?" in the chat. You should see the List Projects tool begin to get invoked and then be prompted to authenticate with GitLab. +Authenticate with GitLab, and you'll see the tool call complete successfully and your projects listed. That concludes our guide. Use this as a jumping off point to create your own integrations. - diff --git a/docs/docs/04-tutorials/01-github-assistant.md b/docs/docs/04-tutorials/01-github-assistant.md index 7332b0d5..08351f30 100644 --- a/docs/docs/04-tutorials/01-github-assistant.md +++ b/docs/docs/04-tutorials/01-github-assistant.md @@ -1,6 +1,6 @@ # Create a Personal GitHub Task Agent -This is a short tutorial demonstrating how to create an Otto8 agent that interacts with GitHub. The agent will help you keep track of the work assigned to you in GitHub. +This is a short tutorial demonstrating how to create an Obot agent that interacts with GitHub. The agent will help you keep track of the work assigned to you in GitHub. :::note As you configure the agent, changes will be saved and applied automatically. @@ -46,7 +46,7 @@ If you gave your agent instructions about a "status update", ask for one and see ## 4. Publishing the agent (optional) -If you're happy with the agent and want other users on your Otto8 instance to be able to use it, +If you're happy with the agent and want other users on your Obot instance to be able to use it, you can click the **Publish** button on the agent configuration page. This will make it available in the user UI for all users to chat with. Each user will have to sign in to GitHub on their own when prompted to do so by the agent. diff --git a/docs/docs/04-tutorials/02-knowledge-assistant.md b/docs/docs/04-tutorials/02-knowledge-assistant.md index 463e3b3d..f1a045fe 100644 --- a/docs/docs/04-tutorials/02-knowledge-assistant.md +++ b/docs/docs/04-tutorials/02-knowledge-assistant.md @@ -1,6 +1,6 @@ # Create an HR Q&A Agent -Otto8 makes it easy to create an agent to answer questions about a set of documents, using its built-in RAG feature. +Obot makes it easy to create an agent to answer questions about a set of documents, using its built-in RAG feature. This tutorial will demonstrate how to do this. :::note @@ -38,6 +38,6 @@ Start by asking it a simple question that can be answered by at least one of the ## 4. Publishing the agent (optional) -If you're happy with the agent and want other users on your Otto8 instance to be able to use it, +If you're happy with the agent and want other users on your Obot instance to be able to use it, you can click the **Publish** button on the agent configuration page. This will make it available in the user UI for all users to chat with. diff --git a/docs/docs/04-tutorials/03-slack-alerts-assistant.md b/docs/docs/04-tutorials/03-slack-alerts-assistant.md index 3b248d5b..772f8a25 100644 --- a/docs/docs/04-tutorials/03-slack-alerts-assistant.md +++ b/docs/docs/04-tutorials/03-slack-alerts-assistant.md @@ -1,6 +1,6 @@ # Create a Slack Alerts Agent -This is a short tutorial demonstrating how to create an Otto8 agent that helps with alerts in a Slack channel. +This is a short tutorial demonstrating how to create an Obot agent that helps with alerts in a Slack channel. :::note As you configure the agent, changes will be saved and applied automatically. @@ -46,7 +46,7 @@ You can also ask it to come up with remediation steps for you. ## 4. Publishing the agent (optional) -If you're happy with the agent and want other users on your Otto8 instance to be able to use it, +If you're happy with the agent and want other users on your Obot instance to be able to use it, you can click the **Publish** button on the agent configuration page. This will make it available in the user UI for all users to chat with. Each user will have to sign in to Slack on their own when prompted to do so by the agent. diff --git a/docs/docs/04-tutorials/04-webhook-workflows.md b/docs/docs/04-tutorials/04-webhook-workflows.md index d410c352..98f7179b 100644 --- a/docs/docs/04-tutorials/04-webhook-workflows.md +++ b/docs/docs/04-tutorials/04-webhook-workflows.md @@ -2,7 +2,10 @@ ## Overview -This guide demonstrates adding an automated AI workflow to an existing Kubernetes - PagerDuty monitoring setup. A webhook event will be added to PagerDuty that triggers automated troubleshooting and remediation in Otto8. The automation is capable of downloading a runbook specified by the alert, searching the knowledge base for workflows, and then executing the diagnostic steps against the cluster. The On-Call engineer will receive this information as notes in the PagerDuty incident. +This guide demonstrates adding an automated AI workflow to an existing Kubernetes - PagerDuty monitoring setup. +A webhook event will be added to PagerDuty that triggers automated troubleshooting and remediation in Obot. +The automation is capable of downloading a runbook specified by the alert, searching the knowledge base for workflows, and then executing the diagnostic steps against the cluster. +The On-Call engineer will receive this information as notes in the PagerDuty incident. ![Workflow Overview](/img/webhook-overview.png) @@ -11,12 +14,12 @@ This guide demonstrates adding an automated AI workflow to an existing Kubernete - A Kubernetes cluster that is configured to send alerts to PagerDuty. - A PagerDuty API Key. - Kubeconfig file from the Kubernetes cluster you would like to interact with. (The workflow users read/write permissions to the cluster ) -- Otto8 CLI installed and configured. See the [CLI installation instructions](/#getting-started) -- Otto8 server will need to be accessible from the internet. +- Obot CLI installed and configured. See the [CLI installation instructions](/#getting-started) +- Obot server will need to be accessible from the internet. -## Setup the workflow +## Set up the workflow -A workflow can be created in the Otto8 Admin UI, or it can be created using the Otto8 CLI. This example has several steps that lend it to be created via the CLI. +A workflow can be created in the Obot Admin UI, or it can be created using the Obot CLI. This example has several steps that lend it to be created via the CLI. First, create a new file called `issue-triage.yaml` and add the following content: @@ -47,10 +50,10 @@ steps: - step: “Get the PAGERDUTY_EMAIL env var. This is the user_email for all interactions with PagerDuty” tools: - sys.getenv - - step: "Get the env value for ${OTTO8_THREAD_ID}." + - step: "Get the env value for ${OBOT_THREAD_ID}." tools: - sys.getenv - - step: "Add a note to the incident that Otto is looking into the issue, and a link to ${OTTO8_SERVER_URL}/admin/thread/${OTTO8_THREAD_ID}" + - step: "Add a note to the incident that Obot is looking into the issue, and a link to ${OBOT_SERVER_URL}/admin/thread/${OBOT_THREAD_ID}" tools: - sys.getenv - step: "Get the incidents alerts" @@ -78,14 +81,14 @@ steps: Save the file and run the following command to create the workflow: ```bash -otto8 create issue-triage.yaml +obot create issue-triage.yaml ``` You will see an ID returned as part of the output, you will need this value in the next steps. ## Authenticate the workflow -Lets prepare our data for the workflow to interact with Kubernetes and PagerDuty. +Let's prepare our data for the workflow to interact with Kubernetes and PagerDuty. ### Prepare the `kubeconfig` file @@ -95,19 +98,19 @@ Your `kubeconfig` file needs to be base64 encoded, with the new lines removed. cat ./kubeconfig | base64 | tr -d '\n' > kubeconfig.base64 ``` -You will also need your PagerDuty API key, and the email address of the user that Otto will use to interact with PagerDuty. +You will also need your PagerDuty API key, and the email address of the user that Obot will use to interact with PagerDuty. ### Run the authentication command ```bash -otto8 workflow auth +obot workflow auth ``` Follow the prompts to authenticate. When asked for the `KUBECONFIG_FILE`, use the file notation `@kubeconfig.base64` to point directly to the file. ## Add Knowledge to the workflow -Visit the workflow in the Otto8 Admin UI. Click on `workflows > issue triage`. +Visit the workflow in the Obot Admin UI. Click on `workflows > issue triage`. Scroll to the bottom of the workflow form. Then click on the `+ Add Knowledge` button. Select `Website` as the source. @@ -123,19 +126,19 @@ This will take you to a form which will list the pages on the website. Select al On PagerDuty side, click integrations > Developer Tools > Generic Webhooks (v3) -Put the URL in it should be \/api/webhooks/default/pd-hook +Put the URL in. It should be `/api/webhooks/default/pd-hook` -Select the Scope type, In the demo setup, I had Scope Type = Service and Scope = Default Service +Select the Scope type. In the demo setup, I had Scope Type = Service and Scope = Default Service -Deselect All events, and select incident.triggered +Deselect all events, and select `incident.triggered` -Click ‘Add Webhook’ button. +Click `Add Webhook` button. -You will get a subscription created pop up, copy the secret so we can verify payloads. +You will get a "subscription created" pop up. Copy the secret so we can verify payloads. -### Create the webhook receiver in Otto8 +### Create the webhook receiver in Obot -Go to the Otto8 Admin UI, click on the `Webhooks` tab, and click `Create Webhook`. +Go to the Obot Admin UI, click on the `Webhooks` tab, and click `Create Webhook`. Name the webhook `pd-hook`, and use the secret you copied from PagerDuty. diff --git a/docs/docs/05-configuration/01-general.md b/docs/docs/05-configuration/01-general.md index f4af1f1f..24cea50a 100644 --- a/docs/docs/05-configuration/01-general.md +++ b/docs/docs/05-configuration/01-general.md @@ -1,10 +1,11 @@ # General -The Otto8 server is configured via environment variables. The following configuration is available: +The Obot server is configured via environment variables. The following configuration is available: #### `OPENAI_API_KEY` -The foundation of Otto8 is a large language model that supports function-calling. The default is OpenAI and specifying an OpenAI key here will ensure none of the users need to worry about specifying their own API key. +The foundation of Obot is a large language model that supports function-calling. +The default is OpenAI and specifying an OpenAI key here will ensure none of the users need to worry about specifying their own API key. :::note @@ -14,12 +15,15 @@ You can configure other [model-providers](02-model-providers.md) besides OpenAI. #### `GITHUB_AUTH_TOKEN` -Otto8 and its underlying tool GPTScript make heavy use of tools hosted on GitHub. Care is taken to cache these tools and only re-check when necessary. However, rate-limiting can happen. Setting a read-only token here can alleviate many of these issues. +Obot and its underlying tool GPTScript make heavy use of tools hosted on GitHub. Care is taken to cache these tools and only re-check when necessary. +However, rate-limiting can happen. Setting a read-only token here can alleviate many of these issues. -#### `OTTO8_SERVER_DSN` +#### `OBOT_SERVER_DSN` -Otto8 uses a database backend. By default, it will use a sqlite3 local database. This environment variable allows you to specify another database option. For example, you can use a postgres database with something like `OTTO8_SERVER_DSN=postgres://user:password@host/database`. +Obot uses a database backend. By default, it will use a sqlite3 local database. +This environment variable allows you to specify another database option. +For example, you can use a postgres database with something like `OBOT_SERVER_DSN=postgres://user:password@host/database`. -#### `OTTO8_SERVER_HOSTNAME` +#### `OBOT_SERVER_HOSTNAME` -Tell Otto8 what its server URL is so that things like OAuth, LLM proxying, and invoke URLs are handled correctly. +Tell Obot what its server URL is so that things like OAuth, LLM proxying, and invoke URLs are handled correctly. diff --git a/docs/docs/05-configuration/02-model-providers.md b/docs/docs/05-configuration/02-model-providers.md index faa2d17d..17e8a94c 100644 --- a/docs/docs/05-configuration/02-model-providers.md +++ b/docs/docs/05-configuration/02-model-providers.md @@ -1,6 +1,10 @@ # Model Providers -Each packaged model provider has a slightly different configuration. Below is a summary of the configuration options for each provider. However, the packaged model providers indicate which configuration parameters they require, and which ones aren't set in the current environment. For example, `/api/model-providers/azure-openai-model-provider` would indicate the status of the Azure OpenAI model provider. If this model provider hasn't been configured, then the API would return something like: +Each packaged model provider has a slightly different configuration. +Below is a summary of the configuration options for each provider. +However, the packaged model providers indicate which configuration parameters they require, and which ones aren't set in the current environment. +For example, `/api/model-providers/azure-openai-model-provider` would indicate the status of the Azure OpenAI model provider. +If this model provider hasn't been configured, then the API would return something like: ```json { @@ -9,23 +13,23 @@ Each packaged model provider has a slightly different configuration. Below is a "revision": "1033", "type": "modelprovider", "name": "azure-openai-model-provider", - "toolReference": "github.com/otto8-ai/tools/azure-openai-model-provider", + "toolReference": "github.com/obot-platform/tools/azure-openai-model-provider", "configured": false, "requiredConfigurationParameters": [ - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_ENDPOINT", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_ID", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_SECRET", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_TENANT_ID", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_SUBSCRIPTION_ID", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_RESOURCE_GROUP" + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_ENDPOINT", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_ID", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_SECRET", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_TENANT_ID", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_SUBSCRIPTION_ID", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_RESOURCE_GROUP" ], "missingConfigurationParameters": [ - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_ENDPOINT", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_ID", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_SECRET", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_TENANT_ID", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_SUBSCRIPTION_ID", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_RESOURCE_GROUP" + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_ENDPOINT", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_ID", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_SECRET", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_TENANT_ID", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_SUBSCRIPTION_ID", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_RESOURCE_GROUP" ] } @@ -34,12 +38,12 @@ Each packaged model provider has a slightly different configuration. Below is a To configure a model provider using the API, a `POST` request can be made to `/api/model-providers/azure-openai-model-provider/configure` with each required configuration parameter set in the body: ```json { - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_ENDPOINT": "...", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_ID": "...", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_SECRET": "...", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_TENANT_ID": "...", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_SUBSCRIPTION_ID": "...", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_RESOURCE_GROUP": "..." + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_ENDPOINT": "...", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_ID": "...", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_SECRET": "...", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_TENANT_ID": "...", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_SUBSCRIPTION_ID": "...", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_RESOURCE_GROUP": "..." } ``` @@ -52,15 +56,15 @@ Once the model provider has been configured, then the API would return something "revision": "1033", "type": "modelprovider", "name": "azure-openai-model-provider", - "toolReference": "github.com/otto8-ai/tools/azure-openai-model-provider", + "toolReference": "github.com/obot-platform/tools/azure-openai-model-provider", "configured": true, "requiredConfigurationParameters": [ - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_ENDPOINT", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_ID", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_SECRET", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_TENANT_ID", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_SUBSCRIPTION_ID", - "OTTO8_AZURE_OPENAI_MODEL_PROVIDER_RESOURCE_GROUP" + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_ENDPOINT", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_ID", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_SECRET", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_TENANT_ID", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_SUBSCRIPTION_ID", + "OBOT_AZURE_OPENAI_MODEL_PROVIDER_RESOURCE_GROUP" ] } ``` @@ -69,37 +73,37 @@ The UI also uses this API to indicate the status of the model provider. ## OpenAI -The OpenAI model provider is the default and has one required configuration parameter: `OTTO8_OPENAI_MODEL_PROVIDER_API_KEY`. +The OpenAI model provider is the default and has one required configuration parameter: `OBOT_OPENAI_MODEL_PROVIDER_API_KEY`. -The OpenAI model provider is also special: you can start Otto8 with the `OPENAI_API_KEY` environment variable set and Otto8 will automatically configure the OpenAI model provider. +The OpenAI model provider is also special: you can start Obot with the `OPENAI_API_KEY` environment variable set and Obot will automatically configure the OpenAI model provider. ## Azure OpenAI The Azure OpenAI model provider requires the following configuration parameters: -- `OTTO8_AZURE_OPENAI_MODEL_PROVIDER_ENDPOINT`: The endpoint to use, found by clicking on the "Deployment" name from the "Deployments" page of the Azure OpenAI Studio. The provider endpoint must be in the format `https://.openai.azure.com` - if your Azure OpenAI resource doesn't have an endpoint that looks like this, you need to create one. -- `OTTO8_AZURE_OPENAI_MODEL_PROVIDER_RESOURCE_GROUP`: The resource group name for the Azure OpenAI resource, found by clicking on the resource name in the top-right of the Azure OpenAI Studio. +- `OBOT_AZURE_OPENAI_MODEL_PROVIDER_ENDPOINT`: The endpoint to use, found by clicking on the "Deployment" name from the "Deployments" page of the Azure OpenAI Studio. The provider endpoint must be in the format `https://.openai.azure.com` - if your Azure OpenAI resource doesn't have an endpoint that looks like this, you need to create one. +- `OBOT_AZURE_OPENAI_MODEL_PROVIDER_RESOURCE_GROUP`: The resource group name for the Azure OpenAI resource, found by clicking on the resource name in the top-right of the Azure OpenAI Studio. -A service principal must be created with the (equivalent permissions of the) `Cognitive Services OpenAI User`. After this service principal is created, use the following parameters to configure the model provider in Otto8: -- `OTTO8_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_ID`: The client ID for the app registration. -- `OTTO8_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_SECRET`: The client secret for the app registration. -- `OTTO8_AZURE_OPENAI_MODEL_PROVIDER_TENANT_ID`: The tenant ID for the app registration. -- `OTTO8_AZURE_OPENAI_MODEL_PROVIDER_SUBSCRIPTION_ID`: The subscription ID for the Azure account. -- `OTTO8_AZURE_OPENAI_MODEL_PROVIDER_API_VERSION`: (optional) Specify the API version to use with Azure OpenAI instead of `2024-10-21`. +A service principal must be created with the (equivalent permissions of the) `Cognitive Services OpenAI User`. After this service principal is created, use the following parameters to configure the model provider in Obot: +- `OBOT_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_ID`: The client ID for the app registration. +- `OBOT_AZURE_OPENAI_MODEL_PROVIDER_CLIENT_SECRET`: The client secret for the app registration. +- `OBOT_AZURE_OPENAI_MODEL_PROVIDER_TENANT_ID`: The tenant ID for the app registration. +- `OBOT_AZURE_OPENAI_MODEL_PROVIDER_SUBSCRIPTION_ID`: The subscription ID for the Azure account. +- `OBOT_AZURE_OPENAI_MODEL_PROVIDER_API_VERSION`: (optional) Specify the API version to use with Azure OpenAI instead of `2024-10-21`. :::note -When configuring models with the Azure OpenAI provider in Otto8, the "Target Model" should be the "Deployment" from Azure. +When configuring models with the Azure OpenAI provider in Obot, the "Target Model" should be the "Deployment" from Azure. ::: ## Anthropic -The Anthropic model provider requires one configuration parameter: `OTTO8_ANTHROPIC_MODEL_PROVIDER_API_KEY`. You can get an API key for your Anthropic account [here](https://console.anthropic.com/settings/keys). +The Anthropic model provider requires one configuration parameter: `OBOT_ANTHROPIC_MODEL_PROVIDER_API_KEY`. You can get an API key for your Anthropic account [here](https://console.anthropic.com/settings/keys). ## Voyage AI -Voyage is Anthropic's recommended text-embedding provider. The Voyage model provider requires `OTTO8_VOYAGE_MODEL_PROVIDER_API_KEY`. You can get an API key for your Voyage account [here](https://dash.voyageai.com/api-keys). +Voyage is Anthropic's recommended text-embedding provider. The Voyage model provider requires `OBOT_VOYAGE_MODEL_PROVIDER_API_KEY`. You can get an API key for your Voyage account [here](https://dash.voyageai.com/api-keys). ## Ollama -The Ollama model provider requires the configuration parameter `OTTO8_OLLAMA_MODEL_PROVIDER_HOST`. This host must point to a running instance of Ollama. For your reference, the default host and port for Ollama is `127.0.0.1:11434`. Otto8 doesn't set this by default. +The Ollama model provider requires the configuration parameter `OBOT_OLLAMA_MODEL_PROVIDER_HOST`. This host must point to a running instance of Ollama. For your reference, the default host and port for Ollama is `127.0.0.1:11434`. Obot doesn't set this by default. To set up and run an instance of Ollama, refer to the [Ollama GitHub readme](https://github.com/ollama/ollama/blob/main/README.md). diff --git a/docs/docs/05-configuration/03-auth-providers.md b/docs/docs/05-configuration/03-auth-providers.md index 14208ff0..fc827371 100644 --- a/docs/docs/05-configuration/03-auth-providers.md +++ b/docs/docs/05-configuration/03-auth-providers.md @@ -1,19 +1,21 @@ # Auth Providers -Authentication providers allow your Otto8 installation to authenticate users with the identity provider of your choice. All authentication providers are configured using environment variables. +Authentication providers allow your Obot installation to authenticate users with the identity provider of your choice. All authentication providers are configured using environment variables. ## Common Environment Variables -The following environment variables are required for all authentication providers. Setting the Client ID and Client Secret will mean that the authentication provider is enabled. The remaining configuration will be validated on startup. +The following environment variables are required for all authentication providers. +Setting the Client ID and Client Secret will mean that the authentication provider is enabled. +The remaining configuration will be validated on startup. -- `OTTO8_AUTH_CLIENT_ID`: The client ID of the authentication provider. -- `OTTO8_AUTH_CLIENT_SECRET`: The client secret of the authentication provider. -- `OTTO8_AUTH_COOKIE_SECRET`: The secret used to encrypt the authentication cookie. Must be of size 16, 24, or 32 bytes. -- `OTTO8_AUTH_ADMIN_EMAILS`: A comma-separated list of the email addresses of the admin users. +- `OBOT_AUTH_CLIENT_ID`: The client ID of the authentication provider. +- `OBOT_AUTH_CLIENT_SECRET`: The client secret of the authentication provider. +- `OBOT_AUTH_COOKIE_SECRET`: The secret used to encrypt the authentication cookie. Must be of size 16, 24, or 32 bytes. +- `OBOT_AUTH_ADMIN_EMAILS`: A comma-separated list of the email addresses of the admin users. The following environment variables are optional for all authentication providers: -- `OTTO8_AUTH_EMAIL_DOMAINS`: A comma-separated list of email domains allowed for authentication. Ignored if not set. -- `OTTO8_AUTH_CONFIG_TYPE`: The type of the authentication provider. For example, `google` or `github`. Defaults to `google`. +- `OBOT_AUTH_EMAIL_DOMAINS`: A comma-separated list of email domains allowed for authentication. Ignored if not set. +- `OBOT_AUTH_CONFIG_TYPE`: The type of the authentication provider. For example, `google` or `github`. Defaults to `google`. ## Google @@ -23,8 +25,8 @@ Google is the default authentication provider. There are currently no additional GitHub authentication has the following optional configuration: -- `OTTO8_AUTH_GITHUB_ORG`: The name of the organization allowed for authentication. Ignored if not set. -- `OTTO8_AUTH_GITHUB_TEAM`: The name of the team allowed for authentication. Ignored if not set. -- `OTTO8_AUTH_GITHUB_REPO`: Restrict logins to collaborators of this repository formatted as `orgname/repo`. Ignored if not set. -- `OTTO8_AUTH_GITHUB_TOKEN`: The token to use when verifying repository collaborators (must have push access to the repository). -- `OTTO8_AUTH_GITHUB_ALLOW_USERS`: A comma-separated list of users allowed to login even if they don't belong to the organization or team. \ No newline at end of file +- `OBOT_AUTH_GITHUB_ORG`: The name of the organization allowed for authentication. Ignored if not set. +- `OBOT_AUTH_GITHUB_TEAM`: The name of the team allowed for authentication. Ignored if not set. +- `OBOT_AUTH_GITHUB_REPO`: Restrict logins to collaborators of this repository formatted as `orgname/repo`. Ignored if not set. +- `OBOT_AUTH_GITHUB_TOKEN`: The token to use when verifying repository collaborators (must have push access to the repository). +- `OBOT_AUTH_GITHUB_ALLOW_USERS`: A comma-separated list of users allowed to log in even if they don't belong to the organization or team. \ No newline at end of file diff --git a/docs/docs/05-configuration/04-workspace-provider.md b/docs/docs/05-configuration/04-workspace-provider.md index 67482740..9cf445ec 100644 --- a/docs/docs/05-configuration/04-workspace-provider.md +++ b/docs/docs/05-configuration/04-workspace-provider.md @@ -1,10 +1,12 @@ # Workspace Provider -In Otto8, a workspace is where files are stored and manipulated by a user. By default, any workspace is a directory on local disk. However, is some server-based applications, this is not acceptable. The concept of a workspace provider is used to abstract away the concept of a workspace and use other options. +In Obot, a workspace is where files are stored and manipulated by a user. By default, any workspace is a directory on local disk. +However, in some server-based applications, this is not acceptable. +The concept of a workspace provider is used to abstract away the concept of a workspace and use other options. This section describes the configuration of the workspace provider. -#### `OTTO8_WORKSPACE_PROVIDER_TYPE` +#### `OBOT_WORKSPACE_PROVIDER_TYPE` The type of provider to use. The current options are `directory` or `s3`. Note that the `s3` provider is compatible with s3-compatible services like CloudFlare R2. @@ -12,13 +14,14 @@ The type of provider to use. The current options are `directory` or `s3`. Note t #### `WORKSPACE_PROVIDER_DATA_HOME` -Specify the directory where workspaces are nested. The default is `$XDG_CONFIG_HOME/otto8/workspace-provider`. +Specify the directory where workspaces are nested. The default is `$XDG_CONFIG_HOME/obot/workspace-provider`. ### The s3 provider configuration #### `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`, `WORKSPACE_PROVIDER_S3_BUCKET` -Specifying these variables allows you to configure access to an s3 or s3-compatible bucket for the workspace provider to use. If the `OTTO8_WORKSPACE_PROVIDER_TYPE` is `s3`, then all of these variables are required for proper configuration. +Specifying these variables allows you to configure access to an s3 or s3-compatible bucket for the workspace provider to use. +If the `OBOT_WORKSPACE_PROVIDER_TYPE` is `s3`, then all of these variables are required for proper configuration. #### `WORKSPACE_PROVIDER_S3_BASE_ENDPOINT` diff --git a/docs/docusaurus.config.ts b/docs/docusaurus.config.ts index 224f977c..0255d0c4 100644 --- a/docs/docusaurus.config.ts +++ b/docs/docusaurus.config.ts @@ -5,13 +5,13 @@ import type * as Preset from '@docusaurus/preset-classic'; // This runs in Node.js - Don't use client-side code here (browser APIs, JSX...) const config: Config = { - title: 'Otto8 Docs', + title: 'Obot Docs', tagline: '', favicon: 'img/favicon.ico', - url: 'https://docs.otto8.ai', + url: 'https://docs.obot.ai', baseUrl: '/', - organizationName: 'otto8-ai', - projectName: 'otto8', + organizationName: 'obot-platform', + projectName: 'obot', onBrokenLinks: 'throw', onBrokenMarkdownLinks: 'warn', @@ -26,7 +26,7 @@ const config: Config = { { docs: { sidebarPath: './sidebars.ts', - editUrl: 'https://github.com/otto8-ai/otto8/tree/main/docs', + editUrl: 'https://github.com/obot-platform/obot/tree/main/docs', routeBasePath: "/", // Serve the docs at the site's root }, theme: { @@ -43,16 +43,16 @@ const config: Config = { themeConfig: { // Replace with your project's social card - image: 'img/otto8-logo-blue-black-text.svg', + image: 'img/obot-logo-blue-black-text.svg', navbar: { logo: { - alt: 'Otto8 Logo', - src: 'img/otto8-logo-blue-black-text.svg', - srcDark: 'img/otto8-logo-blue-white-text.svg', + alt: 'Obot Logo', + src: 'img/obot-logo-blue-black-text.svg', + srcDark: 'img/obot-logo-blue-white-text.svg', }, items: [ { - href: "https://github.com/otto8-ai/otto8", + href: "https://github.com/obot-platform/obot", label: "GitHub", position: "right", }, @@ -68,7 +68,7 @@ const config: Config = { links: [ { label: "GitHub", - to: "https://github.com/otto8-ai/otto8", + to: "https://github.com/obot-platform/obot", }, { label: "Discord", diff --git a/docs/snippets/go-hash-tool-readme.md.mdx b/docs/snippets/go-hash-tool-readme.md.mdx index 3bf628a0..f942db8a 100644 --- a/docs/snippets/go-hash-tool-readme.md.mdx +++ b/docs/snippets/go-hash-tool-readme.md.mdx @@ -1,20 +1,20 @@ ## Writing your first tool in Go {#writing-your-first-tool-in-go-eb5bb8c4} -[go-hash-tool](https://github.com/otto8-ai/go-hash-tool) contains a reference `Go` implementation of the `Hash` Tool. +[go-hash-tool](https://github.com/obot-platform/go-hash-tool) contains a reference `Go` implementation of the `Hash` tool. -This guide walks through the structure and design of the Tool and outlines the packaging requirements for [Otto8](https://docs.otto8.ai/concepts/agents) +This guide walks through the structure and design of the tool and outlines the packaging requirements for [Obot](https://docs.obot.ai/concepts/agents) To clone this repo and follow along, run the following command: ```bash -git clone git@github.com:otto8-ai/go-hash-tool +git clone git@github.com:obot-platform/go-hash-tool ```
## Tool Repo Structure {#tool-repo-structure-eb5bb8c4} -The directory tree below highlights the files required to implement `Hash` in Go and package it for `Otto8`. +The directory tree below highlights the files required to implement `Hash` in Go and package it for Obot. ``` go-hash-tool @@ -25,21 +25,21 @@ go-hash-tool └── hash.go ``` -> **Note:** Most Tools implemented in Go will also have a `go.sum` file that is also required when present. +> **Note:** Most tools implemented in Go will also have a `go.sum`, which is required if the tool has dependencies. > It is not present in the reference implementation because it has no external dependencies and relies solely on the Go standard library.
## Defining the `Hash` Tool {#defining-the-hash-tool-eb5bb8c4} -The `tool.gpt` file contains [GPTScript Tool Definitions](https://docs.gptscript.ai/tools/gpt-file-reference) which describe a set of Tools that can be used by Agents in `Otto8`. -Every Tool repository must have a `tool.gpt` file in its root directory. +The `tool.gpt` file contains [GPTScript Tool Definitions](https://docs.gptscript.ai/tools/gpt-file-reference) which describe a set of tools that can be used by agents in Obot. +Every tool repository must have a `tool.gpt` file in its root directory. -The Tools defined in this file must have a descriptive `Name` and `Description` that will help Agents understand what the Tool does, what it returns (if anything), and all the `Parameters` it takes. -Agents use these details to infer a Tool's usage. -We call the section of a Tool definition that contains this info a `Preamble`. +The tools defined in this file must have a `Name` and `Description` that will help agents understand what the tool does, what it returns (if anything), and all the `Parameters` it takes. +Agents use these details to infer a tool's usage. +We call the section of a tool definition that contains this info a `Preamble`. -We want the `Hash` Tool to return the hash of some given `data`. It would also be nice to support a few different algorithms for the Agent to choose from. +We want the `Hash` tool to return the hash of some given `data`. It would also be nice to support a few different algorithms for the agent to choose from. Let's take a look at the `Preamble` for `Hash` to see how that's achieved: ```yaml @@ -51,14 +51,14 @@ Param: algo: The algorithm to generate a hash with. Supports "sha256" and "md5". Breaking this down a bit: -- The `Preamble` above declares a Tool named `Hash`. -- The `Param` fields enumerate the arguments that an Agent must provide when calling `Hash`, `data` and `algo`. +- The `Preamble` above declares a tool named `Hash`. +- The `Param` fields enumerate the arguments that an agent must provide when calling `Hash`, `data` and `algo`. - In this case, the description of the `algo` parameter outlines the valid options (`sha256` or `md5`) and defines a default value (`sha256`) - The `Description` explains what `Hash` returns with respect to the given arguments; the hash of `data` using the algorithm selected with `algo`.
-Immediately below the `Preamble` is the `Tool Body`, which tells `Otto8` how to execute the Tool: +Immediately below the `Preamble` is the `Tool Body`, which tells Obot how to execute the tool: ```bash #!{GPTSCRIPT_TOOL_DIR}/bin/gptscript-go-tool hash @@ -66,17 +66,17 @@ Immediately below the `Preamble` is the `Tool Body`, which tells `Otto8` how to This is where the magic happens. -To oversimplify, when an Agent calls the `Hash` Tool, `Otto8` reads this line and then: +To simplify, when an agent calls the `Hash` tool, Obot reads this line and then: -1. Downloads the appropriate `Go` tool chain -2. Sets up a working directory for the Tool +1. Downloads the appropriate `Go` toolchain +2. Sets up a working directory for the tool 3. Runs `go build` to install dependencies (from `go.mod` and `go.sum`) and build a binary named `gptscript-go-tool` (`gptscript-go-tool.exe` on Windows) 4. Projects the call arguments onto environment variables (`DATA` and `ALGO`) -5. Runs `gptscript-go-tool hash`. +5. Runs `gptscript-go-tool hash`
-Putting it all together, here's the complete definition of the `Hash` Tool: +Putting it all together, here's the complete definition of the `Hash` tool: ```yaml Name: Hash @@ -91,14 +91,14 @@ Param: algo: The algorithm to generate a hash with. Default is "sha256". Support ## Tool Metadata {#tool-metadata-eb5bb8c4} -The `tool.gpt` file also provides the following metadata for use in `Otto8`: +The `tool.gpt` file also provides the following metadata for use in Obot: -- `!metadata:*:category` which tags Tools with the `Crypto` category to promote organization and discovery -- `!metadata:*:icon` which assigns `https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/fingerprint-duotone.svg` as the Tool icon +- `!metadata:*:category` which tags tools with the `Crypto` category to promote organization and discovery +- `!metadata:*:icon` which assigns `https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/fingerprint-duotone.svg` as the tool icon
-> **Note:** `*` is a wild card pattern that applies the metadata to all Tools in the `tool.gpt` file. +> **Note:** `*` is a wildcard pattern that applies the metadata to all tools in the `tool.gpt` file. ```yaml --- @@ -112,7 +112,7 @@ https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/fingerprint-d
- Note: Metadata can be applied to a specific Tool by either specifying the exact name (e.g. !metadata:Hash:category) or by adding the metadata directly to a Tool's Preamble + Note: Metadata can be applied to a specific tool by either specifying the exact name (e.g. !metadata:Hash:category) or by adding the metadata directly to a tool's Preamble ```yaml @@ -152,9 +152,9 @@ https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/fingerprint-d ## Implementing Business Logic {#implementing-business-logic-eb5bb8c4} -The `main.go` file is the entry point of the `gptscript-go-tool` binary that is executed by `Otto8` when the `Hash` Tool is called. +The `main.go` file is the entry point of the `gptscript-go-tool` binary that is executed by Obot when the `Hash` tool is called. -Let's walk through the the code to understand what happens at runtime: +Let's walk through the code to understand what happens at runtime: ```go // ... @@ -175,9 +175,9 @@ if res != "" { } ``` -This code implements a simple CLI responsible for dispatching the `commands.Hash` function on request -- when `hash` is passed in as an argument -- after extracting the Tool arguments, `data` and `algo`, from the respective environment variables. +This code implements a simple CLI responsible for dispatching the `commands.Hash` function on request -- when `hash` is passed in as an argument -- after extracting the tool arguments, `data` and `algo`, from the respective environment variables. -It also ensures that the return value and errors of the call to `commands.Hash` are written to stdout. This is crucial because only stdout is returned to the Agent, while stderr is discarded. +It also ensures that the return value and errors of the call to `commands.Hash` are written to stdout. This is crucial because only stdout is returned to the agent, while stderr is discarded.
@@ -186,7 +186,7 @@ It also ensures that the return value and errors of the call to `commands.Hash`
-For example, to add business logic for a new Tool to verify a hash, we just have to tack on `verify` case: +For example, to add business logic for a new tool to verify a hash, we just have to tack on `verify` case: ```go // ... @@ -198,7 +198,7 @@ default: //... ``` -The Body of the `Verify` Tool definition would then simply pass `verify` to `gptscript-go-tool` instead of `hash`: +The Body of the `Verify` tool definition would then simply pass `verify` to `gptscript-go-tool` instead of `hash`: ```yaml Name: Verify @@ -211,7 +211,7 @@ Name: Verify
-The `commands.Hash` function implements the bulk of the `Hash` Tool's business logic. +The `commands.Hash` function implements the bulk of the `Hash` tool's business logic. It starts off by validating the `data` and `algo` arguments. @@ -234,12 +234,12 @@ func Hash(data, algo string) (string, error) { ``` When an argument is invalid, the function returns an error that describes the validation issue in detail. -The goal is to provide useful information that an Agent can use to construct valid arguments for future calls. +The goal is to provide useful information that an agent can use to construct valid arguments for future calls. For example, when an invalid `algo` argument is provided, the code returns an error that contains the complete list of valid algorithms.
-Once it determines that all of the arguments are valid, it then calculates the hash and writes a JSON object to stdout. +Once it determines that all the arguments are valid, it calculates the hash and writes a JSON object to stdout. This object contains both the hash and the algorithm used to generate it. ```go @@ -257,7 +257,7 @@ This object contains both the hash and the algorithm used to generate it. ``` > **Note:** Producing structured data with extra contextual info (e.g. the algorithm) is considered good form. -> It's a pattern that improves the Agent's ability to correctly use the Tool's result over time. +> It's a pattern that improves the agent's ability to correctly use the tool's result over time.
Complete main.go and hash.go @@ -270,7 +270,7 @@ import ( "fmt" "os" - "github.com/otto8-ai/go-hash-tool/commands" + "github.com/obot-platform/go-hash-tool/commands" ) func main() { @@ -373,7 +373,7 @@ func keys[V any](m map[string]V) []string { ## Testing `main.go` Locally {#testing-main-go-locally-eb5bb8c4} -Before adding a Tool to `Otto8`, verify that the Go business logic works on your machine. +Before adding a tool to Obot, verify that the Go business logic works on your machine. To do this, run through the following steps in the root of your local fork: @@ -383,10 +383,10 @@ To do this, run through the following steps in the root of your local fork: make build ``` -2. Run the Tool with some test arguments: +2. Run the tool with some test arguments: | **Command** | **Output** | - | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | + | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `DATA='foo' bin/gptscript-go-tool hash` | `{ "algo": "sha256", "hash": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae" }` | | `DATA='' bin/gptscript-go-tool hash` | `Error: A data argument must be provided` | | `DATA='foo' ALGO='md5' bin/gptscript-go-tool hash` | `{ "algo": "md5", "hash": "acbd18db4cc2f85cedef654fccc4a4d8" }` | @@ -394,14 +394,14 @@ To do this, run through the following steps in the root of your local fork:
-## Adding The `Hash` Tool to `Otto8` {#adding-the-hash-tool-to-otto8-eb5bb8c4} +## Adding the `Hash` tool to Obot {#adding-the-hash-tool-to-obot-eb5bb8c4} -Before a Tool can be used by an Agent, an admin must first add the Tool to `Otto8` by performing the steps below: +Before a tool can be used by an agent, an admin must first add the tool to Obot by performing the steps below: 1.
- Navigate to the Otto8 admin UI in a browser and open the Tools page by clicking the Tools button in the left drawer + Navigate to the Obot admin UI in a browser and open the Tools page by clicking the Tools button in the left drawer
- Open The Tools Page
@@ -409,15 +409,15 @@ Before a Tool can be used by an Agent, an admin must first add the Tool to `Otto 2.
Click the Register New Tool button on the right
- Click The Register New Tool Button
3.
- Type the Tool repo reference into the modal's input box and click Register Tool + Type the tool repo reference into the modal's input box and click Register Tool
- Enter Tool Repo Reference
@@ -427,35 +427,35 @@ Before a Tool can be used by an Agent, an admin must first add the Tool to `Otto
Once the tool has been added, you can search for it by category or name on the Tools page to verify
- Search For Newly Added Tools
-## Using The `Hash` Tool in an Agent {#using-the-hash-tool-in-an-agent-eb5bb8c4} +## Using The `Hash` tool in an agent {#using-the-hash-tool-in-an-agent-eb5bb8c4} -To use the `Hash` Tool in an Agent, open the Agent's Edit page, then: +To use the `Hash` tool in an agent, open the agent's Edit page, then: 1.
Click the Add Tool button under either the Agent Tools or User Tools sections
- Click The Add Tool Button
2.
- Search for "Hash" or "Crypto" in the Tool search pop-out and select the Hash Tool + Search for "Hash" or "Crypto" in the tool search pop-out and select the Hash tool
- Add Hash Tool To Agent
3.
- Ask the Agent to generate a hash + Ask the agent to generate a hash
- Ask The Agent To Generate a Hash
diff --git a/docs/snippets/node-hash-tool-readme.md.mdx b/docs/snippets/node-hash-tool-readme.md.mdx index ae3fecf6..b01ac1ee 100644 --- a/docs/snippets/node-hash-tool-readme.md.mdx +++ b/docs/snippets/node-hash-tool-readme.md.mdx @@ -1,19 +1,19 @@ ## Writing your first tool in Node.js (with Typescript) {#writing-your-first-tool-in-node-js-with-typescript-aeed7f15} -[node-hash-tool](https://github.com/otto8-ai/node-hash-tool) contains a reference Typescript `Node.js` implementation of the `Hash` Tool. +[node-hash-tool](https://github.com/obot-platform/node-hash-tool) contains a reference TypeScript Node.js implementation of the `Hash` tool. -This guide walks through the structure and design of the Tool and outlines the packaging requirements for [Otto8](https://docs.otto8.ai/concepts/agents) +This guide walks through the structure and design of the tool and outlines the packaging requirements for [Obot](https://docs.obot.ai/concepts/agents) To clone this repo and follow along, run the following command: ```bash -git clone git@github.com:otto8-ai/node-hash-tool +git clone git@github.com:obot-platform/node-hash-tool ```
## Tool Repo Structure {#tool-repo-structure-aeed7f15} -The directory tree below highlights the files required to implement `Hash` in Typescript and package it for `Otto8`. +The directory tree below highlights the files required to implement `Hash` in TypeScript and package it for Obot. ``` node-hash-tool @@ -26,21 +26,21 @@ node-hash-tool    └── tools.ts ``` -> **Note:** The `tsconfig.json` file is only required for tools written in Typescript. +> **Note:** The `tsconfig.json` file is only required for tools written in TypeScript. > It is not necessary for tools written in JavaScript.
-## Defining the `Hash` Tool {#defining-the-hash-tool-aeed7f15} +## Defining the `Hash` tool {#defining-the-hash-tool-aeed7f15} -The `tool.gpt` file contains [GPTScript Tool Definitions](https://docs.gptscript.ai/tools/gpt-file-reference) which describe a set of Tools that can be used by Agents in `Otto8`. +The `tool.gpt` file contains [GPTScript Tool Definitions](https://docs.gptscript.ai/tools/gpt-file-reference) which describe a set of tools that can be used by agents in Obot. Every Tool repository must have a `tool.gpt` file in its root directory. -The Tools defined in this file must have a descriptive `Name` and `Description` that will help Agents understand what the Tool does, what it returns (if anything), and all the `Parameters` it takes. -Agents use these details to infer a Tool's usage. -We call the section of a Tool definition that contains this info a `Preamble`. +The tools defined in this file must have a `Name` and `Description` that will help agents understand what the tool does, what it returns (if anything), and all the `Parameters` it takes. +Agents use these details to infer a tool's usage. +We call the section of a tool definition that contains this info a `Preamble`. -We want the `Hash` Tool to return the hash of some given `data`. It would also be nice to support a few different algorithms for the Agent to choose from. +We want the `Hash` tool to return the hash of some given `data`. It would also be nice to support a few different algorithms for the agent to choose from. Let's take a look at the `Preamble` for `Hash` to see how that's achieved: ```yaml @@ -52,14 +52,14 @@ Param: algo: The algorithm to generate a hash with. Supports "sha256" and "md5". Breaking this down a bit: -- The `Preamble` above declares a Tool named `Hash`. -- The `Param` fields enumerate the arguments that an Agent must provide when calling `Hash`, `data` and `algo`. +- The `Preamble` above declares a tool named `Hash`. +- The `Param` fields enumerate the arguments that an agent must provide when calling `Hash`, `data` and `algo`. - In this case, the description of the `algo` parameter outlines the valid options (`sha256` or `md5`) and defines a default value (`sha256`) - The `Description` explains what `Hash` returns with respect to the given arguments; the hash of `data` using the algorithm selected with `algo`.
-Immediately below the `Preamble` is the `Tool Body`, which tells `Otto8` how to execute the Tool: +Immediately below the `Preamble` is the `Tool Body`, which tells Obot how to execute the tool: ```bash #!/usr/bin/env npm --silent --prefix ${GPTSCRIPT_TOOL_DIR} run tool -- hash @@ -67,17 +67,17 @@ Immediately below the `Preamble` is the `Tool Body`, which tells `Otto8` how to This is where the magic happens. -To oversimplify, when an Agent calls the `Hash` Tool, `Otto8` reads this line and then: +To simplify, when an Agent calls the `Hash` tool, Obot reads this line and then: -1. Downloads the appropriate `Node.js` tool chain (`node` and `npm`) -2. Sets up a working directory for the Tool -3. Installs the dependencies from the Tool's `package.json` and `package-lock.json` +1. Downloads the appropriate `Node.js` toolchain (`node` and `npm`) +2. Sets up a working directory for the tool +3. Installs the dependencies from the tool's `package.json` and `package-lock.json` 4. Projects the call arguments onto environment variables (`DATA` and `ALGO`) -5. Runs `npm --silent --prefix ${GPTSCRIPT_TOOL_DIR} run tool -- hash`. +5. Runs `npm --silent --prefix ${GPTSCRIPT_TOOL_DIR} run tool -- hash`
-Putting it all together, here's the complete definition of the `Hash` Tool. +Putting it all together, here's the complete definition of the `Hash` tool. ```yaml Name: Hash @@ -92,14 +92,14 @@ Param: algo: The algorithm to generate a hash with. Default is "sha256". Support ## Tool Metadata {#tool-metadata-aeed7f15} -The `tool.gpt` file also provides the following metadata for use in `Otto8`: +The `tool.gpt` file also provides the following metadata for use in Obot: -- `!metadata:*:category` which tags Tools with the `Crypto` category to promote organization and discovery -- `!metadata:*:icon` which assigns `https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/fingerprint-duotone.svg` as the Tool icon +- `!metadata:*:category` which tags tools with the `Crypto` category to promote organization and discovery +- `!metadata:*:icon` which assigns `https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/fingerprint-duotone.svg` as the tool icon
-> **Note:** `*` is a wild card pattern that applies the metadata to all Tools in the `tool.gpt` file. +> **Note:** `*` is a wildcard pattern that applies the metadata to all tools in the `tool.gpt` file. ```yaml --- @@ -113,7 +113,7 @@ https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/fingerprint-d
- Note: Metadata can be applied to a specific Tool by either specifying the exact name (e.g. !metadata:Hash:category) or by adding the metadata directly to a Tool's Preamble + Note: Metadata can be applied to a specific tool by either specifying the exact name (e.g. !metadata:Hash:category) or by adding the metadata directly to a tool's Preamble ```yaml @@ -173,9 +173,9 @@ This means that when the `Tool Body` is executed, the effective command that run node --no-warnings --loader ts-node/esm src/tools.ts hash ``` -> **Note:** The `--loader ts-node/esm` option, in conjunction with the contents of `tsconfig.json`, is the "special sauce" that lets us run Typescript code directly without transpiling it to JavaScript first. +> **Note:** The `--loader ts-node/esm` option, in conjunction with the contents of `tsconfig.json`, is the "special sauce" that lets us run TypeScript code directly without transpiling it to JavaScript first. -To summarize, when the `Hash` Tool is called by an Agent, `src/tools.ts` gets run with `hash` as an argument. +To summarize, when the `Hash` tool is called by an agent, `src/tools.ts` gets run with `hash` as an argument. Let's walk through the `src/tools.ts` to understand what happens at runtime: @@ -199,7 +199,8 @@ try { } ``` -This code implements a simple CLI that wraps business logic in a try/catch block and forwards any exceptions to stdout. Writing errors to stdout instead of stderr is crucial because only stdout is returned to the Agent, while sdterr is discarded. +This code implements a simple CLI that wraps business logic in a try/catch block and forwards any exceptions to stdout. +Writing errors to stdout instead of stderr is crucial because only stdout is returned to the agent, while stderr is discarded.
@@ -208,7 +209,7 @@ This code implements a simple CLI that wraps business logic in a try/catch block
-For example, if we wanted to add a new Tool to verify a given hash, we'd add a `verify` case: +For example, if we wanted to add a new tool to verify a given hash, we'd add a `verify` case: ```typescript switch (cmd) { @@ -222,7 +223,7 @@ switch (cmd) { } ``` -And the Body of the `Verify` Tool would pass `verify` to the `tool` script instead of `hash`: +And the body of the `Verify` tool would pass `verify` to the `tool` script instead of `hash`: ```yaml Name: Verify @@ -235,7 +236,7 @@ Name: Verify
-When `"hash"` is passed as an argument, the code extracts the `data` and `algo` Tool arguments from the respective environment variables, then passes them to the `hash` function. +When `"hash"` is passed as an argument, the code extracts the `data` and `algo` tool arguments from the respective environment variables, then passes them to the `hash` function. The `hash` function is where the bulk of the business logic is implemented. @@ -262,10 +263,10 @@ export function hash(data: string = '', algo = 'sha256'): string { It starts off by validating the `data` and `algo` arguments. When an argument is invalid, the function throws an exception that describes the validation issue in detail. -The goal is to provide useful information that an Agent can use to construct valid arguments for future calls. +The goal is to provide useful information that an agent can use to construct valid arguments for future calls. For example, when an invalid `algo` argument is provided, the code returns an error that contains the complete list of valid algorithms. -Once it determines that all of the arguments are valid, it calculates the hash and writes a JSON object to stdout. +Once it determines that all the arguments are valid, it calculates the hash and writes a JSON object to stdout. This object contains the hash and the algorithm used to generate it. ```typescript @@ -277,7 +278,7 @@ This object contains the hash and the algorithm used to generate it. ``` > **Note:** Producing structured data with extra contextual info (e.g. the algorithm) is considered good form. -> It's a pattern that improves the Agent's ability to correctly use the Tool's result over time. +> It's a pattern that improves the agent's ability to correctly use the tool's result over time.
@@ -353,7 +354,7 @@ export function hash(data: string = '', algo = 'sha256'): string { ## Testing `src/tools.ts` and `src/hash.ts` Locally {#testing-src-tools-ts-and-src-hash-ts-locally-aeed7f15} -Before adding a Tool to `Otto8`, verify that the Typescript business logic works on your machine. +Before adding a tool to Obot, verify that the TypeScript business logic works on your machine. To do this, run through the following steps in the root of your local fork: @@ -363,10 +364,10 @@ To do this, run through the following steps in the root of your local fork: npm install ``` -2. Run the Tool with some test arguments: +2. Run the tool with some test arguments: - | **Command** |**Output** | - | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | + | **Command** | **Output** | + | ----------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `DATA='foo' npm run tool hash` | `{ "algo": "sha256", "hash": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae" }` | | `npm run tool hash` | `Error: A data argument must be provided` | | `DATA='foo' ALGO='md5' npm run tool hash` | `{ "algo": "md5", "hash": "acbd18db4cc2f85cedef654fccc4a4d8" }` | @@ -374,14 +375,14 @@ To do this, run through the following steps in the root of your local fork:
-## Adding The `Hash` Tool to `Otto8` {#adding-the-hash-tool-to-otto8-aeed7f15} +## Adding The `Hash` tool to Obot {#adding-the-hash-tool-to-obot-aeed7f15} -Before a Tool can be used by an Agent, an admin must first add the Tool to `Otto8` by performing the steps below: +Before a tool can be used by an agent, an admin must first add the tool to Obot by performing the steps below: 1.
- Navigate to the Otto8 admin UI in a browser and open the Tools page by clicking the Tools button in the left drawer + Navigate to the Obot admin UI in a browser and open the Tools page by clicking the Tools button in the left drawer
- Open The Tools Page
@@ -389,15 +390,15 @@ Before a Tool can be used by an Agent, an admin must first add the Tool to `Otto 2.
Click the Register New Tool button on the right
- Click The Register New Tool Button
3.
- Type the Tool repo reference into the modal's input box and click Register Tool + Type the tool repo reference into the modal's input box and click Register Tool
- Enter Tool Repo Reference
@@ -407,35 +408,35 @@ Before a Tool can be used by an Agent, an admin must first add the Tool to `Otto
Once the tool has been added, you can search for it by category or name on the Tools page to verify
- Search For Newly Added Tools
-## Using The `Hash` Tool in an Agent {#using-the-hash-tool-in-an-agent-aeed7f15} +## Using The `Hash` tool in an agent {#using-the-hash-tool-in-an-agent-aeed7f15} -To use the `Hash` Tool in an Agent, open the Agent's Edit page, then: +To use the `Hash` tool in an agent, open the agent's Edit page, then: 1.
Click the Add Tool button under either the Agent Tools or User Tools sections
- Click The Add Tool Button
2.
- Search for "Hash" or "Crypto" in the Tool search pop-out and select the Hash Tool + Search for "Hash" or "Crypto" in the tool search pop-out and select the Hash Tool
- Add Hash Tool To Agent
3.
- Ask the Agent to generate a hash + Ask the agent to generate a hash
- Ask The Agent To Generate a Hash
diff --git a/docs/snippets/python-hash-tool-readme.md.mdx b/docs/snippets/python-hash-tool-readme.md.mdx index 0f79505d..6cf1bf7e 100644 --- a/docs/snippets/python-hash-tool-readme.md.mdx +++ b/docs/snippets/python-hash-tool-readme.md.mdx @@ -1,20 +1,20 @@ ## Writing your first tool in Python {#writing-your-first-tool-in-python-28572835} -[python-hash-tool](https://github.com/otto8-ai/python-hash-tool) contains a reference `Python` implementation of the `Hash` Tool. +[python-hash-tool](https://github.com/obot-platform/python-hash-tool) contains a reference `Python` implementation of the `Hash` tool. -This guide walks through the structure and design of the Tool and outlines the packaging requirements for [Otto8](https://docs.otto8.ai/concepts/agents) +This guide walks through the structure and design of the tool and outlines the packaging requirements for [Obot](https://docs.obot.ai/concepts/agents) To clone this repo and follow along, run the following command: ```bash -git clone git@github.com:otto8-ai/python-hash-tool +git clone git@github.com:obot-platform/python-hash-tool ```
## Tool Repo Structure {#tool-repo-structure-28572835} -The directory tree below highlights the files required to implement `Hash` in Python and package it for `Otto8`. +The directory tree below highlights the files required to implement `Hash` in Python and package it for Obot. ``` python-hash-tool @@ -26,13 +26,13 @@ python-hash-tool ## Defining the `Hash` Tool {#defining-the-hash-tool-28572835} -The `tool.gpt` file contains [GPTScript Tool Definitions](https://docs.gptscript.ai/tools/gpt-file-reference) which describe a set of Tools that can be used by Agents in `Otto8`. -Every Tool repository must have a `tool.gpt` file in its root directory. +The `tool.gpt` file contains [GPTScript Tool Definitions](https://docs.gptscript.ai/tools/gpt-file-reference) which describe a set of tools that can be used by agents in Obot. +Every tool repository must have a `tool.gpt` file in its root directory. -The Tools defined in this file must have a descriptive `Name` and `Description` that will help Agents understand what the Tool does, what it returns (if anything), and all the `Parameters` it takes. -Agents use these details to figure out when and how to use the Tool. We call the section of a Tool definition that contains this info a `Preamble`. +The tools defined in this file must have a `Name` and `Description` that will help agents understand what the tool does, what it returns (if anything), and all the `Parameters` it takes. +Agents use these details to figure out when and how to use the tool. We call the section of a tool definition that contains this info a `Preamble`. -We want the `Hash` Tool to return the hash of some given `data`. It would also be nice to support a few different algorithms for the Agent to choose from. +We want the `Hash` tool to return the hash of some given `data`. It would also be nice to support a few different algorithms for the agent to choose from. Let's take a look at the `Preamble` for `Hash` to see how that's achieved: @@ -45,14 +45,14 @@ Param: algo: The algorithm to generate a hash with. Supports "sha256" and "md5". Breaking this down a bit: -- The `Preamble` above declares a Tool named `Hash`. -- The `Param` fields enumerate the arguments that an Agent must provide when calling `Hash`, `data` and `algo`. +- The `Preamble` above declares a tool named `Hash` +- The `Param` fields enumerate the arguments that an agent must provide when calling `Hash`, `data` and `algo` - In this case, the description of the `algo` parameter outlines the valid options (`sha256` or `md5`) and defines a default value (`sha256`) -- The `Description` explains what `Hash` returns with respect to the given arguments; the hash of `data` using the algorithm selected with `algo`. +- The `Description` explains what `Hash` returns with respect to the given arguments; the hash of `data` using the algorithm selected with `algo`
-Immediately below the `Preamble` is the `Tool Body`, which tells `Otto8` how to execute the Tool: +Immediately below the `Preamble` is the `Tool Body`, which tells Obot how to execute the tool: ```bash #!/usr/bin/env python3 ${GPTSCRIPT_TOOL_DIR}/hash.py @@ -61,17 +61,17 @@ Immediately below the `Preamble` is the `Tool Body`, which tells `Otto8` how to This is where the magic happens. -To oversimplify, when an Agent calls the `Hash` Tool, `Otto8` reads this line and then: +To simplify, when an agent calls the `Hash` tool, Obot reads this line and then: -1. Downloads the appropriate `Python` tool chain -2. Sets up a working directory for the Tool and creates a virtual environment +1. Downloads the appropriate `Python` toolchain +2. Sets up a working directory for the tool and creates a virtual environment 3. Installs the dependencies from the `requirements.txt`, if present 4. Projects the call arguments onto environment variables (`DATA` and `ALGO`) -5. Runs `python3 ${GPTSCRIPT_TOOL_DIR}/hash.py`. +5. Runs `python3 ${GPTSCRIPT_TOOL_DIR}/hash.py`
-Putting it all together, here's the complete definition of the `Hash` Tool. +Putting it all together, here's the complete definition of the `Hash` tool. ```yaml Name: Hash @@ -86,14 +86,14 @@ Param: algo: The algorithm to generate a hash with. Default is "sha256". Support ## Tool Metadata {#tool-metadata-28572835} -The `tool.gpt` file also provides the following metadata for use in `Otto8`: +The `tool.gpt` file also provides the following metadata for use in Obot: -- `!metadata:*:category` which tags Tools with the `Crypto` category to promote organization and discovery -- `!metadata:*:icon` which assigns `https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/fingerprint-duotone.svg` as the Tool icon +- `!metadata:*:category` which tags tools with the `Crypto` category to promote organization and discovery +- `!metadata:*:icon` which assigns `https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/fingerprint-duotone.svg` as the tool icon
-> **Note:** `*` is a wild card pattern that applies the metadata to all Tools in a `tool.gpt`. +> **Note:** `*` is a wildcard pattern that applies the metadata to all tools in a `tool.gpt`. ```yaml --- @@ -107,7 +107,7 @@ https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/fingerprint-d
- Note: Metadata can be applied to a specific Tool by either specifying the exact name (e.g. !metadata:Hash:category) or by adding the metadata directly to a Tool's Preamble + Note: Metadata can be applied to a specific tool by either specifying the exact name (e.g. !metadata:Hash:category) or by adding the metadata directly to a tool's Preamble ```yaml @@ -146,7 +146,7 @@ https://cdn.jsdelivr.net/npm/@phosphor-icons/core@2/assets/duotone/fingerprint-d ## Implementing Business Logic {#implementing-business-logic-28572835} -The `hash.py` file executed by the `Tool Body` is the concrete implementation of the Tool's business logic. +The `hash.py` file executed by the `Tool Body` is the concrete implementation of the tool's business logic. Let's walk through the code to understand how it works. @@ -161,10 +161,10 @@ if __name__ == '__main__': ``` Starting at the bottom, the `main` function is called in a `try` block so that any runtime exceptions caught are written to stdout. -This is important because everything written to stdout is returned to the Agent when the Tool call is completed, while everything written to stderr is discarded. -Using this pattern ensures that when a Tool call fails, the calling Agent is informed of the failure. +This is important because everything written to stdout is returned to the agent when the tool call is completed, while everything written to stderr is discarded. +Using this pattern ensures that when a tool call fails, the calling agent is informed of the failure. -Moving on, the `main` function implements the meat and potatoes of the `Hash` Tool. +Moving on, the `main` function implements the core logic of the `Hash` tool. ```python SUPPORTED_HASH_ALGORITHMS = ['sha256', 'md5'] @@ -184,12 +184,12 @@ def main(): #... ``` -It starts off by extracting the Tool's arguments from the respective environment variables and validates them. +It starts off by extracting the tool's arguments from the respective environment variables and validates them. When an argument is invalid, the function raises an exception that describes the validation issue in detail. -The goal is to provide useful information that an Agent can use to construct valid arguments for future calls. +The goal is to provide useful information that an agent can use to construct valid arguments for future calls. For example, when an invalid `algo` argument is provided, the code returns an error that contains the complete list of valid algorithms. -After validating the Tool arguments, it calculates the hash and writes a JSON object to stdout. +After validating the tool arguments, it calculates the hash and writes a JSON object to stdout. This object contains the hash and the algorithm used to generate it. ```python @@ -208,7 +208,7 @@ This object contains the hash and the algorithm used to generate it. ``` > **Note:** Producing structured data with extra contextual info (e.g. the algorithm) is considered good form. -> It's a pattern that improves the Agent's ability to correctly use the Tool's result over time. +> It's a pattern that improves the Agent's ability to correctly use the tool's result over time.
Complete hash.py @@ -263,7 +263,7 @@ if __name__ == '__main__': ## Testing `hash.py` Locally {#testing-hash-py-locally-28572835} -Before adding a Tool to `Otto8`, verify that the Python business logic works on your machine. +Before adding a tool to Obot, verify that the Python business logic works on your machine. To do this, run through the following steps in the root of your local fork: @@ -287,10 +287,10 @@ To do this, run through the following steps in the root of your local fork: pip freeze > requirements.txt ``` -4. Run the Tool with some test arguments: +4. Run the tool with some test arguments: - | **Command** | **Output** | - | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | + | **Command** | **Output** | + | --------------------------------------------- | -------------------------------------------------------------------------------------------------- | | `DATA='foo' python3 hash.py` | `{ "algo": "sha256", "hash": "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae" }` | | `python3 hash.py` | `Error: A data argument must be provided` | | `DATA='foo' ALGO='md5' python3 hash.py` | `{ "algo": "md5", "hash": "acbd18db4cc2f85cedef654fccc4a4d8" }` | @@ -298,14 +298,14 @@ To do this, run through the following steps in the root of your local fork:
-## Adding The `Hash` Tool to `Otto8` {#adding-the-hash-tool-to-otto8-28572835} +## Adding The `Hash` tool to Obot {#adding-the-hash-tool-to-obot-28572835} -Before a Tool can be used by an Agent, an admin must first add the Tool to `Otto8` by performing the steps below: +Before a tool can be used by an agent, an admin must first add the tool to Obot by performing the steps below: 1.
- Navigate to the Otto8 admin UI in a browser and open the Tools page by clicking the Tools button in the left drawer + Navigate to the Obot admin UI in a browser and open the Tools page by clicking the Tools button in the left drawer
- Open The Tools Page
@@ -313,15 +313,15 @@ Before a Tool can be used by an Agent, an admin must first add the Tool to `Otto 2.
Click the Register New Tool button on the right
- Click The Register New Tool Button
3.
- Type the Tool repo reference into the modal's input box and click Register Tool + Type the tool repo reference into the modal's input box and click Register Tool
- Enter Tool Repo Reference
@@ -331,35 +331,35 @@ Before a Tool can be used by an Agent, an admin must first add the Tool to `Otto
Once the tool has been added, you can search for it by category or name on the Tools page to verify
- Search For Newly Added Tools
-## Using The `Hash` Tool in an Agent {#using-the-hash-tool-in-an-agent-28572835} +## Using The `Hash` tool in an agent {#using-the-hash-tool-in-an-agent-28572835} -To use the `Hash` Tool in an Agent, open the Agent's Edit page, then: +To use the `Hash` tool in an agent, open the agent's Edit page, then: 1.
Click the Add Tool button under either the Agent Tools or User Tools sections
- Click The Add Tool Button
2.
- Search for "Hash" or "Crypto" in the Tool search pop-out and select the Hash Tool + Search for "Hash" or "Crypto" in the tool search pop-out and select the Hash Tool
- Add Hash Tool To Agent
3.
- Ask the Agent to generate a hash + Ask the agent to generate a hash
- Ask The Agent To Generate a Hash
diff --git a/docs/static/img/obot-logo-blue-black-text.svg b/docs/static/img/obot-logo-blue-black-text.svg new file mode 100644 index 00000000..e510f22a --- /dev/null +++ b/docs/static/img/obot-logo-blue-black-text.svg @@ -0,0 +1,90 @@ + + + + + + otto8 + + + + + + + + + + + + + + + + diff --git a/docs/static/img/obot-logo-blue-white-text.svg b/docs/static/img/obot-logo-blue-white-text.svg new file mode 100644 index 00000000..f921cf73 --- /dev/null +++ b/docs/static/img/obot-logo-blue-white-text.svg @@ -0,0 +1,93 @@ + + + + + + otto8 + + + + + + + + + + + + + + + + diff --git a/docs/static/img/otto8-logo-blue-black-text.svg b/docs/static/img/otto8-logo-blue-black-text.svg deleted file mode 100644 index ed08cd9e..00000000 --- a/docs/static/img/otto8-logo-blue-black-text.svg +++ /dev/null @@ -1,92 +0,0 @@ - - - - - - otto8 - - - - - - - - - - - - - - - - - diff --git a/docs/static/img/otto8-logo-blue-white-text.svg b/docs/static/img/otto8-logo-blue-white-text.svg deleted file mode 100644 index e1597933..00000000 --- a/docs/static/img/otto8-logo-blue-white-text.svg +++ /dev/null @@ -1,93 +0,0 @@ - - - - - - otto8 - - - - - - - - - - - - - - - - - diff --git a/docs/static/img/webhook-overview.png b/docs/static/img/webhook-overview.png index 12069e25..9df89e9a 100644 Binary files a/docs/static/img/webhook-overview.png and b/docs/static/img/webhook-overview.png differ