A2A Samples: Hello World Agent

Visão Geral do Projeto

Este é um exemplo simples de agente Hello World baseado no A2A (Agent-to-Agent) SDK. Este projeto demonstra como criar um servidor de agente inteligente básico que pode responder a mensagens de usuários e retornar saudações simples.

Descrição das Versões de Dependências

Requisitos de Versão do Python

• Python >= 3.10

Principais Pacotes de Dependências

Estrutura do Projeto

helloworld/
├── __init__.py              # Arquivo de inicialização do pacote
├── __main__.py              # Ponto de entrada do programa principal
├── agent_executor.py        # Implementação do executor de 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. Instalar o Gerenciador de Pacotes UV

Se você ainda não instalou o UV, instale primeiro:

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

# ou use pip
pip install uv

2. Clonar o Projeto

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

3. Instalar Dependências

O UV instalará automaticamente todas as dependências de acordo com os arquivos pyproject.toml e uv.lock:

uv sync

Descrição da Arquitetura do Código

Componentes Principais

1. HelloWorldAgent (agent_executor.py)

class HelloWorldAgent:
    """Hello World Agent."""
    
    async def invoke(self) -> str:
        return 'Hello World'

2. HelloWorldAgentExecutor (agent_executor.py)

class HelloWorldAgentExecutor(AgentExecutor):
    """Implementação do executor de agente"""
    
    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
        result = await self.agent.invoke()
        event_queue.enqueue_event(new_agent_text_message(result))

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

• Definir habilidades do agente (AgentSkill)
• Configurar cartões de agente públicos e estendidos (AgentCard)
• Configurar manipuladores de requisição e armazenamento de tarefas
• Iniciar servidor Uvicorn

Passos de Execução

1. Iniciar o Servidor do Agente

uv run .

O servidor iniciará em http://localhost:9999.

2. Executar o Cliente de Teste

Em outra janela do terminal:

uv run test_client.py

3. Verificar o Serviço

Você pode verificar se o serviço está funcionando corretamente das seguintes maneiras:

Acessar Informações do Cartão do Agente

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

Acessar Cartão de Agente Estendido (Autenticação Necessária)

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

Fluxograma do Projeto

Fluxo de Interação Cliente-Servidor A2A

sequenceDiagram
    participant Client as A2A Client
    participant Server as A2A Server
    participant Agent as HelloWorldAgent
    participant Queue as EventQueue
    
    Note over Client,Server: 1. Fase de Descoberta de Serviço
    Client->>Server: GET /.well-known/agent.json
    Server-->>Client: Retornar cartão de agente público
    
    Note over Client,Server: 2. Recuperação de Cartão Estendido (Opcional)
    Client->>Server: GET /agent/authenticatedExtendedCard<br/>(with Bearer token)
    Server-->>Client: Retornar cartão de agente estendido
    
    Note over Client,Server: 3. Fluxo de Envio de Mensagem
    Client->>Server: POST /agent/message<br/>{"message": {"role": "user", "parts": [...]}}
    
    Note over Server,Queue: 4. Processamento Interno do Servidor
    Server->>Agent: Chamar HelloWorldAgentExecutor.execute()
    Agent->>Agent: Executar HelloWorldAgent.invoke()
    Agent-->>Queue: Gerar mensagem "Hello World"
    Queue-->>Server: Retornar resultado da fila de eventos
    
    Note over Client,Server: 5. Retorno de Resposta
    Server-->>Client: Retornar resposta da mensagem
    
    Note over Client,Server: 6. Processamento de Mensagem em Streaming (Opcional)
    Client->>Server: POST /agent/message/stream
    Server-->>Client: Retornar chunks de mensagem em streaming
    Server-->>Client: Chunk de Mensagem 1
    Server-->>Client: Chunk de Mensagem 2
    Server-->>Client: Marcador de Fim

Fluxograma da Arquitetura do Sistema

graph TB
    subgraph "Ambiente Cliente"
        C1[Inicialização do Cliente de Teste]
        C2[A2ACardResolver<br/>Análise do Cartão do Agente]
        C3[A2AClient<br/>Inicialização]
        C4[Enviar Requisição de Mensagem]
        C5[Processar Resposta]
    end
    
    subgraph "Comunicação de Rede"
        N1[Requisição HTTP/HTTPS]
        N2[Transferência de Dados JSON]
    end
    
    subgraph "Ambiente Servidor"
        S1[A2AStarletteApplication<br/>Servidor Web]
        S2[DefaultRequestHandler<br/>Manipulador de Requisição]
        S3[HelloWorldAgentExecutor<br/>Executor de Agente]
        S4[HelloWorldAgent<br/>Lógica Principal do Agente]
        S5[InMemoryTaskStore<br/>Armazenamento de Tarefas]
        S6[EventQueue<br/>Fila de Eventos]
    end
    
    subgraph "Configuração do Agente"
        A1[Cartão de Agente Público<br/>Habilidades Básicas]
        A2[Cartão de Agente Estendido<br/>Habilidades Aprimoradas]
    end
    
    %% Fluxo do Cliente
    C1 --> C2
    C2 --> C3
    C3 --> C4
    C4 --> C5
    
    %% Comunicação de Rede
    C4 --> N1
    N1 --> N2
    N2 --> S1
    S1 --> N2
    N2 --> C5
    
    %% Fluxo do Servidor
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S6
    S6 --> S3
    S3 --> S2
    S2 --> S1
    
    %% Associação de Configuração
    A1 --> S1
    A2 --> S1
    S2 --> S5
    
    %% Estilização
    style C3 fill:#e3f2fd
    style S1 fill:#f3e5f5
    style S4 fill:#e8f5e8
    style N2 fill:#fff3e0

Endpoints da API

Endpoints Públicos

Endpoints de Autenticação

Configuração de Habilidades

Habilidades Básicas

• ID: hello_world
• Nome: Returns hello world
• Descrição: just returns hello world
• Exemplos: ['hi', 'hello world']

Habilidades Estendidas (Autenticação Necessária)

• ID: super_hello_world
• Nome: Returns a SUPER Hello World
• Descrição: A more enthusiastic greeting, only for authenticated users
• Exemplos: ['super hi', 'give me a super hello']

Solução de Problemas

Problemas Comuns

1. Porta Ocupada

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

2. Falha na Instalação de Dependências

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

3. Versão do Python Incompatível

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

Desenvolvimento de Extensões

Adicionar Novas Habilidades

1. Definir nova AgentSkill em __main__.py
2. Modificar processamento de lógica em agent_executor.py
3. Atualizar configuração do cartão do agente

Integração de API Externa

1. Adicionar novas dependências em pyproject.toml
2. Implementar chamadas de API em agent_executor.py
3. Lidar com respostas assíncronas e erros

Resumo

Este exemplo Hello World demonstra o uso básico do A2A SDK, incluindo:

• Criação e configuração do servidor de agente
• Definição e gerenciamento de habilidades
• Comunicação cliente-servidor
• Autenticação e funcionalidade estendida

Através deste exemplo, você pode rapidamente entender como construir suas próprias aplicações de agentes inteligentes.