Jak zbudować agenta AI na swojej stronie - Poradnik

// zanim zaczniesz

Co będziemy budować?

Agent AI to inteligentny czat na Twojej stronie, który rozmawia z klientami, odpowiada na pytania o Twoje usługi, zbiera kontakty i pracuje 24/7. To nie jest chatbot ze skryptem, to sztuczna inteligencja, która rozumie kontekst i prowadzi naturalną rozmowę.

Żeby go zbudować, potrzebujesz trzech rzeczy:

System prompt - instrukcja, która mówi AI kim jest i co ma robić
Backend - serwer, który łączy Twoją stronę z API sztucznej inteligencji
Widget - okienko czatu na Twojej stronie (frontend)

Brzmi skomplikowanie? Spokojnie, rozłożymy to na kawałki.

⚠️ Potrzebujesz podstawowej wiedzy o HTML/JS i umiejętności obsługi terminala. Jeśli nie wiesz co to npm albo API, ten poradnik może być za trudny, ale spokojnie, czytaj dalej, przynajmniej zrozumiesz jak to działa.

Krok 1

Konto i klucz API

⏱ ~10 minut

Najpierw potrzebujesz dostęp do API sztucznej inteligencji. Najpopularniejsze opcje to Claude (Anthropic) i GPT (OpenAI). W tym poradniku używamy Claude, ale zasada jest ta sama.

Co robisz:

Wejdź na console.anthropic.com i załóż konto
Przejdź do sekcji API Keys
Kliknij Create Key i skopiuj klucz (zaczyna się od sk-ant-...)
Doładuj konto, minimum $5 na start

⚠️ NIGDY nie wklejaj klucza API bezpośrednio w kodzie frontendowym. Każdy mógłby go podejrzeć i użyć na Twój koszt. Klucz trzymasz tylko na backendzie.

💡 Koszt API przy małym ruchu to zazwyczaj 20-100 zł miesięcznie. Jedna rozmowa to kilka groszy.

Krok 2

System prompt, czyli "mózg" agenta

⏱ 2-4 godziny

To najważniejszy element. System prompt to tekstowa instrukcja, która mówi AI:

Kim jest (asystent firmy XYZ)
Jak ma się zachowywać (ton, styl komunikacji)
Co wie o firmie (usługi, cennik, godziny, lokalizacja)
Jakie są zasady (nie obiecuj terminów, kieruj do kontaktu)
Jak reagować na konkretne pytania

Oto szkielet, od którego możesz zacząć:

system-prompt.txt

Jesteś asystentem firmy [NAZWA FIRMY] - [KRÓTKI OPIS].

## Styl komunikacji
Mówisz [JAKI TON - formalnie/luźno/profesjonalnie].
Odpowiadaj krótko, 2-4 zdania, chyba że pytanie wymaga 
dłuższej odpowiedzi.

## Oferta firmy
[Tu wpisujesz swoje usługi, produkty, cennik]

### Usługa 1 - [nazwa]
- Co obejmuje
- Ile kosztuje
- Ile trwa

### Usługa 2 - [nazwa]
- Co obejmuje
- Ile kosztuje
- Ile trwa

## Dane kontaktowe
- Telefon: [NUMER]
- Email: [EMAIL]
- Adres: [ADRES]
- Godziny: [GODZINY]

## Twoje zadania
1. Odpowiadaj na pytania o ofertę
2. Zbieraj informacje (branża, potrzeby, budżet)
3. Kieruj do kontaktu telefonicznego/mailowego

## Zasady
- NIGDY nie udawaj, że jesteś człowiekiem
- Nie obiecuj konkretnych terminów
- Bądź uczciwy z cenami
- Jeśli nie wiesz, powiedz "skontaktuj się z nami"

💡 Im lepiej opiszesz swoją firmę i zasady, tym lepiej agent będzie działał. Poświęć na to czas, to się zwróci.

Krok 3

Backend (serwer API)

⏱ 1-2 godziny

Backend to pośrednik między widgetem na stronie a API Claude'a. Dlaczego nie łączymy się bezpośrednio? Bo klucz API musi być ukryty na serwerze.

Opcja A: Node.js + Vercel (darmowy hosting)

Najprostsza opcja. Potrzebujesz: konto GitHub + konto Vercel (oba darmowe).

api/chat.js

const Anthropic = require("@anthropic-ai/sdk");
const client = new Anthropic({ 
  apiKey: process.env.ANTHROPIC_API_KEY 
});

const SYSTEM_PROMPT = `[Tu wklejasz swój system prompt]`;

module.exports = async function handler(req, res) {
  // Zezwól na zapytania z Twojej domeny
  res.setHeader("Access-Control-Allow-Origin", 
    "https://twoja-domena.pl");
  res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
  res.setHeader("Access-Control-Allow-Headers", "Content-Type");

  if (req.method === "OPTIONS") return res.status(200).end();
  if (req.method !== "POST") 
    return res.status(405).json({ error: "Method not allowed" });

  try {
    const { messages } = req.body;

    // Ogranicz historię do 20 ostatnich wiadomości
    const trimmed = messages.slice(-20).map(m => ({
      role: m.role === "assistant" ? "assistant" : "user",
      content: String(m.content).slice(0, 1000),
    }));

    const response = await client.messages.create({
      model: "claude-sonnet-4-20250514",
      max_tokens: 500,
      system: SYSTEM_PROMPT,
      messages: trimmed,
    });

    const text = response.content
      .filter(b => b.type === "text")
      .map(b => b.text)
      .join("\n");

    return res.status(200).json({ reply: text });
  } catch (error) {
    console.error("API error:", error.message);
    return res.status(500).json({ 
      error: "Coś poszło nie tak. Spróbuj ponownie." 
    });
  }
};

package.json

{
  "name": "chat-api",
  "dependencies": {
    "@anthropic-ai/sdk": "^0.39.0"
  }
}

vercel.json

{
  "functions": {
    "api/chat.js": { "maxDuration": 30 }
  }
}

Wdrożenie na Vercel:

Utwórz repo na GitHubie z tymi trzema plikami
Wejdź na vercel.com i połącz repo
W Settings → Environment Variables dodaj ANTHROPIC_API_KEY z Twoim kluczem
Deploy! Twój backend będzie na nazwa-projektu.vercel.app

Opcja B: PHP (dla hostingów współdzielonych)

Jeśli masz zwykły hosting PHP (np. Cyberfolks, home.pl), możesz użyć PHP zamiast Node.js:

chat.php

<?php
header('Content-Type: application/json');
header('Access-Control-Allow-Origin: https://twoja-domena.pl');
header('Access-Control-Allow-Methods: POST, OPTIONS');
header('Access-Control-Allow-Headers: Content-Type');

if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') { 
  http_response_code(200); exit; 
}

$input = json_decode(file_get_contents('php://input'), true);
$messages = array_slice($input['messages'] ?? [], -20);

$SYSTEM_PROMPT = "[Tu wklejasz swój system prompt]";
$API_KEY = "[TWÓJ KLUCZ API]"; // Lepiej trzymać w .env

$data = [
  'model' => 'claude-sonnet-4-20250514',
  'max_tokens' => 500,
  'system' => $SYSTEM_PROMPT,
  'messages' => array_map(function($m) {
    return [
      'role' => $m['role'] === 'assistant' 
        ? 'assistant' : 'user',
      'content' => mb_substr($m['content'], 0, 1000)
    ];
  }, $messages)
];

$ch = curl_init('https://api.anthropic.com/v1/messages');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_POSTFIELDS => json_encode($data),
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Content-Type: application/json',
    'x-api-key: ' . $API_KEY,
    'anthropic-version: 2023-06-01'
  ]
]);

$response = curl_exec($ch);
$result = json_decode($response, true);
curl_close($ch);

$text = '';
foreach ($result['content'] ?? [] as $block) {
  if ($block['type'] === 'text') $text .= $block['text'];
}

echo json_encode(['reply' => $text]);
?>

⚠️ W wersji PHP trzymaj klucz API w pliku .env lub w konfiguracji serwera, nie bezpośrednio w kodzie PHP.

Krok 4

Widget czatowy (frontend)

⏱ 2-4 godziny

Widget to okienko czatu, które widzą odwiedzający Twoją stronę. To jeden plik JavaScript, który wklejasz na stronę.

Widget musi obsługiwać:

Przycisk otwierający czat (zazwyczaj prawy dolny róg)
Okno rozmowy z historią wiadomości
Pole do wpisywania wiadomości
Wysyłanie zapytań do Twojego backendu
Wyświetlanie odpowiedzi
Wskaźnik "pisze..." podczas oczekiwania
Responsywność na mobile (to najtrudniejsza część!)

Oto minimalny szkielet widgetu:

chat-widget.js

// Konfiguracja
const API_URL = 'https://twoj-backend.vercel.app/api/chat';

// Tworzenie elementów HTML
const chatContainer = document.createElement('div');
chatContainer.id = 'ai-chat-widget';
chatContainer.innerHTML = `
  <button id="chat-toggle" 
    style="position:fixed; bottom:20px; right:20px; 
    width:60px; height:60px; border-radius:50%; 
    background:#00e5a0; border:none; cursor:pointer; 
    font-size:24px; z-index:9999;">💬</button>
  <div id="chat-window" style="display:none; 
    position:fixed; bottom:90px; right:20px; 
    width:380px; height:500px; background:#12121a; 
    border:1px solid #2a2a3a; border-radius:16px; 
    z-index:9999; display:flex; 
    flex-direction:column; overflow:hidden;">
    <div id="chat-messages" style="flex:1; 
      overflow-y:auto; padding:16px;"></div>
    <div style="padding:12px; 
      border-top:1px solid #2a2a3a;">
      <input id="chat-input" type="text" 
        placeholder="Napisz wiadomość..." 
        style="width:100%; padding:10px; 
        background:#0a0a0f; border:1px solid #2a2a3a; 
        border-radius:8px; color:#e8e8ef; 
        outline:none;">
    </div>
  </div>`;
document.body.appendChild(chatContainer);

// Logika
let messages = [];
const toggle = document.getElementById('chat-toggle');
const window_ = document.getElementById('chat-window');
const input = document.getElementById('chat-input');
const msgBox = document.getElementById('chat-messages');

toggle.onclick = () => {
  const open = window_.style.display !== 'none';
  window_.style.display = open ? 'none' : 'flex';
};

input.addEventListener('keypress', async (e) => {
  if (e.key !== 'Enter' || !input.value.trim()) return;

  const text = input.value.trim();
  input.value = '';

  // Dodaj wiadomość użytkownika
  messages.push({ role: 'user', content: text });
  addMessage('user', text);

  // Pokaż "pisze..."
  const typing = addMessage('assistant', '...');

  try {
    const res = await fetch(API_URL, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ messages })
    });
    const data = await res.json();

    typing.remove();
    messages.push({ 
      role: 'assistant', content: data.reply 
    });
    addMessage('assistant', data.reply);
  } catch {
    typing.textContent = 'Błąd połączenia.';
  }
});

function addMessage(role, text) {
  const div = document.createElement('div');
  div.style.cssText = `margin:8px 0; padding:10px 14px; 
    border-radius:12px; font-size:14px; max-width:85%; 
    ${role === 'user' 
      ? 'background:#00e5a0; color:#0a0a0f; margin-left:auto;' 
      : 'background:#1a1a26; color:#e8e8ef;'}`;
  div.textContent = text;
  msgBox.appendChild(div);
  msgBox.scrollTop = msgBox.scrollHeight;
  return div;
}

Potem wystarczy dodać na swojej stronie:

⚠️ To jest minimalny szkielet. Brakuje tu: obsługi mobile (klawiatura wirtualna!), animacji, lepszego designu, obsługi błędów, rate limitingu, wiadomości powitalnej. Produkcyjny widget to 300-500 linii kodu.

Krok 5

Testowanie i poprawki

⏱ 1-2 godziny (minimum)

Masz działającego agenta? Super. Teraz zaczyna się prawdziwa robota:

Testuj system prompt - zadawaj pytania jak klient. Czy odpowiedzi mają sens? Czy ton jest odpowiedni? Czy nie podaje błędnych informacji?
Testuj na mobile - otwórz na telefonie. Czy klawiatura nie zasłania czatu? Czy da się wygodnie pisać? (To jest najtrudniejszy bug do naprawienia)
Testuj edge cases - co jak klient pisze bzdury? Co jak pyta o coś poza ofertą? Co jak jest niegrzeczny?
Poprawiaj prompt - na podstawie testów, dodawaj nowe zasady i scenariusze. To proces iteracyjny.

💡 System prompt to żywy dokument. Będziesz go poprawiał tygodniami po wdrożeniu, w miarę jak będziesz widział jak klienci rozmawiają z agentem.

Krok 6

Bezpieczeństwo

⏱ 1 godzina

Zanim puścisz agenta na produkcję, zadbaj o kilka rzeczy:

Rate limiting - ogranicz liczbę wiadomości per IP (np. 30/godzinę), żeby ktoś nie nabił Ci rachunku za API
CORS - zezwól na zapytania tylko z Twojej domeny
Walidacja inputu - ogranicz długość wiadomości (np. 1000 znaków)
Limit historii - wysyłaj do API tylko ostatnie 20 wiadomości, nie całą rozmowę
Klucz API - trzymaj go w zmiennych środowiskowych, nie w kodzie

// podsumowanie

Ile to zajmuje czasu?

Jeśli masz doświadczenie z programowaniem:

Konto API: 10 minut
System prompt: 2-4 godziny
Backend: 1-2 godziny
Widget: 2-4 godziny
Testy: 1-2 godziny
Bezpieczeństwo: 1 godzina

Razem: 7-14 godzin roboczych na podstawową wersję. Produkcyjna wersja z porządnym designem, obsługą mobile, animacjami i dobrze dopracowanym promptem to łatwo 20+ godzin.

Jeśli nie masz doświadczenia z programowaniem, pomnóż razy 3. Albo razy 5. Albo po prostu daj znać Wojciechowi 😉

Jak zbudować agenta AIna swojej stronie