API nativa

Você pode interagir com agentes de IA usando a API nativa.

Autenticação

Se o agente estiver configurado com um tipo de API privado, cada requisição deve incluir o token de API. Para um tipo de API pública, não é necessário token para enviar requisições.

O token é enviado no seguinte formato:

--header "authorization: Bearer $TOKEN"

Nos exemplos em cURL, você pode:

• informar o token manualmente substituindo $TOKEN pelo seu token real em cada requisição; ou
• usar uma variável de ambiente para não precisar inserir o token todas as vezes:

export TOKEN=your_access_token

Nesse caso, a variável $TOKEN será substituída automaticamente.

Nos exemplos em Python e Node.js, o token é especificado diretamente no código como {{token}}. Recomendamos armazená-lo em variáveis de ambiente ou arquivos de configuração, em vez de deixá-lo no código, para evitar vazamentos.

ID do agente

Para interagir com um agente, você também precisa do seu ID, que pode ser encontrado na aba Dashboard do painel de controle do agente.

Configuração do agente

Ao usar a API nativa, o agente utiliza as configurações definidas no Área de Testes.

Enviar uma mensagem para o agente

Este método permite enviar uma mensagem ao agente de IA e receber uma resposta.

Requisição:

POST /api/v1/cloud-ai/agents/{agent_id}/call

cURL:

curl --request POST \
  --url https://agent.hostman.com/api/v1/cloud-ai/agents/<agent_id>/call \
  --header "authorization: Bearer $TOKEN" \
  --header "content-type: application/json" \
  --data '{ "message": "Hello!", "parent_message_id": "3adfea84-bcdb-44b5-8914-92035e75ec24" }'

Python:

import requests

url = "https://agent.hostman.com/api/v1/cloud-ai/agents/<agent_id>/call"

payload = {
    "message": "Hi",
    "parent_message_id": "3adfea84-bcdb-44b5-8914-92035e75ec24"
}
headers = {
    "content-type": "application/json",
    "authorization": "Bearer {{token}}"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())

Node.js:

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://agent.hostman.com/api/v1/cloud-ai/agents/<agent_id>/call',
  headers: {'content-type': 'application/json', authorization: 'Bearer {{token}}'},
  body: {message: 'Hi', parent_message_id: '3adfea84-bcdb-44b5-8914-92035e75ec24'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Parâmetros:

• message: texto da mensagem enviada ao agente
• parent_message_id: opcional. ID de uma mensagem para continuar uma conversa. Pode ser a última mensagem ou qualquer outro ID da conversa

Exemplo de resposta:

{
  "message": "agent's reply",
  "id": "340b7381-2834-4b98-a51c-e68f8d0abd5b",
  "response_id": "ed08981f-126b-49e7-856d-d122b3a53f26"
}

O valor id na resposta pode ser usado como parent_message_id em requisições subsequentes.

O campo finish_reason indica por que a geração da resposta foi finalizada. Valores possíveis:

• stop: a resposta foi gerada completamente sem erros;
• length: a resposta excedeu o limite máximo de tokens e foi interrompida;
• content_filter: um filtro do provedor de IA (por exemplo, OpenAI, xAI) foi acionado, interrompendo a geração. Os filtros podem incluir moderação de conteúdo pelo provedor;
• error: ocorreu um erro durante a geração. Para investigar, entre em contato com o suporte e inclua o corpo da resposta.