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
Copy file name to clipboardExpand all lines: docs/docs/03-tools/01-using.md
+21-5
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,17 @@
1
1
# Using Tools
2
-
In GPTScript, tools are used to extend the capabilities of a script. The idea behind them is that AI performs better when it has very specific instructions for a given task. Tools are a way to break-up the problem into smaller and more focused pieces where each tool is responsible for a specific task. A typical flow like this is to have a main script that imports a set of tools it can use to accomplish its goal.
2
+
3
+
In GPTScript, tools are used to extend the capabilities of a script.
4
+
The idea behind them is that AI performs better when it has very specific instructions for a given task.
5
+
Tools are a way to break up the problem into smaller and more focused pieces where each tool is responsible for a specific task.
6
+
A typical pattern is to have a main script that imports a set of tools it can use to accomplish its goal.
3
7
4
8
GPTScripts can utilize tools in one of three ways:
5
9
1. Built-in system tools
6
10
2. In-script tools
7
11
3. External tools
8
12
9
13
### System Tools
14
+
10
15
All GPTScripts have access to system tools, like `sys.read` and `sys.write`, that can be used without any additional configuration.
11
16
12
17
```yaml
@@ -16,11 +21,14 @@ Read all of the files in my current directory, do not recurse over any subdirect
16
21
```
17
22
18
23
System tools are a set of core tools that come packaged with GPTScript by default.
24
+
To see a list of the system tools, run `gptscript --list-tools`.
19
25
20
26
### In-Script Tools
21
-
Things get more interesting when you start to use custom tools.
22
27
23
-
The most basic example of this is an in-script tool that is defined in the same file as the main script. This is useful for breaking up a large script into smaller, more manageable pieces.
28
+
Things get more interesting when you start to write your own tools.
29
+
30
+
The most basic example of this is an in-script tool that is defined in the same file as the main script.
31
+
This is useful for breaking up a large script into smaller, more manageable pieces.
24
32
25
33
```yaml
26
34
tools: random-number
@@ -35,7 +43,9 @@ Select a number at random between 1 and 100 and return only the number.
35
43
```
36
44
37
45
### External Tools
38
-
You can refer to GPTScript tool files that are served on the web or stored locally. This is useful for sharing tools across multiple scripts or for using tools that are not part of the core GPTScript distribution.
46
+
47
+
You can refer to GPTScript tool files that are served on the web or stored locally.
48
+
This is useful for sharing tools across multiple scripts or for using tools that are not part of the core GPTScript distribution.
39
49
40
50
```yaml
41
51
tools: https://get.gptscript.ai/echo.gpt
@@ -51,9 +61,11 @@ tools: echo.gpt
51
61
Echo the phrase "Hello, World!".
52
62
```
53
63
54
-
You can also refer to OpenAPI definition files as though they were GPTScript tool files. GPTScript will treat each operation in the file as a separate tool. For more details, see [OpenAPI Tools](03-openapi.md).
64
+
You can also refer to OpenAPI definition files as though they were GPTScript tool files.
65
+
GPTScript will treat each operation in the file as a separate tool. For more details, see [OpenAPI Tools](03-openapi.md).
55
66
56
67
### Packaged Tools on GitHub
68
+
57
69
GPTScript tools can be packaged and shared on GitHub, and referred to by their GitHub URL. For example:
58
70
59
71
```yaml
@@ -64,5 +76,9 @@ Generate an image of a city skyline at night and write the resulting image to a
64
76
Take this image and write a description of it in the style of pirate.
65
77
```
66
78
79
+
:::important
80
+
The GitHub URL must not be prefixed with `http://` or `https://`.
81
+
:::
82
+
67
83
When this script is run, GPTScript will locally clone the referenced GitHub repos and run the tools referenced inside them.
68
84
For more info on how this works, see [Authoring Tools](02-authoring.md).
Copy file name to clipboardExpand all lines: docs/docs/03-tools/02-authoring.md
+19-8
Original file line number
Diff line number
Diff line change
@@ -2,11 +2,12 @@
2
2
3
3
You can author your own tools for your use or to share with others.
4
4
The process for authoring a tool is as simple as creating a `tool.gpt` file in the root directory of your project.
5
-
This file is itself a GPTScript that defines the tool's name, description, and what it should do.
5
+
This file is a GPTScript that defines the tool's name, description, and what it should do.
6
6
7
7
## Quickstart
8
8
9
-
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.
9
+
This is a guide for writing portable tools for GPTScript. The supported languages currently are Python, Node.js, and Go.
10
+
This guide uses Python, but you can see documentation for the other languages below.
GPTScript is designed to easily export and import tools. Doing this is currently based entirely around the use of GitHub repositories. You can export a tool by creating a GitHub repository and ensuring you have the `tool.gpt` file in the root of the repository. You can then import the tool into a GPTScript by specifying the URL of the repository in the `tools` section of the script. For example, we can leverage the `image-generation` tool by adding the following line to a GPTScript:
69
+
GPTScript is designed to easily export and import tools.
70
+
Doing this is currently based entirely around the use of GitHub repositories.
71
+
You can export a tool by creating a GitHub repository and ensuring you have the `tool.gpt` file in the root of the repository.
72
+
You can then import the tool into a GPTScript by specifying the URL of the repository in the `tools` section of the script.
73
+
For example, we can leverage the `image-generation` tool by adding the following line to a GPTScript:
GPTScript can execute any binary that you ask it to. However, it can also manage the installation of a language runtime and dependencies for you. Currently this is only supported for a few languages. Here are the supported languages and examples of tools written in those languages:
83
+
GPTScript can execute any binary that you ask it to.
84
+
However, it can also manage the installation of a language runtime and dependencies for you.
85
+
Currently, this is only supported for a few languages.
86
+
Here are the supported languages and examples of tools written in those languages:
@@ -84,10 +92,13 @@ GPTScript can execute any binary that you ask it to. However, it can also manage
84
92
|`Golang`|[Search](https://github.com/gptscript-ai/search) - Use various providers to search the internet |
85
93
86
94
87
-
###Automatic Documentation
95
+
## Automatic Documentation
88
96
89
-
Each GPTScript tool is self-documented using the `tool.gpt` file. You can automatically generate documentation for your tools by visiting `tools.gptscript.ai/<github repo url>`. This documentation site allows others to easily search and explore the tools that have been created.
97
+
Each GPTScript tool is self-documented using the `tool.gpt` file.
98
+
You can automatically generate documentation for your tools by visiting `https://tools.gptscript.ai/<github repo url>`.
99
+
This documentation site allows others to easily search and explore the tools that have been created.
90
100
91
-
You can add more information about how to use your tool by adding an `examples` directory to your repository and adding a collection of `.gpt` files that demonstrate how to use your tool. These examples will be automatically included in the documentation.
101
+
You can add more information about how to use your tool by adding an `examples` directory to your repository and adding a collection of `.gpt` files that demonstrate how to use your tool.
102
+
These examples will be automatically included in the documentation.
92
103
93
104
For more information and to explore existing tools, visit [tools.gptscript.ai](https://tools.gptscript.ai).
Continuing with the above example, this is how you can use it in a script:
28
28
29
29
```yaml
30
-
credentials: my-credential-tool.gpt
30
+
Credentials: my-credential-tool.gpt as myCred
31
31
32
32
#!/usr/bin/env bash
33
33
34
34
echo "The value of MY_ENV_VAR is $MY_ENV_VAR"
35
35
```
36
36
37
+
:::note
38
+
GPTScript accepts `Cred:`, `Creds:`, `Credential:`, and `Credentials:` as valid directives.
39
+
:::
40
+
37
41
When you run the script, GPTScript will call the credential provider tool first, set the environment variables from its
38
42
output, and then run the script body. The credential provider tool is called by GPTScript itself. GPTScript does not ask the
39
43
LLM about it or even tell the LLM about the tool.
40
44
41
45
If GPTScript has called the credential provider tool in the same context (more on that later), then it will use the stored
42
46
credential instead of fetching it again.
43
47
48
+
To delete the credential that just got stored, run `gptscript credential delete myCred`.
49
+
44
50
You can also specify multiple credential tools for the same script, but they must be on separate lines:
45
51
46
52
```yaml
47
-
credentials: credential-tool-1.gpt
48
-
credentials: credential-tool-2.gpt
53
+
Credentials: credential-tool-1.gpt
54
+
Credentials: credential-tool-2.gpt
49
55
50
56
(tool stuff here)
51
57
```
@@ -56,7 +62,7 @@ GPTScript also provides a generic credential tool (`github.com/gptscript-ai/cred
56
62
where you only need to set one environment variable. Here is an example of how to use it:
57
63
58
64
```yaml
59
-
credentials: github.com/gptscript-ai/credential as myCredentialName with MY_ENV_VAR as env and "this message will be displayed to the user" as message and key as field
65
+
Credentials: github.com/gptscript-ai/credential as myCredentialName with MY_ENV_VAR as env and "this message will be displayed to the user" as message and key as field
60
66
61
67
(tool stuff here)
62
68
```
@@ -66,24 +72,24 @@ the environment variable `MY_ENV_VAR` and stored in a credential called `myCrede
66
72
67
73
See [the repo](https://github.com/gptscript-ai/credential) for more information.
68
74
69
-
## Credential Tool Arguments
75
+
## Credential Tool Parameters
70
76
71
-
A credential tool may define arguments. Here is an example:
77
+
A credential tool may define parameters. Here is an example:
72
78
73
79
```yaml
74
-
name: my-credential-tool
75
-
args: env: the environment variable to set
76
-
args: val: the value to set it to
80
+
Name: my-credential-tool
81
+
Parameter: env: the environment variable to set
82
+
Parameter: val: the value to set it to
77
83
78
84
#!/usr/bin/env bash
79
85
80
86
echo "{\"env\":{\"$ENV\":\"$VAL\"}}"
81
87
```
82
88
83
-
When you reference this credential tool in another file, you can use syntax like this to set both arguments:
89
+
When you reference this credential tool in another file, you can use syntax like this to set both parameters:
84
90
85
91
```yaml
86
-
credential: my-credential-tool.gpt with MY_ENV_VAR as env and "my value" as val
92
+
Credential: my-credential-tool.gpt with MY_ENV_VAR as env and "my value" as val
87
93
88
94
(tool stuff here)
89
95
```
@@ -92,7 +98,7 @@ In this example, the tool's output would be `{"env":{"MY_ENV_VAR":"my value"}}`
92
98
93
99
## Storing Credentials
94
100
95
-
By default, credentials are automatically stored in the credential store. Read the [main credentials page](../02-credentials.md)
101
+
By default, credentials are automatically stored in the credential store. Read the [main credentials page](../06-credentials.md)
96
102
for more information about the credential store.
97
103
98
104
:::note
@@ -105,7 +111,7 @@ will not be stored in the credentials store.
105
111
When you reference a credential tool in your script, you can give it an alias using the `as` keyword like this:
106
112
107
113
```yaml
108
-
credentials: my-credential-tool.gpt as myAlias
114
+
Credentials: my-credential-tool.gpt as myAlias
109
115
110
116
(tool stuff here)
111
117
```
@@ -121,8 +127,7 @@ A credential context is basically a namespace for credentials. If you have multi
121
127
you can switch between them by defining them in different credential contexts. The default context is called `default`,
122
128
and this is used if none is specified.
123
129
124
-
You can set the credential context to use with the `--credential-context` flag when running GPTScript. For
125
-
example:
130
+
You can set the credential context to use with the `--credential-context` flag when running GPTScript. For example:
0 commit comments