A2A Protocol

The HMS4all A2A (Agent-to-Agent) endpoint enables structured agent communication via JSON-RPC. 26 skills with task persistence and keyword-based automatic routing.

Agent Card

The agent card is discoverable at the standard Well-Known URL:

GET https://your-api.hms4all.com/.well-known/agent.json

{
  "name": "HMS4all Hospital Management AI",
  "description": "Multi-tenant hospital management platform with specialized AI agents",
  "version": "1.0.0",
  "url": "https://your-api.hms4all.com",
  "capabilities": { "streaming": true },
  "authentication": { "schemes": ["bearer"] },
  "skills": [ ... ]
}

Sending a Task

curl -X POST https://your-api.hms4all.com/a2a \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hms4all_sk_your_api_key" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tasks/send",
    "id": "req-1",
    "params": {
      "id": "task-unique-id",
      "message": {
        "role": "user",
        "parts": [
          { "type": "text", "text": "Analyze these lab results: CBC Hb 10.2, WBC 12000" }
        ]
      }
    }
  }'

Skill Routing

When you send a task, the system automatically routes to the best skill using keyword matching on the message text. You can also specify a skill explicitly in the task metadata:

{
  "params": {
    "id": "task-002",
    "metadata": { "skillId": "lab-interpretation" },
    "message": {
      "role": "user",
      "parts": [{ "type": "text", "text": "..." }]
    }
  }
}

Task Lifecycle

SUBMITTED → WORKING → COMPLETED
                    → FAILED
                    → INPUT_REQUIRED (HITL skills)

• SUBMITTED: Task received, routing to skill
• WORKING: Skill is processing
• COMPLETED: Result available in response
• FAILED: Error during processing
• INPUT_REQUIRED: HITL skills — human review needed. Send follow-up with actionId to check status

Task Persistence

All tasks are persisted in the database. You can retrieve a task at any time:

{
  "jsonrpc": "2.0",
  "method": "tasks/get",
  "id": "req-2",
  "params": { "id": "task-unique-id" }
}

Skill Reference

26 skills organized by category. All output JSON.

HITL Skills Flow

HITL skills use INPUT_REQUIRED state to pause for human review:

1. Send task with clinical data (e.g., prescription items)
2. Skill creates an AgentAction and returns INPUT_REQUIRED with actionId
3. Human reviews in the admin dashboard → approves or rejects
4. Send follow-up task with {"actionId":"..."} to check result
5. Returns COMPLETED with final status (APPROVED/REJECTED/PENDING)

Interactive Skill Tester

Error Handling

// JSON-RPC error response
{
  "jsonrpc": "2.0",
  "id": "req-1",
  "error": {
    "code": -32600,  // Invalid request
    "message": "..."
  }
}

// Codes:
// -32700 Parse error
// -32600 Invalid request
// -32601 Method not found
// -32000 Server error

Next Steps

• MCP Server — for direct tool calls from AI clients
• Authentication — API keys and JWT