Let's talk

Integration Guide

How to Call an AI Agent via API

Moving from simple chatbots to autonomous agents requires a shift in how you handle API calls. Learn the protocols that make agentic workflows possible.

By Divyaprakash JhaUpdated 5 min readTopic: Agentic AI

Photo for How to Call an AI Agent via API

The Quick Answer: Three Ways to Call an Agent

To call an AI agent via API, you can use an OpenAI-compatible endpoint by targeting an agent role, expose your agent as a tool using the Model Context Protocol (MCP), or use the A2A protocol to allow other agents to discover and delegate tasks to your agent via JSON-RPC.

  • Use an OpenAI-compatible API: Call /v1/chat/completions by setting the model to an agent or workflow role.
  • Use MCP (Model Context Protocol): Expose your agents as tools to any MCP client.
  • Use A2A (Agent-to-Agent): Use an A2A agent card and JSON-RPC endpoint to allow other agents to discover and delegate to yours.

Using OpenAI-Compatible APIs

For many builders, the easiest way to integrate an agent is to treat it like a standard Large Language Model (LLM). Most modern agent platforms, such as Shiva Agents, provide an OpenAI-compatible interface to make this transition seamless.

When you use this method, you aren't just sending a prompt to a chatbot; you are targeting a specific agent role or a complex, multi-step workflow. This allows you to treat an entire autonomous process—such as a specialized tax assistant for a small business in Mumbai—as a single, easy-to-use chat endpoint.

Because these platforms follow standard protocols, you can use any existing OpenAI client to communicate with your agent. You simply change the "model" parameter in your API call to point to your specific agent or workflow instead of a generic model like GPT-4.

Connecting via MCP Server

The Model Context Protocol (MCP) is a growing standard that changes how agents interact with the world. Instead of thinking of an agent as a standalone chatbot that you talk to, MCP allows you to think of an agent as a tool that an LLM can use.

By exposing an agent via an MCP server, you make its specialized capabilities available to any MCP client. For example, if you have built a highly specialized agent that can query a specific database of inventory for a retail shop, you can host that agent as an MCP server. Now, a model like Claude can "reach out" and use your agent as a specialized tool to answer complex inventory questions.

To understand the underlying mechanics of this connection, you can explore MCP server architecture or see MCP server examples to see how these interactions are structured in real-world scenarios.

Agent-to-Agent (A2A) Communication

As the ecosystem of AI grows, agents will need to talk to each other without human intervention. This is where Agent-to-Agent (A2A) communication comes in. A2A is designed specifically for autonomous discovery and delegation.

In an A2A setup, agents use an "agent card" located at a specific path: /.well-known/agent-card.json. This card acts like a digital business card, describing exactly what the agent can do, what its goals are, and what tools it possesses. This allows one agent to "discover" another agent on a network.

Once discovery is complete, the agents use a JSON-RPC endpoint to communicate. This allows one agent to hand off a task to another agent seamlessly. Imagine a "Customer Support Agent" receiving a request to process a refund; it can use A2A to delegate the actual financial transaction to a specialized "Accounting Agent" without a human ever needing to bridge the gap.

API vs. Workflow vs. Agent

It is vital for business owners to understand the difference between these three terms, as they represent different levels of complexity and cost. Using the wrong one for a task can lead to unpredictable results or wasted API credits.

Feature Workflow Agent
Who decides the next step? The developer, in code The model, at run time
Uses tools? Yes, at fixed points Yes, chosen per step
Steps per task Fixed and known Variable, often unknown in advance
Predictability High Lower; needs guardrails

A standard Workflow follows predefined, fixed code paths. It is highly predictable and great for repetitive tasks like "send a WhatsApp template when a new lead arrives."

An Agent, however, is built on agentic architecture. An agent decides the next step at runtime. Because it can loop, use tools, and react to new information, an API call to an agent is significantly more complex than a call to a chatbot. An agent might need to research a problem, try a solution, fail, and then try a different path before finally returning a result.

Ensuring Reliable API Calls

Because agents are autonomous and can enter loops, calling them via API requires different safety measures than calling a standard LLM. If you are building production-grade software, you must implement the following:

1. Implement Timeouts and Step Budgets

An agent might get stuck in a "reasoning loop" where it keeps trying the same failed tool call over and over. To prevent this from draining your budget, always set a maximum number of steps or a "step budget" for every API call. If the agent hasn't reached its goal within 10 steps, the system should terminate the run.

2. Use Webhooks and SSE Streams

Agentic tasks often take a long time. A simple "request-response" HTTP call might time out before the agent finishes. For long-running tasks, use Server-Sent Events (SSE) to stream the agent's thoughts and progress to your UI, or use webhooks to notify your application once the agent has completed its goal.

3. Use Idempotency Keys

When using webhooks to handle retries, always use idempotency keys. If a network error occurs and your system retries the request, the idempotency key ensures that the agent doesn't perform the same action twice—like charging a customer's credit card or sending the same email twice.

Frequently Asked Questions

Can I use my existing OpenAI client to talk to an AI agent?
Yes, if the agent platform provides an OpenAI-compatible API, you can use the /v1/chat/completions endpoint by setting the model to an agent or workflow role.
What is the difference between an API call and an agentic workflow?
A standard API call usually returns a single response, whereas an agentic workflow involves a loop where the model plans, calls tools, observes results, and repeats until a goal is met.
How do agents talk to each other?
Agents can use the A2A protocol, which involves an agent card for discovery and a JSON-RPC endpoint for delegation.
What is MCP in the context of AI agents?
MCP (Model Context Protocol) allows you to expose your agents and workflows as tools that can be used by any MCP-compatible client.
How do I handle long-running agent tasks via API?
You should use webhooks with idempotency keys or server-sent event (SSE) streams to monitor the progress of the agent's execution.
Yellow robotic arm operating inside a glass enclosure with a monitor above.
Photo: Robot arm works on a small component in a lab setting by Shixart1985, CC BY 2.0

Questions people ask

Can I use my existing OpenAI client to talk to an AI agent?

Yes, if the agent platform provides an OpenAI-compatible API, you can use the /v1/chat/completions endpoint by setting the model to an agent or workflow role.

What is the difference between an API call and an agentic workflow?

A standard API call usually returns a single response, whereas an agentic workflow involves a loop where the model plans, calls tools, observes results, and repeats until a goal is met.

How do agents talk to each other?

Agents can use the A2A protocol, which involves an agent card for discovery and a JSON-RPC endpoint for delegation.

What is MCP in the context of AI agents?

MCP (Model Context Protocol) allows you to expose your agents and workflows as tools that can be used by any MCP-compatible client.

How do I handle long-running agent tasks via API?

You should use webhooks with idempotency keys or server-sent event (SSE) streams to monitor the progress of the agent's execution.