Migrating to a2a-sdk 1.0

Starting with abi-core-ai v1.12, the framework requires a2a-sdk>=1.0.0. This version changed AgentCard from a pydantic model to a protobuf message, which means it no longer accepts arbitrary fields.

Who is affected?

• Projects running on the ABI Docker image: Not affected. The image pins a2a-sdk==0.3.25.

• Projects that install abi-core-ai directly from PyPI: You need to update your config.py.

What changed

Before (0.3.x)	After (1.0+)
AgentCard is pydantic	AgentCard is protobuf
Accepts any kwargs	Only accepts protocol fields
card.url	card.supported_interfaces[0].url
AgentCard(**json_data)	load_agent_card(path) or build_agent_card(dict)

How to migrate your config.py

Before:

from a2a.types import AgentCard

def _load_agent_card():
    with open(config.AGENT_CARD) as f:
        data = json.load(f)
    return AgentCard(**data)

After:

from a2a.types import AgentCard
from abi_core.common.agent_card_loader import load_agent_card

def _load_agent_card():
    card, _meta = load_agent_card(config.AGENT_CARD)
    return card

The _meta dict contains ABI-specific fields that are no longer part of the protocol:

• meta["auth"] — HMAC credentials

• meta["id"] — agent identifier

• meta["supportedTasks"] — task list for semantic layer

• meta["llmConfig"] — LLM configuration

• meta["url"] — agent URL (backward compat)

Accessing the agent URL

Before:

url = card.url

After:

from abi_core.common.agent_card_loader import get_agent_url
url = get_agent_url(card)

Agent card JSON files

No changes needed. Your agent_cards/*.json files keep all the same fields. The loader separates protocol fields from ABI metadata automatically.

New projects

Projects created with abi-core create agent (v1.12+) already use the new pattern. No action needed.