Usar API

Oferecemos suporte a dois tipos de API para agentes de IA:

• API compatível com OpenAI: adequada para integração com bibliotecas e interfaces externas, utilizando a estrutura padrão de requisição.
• API nativa: mais simples e fácil de usar, especialmente quando é necessário obter um resultado rapidamente sem dependências externas.

Exemplos de requisições

API compatível com OpenAI

Exemplo de requisição:

POST https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/v1/chat/completions
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "model": "gpt-4",
  "messages": [
    {
      "role": "user",
      "content": "Hello"
    }
  ],
  "temperature": 1,
  "max_tokens": 100,
  "stream": false
}

Exemplo de resposta:

{
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "Hi! How can I help you?"
      }
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 14,
    "total_tokens": 26
  }
}

API nativa

Exemplo de requisição:

POST https://agent.hostman.com/api/v1/cloud-ai/agents/{{agent_id}}/call
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "message": "Hello",
  "parentmessageid": "3adfea84-bcdb-44b5-8914-92035e75ec24"
}

Exemplo de resposta:

{
  "message": "Hi! How can I help you?",
  "id": "340b7381-2834-4b98-a51c-e68f8d0abd5b",
  "response_id": "ed08981f-126b-49e7-856d-d122b3a53f26"
}

Principais diferenças

Qual API escolher

Use a API compatível com OpenAI se você:

• quiser integrar o agente com bibliotecas externas (por exemplo, LangChain, Open WebUI)
• já utiliza OpenAI e deseja apenas substituir a URL
• precisar de estatísticas de uso (tokens, modelo)
• precisar de respostas em streaming
• planejar usar mensagens multimodais

Use a API nativa se você:

• precisar de histórico de mensagens integrado sem enviar contexto explicitamente
• estiver desenvolvendo uma aplicação simples com poucas dependências externas
• quiser respostas em um formato simples
• precisar de uma integração rápida e leve, por exemplo, para um MVP