Normalized API for AI Agents Calling Tools (N-ACT)

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 22 April 2026.¶

Copyright Notice

Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶

Table of Contents

1. Background

AI Agents are applications built using Large Language Models (LLMs). AI Agents typically operate on behalf of some human or organization, and are capable of taking actions through the invocation of functions, also known as tools. [I-D.rosenberg-ai-protocols] provides an overview of protocols and use cases for AI Agents.¶

In enterprise applications of AI Agents - including customer support uses cases - it is very common for the AI Agent to invoke tools provided by other organizations. As an example, consider an enterprise that is a healthcare provider. They have an AI Agent that needs to facilitate appointment scheduling, appointment cancellation, prescription refills, store location and hours lookup, and vaccine scheduling. The actions are all supported by tools which are exposed to the AI Agent through its instructions. The tools, in this case, could be implemented by servers within the enterprise domain - built by their IT department for example. Or, they might be implemented by B2B SaaS providers that offer these capabilities to the entperrise. For example, in the healthcare space, Epic, Cerner, and Meditech are a few of the B2B SaaS providers that are often used by retail healthcare providers.¶

It is very common for enterprises to have dozens, if not hundreds, of different systems providing APIs that might need to be accessed by an AI Agent. This high cardinality is not new. Prior to the advent of large language model technologies, voice and chat bots - and even classic "press 1 for sales, and 2 for support" Interactive Voice Response Systems (IVR) - needed to access large numbers of APIs to provide customer support for end users. Integration of these APIs into IVRs, voice bots and chat bots often represented the most expensive and complex part of deploying those systems - not the training and optimization of the AI model which invokes them.¶

The advent of AI Agents - if anything - only increases the likely cardinality of the number of distinct API sysems that need to be integrated. This is due to increased capabilities of LLMs compared to prior generation AI models. Whereas, in the past, certain use cases where just too difficult to automate (for example, multi-room booking for hotels - is difficult to do on websites, and almost never attempted by voice or chat bots) - now, these may be within reach for automation using AI Agent technology. As a result, we will see more use cases, and therefore even more APIs that need to be integrated.¶

For an AI agent to be effective, it needs more direction than just the enumeration of tools with names and descriptions. Particularly in enterprise and customer support use cases, detailed instructions are required which direct when, how, if and why those tools should be invoked. These instructions guide the AI agent on how to converse with the customer, what kind of information to collect, how to use it to invoke the tools, how to handle the differing responses, and what to do with the data that is returned. We use the term operating procedure to describe an instruction that provides this detail to an AI Agent. An operating procedure is typically specific to a particular task (for example, booking an appointment for a healthcare visit). An operating procedure at the end of the day is a document, containing natural language text with references to tools, tool inputs, and tool outputs. Others have referred to these as skills (see the recent Anthropic blog post here: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills), instructions or even prompts.¶

Here is an abbreviated example of an operating procedure for prescription refill that illustrates this:¶

##Goal

Your goal is to help the user with prescription refill inquiries.

## Prescription Refill Status
Follow this flow if the user:
- is asking about the status of a prescription
 refill request they've made;
- is asking when their prescription refill(s)
  will be ready. For example:
- What's the status of my prescription request?
- I just want an update regarding my prescriptions.
- When will my prescription refill be ready?
### Prescription Lookup
- Use look_up_prescriptions() to look up the user's
  active prescriptions. You must have previously
  authenticated the user and have their account ID.
  If you don't have their accountID yet, perform the
  authentication flow.
### Present Status
- Find the prescriptions which have a status other
  than null and present them to the user along with
  their status.
### Sending Confirmation
- Ask the user if they want to receive a confirmation
  when the refill has been sent to the pharmacy.
- If you have the user's preferred contact method
 (which the you would have gotten earlier from
  look_up_ani_user_by_ani(), use that information
  and send them the confirmation of the appointment
  status along with the appointment details.

As you can see from the example, the operating procedure is a detailed recipe-book - a training manual of sorts - for the AI Agent. It describes API sequencing (for example, that the lookup of prescriptions can only be done after authentication), usage of parameters (that accountID must be included from prior authentication), handling of results (show the list to the user), and so on.¶

Operating procedures are analagous to training manuals for human agents, which similarly instruct them in the sequencing and handling of a call. Instead of invoking tools, humans use web applications to do a similar job. In traditional contact centers, entire teams of people are accountable for creating and maintaining these training manuals. They are essential for ensuring quality of customer support.¶

At the end of the day - operating procedures are what make the AI Agent work. While their generation may be assisted by an AI to facilitate authoring, operating procedures are crafted by human beings using traditional software. The person whose role is to create the operating procedure is called the AI Agent designer - or just designer for short. The software used by the designer to create an AI Agent, including the authoring of the operating procedure, is called the AI Agent platform. To properly create an operating procedure, the designer must be a domain expert - familiar with the appropriate process for performing the task the AI Agent is to perform.¶

Part of task of creating an AI Agent is the selection of the tools to be used. Typically, this selection happens through the authoring of the operating procedure, which makes explicit reference to the tool as in the example above. It is also possible for the designer to select a tool for usage by the AI Agent but not provide any guidance on its usage in the operating procedure (most of the current APIs for AI Agents separate the tool list from the instruction, thus making this possible). While technically this can work, it often results in higher rates of hallucinated tool usage.¶

The choice by a designer on the set of tools that are shown to the LLM (we use the verb show as a synonym for inclusion of information into the model's context window) is referred to as tool selection. The process of tool selection and authorship of the operating procedures happen ahead of the deployment and actual usage of the AI Agent. We refer to this as design time, whereas the usage of the AI Agent by end users is called run time.¶

At run time, a user will begin a session with an AI Agent. At the beginning of the session, the AI Agent is shown the operating procedure and tools, and begins operation.¶

It is becoming increasingly common for AI Agent design systems to make use of multiple distinct AI Agents (called sub-agents) which are each equipped to handle specific tasks. These are called multi-agent systems. Once again using our health care example, one sub-agent might handle prescription refills, while another handles appointment scheduling and cancellation. Each sub-agent would have its own distinct set of operating procedures and tools, appropriate for those tasks. This further reduces the size of the context window at any point in time, reducing hallucination rates. There are various techniques for how these sub-agents are strung together. At the end of the day, it is often done through tool calling, asking the LLM to invoke a tool that transfers the session to a different AI Agent. This is (interestingly) analagous to live human agents in contact centers, which typically have human agents with differing skills. When a customer asks for something which is outside of the expertise for the human agent they are talking to, the human agent transfers the call to a different human agent with the right skill. In essence - that is what is happening in these multi-agent systems.¶

The usage of a designer to select only those tools needed for an agent, and the usage of multi-agent systems, provides progressive tool disclosure. Progressive tool disclosure is a concept wherein an AI Agent is only shown just the set of tools it needs at a given time, and as the conversation flows, more tools are shown.¶

The tools selected by the designer, and incorporated into the operating procedure, are often implemented by the executor through the invocation of APIs on some server. The server exposing those APIs is called an API Server.¶

2. Terminology

Terminology is becoming foundationally important in this emerging AI Agent field. This section summarizes the key terminology and concepts from above.¶

• AI Agent: A software application that makes use of an LLM to perform tasks that require interaction with software systems. With an AI Agent, the LLM can output both text for the user, but it can also request the invocation of tools, which are an interface the LLM can use to access those software systems. AI Agents are composed of two elements: an LLM and an executor. The executor is built using traditional software (e.g., Java, node.js, python, etc) and interfaces with the LLM.¶

• Tool: An interface representing a software system. A tool has a name, a description, inputs and outputs. In AI Agent system, the LLM is responsible for collecting the inputs and requesting the invocation of the tool. The executor actually executes the tool, often through the invocation of APIs, and feeds the results back to the LLM. By convention, tool names use underscores and have a terminating curly bracket, even though they may also take parameters. For example, when we say "the LLM invokes schedule_appointment()" this means that the LLM has made a decision to invoke the tool name schedule_appointment and has synthesized the needed input parameters to the tool¶

• Executor: Also called the orchestrator or orchestration engine. It represents the traditional software component of an AI Agent. The executor funnels messages to and from the end user into the LLM. It receives the outputs of the LLM, and if that output is a request to perform a tool call, the executor runs the tool and provides its output back to the LLM.¶

• Show: The process wherein the executor provides input to the LLM, inclusive of tool call results, by adding it to the context window of the LLM. For example, we say, "the tool call result is shown to the LLM'.¶

• Operating Procedure: A document authored by a human, and shown to an LLM during run-time operation, which instructs the AI Agent on the sequence of tools to invoke, how to interact with the user to collect the data needed for tool invocation, what to do with the results of the tool call, how to handle different conditions based on the output of the tools, and how to handle exceptional conditions. Operating procedures reference tools and their inputs by name.¶

• AI Agent Designer: Synonymous with designer¶

• Designer: A human being whose job is to create operating procedures and perform tool selection during the design phase of the AI Agent.¶

• Tool Selection: The process of selection of the right set of tools to show to an AI Agent for a particular task. By selecting only those tools which are needed for a task, the likelihood of tool hallucination is reduced. Tool selection in the N-ACT framework happens at design time (though the protocol allows this to happen at run time in an interoperable fashion, should that mode be selected by the AI Agent platform vendor).¶

• Design Time: A point in time during which the designer is interacting with the AI Agent platform in the producion of an operating procedure and selection of tools.¶

• Enterprise: The administrative entity on whose behalf an AI Agent operates. Typically the designer is an employee of the enterprise, though this can be outsourced to consulting firms or the AI Agent Platform vendor.¶

• Run Time: A point in time during which an end user is interacting with an AI Agent.¶

• Multi-Agent Systems: An AI Agent wherein its job is broken down into a smaller set of discrete tasks, each handled by a sub-agent that is equipped (via its operating procedure and tool list) to perform that specific task¶

• Sub-Agent: An AI Agent that performs a narrow set of tasks. Multiple Sub-Agents are woven together to form the AI Agent in a Multi-Agent System.¶

• Progressive Tool Disclosure: A technique for reduction of hallucination wherein, as an AI Agent session unfolds, the set of tools shown to the LLM evolves, offering it only the tools it needs to do its job at any point in time.¶

• API Server: A server that exposes APIs which can be invoked via a tool call by the AI Agent¶

• API Provider: The administrative entity that is offering APIs that are of interest to an AI Agent. Typically, the API Provider is different from the enterprise, and is also different in turn from the AI Agent Platorm vendor.¶

• AI Agent Session: A period of time from when an AI agent begins - by having the executor show the LLM the initial operating procedure and tool selection - estabishing initial context - and interacting with the end user - until the end user interaction completes.¶

• AI Agent Platform: A piece of software which includes a design time experience for designers, and a run-time capability for handling AI Agent sessions. Typically built as a cloud service by the AI Agent Platform vendor. Though the AI Agent Platform can be provided by the vendor of the LLM itself, these can be distinct vendors.¶

• AI Agent Platgorm Vendor: The administrative entity that has developed the AI Agent Platform, and made it available for usage by enterprises to author and execute AI Agents.¶

3. Problem Statement

There are multiple problems that are addressed by N-ACT, covering design time and run-time challenges.¶

4. The N-ACT Protocol Goals

The N-ACT protocol (N-ACT is pronounced like the word enact) addresses the underlying problems of tool curation and tool minimization.¶

It has, at its core, the following goals:¶

• Reduce the time and costs for designers to create operating procedures and perform tool selection by simplifying the process of curation¶

• Enable development of AI Agents for enterprises which need access to tools across dozens or hundreds of API servers, typically sold to the enterprise by third party B2B SaaS vendors, by consolidating decision logic on tool selection in the hands of the designer¶

• Simplify adoption by tool vendors by building ontop of the existing API platforms and APIs they already have. The closer the current API surface area is to the ideal tool set for an AI Agent, the less effort is required to implement¶

• Standardize an API signature for tool calling¶

• Tools are just APIs that are optimized for an LLM, but can also be used by traditional software applications too¶

• Authentication and Auhtorization use the existing techniques used for REST APIs offered by the API Vendor¶

• Reduce hallucination risk through tool sculpting¶

• Separation of responsibility - API vendors perform tool sculpting, and the AI Agent designer crafts the operating procedure which instructs the AI Agent on how to use the many tools (across vendors even) that it can use. In other words - one vendor makes tools which independent of the agent, and the other vendor makes agents which make use of those tools.¶

5. Overview of Operation

N-ACT is a web API that defines a pair of REST endpoints - one for enumerating tools available on the server, and the other for invoking a tool on the server. Both of these make use of a tool signature, which is a standardized interface for what a tool looks like - how to describe a tool, and how to invoke it. The API client is implemented by the AI Agent platform, and the rest endpoints are implemented by vendor wishing to expose their APIs as N-ACT tools. It is envisioned that these just end up being new REST APIs added to the existing API surface area of the API Provider.¶

6. Protocol Details

The following provides a detailed specification of the protocol.¶

GET {platform-root}/tools

{
  "toolId" : "0479a45d-ad0a-49d4-94db-75edf00d2ca4",
  "name" : "Lookup Weather",
  "description" : "Invoke this tool to lookup the
                    weather for a given city.",
  "img" : "{optional URL for the tool}",
  "version" : "{versionNum},
  "currentVersion": "{versionNum}",
  "tags" : ["system", "retrievals"]
  "input_parameters" :
  [
    {
    "id" : "city"
    "name" : "City",
    "type" : "string",
    "description" : "The city for the weather
       lookup. For example, Boston or Los Angeles.",
    "required" : true
    }
  ]
  "output_parameters" :
  [
    {
      "id" : "temp-fh"
      "name" : "Temperature in Fahrenheit",
      "type" : "int",
      "description" : "The current temperature
         in the named city."
    }
  ]
}

    {
    "id" : "flight_class"
    "name" : "Flight Class",
    "type" : "enum",
    "description" : "The cabin class for the flight reservation",
    "allowed-values" : {
        [
            {
                "name" : "ECONOMY",
                "description" : "Economy class, the least
                expensive cabin class. Also known as coach."
            },
            {
                "name" : "PREMIUM_ECONOMY",
                "description" : "Premium economy class, the
                second seat tier. More legroom."
            },
            {
                "name" : "BUSINESS",
                "description" : "Business class, the next to top
                seat tier. Offers lie-down seating."
            },
            {
                "name" : "FIRST",
                "description" : "The top tier. Lie down seating,
                luxury meal service, lounge access."
            },

        ]
    }
    "required" : true
    }

7. Invocation API

At run-time, a tool is invoked with the invocation API:¶

POST {platform-root}/tools/{toolID}:invoke¶

The body of this takes the invocation object, an example of which is:¶

{
  "name" : "lookup_weather_by_city",
  "input_parameters" :
  [
    {
    "name" : "City",
    "value" : "Omaha, Nebraska"
    }
  ]

The response should contain the result of the invocation, an example of which looks like this:¶

{
  "output_parameters" :
  [
    {
    "name" : "Temperature in Fahrenheit",
    "value" : 80
    }
  ]

The output MUST include the name which matches to the output name in the signature.¶

It is also possible to request invocation of a specific version of the tool:¶

POST {platform-root}/tools/{toolID}/versions/{versionId}:invoke¶

Traditional HTTP response codes apply to the response, including 5xx for temporary failures and 4xx if the request is formatted correctly. Note that, a 4xx should never happen if the client follows the specification defined here.¶

If the request generates a 5xx, the executor SHOULD retry, rather than show the error to the LLM. However, this is up to the discretion of the AI Agent designer on how long to wait before showing it the error and asking it what to do.¶

8. Relationship to MCP

N-ACT is similar in many ways to the Model Context Protocol (MCP) (https://modelcontextprotocol.io/introduction) which is being driven by Anthropic, but different in others. This section covers both similarities and differences. On the whole, the two protocols tackle a similar problem (facilitating tool calling and serving tool context to LLMs), but differ in their approach (MCP better suited for use cases where less designer control is appropriate, and N-ACT for cases where more designer control is appropriate).¶

Authors' Addresses