Support for Hosting Multiple Agents under a Single Base URL

[ognis1205]

As stated below:

https://google.github.io/A2A/#/documentation?id=agent-card

Currently, I understand the specification maps a single agent to a single host (base URL). However, there may be cases where a host serves as a routing environment for multiple agents, mapping them to different paths under the same base URL.
Do you plan to incorporate such a use case into the specification in the future?For example, something like:

https://<BASE_URL>/.well-known/agents.json

could return a list of AgentCards, where each entry includes the path for the corresponding agent.

[alain-sv]

This is very much needed. We should expect a single domain to host multiple agents.
@ognis1205 's suggestion to include path to each agent's individual card is nice, but a list of all agent cards in agents.json would work too.

[ognis1205]

Thanks for the feedback, @alain-sv! I feel the same way, but I’d like to hear if there’s any particular reason behind the current design.

[IhateCreatingUserNames2]

https://github.com/IhateCreatingUserNames2/Aira

"AIRA (Agent Interoperability and Resource Access) enables AI agents built with different frameworks to discover and communicate with each other using a standardized protocol. It bridges the gap between the Agent-to-Agent (A2A) protocol and the Model Context Protocol (MCP) to create a unified ecosystem where AI tools and resources can be shared across different agent implementations."

This can work for this.

Its a concept of a A2A network, where Agents can Connect and Share Tools...

[robert-at-pretension-io]

That does not seem to have official implementation of A2A?

[kthota-g]

Thanks for starting the thread. Currently if you like more than one agent to be available for open discovery on the same host url, the agent card should be available at a different path per agent or they have to be available via a different port. If don't require open discovery for the agent, you can expose the agent card at any url and have the A2AClient read from the custom url.

As documented in Agent Discovery topic, we think enterprises scenarios may require an agent to fetch a list of entitled agents via a registry.

We are looking to provide more clarity on this requirement in the next revision of the spec. If you have any recommendations or suggestions, please feel free to share with us.

[ognis1205]

Thank you for your response, @kthota-g!

It seems I had overlooked that part. I’m fully on board with the idea of supporting agent discovery through a catalog interface. I'm very interested in the specifications and implementation of this REST Agent Catalog. I believe I can contribute with some ideas or a proof of concept, so I’ll be sure to share any updates on my end as they come.

[vishalmysore]

To support multiple agent groups within the existing AgentCard schema, I would recommend introducing an optional agentGroups property. This would allow each agent to be logically categorized under one or more groups, enabling more flexible organization, routing, and management of agents in multi-agent systems. The modification can be implemented as follows:

"agentGroups": {
  "type": "array",
  "title": "Agent Groups",
  "items": {
    "type": "string"
  },
  "default": [],
  "description": "Logical grouping(s) the agent belongs to, used for scoping, routing, or permissioning"
}

This field should be added to the properties section of the AgentCard schema. It does not need to be required, allowing backward compatibility with existing definitions. With this enhancement, the platform will be better equipped to support use cases involving agent clusters, federation, or role-based agent behaviors.

For example in my java implementation of A2A I am fitting 2 different types of agents using agent groups if would be good to get this support out of the box in a2a.json

https://github.com/vishalmysore/a2ajava/tree/main/src/main/java/io/github/vishalmysore/example

[ognis1205]

@kthota-g

After reviewing the current AgentCard schema and the discovery mechanism, I’d like to propose introducing a dedicated schema for agent discovery—separate from the AgentCard itself, which I personally see as more closely aligned with agent configuration or even prompt-level semantics rather than discovery metadata.

Instead of relying solely on the agent card being hosted at /.well-known/agent.json, I think it could be cleaner to introduce something like a /.well-known/agents/index.json, which acts as a registry within the domain and provides a list of available agents, each with metadata like their relative path and a short description. This could follow a new AgentIndex schema:

{
  "agents": [
    {
      "path": "/path/to/agent",
      "description": "Does something."
    },
    {
      "path": "/another/agent",
      "description": "Does something else."
    }
  ]
}

As for the path structure, I also want to share a few REST-aligned patterns we might consider:

• /path/to/agent/agent.json — used as a sub-resource for retrieving static metadata about the agent, i.e., AgentCard.
• /path/to/agent with a GET — returns the AgentCard directly (if the endpoint is not used for invocation).
• /path/to/agent/card — an alternative sub-resource that clearly separates metadata from execution.

While (2) and (3) are more REST-idiomatic, I feel (1) is simple and intuitive in practice, especially when the agent is already addressable via /path/to/agent. However, there's a risk of redundancy or potential confusion if the agent invocation and metadata paths are too similar or overloaded.

Would love to hear your thoughts on separating discovery from AgentCard and whether an AgentIndex registry spec might fit into future revisions!

[ognis1205]

As an alternative option, I propose moving properties associated with the AgentCard API call (such as authentication and provider information), which are common to all agents under the same BASE_URL, into the AgentIndex. Alternatively, we could return a list of AgentCard objects within the agents field of the AgentIndex, with common properties being moved to the AgentIndex itself. This would simplify the structure and avoid redundancy. Additionally, I suggest not adopting the sub-resource pattern for returning metadata for each individual agent.

However, one potential downside of these approach is that it could lead to a more complex AgentIndex structure if too many properties are centralized there. Balancing the scope of AgentIndex with the need for clear, maintainable separation of concerns will be crucial.

[ognis1205]

While introducing a separate schema does add to the number of entities being managed, I think it may be a preferable direction—especially from a discovery perspective, where such a schema is necessary regardless of whether or not an external registry is used. Rather than overloading the AgentCard, it would be ideal to introduce a separate schema (such as AgentIndex) and organize the necessary properties based on their distinct concerns.

[ognis1205]

@kthota-g

In this proposal, I suggest structuring the AgentIndex to support both open discovery and entitlement-based agent discovery via a registry, by making either of the following properties mandatory:

1. agents:
   Used for open discovery, listing publicly available agents. This list does not include entitled agents and only contains information for agents that are discoverable without authorization.
2. registry_url:
   Used for accessing the agent catalog and entitlement-based discovery via a registry. It allows organizations to manage agent access with finer granularity, such as by role, privilege, and other governance controls.

The AgentIndex would allow the flexibility to support both public agents (for open discovery) and authorized agents (for use cases with strict access control) by providing the following structure:

• If agents is provided: It serves the purpose of open discovery and only lists public agents.
• If registry_url is provided: It enables entitlement-based discovery via a registry and handles access control, such as role-based access or privileges, through another API specification that will be defined separately.

This approach keeps the system simple for open discovery while allowing flexibility for more complex scenarios requiring role-based access control:

{
  "title": "AgentIndex",
  "type": "object",
  "description": "Represents a list of agents discoverable under this base URL or via a registry.",
  "properties": {
    "agents": {
      "type": "array",
      "description": "List of publicly available agents for Open Discovery.",
      "items": {
        "$ref": "#/$defs/AgentEntry"
      }
    },
    "registry_url": {
      "type": "string",
      "description": "URL for accessing the agent catalog and entitlement-based discovery via a registry."
    }
  },
  "oneOf": [
    {
      "required": ["agents"]
    },
    {
      "required": ["registry_url"]
    }
  ],
  "$defs": {
    "AgentEntry": {
      "type": "object",
      "properties": {
        "path": {
          "type": "string",
          "description": "Relative path to the agent metadata (e.g. /path/to/agent/agent.json)"
        },
        "description": {
          "type": "string",
          "description": "Human-readable summary of what the agent does."
        },
        "title": {
          "type": "string",
          "description": "Short name or title for the agent."
        }
      },
      "required": ["path", "title"]
    }
  }
}

[robomotic]

I like this approach very much!

[ognis1205]

Hey @robomotic ,
Thank you! If you have any insights, please share with us!

[sfitts]

I agree; this feels like going in the right direction. We have a multi-tenant agent platform to which we plan to add A2A support. This was one of the first issues I saw with the protocol, so I'm glad to see it being discussed. We definitely will need a "tiered" system that you outline here, with publicly available agents and agents that can only be found if you have the appropriate permissions. In each case there may be multiple agents available "under" the same base URI.

[cdavernas]

@ognis1205 It's an awesome proposal, which imho addresses the issue in a very elegant fashion, without breaking discovery, while remaining flexible, and dead simple.

title and description might be redundant with the AgentCard the path points at, though, requiring needless deduplication of data. We should maybe consider replacing them with a name property instead, used for basic discrimination.

[ognis1205]

@sfitts @cdavernas

Thank you all! I'd really appreciate any feedback to help further refine this. Ideally, building a simple system and identifying issues through hands-on experience would be the best approach.

[ognis1205]

It would be helpful to get some feedback from the project maintainers 🤔

@kthota-g
Are the members of the A2A project currently considering the API design for the Agent Registry/Catalog? Given the nature of the protocol, a Discovery Layer will likely become a necessity.

[akintunca]

I was implementing multiple agents for a single server but didn't complete it, you can check here for the idea: A2A-Server-Management

[darrelmiller]

FYI, .well-known does not allow path segments before the .well-known segment https://datatracker.ietf.org/doc/html/rfc5785#section-3

So, if .well-known is to be used then it really needs to be a list of agents in the file, or you could leverage the "very nearly published" api-catalog well-known endpoint to point to agent cards. https://www.ietf.org/archive/id/draft-ietf-httpapi-api-catalog-08.html

[ognis1205]

Hey @darrelmiller — thank you for sharing this helpful information. I think it makes sense to describe each agent endpoint using a linkset, following the api-catalog format (although it's still a draft and we cannot find any concrete schema/format yet). For the AgentCard, it seems reasonable to expose it as a subresource retrievable via a GET request from the endpoint specified in the linkset.

[ognis1205]

I implemented a PoC for an Open Discovery API Catalog schema based on the draft specification shared by @darrelmiller. Key points include:

• Regarding the Registry URL: for clients, it is assumed to be as self-evident as the Remote Agent Base URL (i.e., if a client knows the Remote Agent Base URL, it is also assumed to know the corresponding Registry URL), so it was excluded from the schema.
• Although the API Catalog schema is still in draft form, it follows the structure outlined in the linked RFC. Wherever possible, I have adopted properties that are commonly used in existing Web Linking practices.

 {
    "title": "AgentCatalog",
    "type": "object",
    "description": "Represents a list of agents discoverable under this base URL following the Linkset format.",
    "properties": {
        "linkset": {
            "type": "array",
            "description": "Linkset structure describing agent discovery entries.",
            "items": {
                "$ref": "#/$defs/AgentLinkContext"
            }
        }
    },
    "required": ["linkset"],
    "$defs": {
        "AgentLinkContext": {
            "type": "object",
            "properties": {
                "anchor": {
                    "type": "string",
                    "format": "uri",
                    "description": "Specifies the absolute URI reference that points to an agent endpoint."
                },
                "links": {
                    "type": "array",
                    "description": "List of links associated with the anchor, each describing a discoverable agent card.",
                    "items": {
                        "$ref": "#/$defs/AgentLinkTarget"
                    }
                }
            },
            "required": ["anchor", "links"]
        },
        "AgentLinkTarget": {
            "type": "object",
            "properties": {
                "href": {
                    "type": "string",
                    "format": "uri",
                    "description": "Absolute URI reference to the agent card endpoint."
                },
                "type": {
                    "type": "string",
                    "enum": ["application/json"],
                    "description": "The media type of the linked resource. Must be 'application/json'."
                },
                "rel": {
                    "type": "string",
                    "enum": ["agent-card"],
                    "description": "The relation type of the linked resource. Must be 'agent-card'."
                },
                "name": {
                    "type": "string",
                    "description": "Human-readable name for the agent."
                },
                "description": {
                    "type": "string",
                    "description": "Short description of what this agent does."
                }
            },
            "required": ["href", "type", "rel"]
        }
    }
}

For example, if example.org is hosting agent1 and agent2, the expected .well-known/api-catalog.json would look like the following:

{
  "linkset": [
    {
      "anchor": "https://example.org/agents/agent1/",
      "links": [
        {
          "href": "https://example.org/agents/agent1/agent.json",
          "type": "application/json",
          "rel": "agent-card"
        }
      ]
    },
    {
      "anchor": "https://example.org/agents/agent2/",
      "links": [
        {
          "href": "https://example.org/agents/agent2/agent.json",
          "type": "application/json",
          "rel": "agent-card"
        }
      ]
    }
  ]
}

If the community finds either the AgentIndex schema or the AgentCatalog schema reasonable, I’d be happy to consider submitting a PR to include it as an example in the documentation rather than as part of the specification.

[cdavernas]

Awesome! I love it!

[vishalmysore]

This is super cool

…

On Tue, May 20, 2025 at 7:20 AM cdavernas ***@***.***> wrote: Awesome! I love it! — Reply to this email directly, view it on GitHub <#166 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AGF4WHNJWM65DFVB7AS5L3327MFYRAVCNFSM6AAAAAB3EG5G26VHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTGMRQGU3DQMA> . You are receiving this because you commented.Message ID: ***@***.***>

[ognis1205]

Thanks everyone for the comments!

• @cdavernas I took the advice to change “title” to “name”.
• @vishalmysore Maybe we could also use this draft as a base to think about things like Agent Groups or Tags.

[vishalmysore]

Sounds fantastic , I will try in my a2ajava project

[ognis1205]

FYI:

#642

[vishalmysore]

another approach with multiple agents card from same server based on user permissions and RBAC, live demo you can test directly here

[ognis1205]

Hi @vishalmysore , thanks for sharing your demo!

I think this demo is very helpful in the context of the AuthenticatedExtendedAgentCard topic. On the other hand, the main interest here seems to be about Open Discovery of agents. I believe everyone is focused on questions like whether it's reasonable to host multiple agents (not just agent cards) under a specific base URL, and if so, how to support Open Discovery in such a setup.

As I mentioned earlier, modifying Agent Cards with RBAC is very important in the context of authn and A2A, and I strongly agree with the direction you're taking in this demo. However, it might be slightly off-topic in this particular discussion. It might be a good idea to start a separate discussion about the API specifications for the Agent Catalog/Registry.

[vishalmysore]

Yes, I completely agree — the original discussion was focused on agent discovery and open registries, and I agree that differs from what I was demonstrating. My intention was to showcase another way to host multiple agents under a single base URL by mapping them to different roles each serving its own .well-known/agent.json.

While it’s a slightly different use case from the open discovery direction, I think both approaches are complementary. Thanks again for the clarification and great discussion! 🙏 Also agree its more focussed towards AuthenticatedExtendedAgentCard

[ognis1205]

Thanks as always for your constructive comments @vishalmysore !

I know you've been sharing various demos with the community. This particular demo, in particular, seems quite important, so I think you could gain more traction in the community if you adjusted the way it's presented or commented—perhaps by framing it in a way that sparks discussion in threads like this one.

[ognis1205]

Regarding the following PR:

#642

I’ve removed the WIP status from this PR due to changes in the repository structure. The related SDK implementation will continue in a2a-python, but for the demo, I plan to publish it using a fork of the relevant SDK—either in the official sample repository or in my personal repository. Looking forward to your review.

[ognis1205]

Hey @darrelmiller, I have a question regarding the use of extension target attributes in RFC 9264.

In a JSON Linkset like this:

{
  "linkset": [
    {
      "anchor": "https://example.org/agents/agent1",
      "describedby": [
        {
          "href": "https://example.org/agents/agent1/agent.json",
          "type": "application/json",
          "title": "Agent Card for Agent 1"
        }
      ]
    }
  ]
}

I'd like to add a custom boolean indicator that tells consumers whether the target document is an extended version of the AgentCard. Based on Section 4.2.4.3, I’m planning to use an extension target attribute like this:

"extended": ["true"]

I understand that:

• All extension attributes must be serialized as arrays.
• Values must be JSON strings (since the attribute name does not end with *).

Is this a valid and interoperable way to represent a custom boolean flag using extension attributes in a link target object? Appreciate any feedback or clarification on this usage!

[rajeshvelicheti]

For the agent registry, one pattern is to use an MCP server as a registry of agent cards (stored as resources).

The sample below demonstrates this pattern. Agent cards are exposed as resources in an MCP server. This uses a simple dot product to match agent cards to the request, but it can be extended further.

https://github.com/google-a2a/a2a-samples/tree/main/samples%2Fpython%2Fagents%2Fa2a_mcp

[rajhanshdhami]

Hi @rajeshvelicheti , apart from this are we following any other pattern also?

[rajeshvelicheti]

This is just an example, there are multiple approaches to implementing a registry.

[darrelmiller]

Is this a valid and interoperable way to represent a custom boolean flag using extension attributes in a link target object? Appreciate any feedback or clarification on this usage!

As is mentioned in the linkset RFC, there is no guarantee of interoperability. There needs to be community agreement around these extension target attributes. It is certainly something could be coordinated through a registry or specification of extensions. As the RFC requires the values to be a string, the fact that "true" looks like a boolean is arguably a coincidence. All that matters is that consumers of the extension agree on a sequence of characters and its meaning.

[ognis1205]

@darrelmiller

Thanks for the clarification — that makes sense.

You’re absolutely right that without shared agreement, even something that looks like a boolean is just a string in the eyes of the spec. Appreciate the insight!

[ognis1205]

PoC: SDK Example for Agent Mounting and API Catalog Discovery

I’ve implemented a proof-of-concept SDK that demonstrates how to define and mount multiple A2A agents using A2AStarletteRouteBuilder and A2AStarletteBuilder. Each agent is configured with its own AgentCard, skill set, and handler, and mounted to a shared Starlette application. The resulting server responds with a valid A2A catalog at /.well-known/api-catalog.json, like the following:

{
  "linkset": [
    {
      "anchor": "http://localhost:9999/a2a/hello/",
      "describedby": [
        {
          "href": "http://localhost:9999/a2a/hello/agent.json",
          "type": "application/json"
        }
      ]
    },
    {
      "anchor": "http://localhost:9999/a2a/echo/",
      "describedby": [
        {
          "href": "http://localhost:9999/a2a/echo/agent.json",
          "type": "application/json"
        }
      ]
    }
  ]
}

Minimal Example Code

@click.command()
@click.option('--host', default='localhost')
@click.option('--port', default=9999)
def main(host: str, port: int):
    hello_skill = AgentSkill(
        id='hello_world',
        name='Returns hello world',
        description='just returns hello world',
        tags=['hello world'],
        examples=['hi', 'hello world'],
    )
    hello_card = AgentCard(
        name='Hello World Agent',
        description='Just a hello world agent',
        url=f'http://{host}:{port}/a2a/hello',
        version='1.0.0',
        defaultInputModes=['text'],
        defaultOutputModes=['text'],
        capabilities=AgentCapabilities(streaming=True),
        skills=[hello_skill],
        supportsAuthenticatedExtendedCard=False,
    )
    hello_handler = DefaultRequestHandler(
        agent_executor=HelloWorldAgentExecutor(),
        task_store=InMemoryTaskStore(),
    )
    hello_agent = A2AStarletteRouteBuilder(
        agent_card=hello_card,
        http_handler=hello_handler,
    )

    echo_skill = AgentSkill(
        id="echo",
        name="Echo input",
        description="Returns the input text as is",
        tags=["echo"],
        examples=["Hello!", "Repeat after me"],
    )
    echo_card = AgentCard(
        name="Echo Agent",
        description="An agent that echoes back your input.",
        url=f"http://{host}:{port}/a2a/echo",
        version="1.0.0",
        defaultInputModes=["text"],
        defaultOutputModes=["text"],
        capabilities=AgentCapabilities(streaming=True),
        skills=[echo_skill],
        supportsAuthenticatedExtendedCard=False,
    )
    echo_handler = DefaultRequestHandler(
        agent_executor=EchoAgentExecutor(),
        task_store=InMemoryTaskStore(),
    )
    echo_agent = A2AStarletteRouteBuilder(
        agent_card=echo_card,
        http_handler=echo_handler,
    )

    server = (
        A2AStarletteBuilder()
            .mount(hello_agent)
            .mount(echo_agent)
            .build()
    )
    uvicorn.run(server, host=host, port=port)


if __name__ == "__main__":
    try:
        main()
    except Exception:
        print(traceback.format_exc(), file=sys.stderr)

This can serve as a practical SDK example when reviewing the following PR:

• google-a2a/A2A#642 – API catalog spec update (this is the primary PR to review)

The following is the related PoC implementation of the SDK:

• google-a2a/a2a-python#109 – SDK implementation

[kthota-g]

In the current implementation, each A2A server publishes it's own Agent Card describing it's capabilities. A standalone A2AServer may not know the presence of other servers or agent cards and so they won't be publishers of such catalog.

For example: Let's assume an enterprise that has two agents: 1) IT Agent, 2) HR Agent. Each agent may be hosted separately, offers different set of capabilities and each publish their own agent card.

These published agent cards could be part of an Agent catalog hosted by another service (let's call it registry).

If there is an orchestrator agent that can call these agents, it can be a consumer of the Agent Catalog to discover these agents and then use the provided Agent Card to invoke the agents. The Agent catalog can have entitlement mechanism to return the list of agents available for a given consumer.

There is usefulness for Agent Catalog, but we think exposing an agent catalog is not the responsibility of an A2AServer, it should rather be available via a separate service that enables agent discovery.

[ognis1205]

Thoughts on the Use of .well-known in A2A Protocol Design

This summarizes some considerations and suggestions regarding the use of .well-known URIs in the context of the A2A protocol. It is shared in the spirit of constructive discussion and future-proof protocol design.

---

.well-known Suggests an Intent Toward Standardization

• Using or recommending .well-known implicitly signals that the protocol or specification may evolve toward broader adoption or standardization.
• As defined in RFC 8615, the .well-known namespace is reserved for interoperable, host-wide metadata and configuration resources.
• Accordingly, any metadata exposed via .well-known should be general-purpose and future-proof.

---

Prioritize Generality and Extensibility

• .well-known entries should ideally describe the host's overall protocol support, not a single resource or agent.
• This facilitates extensibility, versioning, and third-party tooling across varied environments.
• OpenID Connect's /.well-known/openid-configuration serves as a useful precedent: it describes host-level authentication capabilities, not a single user or app.

---

Be Mindful of Granularity

• A path like /.well-known/agent.json that provides only one agent’s information may misalign with the intention of .well-known as host-wide metadata.
• Hosts may expose multiple agents, so a design that assumes a single agent per host introduces limitations and ambiguity.

---

Suggested Structure

• Consider exposing a host-level summary document at /.well-known/api-catalog.json (or similar), which:

  • Provides a list of available agents and their capabilities.
  • Points to further metadata (e.g., per-agent agent.json files).
  • Aligns with patterns like the api-catalog Internet-Draft.

• Individual agent metadata can then live at stable, discoverable paths such as:

  • /path/to/agent/agent.json

---

.well-known May Not Always Be Necessary

• If a clean, extensible .well-known design is difficult to achieve, it may be more appropriate to adopt external catalogs or registries as the primary discovery mechanism.
• This avoids premature assumptions about host structure or deployment models, while retaining flexibility for future integration.

---

Consider Separation of Concerns

• A2A protocols often aim to support agent communication, but agent discovery may benefit from being handled by a separate specification layer or registry API.
• Deferring final decisions around .well-known structure allows time to better understand real-world use cases and system diversity.

---

On the Importance of Updating Current Documentation

• Given the current state of documentation, some existing guidance around .well-known usage may inadvertently lead to misunderstandings or assumptions about the intended scope and structure of A2A deployments.
• Clarifying the role and recommended usage of .well-known—especially in relation to host-level versus agent-level metadata—could help reduce confusion for implementers.
• We therefore recommend revisiting and updating the relevant documentation to reflect a more cautious, future-aware design philosophy.

---

[cdavernas]

we think exposing an agent catalog is not the responsibility of an A2AServer

@kthota-g I respectfully disagree. The specification has so far taken a highly opinionated stance on how agents should be hosted and executed. In my view, it should not impose a specific architectural model, which is precisely why it should provide a mechanism for documenting multiple agents. Failing to address this issue—and simply stating that it is not the responsibility of an A2A server (without justification)—undermines standardization efforts around discovery and, as a result, harms the specification.

[ognis1205]

@kthota-g @cdavernas

we think exposing an agent catalog is not the responsibility of an A2AServer

@kthota-g I respectfully disagree. The specification has so far taken a highly opinionated stance on how agents should be hosted and executed. In my view, it should not impose a specific architectural model, which is precisely why it should provide a mechanism for documenting multiple agents. Failing to address this issue—and simply stating that it is not the responsibility of an A2A server (without justification)—undermines standardization efforts around discovery and, as a result, harms the specification.

I would like to clarify that the term "Agent Catalog" — as proposed — is not equivalent to a conventional catalog in the sense that the word might suggest. While I adopted the term "catalog" in reference to the API Catalog Internet Draft, I recognize that this may have led to some misunderstanding.

In particular, the "Agent Catalog" we propose — modeled after the API Catalog draft — differs from conventional catalog services in the following key ways:

Aspect	IETF-style API Catalog	Conventional API Catalog (e.g., API Catalog Service)
Purpose	Self-published, machine-readable enumeration of APIs/agents	Centralized discovery and governance of many APIs
Ownership	Published by the server (API/agent provider)	Potentially operated by third-party platforms
Access Method	Served via /.well-known/api-catalog in JSON	Often via platform-hosted web portals or APIs
Format	Follows RFC 9264 (application/linkset+json)	Platform-specific formats

This Agent Catalog is conceptually aligned with self-hosted discovery, not centralized indexing.

[liuming-dev]

For example: Let's assume an enterprise that has two agents: 1) IT Agent, 2) HR Agent. Each agent may be hosted separately, offers different set of capabilities and each publish their own agent card.

In our application scenario, we want different agents to be developed as modules within a single project and deployed together using the same domain name.

We would very much like the following scenario to be supported.

• agent1
  • AgentCard path: https://www.example/xxx/agent1/.well-known/agent.json
  • Request action path: https://www.example/xxx/agent1
• agent2
  • AgentCard path: https://www.example/xxx/agent2/.well-known/agent.json
  • Request action path: https://www.example/xxx/agent2

[ognis1205]

Hi @liuming-dev , thanks for the example — it helps clarify the use case!

Just a quick note regarding the .well-known path:

#166 (comment)

So unfortunately, URLs like https://www.example/xxx/agent1/.well-known/agent.json are not valid under the .well-known convention.

If your goal is to host multiple agents under the same domain and still support some form of open discovery, there are a few possible approaches:

• API Catalog
• ORD
• Other similar specifications and/or formats

If Open Discovery is not strictly required for your setup (e.g. you control the client), then it may be more pragmatic to:

• Hardcode the endpoints per agent in the client app, or
• Use a registry-like service that maps logical agent names to endpoint URLs.

Let me know if you’d like help sketching one of these approaches in more detail!

[ognis1205]

Regarding the ongoing discussion about supporting multiple agents under a single host, I have come to consider that, even within the current "one host, one agent" model, similar functionality might be achieved by equipping a single agent with multiple skills. However, this approach may introduce challenges related to skill routing within that agent.

Since this topic is closely related to the current discussion, I am adding a link to the discussion for cross-reference.

#921

[sfitts]

Regarding the ongoing discussion about supporting multiple agents under a single host, I have come to consider that, even within the current "one host, one agent" model, similar functionality might be achieved by equipping a single agent with multiple skills. However, this approach may introduce challenges related to skill routing within that agent.

Since this topic is closely related to the current discussion, I am adding a link to the discussion for cross-reference.

#921

More than that, if the agents are in wildly different domains, it really doesn't work. Consider a hospital with internal HR and patient management -- not 2 things you want to combine. Make a routing mistake between those and...

Currently we are proceeding to use A2A for a number of features for our platform (the bulk of the protocol is quite solid) and simply ignoring the discovery section as it is not enterprise grade.

[ognis1205]

Thanks for sharing your insight, @sfitts !

My exploration using AgentSkill was an attempt to self-critically examine whether similar functionality could be achieved within the currently recommended approach. I share the same concerns as you — particularly when it comes to skill routing within a single agent.

While I still believe that .well-known should expose more general and comprehensive metadata, in the context of the "one-host, one-agent" model, we might consider mechanisms to narrow down skill resolution using additional information like tags when sending messages to a remote agent.

[ognis1205]

SEE ALSO: #943

[MG1-4]

Hi @kthota-g , is there any conclusion directions from the authors of the protocol on how the agent's base url in the agent card could be for orchestrator platforms that could potentially host many agents under a single base url. this is a real world scenario & I'd like some direction, thanks.