Connect Charlie to AI Agents: Automate HR Notes & Team Data

If your team uses ChatGPT, check out our guide on connecting Charlie to ChatGPT. Prefer Anthropic's ecosystem? We also have a dedicated walkthrough for connecting Charlie to Claude.

Building autonomous AI agents for HR operations requires more than basic data extraction. To execute workflows - like cross-referencing leave allowances, updating employee salaries, or documenting 1:1 notes - your agents need structured, reliable access to your core HRIS. Charlie holds exactly this context, but wiring its REST endpoints to an LLM framework requires abstracting away authentication, schema generation, and query parameters.

Truto solves this by exposing Charlie's API surface as LLM-ready tools. By calling Truto's /tools endpoint, your agents gain immediate access to Charlie's underlying data model with normalized schemas, allowing them to take autonomous action.

The Engineering Reality: Charlie API Quirks

Before wiring an agent directly to Charlie's API, it helps to understand the specific mechanical quirks of the platform. Building a resilient integration means handling these edge cases directly in your agent's execution loop.

1. Sort Code Formatting Constraints: When interacting with UK banking details via the list_all_charlie_bank_accounts or get_single_charlie_bank_account_by_id endpoints, Charlie requires the sort_code to be formatted strictly without punctuation. UK sort codes are almost universally presented to humans with hyphens (e.g., 20-00-00), meaning your agent needs explicit system prompting to strip these characters before making a write or query request.
2. Leave Request Unit Variances: Leave requests in Charlie utilize a split between amount and units. Depending on the company's configuration, an agent calculating overlapping time off might receive units as hours rather than days. Agents attempting to calculate exact remaining time off must cross-reference list_all_charlie_leave_requests against the employee's list_all_charlie_leave_allowances to ensure exact metric alignment.
3. Nested Note Permissions: Creating notes via create_a_charlie_team_member_note relies heavily on the overarching team_member_note_type. You cannot simply inject text onto an employee profile; the payload must respect the permissions structure defined by list_all_charlie_team_member_note_types, which dictates visibility across different roles. If your agent uses an incorrect note type ID, the payload will either fail silently or return a 403, depending on the authenticated credentials.

Building Multi-Step Workflows

To allow an agent to chain complex HR tasks - like checking a user's role and then creating a role-specific compliance note - you need to provide the LLM with deterministic tool definitions. Truto automates this by analyzing the methods defined on the integration resources and generating JSON Schema definitions that LangChain, CrewAI, and the Vercel AI SDK understand natively.

Using the TrutoToolManager from the truto-langchainjs-toolset, you can dynamically fetch Charlie tools and bind them to your agent.

Handling Rate Limits (Factual Note)

It is critical to note that Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Charlie API returns an HTTP 429, Truto passes that error directly back to the caller.

Truto normalizes upstream rate limit information into standardized HTTP headers per the IETF specification:

• ratelimit-limit
• ratelimit-remaining
• ratelimit-reset

Your application code or agent execution loop is fully responsible for intercepting the 429 status code, reading the ratelimit-reset header, and applying client-side retry and exponential backoff.

Code Example: LangChain Implementation

Here is how you initialize the tools, bind them to an LLM, and execute a query while catching standard execution errors.

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "truto-langchainjs-toolset";
 
// 1. Initialize the Tool Manager for the Charlie integrated account
const toolManager = new TrutoToolManager({
  trutoToken: process.env.TRUTO_API_KEY,
  integratedAccountId: "charlie_acct_883a9",
});
 
async function runHRAgent(prompt: string) {
  try {
    // 2. Fetch specific tools (e.g., read and custom tools)
    const tools = await toolManager.getTools({
      methods: ["read", "write"],
    });
 
    const llm = new ChatOpenAI({ 
      modelName: "gpt-4-turbo", 
      temperature: 0 
    });
 
    // 3. Bind tools to the LLM
    const agent = llm.bindTools(tools);
 
    // 4. Invoke the agent
    const response = await agent.invoke([
      { role: "user", content: prompt }
    ]);
 
    return response;
 
  } catch (error) {
    // Handle Rate Limits explicitly
    if (error.response?.status === 429) {
      const resetTime = error.response.headers.get("ratelimit-reset");
      console.warn(`Rate limited by Charlie. Backing off until: ${resetTime}`);
      // Implement your backoff queue or delay here
    }
    throw error;
  }
}

Essential Charlie Tools for AI Agents

By calling Truto's /tools endpoint, you instantly equip your agent with the following hero tools to manipulate HR operations.

list_all_charlie_team_members

Fetches an array of team member objects, providing the essential user directory. It returns profile details including id, first_name, last_name, work_email, job_title, and employment_status.

• Usage Notes: Use this tool first when identifying a user dynamically by email or name to retrieve their internal id, which is required for subsequent lookups.
• Example Prompt: "List all active engineering team members and find the internal ID for John Doe."

list_all_charlie_leave_allowances

Retrieves the time-off balances across the organization or for specific users. Returns crucial fields like allowance_in_days, days_used, remaining_allowance_in_days, period_start, and period_end.

• Usage Notes: Always check the period_end to ensure the agent is calculating metrics for the correct fiscal or calendar year.
• Example Prompt: "Check how many remaining holiday days Sarah has left before December 31st."

create_a_charlie_team_member_note

Creates a new log entry on an employee's profile. Returns the created id, team_member_note_type, label, and content.

• Usage Notes: Requires the user id and a valid team_member_note_type. Ensure your agent queries note types first if creating a specific classification of note (e.g., disciplinary vs. 1:1 meeting).
• Example Prompt: "Log a new 1:1 performance review note for team member ID 8472 with the contents of our meeting transcript."

list_all_charlie_salaries

Extracts compensation data, returning team_member, job_title, pay_rate, pay_period, pay_frequency, pay_currency, and effective_date.

• Usage Notes: Highly sensitive. Ensure agent RBAC and scope filtering are applied if exposing this tool to end-users.
• Example Prompt: "Audit the salaries across the marketing department and summarize the currency breakdowns."

list_all_charlie_bank_accounts

Lists all bank accounts associated with the authenticated company. Returns the team_member ID, account_number, sort_code, and bank_name.

• Usage Notes: Remember that the sort_code is returned without punctuation. The agent must format this data if presenting it back to a human expecting standard UK hyphenation.
• Example Prompt: "Verify if team member ID 9932 has a registered bank account for the upcoming payroll run."

get_single_charlie_leave_request_by_id

Retrieves granular data about a specific time-off request. Returns approver, status, details, amount, units, request_type, and dates.

• Usage Notes: Useful for auditing rejected or pending leave requests dynamically during a conversational workflow.
• Example Prompt: "Get the status of leave request ID 1042 and tell me who the assigned approver is."

For the complete tool inventory and full schema details, visit the Charlie integration page.

Workflows in Action

Here are a few concrete examples of how an AI agent can execute domain-specific tasks in Charlie using these tools.

Scenario 1: Leave Approval Automation

An internal IT or HR bot helps managers triage incoming time-off requests by verifying balances.

"Check David's remaining leave allowance. If he has more than 5 days left, summarize his current pending leave requests."

Agent Execution Steps:

1. Calls list_all_charlie_team_members to search for "David" and extract his internal id.
2. Calls list_all_charlie_team_member_leave_allowance using David's id to check the remaining_allowance_in_days.
3. Evaluates the integer. Since it's greater than 5, the agent proceeds.
4. Calls list_all_charlie_team_member_leave_requests to pull pending requests, structuring the output for the manager.

Result: The manager gets a clean slack message outlining David's balance and his requested dates, ready for a 1-click approval.

Scenario 2: Employee Profile Auditing

An Ops agent runs a weekly diagnostic to ensure all recent hires have their banking data configured for payroll and logs a compliance note.

"Find the team member named Alice Smith. Check if her bank account is listed. If it is, log a compliance note on her profile saying 'Payroll details verified'."

Agent Execution Steps:

1. Calls list_all_charlie_team_members to resolve Alice Smith's internal id.
2. Calls list_all_charlie_bank_accounts and filters the response array for Alice's team_member ID.
3. Upon verifying the existence of account_number and sort_code, the agent calls list_all_charlie_team_member_note_types to find the ID for the "Compliance" note category.
4. Calls create_a_charlie_team_member_note passing Alice's ID, the Compliance Note Type ID, and the required content string.

Result: The payroll team knows Alice is ready for the cycle without manual CRM checking, and an immutable log exists on her profile.