API de Agentes de IA #

Um Agente de IA é o cérebro por detrás do seu bot: as suas instruções, personalidade, idioma, conhecimentos e ferramentas. Cria um Agente uma vez e depois direciona o tráfego para ele. Este guia abrange tudo o que pode fazer com um Agente através da API — criá-lo, configurá-lo, fornecer-lhe conhecimentos e ferramentas, rever os seus rascunhos e encaminhar conversas para ele.

• URL Base — https://api.youraiconnector.com/v1
• Autenticação — a sua chave de API (ver Autenticação)
• Erros e paginação — ver Erros e Paginação

Todos os exemplos abaixo mostram o formato de consulta ?apiKey= em cURL e o cabeçalho X-API-Key em JavaScript e Python — qualquer um funciona em todos os endpoints.

Se é novo no conceito de Agentes, leia primeiro Agentes de IA.

Como um Agente é estruturado #

Quatro elementos são geridos separadamente, e é útil saber qual é qual antes de começar:

Um novo Agente não responde a ninguém até que encaminhe conversas para ele. Criar um Agente não o coloca num canal. Esse é o passo que a maioria das integrações falha — consulte Encaminhar conversas para um Agente no final desta página.

O objeto Agente #

Um documento completo de Agente é grande — várias centenas de kilobytes, principalmente a sua lista de FAQs, as suas fontes de conhecimento e qualquer conteúdo de página lido a partir do seu site. Por isso, a listagem devolve uma linha de resumo curta por Agente quando a solicita:

{
  "id": "ag7HkQ2ZpLxR3mNb",
  "name": "Listing assistant",
  "active": true,
  "language": "en",
  "goal": "Book a viewing",
  "tags": [],
  "anthropic_model": "standard",
  "ai_speed": "balanced",
  "enable_bookings": false,
  "enable_follow_ups": true,
  "faq_refs_count": 42,
  "kb_source_refs_count": 3,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

O documento completo adiciona tudo o resto: instructions, rules, personality, availability, follow_up_config, as listas de FAQs e fontes de conhecimento ligadas, os blocos de texto gerados e qualquer estado de execução (tag_generation, optimize_run).

Algumas respostas também contêm substrate_campaign_id. É um registo interno mantido em contas mais antigas; nunca precisa de agir sobre ele e, em contas mais recentes, é null ou inexistente.

Listar Agentes #

GET /agents — todos os Agentes na conta, do mais recente para o mais antigo.

Este endpoint não é paginado. Por predefinição, cada Agente é devolvido com a sua configuração completa, o que é pesado: um único Agente pode atingir 580 KB e uma conta com 64 Agentes mais de 3 MB. Passe view=summary para obter uma linha curta por Agente e, em seguida, leia o que pretende com Obter um Agente.

Parâmetros de consulta

cURL

curl "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents?view=summary", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agents } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"view": "summary"},
)
agents = res.json()["agents"]

Resposta (200)

{
  "success": true,
  "agents": [
    { "id": "ag7HkQ2ZpLxR3mNb", "name": "Listing assistant", "active": true }
  ]
}

Criar um Agente #

POST /agents — apenas name é realmente necessário; envie qualquer configuração que já conheça juntamente com o mesmo. Um novo Agente está ativo por predefinição.

Campos do pedido (todos opcionais, exceto name)

Criar um Agente a partir do seu website. Inclua scrape_urls e a plataforma lê essas páginas e escreve as instruções por si. A resposta indica se essa geração foi iniciada, para que saiba se deve consultar o Agente para verificar o progresso.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Listing assistant",
    "language": "en",
    "instructions": "Answer questions about our listings and book viewings.",
    "goal": "Book a viewing"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Listing assistant",
    scrape_urls: ["https://example.com", "https://example.com/faq"],
  }),
});
const data = await res.json();
console.log(data.agent_id);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Listing assistant", "scrape_urls": ["https://example.com"]},
)
print(res.json()["agent_id"])

Resposta (201)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "substrate_campaign_id": null,
  "agent_generation_queued": true
}

agent_generation_queued é true quando a plataforma começou a escrever as instruções a partir das páginas que forneceu.

Um 400 significa que o corpo não era um objeto JSON, um campo foi rejeitado ou o Agente excede o tamanho de configuração permitido pelo seu plano. Um 403 significa que a conta não tem permissão para utilizar uma das definições que enviou — por exemplo, um nível de IA que o fornecedor da conta não concedeu.

Obter um Agente #

GET /agents/{agentId}

Passe fields com uma lista separada por vírgulas para obter apenas o que precisa, por exemplo fields=name,active,goal. O id é sempre incluído e os nomes que não existem no Agente são ignorados em vez de rejeitados. Omitir para obter o documento completo.

cURL

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?fields=name,active", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agent } = await res.json();

Python

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"fields": "name,active"},
)
agent = res.json()["agent"]

Um Agente que não existe na sua conta devolve 404.

Atualizar um Agente #

PUT /agents/{agentId} — envie apenas os campos que pretende alterar; tudo o resto permanece inalterado.

As definições aninhadas podem ser endereçadas folha a folha com uma chave pontuada, pelo que "availability.monday" altera apenas a segunda-feira e deixa o resto da semana inalterado.

Notas

• Para alterar o tipo de evento reservável em que o Agente efetua reservas, envie event_id (o id do evento, ou null para o limpar). Envie event_ids com uma matriz para associar vários de uma vez — o primeiro torna-se o principal e [] desassocia tudo. event_id e event_ids são mutuamente exclusivos, e o campo event em si não pode ser escrito diretamente.
• enable_bookings tem de ser um booleano real, e booking_provider tem de ser um de default, zenchef, formitable.
• Os campos de propriedade e identidade são ignorados, tal como o estado de execução interno (progresso da geração e otimização).
• O encaminhamento não é definido aqui. Utilize PUT /entry-points/channel-defaults para tornar o Agente o responsável por responder a um canal, POST /agents/{agentId}/entry-points para regras de palavras-chave e comentários, e PATCH /agents/{agentId}/active para o pausar ou retomar.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer questions about our listings and always offer a viewing.",
    "anthropic_model": "standard"
  }'

JavaScript

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ "availability.monday": { start_time: "09:00", end_time: "17:00" } }),
});

Python

requests.put(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"goal": "Book a viewing within three messages"},
)

Resposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Um corpo vazio devolve 400 com "No fields to update".

Atualizar definições do bot #

PUT /agents/{agentId}/bot-config — a forma restrita de alterar apenas as definições de conversação.

Um Agente não tem uma secção de bot separada: as suas definições residem diretamente no Agente, pelo que os nomes dos campos aqui são os mesmos que enviaria para PUT /agents/{agentId}. Este endpoint existe como a forma segura e focada de alterar alguns deles. É necessário pelo menos um campo.

Os nomes dos campos devem ser nomes simples aqui — letras, números, sublinhados e hífenes. Os caminhos pontuados não são aceites neste endpoint (ao contrário de PUT /agents/{agentId}), pelo que bot.goal é rejeitado com um 400.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Book a viewing within three messages", "ai_speed": "thorough" }'

O texto longo conta para o tamanho de configuração permitido pelo seu plano, pelo que um conjunto de instruções muito grande pode ser recusado com um 400.

Definir horas ativas #

PUT /agents/{agentId}/active-hours — as horas durante as quais o Agente responde automaticamente. Fora dessas janelas, permanece em silêncio.

Envie um objeto availability com chaves por dia da semana (monday a sunday). Cada dia aceita uma única janela temporal ou uma lista de janelas, no formato HH:MM de 24 horas. Os dias que omitir mantêm o que tinham, e qualquer chave que não seja um dia da semana é rejeitada — para que um erro de digitação não resulte silenciosamente em nada.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'

Resposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Uma chave de dia da semana incorreta devolve 400: "Invalid availability keys: funday. Allowed keys: monday through sunday."

Pausar ou retomar um Agente #

PATCH /agents/{agentId}/active — liga ou desliga o Agente. Um Agente em pausa mantém toda a sua configuração, mas deixa de responder imediatamente; a retoma tem efeito imediato.

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active", {
  method: "PATCH",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ active: false }),
});

Resposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "active": false }

active tem de ser um booleano real — qualquer outro valor devolve 400 com "active (boolean) is required".

Duplicar um Agente #

POST /agents/{agentId}/duplicate — cria uma cópia com a sua configuração preservada. A cópia não envia nada até que lhe aponte um canal ou um Ponto de Entrada.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/duplicate?apiKey=YOUR_API_KEY"

Resposta (201)

{ "success": true, "agent_id": "ag9WsX3cRfV6tGyH", "source_agent_id": "ag7HkQ2ZpLxR3mNb" }

Uma duplicação conta para o limite de Agentes do seu plano exatamente como a criação de um de raiz, pelo que é recusada com 403 quando a conta atinge o limite.

Eliminar um Agente #

DELETE /agents/{agentId}

A eliminação é recusada enquanto o Agente estiver ligado a algo que deixaria de funcionar sem ele — uma transmissão, um Ponto de Entrada ou (em contas mais antigas) uma campanha. A resposta lista o que o está a reter para que possa primeiro desligar esses elementos e tentar novamente.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY"

Resposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

Bloqueado (409)

{
  "success": false,
  "error": "Agent is still attached to one or more broadcast(s). Detach it first.",
  "blocking_campaign_ids": [],
  "blocking_broadcast_ids": ["bc5TgYhUj8IkOlPm"],
  "blocking_entry_point_ids": []
}

Rascunhos: reveja as alterações antes de serem publicadas #

As edições feitas no editor, e qualquer reescrita produzida por Otimizar com IA, são guardadas como um rascunho não publicado até que as publique. O Agente ativo continua a responder com a sua configuração atual até lá.

Publicar o rascunho #

POST /agents/{agentId}/publish-draft — move o rascunho para a configuração ativa e limpa o rascunho no mesmo passo.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/publish-draft?apiKey=YOUR_API_KEY"

Resposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "published_keys": ["instructions", "goal"] }

published_keys lista as definições que foram movidas do rascunho para o Agente ativo, para que possa mostrar o que mudou.

Verifique se existe um rascunho antes de efetuar esta chamada. Publicar um Agente que não tem rascunho não é uma chamada suportada e, atualmente, é devolvida como um 500 com uma mensagem genérica, não específica. Para descartar um rascunho, utilize a opção de descartar abaixo.

Eliminar o rascunho #

POST /agents/{agentId}/discard-draft — descarta o rascunho e deixa a configuração ativa exatamente como está. É seguro chamar quando não existe nenhum rascunho; nada acontece.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/discard-draft?apiKey=YOUR_API_KEY"

Otimizar um Agente com IA #

POST /agents/{agentId}/optimize — reescreve a configuração do Agente a partir do seu feedback (“continua a oferecer descontos”, “as respostas são demasiado longas”) e guarda a reescrita como um rascunho em vez de a colocar ativa.

Envie user_feedback (uma instrução simples) ou, ao reagir a uma resposta incorreta específica, thumbs_down_feedback juntamente com a thumbs_down_message ofensiva. Pelo menos um dos dois deve conter texto.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Keep replies under three sentences." }'

Resposta (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }

O trabalho é executado em segundo plano e a chamada retorna imediatamente. Leia o Agente com GET /agents/{agentId} e observe optimize_run.status; assim que voltar a Draft, a reescrita estará à espera como rascunho do Agente. Reveja-a e, em seguida, publique-a ou elimine-a.

Apenas uma execução de cada vez por Agente — uma segunda chamada enquanto uma está em curso retorna 409. Isto utiliza créditos de IA.

Regras de etiquetagem #

Uma regra de etiquetagem é uma etiqueta mais uma descrição de quando se aplica. Durante uma conversa, o Agente lê essa descrição e etiqueta o contacto quando esta se adequa, que é a forma como as automatizações baseadas em etiquetas são acionadas.

O objeto de regra

Adicionar uma regra de etiquetagem #

POST /agents/{agentId}/tags

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "hot-lead",
      "description": "Apply when the contact asks about pricing or wants to book a call.",
      "ai_can_remove": false
    }
  }'

Resposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "tag": { "name": "hot-lead", "...": "..." } }

Substituir uma regra de etiquetagem #

PUT /agents/{agentId}/tags/{tagId} — a regra é encontrada pelo ID da etiqueta no caminho e substituída na totalidade, não fundida, por isso envie a regra completa em vez de apenas a parte que está a alterar. A etiqueta para a qual aponta é preservada mesmo que omita tag_id, pelo que uma edição não pode desassociar a regra da sua etiqueta.

curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Apply only when the contact asks to book a call." } }'

Remover uma regra de etiquetagem #

DELETE /agents/{agentId}/tags/{tagId} — o Agente deixa de aplicar essa etiqueta. A etiqueta em si, e quaisquer contactos que já a possuam, permanecem inalterados.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY"

Ambos os endpoints devolvem 404 quando o Agente não existe ou quando não tem nenhuma regra para essa etiqueta.

Gerar um conjunto de etiquetas com IA #

POST /agents/{agentId}/tags/generate — concebe um conjunto completo de regras (os nomes das etiquetas e a formulação “aplicar quando…” por trás de cada uma) ao ler as instruções e o objetivo do próprio Agente.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/generate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "merge" }'

Resposta (202)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mode": "merge" }

O trabalho é executado em segundo plano. Leia o Agente e observe tag_generation.status; as regras em si são colocadas no tags do Agente. Apenas uma execução de cada vez por Agente (409 caso contrário), e utiliza créditos de IA.

Fontes de conhecimento #

As fontes de conhecimento são as páginas e documentos que a plataforma leu para si. Anexar uma a um Agente permite-lhe responder a partir desse conteúdo.

De onde vêm os IDs das fontes. Adicione conteúdo com os endpoints da base de conhecimento — POST /kb-sources/url para uma página, POST /kb-sources/file para um documento, POST /kb-sources/bulk-import para um site inteiro. Estes devolvem um source_id que consulta com GET /kb-sources/{sourceId} até estar pronto. POST /kb-sources/url também aceita autoLinkToAgentId, que anexa a fonte a um Agente assim que a importação termina, para que possa ignorar a chamada de anexação abaixo.

Anexar fontes de conhecimento #

POST /agents/{agentId}/kb-sources — envie kb_source_ids com uma lista para anexar um conjunto completo numa única chamada (o que pretende após rastrear um site), ou kb_source_id para uma única fonte. Envie uma ou outra. Anexar algo que já está anexado não altera nada.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"] }'

Resposta (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "kb_source_id": "kb2QwErTyUi9OpAs",
  "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"]
}

Desanexar fontes de conhecimento #

DELETE /agents/{agentId}/kb-sources/{kbSourceId} para um, ou POST /agents/{agentId}/kb-sources/bulk-remove com kb_source_ids para vários. A remoção em massa é um POST porque a lista de IDs é enviada no corpo do pedido.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources/bulk-remove?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs"] }'

As fontes em si não são eliminadas e permanecem disponíveis para os seus outros Agentes. Desanexar algo que não está anexado não altera nada.

Perguntas Frequentes (FAQs) #

As FAQs são geridas nos seus próprios endpoints e ligadas a um Agente a partir daí: POST /faqs/{faqId}/link com { "agent_id": "ag7HkQ2ZpLxR3mNb" }, e POST /faqs/{faqId}/unlink para a remover novamente. Uma FAQ pode ser partilhada por qualquer número de Agentes. Consulte a API de FAQs.

Uma FAQ só é utilizada pelos Agentes aos quais está ligada — criá-la não é suficiente por si só.

Ferramentas #

Funções personalizadas #

POST /agents/{agentId}/custom-functions permite que o Agente chame uma das suas funções personalizadas durante as conversas. Apenas funções pertencentes à mesma conta podem ser anexadas, e anexar uma que já esteja anexada não altera nada.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "cf7Hk2ZpLxR3mNbV" }'

DELETE /agents/{agentId}/custom-functions/{customFunctionId} desanexa-a. A função em si não é eliminada e permanece disponível para os seus outros Agentes.

Faça a gestão das funções em /custom-functions — consulte Funções Personalizadas para saber o que são.

Servidores MCP #

Um servidor MCP é um conjunto pronto a usar de ferramentas que o seu Agente pode descobrir e chamar autonomamente — consulte Ligar Servidores MCP ao seu Bot. Os servidores são registados uma vez na conta e, em seguida, anexados aos Agentes que os devem utilizar.

Os servidores MCP requerem a funcionalidade de funções personalizadas no seu plano. Sem ela, os endpoints /mcp-servers ao nível da conta devolvem 403. Anexar um servidor já registado a um Agente não está restringido.

Registar um servidor #

POST /mcp-servers

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://tools.example.com/mcp",
    "auth_header_value": "Bearer sk_live_xxx"
  }'

Resposta (201)

{
  "success": true,
  "server_id": "ms4TgBnH7yUj2kLp",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }],
  "last_error": null,
  "server": { "server_id": "ms4TgBnH7yUj2kLp", "name": "Inventory", "...": "..." }
}

Ao guardar, a plataforma liga-se ao servidor e coloca em cache a lista de ferramentas que este oferece. Um servidor que não pode ser alcançado é guardado na mesma, com o motivo em last_error e uma lista de ferramentas vazia — para que possa registar primeiro e corrigir a conectividade depois.

Um auth_type de oauth2 guarda o registo com oauth_connected: false e sem ferramentas: ainda não existe nenhum token. A autorização de um servidor OAuth requer um início de sessão no navegador e é feita a partir do painel de controlo, não através da API.

Listar, atualizar e eliminar servidores #

• GET /mcp-servers — todos os servidores registados, do mais recente para o mais antigo, em servers.
• PUT /mcp-servers/{serverId} — envie apenas o que pretende alterar. Alterar o URL ou os campos de autenticação testa novamente a ligação e atualiza a lista de ferramentas em cache.
• DELETE /mcp-servers/{serverId} — remove o registo e desassocia-o de todos os Agentes e campanhas que o tinham ativado.

curl "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY"

Os segredos nunca são devolvidos. As respostas transportam auth_header_value_set (um sinalizador true/false que indica que um valor está armazenado) em vez da credencial, e os tokens OAuth e segredos de cliente permanecem no lado do servidor. Tudo o resto é devolvido: name, url, enabled, auth_type, auth_header_name, tools, enabled_tools, tool_policies, oauth_connected, tools_cached_at, last_connected_at, last_error, created_at, updated_at.

Testar uma ligação #

POST /mcp-servers/test-connection — liga-se a um servidor e lista as suas ferramentas. Duas formas de a chamar:

• com server_id — testa a configuração guardada e atualiza a sua lista de ferramentas em cache;
• com um url em linha (mais auth_header_name / auth_header_value) — um teste pré-gravação que não armazena nada.

curl -X POST "https://api.youraiconnector.com/v1/mcp-servers/test-connection?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tools.example.com/mcp", "auth_header_value": "Bearer sk_live_xxx" }'

Resposta (200)

{
  "success": true,
  "server_name": "Inventory tools",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }]
}

Uma falha de ligação não é um erro HTTP — obtém um 200 com success: false e um error que descreve o que correu mal, para que o possa mostrar junto ao campo que o operador está a editar.

Associar um servidor a um Agente #

Registar um servidor não dá a nenhum Agente acesso ao mesmo. Associe-o:

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "ms4TgBnH7yUj2kLp" }'

Resposta (200)

{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mcp_server_id": "ms4TgBnH7yUj2kLp" }

DELETE /agents/{agentId}/mcp-servers/{mcpServerId} desassocia-o novamente. O servidor em si não é eliminado e permanece disponível para os seus outros Agentes. Associar ou desassociar algo que já se encontra nesse estado não altera nada.

Biblioteca de multimédia #

A biblioteca de multimédia contém os ficheiros que um Agente pode enviar durante uma conversa — um menu, uma lista de preços, uma fotografia de produto. Um Agente pode ter no máximo 50 itens.

Listar multimédia #

GET /agents/{agentId}/media-library

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY"

Resposta (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "media_items": [
    {
      "id": "mi4RtY7uIoP1aSdF",
      "item_id": "mi4RtY7uIoP1aSdF",
      "media_home": "agent",
      "title": "Spring menu",
      "description": "Send when someone asks what is on the menu.",
      "ai_description": "A one-page menu listing seasonal dishes and prices.",
      "type": "document",
      "media_content_type": "application/pdf",
      "media_url": "https://storage.googleapis.com/...",
      "max_sends_per_conversation": 1,
      "created_at": 1700000000000
    }
  ]
}

Os itens armazenados no Agente aparecem primeiro, seguidos de quaisquer itens mais antigos ainda armazenados na campanha a partir da qual o Agente foi criado; media_home (agent ou campaign) indica qual é qual. Dentro de cada grupo, o mais recente aparece primeiro.

media_url expira após 7 dias. É a ligação de transferência criada quando o ficheiro foi carregado — trate uma ligação antiga como obsoleta em vez de danificada e volte a ler a lista para obter uma ligação atualizada.

Carregar multimédia #

POST /agents/{agentId}/media-library — o ficheiro é carregado inline como base64, até 10 MB. A chamada termina assim que o ficheiro é armazenado, por isso, aguarde um pouco mais do que num pedido normal. Note que este corpo utiliza nomes de campos em camelCase.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "JVBERi0xLjQKJcfs...",
    "mimeType": "application/pdf",
    "fileName": "spring-menu.pdf",
    "title": "Spring menu",
    "description": "Send when someone asks what is on the menu.",
    "maxSendsPerConversation": 1
  }'

Duas coisas acontecem automaticamente: um GIF animado é convertido em vídeo para que seja reproduzido em todos os canais, e a plataforma escreve um breve resumo do que está realmente no ficheiro para que o Agente saiba quando este é adequado.

Um 400 cobre campos em falta, um tipo de ficheiro não suportado, um ficheiro vazio ou demasiado grande, e atingir o limite de 50 itens. Um 403 significa que a biblioteca de multimédia está desativada para a conta.

Atualizar um item de multimédia #

PATCH /agents/{agentId}/media-library/{itemId} — apenas metadados. O ficheiro em si não pode ser substituído; carregue um novo item e elimine o antigo. Este corpo utiliza snake_case: title, description, send_message, max_sends_per_conversation (um número inteiro não negativo, ou null para limpar o limite).

curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Summer menu", "max_sends_per_conversation": 2 }'

Resposta (200)

{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "item_id": "mi4RtY7uIoP1aSdF",
  "campaign_id": "",
  "media_home": "agent"
}

Eliminar um item de multimédia #

DELETE /agents/{agentId}/media-library/{itemId} — remove o item e o seu ficheiro armazenado. Eliminar um item que já não existe é bem-sucedido e reporta deleted: false, pelo que a chamada é segura para repetir.

curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY"

Gerar mensagens de seguimento #

POST /agents/{agentId}/template-generation — escreve as mensagens de seguimento do Agente por si (os lembretes que este envia quando uma conversa fica inativa), com base na finalidade do Agente.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

Existem duas formas de isto ser devolvido, e o campo target indica-lhe qual:

• target: "agent" com um 200 — as mensagens foram escritas durante a chamada e o resultado encontra-se em data. Leia-as a partir do follow_up_config do Agente. Este é o caso habitual.
• target: "campaign" com um 202 — o trabalho foi colocado na fila de espera da campanha nomeada em campaign_id. Monitorize o template_generation_status dessa campanha até que termine.

O cold_only necessita de uma campanha de saída e é recusado com 409 (reason: "cold_only_requires_campaign") num Agente que não tenha nenhuma. Um 403 significa que os seguimentos automáticos não estão ligados para a conta. Isto utiliza créditos de IA, e um 400 com "Insufficient credits." significa que a conta não tem saldo.

Encaminhar conversas para um Agente #

Um Agente apenas responde às conversas que um Ponto de Entrada lhe envia. Até que um canal tenha um, uma primeira mensagem de alguém com quem nunca falou continua a ser guardada, mas nada a recolhe e nenhum assistente responde.

Listar os Pontos de Entrada de um Agente #

GET /agents/{agentId}/entry-points — as regras de encaminhamento que enviam conversas para este Agente, da mais recente para a mais antiga. São devolvidas tanto as regras atuais como as retiradas; uma regra retirada tem enabled: false.

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"

Para as predefinições de canal de toda a conta, incluindo um canal deliberadamente definido para ninguém, leia GET /entry-points/channel-defaults em vez disso.

Criar um Ponto de Entrada #

POST /agents/{agentId}/entry-points — o Agente no caminho ganha sempre, pelo que nunca pode ser criada uma regra para um Agente diferente daquele que consta no URL.

channels é obrigatório e indica quais os canais que a regra abrange — por exemplo whatsapp, whatsapp_web, instagram, messenger, telegram, sms, email, chat_widget ou custom_channel. As novas regras são ativadas, a menos que indique o contrário.

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'

Resposta (201)

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Que regra ganha quando várias podem ser aplicadas: uma conversa em curso ou uma atribuição manual mantém o Agente que já tem; caso contrário, as regras de palavra-chave superam as regras de comentário, que superam as regras de seguidor, e uma predefinição de canal é o último recurso. Se estas regras decidem algo numa conta é algo reportado por GET /entry-points/routing-status.

Esta é a versão curta. O guia da Entry Points API cobre todas as regras de ladder, comentários e seguidores, um Agente por número de WhatsApp, e a alteração ou eliminação de uma regra. Consulte Entry Points para o conceito, e a Channels API para ligar o próprio canal.

Erros da API de Agentes de IA #

Os endpoints de Agente devolvem o envelope de erro padrão:

{
  "success": false,
  "error": "Agent not found"
}

Os códigos partilhados que qualquer endpoint pode devolver — 401, 403 (o seu plano não inclui acesso à API), 429 (limite de taxa) e 500 — estão listados com orientações de repetição em Erros e Paginação.

Uma nota sobre o explorador. Os endpoints /agents estão na especificação OpenAPI publicada, pelo que pode consultar os seus campos exatos e executar pedidos em tempo real na Referência da API. Os endpoints /mcp-servers ao nível da conta também estão na especificação, pelo que também os pode explorar aí.

Relacionado #

• Agentes de IA — o que é um Agente, em linguagem simples.
• Pontos de Entrada — como as conversas são encaminhadas para um Agente.
• API de FAQs — crie e ligue o conhecimento a partir do qual o seu Agente responde.
• API de Canais — ligue os canais nos quais um Agente responde.
• Ligar Servidores MCP ao Seu Bot · Funções Personalizadas
• Referência da API — o explorador de endpoints interativo completo.