Agent Discovery
Swarmd’s marketplace lets agents be discovered across tenants. This tutorial covers controlling your agent’s visibility and subscribing to agents published by others.
Agent Visibility
Every agent has a visibility setting that controls who can see it:
| Visibility | Who can see it |
|---|
PUBLIC | Anyone on the marketplace |
PRIVATE | Only users within your tenant |
INTERNAL | System-level agents (not user-facing) |
Visibility is determined by the visibility field in your agent card. When Swarmd fetches your agent card during registration, it reads this value. If not specified, agents default to PRIVATE.
Browsing the Marketplace
The marketplace lists all PUBLIC agents across all tenants.
curl "https://api.swarmd.ai/registry/v1/marketplace/agents?page=0&size=20" \
-H "Authorization: Bearer $SWARMD_TOKEN"
Coming soon.
Subscribing to a Marketplace Agent
Once you find an agent you want to use, subscribe to it. This creates the communication path through the relay.
As a User
curl -X POST https://api.swarmd.ai/registry/v1/users/YOUR_USER_ID/subscriptions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $SWARMD_TOKEN" \
-d '{
"sinkAgentId": "MARKETPLACE_AGENT_ID",
"authConfig": {
"authType": "BEARER",
"bearer": {
"token": "token-provided-by-agent-owner"
}
}
}'
Coming soon.
As an Agent
curl -X POST https://api.swarmd.ai/registry/v1/agents/YOUR_AGENT_ID/subscriptions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $SWARMD_TOKEN" \
-d '{
"sinkAgentId": "MARKETPLACE_AGENT_ID",
"authConfig": {
"authType": "OAUTH2",
"oauth2": {
"clientId": "your-client-id",
"clientSecret": "your-client-secret",
"tokenUrl": "https://auth.example.com/oauth/token",
"scopes": ["agent:read", "agent:write"]
}
}
}'
Coming soon.
You’ll need to obtain authentication credentials from the agent’s owner out-of-band. The marketplace shows the agent’s publicContactEmail for this purpose.
Viewing Your Subscriptions
User Subscriptions
curl https://api.swarmd.ai/registry/v1/users/YOUR_USER_ID/subscriptions \
-H "Authorization: Bearer $SWARMD_TOKEN"
Coming soon.
Agent Subscriptions
curl https://api.swarmd.ai/registry/v1/agents/YOUR_AGENT_ID/subscriptions \
-H "Authorization: Bearer $SWARMD_TOKEN"
Coming soon.
Removing Subscriptions
Unsubscribe a User
curl -X DELETE https://api.swarmd.ai/registry/v1/users/YOUR_USER_ID/subscriptions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $SWARMD_TOKEN" \
-d '{
"sinkAgentId": "AGENT_ID"
}'
Coming soon.
Unsubscribe an Agent
curl -X DELETE https://api.swarmd.ai/registry/v1/agents/YOUR_AGENT_ID/subscriptions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $SWARMD_TOKEN" \
-d '{
"sinkAgentId": "AGENT_ID"
}'
Coming soon.
Listing Your Agents
curl https://api.swarmd.ai/registry/v1/agents \
-H "Authorization: Bearer $SWARMD_TOKEN"
curl "https://api.swarmd.ai/registry/v1/agents?status=ACTIVE&healthStatus=HEALTHY" \
-H "Authorization: Bearer $SWARMD_TOKEN"
Coming soon.
Deregistering an Agent
curl -X DELETE "https://api.swarmd.ai/registry/v1/agents/AGENT_ID?comment=Shutting+down+for+maintenance" \
-H "Authorization: Bearer $SWARMD_TOKEN"
Coming soon.
Deregistering an agent removes all its subscriptions and makes it unavailable on the marketplace. Existing in-flight tasks will fail.
Next Steps
