A2A Agent Management API¶

API Route Prefix¶

/api/v1/agents

Response Data Structure¶

All agent responses follow this structure:

URL Fields¶

Top-level url: Agent's official URL from agent card metadata (card.url) - this is the agent's self-declared URL
config.url: User-provided agent endpoint URL - primary source for runtime operations (proxy, sync, etc.). This may differ from card.url when using port forwarding, load balancers, or internal network addresses
card.url: Third-party agent card metadata (read-only, same as top-level url)

Config Field¶

The config object contains user-provided metadata: - title: Display title for the agent - description: Agent description - url: User-configured agent endpoint URL - type: Transport type (jsonrpc, grpc, http_json)

Enabled State¶

Top-level response field enabled reports whether the agent is available for proxy/workflow execution.
The persisted source of truth is A2AAgent.config.enabled.
Deprecated root fields status and isEnabled are not returned by the API.

Path Field¶

path is the unique registry identifier used by proxy routes.
API input may be path-like (for example /team/a2a/agent-1) and is normalized by the backend into a slash-free SEO-style slug (for example team-a2a-agent-1).
Stored and returned path values never contain /.
path cannot be / or any value that normalizes to an empty slug. Those requests return 400 Bad Request.
If two different inputs normalize to the same path, create/update returns 409 Conflict.

Well-Known Field¶

The wellKnown object contains sync status only (no URL): - enabled: Whether well-known sync is enabled - lastSyncAt: Last successful sync timestamp - lastSyncStatus: Sync status (success, failed, unreachable) - lastSyncVersion: Agent version from last sync

API Endpoints¶

1. List Agents¶

Endpoint: GET /api/v1/agents

Query Parameters:

{
  query?: string;           // Search keywords (name, description, tags, skills)
  page?: number;            // Page number (default: 1)
  perPage?: number;         // Items per page (default: 20, max: 100)
}

Response: 200 OK



id=__codelineno-2-1 name=__codelineno-2-1 href=#__codelineno-2-1>{ "agents": [ { "id": "507f1f77bcf86cd799439011", "path": "code-reviewer", "name": "Code Review Agent", "description": "AI-powered code review assistant", "url": "https://example.com/agents/code-reviewer", "version": "1.0.0", "protocolVersion": "1.0", "tags": ["code", "review"], "numSkills": 2, "skills": [ { "id": "code-analysis", "name": "Code Analysis", "description": "Analyze code quality and identify issues", "tags": ["analysis", "quality"], "inputModes": ["text/plain"], "outputModes": ["application/json"] }, { "id": "bug-detection", "name": "Bug Detection", "description": "Detect potential bugs in code", "tags": ["bugs", "detection"], "inputModes": ["text/plain"], "outputModes": ["application/json"] } ], "enabled": true, "config": { "title": "Code Review Agent", "description": "AI-powered code review assistant", "url": "https://example.com/agents/code-reviewer", "type": "jsonrpc" }, "permissions": { "VIEW": true, "EDIT": true, "DELETE": true, "SHARE": true }, "author": "507f1f77bcf86cd799439012", "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-20T15:45:00Z" } ], "pagination": { "total": 150, "page": 1, "perPage": 20, "totalPages": 8 } class=p>}
 Note: - Uses AgentListItem schema for list items - All field names use camelCase convention - Each agent includes config field with user-provided metadata
 
 2. Get Agent Statistics¶
 Endpoint: GET /api/v1/agents/stats
 Response: 200 OK 
{
  "totalAgents": 150,
  "enabledAgents": 120,
  "disabledAgents": 30,
  "byTransport": {
    "HTTP+JSON": 100,
    "JSONRPC": 30,
    "GRPC": 20
  },
  "totalSkills": 450,
  "averageSkillsPerAgent": 3.0
}
 Permission: Admin only
 
 3. Get Agent Detail¶
 Endpoint: GET /api/v1/agents/{agent_id}
 Response: 200 OK 
{
  "id": "507f1f77bcf86cd799439011",
  "path": "code-reviewer",
  "name": "Code Review Agent",
  "description": "AI-powered code review assistant",
  "url": "https://example.com/agents/code-reviewer",
  "version": "1.0.0",
  "protocolVersion": "1.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "numSkills": 1,
  "skills": [
    {
      "id": "code-analysis",
      "name": "Code Analysis",
      "description": "Analyze code quality",
      "tags": ["analysis"],
      "inputModes": ["text/plain"],
      "outputModes": ["application/json"]
    }
  ],
  "securitySchemes": {
    "bearer": {
      "type": "http",
      "scheme": "bearer"
    }
  },
  "preferredTransport": "HTTP+JSON",
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["application/json"],
  "provider": {
    "organization": "AI Labs",
    "url": "https://ailabs.com"
  },
  "tags": ["code", "review"],
  "enabled": true,
  "config": {
    "title": "Code Review Agent",
    "description": "AI-powered code review assistant",
    "url": "https://example.com/agents/code-reviewer",
    "type": "jsonrpc"
  },
  "permissions": {
    "VIEW": true,
    "EDIT": true,
    "DELETE": true,
    "SHARE": true
  },
  "author": "507f1f77bcf86cd799439012",
  "wellKnown": {
    "enabled": true,
    "lastSyncAt": "2024-01-20T12:00:00Z",
    "lastSyncStatus": "success",
    "lastSyncVersion": "1.0.0"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T15:45:00Z"
}
 Note: - Uses AgentDetailResponse schema - All field names use camelCase convention - Response structure: - Top-level url: Agent's official URL from agent card (card.url) - config.url: User-provided agent endpoint URL (used for runtime operations like proxy, sync) - config.title, config.description, config.type: User-provided metadata - wellKnown: Sync status only (no URL field, URL is in config.url)
 Error: 404 Agent not found, 403 Access denied
 
 4. Create Agent¶
 Endpoint: POST /api/v1/agents
 Description: Register a new A2A agent. Only 5 fields are required in the request body. All other agent information (version, capabilities, skills, etc.) is automatically fetched from the agent's .well-known/agent-card.json endpoint using the A2A SDK. The fetched agent card is stored as-is without modification in the card field.
 Request Body: 
{
  "path": "code-reviewer",
  "title": "Code Review Agent",
  "description": "AI-powered code review assistant",
  "url": "https://example.com/agents/code-reviewer",
  "type": "jsonrpc"
}
 Request Fields: - path (required, string): Unique registry path identifier. Input may contain slashes (e.g., /code-reviewer or /team/a2a/code-reviewer) but is normalized and stored as a slash-free slug (e.g., code-reviewer or team-a2a-code-reviewer). The value / is invalid and returns 400 Bad Request. - title (required, string): Display title for the agent in the registry (stored in config.title) - description (optional, string): Description of the agent for the registry (stored in config.description) - url (required, string): Agent endpoint URL - the agent card will be automatically fetched from {url}/.well-known/agent-card.json - type (required, string): Transport type - must be one of: jsonrpc, grpc, http_json
 Data Storage Structure: - card: Original agent card from third-party URL (unmodified, contains card.url from the agent's own metadata) - config: Registry-specific configuration containing user-provided title, description, url (for runtime access), and type
 Auto-Fetch Behavior: 1. System fetches agent card from {url}/.well-known/agent-card.json using A2A SDK 2. Validates the fetched agent card structure 3. Stores the original card data without any modifications in the card field 4. User-provided title, description, url, and type are stored separately in the config field 5. Enables wellKnown sync automatically for future updates (URL stored in config.url, not wellKnown.url) 6. Tags field: Initialized as empty array [] - tags are registry-level metadata separate from skill tags, and can be managed manually if needed
 Response: 201 Created 
{
  "id": "507f1f77bcf86cd799439011",
  "path": "code-reviewer",
  "name": "Code Review Agent",
  "description": "AI-powered code review assistant",
  "url": "https://example.com/agents/code-reviewer",
  "version": "1.0.0",
  "protocolVersion": "1.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "skills": [...],
  "securitySchemes": {},
  "preferredTransport": "HTTP+JSON",
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["application/json"],
  "provider": {
    "organization": "AI Labs",
    "url": "https://ailabs.com"
  },
  "tags": [],
  "enabled": false,
  "config": {
    "title": "Code Review Agent",
    "description": "AI-powered code review assistant",
    "url": "https://example.com/agents/code-reviewer",
    "type": "jsonrpc"
  },
  "permissions": {
    "VIEW": true,
    "EDIT": true,
    "DELETE": true,
    "SHARE": true
  },
  "author": "507f1f77bcf86cd799439012",
  "wellKnown": {
    "enabled": true,
    "lastSyncAt": "2024-01-15T10:30:00Z",
    "lastSyncStatus": "success",
    "lastSyncVersion": "1.0.0"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}
 Note: - Uses AgentDetailResponse schema (not a separate create response) - Automatically grants OWNER permission to creator - ACL resource type is ResourceType.REMOTE_AGENT - Agent is created with enabled: false by default for safety - All agent metadata is auto-fetched from the provided URL and stored in card field without modification - User-provided configuration is stored separately in config field
 Error: - 400 Validation error, invalid transport type, invalid path (including /), or failed to fetch agent card from URL - 409 Path already exists, including when another input normalizes to the same slash-free path
 
 5. Update Agent¶
 Endpoint: PATCH /api/v1/agents/{agent_id}
 Description: Update an existing agent. Multiple fields can be updated via this endpoint. When the url field is updated, all other agent information is automatically fetched from the new URL's .well-known/agent-card.json endpoint and stored as-is in the card field.
 Request Body (all fields optional): 
{
  "path": "new-code-reviewer",
  "title": "Updated Agent Name",
  "description": "Updated description",
  "url": "https://example.com/agents/new-code-reviewer",
  "type": "grpc",
  "enabled": true
}
 Request Fields (all optional): - path (string): Update the registry path. Input may contain slashes, but the stored/returned value is normalized to a slash-free slug. The value / is invalid and returns 400 Bad Request. - title (string): Update the display title (stored in config.title) - description (string): Update the description (stored in config.description) - url (string): Update the agent endpoint URL - type (string): Update the transport type - must be one of: jsonrpc, grpc, http_json - enabled (boolean): Update the enabled state
 Auto-Fetch Behavior: 1. If url is updated: - System compares new URL with config.url to detect actual changes - If URL changed: fetches new agent card from {new_url}/.well-known/agent-card.json - Stores the original card data without any modifications in the card field - User-provided fields (title, description, url, type) are updated in the config field separately - wellKnown sync status is updated (URL stored in config.url) - If URL unchanged: skips agent card fetch for better performance
  If only title, description, or type is updated (no URL change):
 Only these fields are updated in the config field
 No agent card re-fetch occurs
  The card field remains unchanged
 
  If only path is updated:
 
 Registry path is normalized to a slash-free slug and updated (must be unique)
  Agent card and config remain unchanged
 
  If only enabled is updated:
 
 Agent enabled state is toggled
 No other fields are changed
 
 Response: 200 OK 
{
  "id": "507f1f77bcf86cd799439011",
  "path": "new-code-reviewer",
  "name": "Updated Agent Name",
  "description": "Updated description",
  "url": "https://example.com/agents/new-code-reviewer",
  "version": "1.1.0",
  "protocolVersion": "1.0",
  "capabilities": {...},
  "skills": [...],
  "securitySchemes": {...},
  "preferredTransport": "HTTP+JSON",
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["application/json"],
  "provider": {...},
  "tags": ["new", "tags"],
  "enabled": true,
  "config": {
    "title": "Updated Agent Name",
    "description": "Updated description",
    "url": "https://example.com/agents/new-code-reviewer",
    "type": "grpc"
  },
  "permissions": {
    "VIEW": true,
    "EDIT": true,
    "DELETE": true,
    "SHARE": true
  },
  "author": "507f1f77bcf86cd799439012",
  "wellKnown": {
    "enabled": true,
    "lastSyncAt": "2024-01-20T15:45:00Z",
    "lastSyncStatus": "success",
    "lastSyncVersion": "1.1.0"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T15:45:00Z"
}
 Note: - Uses AgentDetailResponse schema (not a separate update response) - Returns complete agent details after update - If URL is changed, automatically re-fetches all agent metadata from new URL and stores in card field - User-provided configuration is stored separately in config field
 Error: - 400 Validation error, invalid transport type, invalid path (including /), or failed to fetch agent card from new URL - 404 Agent not found - 403 Access denied - 409 New path conflicts with existing agent, including when another input normalizes to the same slash-free path
 Permission: Requires EDIT permission
 
 6. Delete Agent¶
 Endpoint: DELETE /api/v1/agents/{agent_id}
 Response: 204 No Content
 Error: 404 Agent not found, 403 Access denied
 Permission: Requires DELETE permission
 Note: Deletes all associated ACL permission records when deleting Agent
 
 7. Toggle Agent¶
 Endpoint: POST /api/v1/agents/{agent_id}/toggle
 Request Body: 
{
  "enabled": true
}
 Response: 200 OK 
{
  "id": "507f1f77bcf86cd799439011",
  "path": "code-reviewer",
  "name": "Code Review Agent",
  "description": "AI-powered code review assistant",
  "url": "https://example.com/agents/code-reviewer",
  "version": "1.0.0",
  "protocolVersion": "1.0",
  "capabilities": {...},
  "skills": [...],
  "securitySchemes": {...},
  "preferredTransport": "HTTP+JSON",
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["application/json"],
  "provider": {...},
  "tags": ["code", "review"],
  "enabled": true,
  "config": {
    "title": "Code Review Agent",
    "description": "AI-powered code review assistant",
    "url": "https://example.com/agents/code-reviewer",
    "type": "jsonrpc"
  },
  "permissions": {
    "VIEW": true,
    "EDIT": true,
    "DELETE": true,
    "SHARE": true
  },
  "author": "507f1f77bcf86cd799439012",
  "wellKnown": {...},
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T15:45:00Z"
}
 Note: - Uses AgentDetailResponse schema (not a separate toggle response) - Returns complete agent details after toggle - Includes config field with user-provided metadata
 Error: 404 Agent not found, 403 Access denied
 Permission: Requires EDIT permission
 
 8. Get Agent Skills¶
 Endpoint: GET /api/v1/agents/{agent_id}/skills
 Response: 200 OK 
{
  "agentId": "507f1f77bcf86cd799439011",
  "agentName": "Code Review Agent",
  "skills": [
    {
      "id": "code-analysis",
      "name": "Code Analysis",
      "description": "Analyze code quality",
      "tags": ["analysis", "quality"],
      "inputModes": ["text/plain"],
      "outputModes": ["application/json"]
    }
  ],
  "totalSkills": 1
}
 Error: 404 Agent not found, 403 Access denied
 Permission: Requires VIEW permission
 
 9. Refresh Agent Capabilities¶
 Endpoint: POST /api/v1/agents/{agent_id}/refresh
 Description: Refresh agent capabilities (skills) by fetching the latest agent card from the agent's .well-known/agent-card.json endpoint. This provides a consistent API experience with MCP server refresh (/servers/{id}/refresh).
 Request Body: None
 Response: 200 OK 
{
  "id": "507f1f77bcf86cd799439011",
  "path": "code-reviewer",
  "name": "Code Review Agent",
  "description": "AI-powered code review assistant",
  "url": "https://example.com/agents/code-reviewer",
  "version": "1.1.0",
  "protocolVersion": "1.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "numSkills": 3,
  "skills": [
    {
      "id": "code-analysis",
      "name": "Code Analysis",
      "description": "Analyze code quality",
      "tags": ["analysis", "quality"],
      "inputModes": ["text/plain"],
      "outputModes": ["application/json"]
    },
    {
      "id": "bug-detection",
      "name": "Bug Detection",
      "description": "Detect potential bugs",
      "tags": ["bugs", "detection"],
      "inputModes": ["text/plain"],
      "outputModes": ["application/json"]
    },
    {
      "id": "security-scan",
      "name": "Security Scan",
      "description": "Scan for security vulnerabilities",
      "tags": ["security", "vulnerabilities"],
      "inputModes": ["text/plain"],
      "outputModes": ["application/json"]
    }
  ],
  "securitySchemes": {...},
  "preferredTransport": "HTTP+JSON",
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["application/json"],
  "provider": {...},
  "tags": ["code", "review"],
  "enabled": true,
  "config": {
    "title": "Code Review Agent",
    "description": "AI-powered code review assistant",
    "url": "https://example.com/agents/code-reviewer",
    "type": "jsonrpc"
  },
  "permissions": {
    "VIEW": true,
    "EDIT": true,
    "DELETE": true,
    "SHARE": true
  },
  "author": "507f1f77bcf86cd799439012",
  "wellKnown": {
    "enabled": true,
    "lastSyncAt": "2024-01-20T15:45:00Z",
    "lastSyncStatus": "success",
    "lastSyncVersion": "1.1.0"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-20T15:45:00Z"
}
 Features: - Fetches latest agent card from well-known endpoint using A2A SDK - Updates agent capabilities (skills, version, etc.) in MongoDB - Automatically syncs to Weaviate vector database - Updates wellKnown.lastSyncAt and wellKnown.lastSyncStatus - Returns full agent detail response (consistent with MCP server refresh API)
 Use Cases: - Manual capability refresh: User clicks refresh button to get latest skills - Periodic updates: Scheduled refresh to keep agent capabilities up-to-date - Post-deployment sync: Refresh after agent is updated on the remote server - Frontend integration: Display last refresh time and refresh button on agent card
 Error Responses: - 400 Bad Request: Well-known sync not enabled or not configured - 404 Not Found: Agent not found or agent card not found at well-known endpoint - 502 Bad Gateway: Upstream errors or parse errors from remote agent - 503 Service Unavailable: Network/transport errors accessing remote agent
 Permission: Requires EDIT permission
 Comparison with /wellknown endpoint: - /refresh: Returns full AgentDetailResponse (consistent with server refresh) - /wellknown: Returns detailed WellKnownSyncResponse with change tracking
 
 10. Sync Well-Known¶
 Endpoint: POST /api/v1/agents/{agent_id}/wellknown
 Response: 200 OK 
{
  "message": "Well-known configuration synced successfully",
  "syncStatus": "success",
  "syncedAt": "2024-01-20T15:45:00Z",
  "version": "1.0.0",
  "changes": [
    "Updated version to 1.0.0",
    "Added 2 new skills"
  ]
}
 Error: 400 Well-known sync not enabled, 404 Agent not found or URL unreachable
 Permission: Requires EDIT permission
 
 11. Get Agent Card (Well-Known)¶
 Endpoint: GET /api/v1/agents/.well-known/agent-cards?url={agent_url}
 Authentication: JWT Bearer token required
 Description: Fetch and validate agent card from a remote A2A agent URL. This endpoint is used during agent creation (before ID is assigned) to validate and preview the agent card from the provided URL. It uses the A2A SDK to fetch and validate the card from the remote agent's .well-known/agent-card.json endpoint.
 Query Parameters: - url (required, string): The base URL of the A2A agent to fetch card from (e.g., https://example.com/agents/code-reviewer)
 Example Request: 
GET /api/v1/agents/.well-known/agent-cards?url=https://example.com/agents/code-reviewer
Authorization: Bearer <token>
 Response: 200 OK 
{
  "name": "Code Review Agent",
  "description": "AI-powered code review assistant",
  "url": "https://example.com/agents/code-reviewer",
  "version": "1.0.0",
  "protocolVersion": "1.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "preferredTransport": "HTTP+JSON",
  "provider": {
    "organization": "AI Labs",
    "url": "https://ailabs.com"
  },
  "skills": [
    {
      "id": "code-analysis",
      "name": "Code Analysis",
      "description": "Analyze code quality",
      "tags": ["analysis", "quality"]
    }
  ],
  "securitySchemes": {
    "bearer": {
      "type": "http",
      "scheme": "bearer"
    }
  },
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["application/json"]
}
 Features: - Fetches agent card from remote URL using A2A SDK's A2ACardResolver - Validates agent card structure per A2A protocol (via a2a-sdk) - No caching (for real-time validation during creation) - 15-second timeout for remote requests - Supports both with/without .well-known suffix in URL
 Headers: 
Content-Type: application/json
 Implementation: 
# Fetch and validate from remote URL using SDK
async with httpx.AsyncClient(timeout=httpx.Timeout(15.0)) as client:
    resolver = A2ACardResolver(base_url=url, httpx_client=client)
    agent_card = await resolver.get_agent_card()

agent_card_data = agent_card.model_dump(mode="json", exclude_none=True, by_alias=True)
 Use Cases: - Pre-creation validation: Validate agent before registering - Agent discovery: Preview agent capabilities from URL - Frontend integration: Fetch agent details during creation flow - URL validation: Verify the agent URL is accessible and valid
 Error Responses: - 400 Bad Request: Invalid URL format - 404 Not Found: Agent card not found at the provided URL - 500 Internal Server Error: Failed to fetch or parse agent card from remote URL
 Permission: No specific resource permission required (uses authenticated user context only)
 
      June 15, 2026      February 11, 2026