Własny agent to zewnętrzny agent AI, którego posiadasz i hostujesz. Po połączeniu otrzymuje własną tożsamość w monday.com. Można go oznaczać za pomocą @ w aktualizacjach lub przypisywać do elementów. Agent działa na tablicach za pośrednictwem API monday.com.

Gdy agent zostanie wywołany, monday.com wysyła podpisane żądanie HTTP POST na podany przez Ciebie adres URL wywołania zwrotnego. Potwierdź otrzymanie żądania w ciągu 30 sekund. W przypadku czatu z agentem wyślij widoczną odpowiedź później za pomocą send_custom_agent_message, używając wartości payload.conversationId z webhooka. Twoja usługa może też działać niezależnie w monday.com, korzystając z tokena API wydanego podczas łączenia agenta.

📘 Mutacje GraphQL wymienione w tym artykule (connect_external_agent_sync, update_custom_agent, send_custom_agent_message, disconnect_external_agent, add_agent_resource_access) są szczegółowo opisane w dokumentacji referencyjnej Agents API.

---

Krok 1. Utwórz agenta

W interfejsie: przejdź do Agenci (Agents) → Zarządzaj agentami (Manage agents) → Dodaj własnego agenta (Bring your agent), wybierz Własny agent (Custom agent), wpisz nazwę i opcjonalnie podaj Adres URL wywołania zwrotnego (Callback URL). W oknie potwierdzenia skopiuj Token API (API Token) i Tajny klucz podpisu (Signing Secret) - są wyświetlane tylko raz.

Za pomocą API: wywołaj connect_external_agent_sync. Mutacja zwraca agent_id, signing_secret i api_token.

---

Krok 2. Odbierz webhook wywołujący agenta

Gdy agent zostanie wywołany, monday.com wysyła podpisane żądanie POST na podany przez Ciebie adres URL wywołania zwrotnego.

Treść żądania:

{
  "event": "agent_triggered",
  "triggerType": "chat",
  "payload": {
    "text": "<trigger text>",
    "conversationId": "v1.example-conversation-token"
  },
  "timestamp": "2026-06-15T10:30:00Z"
}

Pole	Wartości	Opis
event	agent_triggered	W webhookach własnych agentów zawsze ma wartość agent_triggered.
triggerType	chat, mention, assigned, unknown	Sposób wywołania agenta. Mogą pojawić się aliasy, takie jak assign - ujednolić je.
payload.text	ciąg znaków	Tekst, który wywołał agenta.
payload.conversationId	ciąg znaków	Dotyczy tylko czatu. Nieprzezroczysty identyfikator konwersacji. Przekaż go bez zmian jako conversation_id do send_custom_agent_message.
timestamp	ciąg znaków ISO 8601	Czas wystąpienia zdarzenia.

Nagłówki żądania:

Nagłówek	Opis
x-monday-signature	sha256=<hex> - podpis żądania HMAC-SHA256.
x-monday-timestamp	Czas wysłania żądania przez monday.com w milisekundach od epoki Unix.
x-monday-agent-id	Identyfikator agenta, który wywołał zdarzenie.
content-type	application/json

---

Krok 3. Odpowiedz na webhook

monday.com wysyła żądanie POST z informacją o wywołaniu na podany przez Ciebie adres URL i czeka do 30 sekund na odpowiedź HTTP 200. Treść odpowiedzi może mieć maksymalnie 1 MB. W przypadku czatu z agentem odpowiedź HTTP służy tylko do potwierdzenia otrzymania żądania. Wiadomość widoczną dla użytkownika wyślij później za pomocą send_custom_agent_message.

Odpowiedz na czacie

1. Odczytaj payload.conversationId z webhooka. To nieprzezroczysty ciąg znaków - przekaż go bez zmian.
2. Zwróć odpowiedź HTTP 200, zanim rozpoczniesz dłużej trwające operacje. Jeśli pominięto stream lub ma wartość true, zwróć pusty strumień SSE zakończony przez data: [DONE]. Jeśli stream ma wartość false, zwróć { "success": true }.
3. Wywołaj send_custom_agent_message za pomocą wartości api_token agenta. Ustaw conversation_id na payload.conversationId.

Możesz używać tej samej wartości conversation_id w dowolnej liczbie wiadomości przez maksymalnie 7 dni. Zmiana adresu URL wywołania zwrotnego lub ponowne połączenie agenta unieważni tę wartość.

mutation ($input: SendCustomAgentMessageInput!) {
  send_custom_agent_message(input: $input) {
    delivered
    message_id
  }
}

{
  "input": {
    "conversation_id": "v1.example-conversation-token",
    "message": "The project is 62% complete - 3 tasks remain in the backlog."
  }
}

await mondayApi(agentApiToken, `
  mutation ($input: SendCustomAgentMessageInput!) {
    send_custom_agent_message(input: $input) {
      delivered
      message_id
    }
  }`, {
  input: {
    conversation_id: payload.conversationId,
    message: replyText,
  },
});

Wartość delivered jest równa true, gdy interfejs czatu otrzyma wiadomość. message_id to identyfikator tej wiadomości.

Możesz też umieścić całą odpowiedź na czacie w treści HTTP. Zwróć JSON { "success": true, "message": "Your reply text" } albo strumieniuj wiersze SSE data: {"type":"text","content":"..."}, a na końcu dodaj data: [DONE]. Użyj tej metody tylko wtedy, gdy odpowiedź będzie gotowa w ciągu 30 sekund. W przypadku wywołań przez oznaczenie lub przypisanie treść HTTP nie jest wyświetlana - potwierdź otrzymanie żądania, a następnie wyślij wiadomość za pomocą tokena agenta (zobacz Krok 5).

---

Krok 4. Zweryfikuj podpis webhooka

Przed przetworzeniem zweryfikuj każdy przychodzący webhook. Użyj porównania o stałym czasie wykonania, aby zapobiec atakom czasowym.

1. Odczytaj x-monday-signature i x-monday-timestamp z nagłówków żądania.
2. Oblicz HMAC-SHA256(signing_secret, "{x-monday-timestamp}.{raw_body}").
3. Dodaj przed wynikiem prefiks sha256= i porównaj go z x-monday-signature, używając porównania o stałym czasie wykonania.
4. Odrzuć żądania, jeśli podpisy się nie zgadzają lub znacznik czasu jest nieaktualny.

const crypto = require('crypto');

function verifySignature(signingSecret, rawBody, headers) {
  const timestamp = headers['x-monday-timestamp'];
  const receivedSig = headers['x-monday-signature'];

  if (!timestamp || !receivedSig) return false;

  const expected = 'sha256=' + crypto
    .createHmac('sha256', signingSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');

  // timingSafeEqual throws if the buffers differ in length, so guard first.
  const expectedBuf = Buffer.from(expected);
  const receivedBuf = Buffer.from(receivedSig);
  return (
    expectedBuf.length === receivedBuf.length &&
    crypto.timingSafeEqual(expectedBuf, receivedBuf)
  );
}

---

Krok 5. Wykonuj działania w monday.com

Połączone agenty działają pod własną tożsamością monday.com - uprawnienia dostępu Twojego konta nie są przenoszone na agenta. Przyznaj agentowi dostęp do potrzebnych tablic lub dokumentów (strona agenta → Wiedza i dostęp (Knowledge and access) albo mutacja add_agent_resource_access), a następnie wywołaj API za pomocą wartości api_token agenta:

curl -X POST https://api.monday.com/v2 \
  -H "Authorization: <agent-api-token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ me { id name } }"}'

Wartość api_token jest ważna przez długi czas - nie wygasa automatycznie i zostaje unieważniona dopiero po rozłączeniu agenta. Używaj jej do operacji trwających dłużej niż 30-sekundowe okno webhooka, w tym do wysyłania odpowiedzi na czacie za pomocą send_custom_agent_message.

---

Zarządzanie agentem

• Zaktualizuj nazwę lub adres URL wywołania zwrotnego - update_custom_agent (token właściciela z agent_id albo własny api_token agenta bez agent_id). Zmiana wartości callback_url powoduje wygenerowanie nowej wartości signing_secret - zapisz ją.
• Rozłącz agenta - disconnect_external_agent. Spowoduje to unieważnienie tokena agenta i usunięcie agenta.

---

Rozwiązywanie problemów

Agent twierdzi, że ma dostęp, ale nie może edytować elementów.
Agent działa pod własną tożsamością. Przyznaj mu dostęp READ_WRITE do odpowiedniej tablicy (zobacz Krok 5) - uprawnienia dostępu Twojego konta do tablicy nie mają wpływu na agenta.

Weryfikacja podpisu webhooka nie działa.
Oblicz HMAC-SHA256 dla "{x-monday-timestamp}.{raw_body}", używając signing_secret (nie tokena API), i użyj nieprzetworzonej treści żądania.

Przekroczono limit czasu webhooka.
Potwierdź otrzymanie webhooka w ciągu 30 sekund. Aby wysłać później odpowiedź na czacie, wywołaj send_custom_agent_message i użyj wartości payload.conversationId z webhooka.

Dane poufne zostały utracone po konfiguracji.
Wartości signing_secret i api_token są wyświetlane tylko raz. Jeśli je utracisz, rozłącz agenta i połącz go ponownie, aby wygenerować nowe dane uwierzytelniające.

---

📘 Dołącz do naszej społeczności deweloperów!

Jeśli masz pytania lub potrzebujesz pomocy dotyczącej własnych agentów, odwiedź społeczność deweloperów monday.com.