Descrição do artigo: O AI Chat v2 mantém a forma simples de chamar a interface de conversação original, ao mesmo tempo que adiciona entrada multimodal, fluxo de eventos estruturado, chamada automática de ferramentas, pausa e retomada, execução assíncrona e gerenciamento de sessões. Este artigo começa com uma migração que quase não exige reescrever código e explica como essas mudanças afetam o desenvolvimento real de produtos.

Muitas interfaces de chat funcionam muito bem na fase de demonstração: envie uma pergunta, espere o modelo retornar um trecho de texto e então exiba o texto na página.

À medida que o produto avança, as coisas deixam de ser apenas “uma pergunta, uma resposta”. Os usuários fazem upload de PDFs e capturas de tela, e o modelo precisa pesquisar páginas da web, ler arquivos e até chamar ferramentas já autorizadas, como GitHub e Notion. Uma tarefa pode durar várias rodadas e, no meio do processo, parar para fazer perguntas adicionais por falta de informações. Nesse momento, se a interface ainda retornar apenas uma sequência de texto que cresce continuamente, será difícil para o frontend saber o que o modelo está fazendo, e o backend também terá dificuldade para determinar se a tarefa realmente terminou.

A API Ace Data Cloud AI Chat v2 resolve exatamente esse problema. Ela não derruba a forma original de conversação, mas, com base na compatibilidade com chamadas simples, divide uma resposta em eventos que os programas podem reconhecer e processar: o conteúdo principal é conteúdo principal, a chamada de ferramenta é chamada de ferramenta, e citações, arquivos, erros e estado final têm cada um um local claramente definido.

Ace Data Cloud AI Chat v2: entrada multimodal, ferramentas de Agent e fluxo de eventos estruturado

Figura: o AI Chat v2 não comprime mais toda a tarefa em um trecho de texto, mas mantém a estrutura dos eventos de entrada, ferramentas e saída.

A migração pode começar alterando apenas um endereço

Se o projeto estiver usando a versão anterior de /aichat/conversations, não é necessário reescrever primeiro a estrutura das mensagens, nem criar antes uma interface de Agent. A V2 continua aceitando campos como model, question, stateful, id, references e preset da versão original. A migração mínima exige apenas alterar o endereço da solicitação para:

https://api.acedata.cloud/aichat2/conversations

Uma solicitação mais básica continua sendo curta:

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": "请概括这份需求里最重要的三个问题。",
    "stateful": true
  }'

No modo JSON comum, a interface ainda retorna um resultado familiar:

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

Salve o id retornado e inclua o mesmo id na próxima solicitação para continuar a conversa. O padrão de stateful é true, usado para controlar se o contexto da sessão salva deve ser carregado e continuado.

Esta etapa é muito adequada para projetos reais: primeiro, valide se a autenticação, o modelo, a latência e os negócios existentes funcionam normalmente; depois, integre gradualmente os novos recursos. A migração não precisa estar vinculada à reformulação da interface no mesmo lançamento.

Quando arquivos e imagens entram na conversa, a ordem também se torna informação

O antigo question é adequado para texto puro. Em tarefas como “primeiro leia o relatório, depois compare com a captura de tela e, por fim, dê uma conclusão”, uma simples lista de anexos já não é suficientemente precisa. A V2 adiciona uma matriz estruturada message, na qual texto, imagens e arquivos podem ser inseridos em ordem:

{
  "model": "YOUR_SUPPORTED_MODEL",
  "stateful": true,
  "message": [
    {
      "type": "text",
      "text": "阅读报告,并把其中的趋势与后面的仪表盘截图进行对照。"
    },
    {
      "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 disponíveis incluem text, image_url e file_url. O importante não é apenas “suportar anexos”, mas que as relações entre os conteúdos não se percam durante a transmissão. O cliente pode informar claramente ao modelo: qual trecho é a descrição da tarefa, qual documento é o material original e o que deve ser comparado em seguida.

Para permitir uma migração suave dos clientes antigos, a V2 ainda reconhece references. URLs com extensões de imagem serão processadas como imagens, enquanto outras URLs serão processadas como arquivos. Se for apenas uma atualização de interface, é possível manter temporariamente a escrita original; se a ordem da entrada afetar a compreensão, recomenda-se usar message.

A resposta em streaming não é mais apenas “digitando”

A saída em streaming tradicional normalmente contém apenas incrementos de texto. Quando o modelo começa a pesquisar, ler arquivos ou chamar ferramentas externas, a página parece travada, os usuários não sabem se a tarefa continua e os desenvolvedores também não obtêm um estado claro.

O AI Chat v2 oferece três formas de resposta por meio do cabeçalho de solicitação accept:

Cenário de uso accept Forma de retorno
Solicitação simples no servidor application/json Retorna {answer, id} após a conclusão
Node, Python, CLI ou Worker application/x-ndjson Um evento JSON por linha
Frontend Web text/event-stream Fluxo de eventos SSE

Nos modos NDJSON e SSE, o retorno não contém apenas tokens, mas um conjunto de eventos tipados. text_delta é usado para incrementos do conteúdo principal, tool_use indica que o modelo está pronto para chamar uma ferramenta, tool_result retorna o resultado da ferramenta, citation fornece a fonte da citação, card e artifact carregam cartões ou artefatos que podem ser exibidos separadamente, error indica falha nesta rodada, e done fornece o uso e o motivo da finalização.

O consumidor Python abaixo concatena o conteúdo principal enquanto preserva os estados importantes:

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": "检索资料,给出带来源的简要结论。",
    "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("开始调用:", event.get("tool_name"))
        elif event_type == "tool_result":
            print("工具是否失败:", event.get("is_error"))
        elif event_type == "error":
            raise RuntimeError(event.get("message", "未知错误"))
        elif event_type == "done":
            print("用量:", event.get("usage"))
            print("终止原因:", event.get("terminal_reason"))

print("".join(answer))

Se o produto se preocupa apenas com o texto final, basta concatenar todos os text_delta.content; se for necessário criar uma interface de Agent observável, é possível renderizar separadamente chamadas de ferramentas, citações, artefatos e estados. As duas necessidades usam a mesma interface, sem ser necessário manter dois conjuntos de protocolos para “chat simples” e “tarefas complexas”.

A chamada de ferramentas está disponível por padrão, mas o produto ainda deve traçar limites claros

O V2 pode permitir que o modelo chame capacidades integradas, como pesquisa na web, extração de páginas e leitura de arquivos, conforme a necessidade da tarefa; depois que os usuários conectarem e autorizarem os serviços correspondentes, também poderão usar ferramentas MCP para processar dados externos, como GitHub e Notion.

No fluxo, tool_use e tool_result aparecerão separadamente, e ambos são pareados por meio de tool_id. Com isso, o frontend pode exibir o progresso real, e o backend também pode registrar o tempo gasto e o ponto de falha de cada ferramenta.

O fato de as ferramentas poderem ser chamadas automaticamente não significa que o escopo de execução deva ser liberado sem limites. max_turns é usado para restringir o número de rodadas de iteração do Agent em uma única solicitação, e o intervalo fornecido pela documentação é de 1 a 500; quando definido como 1, esta rodada realiza apenas uma chamada ao modelo e não continuará para chamadas de ferramentas. O ambiente de produção deve ser configurado ativamente de acordo com a complexidade da tarefa, o tempo de resposta e o orçamento de custos, em vez de depender por muito tempo de um limite padrão elevado.

Para Webhook, CI/CD ou tarefas de monitoramento, o V2 oferece suporte a async: true; as tarefas podem ser executadas em segundo plano, e os resultados podem ser obtidos por consulta ou por callback_url. Porém, ações que envolvem envio, publicação ou gravação exigem pré-autorização explícita por meio de allowed_skills, allowed_mcp_servers ou unattended_policy.

A conexão resolve “se é possível acessar”, enquanto a política de autorização resolve “se, desta vez, é permitido agir em nome do usuário”. Essas duas coisas não podem ser misturadas.

Quando o Agent não tem informações suficientes, não é necessário fingir que a tarefa já foi concluída

Tarefas complexas frequentemente ficam bloqueadas em questões específicas: em qual canal publicar, qual formato adotar, se deve substituir arquivos existentes. Para isso, o V2 fornece o evento ask_user_question. Depois que o evento aparece, a sessão entra no estado de espera pela entrada do usuário.

O cliente salva o id da sessão atual e o tool_id correspondente, exibe a pergunta e coleta a resposta; em seguida, usando o mesmo id da sessão, devolve a resposta por meio de tool_results, e a tarefa pode continuar a partir do ponto de pausa. Esse mecanismo também é adequado para criar nós de aprovação. Em vez de deixar o modelo adivinhar por conta própria quando faltam informações, é melhor devolver ao usuário as escolhas que estão faltando.

A própria sessão também pode ser gerenciada

O V2 adiciona um CRUD leve de sessões no mesmo endpoint, distinguindo retrieve, retrieve_batch, update e delete por meio de action.

retrieve_batch retorna resumos sem incluir messages completos, sendo adequado para a barra lateral de sessões; quando o usuário realmente abre uma sessão, chama-se então retrieve para ler o conteúdo. Para sessões longas, a organização de contexto do servidor também não substituirá as mensagens originais salvas por resumos. Quando for necessário continuar editando um artigo, verificar números ou preparar uma publicação, ainda se deve ler o texto original, em vez de usar um resumo no lugar do conteúdo.

Antes de entrar em produção, não valide apenas “se há texto retornado”

Depois de integrar uma interface de Agent, receber texto parcial não significa que esta rodada foi concluída de forma confiável; o fim do fluxo também não representa necessariamente o sucesso da tarefa. O cliente deve processar error e, após receber done, registrar usage e terminal_reason. No SSE, [DONE] indica apenas o fim da transmissão e não pode substituir eventos de erro que já tenham aparecido anteriormente.

O API Token deve ser armazenado apenas no servidor; o analisador de fluxo deve conseguir processar fragmentação de rede e novos eventos temporariamente desconhecidos; as chamadas de ferramentas devem ser pareadas por tool_id; links de citações e artefatos devem ser renderizados com segurança; conexões com permissão de gravação devem continuar mantendo confirmação humana ou uma autorização não supervisionada suficientemente restrita. Os nomes dos modelos, a cobrança e as capacidades disponíveis podem ser atualizados; na integração formal, devem prevalecer a documentação atual, a página do serviço e o console, sem deixar configurações de exemplo fixadas por muito tempo.

O ponto mais digno de atenção no AI Chat v2 não é adicionar mais alguns botões à janela de chat. Ele finalmente permite que os aplicativos vejam o que aconteceu dentro de uma tarefa de IA: quando o modelo produz texto, quando chama ferramentas, onde espera pelo usuário e com qual estado termina.

Se o projeto atual ainda é apenas uma caixa comum de perguntas e respostas, é possível primeiro alterar o endereço da interface e continuar usando o corpo de solicitação original. Depois que essa etapa estiver estável, integre message, NDJSON ou SSE, a linha do tempo de ferramentas e a pausa e retomada. A atualização pode ser pequena, mas ela deixa espaço suficiente para as próximas formas de produto.