How agents.json Empowers AI Agents to Seamlessly Call APIs

agents.json is an open specification built on the OpenAPI standard that enables AI agents to discover and reliably invoke external APIs. Service providers publish an agents.json file describing their APIs, flows (pre‑defined multi‑step operations), and links (parameter bindings), allowing agents to execute complex tasks with a single natural‑language request.

Background and Relation to OpenAPI

OpenAPI Specification (OAS) standardizes RESTful API description in a machine‑readable format (JSON/YAML). By extending OpenAPI, agents.json adds flow definitions, links between actions, and LLM‑friendly metadata, solving the problem of ordering multiple API calls for AI agents.

Comparison with MCP and Google A2A

While MCP also lets agents obtain external data, agents.json focuses on interaction with internet service providers, ensuring reliable multi‑step calls. Google’s A2A protocol defines agent.json to describe an agent’s own capabilities, not the provider’s API declarations; the two should not be confused.

How agents.json Works

When an AI agent receives a user intent, it loads the provider’s agents.json (typically hosted at /.well-known/agents.json), extracts available flows, and injects them into the system prompt. The agent then selects an appropriate flow, resolves parameter bindings via links, and executes the sequence of API calls.

Key Concepts

flows : ordered list of actions (API calls) that accomplish a task.

links : define how outputs of one action feed inputs of another.

actions : each maps to an OpenAPI operationId from a source definition.

fields : describe parameters, request bodies, and responses for each action.

Loading agents.json in Python

from agentsjson.core.models import Flow
from agentsjson.core.models.bundle import Bundle
import agentsjson.core as core

# load the agents.json file
data: Bundle = core.load_agents_json(agents_json_url)
flows = data.agentsJson.flows

Setting the System Prompt

from agentsjson.core import ToolFormat

flows_context = core.flows_prompt(flows)
system_prompt = f"""You are an AI assistant that helps users interact with the Stripe API.
You have access to the following API flows:

{flows_context}

Analyze the user's request and use the appropriate API flows to accomplish the task.
You must give your arguments for the tool call as Structured Outputs JSON with keys `parameters` and `requestBody`."""

Configuring Authentication

from agentsjson.core.models.auth import AuthType, BearerAuthConfig
auth = BearerAuthConfig(type=AuthType.BEARER, token=STRIPE_API_KEY)

Executing the Flow

from openai import OpenAI
from agentsjson.core.executor import execute_flows
client = OpenAI(api_key=OPENAI_API_KEY)

query = "Create a new Stripe product for tie‑die tshirts priced at $10, $15, and $30 for small, medium, and large sizes"
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "system", "content": system_prompt}, {"role": "user", "content": query}],
    tools=core.flows_tools(flows, format=ToolFormat.OPENAI),
    temperature=0,
)
response = execute_flows(response, format=core.ToolFormat.OPENAI, bundle=data, flows=flows, auth=auth)
print(response)

Schema Overview

An example agents.json for an e‑commerce site includes info, sources (OpenAPI documents), optional overrides, and a list of flows with detailed actions, links, and fields definitions.

{
  "info": {"title": "Alpaca Trading and Market Data API Methods", "version": "0.1.0", "description": "..."},
  "sources": [{"id": "alpacatrading", "path": "https://.../trading_openapi.yaml"}, {"id": "alpacamarketdata", "path": "https://.../marketdata_openapi.yaml"}],
  "flows": [{
    "id": "order_roundtrip",
    "title": "Place Order and Get Order Status",
    "description": "Places a new order and then retrieves that order's details using the returned order ID.",
    "actions": [{"id": "order_roundtrip_place_action", "sourceId": "alpacatrading", "operationId": "alpacatrading_post_order"}, {"id": "order_roundtrip_get_action", "sourceId": "alpacatrading", "operationId": "alpacatrading_get_order_by_order_i_d"}],
    "links": [{"origin": {"actionId": "order_roundtrip", "fieldPath": "parameters.order_id"}, "target": {"actionId": "order_roundtrip_get_action", "fieldPath": "parameters.order_id"}}],
    "fields": {"parameters": [{"name": "symbol", "type": "string", "required": true}, {"name": "side", "type": "string", "enum": ["buy","sell"], "required": true}], "responses": {"success": {"type": "object", "properties": {"placed_order": {"type": "object"}, "retrieved_order": {"type": "object"}}}}}
  }]
}

Benefits

Optimized natural‑language driving : Users can trigger API operations with plain language instead of manual endpoint calls.

Standardized task flows : Pre‑defined multi‑step flows guarantee correct ordering and reliability.

Enhanced discoverability : Extends OpenAPI endpoint descriptions, making API capabilities easier for LLMs to find and use.

Core Problems Solved

Bridges the gap between APIs designed for developers and large language models.

Ensures reliable multi‑step API execution, avoiding logical errors.

Provides a lightweight, stateless integration that works with existing authentication mechanisms.

The agents.json specification is still community‑driven but is seen as a strong candidate for the future "agent‑centric web protocol," with use cases in automated customer service, social media management, and data analysis.