Connect Attio to AI Agents: Orchestrate Customer Data and Entities

To connect Attio to AI agents, you need an integration layer that translates the LLM's standardized tool calls into Attio's specific object, record, and list API requests. If your team uses ChatGPT, check out our guide to connecting Attio to ChatGPT, or if you are building on Anthropic's models, read our guide to connecting Attio to Claude. For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework (though if you are just looking to connect a standard chat interface, evaluating the best MCP servers for Attio might be a faster path).

Attio is a highly flexible, data-dense CRM used by AI-native companies. Unlike legacy CRMs with rigid schemas, Attio relies heavily on custom objects, complex attribute types, and a unique list-entry architecture. Exposing this complexity to a Large Language Model (LLM) requires precise tool definitions and strict schema enforcement.

This guide breaks down exactly how to use Truto's /tools endpoint to generate AI-ready tools for Attio, bind them natively to your LLM using frameworks like LangChain, and execute complex CRM workflows autonomously.

The Engineering Reality of Attio's API

As we've seen when connecting Affinity to AI agents, giving an LLM access to external data sounds simple in a prototype: you write a Node.js function that makes a fetch request and wrap it in an @tool decorator. In production, this approach collapses entirely. If you decide to build a custom integration for Attio, you own the entire API lifecycle. You have to handle OAuth token refreshes. You have to write and maintain massive JSON schemas for every endpoint you want the LLM to access.

Attio's API introduces several specific integration challenges that break standard CRUD assumptions:

The Record vs. Entry Hierarchy Attio separates the concept of a person or company from their presence in a workflow. A Record represents the global canonical entity (like a Company). A List represents a workflow (like "Q3 Pipeline"). An Entry is the relational bridge connecting that Record to that List. When an AI agent wants to move a deal to "Closed Won", it is not updating the Company Record. It is updating the Entry for that Company on the Sales List. This distinction trips up standard LLMs that assume flat CRM structures.

The Assert Pattern When an AI agent processes an inbound email, it usually needs to ensure a company exists before adding it to a list. Standard APIs require a "search, then create if missing" loop. Attio provides assert endpoints (e.g., attio_companies_assert) which act as an upsert based on matching attributes (like an email domain). This is highly useful for AI agents, cutting a two-step LLM reasoning loop down to a single definitive tool call.

Rate Limits and Edge Cases If your AI agent gets stuck in a loop or tries to summarize hundreds of interactions at once, the API will return an HTTP 429 error. Truto acts as a pass-through proxy for these requests. Truto normalizes the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset), but it does not absorb or retry the 429s for you. Your agent executor must implement its own exponential backoff.

Core Attio Tools for AI Agents

Truto automatically generates tool definitions from Attio's API documentation. Here are the highest-signal tools your agent will use to orchestrate customer data.

attio_companies_assert

• Description: Create or update a company in Attio using a unique matching attribute (like a domain name). This prevents duplicate records and is the safest way for an agent to ensure a company exists before acting on it.
• Example Prompt: "Ensure Acme Corp (acme.com) exists in the CRM, then return its record ID."

create_a_attio_entry

• Description: Create an entry in Attio by adding a record to a list. Requires the list identifier and the parent record ID.
• Example Prompt: "Add the Acme Corp record to the 'Enterprise Sales' list."

update_a_attio_entry_by_id

• Description: Update a list entry in Attio using the list ID and entry ID. This is used to change pipeline stages, update custom list attributes, and append new multiselect values.
• Example Prompt: "Move Acme Corp's entry on the Enterprise Sales list to the 'Proposal Sent' stage."

attio_records_record_entries

• Description: List all entries for which a specific record is the parent. This allows the agent to see every workflow or pipeline a specific person or company is currently involved in.
• Example Prompt: "Check which active lists Jane Doe is currently on."

create_a_attio_task

• Description: Create a new task in Attio linked to specific records. Requires content and allows optional deadlines and assignees.
• Example Prompt: "Create a task linked to the Acme Corp record to follow up on the security review by next Tuesday."

list_all_attio_notes

• Description: List notes in Attio including titles and parent record IDs. Useful for RAG workflows where the agent needs to summarize past account context before drafting an email.
• Example Prompt: "Pull all recent notes attached to the Acme Corp record and summarize the last meeting."

Complete Attio Tool Inventory

Here is the complete inventory of additional Attio tools available. For full schema details, visit the Attio integration page.

• attio_entries_attribute_values: List all values for a specific attribute on an entry in Attio.
• attio_entries_assert: Assert a list entry by parent in Attio for the given list.
• attio_entries_overwrite: Update a list entry in Attio using list and id. Overwrites multiselect values.
• attio_records_attribute_values: List all values for a specific attribute on a record in Attio.
• update_a_attio_record_by_id: Update a record in Attio by object and id. Appends new multiselect attribute values.
• attio_records_overwrite: Update a specific record in Attio by object and id. Overwrites existing multiselect values.
• create_a_attio_record: Create a record in Attio for a specific object.
• delete_a_attio_record_by_id: Delete a record in Attio by object and id.
• get_single_attio_record_by_id: Get a specific record in Attio using object and id.
• list_all_attio_records: List records for a specific object in Attio.
• attio_workspaces_record_entries: List all entries for which the specified workspace record in Attio is the parent.
• attio_workspaces_attribute_values: List attribute values for a workspace record in Attio.
• attio_workspaces_assert: Create or update a workspace record in Attio using a matching attribute.
• create_a_attio_workspace: Create a workspace record in Attio.
• list_all_attio_workspaces: List workspace records in Attio including record IDs and timestamps.
• get_single_attio_workspace_by_id: Get a specific workspace record in Attio using a unique identifier.
• update_a_attio_workspace_by_id: Update a workspace record in Attio by id.
• delete_a_attio_workspace_by_id: Delete a workspace record in Attio by id.
• attio_users_attribute_values: List all values for a specific attribute on a user record in Attio.
• attio_users_record_entries: List all entries for which the user record in Attio is the parent.
• update_a_attio_user_by_id: Update a user record in Attio by id.
• delete_a_attio_user_by_id: Delete a user record in Attio using a specific record identifier.
• attio_users_assert: Create or update a user record in Attio using the matching_attribute parameter.
• get_single_attio_user_by_id: Get a user record in Attio by providing a specific record identifier.
• list_all_attio_users: List user records in Attio including workspace and object details.
• create_a_attio_user: Create a user record in Attio.
• attio_deals_attribute_values: List deal record attribute values in Attio.
• attio_deals_record_entries: List all entries for which the deal record in Attio is the parent.
• get_single_attio_deal_by_id: Get a specific deal record in Attio using its unique identifier.
• delete_a_attio_deal_by_id: Delete a deal record in Attio.
• attio_deals_assert: Create or update a deal record in Attio using a unique matching_attribute.
• update_a_attio_deal_by_id: Update a deal record in Attio by its unique identifier.
• attio_companies_record_entries: List all entries for which the company record is the parent in Attio.
• attio_companies_attribute_values: List attribute values for a company record in Attio using record ID.
• delete_a_attio_company_by_id: Delete a company record in Attio by providing its unique identifier.
• attio_people_attribute_values: List all values for a specific attribute on a person record in Attio.
• attio_people_record_entries: List all entries for a specific person record in Attio.
• update_a_attio_person_by_id: Update a person record in Attio using its unique identifier.
• get_single_attio_person_by_id: Get a person record in Attio using its unique identifier.
• attio_people_assert: Create or update a person record in Attio using a matching attribute.
• delete_a_attio_person_by_id: Delete a person record in Attio by its unique identifier.
• list_all_attio_auth_session: Identify the current access token, its Attio workspace, and permissions.
• delete_a_attio_webhook_by_id: Delete a webhook in Attio using its unique identifier.
• create_a_attio_webhook: Create a webhook in Attio by specifying a target URL and subscriptions.
• update_a_attio_webhook_by_id: Update a webhook in Attio.
• get_single_attio_webhook_by_id: Get detailed information about a specific webhook in Attio.
• list_all_attio_webhooks: List all active webhooks in Attio including delivery URLs and event types.
• get_single_attio_comment_by_id: Get a specific comment in Attio including thread and content details.
• delete_a_attio_comment_by_id: Delete a comment in Attio by id.
• create_a_attio_comment: Create a comment in Attio on a specific thread, record, or entry.
• get_single_attio_thread_by_id: Get all comments and metadata in a specific thread in Attio.
• list_all_attio_threads: List threads in Attio including comment counts and key details.
• update_a_attio_task_by_id: Update a specific task in Attio including content, deadline, and status.
• get_single_attio_task_by_id: Get a single task in Attio including linked records and completion status.
• delete_a_attio_task_by_id: Delete a task in Attio by its unique identifier.
• delete_a_attio_note_by_id: Delete a note in Attio by providing its unique identifier.
• get_single_attio_note_by_id: Get a note in Attio including parent record and content details.
• get_single_attio_workspace_member_by_id: Get a workspace member in Attio using a specific member identifier.
• get_single_attio_entry_by_id: Get a specific list entry in Attio using list and entry identifiers.
• list_all_attio_attribute_options: List select options for a specific attribute in Attio.
• get_single_attio_attribute_by_id: Get information about a specific attribute in Attio using id.
• update_a_attio_attribute_by_id: Update a specific attribute in Attio for a given object or list.
• list_all_attio_attributes: List attributes for a specific object or list in Attio.
• create_a_attio_attribute: Create an attribute in Attio for a specific object or list.
• create_a_attio_object: Create a new custom object in Attio with specific naming nouns.
• list_all_attio_objects: List all system-defined and user-defined objects in Attio.
• update_a_attio_object_by_id: Update an object definition in Attio including its API slug and names.
• get_single_attio_object_by_id: Get an object definition in Attio using its unique identifier.
• list_all_attio_tasks: List all tasks in Attio with content and deadline details.
• list_all_attio_workspace_members: List all members in an Attio workspace with identity details.
• create_a_attio_note: Create a note in Attio attached to a parent object or record.
• list_all_attio_deals: List deal records in Attio with values and record identifiers.
• create_a_attio_deal: Create a new deal record in Attio for sales tracking.
• create_a_attio_person: Create a person record in Attio with contact information.
• list_all_attio_people: List person records in Attio including created timestamps and URLs.
• update_a_attio_company_by_id: Update a company record in Attio using its record identifier.
• get_single_attio_company_by_id: Get a company record in Attio using its unique identifier.
• create_a_attio_company: Create a company record in Attio including attribute values.
• delete_a_attio_entry_by_id: Delete an entry from a list in Attio.
• list_all_attio_entries: List entries in a specific list in Attio using its identifier.
• update_a_attio_status_by_id: Update a status value for a specific attribute in Attio.
• update_a_attio_list_by_id: Update an existing list definition by id in Attio.
• list_all_attio_statuses: List available statuses for a specific status attribute in Attio.
• create_a_attio_status: Create a new status for a specific attribute in Attio.
• create_a_attio_list: Create a new list with workspace access controls in Attio.
• get_single_attio_list_by_id: Get a single list definition by id in Attio.
• list_all_attio_lists: List all lists accessible with the current access token.
• update_a_attio_attribute_option_by_id: Update a select option on an attribute in Attio.
• create_a_attio_attribute_option: Create a select option on an attribute for a target in Attio.
• list_all_attio_me: Check validity of an access token and see active scopes.
• list_all_attio_companies: List company records in Attio with filtering and sorting options.

Building Multi-Step Workflows

To build an autonomous agent, you need to fetch these tool definitions and bind them to your LLM. Truto provides a /tools endpoint that returns ready-to-use OpenAPI schemas for every method available on the connected Attio account.

While the example below uses LangChain, this approach works with CrewAI, Vercel AI SDK, or any framework that supports standard tool calling.

import { ChatOpenAI } from "@langchain/openai";
import { TrutoToolManager } from "truto-langchainjs-toolset";
import { AgentExecutor, createToolCallingAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
 
// 1. Initialize the LLM
const llm = new ChatOpenAI({
  modelName: "gpt-4o",
  temperature: 0,
});
 
// 2. Fetch Attio tools dynamically from Truto
const toolManager = new TrutoToolManager({
  trutoAccessToken: process.env.TRUTO_API_KEY,
  integratedAccountId: process.env.ATTIO_ACCOUNT_ID,
});
 
// We only want write methods and specific read methods for safety
const tools = await toolManager.getTools({
  methods: ["write", "get", "list"]
});
 
// 3. Bind tools to the LLM
const prompt = ChatPromptTemplate.fromMessages([
  ["system", "You are an elite CRM automation agent. You manage Attio records and entries. Always assert a record exists before adding it to a list."],
  ["human", "{input}"],
  ["placeholder", "{agent_scratchpad}"],
]);
 
const agent = createToolCallingAgent({
  llm,
  tools,
  prompt,
});
 
// 4. Create the executor loop
const agentExecutor = new AgentExecutor({
  agent,
  tools,
  maxIterations: 5,
});
 
// Execute a workflow
const result = await agentExecutor.invoke({
  input: "Ensure a company record exists for truto.one, then add them to the 'Q4 Outbound' list."
});
 
console.log(result.output);

sequenceDiagram
  participant Agent as Agent (LLM)
  participant Truto as Truto API
  participant Attio as Attio API
  
  Agent->>Truto: Call attio_companies_assert<br>{"domain": "truto.one"}
  Truto->>Attio: POST /v2/objects/companies/records
  Attio-->>Truto: 200 OK (Record ID: rec_123)
  Truto-->>Agent: JSON Tool Result
  
  Agent->>Truto: Call create_a_attio_entry<br>{"list": "Q4 Outbound", "parent_record_id": "rec_123"}
  Truto->>Attio: POST /v2/lists/Q4_Outbound/entries
  Attio-->>Truto: 200 OK (Entry ID: ent_456)
  Truto-->>Agent: JSON Tool Result

Handling Errors and Rate Limits

When building an executor loop, you must account for API realities. If a tool call fails because the LLM hallucinated a list ID, Truto will return an HTTP 400 error with Attio's specific error message. Your agent executor should catch this error and pass the message back to the LLM as a tool message, allowing the LLM to self-correct (e.g., by calling list_all_attio_lists to find the correct ID).

If you hit an HTTP 429, you must pause execution. Truto passes the ratelimit-reset header back to you. Your agent framework should intercept 429s, read the header, sleep the thread, and retry the tool call without failing the entire agent run.

Workflows in Action

Here are two concrete examples of how an AI agent uses these tools to automate Attio.

Scenario 1: Inbound Lead Triage

"A new inbound lead just arrived: Jane Smith from Vercel (jane@vercel.com). Make sure Vercel is in our system, create a person record for Jane, and add her to the 'Inbound Leads' list in the 'New' stage."

Agent Execution Steps:

1. attio_companies_assert: The agent calls this tool with the domain vercel.com. Attio either creates the company or returns the existing record ID.
2. attio_people_assert: The agent asserts Jane's email address, linking her to the Vercel company record ID returned in step 1.
3. create_a_attio_entry: The agent adds Jane's Person Record ID to the 'Inbound Leads' list.
4. update_a_attio_entry_by_id: The agent updates the newly created entry, setting the status attribute to 'New'.

Outcome: The CRM is perfectly updated without duplicates, and the sales team sees the new lead in their pipeline view instantly.

Scenario 2: Post-Meeting Task Generation

"I just finished a call with Acme Corp. Pull their recent notes. If there isn't a note about a security review, create a task for me to send them the SOC2 report by Friday."

Agent Execution Steps:

1. attio_companies_assert: The agent finds the Acme Corp record ID using their domain.
2. list_all_attio_notes: The agent queries notes associated with the Acme Corp record ID.
3. Internal LLM Reasoning: The agent reads the JSON response of the notes. It determines that no note mentions a security review.
4. create_a_attio_task: The agent creates a task, sets the deadline to Friday, assigns it to the user, and links it to the Acme Corp record.

Outcome: The agent performs conditional logic based on real-time CRM data, acting as an autonomous sales assistant.

Next Steps

Connecting an AI agent to Attio requires strict adherence to its Record and Entry architecture. By using Truto to dynamically generate tool schemas from the API documentation, you eliminate the need to write custom integration code, manage OAuth tokens, or maintain massive JSON schema files.