Skip to main content
Practice

APIs: The Channel Through Which Agents Connect to External Systems

When we say an AI agent "actually does work," we do not just mean it produces good answers; we mean it directly operates external systems. Registering appointments, sending emails, querying data, and confirming payments all require a connection to other services. The key to that connection is the API.

API connection flow

What Is an API?​

An API (Application Programming Interface) is a defined "connection interface" that allows programs to communicate with each other.

Just as pressing a button on a website changes what appears on the screen, a program can also send a request to another program saying "please do this task." The only difference is that code sends the request instead of a human.

Here is a simple example:

  • When you open a weather app, it sends a request to a weather service server: "Tell me the current temperature in New York."
  • The server returns data in a defined format.
  • The app displays that data on the screen.

The interface that connects the app and the weather server is the API. An API is a contract: "if you send a request in this format, you will get a response in this format."

An agent works by the same principle. Instead of a person clicking a screen, the agent sends requests directly through APIs.

How an Agent Uses APIs​

When an agent connects to an external system, the process typically goes like this:

  1. Understand the user's request.
  2. Determine which system is needed.
  3. Construct the request to match that system's API format.
  4. Receive the response and use it in the next step.

For example, if the request "schedule a team meeting tomorrow at 3 PM" comes in:

  • Extract the date and time.
  • Determine that the Google Calendar API is needed.
  • Organize the title, time, and attendee information to match the event creation format.
  • Send the request to the calendar server.
  • Confirm the success response.

A conversational AI can only "recommend" a meeting time; an agent actually "creates" the event through the API.

The difference lies in whether it can move a real system through an API.

Authentication Is Required to Use an API​

External systems do not accept requests from just any program. They need to verify "who sent this request." This is called authentication. There are three primary methods:

1. API Key​

A unique string issued by the service is included with each request. Including this key identifies the requester as an "authorized user."

This approach is simple to implement, but if the key is leaked, anyone can use it. It is therefore primarily used for public data queries and simple service integrations.

2. OAuth​

The user logs in directly and approves "this app may use my data." When you log into another app using your Google account, the authentication method being used is OAuth.

This approach is more secure because the password is never handed to the external service, and access permissions can be finely controlled.

3. Webhook​

A webhook is not a way of sending a request. It is a structure for receiving a notification when a specific event occurs. Think of it as "the other party notifies you first."

For example, when a payment completes, the payment system automatically sends a "payment completed" signal to your server. The agent receives this signal and performs the follow-up tasks.

A Real-World AI Agent Workflow Example​

Scenario: "When a customer confirms a meeting, register it on the calendar and send a Slack notification."

The processing flow is as follows:

  • Extract the meeting date and time from an email or form.
  • Send an event creation request to the Google Calendar API connected via OAuth.
  • Once the event is successfully created, send a message delivery request to the Slack API.
  • A notification automatically appears in the team channel.

All of this happens automatically without a person directly operating any screen. This is the "execution capability" of an agent.

Understanding Error Codes​

When working with API integrations, you will frequently encounter numeric status codes. These numbers summarize "how the request was processed" in a single line. They may look cold on the surface, but they are actually the most important clue for diagnosing problems.

1) 2xx: Success​

  • 200 OK: The request was processed normally.
  • 201 Created: New data was successfully created.

When designing an agent, you must include a step that confirms whether the response is in the 2xx range, not just that "a response arrived." Without this, the agent may proceed to the next step as if it succeeded even when it failed.

2) 4xx: Something Was Wrong with Your Request​

4xx means "the request itself has a problem."

  • 400 Bad Request: The request format is incorrect (missing required fields, format error, etc.)
  • 401 Unauthorized: Authentication information is missing or incorrect
  • 403 Forbidden: Authenticated, but insufficient permissions
  • 404 Not Found: Request sent to the wrong address (endpoint)
  • 429 Too Many Requests: Rate limit exceeded

The most frequently encountered in practice are 401, 403, and 429.

Common scenarios:

  • A 401 occurs when a token has expired but there is no re-issuance logic.
  • A 403 occurs when you have read-only access but send a write request.
  • A 429 occurs when making many repeated calls during testing.

4xx errors are mostly problems that can be resolved by redesigning the request.

3) 5xx: Server-Side Problem​

  • 500 Internal Server Error: Internal error on the server
  • 502/503: The server is temporarily overloaded or down

5xx errors are not problems the user can fix. The following strategies are needed to handle them:

  • Automatic retry logic (e.g., retry up to 3 times)
  • Re-requesting after a set period of time

In this way, an agent must be designed not just to "send one request and be done" but also to handle what happens when that request fails.

Want to learn more?

Join CodeFriends Plus membership or enroll in a course to start your journey.