DEV Community

Cover image for Connecting AI Agents to Real APIs Safely: Narrow Tools, Backend Auth, Clean Errors
Shaheryar Yousaf
Shaheryar Yousaf

Posted on

Connecting AI Agents to Real APIs Safely: Narrow Tools, Backend Auth, Clean Errors

TL;DR for devs

  • Start with one specific task and design a narrow tool contract for it.
  • Keep identity, authorization and API keys in the backend, never in prompts or frontend code.
  • Read tools and action tools need different levels of care.
  • Avoid generic HTTP request tools, validate every argument and return only the data the task needs.
  • A timeout on a mutating call is not proof of failure; use idempotency and check status.

Tool contracts, authorization, timeouts and the integration mistakes to avoid

An AI assistant can explain what a calendar API does. An agent connected to that API could check availability, suggest a meeting time, and create an event after the user confirms. The connection between language model and outside system is what makes these experiences possible.

For developers, “connect the agent to an API” involves more than giving a model an endpoint URL. You need to define a safe tool contract, validate arguments, enforce authorization, execute the request, handle failures, and return a useful result. The model may select and prepare a tool call, but your application should control how it runs.

This beginner-friendly guide explains how to build AI agents that use APIs and external tools, with Python examples. We’ll use a read-only order lookup as the running example, then discuss how to add actions safely.

What Is an External Tool?

A tool is a capability the application makes available to an agent. It might be a Python function, an internal service, or an external API. Examples include searching documentation, retrieving an order, checking calendar availability, or creating a task.

A model does not necessarily call an external service directly. In a typical tool-calling flow:

  1. The application describes available tools to the model.
  2. The model returns a request to call one tool with structured arguments.
  3. The application validates the request and calls its function or API.
  4. The application returns the result to the model.
  5. The model uses that result to answer or choose a next step.

OpenAI’s function calling guide explains this application-mediated pattern. Tool formats vary by provider, but the key design principle remains: the model can request a capability; your code decides whether to execute it.

Start With a Specific Task

Avoid starting with “connect my agent to our whole backend.” Pick one task with clear inputs and outputs. For example:

Given an authenticated customer and an order number, return the order’s current shipping status.

This task is read-only. The user needs to be authenticated, the order number must be valid, and the result should include only information the customer is allowed to see. A narrow task is easier to test than a general-purpose tool that can query arbitrary records.

Before implementation, define what should happen when the order is missing, belongs to a different customer, or the shipping service is unavailable. Those cases are part of the feature, not optional details.

Design a Narrow Tool Contract

A tool contract should tell the model what the tool does, when to use it, and which arguments it needs. Keep the schema narrow. Do not expose raw SQL, arbitrary URLs, or an unrestricted shell as a shortcut to flexibility.

A conceptual definition might be:

{
  "name": "get_order_status",
  "description": "Look up the shipping status of an order belonging to the signed-in customer.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_number": { "type": "string" }
    },
    "required": ["order_number"],
    "additionalProperties": false
  }
}
Enter fullscreen mode Exit fullscreen mode

The description supports tool selection, but it does not enforce access control. Your backend must identify the signed-in customer from the authenticated session. Do not trust a customer_id supplied by the model as proof of identity.

Call the API From Python

The model’s tool request should reach your application code, where arguments are checked and an API client performs the operation. Here is a simplified example using Python’s requests library. The endpoint and response format are placeholders; adapt them to your service.

import os
import requests

API_BASE_URL = os.environ["ORDERS_API_BASE_URL"]
API_TOKEN = os.environ["ORDERS_API_TOKEN"]


def get_order_status(order_number: str, customer_id: str) -> dict:
    order_number = order_number.strip()
    if not order_number or len(order_number) > 40:
        raise ValueError("A valid order number is required")

    response = requests.get(
        f"{API_BASE_URL}/orders/{order_number}",
        headers={"Authorization": f"Bearer {API_TOKEN}"},
        params={"customer_id": customer_id},
        timeout=8,
    )
    response.raise_for_status()
    order = response.json()

    if order.get("customer_id") != customer_id:
        raise PermissionError("Order not available to this customer")

    return {
        "order_number": order["order_number"],
        "status": order["status"],
        "estimated_delivery": order.get("estimated_delivery"),
    }
Enter fullscreen mode Exit fullscreen mode

The example reads credentials from environment variables rather than embedding secrets in source code. A production application should use its secret-management system, validate API responses, avoid returning unnecessary personal data, and map provider errors to safe user-facing messages.

Keep Identity and Authorization in the Backend

A model can help extract an order number from a conversation, but it should not decide who the user is. The application should use its authentication layer to identify the person and enforce record-level permissions.

A safe flow looks like this:

Signed-in user → application obtains trusted user identity
                → model requests order lookup with an order number
                → backend validates order and user access
                → API returns allowed fields
                → model explains the result
Enter fullscreen mode Exit fullscreen mode

Never rely only on a prompt such as “do not reveal other customers’ orders.” Prompts can guide model behavior, but authorization needs to be enforced by software around the tool.

Read Tools and Action Tools Need Different Care

A read-only tool returns information. An action tool changes something: it may send an email, create a meeting, update a record, issue a refund, or purchase a product.

For an action, consider whether to require confirmation. A calendar assistant can prepare an event and show the details before creating it. A support agent can draft a refund request and ask an authorized person to approve it. The backend should re-check permissions at the moment of execution, because approval and user state may have changed since the model prepared the request.

For actions that could be retried, use idempotency keys or another duplicate-prevention method. A timeout does not always mean the remote service failed; it may have completed the action but lost the response. Retrying blindly could create duplicate events or charges.

Handle API Errors and Timeouts

External services can be slow, unavailable, or return unexpected data. Your application should define how to handle:

  • Timeouts: stop waiting after a sensible duration and report the lookup could not be completed.
  • Rate limits: respect retry guidance and avoid rapid repeated calls.
  • Authentication failures: refresh credentials where appropriate or fail safely.
  • Not found: explain that no matching record exists, without inventing one.
  • Malformed responses: treat invalid data as an error rather than passing it to the model as fact.
  • Partial data: return what is verified and mark missing fields clearly.

The tool result should distinguish success, no match, and service failure. That gives the model enough information to respond accurately.

Return Small, Useful Results

Do not send an entire database row or API payload to the model if the user only needs a shipping status. Return the minimum useful fields. This reduces unnecessary exposure, limits prompt size, and makes the model’s task clearer.

If the result contains a date, include its time zone or format. If a status is an internal code, translate it into a clear label before or while passing it to the model. Keep source timestamps when freshness matters so the assistant can communicate when the information was checked.

Test the Complete Integration

Test more than the API function. Verify how the model, application, and external service work together. Include cases where the user provides a valid order, a misspelled number, another customer’s order, or no order number. Simulate a timeout, rate limit, and malformed API response. For action tools, test unauthorized attempts, duplicate submissions, and cancellation after confirmation.

For each case, inspect:

  • Whether the right tool was selected.
  • Whether arguments were validated.
  • Whether the backend enforced access rules.
  • Whether the API was called only when appropriate.
  • Whether the result was summarized accurately.
  • Whether failure was reported honestly.

Keep logs useful for debugging, but minimize sensitive data. Record tool name, outcome, timing, and safe identifiers rather than full credentials or unnecessary personal information.

Common Integration Mistakes

Putting API keys in prompts or frontend code

Secrets belong in backend configuration or a secret manager. Never expose privileged credentials to the model or browser.

Exposing a generic HTTP request tool

An unrestricted URL and method tool can create security risks. Prefer purpose-built functions with fixed hosts, methods, and narrow parameters.

Trusting model arguments without validation

Tool arguments are still external input. Check their type, length, allowed values, and authorization before using them.

Returning too much data

Only return what the task needs. A result can contain confidential fields that the model does not need to see or repeat.

Treating a timeout as proof of failure

For a mutating action, the remote service might have completed it even if the response timed out. Use idempotency and reconcile the action status before retrying.

Assuming prompts are access controls

Application code must enforce identity, permissions, and business rules. Instructions to the model are not a substitute.

Frequently Asked Questions

Can an AI agent call any API?

Only APIs and operations that the application exposes. It is better to provide narrow functions than a generic capability that can reach arbitrary services.

Should the model receive an API key?

Usually no. The application should keep credentials server-side and call the service after validating the model’s request.

How do APIs make an agent more useful?

They let an agent retrieve current, application-specific information or request actions through software. The model can interpret a natural-language request while the application handles the service interaction.

Should an agent be allowed to update a database?

Only when the task needs it and the application can enforce suitable permissions, validation, and approval. Start with read-only access if that is enough.

What happens if an API is unavailable?

The agent should report that it could not complete the lookup or action, and explain a sensible next step. It should not invent a successful result.

Conclusion

Connecting an AI agent to APIs turns language understanding into useful application capabilities. The safest design keeps the model’s role clear: it interprets the user’s request and can ask for a tool, while the backend validates arguments, applies permissions, calls the external service, and returns only the relevant result.

Start with one narrow, read-only tool. Add timeouts, error handling, authorization, and logging from the beginning. When you add actions, consider user confirmation and duplicate prevention. Treat tool calls as software operations that need the same careful design as any other backend feature.

References


I write about building AI agents and full-stack AI apps. Follow me for the next one, and tell me in the comments: What's the riskiest API you've considered handing to an agent?

Top comments (0)