Crie Aplicativos Agênticos com AceDataCloud AI Chat v2

Um endpoint de chat pode retornar texto. Um endpoint de agente pode inspecionar um arquivo, pesquisar na web, chamar uma ferramenta autorizada, pedir informações ausentes e transmitir cada etapa de volta para sua interface.

Essa é a diferença prática por trás do AceDataCloud AI Chat v2. O endpoint em POST https://api.acedata.cloud/aichat2/conversations preserva o estilo simples de requisição da API de conversação original, enquanto adiciona blocos de conteúdo multimodal, uso autônomo de ferramentas em múltiplas rodadas, conexões MCP, eventos de streaming estruturados, conversas retomáveis e ações CRUD de conversação.

Arquitetura do AI Chat v2: entradas multimodais, ferramentas de agente e eventos estruturados

Este guia concentra-se nas decisões de integração que importam ao passar de um chatbot básico para uma experiência de agente em produção.

O que muda no AI Chat v2?

O AI Chat v2 é uma atualização abrangente da interface original /aichat/conversations. Suas principais capacidades são:

  • Entrada multimodal: envie blocos ordenados de text, image_url e file_url em um único array message.
  • Uso autônomo de ferramentas: o modelo pode chamar ferramentas integradas e servidores MCP autorizados pelo usuário em múltiplas rodadas.
  • Streaming tipado: renderize texto, atividade de ferramentas, citações, cards, artefatos, erros e dados de conclusão como eventos separados.
  • Pausar e retomar: trate um evento ask_user_question e continue a mesma conversa com um resultado de ferramenta.
  • Gerenciamento de conversas: recupere, recupere em lote, atualize e exclua por meio de ações no mesmo endpoint.
  • Requisições compatíveis com versões anteriores: clientes existentes de model + question podem migrar alterando o caminho do endpoint.

A mudança arquitetural importante é que seu frontend não precisa mais tratar a resposta como uma única string opaca. Ele pode se tornar um espaço de trabalho orientado a eventos.

Comece pelo caminho compatível com versões anteriores

A migração de menor risco é intencionalmente pequena. Mantenha o corpo de requisição existente e altere apenas o endpoint:

curl -X POST 'https://api.acedata.cloud/aichat2/conversations' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer YOUR_API_TOKEN' \
  -H 'content-type: application/json' \
  -d '{
    "model": "YOUR_SUPPORTED_MODEL",
    "question": "Summarize the three most important points in this request.",
    "stateful": true
  }'

No modo JSON, a resposta mantém a estrutura familiar:

{
  "answer": "...",
  "id": "conversation-uuid"
}

Mantenha o id retornado. Enviá-lo na próxima requisição continua a conversa gerenciada sem exigir que seu cliente reenvie todo o histórico de mensagens.

stateful assume true por padrão. Defina-o explicitamente como false quando uma rodada não deve ser armazenada.

Esta primeira etapa de migração permite validar autenticação, disponibilidade do modelo, latência e comportamento da aplicação antes de introduzir ferramentas ou uma nova interface de streaming.

Use message quando a ordem e a modalidade importarem

O campo mais antigo question é conveniente para prompts somente de texto. Para texto misturado com imagens ou arquivos, use um array ordenado message:

{
  "model": "YOUR_SUPPORTED_MODEL",
  "stateful": true,
  "message": [
    {
      "type": "text",
      "text": "Read the attached report and compare its chart with this screenshot. Return five findings."
    },
    {
      "type": "file_url",
      "file_url": {
        "url": "https://example.com/report.pdf"
      }
    },
    {
      "type": "image_url",
      "image_url": {
        "url": "https://example.com/dashboard.png"
      }
    }
  ]
}

Os blocos de conteúdo compatíveis são:

Bloco Valor obrigatório Melhor uso
text text Instruções, contexto e perguntas
image_url image_url.url Capturas de tela, gráficos, imagens de produto
file_url file_url.url PDF, CSV, TXT e outros arquivos

O AI Chat v2 ainda reconhece o array mais antigo references. Extensões de imagem são convertidas em blocos de imagem, enquanto outras URLs se tornam blocos de arquivo. Essa compatibilidade é útil durante a migração, mas message é o melhor contrato de longo prazo quando a ordem do conteúdo importa.

Projete o cliente em torno de eventos, não apenas de tokens

Escolha o formato de resposta com o cabeçalho accept:

Cliente Cabeçalho Formato
Interface de navegador text/event-stream Eventos enviados pelo servidor
Node, Python, CLI, worker application/x-ndjson Um evento JSON por linha
Requisição simples de backend application/json Objeto final {answer, id}

Um consumidor NDJSON mínimo em Python pode montar texto enquanto preserva outros tipos de evento:

import json
import os
import requests

url = "https://api.acedata.cloud/aichat2/conversations"
headers = {
    "accept": "application/x-ndjson",
    "authorization": f"Bearer {os.environ['ACEDATA_API_TOKEN']}",
    "content-type": "application/json",
}
payload = {
    "model": os.environ["ACEDATA_CHAT_MODEL"],
    "question": "Research the topic, cite sources, and return a concise brief.",
    "stateful": True,
}

with requests.post(url, json=payload, headers=headers, stream=True, timeout=120) as response:
    response.raise_for_status()
    answer = []

    for raw_line in response.iter_lines():
        if not raw_line:
            continue

        event = json.loads(raw_line)
        event_type = event.get("type")

        if event_type == "text_delta":
            answer.append(event.get("content", ""))
        elif event_type == "tool_use":
            print("tool started:", event.get("tool_name"))
        elif event_type == "tool_result":
            print("tool finished; error =", event.get("is_error"))
        elif event_type == "citation":
            print("source:", event)
        elif event_type == "artifact":
            print("artifact:", event)
        elif event_type == "error":
            raise RuntimeError(event.get("message", "unknown agent error"))
        elif event_type == "done":
            print("usage:", event.get("usage"))
            print("terminal reason:", event.get("terminal_reason"))

print("".join(answer))

Interfaces de produção devem definir um renderizador ou manipulador para cada família de eventos:

  • text_delta atualiza a região de resposta.
  • tool_use e tool_result conduzem estados de atividade e visualizações de auditoria.
  • citation anexa fontes à saída relevante.
  • card renderiza pré-visualizações estruturadas.
  • artifact expõe uma entrega gerada separadamente.
  • thinking deve ser tratado apenas quando o modelo escolhido o expuser.
  • error encerra ou recupera a rodada atual.
  • done encerra o stream e registra o uso de tokens, além do motivo terminal.

Se sua interface precisar apenas da resposta final, concatene content de cada text_delta. Isso é equivalente ao answer retornado no modo JSON.

Deixe o agente usar ferramentas — mas torne a atividade visível

A chamada de ferramentas é ativada por padrão. O AI Chat v2 pode usar capacidades integradas como pesquisa na web, extração de páginas e leitura de arquivos. Ele também pode montar conexões MCP autorizadas pelo usuário, como Google Drive, Notion, Slack ou GitHub.

O stream expõe claramente o limite:

{"type":"tool_use","tool_id":"toolu_01","tool_name":"web_search","input":{"query":"topic"}}
{"type":"tool_result","tool_id":"toolu_01","output":"...","is_error":false}

Associe tool_use e tool_result por tool_id. Isso oferece suporte a indicadores de progresso, medições de latência, tratamento de erros e uma trilha de auditoria legível por operadores.

Use max_turns para restringir quantas rodadas autônomas de ferramentas podem ocorrer em uma requisição. O intervalo aceito é de 1–500; o padrão documentado é 500. Um valor menor reduz a execução aberta. Definir max_turns: 1 força uma única resposta e impede chamadas de ferramentas.

Um padrão prático de implantação é:

  1. Comece no modo JSON sem ferramentas na interface do produto.
  2. Adicione NDJSON ou SSE e renderize text_delta mais done.
  3. Exiba a atividade de ferramentas como uma linha do tempo recolhida.
  4. Adicione renderização de citações e artefatos.
  5. Defina um max_turns deliberado com base na complexidade da tarefa e na tolerância a custos.
  6. Habilite conexões com capacidade de escrita somente após revisar seu modelo de confirmação.

Trate perguntas como uma máquina de estados retomável

Um agente às vezes precisa de esclarecimentos. Nesse caso, o stream pode emitir ask_user_question, e a conversa entra em um estado awaiting_user_input.

Seu cliente deve:

  1. Salvar o id da conversa e o tool_id.
  2. Renderizar a pergunta e suas opções.
  3. Coletar a resposta do usuário.
  4. Enviar outra requisição com o mesmo id da conversa.
  5. Retornar a resposta por meio de tool_results para a chamada de ferramenta pendente. Isso é mais robusto do que fingir que o agente pode concluir com informações ausentes. Isso também torna possíveis portões de aprovação para ações sensíveis.

Separe a execução interativa e não assistida

Para webhooks, trabalhos de CI/CD e sistemas de monitoramento, async: true retorna um identificador de tarefa enquanto o trabalho continua. O resultado pode ser recuperado posteriormente ou entregue a uma URL de callback HTTP(S).

O acesso de escrita não assistido deve ser explícito. O AI Chat v2 oferece suporte a allowed_skills, allowed_mcp_servers ou a um objeto unattended_policy equivalente. Uma lista vazia não autoriza nenhuma capacidade. A pré-autorização não ignora o próprio mecanismo de segurança de um conector; uma habilidade que não oferece suporte à confirmação não assistida ainda deve executar uma simulação ou recusar a escrita.

Essa distinção importa: a disponibilidade da conexão não é o mesmo que a permissão para agir sem uma pessoa presente.

Lista de verificação de produção

Antes de lançar uma interface agêntica, verifique:

  • As credenciais da API são armazenadas no servidor, nunca no código do navegador.
  • Os nomes dos modelos vêm da lista atual de modelos suportados, em vez de suposições codificadas.
  • O analisador de stream tolera fragmentos parciais de rede e tipos de evento desconhecidos.
  • Os eventos de ferramenta são pareados por tool_id e os erros são registrados.
  • max_turns é definido intencionalmente.
  • As URLs de citações e artefatos são renderizadas com segurança.
  • ask_user_question persiste estado suficiente para retomar mais tarde.
  • Conexões com capacidade de escrita mantêm confirmação ou autorização não assistida com escopo restrito.
  • done.usage e terminal_reason alimentam a observabilidade.
  • As políticas de exclusão e retenção de conversas correspondem aos requisitos do seu produto.

O caminho mais curto de chatbot para agente

O AI Chat v2 não exige uma reescrita completa. Comece alterando o endpoint e preservando o corpo da sua solicitação atual. Em seguida, migre para blocos message multimodais, adote streaming estruturado, exponha o progresso das ferramentas e adicione o tratamento de pausa e retomada.

O resultado é um cliente que pode evoluir de respostas simples para um fluxo de trabalho de agente auditável — sem inventar um protocolo separado para arquivos, ferramentas, citações, artefatos ou esclarecimentos do usuário.

Recursos oficiais