PromptAgentSession - DataWorks: Central de Documentação do Alibaba Cloud

Envia um prompt de usuário para uma sessão existente e transmite a resposta do agente em streaming.

Descrição da operação

Descrição da solicitação

Esta operação de API envia um prompt de usuário para um ID de sessão especificado e aceita a resposta do agente como fluxos de Server-Sent Events (SSE).
A resposta pode incluir fragmentos de mensagens, procedimentos de raciocínio e atualizações de status de invocação de ferramentas.
Se a sessão especificada não existir, um erro 400 será retornado em um quadro de erro SSE.
O campo stopReason indica o motivo pelo qual o agente interrompeu o turno de conversa atual.
Esta operação suporta vários tipos de blocos de conteúdo como entrada de prompt, como texto e links de download de arquivos do OSS.
Você pode, opcionalmente, fornecer metadados adicionais em Meta para passar mais contexto ao servidor.
O conteúdo retornado está em conformidade com a especificação de código aberto Agent Client Protocol (ACP). Para mais informações, consulte https://agentclientprotocol.com.
Antes de usar esta operação de API, certifique-se de compreender totalmente os métodos de cobrança e os preços do Data Agent: https://www.alibabacloud.com/help/en/dataworks/dataworks-data-agent-agent-billing

Tarefas de longa duração e recuperação de tempo limite

Para tarefas de longa duração que podem exceder o tempo limite de solicitação única, após a liberação canário do GetAgentSessionEvents ser ativada para a conta atual e a região de destino, primeiro estabeleça uma assinatura de Events e, em seguida, chame PromptAgentSession para ler ambos os fluxos em paralelo. Use Events para exibir o progresso em tempo real e use o fluxo Prompt para ler o estado final e os erros de negócio do turno atual. Cada mensagem é exibida apenas uma vez.

Se o fluxo Prompt atingir o tempo limite ou for desconectado antes que o estado final de negócio seja recebido, o resultado do turno atual será desconhecido. Continue a observar Events e chame LoadAgentSession quando precisar verificar o histórico da sessão. Não reenvie o prompt automaticamente.

Experimente agora

Experimente esta API no OpenAPI Explorer, sem necessidade de assinatura manual. Chamadas bem-sucedidas geram automaticamente código SDK correspondente aos seus parâmetros. Faça o download com segurança de credenciais integrada para uso local.

Testar

Autorização RAM

A tabela abaixo descreve a autorização necessária para chamar esta API. Você pode defini-la em uma política do Resource Access Management (RAM). As colunas da tabela estão detalhadas abaixo:

Ação: As ações que podem ser usadas no elemento Action das instruções de política de permissão do RAM para conceder permissões para executar a operação.
API: A API que você pode chamar para executar a ação.
Nível de acesso: O nível de acesso predefinido concedido para cada API. Valores válidos: create, list, get, update e delete.
Tipo de recurso: O tipo de recurso que suporta autorização para executar a ação. Indica se a ação suporta permissão em nível de recurso. O recurso especificado deve ser compatível com a ação. Caso contrário, a política será ineficaz.
- Para APIs com permissões em nível de recurso, os tipos de recursos obrigatórios são marcados com um asterisco (*). Especifique o Nome de Recurso Alibaba Cloud (ARN) correspondente no elemento Resource da política.
- Para APIs sem permissões em nível de recurso, é exibido como Todos os Recursos. Use um asterisco (*) no elemento Resource da política.
Chave de condição: As chaves de condição definidas pelo serviço. A chave permite controle granular, aplicando-se somente a ações ou a ações associadas a recursos específicos. Além das chaves de condição específicas do serviço, o Alibaba Cloud fornece um conjunto de chaves de condição comuns aplicáveis a todos os serviços compatíveis com RAM.
Ação dependente: As ações dependentes necessárias para executar a ação. Para concluir a ação, o usuário RAM ou a função RAM deve ter permissões para executar todas as ações dependentes.

Ação

Nível de acesso

Tipo de recurso

Chave de condição

Ação dependente

dataworks:PromptAgentSession

none

*All resources.

*

Nenhuma

Sintaxe da solicitação

POST  HTTP/1.1

Parâmetros da solicitação

Parâmetro	Tipo	Obrigatório	Descrição	Exemplo
Jsonrpc	string	Não	A versão do JSON-RPC. Fixada em 2.0.	2.0
Id	string	Não	O ID passado pelo solicitante, que é retornado exatamente como foi recebido.	1021418411
Params	object	Não	Os parâmetros de negócio.
Meta	object	Não	Os metadados estendidos. Importante Se o nome do agente vinculado à sessão especificada for dataworks_ai_assistant_agent (AI Assistant Service), você deverá fornecer o ID da instância do AI Assistant Service no campo Context.agent.instanceId dos metadados estendidos.
Context	any	Não	O tipo de mapa. Em cenários de agente personalizado, você pode usar este valor para substituir parâmetros de espaço reservado específicos.	{ "key1": "value1", "key2": "value2" }
Prompt	array<object>	Não	A matriz de blocos de conteúdo de mensagens do usuário. Para mais informações, consulte https://agentclientprotocol.com/protocol/content.
	array<object>	Não
Description	string	Não	A descrição do arquivo.	Valid when Type is set to resource_link. Example: Sales order details.csv
Meta	object	Não	Os metadados de prompt estendidos do DataWorks.
Hide	boolean	Não	Especifica se o prompt deve ser ocultado do usuário. Por exemplo, se um usuário fizer uma pergunta na caixa de diálogo de chat, como "Valor de vendas nos últimos 7 dias", e o sistema chamador recuperar o conhecimento do domínio de negócio por meio de RAG antes de chamar a operação de API para complementar o contexto do agente sem exibi-lo ao usuário, defina este parâmetro como true.	true
MimeType	string	Não	O tipo MIME do arquivo.	Valid when Type is set to resource_link. Example: text/csv
Name	string	Não	O nome do arquivo.	Valid when Type is set to resource_link. Example: xxx.csv
Size	integer	Não	O tamanho do arquivo, em bytes. Válido apenas quando Type é definido como resource_link.	1231231
Text	string	Não	Conteúdo de texto	Valid when Type is set to text. Example: Sales amount in the last 7 days
Title	string	Não	O título do arquivo.	Valid when Type is set to resource_link. Example: Sales order details.csv
Type	string	Não	Tipo de bloco de conteúdo	Currently supported values: text and resource_link
Uri	string	Não	O URI do arquivo.	Valid when Type is set to resource_link. Example: oss://${bucket}/${ossKey}
SessionId	string	Não	O ID da sessão de destino. Se a sessão não existir, um quadro de erro SSE será retornado.	sess_0f12abc34

Elementos de resposta

Elemento	Tipo	Descrição	Exemplo
	object
Error	any	A mensagem de erro no quadro SSE. O conteúdo retornado está em conformidade com a especificação de código aberto Agent Client Protocol (ACP). Para mais informações, consulte https://agentclientprotocol.com/protocol/prompt-turn.	{"code": 400, "errorCode": "0x50000000001", "message": "not exist session", "data": null}
Id	string	O ID passado pelo solicitante, que é retornado exatamente como foi recebido.	631478864897630XXXX
Jsonrpc	string	A versão do JSON-RPC. Fixada em 2.0.	2.0
Meta	object	Os metadados de continuação de eventos.
EventCursor	object	O cursor de continuação de eventos.
EventEpoch	string	A época do fluxo de eventos.	f7c6a27a-09f6-4bc9-b924-0c360351373c
EventId	string	O ID do evento.	4
EventType	string	O tipo de evento.	session_update
PromptId	string	O ID de execução do prompt.	p1
SessionId	string	O ID da sessão.	79fea58a-45f5-45c6-9169-c59beac0d5b6
Method	string	O método SSE. O conteúdo retornado está em conformidade com a especificação de código aberto Agent Client Protocol (ACP). Para mais informações, consulte https://agentclientprotocol.com/protocol/prompt-turn.	session/update
Params	any	Os parâmetros SSE. O conteúdo retornado está em conformidade com a especificação de código aberto Agent Client Protocol (ACP). Para mais informações, consulte https://agentclientprotocol.com/protocol/prompt-turn.	{"sessionId":"af4f5ef8-e8f5-481c-ad1f-94886c6c0aed","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"hello world"}}}
RequestId	string	O ID da solicitação desta invocação de API, que é usado para solucionar problemas de invocação.	D5D70885-7CC7-594A-80C7-2EF1B00FFB4B
Result	any	O conjunto de resultados do quadro SSE. O conteúdo retornado está em conformidade com a especificação de código aberto Agent Client Protocol (ACP). Para mais informações, consulte https://agentclientprotocol.com/protocol/prompt-turn.	{"stopReason":"end_turn"}
Timestamp	integer	O timestamp.	1747447032

Exemplos

Resposta de sucesso

JSON formato

{
  "Error": "{\"code\": 400, \"errorCode\": \"0x50000000001\", \"message\": \"not exist session\", \"data\": null}",
  "Id": "631478864897630XXXX",
  "Jsonrpc": "2.0",
  "Meta": {
    "EventCursor": {
      "EventEpoch": "f7c6a27a-09f6-4bc9-b924-0c360351373c",
      "EventId": "4",
      "EventType": "session_update",
      "PromptId": "p1",
      "SessionId": "79fea58a-45f5-45c6-9169-c59beac0d5b6"
    }
  },
  "Method": "session/update",
  "Params": "{\"sessionId\":\"af4f5ef8-e8f5-481c-ad1f-94886c6c0aed\",\"update\":{\"sessionUpdate\":\"agent_message_chunk\",\"content\":{\"type\":\"text\",\"text\":\"hello world\"}}}",
  "RequestId": "D5D70885-7CC7-594A-80C7-2EF1B00FFB4B",
  "Result": "{\"stopReason\":\"end_turn\"}\n",
  "Timestamp": 1747447032
}

Códigos de erro

Consulte Códigos de Erro para uma lista completa.

Notas de versão

Consulte Notas de Versão para uma lista completa.