FHIR Context With A2A

Agents that support A2A can indicate that they require FHIR context. This is primarily handled by implementing the extensions feature of the A2A specification.

Extension Declaration

For agents that are configured with FHIR context, the extension with uri https://app.promptopinion.ai/schemas/a2a/v1/fhir-context.

This is how the agent card will look like:

{
  "capabilities": {
    "extensions": [
      {
        "uri": "https://app.promptopinion.ai/schemas/a2a/v1/fhir-context",
        "description": "FHIR context allowing the agent to query a FHIR server securely",
        "required": false
      }
    ]
  }
}

The extension is a resolvable url. It directs you to JSON schema that indicates how FHIR context will be passed to the A2A agent.

Extension Scopes

The params within the extension should indicate SMART scopes that your application requires. The user that adds the agent can then decide to authorize the agent with the requested access. You can mark a scope as required. When marking a scope as required, a user cannot uncheck the scope and their only option is to avoid using the agent at all if they do not consent to giving the required access.

Here is the structure of the params object:

{
  "scopes": [
    {
      "name": "", // The name of the scope
      "required": true // Whether the scope is required to run your server
    }
  ]
}

Here is a sample extension declaration for an agent that has a required scope of patient/Patient.rs (which allows reading and searching on the current patient) and an optional scope of patient/Condition.rs (which allows reading and searching for conditions for the current patient).

{
  "capabilities": {
    "extensions": [
      {
        "uri": "https://app.promptopinion.ai/schemas/a2a/v1/fhir-context",
        "description": "FHIR context allowing the agent to query a FHIR server securely",
        "required": false,
        "params": {
          "scopes": [
            {
              "name": "patient/Patient.rs",
              "required": true
            },
            {
              "name": "patient/Condition.rs"
            }
          ]
        }
      }
    ]
  }
}

FHIR Context Payload

When a message is sent to an agent that supports this extension PromptOpinion will include the FHIR context in the message payload:

{
  "jsonrpc": "2.0",
  "method": "SendMessage",
  "params": {
    "message": {
      "role": "user",
      "parts": [
        {
          "text": "Hello World!"
        }
      ],
      "metadata": {
        "https://app.promptopinion.ai/schemas/a2a/v1/fhir-context": {
          "fhirUrl": "https://app.promptopinion.ai/api/workspaces/abc123/fhir",
          "fhirToken": "eyJ...",
          "patientId": "abc123"
        }
      }
    }
  }
}

The FHIR context will include the url to the FHIR server, the token required to authorize with the server, and a patient id.