Este projeto demonstra a criação de um agente inteligente básico utilizando o SDK A2A (Agent-to-Agent). O exemplo prático ensina como implementar um servidor de agente simples, capaz de responder a mensagens do usuário com uma saudação padronizada.

Especificações de Dependências

Versão do Python

• Python >= 3.10

Pacotes Essenciais

Pacote	Versão	Finalidade
a2a-sdk	>= 0.2.5	Framework principal do A2A
uvicorn	>= 0.34.2	Servidor ASGI para aplicações web
click	>= 8.1.8	Ferramenta de interface de linha de comando
httpx	>= 0.28.1	Cliente HTTP assíncrono
pydantic	>= 2.11.4	Validação e serialização de dados
python-dotenv	>= 1.1.0	Gerenciamento de variáveis de ambiente
langchain-google-genai	>= 2.1.4	Integração com IA Generativa do Google
langgraph	>= 0.4.1	Framework para processamento de grafos de linguagem

Estrutura do Projeto

helloworld/
├── __init__.py              # Arquivo de inicialização do pacote
├── __main__.py              # Ponto de entrada principal
├── agent_executor.py        # Implementação do executor do agente
├── test_client.py           # Cliente de teste
├── pyproject.toml           # Configuração do projeto e dependências
├── uv.lock                  # Arquivo de bloqueio de dependências
└── README.md                # Documentação do projeto

Configuração do Ambiente

1. Instalação do Gerenciador de Pacotes UV

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Usando pip
pip install uv

2. Clonagem do Repositório

git clone https://github.com/google-a2a/a2a-samples.git
cd a2a-samples/samples/python/agents/helloworld

3. Instalação das Dependências

uv sync

Arquitetura do Código

Componentes Principais

1. AgenteOláMundo (agent_executor.py)

class AgenteOlaMundo:
    """Agente responsável por gerar saudações."""
    
    async def executar_comando(self) -> str:
        return 'Olá Mundo'

2. ExecutorAgenteOláMundo (agent_executor.py)

class ExecutorAgenteOlaMundo(AgentExecutor):
    """Implementação do executor do agente."""
    
    async def executar(self, contexto: RequestContext, fila_eventos: EventQueue) -> None:
        resultado = await self.agente.executar_comando()
        fila_eventos.enfileirar_evento(nova_mensagem_texto_agente(resultado))

3. Configuração do Servidor (__main__.py)

• Definição de habilidades do agente (AgentSkill)
• Configuração de cartões de agente público e estendido (AgentCard)
• Configuração do manipulador de requisições e armazenamento de tarefas
• Inicialização do servidor Uvicorn

Execução do Projeto

1. Iniciar o Servidor do Agente

uv run .

O servidor será iniciado em http://localhost:9999.

2. Executar o Cliente de Teste

Em outro terminal:

uv run test_client.py

3. Verificar o Funcionamento

Acessar Informações do Cartão do Agente

curl http://localhost:9999/.well-known/agent.json

Acessar Cartão Estendido (requer autenticação)

curl -H "Authorization: Bearer dummy-token-for-extended-card" \
     http://localhost:9999/agent/authenticatedExtendedCard

Diagrama de Fluxo do Projeto

Interação entre Cliente e Servidor A2A

Note over Cliente,Servidor: 1. Fase de descoberta do serviço
Cliente->>Servidor: GET /.well-known/agent.json
Servidor-->>Cliente: Retorna cartão público do agente

Note over Cliente,Servidor: 2. Obtenção do cartão estendido (opcional)
Cliente->>Servidor: GET /agent/authenticatedExtendedCard
Servidor-->>Cliente: Retorna cartão estendido do agente

Note over Cliente,Servidor: 3. Fluxo de envio de mensagem
Cliente->>Servidor: POST /agent/message
Note over Servidor,Fila: 4. Processamento interno no servidor
Servidor->>Agente: Executa ExecutorAgenteOláMundo.executar()
Agente->>Agente: Executa AgenteOláMundo.executar_comando()
Agente-->>Fila: Gera mensagem "Olá Mundo"
Fila-->>Servidor: Retorna resultado da fila de eventos

Note over Cliente,Servidor: 5. Retorno da resposta
Servidor-->>Cliente: Retorna resposta da mensagem

</div>### Diagrama de Arquitetura do Sistema

<div>```
graph TB
    subgraph "Ambiente do Cliente"
        C1[Inicialização do cliente de teste]
        C2[A2ACardResolver - Resolução do cartão do agente]
        C3[A2AClient - Inicialização]
        C4[Envio de requisição de mensagem]
        C5[Processamento da resposta]
    end
    
    subgraph "Comunicação de Rede"
        N1[Requisição HTTP/HTTPS]
        N2[Transferência de dados JSON]
    end
    
    subgraph "Ambiente do Servidor"
        S1[A2AStarletteApplication - Servidor Web]
        S2[DefaultRequestHandler - Manipulador de requisições]
        S3[ExecutorAgenteOláMundo - Executor do agente]
        S4[AgenteOláMundo - Lógica central do agente]
        S5[InMemoryTaskStore - Armazenamento de tarefas]
        S6[EventQueue - Fila de eventos]
    end
    
    subgraph "Configuração do Agente"
        A1[Cartão público do agente - Habilidades básicas]
        A2[Cartão estendido do agente - Habilidades avançadas]
    end
    
    C1 --> C2
    C2 --> C3
    C3 --> C4
    C4 --> C5
    
    C4 --> N1
    N1 --> N2
    N2 --> S1
    S1 --> N2
    N2 --> C5
    
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S6
    S6 --> S3
    S3 --> S2
    S2 --> S1
    
    A1 --> S1
    A2 --> S1
    S2 --> S5

    style C3 fill:#e3f2fd
    style S1 fill:#f3e5f5
    style S4 fill:#e8f5e8
    style N2 fill:#fff3e0

Endpoints Públicos

Endpoint	Método	Descrição
/.well-known/agent.json	GET	Obter informações do cartão público do agente
/agent/message	POST	Enviar mensagem para o agente
/agent/message/stream	POST	Enviar mensagem via streaming

Endpoint Autenticado

Endpoint	Método	Descrição	Autenticação
/agent/authenticatedExtendedCard	GET	Obter cartão estendido do agente	Bearer Token

Configuração de Habilidades

Habilidade Básica

• ID: ola_mundo
• Nome: Retorna olá mundo
• Descrição: Apenas retorna olá mundo
• Exemplos: ['oi', 'olá mundo']

Habilidade Estendida (requer autenticação)

• ID: super_ola_mundo
• Nome: Retorna um SUPER Olá Mundo
• Descrição: Uma saudação mais entusiasmada, apenas para usuários autenticados
• Exemplos: ['super oi', 'dê-me um super olá']

Solução de Problemas

Problemas Comuns

1. Porta ocupada

# Verificar uso da porta
lsof -i :9999
# Matar processo
kill -9 <PID>

2. Falha na instalação de dependências

# Limpar cache e reinstalar
uv cache clean
uv sync --reinstall

3. Incompatibilidade de versão do Python

# Verificar versão do Python
python --version
# Garantir que seja >= 3.10

Desenvolvimento de Extensões

Adicionar Nova Habilidade

1. Definir um novo AgentSkill em __main__.py
2. Modificar a lógica em agent_executor.py
3. Atualizar a configuração do cartão do agente

Integrar API Externa

1. Adicionar nova dependência em pyproject.toml
2. Implementar a chamada da API em agent_executor.py
3. Gerenciar respostas assíncronas e erros