---
title: "Connect Sesame to AI Agents: Sync Project Time and Task Tracking"
slug: connect-sesame-to-ai-agents-sync-project-time-and-task-tracking
date: 2026-10-13
author: Yuvraj Muley
categories: ["AI & Agents"]
excerpt: "Learn how to natively connect Sesame to AI agents using Truto. Build autonomous workflows for project time tracking, HR ops, and employee management."
tldr: "Connect Sesame to AI agents using Truto's /tools API. This guide covers bypassing Sesame API quirks, binding normalized tools to LangChain or Vercel AI SDK, and building autonomous HR workflows."
canonical: https://truto.one/blog/connect-sesame-to-ai-agents-sync-project-time-and-task-tracking/
---

# Connect Sesame to AI Agents: Sync Project Time and Task Tracking


You want to connect Sesame to an AI agent so your system can autonomously log project time, orchestrate shift planners, handle time-off requests, and sync employee directories. Here is exactly how to do it using Truto's `/tools` endpoint and SDK, bypassing the need to build and maintain a custom Sesame integration from scratch.

Building an AI agent that safely interacts with human resources and time-tracking systems requires precision. When an LLM executes a tool call to clock an employee out, it cannot afford to hallucinate API payloads or guess at required parameters. If your team uses ChatGPT, check out our guide on [connecting Sesame to ChatGPT](https://truto.one/connect-sesame-to-chatgpt-manage-personnel-and-attendance/), or if you are building on Anthropic's models, read our guide on [connecting Sesame to Claude](https://truto.one/connect-sesame-to-claude-automate-contracts-and-payroll-data/). For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them directly to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for Sesame, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex time-tracking workflows. For a broader look at this design pattern, read our research on [Architecting AI Agents: LangGraph, LangChain, and the SaaS Integration Bottleneck](https://truto.one/architecting-ai-agents-langgraph-langchain-and-the-saas-integration-bottleneck/).

## The Engineering Reality of the Sesame API

Giving an LLM access to external HR data sounds simple in a prototype. You write a Node.js function that makes a fetch request and wrap it in a tool decorator. In production against complex operational systems like Sesame, this approach collapses quickly. 

If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code instead of improving your model's reasoning. Sesame has several specific API characteristics that break standard REST assumptions and confuse LLMs.

### The Implicit Company ID Dependency

In many modern APIs, the authentication token implicitly scopes all requests to a specific tenant or workspace. Sesame operates slightly differently for write operations. 

While read operations are scoped securely, many critical write endpoints - such as creating an employee (`employees.create`), creating an office (`offices.create`), or creating a project (`projects.create`) - strictly require a `companyId` in the JSON payload. This ID is not guessable, nor is it provided in the standard OAuth callback. To get it, the integration must first call the `/core/v3/info` endpoint (which Truto maps to `list_all_sesame_info`) to extract the company ID that owns the token. If you pass raw Sesame endpoints to an LLM, the model will frequently attempt to create records without this ID, resulting in persistent validation errors.

### Silent Overwrites in Time Tracking

When an LLM attempts to resolve a scheduling conflict, it relies on API errors to guide its behavior. Sesame's `create_a_sesame_work_entry` endpoint handles conflicts in a highly unusual way that can derail autonomous agents.

If you attempt to create a work entry (a clock-in/clock-out record) that overlaps with an existing entry for that employee, Sesame does not reject the request with an HTTP 409 Conflict. Instead, it accepts the request and silently overwrites the existing data. Fully covered entries are deleted, partial overlaps are trimmed, and containing entries are split into multiple records - all without reporting these changes in the response body. 

An agent executing a raw API call will assume the schedule is clean, unaware that it just destructively modified previous timesheets. Safe interaction requires abstracting this endpoint so the agent first queries existing entries to check for overlaps before attempting a write.

### Fragmented API Versions and Pagination

Sesame's API surface is actively evolving, meaning an integration must span multiple API versions concurrently. Organizational endpoints (like entity groups) exist on the V3 API, while skill tracking and employee managers reside on the V4 API. 

These versions carry different structural expectations. Truto abstracts this fragmentation by normalizing all Sesame methods into standardized Proxy APIs. Truto handles the pagination (standardizing page/limit parameters to 100 records per page) and unifies the response shapes. Your agent interacts with a stable, predictable tool layer instead of juggling versioned route paths.

## Hero Tools for Sesame Agents

Exposing an entire API surface to an LLM is a recipe for hallucination. Instead, you should provide a curated subset of high-leverage tools. A [unified tool layer](https://truto.one/best-unified-api-for-llm-function-calling-ai-agent-tools-2026/) collapses API complexity behind stable function names and deterministic JSON schemas.

Here are the most critical tools to bind to your Sesame agent.

### `list_all_sesame_info`

As mentioned in the engineering reality section, this tool is the mandatory starting point for many workflows. It retrieves the core company profile associated with the current API token. Agents must use this tool to discover the `companyId` before attempting to provision new employees, offices, or projects.

> "Fetch the current company information to get the company ID, we will need it to provision the new engineering office."

### `list_all_sesame_employees`

This is the primary lookup tool for human resources workflows. It allows the agent to search the employee directory, filtering by email, national ID (DNI), or department IDs. Because Truto handles the pagination, the agent can safely request employee lists without managing cursor state.

> "Find the employee record for jane.doe@example.com so we can check her current project assignments."

### `create_a_sesame_project_time_entry`

This tool enables the agent to log past work against specific projects. It requires the employee ID and the start time (`timeEntryIn`), and accepts optional tags, comments, and end times. This is vital for AI assistants that help developers or field workers log their daily activities via natural language.

> "Log a project time entry for John Smith on the 'Website Redesign' project. Start time was 9:00 AM today and end time was 1:00 PM. Add a comment saying 'Frontend CSS updates'."

### `create_a_sesame_time_entries_start` and `create_a_sesame_time_entries_stop`

Unlike the retrospective project time entry tool, these tools are for real-time clock operations. They allow an agent to act as a virtual punch clock, starting a live timer for an employee on a specific project right now, and stopping it later.

> "Clock me into the 'Q3 Financial Audit' project right now."

### `list_all_sesame_project_planned_tasks`

An agent needs to know what an employee is scheduled to do before it can intelligently log their time or update their status. This tool fetches planned tasks, allowing filtering by project or description, returning the expected start and end times for the work.

> "What tasks are planned for the 'Server Migration' project this week?"

### `create_a_sesame_absence_day_off_request`

This tool handles the creation of leave requests (sick days, personal time, etc.). It requires the employee ID, the absence type ID, and the specific days off. It places the request into a pending state for a human manager (or another automated process) to approve.

> "Submit an absence request for employee ID 4452 for tomorrow due to illness. Use the standard sick leave absence type."

To view the complete inventory of available tools and their exact JSON schema definitions, visit the [Truto Sesame Integration page](https://truto.one/integrations/detail/sesame).

## Building [Multi-Step Workflows](https://truto.one/how-to-handle-long-running-saas-api-tasks-in-ai-agent-tool-calling-workflows/)

To build resilient AI agents, you need a programmatic way to fetch these tools and bind them to your LLM. Truto provides a `/tools` endpoint that outputs the exact JSON schemas required by major agent frameworks.

By using the `TrutoToolManager` (part of the `truto-langchainjs-toolset`), you can pull these schemas dynamically. This ensures that if you update a tool description in the Truto UI to improve the LLM's prompting, the agent inherits the update immediately without a code deployment.

### Managing State and Rate Limits

One critical architectural constraint to understand: **Truto does not retry, throttle, or apply backoff on rate limit errors (see our guide on [handling API rate limits and retries](https://truto.one/best-practices-for-handling-api-rate-limits-and-retries-across-multiple-third-party-apis/)).** 

When the upstream Sesame API returns an HTTP 429 Too Many Requests, Truto passes that error directly back to the caller. However, Truto normalizes the upstream rate limit information into standard IETF headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`). 

It is entirely the responsibility of your agent execution loop to inspect these headers and pause execution. If you fail to implement backoff, your agent will blindly fire tool calls into a 429 wall, crashing the workflow.

```mermaid
sequenceDiagram
  participant App as Agent Framework
  participant Truto as Truto API
  participant Sesame as Sesame API
  
  App->>Truto: GET /integrated-account/<id>/tools
  Truto-->>App: Returns JSON tool schemas
  App->>App: .bindTools(sesameTools)
  App->>Truto: POST /proxy/sesame/time-entries/start
  Truto->>Sesame: Formatted REST call (Start Timer)
  Sesame-->>Truto: HTTP 429 Too Many Requests
  Truto-->>App: HTTP 429 + ratelimit-* headers
  App->>App: Pause execution based on ratelimit-reset
  App->>Truto: Retry POST /proxy/sesame/time-entries/start
  Truto->>Sesame: Formatted REST call
  Sesame-->>Truto: HTTP 200 OK
  Truto-->>App: HTTP 200 Success
```

### Example: Binding Sesame Tools in TypeScript

Here is how you fetch the Sesame tools and bind them to a LangChain agent, complete with the setup required to handle execution safely.

```typescript
import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { TrutoToolManager } from "truto-langchainjs-toolset";

async function runSesameAgent(integratedAccountId: string, userPrompt: string) {
  // 1. Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });

  // 2. Fetch Sesame tools dynamically via Truto
  const toolManager = new TrutoToolManager({
    trutoApiKey: process.env.TRUTO_API_KEY!,
    integratedAccountId: integratedAccountId,
  });
  
  // Filter to only include write methods and specific custom tools for safety
  const tools = await toolManager.getTools();

  // 3. Bind the tools to the LLM
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are a strict HR and Project Management assistant. Always verify employee IDs before clocking time or requesting leave."],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);

  const agent = createToolCallingAgent({
    llm,
    tools,
    prompt,
  });

  const agentExecutor = new AgentExecutor({
    agent,
    tools,
    // Frameworks like LangChain allow you to handle tool errors.
    // In production, you must implement logic here to catch 429s 
    // and read the ratelimit-reset header from Truto.
    handleParsingErrors: true, 
    maxIterations: 10,
  });

  // 4. Execute the workflow
  const result = await agentExecutor.invoke({
    input: userPrompt,
  });

  console.log(result.output);
}
```

## Workflows in Action

Let's look at how an AI agent actually utilizes these tools in the real world to solve complex operational problems. 

### Scenario 1: The Project Manager Bot

Field service and software engineering teams are notorious for forgetting to log their time against specific project codes, resulting in inaccurate client billing. A project manager persona can interact with an AI Slack bot to fix timesheets retroactively.

> "Jane Doe forgot to clock out of the 'Website Redesign' project yesterday. She started at 9 AM and finished at 2 PM. Please log this time for her."

**Step-by-step execution:**
1.  **Call `list_all_sesame_employees`**: The agent searches for "Jane Doe" to resolve her natural language name into a strict Sesame `employeeId`.
2.  **Call `list_all_sesame_projects`**: The agent searches for "Website Redesign" to resolve the string into a valid `projectId`.
3.  **Call `list_all_sesame_project_time_entries`**: The agent queries yesterday's entries for Jane to ensure there are no overlapping timesheets that would trigger Sesame's silent overwrite behavior.
4.  **Call `create_a_sesame_project_time_entry`**: The agent executes the write operation, passing the `employeeId`, `projectId`, and the calculated ISO-8601 timestamps for 9:00 AM and 2:00 PM yesterday.

**Result:** The agent replies, *"I have successfully logged 5 hours for Jane Doe on the Website Redesign project for yesterday. No scheduling conflicts were found."*

### Scenario 2: The Automated Leave Coordinator

When an employee calls in sick, the resulting administrative work spans multiple systems. An AI agent can handle the intake, verify planned tasks, and log the absence in one motion.

```mermaid
graph TD
  A["User: Mark John Smith sick today<br>and clear his schedule."] --> B["Agent: list_all_sesame_employees"]
  B --> C["Agent: list_all_sesame_absence_types"]
  C --> D["Agent: create_a_sesame_absence_day_off_request"]
  D --> E["Agent: list_all_sesame_project_planned_tasks"]
  E --> F{"Has tasks today?"}
  F -->|"Yes"| G["Agent: delete_a_sesame_project_planned_task_by_id"]
  F -->|"No"| H["Process complete"]
  G --> H
```

> "John Smith called in sick today. Please submit a sick leave request for him and check if he was assigned to any planned project tasks today. If he was, remove him from those tasks so the PM knows."

**Step-by-step execution:**
1.  **Call `list_all_sesame_employees`**: The agent retrieves John Smith's `employeeId`.
2.  **Call `list_all_sesame_absence_types`**: The agent retrieves the catalog of absence types to find the UUID corresponding to "Sick Leave".
3.  **Call `create_a_sesame_absence_day_off_request`**: The agent submits the request for today's date using the resolved employee and absence IDs.
4.  **Call `list_all_sesame_project_planned_tasks`**: The agent queries tasks assigned to John Smith for the current date.
5.  **Call `delete_a_sesame_project_planned_tasks_assignation_by_id`**: If the agent finds tasks, it loops through the assignation IDs and removes John from the schedule, freeing up the work.

**Result:** The agent replies, *"I have submitted a sick leave request for John Smith for today. I found he was scheduled for the 'Database Migration' task; I have removed his assignment so the project manager is aware he is unavailable."*

## Moving Beyond Generic Integrations

Connecting an AI agent to Sesame is not about writing HTTP wrappers; it is about providing the LLM with a highly structured, restricted vocabulary of actions that map to real business operations. By using Truto's `/tools` endpoint, you remove the burden of managing API schemas, pagination, and structural drift, allowing you to focus purely on prompt engineering and workflow orchestration.

Remember that while Truto handles the schema normalization, the engineering fundamentals of interacting with a production system - particularly handling IETF rate limits and verifying state before executing destructive writes - remain your responsibility. Treat your agent like a junior developer: give it clear tools, enforce strict validation, and watch it automate your most tedious operational overhead.

> Want to give your AI agents safe, normalized access to Sesame and 100+ other SaaS applications without writing integration code? Book a demo with our engineering team today.
>
> [Talk to us](https://truto.one/book-a-demo/)