Data Grants

Data Grants sao o sistema de permissao do Hashee para acesso de agentes a dados do usuario. Eles garantem que os usuarios permanecam no controle de quais informacoes os agentes podem acessar.

Como Funciona

1. Agente solicita acesso — Seu agente envia uma solicitacao de data grant especificando quais dados precisa e por que.
2. Usuario analisa — O aplicativo Hashee apresenta a solicitacao ao usuario com descricoes claras de escopo.
3. Usuario decide — O usuario explicitamente aprova ou nega a solicitacao.
4. Acesso concedido — Se aprovado, seu agente pode acessar os dados especificados dentro do escopo concedido.

Principios de Design

Data Grants seguem o modelo de soberania de dados do Hashee:

• Iniciado pelo usuario — O usuario deve aprovar explicitamente cada grant. Sem coleta silenciosa de dados.
• Com escopo definido — Cada grant especifica exatamente quais dados sao acessiveis. Sem permissoes genericas.
• Revogavel — Usuarios podem revogar qualquer grant a qualquer momento nas configuracoes.
• Transparente — Usuarios podem ver todos os grants ativos e quais dados cada agente tem acesso.
• Auditavel — Todas as solicitacoes e decisoes de grant sao registradas.

Solicitando um Grant

Solicitacoes de data grant sao entregues como interacoes de Artifact. Seu agente envia um artifact com os detalhes da solicitacao de grant, e o usuario responde atraves do A2H Protocol:

await agent.sendArtifact(conversationId, {
  artifact: {
    a2h: "0.3",
    subtype: "form",
    blocks: [
      {
        tag: "text",
        key: "explanation",
        content: "I need access to your knowledge base to provide personalized recommendations.",
      },
      {
        tag: "action",
        key: "approve",
        label: "Grant Access",
        variant: "primary",
      },
      {
        tag: "action",
        key: "deny",
        label: "Deny",
        variant: "secondary",
      },
    ],
  },
  title: "Data Access Request",
  summary: "Requesting access to your knowledge base",
  forwardable: false,
});

Escopos

Escopo	Descricao
knowledge:read	Ler itens da base de conhecimento do usuario
profile:read	Ler informacoes do perfil do usuario
conversations:read	Ler historico de conversas (dentro da relacao H2A)

Boas Praticas

• Solicite escopos minimos — Peca apenas os dados que realmente precisa.
• Explique o motivo — Inclua uma explicacao clara de como os dados serao usados.
• Trate negacoes graciosamente — Seu agente deve funcionar com funcionalidade reduzida se um grant for negado.
• Respeite revogacoes — Se um usuario revogar um grant, pare de usar aqueles dados imediatamente.

Proximos Passos

• Artifacts — A2H Protocol para solicitacoes interativas
• Webhooks — Receba notificacoes de mudanca de grant
• Autenticacao — Referencia do fluxo de auth