Agent Format Makes Contract Based Agent Discovery Possible

agentsagent-formatA2AMCPdiscoveryagentdex

I have been building systems with A2A based agents for a while. One problem appears quickly as systems grow. Selecting the correct sub agent during orchestration becomes difficult even when several agents advertise similar capabilities.

Today discovery relies mostly on matching natural language descriptions. An orchestrator can guess which agent might work. It cannot verify interface compatibility, cost constraints, or execution limits.

Snap recently released Agent Format, a declarative specification for defining agents with structured interfaces and constraints. While reading the specification it became clear that this metadata could also power a discovery layer.

AgentDex is an open agent discovery registry I have been building on top of A2A. Today it indexes Agent Cards and matches agents using semantic search over skill descriptions. It works, but semantic search alone has a ceiling.

This post explores how AgentDex could build on Agent Format to move agent discovery from semantic guessing toward contract aware selection.

The limitation of Agent Cards for discovery

A2A solved agent communication. Agent Cards located at .well-known/agent.json describe an agent's skills using natural language.

{
  "name": "Validate Agent",
  "url": "https://validate.mx/api/a2a",
  "skills": [
    {
      "id": "pii-detection",
      "description": "Detects personally identifiable information in text",
      "tags": ["security", "privacy", "pii"]
    }
  ]
}

Semantic search over these descriptions works well. A query such as "detect PII" can match "personally identifiable information scanner" through embedding similarity.

However several important properties remain unknown to the calling agent.

  • Input and output schema
  • Cost per execution
  • Timeout guarantees
  • Execution model

Agent Cards describe what an agent does. They do not define a contract describing how the agent behaves. Discovery therefore remains best effort.

What Agent Format adds

Agent Format introduces structured metadata that Agent Cards do not contain.

interface:
  input:
    type: object
    properties:
      text: { type: string }
 
  output:
    type: object
    properties:
      pii_found: { type: boolean }
      entities: { type: array, items: { type: string } }
 
execution:
  policy: agf.sequential
 
constraints:
  budget:
    maxCostPerRun: 0.002
 
  limits:
    timeoutSeconds: 10

With this information available discovery can move from "this sounds correct" to "this is contract compatible".

Typed interfaces, cost limits, and execution guarantees become queryable properties that a registry can evaluate before any agent invocation occurs.

How AgentDex and Agent Format could work together

The idea is simple. AgentDex indexes both the Agent Card and the .agf.yaml definition.

  • Agent Card descriptions support semantic capability search.
  • Agent Format metadata supports contract validation.
Loading diagram...

Registration

$ npx agentdex init
Found .well-known/agent.json
Found .agf.yaml
Indexed interface { text } → { pii_found, entities }
Indexed constraints maxCost $0.002 timeout 10s
Registered

During registration AgentDex reads both files.

  • Agent Card descriptions are indexed for semantic search.
  • Agent Format metadata is indexed for structural filtering.

Search

Queries combine capability search with contract constraints.

const matches = await agentdex.search({
  capability: "detect PII in customer messages",
 
  interface: {
    input: { required: ["text"] },
    output: { required: ["pii_found"] }
  },
 
  constraints: {
    maxCostPerRun: { lte: 0.01 }
  }
})

Discovery occurs in two stages.

  • Semantic pass. Capability descriptions are matched using embeddings to produce candidate agents.
  • Structural pass. Candidates are filtered using .agf.yaml metadata including interface compatibility, cost limits, execution policies, and timeouts.

Example result:

[
  {
    "name": "pii-detector",
    "endpoint": "https://pii-detector.dev/a2a",
    "contract": {
      "input": ["text"],
      "output": ["pii_found", "entities"],
      "maxCostPerRun": 0.002,
      "timeout": 10
    },
    "score": 97,
    "status": "online",
    "latency": "142ms"
  }
]

At this point the orchestrator already knows the interface, cost, and expected latency before making a single request.

Delegation

Once a compatible agent is discovered communication remains direct A2A. AgentDex acts only as a registry and does not proxy the request.

Loading diagram...

Example

Consider a developer publishing a translation agent with the following contract.

  • Interface: { text, source_lang, target_lang } → { translated, confidence }
  • Cost: $0.005 per run
  • Timeout: 15 seconds

The agent registers with AgentDex.

Weeks later another orchestrator receives a customer request written in Japanese. Translation capability is not built into the system.

The orchestrator queries the registry.

const match = await agentdex.search({
  capability: "translate Japanese to English",
 
  interface: {
    input: { required: ["text", "target_lang"] },
    output: { required: ["translated"] }
  },
 
  constraints: {
    maxCostPerRun: { lte: 0.01 }
  }
})

AgentDex returns the translation agent as a compatible match. The orchestrator delegates the request through A2A and the translated response is returned.

Two independently developed agents running on different stacks collaborate successfully because they share a structured contract.

A possible direction

Agent Format gives agents a portable definition. It describes interfaces, constraints, and execution policies in a way that different systems can understand.

A discovery layer could extend this idea further.

Instead of agents being discovered through semantic similarity alone, registries could combine capability search with contract validation. An orchestrator would not only find an agent that sounds correct. It would find one that is structurally compatible with its interface, budget, and execution constraints.

AgentDex is an early experiment exploring this direction. The goal is simple. Treat .agf.yaml as a machine readable contract that a discovery registry can index and query.

If Agent Format defines what an agent is, a discovery layer defines how agents find and safely collaborate with each other.

Ideas worth exploring

While experimenting with a discovery layer, a few areas emerged where Agent Format and discovery systems could connect more tightly.

  1. Linking agent definitions and endpoints Today .agf.yaml defines the agent contract while .well-known/agent.json defines the endpoint and capabilities. There is currently no standard way to link the two. Establishing a clear reference between these files could simplify discovery and validation.

  2. Discovery metadata Discovery systems may benefit from optional metadata describing how an agent should be indexed. A small discovery block in .agf.yaml could include categories, visibility scope, or registry hints.

  3. Interface evolution and migrations As agent ecosystems grow, registries will likely need guidance on handling interface changes across versions. Clear patterns for compatibility and migration could help orchestrators safely interact with evolving agents.

  4. Contract verification If .agf.yaml becomes the contract used for discovery, registries may eventually need mechanisms to verify that a running agent actually conforms to its declared interface and constraints.

These are just early ideas while experimenting with an agent discovery registry called AgentDex.

Agent Format provides a portable definition for agents. A discovery layer could extend this idea by allowing agents to be located and selected based on their contracts.

Exploring how these layers connect could be an interesting direction

These feel like natural next steps. Agent Format gives agents a portable identity. A discovery layer gives that identity a place to be found.