AI Agent Discovery and Invocation Protocol

3.1. Core Fields

The following are the core fields of an agent metadata document:¶

• id (string): A globally unique identifier for the agent. This could be a UUID or a similarly unique value, assigned by the registry upon registration or by the agent provider in advance. This ID is used to refer to the agent in all subsequent operations (e.g., retrieval, invocation routing).¶

• name (string): A human-readable name for the agent (e.g., "Chinese-English Translator Agent"). Names need not be unique but should be descriptive.¶

• description (string): A detailed description of the agent, its purpose, and capabilities in natural language. This helps both human users and semantic search algorithms understand what the agent does.¶

• version (string): The version of the agent or its metadata (e.g., "1.0.0"). This allows tracking of agent updates over time.¶

• publisher (string): The name or identifier of the entity publishing the agent (e.g., an organization name or developer name).¶

• capabilities (array of strings): A list of capabilities the agent supports. Capabilities are high-level descriptors (like tags or categories) that clients can filter by. Examples: ["translation", "summarization", "text_generation"].¶

• tags (array of strings): Additional tags for search and categorization (e.g., ["nlp", "chinese", "transformer_model", "cloud"]). Tags differ from capabilities in that they can include broader or orthogonal categories (like domain, language support, deployment model, etc.).¶

• endpoint (string): The URL of the agent's invocation endpoint. If the agent is behind a gateway, this could be either the direct endpoint or, if direct access is not allowed, a gateway path (e.g., the gateway might provide a unified endpoint like /agents/{id}/invoke and internally route to the actual agent endpoint).¶

• supported_languages (array of strings, optional): A list of languages the agent supports (e.g., ["en", "zh", "fr"]). For agents dealing with natural language tasks, this field indicates which languages are handled. If omitted, the agent is either language-agnostic or should not be filtered by language.¶

• authentication (object, optional): Describes the authentication mechanism required to invoke the agent. This object may include:¶

  • type (string): e.g., "api_key", "oauth2_bearer", "mtls" (mutual TLS), "none".¶

  • instructions (string): Human-readable note or URL for obtaining credentials.¶

  • scopes (array of strings): If OAuth 2.0 is used, the OAuth scopes required.¶

  If no authentication is required, this field can be omitted or set with type: "none".¶

• status (string, optional): Operational status of the agent (e.g., "active", "inactive", "deprecated"). The registry may use this to filter out agents that are not currently available.¶

• additional fields: Additional fields may include metadata about rate limits (e.g., max calls per minute), pricing info (if the agent charges per use), or links to documentation. These are not standardized here but can be included in agent metadata as needed.¶

3.2. Operations and I/O Schema

Each agent MUST describe its input and output formats. This is done using the operations field:¶

• operations (array of objects): A list of operations the agent supports. Each operation object has:¶

  • name (string): The operation name/identifier (e.g., "translateText", "summarize").¶

  • description (string): A description of what the operation does.¶

  • inputs (object): A JSON Schema describing the expected input. This allows clients to understand what data to send. The JSON Schema can specify required fields, types, enums, etc.¶

  • outputs (object): A JSON Schema describing the output format.¶

  • examples (array of objects, optional): Example input/output pairs. Each example is an object {"input": {...}, "output": {...}} showing a sample invocation.¶

If an agent has a single operation, this array will have one element. If it can do multiple distinct tasks, each is listed here. Some agents may not have structured operations (e.g., a general-purpose language model that just produces text). In that case, the operations field might include a generic operation like {"name": "generate", ...}.¶

If an agent has a single operation, this array will have one element. If it can do multiple distinct tasks, each is listed here. For simple agents with one primary function, an alternative is to use top-level inputs and outputs fields directly (instead of an operations array). In that case, the whole agent effectively has one implied operation. This spec allows both styles, but using operations is recommended for future extensibility.¶

3.3. Example Agent Metadata

Below is an example metadata JSON for a translation agent:¶

json { "id": "agent-12345", "name": "Chinese-English Translator", "description": "Translates text between Chinese and English with high accuracy using a fine-tuned model.", "version": "1.2.0", "publisher": "ExampleAI Inc.", "capabilities": ["translation"], "tags": ["nlp", "chinese", "english", "cloud"], "endpoint": "https://api.example.com/agents/translate", "supported_languages": ["en", "zh"], "authentication": { "type": "api_key", "instructions": "Include 'X-API-Key' header with your API key." }, "status": "active", "operations": [ { "name": "translateText", "description": "Translates text from source language to target language.", "inputs": { "type": "object", "properties": { "text": {"type": "string"}, "source_language": {"type": "string", "enum": ["en", "zh"]}, "target_language": {"type": "string", "enum": ["en", "zh"]} }, "required": ["text", "source_language", "target_language"] }, "outputs": { "type": "object", "properties": { "translated_text": {"type": "string"} } }, "examples": [ { "input": {"text": "你好世界", "source_language": "zh", "target_language": "en"}, "output": {"translated_text": "Hello World"} } ] } ] } ¶

This metadata tells us the agent is an active translation agent for Chinese and English, requires an API key for authentication, and has one operation translateText with a clear input/output schema.¶

4.1. Registry Overview

The Agent Registry is a network-accessible service that:¶

1. Allows agents (or their administrators) to register metadata about the agent.¶

2. Stores and indexes these metadata entries for efficient search.¶

3. Provides endpoints for clients to query and retrieve agent information.¶

A registry may be operated by an organization for its internal agents, or by a third party acting as a directory of agents across multiple providers. Multiple registries can coexist; interoperability between registries is facilitated by consistent metadata formats, though formal registry federation is out of scope for this draft.¶

4.2. Agent Registration

An agent (or its administrator) registers with the registry by sending its metadata to a registration endpoint:¶

• Endpoint: POST /agents¶

• Request Body: The agent metadata JSON document.¶

• Response: On success, the registry returns 201 Created (if a new agent was added) or 200 OK (if an existing agent was updated), with the stored agent metadata (including the assigned id if the agent did not provide one). If validation fails (e.g., missing required fields), the registry returns a 400 Bad Request with error details.¶

The registry MUST validate the metadata against the schema. Registration may require authentication (for example, the registry only allows verified publishers to register agents).¶

Updates to an agent's metadata (e.g., a new version, changed endpoint, etc.) can be done via a PUT request to the agent's entry:¶

• Endpoint: PUT /agents/{id}¶

• Request Body: Updated metadata.¶

• Response: 200 OK on success; 404 Not Found if no agent with that ID exists; 403 Forbidden if the requester is not authorized to update that agent.¶

4.3. Querying Agents

Clients query the registry using the search endpoint. The protocol supports two types of queries:¶

5.1. Invocation Request

To invoke an agent, the client sends an HTTP POST request to the agent's invocation endpoint with a JSON body containing the input data for the agent's task.¶

• Method: POST¶

• URL: The endpoint URL from the agent's metadata (e.g., https://api.example.com/agents/translate). If a gateway is used, the URL might be a gateway-provided path.¶

• Headers:¶

  • Content-Type: application/json¶

  • Authentication header as required (e.g., Authorization: Bearer <token> or X-API-Key: <key>).¶

• Body: A JSON object containing input data as per the agent's input schema.¶

For example, invoking the translation agent:¶

json { "text": "Hello, how are you?", "source_language": "en", "target_language": "fr" } ¶

This corresponds to the agent's expected input fields. If the agent had multiple operations and a unified endpoint, there might be an additional field to specify which operation or capability to use. For instance, the JSON could include something like "operation": "translateText" if needed. Alternatively, different operations could be exposed at different URLs (e.g., /agents/xyz/translate vs /agents/xyz/summarize), in which case the operation is selected by the URL and no extra field is required.¶

The protocol does not fix a specific parameter naming; it defers to the agent's published schema. The only requirement is that the client's JSON must conform to what the agent expects. For interoperability, using clear field names and standard data types (strings, numbers, booleans, or structured objects) is encouraged. Binary data (like images for an image-processing agent) should be handled carefully: typically, binary inputs can be provided either as URLs (pointing to where the data is stored), or as base64-encoded strings within the JSON, or by using a multipart request. This specification suggests that if agents need to receive large binary payloads, they either use URL references or out-of-scope mechanisms (like a separate upload and then an ID in the JSON). The core invocation remains JSON-based for simplicity and consistency.¶

Headers: If authentication is required (see Security section), the client must also include the appropriate headers (e.g., Authorization: Bearer <token> or an API key header) as dictated by the agent's metadata. The invocation request may also include optional headers for correlation or debugging, such as a request ID, but those are not standardized here.¶

5.2. Invocation Response

The agent (or gateway) will process the request and return a response. The status code and JSON body of the response follow these guidelines:¶

• Success (2xx status): If the agent successfully performed its task and produced a result, the status SHOULD be 200 OK (or 201 Created if a new resource was created as a result, though usually for these actions 200 is fine). The response body will contain the output data in JSON. Ideally, the output JSON conforms to the agent's advertised output schema.¶

  For example, for the translation request above, a success response might be:¶

  json { "translated_text": "Bonjour, comment êtes-vous?" } ¶

  Here the JSON structure matches what was described in the agent metadata's outputs. If the output is complex (e.g., multiple fields or nested objects), those should appear accordingly. The response can include other informational fields if necessary (for example, some agents might return usage metrics, like tokens used or time taken, or a trace id for debugging, but these are optional and out of scope of the core spec).¶

• Client Error (4xx status): If the request was malformed or invalid, the agent returns a 4xx status code. The most common would be 400 Bad Request for a JSON that doesn't conform to the expected schema or missing required fields. For example, if the client omitted a required field target_language, the agent might respond with 400. The response body SHOULD include an error object explaining what went wrong. We define a simple standard for error objects:¶

  json { "error": { "code": "InvalidInput", "message": "Required field 'target_language' is missing." } } ¶

  Here, "code" is a short string identifier for the error type (e.g., InvalidInput, Unauthorized, NotFound), and "message" is a human-readable description. The agent can include additional details if available (e.g., a field name that is wrong, etc.). If the error is due to unauthorized access, 401 Unauthorized or 403 Forbidden should be used (with an appropriate error message indicating credentials are missing or insufficient). If the agent ID is not found (perhaps the client used an outdated reference), 404 Not Found is appropriate.¶

• Server/Agent Error (5xx status): If something goes wrong on the agent's side during processing (an exception, a timeout while executing the task, etc.), the agent (or gateway) returns a 5xx status (most likely 500 Internal Server Error or 502/504 if there are upstream issues). The response should again include an error object. For example:¶

  json { "error": { "code": "AgentError", "message": "The agent encountered an unexpected error while processing the request." } } ¶

  The agent might log the detailed error internally, but only convey a generic message to the client for security. A 503 Service Unavailable might be returned if the agent is temporarily overloaded or offline, indicating the client could retry later.¶

• Status Codes Summary: In short, this protocol expects the use of standard status codes to reflect outcome (200 for success, 4xx for client-side issues, 5xx for server-side issues). Agents should avoid using 2xx if the operation did not semantically succeed (even if technically a response was generated). For example, if an agent is a composite that calls other services and one of those calls fails, it should propagate an error rather than returning 200 with an error in the data.¶

5.3. Additional Considerations for Invocation

• Streaming Responses: Some agents (especially those wrapping large language models) may produce results that are streamed (for example, token-by-token outputs). While this base protocol assumes a request-response pattern with the full result delivered at once, it can be extended to support streaming by using chunked responses or WebSockets. For instance, an agent might accept a parameter like stream: true and then send partial outputs as they become available. This is an advanced use case and not elaborated in this draft, but implementers should consider compatibility with streaming if real-time responsiveness is needed.¶

• Batch Requests: If a client wants to send multiple independent requests to an agent in one go (for efficiency), the protocol can support that by allowing an array of input objects in the POST body instead of a single object. The response would then be an array of output results. This is optional and depends on agent support.¶

• Idempotency and Retries: Most agent invocations are not strictly idempotent (since an agent might perform an action or have side effects), but many are pure functions (e.g., translate text). Clients and gateways should design with retry logic carefully — if a network failure happens, a retry might re-run an operation. It's best to ensure that agents' operations are either idempotent or have safeguards (for example, an operation that sends an email might have an idempotency key).¶

• Operation Metadata: In cases where the agent defines multiple operations in its metadata, the invocation interface might allow a generic endpoint that accepts an operation name. Alternatively, each operation could be a sub-resource. This draft leaves the exact mechanism flexible: an implementation could choose one of these approaches. The key is that the invocation uses POST and a JSON body following the agent's schema.¶

6.1. Non-Goals

ASR explicitly does not provide:¶

• Name-to-address resolution¶

• Global or persistent agent identifiers¶

• Replacement for DNS, ANS, or URI-based registries¶

ASR answers the question "Which agent(s) should handle this task now?" rather than "Where is agent X located?".¶