What does "Agent Descriptor Files" mean?

Agent Descriptor Files are machine-readable description files for AI agents or for interfaces that AI agents are intended to use. The term does not refer to a uniform file format or a universally supported standard. Such a file can describe capabilities, endpoints, and authentication requirements. Publishing such a file does not guarantee automatic discovery by AI systems or access to your systems.

A single file is called an Agent Descriptor File or Agent Description File . We use the abbreviation ADF exclusively in this sense; in other fields, the abbreviation may have different meanings.

Agent Descriptor Files: two different tasks

Before you plan to create an agent description file, clarify what the file should describe . Two tasks need to be distinguished:

• Describe an agent: What tasks does the agent perform? What skills does the agent offer? Which protocol can you use to contact the agent?
• Describe an interface: What functions does your company provide? What inputs does the interface require? What answers does the interface provide?

An agent that processes requests is not the same as an API. An API explained simply: An API is a standardized programming interface through which two software systems exchange data or functions. The long form, Application Programming Interface, describes... Click to learn more , which returns available appointments. Both may require a machine-readable description, but not necessarily the same format.

For you as an SME decision-maker, the first question is therefore: Which business process do you want to make accessible in a controlled manner? Only then can you decide what kind of description is required.

What information do Agent Descriptor Files contain?

Agent Descriptor Files (ADFs) make technical properties evaluable in a structured manner. The required information and field names are determined by the respective specification. A protocol-specific format may be required for agent communication; API descriptions follow their own specification.

• Identity: Name, description and, if applicable, responsible provider.
• Skills: Offered tasks or functions with clear boundaries.
• Endpoints: Technical addresses for communication with the agent or interface.
• Protocols: Agreed rules for inquiries and responses.
• Versions: Information on the description format and the interface offered.
• Authentication requirements: Information on how a calling client must prove its identity.

A description can help a compatible client prepare for integration. However, understandable field names alone do not create interoperability. The client must support the specific schema and the associated protocol.

Schematic JSON example

The following example illustrates the basic idea only. The JSON does not correspond to an A2A agent card or an OpenAPI description and is not a template for a production integration. The endpoint is fictitious; credentials are not included.

{
  "name": "Termin-Auskunft",
  "description": "Gibt verfügbare Zeitfenster zurück.",
  "version": "1.0",
  "capabilities": [
    {
      "name": "Zeitfenster lesen",
      "readOnly": true
    }
  ],
  "endpoint": "https://example.com/api/availability",
  "authentication": {
    "required": true,
    "scheme": "Bearer"
  }
}

The entry "Bearer" merely describes a request. The server must check the transmitted token and decide which data the client is allowed to read. The "readOnly" specification also does not replace server-side access control.

Agent Descriptor Files and specific formats: the differences

Agent Card, OpenAPI, and AI Plugin Manifest are not interchangeable names for the same file. For implementation, the specific specification version and documented support by the intended client are crucial. The following explanations describe the functions of the formats, not a tested product compatibility.

Agent Card in the A2A protocol

An agent card describes an agent in the A2A protocol for communication between agents. An agent card is not a general description of a company website.

• Specifications: Check the A2A version used and the required information.
• Compatibility: Both systems involved must support the required protocol version and its functions.
• Findability: A published agent card does not mean that every assistant can automatically find or use the agent.

OpenAPI for interfaces

OpenAPI describes HTTP APIs. The focus is on interface operations, inputs, responses, and security requirements – not the identity of an independently acting agent.

• Documentation: Humans and suitable tools can replicate the described operations.
• Version support: Check which OpenAPI version and features the integration tool supports.
• Agent usage: The client requires a defined integration path. Publishing an API description does not automatically establish this connection.

If you want to make company services accessible via an interface, the article OpenAPI for business services explains the path from process to API.

AI Plugin Manifesto

An AI plugin manifest describes an integration. An associated API description documents the interface that this integration can use. The manifest, agent card, and API description each fulfill different functions.

• Historical instructions: Do not transfer past plugin support to today's assistants without checking.
• Product status: Check the publisher, documentation date, and the currently planned integration path.
• Recognition: An existing manifest or a known filename does not guarantee automatic support.

Agent Descriptor Files: Description is not a permission

Agent descriptor files describe capabilities and interfaces. These files do not grant access rights.

Authentication verifies who is making the request. Authorization determines what the requester is allowed to do. A public description may explain these requirements, but may not contain secret keys or access tokens.

If an agent is supposed to book appointments, place orders, or change customer data, you need additional controls:

• permissions: What actions is the calling client allowed to perform?
• Confirmations: Which actions require human approval?
• Logging: How are actions and changes documented in a traceable manner?

These controls must be implemented in the executing application or on the server side. A description file does not replace access control.

Separating Agent Descriptor Files, Website Content, and Interfaces

• llms.txt: A proposed orientation file for ContentContent encompasses all intentionally published digital content on websites, in online shops, on social media channels, in newsletters, and in other digital environments. If you want to know more... Click to learn moreThe file can reference relevant information, but does not itself provide an executable interface.
• Structured data: Descriptive markup for website information, such as about a company or offer. The markup itself does not perform any actions.
• OpenAPI: A description of an HTTP API. The functions must be provided through an implemented interface.
• Agent description file: This is a collective term used here. For integration, you need a specific format supported by the client.

Discoverability, technical responsiveness, and authorization are three distinct properties. A client can find a description without supporting the protocol. A compliant client can access an endpoint without gaining access to protected data.

Our architectural approach at Berger+Team

At Berger+Team, my freelance collective in Bolzano, we view brand information, website content, and technical services as an interconnected system with separate tasks. In this architectural approach, btlabs Core refers to our digital foundation with a central content repository. btlabs Core is not an ADF standard and does not demonstrate universal agent support.

Agent Descriptor Files are to be distinguished from other building blocks:

• Identity files: Describe company and brand information.
• Table of contents: Provides guidance on approved content.
• OpenAPI description: Documents the HTTP interfaces provided for this purpose.
• Tools endpoint: Provides access to the implemented functions; access and permissions are regulated separately.

This separation describes an architectural decision, not a confirmed compatibility with a specific assistant. We explain the central database in the article " Structured Company Knowledge with btlabs Core".

AI-powered booking agents are a possible development stage, not a guaranteed standard feature. For reservations or orders, the process, interface, client support, and approval rules must be specifically implemented and tested.

What solution does your company need?

From my over 20 years of experience in branding, I know that branding is the conscious, strategic development of a brand. Branding determines how your company is perceived, what people recognize it by, and why they trust it... Click to learn more . In web development and digital strategy, my priority is clear: first clarify the business benefits, then select the technical specifications. When working with SMEs, it's crucial for me that any additional technology supports a comprehensible use case. Agent Descriptor Files are not an end in themselves.

• You would like to inform: Prioritize reliable content, clear services, up-to-date contact information, and an accessible website. An agent description file is not automatically required for this.
• You want to provide data or functions: Plan a documented API with appropriate access rules and a specifically designated client.
• You want to connect agents: Check for a suitable protocol and its support on both sides.
• You want to enable actions: Additionally, define permissions, confirmations, and traceable processes.

We cover preparing a website for use by AI agents under Agent Readiness . The business focus on such users is described as B2A, or Business to Agent.

Checklist for Agent Descriptor Files

• Set a goal: Should the client read information, contact an agent, or execute a function?
• Choose format: Use the specification required by the specific integration path.
• Document support: Record the client, version, supported features, and audit date.
• Validate description: Check the schema, mandatory fields, and consistency with the actual interface.
• Test security: Check for missing, invalid, and insufficiently authorized access tokens, as well as permissions for write actions.
• Versioning changes: Update the description, interface, and tests together.

Frequently Asked Questions about Agent Descriptor Files

Is there a binding ADF standard?

Agent Descriptor Files (ADF) are a collective term used in this article; ADF does not refer to a specific file format. For your implementation, you will need a concrete specification, its version, and a client that supports the format.

Which file does my website need?

It depends on the purpose: For informational purposes, good content is paramount; for API use, a documented interface is essential; and for agent communication, a suitable protocol is crucial. First, clarify which client will use the file and for what purpose.

Do ChatGPT and other wizards automatically read such files?

Do not assume automatic detection. For the intended assistant, require a documented integration path and a reproducible test. The existence of a file does not prove support.

Does an agent description file replace an API?

No. A description doesn't implement a function. If your agent is to retrieve current data or trigger an action, you need an accessible and appropriately secured interface.

Is an agent allowed to perform actions based on the description?

No. The description does not grant permission. Your server must verify identity, access rights, and, if necessary, additional permissions before any action is performed.

How do I check compatibility and up-to-dateness?

Record the format version, client version, and test date, and verify the integration against the associated documentation. Repeat tests whenever capabilities, endpoints, or security requirements change to ensure that the description and actual behavior match.