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.

Refresh Token Capability

An A2A agent has the option of requesting offline access that allows it to also receive a refresh token. This allows the agent to perform background processing.

In order to enable this feature, you must include the offline_access as a scope in the A2A extension. This will then be displayed to the user and if the user authorizes this scope, the agent will receive two additional properties in the payload of the message. Here's an example:

{
  "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",
          "fhirRefreshToken": "eyJ...", // The new property that contains the refresh token
          "fhirRefreshTokenUrl": "https://app.promptopinion.ai/..." // The url where the refresh token should be sent
        }
      }
    }
  }
}

When making a request to the refresh token URL, the body of the request must be in the format:

{
  "refreshToken": "eyJ..." // The refresh token
}

If validation succeeds, the API will return a new access token and refresh token:

// Response
{
  "accessToken": "eyJ...",
  "refreshToken": "eyJ..."
}