[Feature]: OASF extension to support semantic agent search

[aduminuc]

Problem Statement

A compelling use case for agent directory when building agentic apps is to search for agents that are capable of accomplishing a given task.

To implement such search mechanism, one needs a data structure, i.e. an agent record, that captures somehow what the agent is capable of and match it against a description of the task to accomplish.

OASF schema defines already 2 record attributes (https://schema.oasf.outshift.com/0.6.0/objects/record) that could be used to capture what an agent is capable of:

• description, which is a free form text that can describe what the agent can do.
• skills, which is a list of distinct abilities of an agent, taken from a predefined taxonomy (https://schema.oasf.outshift.com/0.6.0/main_skills)

While applying semantic search on the above attributes is useful, it might not be enough: description lacks any structure and leaves too much freedom in defining the agent capabilities, while skills are constrained by the predefined taxonomy and are not able to capture all the nuanced capabilities of a specific agent. Moreover, in our experience, semantic search based on a vector database works much better when using sample queries on top of simple descriptions.

Proposed Solution

We propose an additional approach to define what an agent can do, by allowing the OASF record to define a list of capabilities, where each of them provides, on top of the description, a list of sample queries that the agent is able to address. In this case the semantic search will try to match semantically the user query with one or more sample queries present in such list of capabilities.

Example of the list of capabilities with just one element could be (Note that typically an agent will have more than one element in its list):

capabilities: [
    {
    	“name”: "access policy creation”
    	“description”: “accurately interpret and execute user intents involving the creation, configuration, and definition of detailed access control policies”
    	“query_samples”: [
    		“Allow admin_123@outlook.com access to [cnn.com](http://cnn.com/)”,
    		“block sales and engineering from using social media”,
    		“create a rule allowing '#network sme'  connecting to  private-resources 'internalnets-vpn' using posture profile Windows only”
    }
]

This is very similar to what A2A Agent Card proposes for AgentSkill definition: see name, description, and examples in https://a2a-protocol.org/latest/specification/#554-agentskill-object .

We believe that this way of describing agent capabilities should be independent from A2A AgentCard definition, since it should be applied also to records that do not carry an A2A Agent card. For this reason, we propose to define a new OASF extension that contains only the list of capabilities as defined above.

Note that we are open to suggestions to find the right names for such extension and the names of their attributes (we have used the capabilities for now, just as a placeholder)

Alternatives Considered

No response

Additional Context

No response

Checklist

• I have read the contributing guidelines.
• I have verified this does not duplicate an existing feature request.

[muscariello]

semantic search is outside of agent directory and there is no machinery to do semantic search in a network of agent directory nodes. for scalability reasons. the description field can contain any structured model such a machinery would use.

If such machinery is private, OASF allows creating private extensions.

If the machinery is supposed to become public at some point it seems like a duplication of A2A agent skills into a separate extension. It is unclear how this is going to work.

1. the proposal is to replace or duplicate current AGNTCY Skill Definition with the A2A AgentSkill and extend it to all records. This approach would be a normative change to agent directory which is already available in A2A for local search.

2. the proposal instead adds yet another skill data model which is used by another framework.

In both cases it would constitute a normative change to both OASF and agent directory.

[aduminuc]

semantic search is outside of agent directory and there is no machinery to do semantic search in a network of agent directory nodes. for scalability reasons. the description field can contain any structured model such a machinery would use.

If such machinery is private, OASF allows creating private extensions.

If the machinery is supposed to become public at some point it seems like a duplication of A2A agent skills into a separate extension. It is unclear how this is going to work.

1. the proposal is to replace or duplicate current AGNTCY Skill Definition with the A2A AgentSkill and extend it to all records. This approach would be a normative change to agent directory which is already available in A2A for local search.
2. the proposal instead adds yet another skill data model which is used by another framework.

In both cases it would constitute a normative change to both OASF and agent directory.

The idea is to implement the semantic search as a local search over a directory node, not as semantic search in the network, because of the scalability reasons you rightfully mention.

We can definitely opt for a private extension, we thought however it could be generally useful for any semantic search implementation, irrespective if ours is going to become public or not.

The proposal does not intend to replace AGNTCY skill definition and it's not meant to extend to all records. The proposal aims at adding an extension that list the capabilities of an agent in the way we describe (i.e. with query samples). Being an extension, it should not constitute a normative change, it's a way to describe capabilities that could be used to do semantic search.

[muscariello]

I am not suggesting anything in particular. Just trying to understand a proposal that may have significant design implications.

This kind of search as you describe is local, and is also outside of agent directory. Which already supports local search internally.

If the search is run by an external tool over all records, the new search substitutes to the normative way to do search in agent directory.

This would replace search as currently done and therefore it is normative or a design fork.

Like I said above, if the tool runs outside of agent directory the existing fields available for all records can be customized as being payload for agent directory, e.g. the description field which can contain an inner data model that such tool can parse.
If instead an outer data model is required (where the data model is actually used by agent directory for doing search) this requires a normative change which forks from the current design.

The proposal needs to clarify the scope as the proposed extension modifies core agent directory functionality like search.

[aduminuc]

The semantic search would not replace the existing local search already provided by the directory.

It is an additional tool that we would like to build on top of the directory. To do so we would like the data described above (list of capabilities with query samples) to be present somewhere in the record.

Are you suggesting to hide these data in the descriptor field? This would mean that they would not be explicit in the oasf schema.
This would certainly do the job, but I feel it would not leverage the principle of OASF being an extensible schema where it’s possible to add definitions for specific tools and use cases. What do you think?

If adding an extension is not a viable option, we could probably use the existing A2A agent card extension to achieve the same instead , but also in this case it would be a bit of misuse of that extension.

I am open to any option that would make the implementation of our use case easier and in the spirit of OASF.

[muscariello]

When you say "on top" you mean outside. Therefore it would mean for some records and not for all records.

That's why I was suggesting to create an extension like for A2A cards.
Moreover this tool will be public or private.

If the tool is publicly available and the community can use it then it is just like all the other extensions.
If it is a private tool not publicly available it would be a private extension.

However the example you gave uses a search function which is applied after all the other search functions happened already.

The current search function is a meta-search mechanism in two layers: single node search and network node search with pull through cache.

The search function you describe happens after meta-search, on some inner data which can be stored either in the description field like you say or with a structured data model like the A2A AgentSkill model.

This is exactly the same as the current integration for A2A. Notice that in A2A the AgentSkill data model is an inner model which is currently payload for agent directory.

So either you want to support another local registry (just like we support A2A registry), say MY_REGISTRY and duplicate search metadata in the same way A2A does but applied to other data.

I wonder if this is an extension to the A2A registry or a normative change in AGNTCY agent directory or effectively the creation of MY_REGISTRY as yet another local registry.

I think you need to clarify that.

[aduminuc]

When you say "on top" you mean outside. Therefore it would mean for some records and not for all records.

That's why I was suggesting to create an extension like for A2A cards. Moreover this tool will be public or private.

Ok, I think we agree. Let's create an extension.

If the tool is publicly available and the community can use it then it is just like all the other extensions. If it is a private tool not publicly available it would be a private extension.

We are not sure if this tool will be public or not. I guess we should start with a private extension then and make it public if needed.

In such a case, does this mean we don't need to document the format? Would the directory accept a record holding a private extension?

[muscariello]

Please have a look at how OCSF manages private extensions.

https://github.com/ocsf/ocsf-schema/blob/main/extensions.md

Currently we have none in OASF but this approach must be followed.

This file is currently empty in OASF.

A UID must be reserved to avoid you get collisions with other public extensions.

If the private extension becomes public at some point it won't collide.

[aduminuc]

Thanks. Reserving the UID in the corresponding file in OASF is the only thing to do?

How does directory handle records carrying private extensions?

[muscariello]

We will document this in preparation of the first private extension.
Stay tuned. It will take some time because of ongoing vacations.

[aduminuc]

After further discussions, we realized that the extension we are proposing is about listing examples of usage of the agents described in the record. This seems to be generic and not necessarily tight to the semantic search use case.

Another use use case for example could be instructing a client about the best way to interact with the agent being described by the record.

For this reason, we are proposing to make the extension public and be more generic.

Here is an example of a record carrying this extension:

{
  "name": "firewall-policy-assistant",
  "authors": [
    "John Doe"
  ],
  "created_at": "2025-08-31T23:20:50.520Z",
  "description": "Assistant for ACME firewall that can answer documentation questions about such firewalll, create new access policy rules, report on existing firewall objects, policies, and configurations, provide recommendations for policy optimization, and report on firewall-related customer support cases.",
  "domains": [],
  "skills": [],
  "version": "1.0.0",
  "locators": [],
  "extensions": [
    {
      "name": "schema.oasf.agntcy.org/features/usage_examples",
      "data": {
        "usage_examples_groups": [
          {
            "name": "documentation",
            "description": "answer documentation questions about ACME Firewall",
            "prompt_examples": [
              "What is the ACME Firewall?",
              "How do I create a new access policy rule?"
            ]
          },
          {
            "name": "createNewAccessPolicyRule",
            "description": "create new access policy rules",
            "prompt_examples": [
              "Create a new access policy rule to allow SSH traffic from 1.2.3.4.",
              "Create a rule on policy Default Access Policy to deny HTTP traffic to a network any-ipv4."
            ]
          },
          {
            "name": "policyConfigurationInquiry",
            "description": "report on existing firewall objects, policies, and configurations",
            "prompt_examples": [
              "List my access policies.",
              "What network objects are targeted by policy Default Access Policy?"
            ]
          },
          {
            "name": "customerSupport",
            "description": "report on firewall-related customer support cases",
            "prompt_examples": [
              "List my firewall support cases.",
              "What is the status of support case 12345?"
            ]
          }
        ]
      }
    }
  ],
  "schema_version": "0.6.0"
}

We could enhance the extension proposed by including also examples of outputs from the agent.