Tools
Understanding tools in Julep
Overview
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.
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.
Components
Tools in Julep consist of three main components:
- Name: A unique identifier for the tool.
- Type: The category of the tool. In Julep, there are four types of tools:
- 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. Learn more system
tools: Built-in tools for calling Julep APIs, such as triggering task execution or appending to a metadata field. Learn moreintegrations
: Built-in third-party tools that enhance the capabilities of your agents. Learn moreapi_calls
: Direct API calls executed during workflow processes as tool calls. Learn more
- User-defined
- Arguments: The inputs required by the tool.
User-defined Function Tool
These are function signatures that you can give the model to choose from, similar to how [openai]‘s function-calling works. An example:
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.
System Tool
Built-in tools that can be used to call the julep APIs themselves, like triggering a task execution, appending to a metadata field, etc.
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,
Available system resources and operations
Available system resources and operations
Agent
Agent
- list: List all agents.
- get: Get a single agent by id.
- create: Create a new agent.
- update: Update an existing agent.
- delete: Delete an existing agent.
User
User
- list: List all users.
- get: Get a single user by id.
- create: Create a new user.
- update: Update an existing user.
- delete: Delete an existing user.
Session
Session
- list: List all sessions.
- get: Get a single session by id.
- create: Create a new session.
- update: Update an existing session.
- delete: Delete an existing session.
- chat: Chat with a session.
- history: Get the chat history with a session.
Task
Task
- list: List all tasks.
- get: Get a single task by id.
- create: Create a new task.
- update: Update an existing task.
- delete: Delete an existing task.
Doc (subresource for agent and user)
Doc (subresource for agent and user)
- list: List all documents.
- create: Create a new document.
- delete: Delete an existing document.
- search: Search for documents.
Additional Operations
Additional Operations
- embed: Embed a resource (specific resources not specified in the provided code).
- change_status: Change the status of a resource (specific resources not specified in the provided code).
- chat: Chat with a resource (specific resources not specified in the provided code).
- history: Get the chat history with a resource (specific resources not specified in the provided code).
- create_or_update: Create a new resource or update an existing one (specific resources not specified in the provided code).
Integration Tool
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
metadata
fields.
An example of how to create a integration
tool for an agent using the wikipedia
integration:
Checkout the list of integrations that Julep supports here.
API Call Tool
Julep can also directly make api_call
during workflow executions as tool calls. Similar to integration
tools, additional runtime parameters are loaded from metadata fields.
API call tools support params_schema
to define the expected parameters for the API call, enabling better validation and documentation:
The params_schema
follows JSON Schema format and helps:
- Document expected parameters for the API
- Enable LLMs to understand what parameters the tool accepts
- Provide validation for API calls
- Generate better tool descriptions for the model
Available API HTTP Methods
Available API HTTP Methods
- GET: Get a resource.
- POST: POST a resource.
- PUT: PUT a resource.
- DELETE: DELETE a resource.
- PATCH: PATCH a resource.
- HEAD: HEAD a resource.
- OPTIONS: OPTIONS a resource.
- CONNECT: CONNECT to a resource.
- TRACE: TRACE a resource.
Available API Call Parameters
Available API Call Parameters
- method: (Required) The HTTP method to use.
- url: (Required) The URL to call.
- params_schema: JSON Schema definition for API parameters, enabling validation and better LLM understanding.
- schema: The schema of the response.
- headers: The headers to send with the request.
- content: The content as base64 to send with the request.
- data: The data to send as form data.
- files: The data to send as files data.
- json: The JSON body to send with the request.
- cookies: The cookies to send with the request.
- params: The parameters to send with the request.
- follow_redirects: Follow redirects.
- timeout: The timeout for the request.
- Arguments provided during the tool call can override the default
method
andurl
set in theapi_call
configuration. - We utlize the python httpx library to make the api calls. Please refer to the httpx documentation for more details on the parameters.
How to Use Tools
Create a Tool for an Agent
A tool can be created for an agent using the client.agents.tools.create
method.
An example of how to create a integration
tool for an agent using the wikipedia
integration:
Execute a Tool for a Task
To create a tool for a task, you can use the client.tasks.create
method and define the tool in that task
definitions.
Relationship to Other Concepts
This section will help you understand how tools relate to other concepts in Julep.
Task
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.
Agent
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.
Automatic Tool Execution
Julep supports automatic tool execution, allowing agents to seamlessly use tools without manual intervention. This feature is controlled by the auto_run_tools
parameter.
How Automatic Tool Execution Works
-
In Sessions (Chat):
- Set
auto_run_tools=true
when callingsessions.chat()
- When the model decides to use a tool, Julep automatically:
- Executes the tool with the provided arguments
- Captures the tool’s output
- Sends the results back to the model
- Continues the conversation with the tool results
- All happens in a single API call - no manual intervention needed
- Set
-
In Tasks (Prompt Steps):
- Set
auto_run_tools: true
in the prompt step definition - During task execution, tools are automatically invoked when needed
- Results flow seamlessly into subsequent steps
- Set
-
Default Behavior (
auto_run_tools=false
):- Tool calls are returned in the response
- Your application must handle tool execution
- Results must be sent back in a follow-up message
Example: Session with Automatic Tools
Example: Task with Automatic Tools
When to Use Automatic Tool Execution
Use auto_run_tools=true
when:
- Building conversational agents that need real-time information
- Creating autonomous workflows in tasks
- You want a seamless, single-call interaction
- Tools are trusted and don’t require manual validation
Use auto_run_tools=false
when:
- You need to validate or modify tool inputs before execution
- Tool execution requires user confirmation
- You want to handle tool errors with custom logic
- Building applications with complex tool orchestration
Tool Execution Flow
Model Decision
The LLM analyzes the user’s request and decides if a tool is needed
Tool Call Generation
The model generates appropriate tool calls with arguments
Automatic Execution
With auto_run_tools=true: Julep executes the tool automatically With auto_run_tools=false: Tool calls are returned for manual handling
Result Processing
Tool results are fed back to the model or returned to the client
Response Generation
The model uses tool results to generate the final response
Managing Tool History
When using sessions.chat()
, the recall_tools
parameter controls whether tool interactions are saved in the conversation history:
recall_tools=true
(default): Tool calls and results are preservedrecall_tools=false
: Tool interactions are excluded from history
This helps maintain clean conversation logs while still benefiting from tool capabilities.
Best Practices
Consistent Naming
- 1. Naming Conventions: Use clear and consistent naming conventions for tools to make them easily identifiable and understandable.
Correct Usage
- 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.
Type
- 1. Type: Ensure that the type is correct for the tool you are using. Checkout the Tool Types Definitions here for further details.
Next Steps
- Checkout the Integration - Learn how to use executions in an integration
- Checkout the Tutorial - Learn how to use tools in a task