Why does my agent keep failing even though the model responses look correct?

The model is probably fine. The failure is almost always in the tools the agent calls: a missing API, stale data, or an authentication error that returns an empty result instead of an explicit failure. Instrument every tool call and log the raw response before you debug the model.

Can we give the agent read/write access to start and narrow it down later?

That approach tends to expand scope rather than reduce it. Start with read-only access to one system and add write actions one at a time, each with a tested rollback path. It is much easier to add permissions than to recover from an unintended write at scale.

What should we do if a critical system has no API at all?

You have three realistic options: expose a thin read-only API over the data, use a scheduled export to a queryable store the agent can reach, or pick a different use case. Browser automation as a workaround introduces fragility that compounds quickly in production.

How do service accounts for agents differ from regular user accounts?

A service account should carry the minimum permissions the agent needs for its defined tasks, have its credentials stored in a secrets manager rather than in code or environment files, and have its activity logged separately so you can audit what the agent did without filtering through human activity.

The Data and API Plumbing Your First Agent Needs

What you get from this article

By the end you will know how to audit your API surface before agent work starts, where data readiness problems hide, and what authentication patterns are realistic for a first agent. You will also have a checklist to run before committing engineering time to any use case.

Most first agents stall here, not in the model layer. The getting-your-first-agent-live pillar covers the full picture of production readiness. This article goes deep on the plumbing underneath.

Why agents fail at the integration layer

An agent can only act through the tools and data you expose to it. The model can reason correctly and still produce nothing useful if the tool it calls returns a 403, an empty payload, or a UI-rendered page it cannot parse. 86% of enterprises report needing tech stack upgrades to achieve agent integration compatibility, and 42% rely on eight or more data sources, compounding that complexity.

The failure mode is usually invisible at demo time. A prototype runs against a sandbox with permissive auth and clean fixture data. Production has a legacy CRM behind SSO, a rate-limited ERP with no service-account story, and a knowledge base that lives in a shared drive nobody has catalogued in two years. The model is identical in both environments. The integration layer is not.

This is why choosing the right use case for your first agent matters so much before any build work starts. A use case that looks simple in a product demo can sit on top of three systems none of which have machine-readable APIs.

Auditing your API surface before you write a line of agent code

Run this audit as a spreadsheet, one row per action the agent needs to perform.

For each action, answer four questions: Does a working API exist? Is it documented well enough to write a tool wrapper in under a day? Does it support machine authentication, not just user SSO? And does it have a test environment that resembles production?

Actions that fail the first question fall into two buckets. Some exist only in a UI, meaning someone built the feature without exposing it programmatically. Others have no programmatic path at all, usually because the system predates API-first design. Both buckets block your agent. UI scraping and browser automation can fill gaps in a prototype but they add a fragile layer that breaks on every UI release, and that fragility compounds as the agent runs thousands of calls per day rather than dozens.

BMW’s root cause analysis agent, built on Amazon Bedrock Agents, achieved 85% accuracy in identifying complex cloud incidents and significantly reduced diagnosis times because every data source it needed, architecture logs, metrics, and infrastructure state, was already accessible through instrumented APIs. The agent did not need to invent access paths. It used the ones the platform team had already built.

Where data readiness problems hide

API availability is necessary but not sufficient. The data behind the API also needs to be ready.

Three problems appear most often. First, the data exists but is wrong. A product catalogue with stale prices, a customer record with a missing contact field, a ticket system where half the entries are miscategorised. The agent will act on what it finds. AI agent governance practices are easier to enforce when the underlying data is trustworthy, but auditing data quality is an unglamorous prerequisite that most teams skip until the agent starts producing bad outputs.

Second, the data exists and is correct but is locked behind access controls the agent cannot satisfy. A knowledge base that requires a named-user login, a data warehouse accessible only through a BI tool’s GUI, a document store that grants permissions by department rather than by role. You need to know where the knowledge your agent needs actually lives and whether a service principal can reach it.

Third, the data is split across systems with no single source of truth. Geotab’s fleet management agent translates natural language into SQL queries against vehicle data covering millions of daily trips. That reduced the technical barrier for actionable insights because Geotab had already consolidated its vehicle data into a queryable store. If the data had been split across six regional databases with inconsistent schemas, the agent would have needed to reconcile conflicts before it could answer a question.

Authentication realities

Service accounts are the practical path for most first agents. A service account carries scoped credentials, has its activity logged separately from human users, and can have its access revoked without affecting anyone else. Store credentials in a secrets manager, not in environment files or source code.

The harder cases are systems with no machine-auth story at all. Some legacy platforms issue tokens only through interactive OAuth flows designed for browsers. Others require MFA on every session. Some SaaS tools in the mid-market simply never built a service-account model. For these, your realistic options are a thin API wrapper you build and own, a scheduled data export to a store the agent can reach, or a different use case.

flowchart TD
    A[Action needed by agent] --> B{API exists?}
    B -- No --> C[UI-only or no path]
    C --> D[Build thin API or change use case]
    B -- Yes --> E{Machine auth supported?}
    E -- No --> F[Legacy SSO / interactive only]
    F --> G[Wrapper, export, or change use case]
    E -- Yes --> H{Test env available?}
    H -- No --> I[Production-only risk]
    I --> J[Negotiate sandbox or scope down]
    H -- Yes --> K[Tool wrapper candidate]

Integration patterns that work for a first agent

Start read-heavy. A first agent that reads from two or three systems and surfaces answers carries near-zero write risk. You can observe what it retrieves, verify the answers, and build confidence before you expose any write actions. Knowing how to tell whether your agents are doing their job is easier when the action surface is narrow.

Limit write actions to one system of record at launch. Each write action needs a tested rollback path or a human-in-the-loop confirmation step before it runs. Salesforce’s multi-agent financial reporting system, which cut reporting time from 15 days to 35 minutes and reduced cost from $2,200 to $9 per report, used clearly separated agents for reading, cleaning, analysing, and narrating. Write operations happened only after upstream agents had validated the data.

flowchart TD
    A[Use case candidate] --> B[List all required actions]
    B --> C[Classify: read or write]
    C --> D[Reads only at launch]
    D --> E[Identify data sources]
    E --> F{Single system of record?}
    F -- Yes --> G[Proceed to tool design]
    F -- No --> H[Resolve source of truth first]
    G --> I[Assign service account]
    I --> J[Confirm scoped credentials and logging]
    J --> K[Ready for tool wrapper build]

For agentic AI integration patterns more broadly, the principle holds: reduce the number of systems the agent touches at launch, not because complexity is inherently bad, but because each additional system multiplies the surface area where auth, data quality, and API availability problems can combine.

Tools like Prefactor provide a layer for governing which tools and APIs an agent can call, which is useful once you have identified your integration surface and want to enforce it at runtime.

Plumbing checklist before committing to a use case

Work through this before writing agent code.

For each action the agent needs: API confirmed working, machine auth confirmed, test environment confirmed, data quality spot-checked, write actions each have a rollback path.

For the data the agent reads: source of truth identified, access controls compatible with a service principal, no stale or missing fields in the fields the agent will act on.

For auth overall: service account created, credentials in a secrets manager, activity logging enabled and queryable, token rotation documented.

If more than two items are unresolved, the use case is not ready. Resolve the blockers or pick a use case where fewer apply. Building vs buying your agent infrastructure is a secondary question: the plumbing audit applies regardless of which path you take.

Your evaluation suite will also be stronger when the integration layer is clean. Ambiguous tool responses make it hard to distinguish a model error from a data error, and that ambiguity slows debugging in production.

Where to start

Run the plumbing checklist above against the use case your team is currently piloting, before investing further in model selection or prompt design. If you want a structured way to assess your full integration readiness alongside the other factors that determine whether a first agent ships, take the agent readiness assessment.