Olá sobreviventes,
Passei as ultimas horas migrando o projeto multiagente para a versão 1.0 do A2A e achei que valeria a pena compartilhar algumas descobertas. Talvez poupe algumas horas de sofrimento de quem estiver passando pelo mesmo processo.
A maior dificuldade foi que boa parte dos exemplos, vídeos, posts, respostas de IA ainda estão baseados na série 0.x do SDK.
O resultado é que muito código aparentemente correto simplesmente não funciona mais na v1.0.
Os erros que mais encontrei foram:
AttributeError: configuration
problemas com:
role="agent"
e também código usando:
ClientFactory.create(...)
que não existe mais da mesma forma.
O que mudou?
A principal mudança é arquitetural.
O SDK deixou de utilizar os modelos Pydantic internos e passou a trabalhar diretamente com os tipos gerados a partir da especificação Protobuf(Google - framework gRPC).
Na prática:
- O Protobuf virou a fonte principal da verdade.
- O
ClientFactoryfoi substituído porcreate_client(). - O fluxo agora gira em torno de
Message,SendMessageRequesteStreamResponse. - Os helpers foram centralizados em
a2a.helpers. AgentCardganhousupported_interfaces.AgentCapabilitiesperdeuinput_modeseoutput_modes.
Algumas mudanças rápidas de sintaxe
| Antes | Depois |
|---|---|
role="agent" | Role.ROLE_AGENT |
role="user" | Role.ROLE_USER |
ClientFactory.create() | await create_client() |
AgentCard(url=...) | supported_interfaces=[AgentInterface(...)] |
O erro mais complexo e traiçoeiro que encontrei
Esse aqui consumiu mais tempo do que deveria.
Você cria a mensagem normalmente:
msg = new_text_message(
"Olá",
role=Role.ROLE_USER
)
Tudo parece correto.
Então você tenta:
await client.send_message(msg)
e recebe:
AttributeError: configuration
O problema não está na Message.
O problema é que o método espera um SendMessageRequest, não uma Message.
O correto é:
request = SendMessageRequest()
request.message.CopyFrom(msg)
await client.send_message(request)
Depois disso tudo começou a funcionar normalmente.
Uma dica que acabou me salvando
Quando a documentação não estava clara, comecei a inspecionar diretamente os objetos protobuf.
Por exemplo:
Message.DESCRIPTOR.fields
SendMessageRequest.DESCRIPTOR.fields
Role.DESCRIPTOR
Também foi assim que descobri os enums corretos:
from a2a.types import Role
Role.ROLE_USER
Role.ROLE_AGENT
e até:
Role.Name(1)
Role.Value("ROLE_USER")
Se você estiver tentando descobrir o que realmente existe no protocolo, isso ajuda muito.
E afinal, a mudança valeu a pena?
Depois da dor inicial, sinceramente acho que sim.
Tenho que estudar mais contudo percebi:
- Suporte multilingue (Python, Java, C, ....)
- Mais controle sobre o protocolo (Server).
- Menos camadas escondidas.
- Menos acoplamento interno.
- Melhor interoperabilidade entre linguagens.
- Mais previsibilidade durante o debugging.
No meu caso, depois que entendi a nova estrutura, ficou muito mais fácil descobrir o que estava acontecendo olhando diretamente para os DESCRIPTORs do protocolo.
Guia oficial de migração
O material que realmente me ajudou a fechar a migração foi este:
https://github.com/a2aproject/a2a-python/blob/main/docs/migrations/v1_0/README.md
Recomendo fortemente a leitura antes de começar qualquer atualização de projeto.
Espero que isso ajude alguém que esteja travado na atualização de Supervisors, Executors, AgentCards ou no novo fluxo baseado em Protobuf.
Se alguém estiver passando pela mesma migração e quiser trocar experiências, ou acrescentar alguma info/crítica, fico feliz em ajudar no que eu conseguir.
