AI agent integration: the API call is the easy part

The short version

• AI agent integration is the wiring between an agent and the systems it reads from and writes to: authentication, tool definitions, permission scoping and failure handling.
• An agent composes its own calls at runtime, so every integration has to tolerate a caller that can be wrong about which tool to use and what to send.
• An agent connected through a service account holds the union of everyone's permissions, which is the most common and least visible integration mistake.
• Giving an agent fewer tools usually improves it, because selection accuracy falls as the list grows and falls fastest when descriptions overlap.
• An integration platform buys you token refresh and provider drift, and costs you schema depth plus a third party holding your customers' credentials.

What does AI agent integration actually involve?

Four things, and the HTTP request is the smallest of them. You need a way to authenticate as the right person, a tool definition the model can read and choose correctly from, a boundary around what the agent is allowed to write, and a decision about what happens when a call fails. Teams usually budget for the request and are surprised by the other three.

The tool definition is the part most often underestimated, because it is not code, it is prose. The model picks between your tools by reading their names, descriptions and parameter names. If two tools both say they search records, the model picks between them the way a new starter would, which is to say inconsistently. A tool description is a prompt, and it deserves the same care as one.

The boundary matters because the agent builds its own arguments. A parameter typed as a free string will eventually receive something you did not anticipate. Narrow the types where you can: enumerate the statuses, bound the date ranges, make an identifier a lookup rather than a guess. Validate on the server anyway, because the tool schema is a suggestion to the model, not a contract it is capable of honouring.

How is an AI agent API different from a normal API integration?

The caller is not deterministic. In a normal integration, the code that posts an invoice was written once, reviewed once, and will send the same shape forever. An agent assembles the call fresh each time out of whatever happened in the conversation. The endpoint has not changed. The thing calling it has stopped being predictable.

That changes three decisions. Writes need idempotency keys, because an agent that sees a timeout will often just try again, and two attempts without a key is two invoices. Anything that spends money or reaches a customer needs a confirmation step held outside the model, so it cannot be argued around. And every tool call needs logging with its arguments, because when the output is wrong you need to know whether the model chose the wrong tool, sent the wrong arguments, or got a faithful answer from a system that was itself wrong.

It also changes what a good error looks like. A 400 that says 'invalid request' is fine for a developer who will go and read the documentation. An agent cannot read the documentation. An error that names the field and the allowed values gives the model something to act on, and it will often recover on the next turn without a human noticing anything happened.

Should you build AI agent integrations yourself or use an integration platform?

Build when you own the accounts and use them deeply. Use a platform when you need shallow access to many systems inside each of your customers' accounts. That is most of the rule, and most of the argument around it is people applying one situation's answer to the other.

A platform buys you the unglamorous parts: OAuth flows per provider, token storage and refresh, webhook plumbing, rate limit handling, and somebody else noticing when a provider changes an endpoint. If you are a software company connecting to whichever CRM each customer happens to use, that work never ends and it is not your product.

It costs you three things. Unified schemas are a lowest common denominator, and the field you actually need is often the one that did not survive normalisation. Every call takes an extra hop inside a loop that is already waiting on a model. And a third party now holds credentials to your customers' systems, which will come up in their security review whether or not you raise it first.

There is a third option now, which is the vendor's own MCP server. It removes the schema argument, because you are talking to the real API rather than a normalised view of it. It does not remove the trust question. A third-party MCP server is a dependency with credentials, and it deserves the review you would give any other one.

When does a platform earn its place?

How should an AI agent authenticate to the systems it uses?

As the person it is acting for, wherever the system supports it. An agent connected through a single service account holds the union of everyone's permissions, and the only thing then standing between a junior employee and the board pack is an instruction in a prompt. Prompts do not hold.

Per-user authentication is more work at the start and less work forever after, because the entitlement question gets answered by the system that already owns it. Where per-user auth genuinely is not available, scope a dedicated role as narrowly as the system allows, and apply the filter before the call rather than to the response. Filtering the response means the content already reached the model.

Then plan for the token lifecycle, which is the failure nobody designs for. Refresh tokens expire. They get revoked when someone leaves, or when an admin rotates an app registration. An agent that quietly loses access to a mailbox does not throw an error a user will see: it returns nothing and then explains the nothing. That arrives as 'the agent got worse', and it is the hardest report to debug because it shows up weeks after the cause.

How many integrations should an AI agent have?

Fewer than the roadmap says. Selection accuracy falls as the tool list grows, and it falls fastest when tools overlap. Three different ways to search customer records is worse than one, because the model now has to make a judgement with no right answer and you have no way to evaluate it.

A workable test: if two tools need the same sentence to explain when to use them, merge them or delete one. Name tools after the intent rather than the system. A tool called find_customer beats one called salesforce_query, because the model chooses by meaning and the second name only means something to the people who built it.

Read before write, every time. Ship the integration read-only, run it against real traffic, and look at the logged calls it would have made. The gap between what the agent proposed and what a competent human would have done is the cheapest evaluation you will ever run, and you get it before anything is at stake.

What breaks in production that the demo never showed?

Volume, mostly. The demo account has twelve records and one user. The real one has forty thousand records, a custom field somebody added last Tuesday, and a user whose permissions are narrower than yours. Almost every integration failure that matters is a version of that sentence.

What the demo account hid

• •Pagination: an agent that reads the first page and answers confidently is wrong in a way that looks right.
• •Rate limits: an agent in a reasoning loop hits them in a different pattern from a nightly batch job, and usually sooner.
• •Latency: every tool call is a round trip inside a turn somebody is waiting on, and three sequential calls is the difference between useful and abandoned.
• •Partial failure: three of five writes land, and the agent has no idea which two did not unless the response tells it.
• •Schema drift: custom fields and renamed picklists arrive without warning, and the tool description that explained them is now quietly wrong.
• •Permission variance: the integration works for the person who built it and returns nothing for everyone else.

What do the integration surveys actually tell you?

Less than their headlines suggest, and the sample is usually why. Most of the widely quoted numbers on agent integration come from vendor surveys of mid-market and enterprise software companies. That is a real population and the research is worth reading, but it is not a cross-section of ordinary businesses and the figures do not transfer.

Paragon's 2026 State of Agentic Integrations report surveys 600 B2B SaaS leaders, and more than 60% of them work at companies with 500 or more employees. Anthropic's 2026 state of AI agents report, run with the research firm Material, surveys over 500 technical leaders in the United States, with fieldwork described as late 2025. Postman's 2025 State of the API covers more than 5,700 developers, architects and executives globally, 43% of them in Asia-Pacific. Each is useful for the population it drew from. None of them is everyone.

The nationally representative one tells a flatter story. The U.S. Census Bureau's Business Trends and Outlook Survey asks a representative sample of American businesses whether they used AI in any business function in the past fortnight, and finds the biggest users are larger firms, those with at least 20 employees. When a vendor survey implies that everybody has already done this, that is the figure to hold next to it.

This matters for integration specifically, because most published advice is written for the enterprise case: many customers, many CRMs, a platform to absorb the variance. If you have four systems and one tenant, a good part of that advice solves a problem you do not have.

Where should you start with AI agent integration?

With one workflow somebody currently does by hand, and read-only access to the systems it touches. Pick the workflow where a wrong answer is visible and recoverable, not the one that demos best. Connect the minimum number of systems needed to complete it end to end, and resist adding the fifth integration until the first four are boring.

Then earn the write. Once the logs show the agent choosing correctly against real traffic for a few weeks, turn on the narrowest write it needs, with an idempotency key and a confirmation step. The order matters because the failure modes are asymmetric: a wrong read is a bad answer, and a wrong write is a phone call from a customer.