Connect Hourtick to AI Agents: Delegate Work and Audit Agent Costs

You want to connect Hourtick to an AI agent so your system can autonomously delegate tasks, audit AI provider costs, reconcile timesheets, and execute bulk operational updates. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom Hourtick integration from scratch.

Hourtick is uniquely positioned as a platform that tracks both human time and AI agent costs side-by-side. Giving a Large Language Model (LLM) read and write access to a system that manages financial ledgers, billing states, and complex task dependencies requires strict schema enforcement and error handling. If your team uses ChatGPT, check out our guide on connecting Hourtick to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting Hourtick to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for Hourtick, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex workflows. This approach is completely framework-agnostic and is NOT limited to MCP. For a broader look at the architecture behind this approach, refer to our research on architecting AI agents and the SaaS integration bottleneck.

Why a Unified Tool Layer Matters for Agent Safety

Before writing a line of integration code, decide what layer your agent talks to. This choice determines how safe your production system will be.

Direct API tools - mapping one tool directly to raw Hourtick endpoints without abstraction - force the LLM to memorize underlying HTTP mechanics. The model has to remember exactly how to format date strings, how to construct JSON patch operations, and how to handle pagination cursors. Every time the model has to guess the shape of a payload, you risk a hallucination that could corrupt time entries or misallocate agent budgets.

A unified tool layer abstracts these quirks behind stable schemas. Truto's Proxy APIs process raw Hourtick endpoints and convert them into standard CRUD tools with strict JSON schemas. When you provide these tools to an LLM, the model sees clearly defined parameters, predictable return objects, and bounded constraints.

This provides concrete engineering advantages:

1. Smaller attack surface for hallucination. Invalid arguments are rejected by the schema validation layer before they ever reach Hourtick.
2. Normalized pagination and authentication. Truto handles the cursor management and OAuth token lifecycles automatically, keeping the LLM's context window focused strictly on business logic.
3. Real-time updates. When you edit a tool description in the Truto UI to give the agent better instructions, the changes propagate to the /tools endpoint immediately.

The Engineering Reality of the Hourtick API

Giving an LLM access to external data sounds simple in a prototype. You write a fetch request and wrap it in a tool decorator. In production against complex operational systems like Hourtick, this approach collapses.

The Hourtick API introduces several specific integration challenges that break standard assumptions. If you hardcode these interactions into your agent without a robust handling strategy, you will spend your sprints writing defensive code instead of improving your model's reasoning capabilities.

Optimistic Concurrency Control (OCC) Conflicts

Hourtick relies heavily on versioning for data integrity. When updating sensitive records like time entries, commands, or notes, the API requires an expectedVersion parameter. This is Optimistic Concurrency Control in action.

If your agent fetches a note at version 4, formulates a plan, and then attempts an edit using version 4, but a human user updated the note to version 5 in the interim, Hourtick will reject the agent's request with a HTTP 409 Conflict. A naive agent implementation will simply crash or hallucinate a success state. Your agent loop must be explicitly designed to catch 409s, fetch the fresh state, re-evaluate the context, and retry the mutation.

Opaque and Untyped JSON Responses

LLMs rely on structured schemas to understand their environment. Unfortunately, several critical endpoints in the Hourtick API return what upstream documentation calls "opaque" or "untyped" JSON objects.

For example, endpoints managing timesheet submissions, approval lists, and agent delegation sessions often return varying shapes depending on the internal state machine. When an LLM receives an undocumented payload structure, its ability to reason about the next step degrades. By routing these calls through Truto's tool layer, you can enforce customized schemas and descriptions over these opaque responses, forcing the data into a shape the LLM can parse deterministically.

Atomic Bulk Mutation Failures

Hourtick provides powerful bulk update tools, such as hourtick_time_entries_bulk_update, which can patch up to 500 entries in a single request. However, this endpoint fails atomically. If an agent attempts to update 499 valid open time entries and 1 entry that is already marked as invoiced, approved, or running, the entire batch of 500 updates is rejected.

An LLM cannot reliably guess which entries are safe to mutate without checking the state of each one. You must provide the agent with tools to filter state prior to building the bulk request array, and instruct the agent via the tool description to never include locked records in a bulk patch payload.

Hourtick Hero Tools for AI Agents

To build effective Hourtick agents, you need to provide tools that map to high-leverage workflows. Exposing every CRUD endpoint overwhelms the context window. Instead, focus on the tools that enable delegation, auditing, and complex state mutations.

Here are the hero tools you should pull from Truto's /tools endpoint when building your agent.

1. create_a_hourtick_delegation

This tool allows an agent to delegate work to a specialized Hourtick AI agent by name. It can assign work against an existing task ID or create a new one. The Hourtick backend explicitly rejects unknown agents, full queues, or looping delegation chains (where Agent A delegates to B, which delegates to A).

"I need to run a deep analysis on the Q3 server logs attached to task #405. Delegate this to the 'LogAnalyzer' agent with instructions to extract all 502 error frequencies and update the task comments."

2. list_all_hourtick_agent_costs

If you deploy autonomous agents, you must audit their spending. This tool lists the Hourtick agent cost ledger for a specific period, returning rows detailing the USD cost, model used, input/output tokens, and the specific agentId. Admins can query across all agents to reconcile AI budgets.

"Pull the agent cost ledger for all AI operations between October 1st and October 15th. Group the total USD cost by model, and alert me if any single agent exceeded $50 in spending."

3. hourtick_time_entries_bulk_update

This tool enables sweeping operational changes, such as reassigning a batch of miscategorized time entries to a new project or updating notes across 100 records. Because of the atomic failure constraint, the agent must be instructed to verify record states beforehand.

"Find all time entries logged under the 'Legacy DB Migration' project for last week. Filter out any that are already invoiced, and bulk update the remaining entries to reassign them to the 'Cloud Infra V2' project."

4. create_a_hourtick_command

This is the primary state machine engine for time entries. It accepts an idempotent commandId to safely retry network failures, and handles starting, stopping, editing, or restoring timers. Edits and deletes mandate the expectedVersion parameter.

"Stop the currently running timer for the active user. Then, fetch version 3 of time entry #892 and edit the notes to append 'Completed initial code review'. Use command idempotency to ensure this doesn't double-post."

5. create_a_hourtick_work_item_dependency

Complex tasks require orchestration. This tool marks a work item as blocked by another (blocked_by) or blocking another (blocks). Hourtick enforces strict limits here - refusing dependency loops and capping blockers at 50 to prevent deadlocks.

"Take the 'Deploy Auth Service' task and mark it as blocked by 'Provision AWS RDS'. Ensure the dependency is recorded so the auth task cannot be moved to 'in progress' until the database is ready."

6. list_all_hourtick_reports_agent_outcomes

This tool generates data on how effectively AI agents are working. It returns agent time/cost, the human time spent before delivery (briefing), the human time spent after delivery (rework), and how often the agent's work was sent back for revision.

"Generate an agent outcomes report for last month. Identify which tasks required the most human rework time after the agent delivered its results, and list the agents responsible."