Agentes

Os endpoints de Agentes são somente leitura. Eles permitem descobrir agentes não arquivados da organização do token e consultar a configuração completa de um agente específico.

Todas as chamadas exigem Authorization: Bearer pk_.... A base é https://api.squados.io/v1; consulte Autenticação e Erros para os contratos compartilhados.

Listar agentes

`GET /agents`

Retorna os agentes da organização, do mais novo para o mais antigo. Agentes arquivados nunca entram na listagem.

Query	Tipo	Padrão	Comportamento atual
`limit`	inteiro	`50`	Tamanho da página. O máximo é `100`; valores maiores são reduzidos para 100.
`offset`	inteiro	`0`	Quantidade de agentes ignorados antes da página.
`active`	booleano	`true`	Ausente ou diferente do texto literal `false`: retorna somente ativos. `false`: remove o filtro e retorna ativos e inativos.

curl "https://api.squados.io/v1/agents?limit=20&offset=0&active=true" \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta 200

{
  "agents": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Suporte ao Cliente",
      "description": "Responde dúvidas sobre produtos e pedidos.",
      "model": "openai/gpt-4o-mini",
      "avatar_url": null,
      "is_public": true,
      "active": true,
      "temperature": 0.7,
      "history_limit": 20,
      "created_at": "2026-01-15T10:30:00Z",
      "conversation_count": 1482,
      "bases_count": 2
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

total considera todos os agentes que correspondem ao filtro atual, não apenas a página retornada. Uma página sem resultados devolve agents: [] e total: 0.

Campos da listagem

model é o slug do modelo associado. Se o agente não tiver modelo vinculado, a API devolve o slug do modelo padrão ativo do sistema.
description e avatar_url podem ser null.
conversation_count conta conversas associadas ao agente.
bases_count conta vínculos do agente com bases de conhecimento.
Falha ao consultar os agentes retorna 500 internal_error.

Consultar um agente

`GET /agents/{agentId}`

O UUID precisa identificar um agente não arquivado da organização do token.

curl "https://api.squados.io/v1/agents/AGENT_ID" \
  -H "Authorization: Bearer pk_sua_chave_aqui"

Resposta 200

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Suporte ao Cliente",
  "description": "Responde dúvidas sobre produtos e pedidos.",
  "prompt": "Você é um assistente de suporte objetivo e cordial.",
  "model": "openai/gpt-4o-mini",
  "model_details": {
    "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "name": "GPT-4o mini",
    "provider": "openai",
    "supports_vision": true,
    "supports_files": true
  },
  "avatar_url": null,
  "is_public": true,
  "active": true,
  "temperature": 0.7,
  "history_limit": 20,
  "created_at": "2026-01-15T10:30:00Z",
  "bases": [
    {
      "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "name": "Catálogo de Produtos"
    }
  ],
  "tools_count": 3,
  "conversation_count": 1482
}

Como interpretar o detalhe

prompt contém o prompt de sistema completo do agente. Trate esse campo como configuração sensível da sua organização.
model sempre traz um slug: usa o modelo vinculado ou o padrão ativo do sistema.
model_details contém os dados do modelo vinculado e pode ser null quando o agente depende do modelo padrão.
bases contém somente id e name das bases vinculadas.
tools_count conta apenas ferramentas nativas ativas em agent_native_tools; não é a soma de todas as integrações e ferramentas personalizadas disponíveis ao agente.
conversation_count conta as conversas associadas ao agente.

Erros e limites

Situação	Resposta
`agentId` não é um UUID válido	`400 invalid_request`
Agente ausente, arquivado ou de outra organização	`404 not_found`
Token ausente, inválido ou revogado	`401 unauthorized`

Não existem operações públicas de criação, edição, ativação, desativação ou arquivamento de agentes na API v1. Faça essas ações no produto e use estes endpoints para leitura e integração.