Pause a Tool Execution

Learn how to pause the execution of a tool and process the data

Prompt

When a tool’s calculation is simple, you can simply return its value to the Latitude SDK, as shown in the prompt with tools example. However, for more complex calculations, you can pause the execution of the tool, process the data asynchronously, and then respond with the result in the same conversation.

example

---
provider: Latitude
model: gpt-4o-mini
tools:
  - generate_travel_itinerary:
      description: Generates a personalized multi-day travel itinerary for a user based on their preferences, location, and available dates. This requires multiple external data sources and can take some time, so it runs as a background job.
      parameters:
        type: object
        additionalProperties: false
        required: ['destination', 'start_date', 'end_date', 'preferences', 'user_id']
        properties:
          destination:
            type: string
            description: Name of the travel destination (city, country, etc.)
          start_date:
            type: string
            description: Start date of the trip (YYYY-MM-DD)
          end_date:
            type: string
            description: End date of the trip (YYYY-MM-DD)
          preferences:
            type: array
            items:
              type: string
            description: List of user interests (e.g., museums, food, outdoor, art)
          user_id:
            type: string
            description: Unique identifier for the requesting user
---

Plan my trip to {{ destination }} from {{ start_date }} to {{ end_date }}.
I like {{ preferences.join(', ') }}.

# Example response to user
Great! I’m planning your trip to {{ destination }} with your preferences.
This may take a few minutes, as I’ll be gathering up-to-date info from multiple sources. I’ll notify you as soon as your custom itinerary is ready!

Code

In this example, you can see how itinerary creation is requested by the AI. The execution is paused, the data is stored (in memory, though you could also store it in your database or Redis), and then the tool execution is resumed with the calculated itinerary.

Typescript

import { Latitude } from '@latitude-data/sdk'
import { Message, MessageRole } from 'promptl-ai'

// You can type the tools you are using
type Tools = {
  generate_travel_itinerary: {
    location: string
    start_date: string
    end_date: string
    preferences: string
  }
}

type ItineraryRequested = {
  data: {
    location: string
    start_date: string
    end_date: string
    preferences: string
  }
  toolId: string
  toolName: string
  conversationUuid: string
  previousMessages: Message[]
}

let toolRequested: ItineraryRequested | undefined

function enqueueJobToProcessItinerary(itinerary: ItineraryRequested) {
  toolRequested = itinerary
}

function computeTravelItinerary(itinerary: ItineraryRequested) {
  return {
    location: itinerary.data.location,
    start_date: itinerary.data.start_date,
    end_date: itinerary.data.end_date,
    preferences: itinerary.data.preferences,
    recomendations: [
      'Visit the Sagrada Familia',
      'Explore Park Güell',
      'Take a stroll down La Rambla',
      'Relax at Barceloneta Beach',
      'Enjoy tapas at a local restaurant',
      'Visit the Picasso Museum',
    ],
  }
}

async function run() {
  const sdk = new Latitude(process.env.LATITUDE_API_KEY, {
    projectId: Number(process.env.PROJECT_ID),
    versionUuid: 'live',
  })

  await sdk.prompts.run<Tools>('pause-tools/example', {
    parameters: {
      destination: 'Barcelona',
      start_date: '2025-06-02',
      end_date: '2025-06-10',
      preferences: 'museums, parks, and local cuisine',
    },
    tools: {
      generate_travel_itinerary: async (
        data,
        { messages, conversationUuid, toolId, toolName, pauseExecution },
      ) => {
        enqueueJobToProcessItinerary({
          data,
          toolId,
          toolName,
          conversationUuid,
          previousMessages: messages,
        })

        // You are not returning the result now because the computation
        // is heavy and you want to pause the execution
        return pauseExecution()
      },
    },
  })

  // Imagine this is your backend processing the job
  if (toolRequested) {
    const result = await sdk.prompts.chat(toolRequested.conversationUuid, [
      {
        role: MessageRole.tool,
        content: [
          {
            type: 'tool-result',
            toolName: toolRequested.toolName,
            toolCallId: toolRequested.toolId,
            result: computeTravelItinerary(toolRequested),
          },
        ],
      },
    ])

    console.log('Recomendation', result.response.text)
  }
}

run()

import asyncio
import os
from devtools import pprint
from typing import Optional, Dict, Any

from latitude_sdk import (
    Latitude,
    LatitudeOptions,
    RunPromptOptions,
    OnToolCallDetails,
)
from promptl_ai import ToolMessage, ToolResultContent


ItineraryRequested = Dict[str, Any]
tool_requested: Optional[ItineraryRequested] = None


def enqueue_job_to_process_itinerary(itinerary: ItineraryRequested):
    global tool_requested
    tool_requested = itinerary


def compute_travel_itinerary(itinerary: ItineraryRequested) -> Dict[str, Any]:
    data = itinerary["data"]
    return {
        "location": data["location"],
        "start_date": data["start_date"],
        "end_date": data["end_date"],
        "preferences": data.get("preferences"),
        "recommendations": [
            "Visit the Sagrada Familia",
            "Explore Park Güell",
            "Take a stroll down La Rambla",
            "Relax at Barceloneta Beach",
            "Enjoy tapas at a local restaurant",
            "Visit the Picasso Museum",
        ],
    }


async def generate_travel_itinerary(arguments: dict[str, Any], details: OnToolCallDetails) -> str:
    pprint(details)
    enqueue_job_to_process_itinerary(
        {
            "data": {
                "location": arguments.get("location", "Barcelona"),
                "start_date": arguments.get("start_date"),
                "end_date": arguments.get("end_date"),
                "preferences": arguments.get("preferences"),
            },
            "tool_id": details.id,
            "tool_name": details.name,
            "conversationUuid": details.conversation_uuid,
        }
    )

    return details.pause_execution()


async def run():
    api_key = os.getenv("LATITUDE_API_KEY")
    sdk_options = LatitudeOptions(
        project_id=int(os.getenv("PROJECT_ID")),
        version_uuid="live",
    )

    sdk = Latitude(api_key, sdk_options)
    await sdk.prompts.run(
        "pause-tools/example",
        RunPromptOptions(
            parameters={
                "destination": "Barcelona",
                "start_date": "2025-06-02",
                "end_date": "2025-06-10",
                "preferences": "museums, parks, and local cuisine",
            },
            tools={"generate_travel_itinerary": generate_travel_itinerary},
        ),
    )

    if tool_requested is None:
        print("No tool requested.")
        return

    # Imagine this is your backend processing the job asynchronously.
    result = await sdk.prompts.chat(
        tool_requested["conversationUuid"],
        [
            ToolMessage(
                content=[
                    ToolResultContent(
                        id=tool_requested["tool_id"],
                        name=tool_requested["tool_name"],
                        result=compute_travel_itinerary(tool_requested),
                        is_error=False,
                    ),
                ],
            )
        ],
    )

    pprint(result.response.text)


asyncio.run(run())