Tools - 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 more
- integrations: Built-in third-party tools that enhance the capabilities of your agents. Learn more
- api_calls: Direct API calls executed during workflow processes as tool calls. Learn more
Arguments: The inputs required by the tool.

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,

YAML

name: Example system tool task
description: List agents using system call

tools:
- name: list_agent_docs
  description: List all docs for the given agent
  type: system
  system:
    resource: agent
    subresource: doc
    operation: list

main:
- tool: list_agents
  arguments:
    limit: $ 10

Available system resources and operations

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:

YAML

name: Example integration tool task
description: Search wikipedia for a query

tools:
- name: wikipedia_search
  description: Search wikipedia for a query
  type: integration
  integration:
    provider: wikipedia

main:
- tool: wikipedia_search
  arguments:
    query: "Julep"

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:

YAML

name: Example api_call task
tools:
- type: api_call
  name: weather_api
  description: Get weather information for a location
  api_call:
    method: GET  # Required - HTTP method must be specified
    url: https://api.openweathermap.org/data/2.5/weather  # Required - URL must be specified
    params_schema:  # Define expected parameters
      type: object
      properties:
        q:
          type: string
          description: City name or coordinates
        units:
          type: string
          enum: [metric, imperial]
          description: Temperature units
        appid:
          type: string
          description: API key (loaded from metadata)
      required: [q, appid]

main:
- tool: weather_api
  arguments:
    params:
      q: $ _.location  # City from input
      units: "metric"
      appid: $ metadata.weather_api_key  # API key from metadata

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 Call Parameters

Arguments provided during the tool call can override the default method and url set in the api_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.

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:

YAML

name: Example system tool task
description: List agents using system call

tools:
  - name: send_notification
    description: Send a notification to the user
    type: function
    function:
      parameters:
        type: object
        properties:
          text:
            type: string
            description: Content of the notification

main:
  - tool: send_notification
    arguments:
      content: "hi"

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.

How User-Defined Functions Work

User-defined function tools in Julep work exactly like OpenAI’s function calling:

Definition: You define a function signature with name, description, and parameters schema
Model Decision: The LLM decides when to call your function based on the conversation context
Execution Pause: When Julep encounters a user-defined function call, it pauses execution and returns control to your client
Your Implementation: You implement the actual function logic in your client code
Result Return: You send the function results back to Julep to continue the workflow

Unlike integration, system, or api_call tools that execute automatically, function tools require manual handling by your client application.

Complete Example: Math Calculator with Function Tools

Here’s a comprehensive example showing how to implement and handle user-defined functions:

import yaml
import time
from julep import Julep

# Replace with your API key
API_KEY = "your-api-key"

client = Julep(api_key=API_KEY, environment="production")

# 1. Define your actual functions
def add_numbers(a, b):
    """Add two numbers together"""
    result = a + b
    print(f"Adding {a} + {b} = {result}")
    return result

def multiply_numbers(x, y):
    """Multiply two numbers"""
    result = x * y
    print(f"Multiplying {x} × {y} = {result}")
    return result

# Function dispatcher
FUNCTION_MAP = {
    "add_numbers": add_numbers,
    "multiply_numbers": multiply_numbers,
}

def execute_function(function_name, arguments):
    """Execute a function by name with arguments"""
    if function_name not in FUNCTION_MAP:
        raise ValueError(f"Unknown function: {function_name}")
    
    func = FUNCTION_MAP[function_name]
    return func(**arguments)

# 2. Create agent
agent = client.agents.create(
    name="Math Calculator",
    model="gpt-4o-mini",
    instructions="You are a calculator."
)

# 3. Define task with inline tools
task_def = yaml.safe_load("""
name: "function-tool-demo"

tools:
  - name: add_numbers
    type: function
    function:
      parameters:
        type: object
        properties:
          a:
            type: number
            description: First number
          b:
            type: number
            description: Second number
        required: ["a", "b"]

main:
  - tool: add_numbers
    arguments:
      a: 15
      b: 27
""")

# 4. Create and execute task
task = client.tasks.create(agent_id=agent.id, **task_def)
execution = client.executions.create(task_id=task.id, input={})

print(f"Execution: {execution.id}")

# 5. Monitor and handle function calls
for i in range(15):
    execution = client.executions.get(execution.id)
    print(f"Iteration {i+1}: Status = {execution.status}")
    
    if execution.status == "awaiting_input":
        # Execute the function based on task definition
        tool_name = task_def["main"][0]["tool"]  # "add_numbers"
        arguments = task_def["main"][0]["arguments"]  # {"a": 15, "b": 27}
        
        result = execute_function(tool_name, arguments)
        print(f"Result: {result}")
        
        # Use change_status to provide tool results
        client.executions.change_status(
            execution_id=execution.id,
            status="running",  # Resume execution
            input={"result": result} 
        )
        print("Sent result back to Julep")
        
    elif execution.status == "succeeded":
        print(f"Output: {execution.output}")
        break
        
    elif execution.status == "failed":
        print(f"Failed: {execution.error}")
        break
    
    time.sleep(3)

Key Points

Execution Status Monitoring: You must monitor the execution status and watch for awaiting_input
Manual Function Execution: When status is awaiting_input, execute your function locally
Resume with Results: Use change_status to resume execution with the function output
Alternative Tool Creation: You can also use client.agents.tools.create() to create tools before running the task

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:

# Create an agent
agent = client.agents.create(name="My Agent")

# Associate a tool with the agent
client.agents.tools.create(
        agent_id=AGENT_UUID,
        **{
            "name": "wikipedia_search",
            "type": "integration",
            "integration": {
              "provider": "wikipedia",
            } 
          },
    )

Check out the API reference here or SDK reference (Python here or JavaScript here for more details on different operations you can perform on agents.

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.

name: Example integration tool task
description: Search wikipedia for a query

tools:
- name: wikipedia_search
  description: Search wikipedia for a query
  type: integration
  integration:
    provider: wikipedia
main:
- tool: wikipedia_search
  arguments:
    query: "Julep"

Check out the API reference here or SDK reference (Python here or JavaScript here for more details on different operations you can perform on agents.

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 calling sessions.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
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
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

# Create agent with multiple tools
agent = client.agents.create(
    name="Research Assistant",
    tools=[
        {
            "name": "web_search",
            "type": "integration",
            "integration": {"provider": "brave"}
        },
        {
            "name": "wikipedia",
            "type": "integration",
            "integration": {"provider": "wikipedia"}
        }
    ]
)

# Chat with automatic tool execution
response = client.sessions.chat(
    session_id=session.id,
    messages=[
        {
            "role": "user",
            "content": "Tell me about the latest developments in quantum computing"
        }
    ],
    auto_run_tools=True  # Enable automatic execution
)

# Response includes information gathered from tools
print(response.choices[0].message.content)
# "Based on recent search results, here are the latest developments..."

Example: Task with Automatic Tools

YAML

name: Research and Summarize Task
tools:
  - name: web_search
    type: integration
    integration:
      provider: brave
  
  - name: save_research_summary
    description: Save the research summary as a document
    type: system
    system:
      resource: agent
      subresource: doc
      operation: create

main:
  # Step 1: Search with automatic tool execution
  - prompt:
      - role: user
        content: "Search for recent news about {{topic}} and create a comprehensive summary and save it as a document for agent {{agent.id}}"
    auto_run_tools: true  # Tools execute automatically
  
  # Step 2: The results from tools are already available
  - evaluate:
      summary: $ _.choices[0].message.content

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

Important: User-defined function tools (type: function) are never executed automatically, regardless of the auto_run_tools setting. They always pause execution and return control to the client for manual handling. This is a key difference from system, integration, and api_call tools.

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 preserved
recall_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

​Overview

​Components

​System Tool

​Integration Tool

​API Call Tool

​User-defined Function Tool

How User-Defined Functions Work

Complete Example: Math Calculator with Function Tools

Key Points

​How to Use Tools

​Create a Tool for an Agent

​Execute a Tool for a Task

​Relationship to Other Concepts

​Task

​Agent

​Automatic Tool Execution

​How Automatic Tool Execution Works

​Example: Session with Automatic Tools

​Example: Task with Automatic Tools

​When to Use Automatic Tool Execution

​Tool Execution Flow

​Managing Tool History

​Best Practices

Consistent Naming

Correct Usage

Type

​Next Steps

​See Examples

Overview

Components

System Tool

Integration Tool

API Call Tool

User-defined Function Tool

How to Use Tools

Create a Tool for an Agent

Execute a Tool for a Task

Relationship to Other Concepts

Task

Agent

Automatic Tool Execution

How Automatic Tool Execution Works

Example: Session with Automatic Tools

Example: Task with Automatic Tools

When to Use Automatic Tool Execution

Tool Execution Flow

Managing Tool History

Best Practices

Next Steps

See Examples