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, or if you are building on Anthropic's models, read our guide on connecting Sesame to Claude. 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.

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

Building Multi-Step 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).

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.

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.

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.

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.