You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
4
-
5
-
-[gh](https://cli.github.com/) - the GitHub CLI
6
-
-[kubectl](https://kubernetes.io/docs/reference/kubectl/) - the Kubernetes CLI
3
+
GPTScript makes it easy to write AI integrations with CLIs and other executables available on your local workstation.
4
+
You can describe complex requests in plain English and GPTScript will figure out the best CLI commands to make that happen.
5
+
This guide will show you how to build a GPTScript that integrates with the `gh` CLI for GitHub.
7
6
8
7
:::warning
9
-
This script **does not install** or configure gh or kubectl. We assume you've done that already.
10
-
11
-
- 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)
12
-
- For kubectl, you must have a proper `kubeconfig`. [See here for more details](https://kubernetes.io/docs/tasks/tools/)
13
-
8
+
This script **does not install** or configure `gh`. We assume you've done that already.
9
+
You must be logged in via `gh auth login`. [See here for more details](https://docs.github.com/en/github-cli/github-cli/quickstart)
14
10
:::
15
11
16
-
## Too Long; Didn't Read
17
-
18
-
Want to start using this script now? Just run:
19
-
20
-
```
21
-
gptscript github.com/gptscript-ai/cli-demo
22
-
```
23
-
24
-
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).
12
+
You should have basic familiarity with [tools](../03-tools/01-using.md) before starting this guide.
25
13
26
14
## Getting Started
27
15
28
-
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.
29
-
30
-
First, open up a new gptscript file in your favorite editor. We'll call the file cli-demo.gpt
16
+
First, open up a new file in your favorite editor. We'll call the file `cli-demo.gpt`.
31
17
32
18
```
33
19
vim cli-demo.gpt
34
20
```
35
21
36
-
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.
37
-
38
-
## Create the Kubernetes Agent
39
-
40
-
Let's start by adding the Kubernetes agent. In our script, add the following:
41
-
42
-
```
43
-
---
44
-
Name: k8s-agent
45
-
Description: An agent that can help you with your Kubernetes cluster by executing kubectl commands
46
-
Context: shared-context
47
-
Tools: sys.exec
48
-
Parameter: task: The kubectl related task to accomplish
49
-
Chat: true
50
-
51
-
You have the kubectl cli available to you. Use it to accomplish the tasks that the user asks of you.
52
-
53
-
```
54
-
55
-
Now, let's walk through this tool line-by-line.
56
-
57
-
**---** is a block separator. It's how we delineate tools in a script.
58
-
59
-
**Name and Description** help the LLM understand the purpose of this tool. You should always have meaningful names and descriptions.
60
-
61
-
**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.
62
-
63
-
**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.
64
-
65
-
**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.
66
-
67
-
Finally, we have the **tool body**, which in this case is a prompt:
68
-
69
-
```
70
-
You have the kubectl cli available to you. Use it to accomplish the tasks that the user asks of you.
71
-
```
72
-
73
-
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.
74
-
75
-
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:
76
-
77
-
```
78
-
gptscript --sub-tool k8s-agent cli-demo.gpt
79
-
```
80
-
81
-
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.
22
+
All edits below are assumed to be in this file.
82
23
83
-
## Create the GitHub Agent
24
+
## Create the entrypoint tool
84
25
85
-
Now let's add the GitHub Agent. Drop the following into the file below the tool we just added.
26
+
Let's start by adding the main tool to the file:
86
27
87
28
```
88
-
---
89
-
Name: github-agent
90
-
Description: An agent to help you with GitHub related tasks using the gh cli
91
29
Context: learn-gh
92
-
Tools: sys.exec
93
-
Parameter: task: The GitHub task to accomplish
30
+
Context: github.com/gptscript-ai/context/cli
94
31
Chat: true
95
32
96
33
You have the gh cli available to you. Use it to accomplish the tasks that the user asks of you.
97
34
98
35
```
99
36
100
-
This tool is very similar to the Kubernetes agent. There are just a few key differences:
37
+
Let's walk through this tool line by line.
38
+
39
+
Each `Context` line references a context tool that will be run before the tool itself runs.
40
+
Context tools provide helpful output for the LLM to understand its capabilities and what it is supposed to do.
41
+
The first, `learn-gh`, we will define later in this file.
42
+
The second, `github.com/gptscript-ai/context/cli`, provides information to the LLM about the operating system that GPTScript is running on,
43
+
and gives it access to the `sys.exec` built-in tool, which is used to run commands.
101
44
102
-
1. Names and descriptions have been changed to reference GitHub and gh as appropriate.
103
-
2. We've introduced the `learn-gh` context. We'll explore this next.
45
+
`Chat: true` turns this tool into a "chat-able" tool, which we also call an "agent".
46
+
This causes the tool to run as an interactive chatbot, asking for user input and providing output.
47
+
If `Chat` is set to `false` (or not specified at all), the tool will run once without user interaction and exit.
48
+
This is useful for automated tasks, but right now we are working on an agent, so we set it to `true`.
49
+
50
+
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.
51
+
The tool body specifies what the tool should actually do. It can be a prompt or raw code like Python, JavaScript, or bash.
52
+
For chat-able tools, the tool body must be a prompt.
104
53
105
54
### The learn-gh context tool
106
55
107
-
Add this for the learn-gh context tool:
56
+
Next, add this to the file for the `learn-gh` context tool:
108
57
109
58
```
110
59
---
111
60
Name: learn-gh
112
61
113
62
#!/usr/bin/env bash
114
63
115
-
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."
64
+
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."
116
65
gh --help
117
66
gh repo --help
118
67
gh issue --help
@@ -128,159 +77,34 @@ gh release --help
128
77
gh release create --help
129
78
```
130
79
131
-
As we saw, this tool is used as the context for the github-agent. Why did we add this and what does it do?
80
+
The `---` at the top of this tool is a block separator. It's how we delineate tools within a script file.
132
81
133
-
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.
82
+
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.
134
83
135
-
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.
84
+
The body of this tool is a bash script, rather than a prompt.
85
+
This context tool will be run by GPTScript automatically at the start of execution, and its output will be provided to the LLM.
86
+
We're running a bunch of `--help` commands in the `gh` CLI so that the LLM can understand how to use it.
87
+
GPTScript knows that this tool body is a script rather than a prompt because it begins with `#!`.
136
88
137
-
:::tip
138
-
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.
139
-
:::
89
+
## Running the tool
140
90
141
-
And that's the GitHub Agent. You can try it out now:
91
+
Now try running the tool:
142
92
143
93
```
144
-
gptscript --sub-tool github-agent cli-demo.gpt
94
+
gptscript cli-demo.gpt
145
95
```
146
96
147
-
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"
148
-
149
-
## Your CLI Assistant
150
-
151
-
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:
152
-
153
-
```
154
-
Name: Your CLI Assistant
155
-
Description: An assistant to help you with local cli-based tasks for GitHub and Kubernetes
156
-
Agents: k8s-agent, github-agent
157
-
Context: shared-context
158
-
Chat: true
159
-
160
-
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.
161
-
```
162
-
163
-
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:
164
-
165
-
**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.
166
-
167
-
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.
168
-
169
-
### The shared-context tool
170
-
171
-
Drop the shared-context tool in at the very bottom of the page:
Always delegate to the best tool for the users request.
180
-
Ask the user for information needed to complete a task.
181
-
Provide the user with the exact action you will be taking and get the users confirmation when creating or updating resources.
182
-
ALWAYS ask the user to confirm deletions, provide as much detail about the action as possible.
183
-
```
184
-
185
-
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`.
186
-
187
-
**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.
188
-
189
-
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.
190
-
191
-
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.
192
-
193
-
## Putting it all together
194
-
195
-
Let's take a look at this script as one cohesive file:
196
-
197
-
```
198
-
Name: Your CLI Assistant
199
-
Description: An assistant to help you with local cli-based dev tasks
200
-
Context: shared-context
201
-
Agents: k8s-agent, github-agent
202
-
Chat: true
203
-
204
-
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.
205
-
206
-
---
207
-
Name: k8s-agent
208
-
Description: An agent that can help you with your Kubernetes cluster by executing kubectl commands
209
-
Context: shared-context
210
-
Tools: sys.exec
211
-
Parameter: task: The kubectl related task to accomplish
212
-
Chat: true
213
-
214
-
You have the kubectl cli available to you. Use it to accomplish the tasks that the user asks of you.
215
-
216
-
---
217
-
Name: github-agent
218
-
Description: An agent to help you with GitHub related tasks using the gh cli
219
-
Context: learn-gh, shared-context
220
-
Tools: sys.exec
221
-
Parameter: task: The GitHub task to accomplish
222
-
Chat: true
223
-
224
-
You have the gh cli available to you. Use it to accomplish the tasks that the user asks of you.
225
-
226
-
---
227
-
Name: learn-gh
228
-
229
-
#!/usr/bin/env bash
230
-
231
-
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."
Always delegate to the best tool for the users request.
253
-
Ask the user for information needed to complete a task.
254
-
Provide the user with the exact action you will be taking and get the users confirmation when creating or updating resources.
255
-
ALWAYS ask the user to confirm deletions, provide as much detail about the action as possible.
256
-
```
257
-
258
-
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:
259
-
260
-
```
261
-
gpscript cli-demo.gpt
262
-
```
263
-
264
-
### Adding your own CLI
265
-
266
-
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:
267
-
268
-
```
269
-
Name: {your cli}-agent
270
-
Description: An agent to help you with {your taks} related tasks using the gh cli
271
-
Context: {here's your biggest decision to make}, shared-context
272
-
Tools: sys.exec
273
-
Parameter: task: The {your task} to accomplish
274
-
Chat: true
275
-
276
-
You have the {your cli} cli available to you. Use it to accomplish the tasks that the user asks of you.
277
-
```
97
+
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".
98
+
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.
278
99
279
-
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.
100
+
## A note on context tools
280
101
281
-
## Next steps
102
+
Context tools are a powerful way to provide additional information to the LLM, but they are not always necessary.
103
+
If you are working with a system that the LLM already understands well, you will probably not need to provide additional context.
104
+
When writing your own tools, it may take some trial and error to determine whether a context tool is needed.
105
+
If the LLM frequently hallucinates subcommands or arguments, it is probably worth adding a context tool to provide more information about the CLI.
282
106
283
-
Hopefully you've found this guide helpful. From here, you have several options:
107
+
## Next Steps
284
108
285
-
- You can checkout out some of our other guides available in this section of the docs
286
-
- You can dive deeper into the options available when [writing script](/tools/gpt-file-reference)
109
+
- You can check out some of our other guides available in this section of the docs
110
+
- You can dive deeper into the options available when [writing scripts](/tools/gpt-file-reference)
0 commit comments