diff --git a/docs/docs/02-examples/01-cli.md b/docs/docs/02-examples/01-cli.md index 17c67244..4c8f3bab 100644 --- a/docs/docs/02-examples/01-cli.md +++ b/docs/docs/02-examples/01-cli.md @@ -1,110 +1,59 @@ # Chat with a Local CLI -GPTScript makes it easy to write AI integrations with CLIs and other executable available on your local workstation. This is powerful because it allows you to work AI to solve complex problems using your available CLIs. You can describe complex requests in plain English and GPTScript will figure out the best CLI commands to make that happen. This guide will show you how to build a GPTScript that integrates with two CLIs: - -- [gh](https://cli.github.com/) - the GitHub CLI -- [kubectl](https://kubernetes.io/docs/reference/kubectl/) - the Kubernetes CLI +GPTScript makes it easy to write AI integrations with CLIs and other executables available on your local workstation. +You can describe complex requests in plain English and GPTScript will figure out the best CLI commands to make that happen. +This guide will show you how to build a GPTScript that integrates with the `gh` CLI for GitHub. :::warning -This script **does not install** or configure gh or kubectl. We assume you've done that already. - -- For gh, you must be logged in via `gh auth login`. [See here for more details](https://docs.github.com/en/github-cli/github-cli/quickstart) -- For kubectl, you must have a proper `kubeconfig`. [See here for more details](https://kubernetes.io/docs/tasks/tools/) - +This script **does not install** or configure `gh`. We assume you've done that already. +You must be logged in via `gh auth login`. [See here for more details](https://docs.github.com/en/github-cli/github-cli/quickstart) ::: -## Too Long; Didn't Read - -Want to start using this script now? Just run: - -``` -gptscript github.com/gptscript-ai/cli-demo -``` - -Or if you want to skip ahead and just grab the full script so that you can start hacking on it, jump to the [Putting it all together section](cli#putting-it-all-together). +You should have basic familiarity with [tools](../03-tools/01-using.md) before starting this guide. ## Getting Started -The rest of this guide will walk you through building a script that can serve as an assistant for GitHub and Kubernetes tasks. We'll be explaining the how, what, and why along the way. - -First, open up a new gptscript file in your favorite editor. We'll call the file cli-demo.gpt +First, open up a new file in your favorite editor. We'll call the file `cli-demo.gpt`. ``` vim cli-demo.gpt ``` -All edits below are assumed to be in this file. At the end, we'll share the entire script as one cohesive file, but along the way we'll just be adding tools one-by-one. - -## Create the Kubernetes Agent - -Let's start by adding the Kubernetes agent. In our script, add the following: - -``` ---- -Name: k8s-agent -Description: An agent that can help you with your Kubernetes cluster by executing kubectl commands -Context: shared-context -Tools: sys.exec -Parameter: task: The kubectl related task to accomplish -Chat: true - -You have the kubectl cli available to you. Use it to accomplish the tasks that the user asks of you. - -``` - -Now, let's walk through this tool line-by-line. - -**---** is a block separator. It's how we delineate tools in a script. - -**Name and Description** help the LLM understand the purpose of this tool. You should always have meaningful names and descriptions. - -**Tools: sys.exec** makes the built-in `sys.exec` tool available to this agent. This gives the agent the ability to execute arbitrary commands. Based on our prompt, it will be used for kubectl commands. GPTScript's authorization system will prompt for approval whenever it's going to run a `sys.exec` command. - -**Parameter: task:** defines a parameter named "task" for this tool. This will be important later on when other tools need to hand-off to this tool - they'll pass the task to it as this parameter. As with the name and description fields, it's important to provide a good description so that the LLM knows how to use this parameter. - -**Chat: true** turns this tool into a "chat-able" tool, which we also call an "agent". This is important for open-ended tasks that might take some iteration. - -Finally, we have the **tool body**, which in this case is a prompt: - -``` -You have the kubectl cli available to you. Use it to accomplish the tasks that the user asks of you. -``` - -This is what the tool will actually do. Tool bodies can be prompts or raw code like python, javascript, or the [world's best programming language](https://x.com/ibuildthecloud/status/1796227491943637125) - bash. For chat-able tools, your tool body should always be a prompt. - -That's all there is to the Kubernetes agent. You can try it out now. One nice thing about GPTScript is that tools are composable. So, you can get this tool working well and then move onto the next tool without affecting this one. To launch this tool, run: - -``` -gptscript --sub-tool k8s-agent cli-demo.gpt -``` - -Once you're chatting, try asking it do something like list all the pods in your cluster or even to launch an new deployment in the cluster. +All edits below are assumed to be in this file. -## Create the GitHub Agent +## Create the entrypoint tool -Now let's add the GitHub Agent. Drop the following into the file below the tool we just added. +Let's start by adding the main tool to the file: ``` ---- -Name: github-agent -Description: An agent to help you with GitHub related tasks using the gh cli Context: learn-gh -Tools: sys.exec -Parameter: task: The GitHub task to accomplish +Context: github.com/gptscript-ai/context/cli Chat: true You have the gh cli available to you. Use it to accomplish the tasks that the user asks of you. ``` -This tool is very similar to the Kubernetes agent. There are just a few key differences: +Let's walk through this tool line by line. + +Each `Context` line references a context tool that will be run before the tool itself runs. +Context tools provide helpful output for the LLM to understand its capabilities and what it is supposed to do. +The first, `learn-gh`, we will define later in this file. +The second, `github.com/gptscript-ai/context/cli`, provides information to the LLM about the operating system that GPTScript is running on, +and gives it access to the `sys.exec` built-in tool, which is used to run commands. -1. Names and descriptions have been changed to reference GitHub and gh as appropriate. -2. We've introduced the `learn-gh` context. We'll explore this next. +`Chat: true` turns this tool into a "chat-able" tool, which we also call an "agent". +This causes the tool to run as an interactive chatbot, asking for user input and providing output. +If `Chat` is set to `false` (or not specified at all), the tool will run once without user interaction and exit. +This is useful for automated tasks, but right now we are working on an agent, so we set it to `true`. + +Lastly, there is the **tool body**, which in this case is a simple prompt, letting the LLM know that it should use the `gh` command and follow the user's instructions. +The tool body specifies what the tool should actually do. It can be a prompt or raw code like Python, JavaScript, or bash. +For chat-able tools, the tool body must be a prompt. ### The learn-gh context tool -Add this for the learn-gh context tool: +Next, add this to the file for the `learn-gh` context tool: ``` --- @@ -112,7 +61,7 @@ Name: learn-gh #!/usr/bin/env bash -echo "The following is the help text for the gh cli and some of its sub-commands. Use these when figuring out how to construct new commands. Note that the --search flag is used for filtering and sorting as well; there is no dedicate --sort flag." +echo "The following is the help text for the gh cli and some of its sub-commands. Use these when figuring out how to construct new commands. Note that the --search flag is used for filtering and sorting as well; there is no dedicated --sort flag." gh --help gh repo --help gh issue --help @@ -128,159 +77,34 @@ gh release --help gh release create --help ``` -As we saw, this tool is used as the context for the github-agent. Why did we add this and what does it do? +The `---` at the top of this tool is a block separator. It's how we delineate tools within a script file. -To answer that, let's first understand what the Context stanza does. Any tools referenced in the Context stanza will be called and their output will be added to the chat context. As the name suggests, this gives the LLM additional context for subsequent messages. Sometimes, an LLM needs extra instructions or context in order to achieve the desired results. There's no hard or fast rule here for when you should include context; it's best discovered through trial-and-error. +This tool has a `Name` field. We named this tool `learn-gh` so that it matches the `Context: learn-gh` line from the entrypoint tool. - We didn't need extra context for the Kubernetes tool because we found our default LLM knows kubectl (and Kubernetes) quite well. However, our same testing showed that our default LLM doesn't know the gh cli as well. Specifically, the LLM would sometimes hallucinate invalid combinations of flags and parameters. Without this context, the LLM often takes several tries to get the gh command correct. +The body of this tool is a bash script, rather than a prompt. +This context tool will be run by GPTScript automatically at the start of execution, and its output will be provided to the LLM. +We're running a bunch of `--help` commands in the `gh` CLI so that the LLM can understand how to use it. +GPTScript knows that this tool body is a script rather than a prompt because it begins with `#!`. -:::tip -Did you catch that "takes several tries to get the command correct" part? One useful feature of GPTScript is that it will feed error messages back to the LLM, which allows the LLM to learn from its mistake and try again. -::: +## Running the tool -And that's the GitHub Agent. You can try it out now: +Now try running the tool: ``` -gptscript --sub-tool github-agent cli-demo.gpt +gptscript cli-demo.gpt ``` -Once you're chatting, try asking it do something like "Open an issue in gptscript-ai/gptscript with a title and body that says Hi from me and states how wonderful gptscript is but jazz it up and make it unique" - -## Your CLI Assistant - -Right now if you were to launch this script, you'd be dropped right into the Kubernetes agent. Let's create a new entrypoint whose job it is to handle your initial conversation and route to the appropriate agent. Add this to the **TOP** of your file: - -``` -Name: Your CLI Assistant -Description: An assistant to help you with local cli-based tasks for GitHub and Kubernetes -Agents: k8s-agent, github-agent -Context: shared-context -Chat: true - -Help the user acomplish their tasks using the tools you have. When the user starts this chat, just say hello and ask what you can help with. You don't need to start off by guiding them. -``` - -By being at the top of the file, this tool will serve as the script's entrypoint. Here are the parts of this tool that are worth additional explanation: - -**Agents: k8s-agent, github-agent** puts these two agents into a group that can hand-off to each other. So, you can ask a GitHub question, then a Kubernetes question, and then a GitHub question again and the chat conversation will get transferred to the proper agent each time. - -Next is **Context: shared-context**. You're already familiar with contexts, but in the next section we'll explain what's unique about this one. - -### The shared-context tool - -Drop the shared-context tool in at the very bottom of the page: - -``` ---- -Name: shared-context -Share Context: github.com/gptscript-ai/context/history - -#!sys.echo -Always delegate to the best tool for the users request. -Ask the user for information needed to complete a task. -Provide the user with the exact action you will be taking and get the users confirmation when creating or updating resources. -ALWAYS ask the user to confirm deletions, provide as much detail about the action as possible. -``` - -and do one more thing: add it as a context tool to both the k8s-agent and github-agent. For k8s-agent, that means adding this line: `Context: shared-context` and for github-agent, it means modifying the existing Context line to: `Context: learn-gh, shared-context`. - -**Share Context: github.com/gptscript-ai/context/history** - In this line, "Share Context" means that the specified tool(s) will be part of the context for any tools that references this tool in their Context stanza. It's a way to compose and aggregate contexts. - - The specific tool referenced here - github.com/gptscript-ai/context/history - makes it so that when you transition from one agent to the next, your chat history is carried across. Using this file as an example, this would allow you to have a history of all the Kubernetes information you gathered available when talking to the GitHub tool. - -The **#!sys.echo** body is a simple way to directly output whatever text follows it. This is useful if you just have a static set of instructions you need to inject into the context. The actual text should make sense if you read it. We're telling the agents how we want them to behave and interact. - -## Putting it all together - -Let's take a look at this script as one cohesive file: - -``` -Name: Your CLI Assistant -Description: An assistant to help you with local cli-based dev tasks -Context: shared-context -Agents: k8s-agent, github-agent -Chat: true - -Help the user acomplish their tasks using the tools you have. When the user starts this chat, just say hello and ask what you can help with. You don't need to start off by guiding them. - ---- -Name: k8s-agent -Description: An agent that can help you with your Kubernetes cluster by executing kubectl commands -Context: shared-context -Tools: sys.exec -Parameter: task: The kubectl related task to accomplish -Chat: true - -You have the kubectl cli available to you. Use it to accomplish the tasks that the user asks of you. - ---- -Name: github-agent -Description: An agent to help you with GitHub related tasks using the gh cli -Context: learn-gh, shared-context -Tools: sys.exec -Parameter: task: The GitHub task to accomplish -Chat: true - -You have the gh cli available to you. Use it to accomplish the tasks that the user asks of you. - ---- -Name: learn-gh - -#!/usr/bin/env bash - -echo "The following is the help text for the gh cli and some of its sub-commands. Use these when figuring out how to construct new commands. Note that the --search flag is used for filtering and sorting as well; there is no dedicate --sort flag." -gh --help -gh repo --help -gh issue --help -gh issue list --help -gh issue create --help -gh issue comment --help -gh issue delete --help -gh issue edit --help -gh pr --help -gh pr create --help -gh pr checkout --help -gh release --help -gh release create --help - - ---- -Name: shared-context -Share Context: github.com/gptscript-ai/context/history - -#!sys.echo -Always delegate to the best tool for the users request. -Ask the user for information needed to complete a task. -Provide the user with the exact action you will be taking and get the users confirmation when creating or updating resources. -ALWAYS ask the user to confirm deletions, provide as much detail about the action as possible. -``` - -There isn't anything new to cover in this file, we just wanted you to get a holistic view of it. This script is now fully functional. You can launch it via: - -``` -gpscript cli-demo.gpt -``` - -### Adding your own CLI - -By now you should notice a simple pattern emerging that you can follow to add your own CLI-powered agents to a script. Here are the basics of what you need: - -``` -Name: {your cli}-agent -Description: An agent to help you with {your taks} related tasks using the gh cli -Context: {here's your biggest decision to make}, shared-context -Tools: sys.exec -Parameter: task: The {your task} to accomplish -Chat: true - -You have the {your cli} cli available to you. Use it to accomplish the tasks that the user asks of you. -``` +Once you're chatting, try asking it do something like "Open an issue in gptscript-ai/gptscript with a title and body that says Hi from me and states how wonderful gptscript is but jazz it up and make it unique". +GPTScript will ask for confirmation before it runs each command, so you can make sure that it only runs the commands you want it to. -You can drop in your task and CLI and have a fairly functional CLI-based chat agent. The biggest decision you'll need to make is what and how much context to give your agent. For well-known CLIs/technologies like kubectl and Kubernetes, you probably won't need a custom context. For custom CLIs, you'll definitely need to help the LLM out. The best approach is to experiment and see what works best. +## A note on context tools -## Next steps +Context tools are a powerful way to provide additional information to the LLM, but they are not always necessary. +If you are working with a system that the LLM already understands well, you will probably not need to provide additional context. +When writing your own tools, it may take some trial and error to determine whether a context tool is needed. +If the LLM frequently hallucinates subcommands or arguments, it is probably worth adding a context tool to provide more information about the CLI. -Hopefully you've found this guide helpful. From here, you have several options: +## Next Steps -- You can checkout out some of our other guides available in this section of the docs -- You can dive deeper into the options available when [writing script](/tools/gpt-file-reference) +- You can check out some of our other guides available in this section of the docs +- You can dive deeper into the options available when [writing scripts](/tools/gpt-file-reference) diff --git a/docs/docs/02-examples/02-api.md b/docs/docs/02-examples/02-api.md index d84ae653..468fdd48 100644 --- a/docs/docs/02-examples/02-api.md +++ b/docs/docs/02-examples/02-api.md @@ -1,40 +1,27 @@ # Chat with an API -Interacting with cloud providers through dashboards, APIs, and CLIs is second nature to devops engineers. Using AI chat, the engineer can express a goal, and the AI can generate and execute the calls needed to achieve it. This saves the engineer time from having to look up the API calls needed themselves. GPTScript makes building a chat integration with an existing OpenAPI schema quick and easy. +GPTScript makes it easy to create a chatbot interface to interact with an API. -This guide will walk through the process of using the OpenAPI spec from Digital Ocean to build a chatbot capable of launching droplets and databases. The reader will be able to continue adding Digital Ocean capabilities or build their own chatbot with another OpenAPI schema. +This guide will demonstrate how to build a chatbot that interacts with the DigitalOcean API. -## Too Long; Didn't Read +## Getting Started -If you just want to try out the Digital Ocean chatbot first: - -Follow the [API credential](#api-access) settings here. - -Then you can run the following commands to get started: - -```bash -gptscript github.com/gptscript-ai/digital-ocean-agent -``` - -## Getting started - -First we will need to download a copy of the openapi.yaml. This spec technically can be accessed by URL, but initially, it is easier to download a copy and save it as openapi.yaml. - -### The Digital Ocean openapi.yaml spec - -Getting the openapi.yaml file from Digital Ocean can be done by running the following command in a terminal. +First, you will need to download a copy of DigitalOcean's OpenAPI definition. +While you can reference it by its URL, it is a bit easier to work with it locally. +You can download the file by running the following command: ```bash curl -o openapi.yaml -L https://api-engineering.nyc3.cdn.digitaloceanspaces.com/spec-ci/DigitalOcean-public.v2.yaml ``` -This will download a copy of the openapi yaml file to the local directory. +This will download a copy of the OpenAPI definition to the current directory. -Lets take a look at the spec file a little bit. The integration in GPTScript creates a tool named after each operationId in the OpenAPI spec. You can see what these tools would be by running the following. +Let's examine this OpenAPI file. GPTScript will create a tool named after each operationId in the file. +You can see the operationIds by running the following command: ```bash grep operationId openapi.yaml -# … +# ... # operationId: domains_delete_record # operationId: droplets_list # operationId: droplets_create @@ -50,189 +37,72 @@ grep operationId openapi.yaml # operationId: droplets_list_kernels # operationId: droplets_list_firewalls # operationId: droplets_list_neighbors -# … -``` - -If we look at the operationIds, you’ll notice they are structured around an object like droplet, database, or project. Each object has a collection of verb like list, get, delete, create, etc. Each tool in GPTScript has it’s own set of tools. So we can create agents, tools with chat enabled, that are experts in a specific set of objects and have access to all of the object_verb tools available to them. This allows us to fan out tools from a main entrypoint to multiple experts that can solve the users tasks. - -Lets explore this design pattern. - -## Creating Main Entrypoint - -Lets start by creating our main entrypoint to the Digital Ocean chatbot. The main tool in a GPTScript chat program is usually named agent.gpt. Let’s first setup the agents by giving it a name, the ability to chat, basic instructions, and the main greeting prompt. Create an agent.gpt file with the following contents. - -agent.gpt - -``` -Name: Digital Ocean Bot -Chat: true - -You are a helpful DevOps assistant that is an expert in Digital Ocean. -Using only the tools available, do not answer without using a tool, respond to the user task. -Greet the User with: "Hello! How can I help you with Digital Ocean?" -``` - -This file when run will show the following. - -![screenshot](/img/chat-api.png) - -In the current form, the chatbot will not be able to do anything since it doesn’t have access to any APIs. Let’s address that now, open our tool.gpt file and add the following. - -agent.gpt - +# ... ``` -Name: Digital Ocean Bot -Chat: true -Agents: droplets.gpt -You are a helpful DevOps assistant that is an expert in Digital Ocean -Using only the tools available, do not answer without using a tool, respond to the user task. -Greet the User with: "Hello! How can I help you with Digital Ocean?" -``` +The operationIds generally follow a pattern of `object_verb`. +This will be helpful for us, because we can use wildcard matching to refer to a subset of the operations. -Now lets create a droplets.gpt file to bring in the droplet tools. +## Creating the Script -droplets.gpt +Create a `tool.gpt` file with the following contents: ``` -Name: Droplet Agent +Name: DigitalOcean Bot Chat: true -Tools: droplets* from ./openapi.yaml -Description: Use this tool to work with droplets -Args: request: the task requested by the user +Tools: droplets* from openapi.yaml +Tools: databases* from openapi.yaml +Tools: images* from openapi.yaml +Tools: regions_list from openapi.yaml +Tools: tags* from openapi.yaml +Tools: sizes_list from openapi.yaml +Tools: sshKeys_list from openapi.yaml +Tools: sys.time.now -Help the user complete their Droplet operation requests using the tools available. -When creating droplets, always ask if the user would like to access via password or via SSHkey. +You are a helpful assistant with access to the DigitalOcean API to manage droplets and databases. +Before creating, updating, or deleting anything, tell the user about the exact action you are going to take, and get their confirmation. +Start the conversation by asking the user how you can help. ``` -Here we have defined the Droplet Agent, and enabled chat. We have also brought in an subset of the openapi.yaml tools that relate to droplets. By using droplets* we are making available everything droplet related into the available tools for this agent. We also provided the description to the main agent, and any other agent that has access to it, when to utilize this tool. We also have an argument called “request”, this is used when the LLM decides to call the agent it can smoothly pass off the user request without the Droplet Agent having to ask again. - -## Chat with Digital Ocean +This chatbot has access to several tools that correspond to various operations in the DigitalOcean OpenAPI file. +We give it access to all tools related to droplets and databases, since those are the main things we want it to work with. +In order to support this, we also need to give it access to images, regions, tags, etc. so that it can get the information it needs to create new droplets and databases. +Lastly, the `sys.time.now` tool is a tool that is built-in to GPTScript that provides the current date and time. -### API Access +:::note +We cannot give the entire `openapi.yaml` file to the tool because it contains too many API operations. +Most LLM providers, such as OpenAI, have a limit on the number of tools that you can provide to the model at one time. +The OpenAPI file contains over 300 operations, which is too many for most LLMs to handle at once. +::: -Now that we have brought in our first tool using the OpenAPI spec, we will need to setup authentication. Defined in the openapi.yaml is how the Digital Ocean API expects authenticated requests to work. If you look in the spec file path of components.securitySchemes you will see that Digital Ocean expects bearer_auth. So you will need to create an API key in the Digital Ocean dashboard with the access you want the LLM to be able to interact with Digital Ocean. For instance, you can do a read only key that will allow you to just query information, or you can provide it full access and the operator can work with the LLM to do anything in the project. It is up to you. For this example, we will be using a full access token, but you can adjust for your needs. You can create your API key by going to this link [Apps & API](https://cloud.digitalocean.com/account/api/tokens) section in your account. +## Creating an API Token -Once you have an API key, you will need to set an environment variable with that value stored. - -```bash -export GPTSCRIPT_API_DIGITALOCEAN_COM_BEARER_AUTH=****** -``` +Before you run this script, you need to have a DigitalOcean API token. -Where the *** is the API key created in the dashboard. +Go to [Applications & API](https://cloud.digitalocean.com/account/api/tokens) in the DigitalOcean dashboard and create a new token. +You can select whichever scopes you want, but you should at least give it the ability to read droplets and databases. -### Chatting with Digital Ocean APIs +## Running the Script -Now you can run gptscript to start your conversation with Digital Ocean. +Let's run the script and start chatting with it: ```bash -gptscript agent.gpt -``` - -You should now be able to ask how many droplets are running? - -And get an output from the chatbot. This is great, but not quite ready to use just yet. Lets keep adding some functionality. - -## Adding Database Support - -Now that we can do droplets, we can add support for databases just as easy. Lets create a databases.gpt file with the following contents. - -Ddtabases.gpt - -``` -Name: Database Agent -Chat: true -Tools: databases* from ./openapi.yaml -Description: Call this tool to manage databases on digital ocean -Args: request: the task requested by the user - -Help the user complete database operation requests with the tools available. -``` - -Here again, we are essentially scoping our agent to handle database calls with the Digital Ocean API. Now in order for this to be used, we need to add it to our agent list in the main agent.gpt file. - -Agent.gpt - -``` -Name: Digital Ocean Bot -Chat: true -Agents: droplets.gpt, databases.gpt - -You are a helpful DevOps assistant that is an expert in Digital Ocean -Using only the tools available, do not answer without using a tool, respond to the user task. -Greet the User with: "Hello! How can I help you with Digital Ocean?" -``` - -Now when we test it out we can ask how many databases are running? And it should give back the appropriate response. - -Now, when it comes to creating a database or droplet, we are missing some APIs to gather the correct information. We don’t have access to size information, regions, SSH Keys, etc. Since these are common tools, it would be a bit of a hassle to add lines to both the databases.gpt and droplets.gpt files. To avoid this, we can make use of the GPTScript Context to provide a common set of tools and instructions. - -## Context - -Context is a powerful concept in GPTScript that provides information to the system prompt, and provide a mechanism to compose a common set of tools reducing duplication in your GPTScript application. Lets add a context.gpt file to our chatbot here with the following contents. - -context.gpt - -``` -Share Tools: sys.time.now - -Share Tools: images* from ./openapi.yaml -Share Tools: regions_list from ./openapi.yaml -Share Tools: tags* from openapi.yaml -Share Tools: sizes_list from ./openapi.yaml -Share Tools: sshKeys_list from ./openapi.yaml - - -#!sys.echo -Always delegate to the best tool for the users request. -Ask the user for information needed to complete a task. -Provide the user with the exact action you will be taking and get the users confirmation when creating or updating resources. -ALWAYS ask the user to confirm deletions, provide as much detail about the action as possible. -``` - -There is quite a bit going on here, so lets break it down. Anywhere you see Share Tools it is making that tool available to anything uses the context. In this case, it is providing access to the time now tool so you can ask what was created yesterday and the LLM can get a frame of reference. Additionally, it provides a common set of Digital Ocean APIs that are needed for placement, organization(tags), sizes, and images, etc. Since multiple components in Digital Ocean use these values, it is useful to only need to define it once. Last we are providing a set of common instructions for how we want the chatbot to behave overall. This way, we do not need to provide this information in each agent. Also, since this is in the system prompt, it is given a higher weight to the instructions in the individual agents. - -Now lets add this to our agents. You will need to add the line: - -``` -Context: context.gpt -``` - -To each of our agents, so the droplets.gpt, agent.gpt, and databases.gpt will have this line. - -## Wrapping up - -Provided you have given API access through your token, you should now be able to run the chatbot and create a database or a droplet and be walked through the process. You should also be able to ask quesitons like What VMs were created this week? - -You now know how to add additional capabilities through agents to the chatbots. You can follow the same patterns outlined above to add more capabilities or you can checkout the chat bot repository to see additional functionality. - -### Use your own OpenAPI schema - -If you have your own OpenAPI schema, you can follow the same pattern to build a chatbot for your own APIs. The simplest way to get started is to create a gptscript file with the following contents. - -``` -Name: {Your API Name} Bot -Chat: true -Tools: openapi.yaml - -You are a helpful assistant. Say "Hello, how can I help you with {Your API Name} system today?" +gptscript tool.gpt ``` -You can then run that and the LLM will be able to interact with your API. +Try asking it to list your current databases or droplets, or to help you create a new one. -#### Note on OpenAI tool limits +The first time the LLM tries to make an API call, it will ask for your API token. +Paste it into the prompt. It will be used for all future API calls as well. +The LLM will never see or store your API token. It is only used client-side, on your computer. -As we mentioned before, GPTScript creates a tool for each operationId in the OpenAPI spec. If you have a large OpenAPI spec, you may run into a limit on the number of tools that can be created. OpenAI, the provider of the GPT-4o model only allows a total of 200 tools to be passed in at a single time. If you exceed this limit, you will see an error message from OpenAI. If you run into this issue, you can follow the same pattern we did above to create our Digital Ocean bot. +## Next Steps -A quick check to see how many tools total would be created, you can run the following: +Feel free to modify the script to add other parts of the DigitalOcean API. +You could also try creating a chatbot for a different API with an OpenAPI definition. -```bash -grep operationId openapi.yaml|wc -l - 306 -``` +For a more advanced DigitalOcean chatbot, see our [DigitalOcean Agent](https://github.com/gptscript-ai/digital-ocean-agent) tool. -In our case, there are 306 tools that would be created in the case of our Digital Ocean spec. This would not fit into a single agent, so breaking it up into multiple agents is the best way to handle this. - -## Next Steps +To read more about OpenAPI tools in GPTScript, see the [OpenAPI Tools](../03-tools/03-openapi.md) article. -Now that you have seen how to create a chatbot with an OpenAPI schema, checkout our other guides to see how to build other ChatBots and agents. +To read more about credential storage in GPTScript, see the [Credentials](../02-credentials.md) article. diff --git a/docs/docs/02-examples/04-local-files.md b/docs/docs/02-examples/04-local-files.md index 33471afa..252ddf96 100644 --- a/docs/docs/02-examples/04-local-files.md +++ b/docs/docs/02-examples/04-local-files.md @@ -1,6 +1,9 @@ # Chat with Local Files -With GPTScript interacting with local files is simple and powerful. This can help you streamline repetitive or data-intensive tasks. In this guide, we'll build a script that can query Excel files, CSVs, and PDFs. We'll then use the script to read, transform, and utilize the data in these files. +With GPTScript, interacting with local files is simple and powerful. +This can help you streamline repetitive or data-intensive tasks. +In this guide, we'll build a script that can query Excel files, CSVs, and PDFs. +We'll then use the script to read, transform, and utilize the data in these files. ## Too Long; Didn't Read @@ -14,60 +17,79 @@ gptscript --workspace=~/Documents github.com/gptscript-ai/local-files-demo ``` ## Getting Started -The rest of this guide will walk you through building and using a data processing assistant. We'll be explaining the how, what, and why along the way. + +The rest of this guide will walk you through building and using a data processing assistant. First, let's get some sample data to work with. You can clone our repo with our sample data: + ``` git clone https://github.com/gptscript-ai/local-files-demo.git cd local-files-demo ``` -Next, open up a new gptscript file in your favorite editor. We'll call the file data-assistant.gpt. +Next, open up a new gptscript file in your favorite editor. We'll call the file `data-assistant.gpt`. + ``` vim data-assistant.gpt ``` + All edits below are assumed to be in this file. ### Create the Assistant -Put this in the gpt file: + +Add this to the file: + ``` -Name: Your Data Processing Assitant -Description: An asistant to help you with processing data found in files on your workstation. Helpful for querying spreadsheets, CSVs, JSON files, and pdfs. +Name: Data Processing Assitant +Description: An assistant to help you with processing data found in files on your workstation. Helpful for querying spreadsheets, CSVs, JSON files, and PDFs. Tools: github.com/gptscript-ai/structured-data-querier, github.com/gptscript-ai/pdf-reader Context: github.com/gptscript-ai/context/workspace Chat: true -You are a helpful data processing assistant. Your goal is to help the user with data processing. Help the user accomplish their tasks using the tools you have. When the user starts this chat, just say hi, introduce yourself, and ask what you can help with. +You are a helpful data processing assistant. Your goal is to help the user with data processing. +Help the user accomplish their tasks using the tools you have. +When the user starts this chat, say hi, introduce yourself, and ask what you can help with. ``` -This is actually the entirety of the script. We're packing a lot of power into just a handful of lines here. Let's talk through them. -**Name and Description** help the LLM understand the purpose of this tool. You should always have meaningful names and descriptions. +This is the entire script. Here's what each part does: + +`Name and Description` help the LLM understand the purpose of this tool. You should always have meaningful names and descriptions. -The **Tools: ...** stanza pulls two useful tools into this assistant. +The `Tools: ...` line provides two useful tools to this assistant. -The [structured-data-querier](https://github.com/gptscript-ai/structured-data-querier) makes it possible to query csv, xlsx, and json files as though they were SQL databases (using an application called [DuckDB](https://duckdb.org/)). This is extremely powerful when combined with the power of LLMs because it let's you ask natural language questions that the LLM can then translate to SQL. +The [structured-data-querier](https://github.com/gptscript-ai/structured-data-querier) makes it possible to query CSV, XLSX, and JSON files as though they were SQL databases (using an application called [DuckDB](https://duckdb.org/)). +This is extremely powerful when combined with the power of LLMs because it allows you to ask natural language questions that the LLM can then translate to SQL. -The [pdf-reader](https://github.com/gptscript-ai/pdf-reader) isn't quite as exciting, but still useful. It parses and reads PDFs and returns the contents to the LLM. This will put the entire contents in your chat context, so it's not appropriate for extremely large PDFs, but it's handy for smaller ones. +The [pdf-reader](https://github.com/gptscript-ai/pdf-reader) parses and reads PDFs and returns the contents to the LLM. +This will put the entire contents in your chat context, so it's not appropriate for extremely large PDFs, but it's handy for smaller ones. -**Context: github.com/gptscript-ai/context/workspace** introduces a context tool that makes this assistant "workspace" aware. Its description reads: +`Context: github.com/gptscript-ai/context/workspace` introduces a [context tool](../03-tools/05-context.md) makes this assistant "workspace" aware. Its description reads: > Adds the workspace and tools needed to access the workspace to the current context -That translates to telling the LLM what the workspace directory is and instructing it to use that directory for reading and writing files. As we saw above, you can specify a workspace like this: +Basically, this context tool tells the LLM what the workspace directory is and instructs it to use that directory for reading and writing files. +As we saw above, you can specify a workspace like this: + ``` gptscript --workspace=/Your/path/here ... ``` + If you don't specify one, a temporary directory will be created and used for the workspace. -This context also shares the `sys.read`, `sys.write`, and `sys.ls` built-in tools with the assistant so that it automatically has access to them. +This context tool also shares the `sys.read`, `sys.write`, and `sys.ls` built-in tools with the assistant. -Next we have **Chat: true**, which you've seen if you looked at any of our other guides. This makes the current tool "chat-able". We refer to chatable tools as agents or assistants. +Next we have `Chat: true`. This makes the current tool "chat-able". We refer to chat-able tools as agents or assistants. Finally, we have the prompt: -> You are a helpful data processing assistant. Your goal is to help the user with data processing tasks. Help the user accomplish their tasks using the tools you have. When the user starts this chat, just say hi, introduce yourself, and ask what you can help with. +> You are a helpful data processing assistant. Your goal is to help the user with data processing. +> Help the user accomplish their tasks using the tools you have. +> When the user starts this chat, say hi, introduce yourself, and ask what you can help with. ## Using the Assistant -Once again, that's all there is to this assistant. You can start using it by specifying your own workspace or using our sample-data directory as the workspace. Assuming you're using our sample data and have followed these instructions, here's how you launch it: + +When you run the assistant, you can specify your own workspace folder or our sample data directory +Assuming you're using our sample data and have followed these instructions, here's how you run it: + ``` gptscript --workspace=./sample-data data-assistant.gpt ``` @@ -75,6 +97,7 @@ gptscript --workspace=./sample-data data-assistant.gpt Here's a few sample interactions with these files. ### Cleaning up data + ``` > whats in the key contacts file? @@ -114,6 +137,7 @@ Here's a few sample interactions with these files. ``` ### Identifying and fixing data gaps + ``` > is there any missing data in that csv? ... @@ -126,6 +150,7 @@ Here's a few sample interactions with these files. ``` ### Cross-referencing + ``` > what were sales like for Kevin's location? @@ -149,7 +174,9 @@ Here's a few sample interactions with these files. Is there anything else you would like to know or do with this data? ``` + ### Pulling all the info together + ``` > Let's help Kevin raise sales. What promotions do we have going on? ... @@ -234,11 +261,12 @@ Here's a few sample interactions with these files. Feel free to customize this email further to better suit your needs. Let me know if there's anything else I can assist you with! ``` + Try it out yourself and see what you can come up with. ## Next steps Hopefully you've found this guide helpful. From here, you have several options: -- You can checkout out some of our other guides available in this section of the docs +- You can check out some of our other guides available in this section of the docs - You can dive deeper into the options available when [writing script](/tools/gpt-file-reference) diff --git a/docs/docs/02-examples/05-workflow.md b/docs/docs/02-examples/05-workflow.md index 0aca6fc3..7f903536 100644 --- a/docs/docs/02-examples/05-workflow.md +++ b/docs/docs/02-examples/05-workflow.md @@ -1,15 +1,14 @@ # Run an Automated Workflow -Automating a sequence of tasks that integrate with one or more systems is a ubiquitous engineering problem that typically requires some degree of domain-specific knowledge up-front. However, workflows written with GPTScript all but eliminate this prerequisite, enabling developers to build their workflows by describing the high-level steps it should perform. +Automating a sequence of tasks that integrate with one or more systems is a ubiquitous engineering problem that typically requires some degree of domain-specific knowledge up-front. +However, workflows written with GPTScript all but eliminate this prerequisite, enabling developers to build their workflows by describing the high-level steps it should perform. This guide will show you how to build a GPTScript that encapsulates a workflow consisting of the following steps: -1. Get a selection of twitter posts +1. Get a selection of X (Twitter) posts 2. Summarize their content 3. Summarize the content of any links they directly reference 4. Write the results to a Markdown document -We'll be explaining the how, what, and why along the way. - ## Too long; didn't read Want to start using this script now? Just run: @@ -53,7 +52,7 @@ This tool: - imports two other tools - `sys.write` is a built-in tool which enables the entrypoint tool to write files to your system. - `summarize-tweet` is a custom tool that encapsulates how each tweet gets summarized. We'll define this tool in the next step. -- ensures tweets are never summarized in parallel to ensure they are summarized in the correct order +- ensures tweets are never summarized in parallel so that they are summarized in the correct order - defines the tweet URLs to summarize and the file to write them to At a high-level, it's getting the summaries for two tweets and storing them in the `tweets.md` file. @@ -87,7 +86,7 @@ This tool - imports three other tools to solve summarization sub-problems - `github.com/gptscript-ai/browser` is an external tool that is used to open the tweet URL in the browser and extract the page content - `get-hyperlinks` and `summarize-hyperlinks` are custom helper tools we'll define momentarily that extract hyperlinks from tweet text and summarize them -- describes the markdown document this tool should produce, leaving it up to the LLM to decide which of the available tools to call to make this happen +- describes the Markdown document this tool should produce, leaving it up to the LLM to decide which of the available tools to call to make this happen ## Hyperlink Summarization Tools diff --git a/docs/docs/03-tools/02-authoring.md b/docs/docs/03-tools/02-authoring.md index 3e81613a..186147a6 100644 --- a/docs/docs/03-tools/02-authoring.md +++ b/docs/docs/03-tools/02-authoring.md @@ -6,7 +6,7 @@ This file is itself a GPTScript that defines the tool's name, description, and w ## Quickstart -This is a guide for writing portable tools for GPTScript. The supported languages currently are Python, NodeJS, and Go. This guide uses Python but you can see documentation for the other language below. +This is a guide for writing portable tools for GPTScript. The supported languages currently are Python, Node.js, and Go. This guide uses Python, but you can see documentation for the other language below. ### 1. Write the code