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: documentation/docs/concepts/sessions.mdx
+16
Original file line number
Diff line number
Diff line change
@@ -38,6 +38,22 @@ When creating a session, you can leverage the following configuration options to
38
38
|`forward_tool_calls`| boolean | Whether to forward tool calls directly to the model |`false`|
39
39
|`recall_options`|[RecallOptions](#recall-options)| Options for recalling context or certain data during the session |`null`|
40
40
41
+
### Recall Options
42
+
43
+
When configuring a session, you can specify recall options to control how context or certain data is recalled during the session. Below are the available options:
The **System Template** is a specific system prompt written as a Jinja template that sets the foundational context and instructions for the agent within a session. It defines the background, directives, and any relevant information that the agent should consider when interacting with the user. For more details on Jinja templates, refer to the [Jinja documentation](https://jinja.palletsprojects.com/).
43
59
<Accordiontitle="Default System Template"icon="template">
Copy file name to clipboardExpand all lines: documentation/docs/concepts/tools.mdx
+245-15
Original file line number
Diff line number
Diff line change
@@ -6,50 +6,280 @@ icon: 'screwdriver-wrench'
6
6
7
7
## Overview
8
8
9
-
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
9
+
Agents can be given access to a number of "tools" -- any programmatic interface that a foundation model can "call" with a set of inputs to achieve a goal. For example, it might use a `web_search(query)` tool to search the Internet for some information.
10
+
11
+
Unlike agent frameworks, julep is a _backend_ that manages agent execution. Clients can interact with agents using our SDKs. julep takes care of executing tasks and running integrations.
10
12
11
13
## Components
12
14
13
-
### Name
15
+
Tools in Julep consist of three main components:
16
+
17
+
1.**Name**: A unique identifier for the tool.
18
+
2.**Type**: The category of the tool. In Julep, there are four types of tools:
19
+
-**User-defined `functions`**: Function signatures provided to the model, similar to OpenAI's function-calling. These require client handling, and the workflow pauses until the client executes the function and returns the results to Julep.
20
+
-**`system` tools**: Built-in tools for calling Julep APIs, such as triggering task execution or appending to a metadata field.
21
+
-**`integrations`**: Built-in third-party tools that enhance the capabilities of your agents.
22
+
-**`api_calls`**: Direct API calls executed during workflow processes as tool calls.
23
+
3.**Arguments**: The inputs required by the tool.
24
+
25
+
### Tool Types Definitions:
26
+
27
+
1.**User-defined `functions`**: These are function signatures that you can give the model to choose from, similar to how [openai]'s function-calling works. An example:
28
+
29
+
```yaml Task YAML
30
+
name: Example system tool task
31
+
description: List agents using system call
32
+
33
+
tools:
34
+
- name: send_notification
35
+
description: Send a notification to the user
36
+
type: function
37
+
function:
38
+
parameters:
39
+
type: object
40
+
properties:
41
+
text:
42
+
type: string
43
+
description: Content of the notification
44
+
45
+
main:
46
+
- tool: send_notification
47
+
arguments:
48
+
content: '"hi"'# <-- python expression
49
+
```
50
+
51
+
<Note>
52
+
Whenever julep encounters a user-defined function, it pauses, giving control back to the client and waits for the client to run the function call and give the results back to julep.
53
+
</Note>
54
+
55
+
2. **`system` tools**: Built-in tools that can be used to call the julep APIs themselves, like triggering a task execution, appending to a metadata field, etc.
56
+
57
+
`System`tools are built into the backend. They get executed automatically when needed. They do not require any action from the client-side. For example,
58
+
59
+
```yaml Task YAML
60
+
name: Example system tool task
61
+
description: List agents using system call
62
+
63
+
tools:
64
+
- name: list_agent_docs
65
+
description: List all docs for the given agent
66
+
type: system
67
+
system:
68
+
resource: agent
69
+
subresource: doc
70
+
operation: list
14
71
15
-
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
72
+
main:
73
+
- tool: list_agents
74
+
arguments:
75
+
limit: 10 # <-- python expression
76
+
```
16
77
17
-
### Type
78
+
<Accordion title="Available `system` resources and operations">
79
+
<Accordion title="Agent">
80
+
<ul>
81
+
<li><strong>list</strong>: List all agents.</li>
82
+
<li><strong>get</strong>: Get a single agent by id.</li>
83
+
<li><strong>create</strong>: Create a new agent.</li>
84
+
<li><strong>update</strong>: Update an existing agent.</li>
85
+
<li><strong>delete</strong>: Delete an existing agent.</li>
86
+
</ul>
87
+
</Accordion>
88
+
<Accordion title="User">
89
+
<ul>
90
+
<li><strong>list</strong>: List all users.</li>
91
+
<li><strong>get</strong>: Get a single user by id.</li>
92
+
<li><strong>create</strong>: Create a new user.</li>
93
+
<li><strong>update</strong>: Update an existing user.</li>
94
+
<li><strong>delete</strong>: Delete an existing user.</li>
95
+
</ul>
96
+
</Accordion>
97
+
<Accordion title="Session">
98
+
<ul>
99
+
<li><strong>list</strong>: List all sessions.</li>
100
+
<li><strong>get</strong>: Get a single session by id.</li>
101
+
<li><strong>create</strong>: Create a new session.</li>
102
+
<li><strong>update</strong>: Update an existing session.</li>
103
+
<li><strong>delete</strong>: Delete an existing session.</li>
104
+
<li><strong>chat</strong>: Chat with a session.</li>
105
+
<li><strong>history</strong>: Get the chat history with a session.</li>
106
+
</ul>
107
+
</Accordion>
108
+
<Accordion title="Task">
109
+
<ul>
110
+
<li><strong>list</strong>: List all tasks.</li>
111
+
<li><strong>get</strong>: Get a single task by id.</li>
112
+
<li><strong>create</strong>: Create a new task.</li>
113
+
<li><strong>update</strong>: Update an existing task.</li>
114
+
<li><strong>delete</strong>: Delete an existing task.</li>
115
+
</ul>
116
+
</Accordion>
117
+
<Accordion title="Doc (subresource for agent and user)">
118
+
<ul>
119
+
<li><strong>list</strong>: List all documents.</li>
120
+
<li><strong>create</strong>: Create a new document.</li>
121
+
<li><strong>delete</strong>: Delete an existing document.</li>
122
+
<li><strong>search</strong>: Search for documents.</li>
123
+
</ul>
124
+
</Accordion>
125
+
<Accordion title="Additional Operations">
126
+
<ul>
127
+
<li><strong>embed</strong>: Embed a resource (specific resources not specified in the provided code).</li>
128
+
<li><strong>change_status</strong>: Change the status of a resource (specific resources not specified in the provided code).</li>
129
+
<li><strong>chat</strong>: Chat with a resource (specific resources not specified in the provided code).</li>
130
+
<li><strong>history</strong>: Get the chat history with a resource (specific resources not specified in the provided code).</li>
131
+
<li><strong>create_or_update</strong>: Create a new resource or update an existing one (specific resources not specified in the provided code).</li>
132
+
</ul>
133
+
</Accordion>
134
+
</Accordion>
18
135
19
-
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
136
+
3. **`integrations`**: Julep comes with a number of built-in integrations (as described in the section below). `integration` tools are directly executed on the julep backend. Any additional parameters needed by them at runtime can be set in the agent/session/user's `metadata` fields.
20
137
21
-
### Arguments
138
+
An example of how to create a `integration` tool for an agent using the `wikipedia` integration:
22
139
23
-
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
140
+
```yaml Task YAML
141
+
name: Example integration tool task
142
+
description: Search wikipedia for a query
143
+
144
+
tools:
145
+
- name: wikipedia_search
146
+
description: Search wikipedia for a query
147
+
type: integration
148
+
integration:
149
+
provider: wikipedia
150
+
151
+
main:
152
+
- tool: wikipedia_search
153
+
arguments:
154
+
query: "'Julep'"
155
+
```
156
+
157
+
<Info>
158
+
Checkout the list of integrations that Julep supports [here](/docs/integrations).
159
+
</Info>
160
+
161
+
4. **Direct `api_calls`**: Julep can also directly make api calls during workflow executions as tool calls. Same as `integration`s, additional runtime parameters are loaded from metadata fields. For example,
162
+
163
+
```yaml Task YAML
164
+
name: Example api_call task
165
+
tools:
166
+
- type: api_call
167
+
name: hello
168
+
api_call:
169
+
method: GET
170
+
url: https://httpbin.org/get
171
+
172
+
main:
173
+
- tool: hello
174
+
arguments:
175
+
json:
176
+
test: _.input # <-- python expression
177
+
```
24
178
25
179
## How to Use Tools
26
180
27
181
### Create a Tool for an Agent
28
182
29
-
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
183
+
A tool can be created for an agent using the `client.agents.tools.create` method.
184
+
185
+
An example of how to create a `integration` tool for an agent using the `wikipedia` integration:
186
+
```python
187
+
# Create an agent
188
+
agent = client.agents.create(name="My Agent")
189
+
190
+
# Associate a tool with the agent
191
+
client.agents.tools.create(
192
+
agent_id=AGENT_UUID,
193
+
**{
194
+
"name": "wikipedia_search",
195
+
"type": "integration",
196
+
"integration": {
197
+
"provider": "wikipedia",
198
+
}
199
+
},
200
+
}
201
+
)
202
+
```
203
+
204
+
<Tip>
205
+
Check out the API reference [here](api-reference/agents/tools/create) or SDK reference (Python [here](/sdks/python/reference#Tools) or JavaScript [here](/sdks/nodejs/reference#Tools) for more details on different operations you can perform on agents.
206
+
</Tip>
30
207
31
208
### Execute a Tool for a Task
32
209
33
-
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
210
+
To create a tool for a task, you can use the `client.tasks.create` method and define the tool in that `task` definitions.
34
211
35
-
### All Configuration Options
212
+
<CodeGroup>
213
+
```yaml TAML
214
+
name: Example integration tool task
215
+
description: Search wikipedia for a query
36
216
37
-
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
217
+
tools:
218
+
- name: wikipedia_search
219
+
description: Search wikipedia for a query
220
+
type: integration
221
+
integration:
222
+
provider: wikipedia
223
+
main:
224
+
- tool: wikipedia_search
225
+
arguments:
226
+
query: "'Julep'"
227
+
```
228
+
229
+
```python Python
230
+
# Create a task
231
+
import yaml
232
+
task_def = yaml.safe_load(task_yaml)
233
+
task = client.tasks.create(
234
+
agent_id="agent_id",
235
+
**task_def
236
+
)
237
+
238
+
execution = client.executions.create(
239
+
task_id=task.id,
240
+
input={
241
+
"document_text": "This is a sample document"
242
+
}
243
+
)
244
+
```
245
+
</CodeGroup>
246
+
<Tip>
247
+
Check out the API reference [here](api-reference/agents/tools/create) or SDK reference (Python [here](/sdks/python/reference#Tools) or JavaScript [here](/sdks/nodejs/reference#Tools) for more details on different operations you can perform on agents.
248
+
</Tip>
38
249
39
250
## Relationship to Other Concepts
40
251
252
+
This section will help you understand how tools relate to other concepts in Julep.
253
+
41
254
### Task
42
255
43
-
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
256
+
When a tool is associated with a task, it is meant to be used only for that task. It is not associated with other tasks. An agent associated with that task will have access to that tool, but the same agent associated with another task will not have that access. This ensures that tools are used in a context-specific manner, providing precise functionality tailored to the task's requirements.
44
257
45
258
### Agent
46
259
47
-
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
260
+
When a tool is associated with an agent, it is meant to be used across all tasks associated with that agent. This allows for greater flexibility and reuse of tools, as the agent can leverage the same tool in multiple tasks. It also simplifies the management of tools, as they only need to be defined once for the agent and can then be utilized in various tasks.
48
261
49
262
## Best Practices
50
263
51
-
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
264
+
<CardGroup cols={3}>
265
+
<Card title="Consistent Naming" icon="tag">
266
+
<ul>
267
+
<li>**1. Naming Conventions**: Use clear and consistent naming conventions for tools to make them easily identifiable and understandable.</li>
268
+
</ul>
269
+
</Card>
270
+
<Card title="Correct Usage" icon="check-double">
271
+
<ul>
272
+
<li>**1. Correct Usage**: Ensure that tools are used correctly and in the appropriate context. This includes providing the necessary arguments and ensuring that the tools are executed as intended.</li>
273
+
</ul>
274
+
</Card>
275
+
<Card title="Type" icon="font">
276
+
<ul>
277
+
<li>**1. Type**: Ensure that the type is correct for the tool you are using. Checkout the Tool Types Definitions <a href="/docs/concepts/tools#tool-types-definitions">here</a> for further details.</li>
278
+
</ul>
279
+
</Card>
280
+
</CardGroup>
52
281
53
282
## Next Steps
54
283
55
-
-[Checkout the Integration](/docs/integrations) - Learn how to use executions in an integration
284
+
- [Checkout the Integration](/docs/integrations) - Learn how to use executions in an integration
285
+
- [Checkout the Tutorial](/docs/tutorials/tool-usage) - Learn how to use tools in a task
0 commit comments