Agent to agent (A2A)

1. Foral Data A2A

Foral Data A2A is an A2A 1.0 agent over the Foral Data API. Your agent sends a typed request — a skill and its input — and gets the data back at once: public procurement (Portal BASE), municipal signals, municipalities, your alerts and the indicator catalogue. The answers are deterministic reads: no language model, no task to follow.

It is for Premium accounts and their agents. It is the same data, the same key and the same quota as the REST API and the Data MCP.

2. Read the agent card

The card is public: no key is necessary. With A2A-Version: 1.0 (header or ?A2A-Version=1.0) you get the A2A 1.0 card. Without it you get the older 0.3 compatibility card.

The card lists every skill. The JSON Schema of each skill's input is in the Foral extension of the card (capabilities.extensions[0].params.inputSchemas).

curl -s https://data.foral.ai/.well-known/agent-card.json \
  -H "A2A-Version: 1.0"

3. Authentication

Send Authorization: Bearer sk_live_… — the same key as the REST API. Create it on the API keys page. Keep it on your server — never in a browser page.

An OAuth access token also works: the token a client gets for the Data MCP (resource=https://data.foral.ai/mcp) is accepted on /a2a too. The card names the authorization server. You can disconnect an app at any time in Connected apps.

4. Call a skill

SendMessage takes one message with exactly ONE data part: {"skill": "<id>", "input": {…}}, with mediaType: application/json. Text, file and URL parts are refused with -32005.

The answer is a message with one data part: the same JSON as the REST endpoint of the skill. A list (the two lookups) comes as {"items": [...]}. No task is created.

messageId is yours (1–128 characters). It is not de-duplicated: every skill is a read, and each call counts as one request, like a repeated GET.

curl -s https://data.foral.ai/a2a \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "SendMessage",
    "params": {"message": {
      "messageId": "msg-0001", "role": "ROLE_USER",
      "parts": [{"data": {"skill": "procurement_lookup_municipalities",
                          "input": {"q": "Faro"}},
                 "mediaType": "application/json"}]
    }}
  }'

{
  "jsonrpc": "2.0", "id": 1,
  "result": {"message": {
    "role": "ROLE_AGENT", "messageId": "msg_…",
    "parts": [{"data": {"items": [
      {"municipality": "<code>", "slug": "faro", "name": "Faro",
       "district_name": "Faro", "match": "exact", …}
    ]}, "mediaType": "application/json"}],
    "metadata": {"skill": "procurement_lookup_municipalities",
                 "rest": "GET /v1/procurement/lookup/municipalities"}
  }}
}

5. Your skills (extended card)

GetExtendedAgentCard returns the card cut to the skills that your key can call: your plan's data domains and the key's scopes. A skill outside them is refused with -32004 and the error names the reason (DOMAIN_NOT_IN_PLAN or INSUFFICIENT_SCOPE).

curl -s https://data.foral.ai/a2a \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "GetExtendedAgentCard"}'

6. Skills

The skills are the Data MCP tools, with the same names and the same input. Start with me: it returns your plan, domains, scopes and limits.

7. Python

A plain JSON-RPC client with httpx: find a municipality code by name, then aggregate its contracts by year.

# pip install httpx
import uuid

import httpx

URL = "https://data.foral.ai/a2a"
HEADERS = {
    "Authorization": "Bearer sk_live_...",
    "A2A-Version": "1.0",
}


def skill(name: str, data: dict) -> dict:
    body = {"jsonrpc": "2.0", "id": str(uuid.uuid4()), "method": "SendMessage",
            "params": {"message": {
                "messageId": str(uuid.uuid4()), "role": "ROLE_USER",
                "parts": [{"data": {"skill": name, "input": data},
                           "mediaType": "application/json"}],
            }}}
    reply = httpx.post(URL, json=body, headers=HEADERS, timeout=60).json()
    if "error" in reply:
        raise RuntimeError(reply["error"])
    return reply["result"]["message"]["parts"][0]["data"]


faro = skill("procurement_lookup_municipalities", {"q": "Faro"})["items"][0]
totals = skill("procurement_aggregate", {"executed_in": [faro["municipality"]],
                                         "from": "2025-01-01", "group_by": ["year"]})
print(totals)

8. Limits and quota

Same limits as the REST API. Every HTTP request counts against your per-minute rate limit. Each SendMessage to a data skill counts as one request against your monthly quota; me, the card and GetExtendedAgentCard do not use quota. A 429 carries Retry-After (seconds).

9. Troubleshooting

A refusal of the data (quota, plan, scope, not found, invalid filter) is a JSON-RPC error. Its data holds a google.rpc.ErrorInfo (the reason is the error code of the REST API) and the full problem document of the REST API.

10. Company agents and Mercado

A company's Foral agent can also be published on the A2A channel. Another company's agent then talks to it with typed requests: check a service area, assess a project, research a public buyer.

Card: https://agents.foral.ai/<slug>/.well-known/agent-card.json. Endpoint: https://agents.foral.ai/<slug>/a2a. <slug> is the deployment slug shown in the company studio. The rules for A2A-Version: 1.0 and data parts are the same as above.

Authentication: an agent credential (sk_live_…) bound to ONE deployment and to the A2A channel. A company admin creates it in the studio (Deploy step). See Foral Agents.

Buyers on the Mercado: a licensed credential reaches the agent's read skills. Its card is the authenticated one (GetExtendedAgentCard).

Limits: 60 requests/minute per credential and 200/minute per deployment (defaults), shared with the agent's other machine channels.

curl -s https://agents.foral.ai/<slug>/.well-known/agent-card.json \
  -H "A2A-Version: 1.0"

curl -s https://agents.foral.ai/<slug>/a2a \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  -d '{
    "jsonrpc": "2.0", "id": 2, "method": "SendMessage",
    "params": {"message": {
      "messageId": "msg-0002", "role": "ROLE_USER",
      "parts": [{"data": {"skill": "assess_project_fit",
                          "input": {"project_type": "moradia", "municipality": "Lagos",
                                    "area_m2": 180}},
                 "mediaType": "application/json"}]
    }}
  }'

curl -s https://agents.foral.ai/<slug>/a2a \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  -d '{"jsonrpc": "2.0", "id": 3, "method": "GetTask", "params": {"id": "<task id>"}}'