Connect JustSift to AI Agents: Query People and Dynamic Profile Data

You want to connect JustSift to an AI agent so your system can autonomously search people, query dynamic organizational profiles, and retrieve employee media. Here is exactly how to do it using Truto's /tools endpoint and SDK, bypassing the need to build and maintain a custom JustSift integration from scratch.

Giving a Large Language Model (LLM) read and write access to your enterprise directories is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on connecting JustSift to ChatGPT, or if you are building on Anthropic's models, read our guide on connecting JustSift 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 JustSift, bind them natively to an LLM using frameworks like LangChain, LangGraph, CrewAI, or the Vercel AI SDK, and execute complex people-ops workflows. For a deeper 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, you must decide what layer your agent talks to. This choice determines how safe your production system will be.

Direct API tools (one tool per raw JustSift endpoint) look convenient in a prototype, but they push provider quirks directly into the LLM's context window. The model has to remember that JustSift requires specific filter shapes, that pagination relies on specific cursor parameters, and that profile fields are dynamic per organization. Every one of those quirks is a hallucination waiting to happen.

Truto operates differently. Every integration on Truto is essentially a comprehensive JSON object that represents how an underlying product's API behaves. Integrations have a concept of Resources, which map to the endpoints on the underlying product's API. Truto then defines Methods on these resources (like List, Get, Create, Update, Delete) to create Proxy APIs.

These Proxy APIs are what Truto provides to your AI agents via the /tools endpoint. Truto handles all pagination, authentication, and query parameter processing, returning data in a predictable format. Your agent simply sees clean, descriptive tool names like get_single_just_sift_person_by_id. This gives you three concrete safety wins:

1. Smaller attack surface for hallucination. The LLM only ever chooses from a stable list of function names with predictable inputs.
2. Deterministic input validation. Every tool has a strict JSON schema. Invalid arguments are rejected before they hit JustSift.
3. Abstracted authentication. The agent never sees bearer tokens or OAuth credentials. Truto's infrastructure handles the token lifecycle securely.

The Engineering Reality of the JustSift API

Giving an LLM access to external data sounds simple until you hit production. Hashicorp, Salesforce, and JustSift all introduce specific integration challenges that break standard REST assumptions. If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code instead of improving your model's reasoning.

Here are the specific engineering realities of the JustSift API that will break naive agent implementations.

The Dynamic Profile Schema Trap

Standard LLMs are trained to expect flat, intuitive, and static JSON objects. When an agent wants to find a person's clearance level, it naturally attempts to query a field like clearance_level or department.

JustSift does not have a static schema for person profiles. Outside of standard properties (like firstName, lastName, and email), the vast majority of useful data in JustSift is stored in dynamic, per-organization fields. An agent cannot simply guess the key for "Department". It must first discover the exact objectKey configured by the specific organization it is querying. If your agent does not know to fetch the field definitions first, it will hallucinate field names in its search queries, resulting in empty responses and broken reasoning loops.

Binary Media Responses

Agent frameworks like LangChain and Vercel AI SDK are heavily optimized for JSON-in, JSON-out tool calling. When an agent needs to retrieve a user's profile picture from JustSift, the API does not return a convenient CDN link. The people_media endpoint returns binary JPEG image data directly in the response body.

If you feed raw binary data directly back into an LLM's observation context, the agent will instantly crash or max out its token limit with garbage characters. Your tool layer must intercept this binary response, store the blob in a secure ephemeral bucket, and return a signed URL or base64 encoded string to the agent instead.

Complex AND/OR Search Logic Nesting

JustSift offers a powerful complex search endpoint, but the payload requires strict boolean logic nesting. You cannot simply pass a flat list of filters. The API requires an array of conditions grouped by AND or OR operators. LLMs are notoriously bad at structuring deeply nested boolean logic without strict JSON schema enforcement. Without a robust proxy layer to validate the search schema before forwarding the request to JustSift, the LLM will generate malformed query syntax that results in HTTP 400 Bad Request errors.

Rate Limiting and Backoff Delegation

When building autonomous agents, rate limits are your biggest enemy. An agent in a recursive reasoning loop can easily fire dozens of requests per second as it searches for a specific employee profile.

It is critical to understand how Truto handles rate limits. Truto does not automatically retry, throttle, or apply backoff on rate limit errors. When JustSift returns an HTTP 429 Too Many Requests error, Truto passes that error directly back to the caller.

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

• ratelimit-limit: The maximum number of requests permitted in the current window.
• ratelimit-remaining: The number of requests remaining in the current window.
• ratelimit-reset: The time at which the current rate limit window resets.

The caller (your agent framework or application logic) is strictly responsible for inspecting these headers and implementing the appropriate retry and backoff logic. Do not assume the integration layer will absorb rate limit errors for you.

Hero Tools for JustSift AI Agents

Truto provides a comprehensive set of tools for JustSift by offering descriptions and schemas for all the methods defined on the integration's resources. When you call the GET /integrated-account/<id>/tools endpoint, you receive these Proxy APIs as tools that LLM frameworks can consume natively.

Here are the highest-leverage tools available for JustSift agent workflows.

List All JustSift Person Fields

Because JustSift relies on dynamic, per-organization data models, your agent must map the territory before making queries. This tool returns the field definitions configured in the target organization, including the exact objectKey and whether the field is searchable.

Contextual usage notes: Always instruct your agent to call this tool first if it is asked to search by custom attributes like "Clearance Level", "Office Location", or "Cost Center".

"Fetch the custom person fields for the organization so I know the exact objectKey used for 'Department' before I run my search."

List All JustSift Complex Search People

This is the heavy lifter for data retrieval. It allows the agent to search JustSift people using complex AND/OR filter logic against person fields. It supports field-based sorting and optional generic text queries, returning up to 100 records per page including the id and email.

Contextual usage notes: Use this tool when the user requests a highly specific cohort of people (e.g., "Find all engineers in London who are not contractors"). The agent must construct the nested boolean payload carefully.

"Find all employees where the 'department' field equals 'Engineering' AND the 'location' field equals 'London'."

List All JustSift Search People

For simpler lookups, this tool performs a standard people search. It returns a collection of matching people including their id, firstName, lastName, pictureUrl, and dynamic fields. It accepts a standard q query string and exact-match field filters that combine with an implicit AND (unless orQuery is set to true).

Contextual usage notes: Use this for broad text searches or simple single-field lookups where the complex boolean nesting is unnecessary.

"Search for anyone with the name 'Sarah' in the Marketing department."

Get Single JustSift Person by ID

Once an agent identifies a user via a search tool, it needs a way to pull their complete profile. This tool retrieves a single person record by their internal id or email address, returning the full mix of standard properties and dynamic per-organization fields.

Contextual usage notes: This is the primary tool for detailed entity extraction. If a user asks for a dossier on a specific employee, the agent should search for the ID first, then call this tool.

"Get the full JustSift profile for the employee with ID 8f7d9a2b."

List All JustSift People Media

This tool retrieves a person's photo from JustSift using their ID or email. Because JustSift returns binary JPEG data, this tool requires careful handling at the application edge if you intend to display the image or process it via a multimodal vision model.

Contextual usage notes: Only use this if the workflow specifically requires facial recognition, badge generation, or visual profile auditing.

"Retrieve the profile picture media for john.doe@example.com so we can update the internal company directory."

To view the complete inventory of available tools, their exact JSON schemas, and required parameters, visit the JustSift integration page.

Building Multi-Step Workflows

Building a robust AI agent is a straightforward exercise in prompting and state management. Truto's LLM SDKs use the /tools endpoint to register tools in your framework of choice. Below is a realistic architectural pattern for binding JustSift tools to a LangChain agent, complete with rate limit handling.

Because Truto passes HTTP 429s directly to the caller, your tool execution loop must inspect the IETF rate limit headers and apply backoff.

Here is how you architect that execution loop.

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 runJustSiftAgent(promptText: string, integratedAccountId: string) {
  // 1. Initialize the Truto Tool Manager with your tenant API key
  const trutoManager = new TrutoToolManager({
    apiKey: process.env.TRUTO_API_KEY,
  });
 
  // 2. Fetch the JustSift tools via the Proxy API layer
  const justSiftTools = await trutoManager.getTools(integratedAccountId);
 
  // 3. Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4-turbo",
    temperature: 0,
  });
 
  // 4. Bind the tools to the LLM natively
  const llmWithTools = llm.bindTools(justSiftTools);
 
  // 5. Create the prompt template
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are an autonomous HR intelligence agent. If asked to query custom fields, ALWAYS fetch the person fields schema first to discover the correct objectKeys."],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);
 
  // 6. Create the agent executor
  const agent = createToolCallingAgent({
    llm: llmWithTools,
    tools: justSiftTools,
    prompt,
  });
 
  const executor = new AgentExecutor({
    agent,
    tools: justSiftTools,
    maxIterations: 10,
  });
 
  // 7. Execute with custom rate limit error handling
  try {
    const result = await executor.invoke({ input: promptText });
    console.log("Agent Result:", result.output);
  } catch (error: any) {
    // Inspect Truto's standardized IETF rate limit headers
    if (error.status === 429) {
      const resetTime = error.headers['ratelimit-reset'];
      console.warn(`Rate limit hit. Must backoff until UNIX timestamp: ${resetTime}`);
      // Implement your application-level backoff and queueing logic here
    } else {
      console.error("Agent execution failed:", error);
    }
  }
}

The architectural flow of this system is straightforward but highly resilient. The agent fetches the integration definitions as JSON, LangChain converts those JSON schemas into native OpenAI tool schemas, and the LLM executes the routing logic.

sequenceDiagram
    participant App as Your App
    participant LLM as LLM (OpenAI/Claude)
    participant Truto as Truto Tool Manager
    participant Upstream as JustSift API

    App->>Truto: GET /integrated-account/{id}/tools
    Truto-->>App: Returns JSON array of Proxy API schemas
    App->>LLM: .bindTools(justSiftTools)
    App->>LLM: Invoke with User Prompt
    LLM-->>App: Tool Call: list_all_just_sift_person_fields
    App->>Truto: Execute Tool (Proxy API Request)
    Truto->>Upstream: Authenticated GET /fields/person
    Upstream-->>Truto: Field definitions
    Truto-->>App: Standardized JSON response
    App->>LLM: Return Tool Observation
    LLM-->>App: Tool Call: list_all_just_sift_complex_search_people
    App->>Truto: Execute Tool with constructed logic
    Truto->>Upstream: Authenticated POST /search/complex
    Upstream-->>Truto: HTTP 429 Too Many Requests
    Truto-->>App: HTTP 429 + ratelimit-reset header
    Note over App: App reads header, waits,<br>and retries the tool execution.

Workflows in Action

When you give an LLM access to JustSift's dynamic schemas and search endpoints, it transitions from a simple chatbot into an autonomous operations engine. Here is what that looks like in practice for different technical personas.

The HR Analyst: Automated Executive Profiling

HR teams frequently need to pull consolidated reports on specific cohorts of employees based on constantly changing custom criteria.

"Find the exact objectKey for 'Security Clearance'. Then, run a complex search to find all employees with a Top Secret clearance level. Finally, pull the complete profile and profile picture for each of those employees and summarize their departments."

How the agent executes this:

1. The agent calls list_all_just_sift_person_fields and discovers that "Security Clearance" is mapped to the internal objectKey: sec_clear_lvl.
2. It constructs a nested boolean JSON payload and calls list_all_just_sift_complex_search_people, filtering where sec_clear_lvl equals Top Secret.
3. The agent receives a list of IDs and emails in the response.
4. It loops through the IDs, calling get_single_just_sift_person_by_id to grab the textual data and list_all_just_sift_people_media to fetch their photos.
5. The user receives a perfectly formatted markdown table containing the requested cohort, complete with their actual departmental metadata.

The IT Admin: Cross-Department Software Auditing

IT teams need to ensure that software licenses are only assigned to active employees in specific departments. If profile data lives in JustSift, the agent can audit access autonomously.

"Look up Sarah Jenkins in JustSift. Tell me what her current 'Cost Center' is so I can accurately bill her new GitHub Copilot license. If she doesn't have a cost center assigned, flag her account."

How the agent executes this:

1. The agent calls list_all_just_sift_search_people with the query parameter q=Sarah Jenkins.
2. It extracts her id from the search results.
3. It calls list_all_just_sift_person_fields to find the exact objectKey for "Cost Center".
4. It calls get_single_just_sift_person_by_id and parses the dynamic fields array for the Cost Center key.
5. The user receives the exact billing code required, saving the IT admin 15 minutes of manual UI navigation and cross-referencing.

Moving Past Manual Integration Code

Connecting an AI agent to an enterprise directory like JustSift exposes the harsh realities of SaaS integrations. Dynamic schemas, binary media formats, and unforgiving rate limits will break standard LLM wrappers. By utilizing Truto's Proxy APIs and the /tools endpoint, you abstract away the API boilerplate, ensuring your agent only interacts with deterministic, validated JSON schemas.