> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Procedury w dowolnej formie

## Przegląd

Procedura w dowolnej formie opisuje jedno zadanie prostym, naturalnym językiem. Agent interpretuje instrukcje i dostosowuje sformułowania oraz kolejność do sytuacji. Taka procedura może wywoływać narzędzia (w tym narzędzia systemowe, jak zakończenie rozmowy), wyszukiwać dokumenty w bazie wiedzy i łączyć się z innymi procedurami.

## Kiedy używać procedury w dowolnej formie

Użyj takiej procedury, gdy agent może dostosować sformułowania i kolejność do sytuacji, a ty chcesz szybko napisać ją prostym językiem. Porównanie z procedurami strukturalnymi, workflow i promptem systemowym znajdziesz w sekcji [Kiedy używać procedur](/docs/pl/eleven-agents/customization/procedures#when-to-use-procedures).

## Budowa procedury

Oto procedura zwrotu środków w edytorze:

![Przykład procedury
zwrotu środków](/docs/_fern-img/e1264b7a4f94403453087d30ef0894e72d412ba69378e6b8cb1b675e53e887b7.webp)

Procedura ma dwie główne części: wyzwalacz i treść. Obie mogą zawierać odwołania inline do innych zasobów, pokazane na zrzucie ekranu powyżej jako tagi z ikonami klucza. Każda procedura ma też nazwę widoczną w panelu.

### Nazwa

Krótka etykieta identyfikująca procedurę w panelu. Nazwa nigdy nie jest wysyłana do LLM, więc nie wpływa na zachowanie agenta.

### Wyzwalacz

Opis, kiedy agent powinien użyć tej procedury, na przykład *Gdy użytkownik prosi o zwrot środków za zamówienie*.

Pozostaw wyzwalacz pusty tylko podczas tworzenia [podprocedury](#sub-procedures).

### Treść

Treść procedury, napisana w markdown. Opisuje, co agent powinien zrobić: zadać pytanie, wyszukać zamówienie, wywołać narzędzie lub zakończyć rozmowę. Może być numerowaną sekwencją kroków albo ogólnymi wskazówkami do danej sytuacji. Każdy krok lub wskazówka może być jednym zdaniem (*Poproś użytkownika o identyfikator zamówienia*) albo krótkim akapitem wyjaśniającym, co zrobić i dlaczego.

Używaj numerowanych kroków dla działań wykonywanych po kolei, a punktów dla wymagań lub podpunktów w kroku.

### Odwołania inline

Procedury mogą inline odwoływać się do różnych zasobów:

* Narzędzi (np. wyszukiwania zamówienia, obciążenia karty, zakończenia rozmowy, przekazania do człowieka)
* Dokumentów bazy wiedzy
* Innych procedur

Używaj odwołań inline, gdy krok wymaga użycia przez agenta narzędzia, dokumentu bazy wiedzy lub innej procedury. Odwołania automatycznie dołączają zasób do procedury, aby agent mógł go użyć. Zwykłe wzmianki w tekście (np. *użyj tu narzędzia kalkulatora*) też działają, ale tylko jeśli zasób jest już dołączony do agenta.

Wstaw odwołanie, wpisując `/` w wyzwalaczu lub treści, a następnie wybierając zasób z menu ukośnika. Odwołania pojawiają się w edytorze jako klikalne tagi. Kliknij tag, aby otworzyć powiązany zasób i sprawdzić jego konfigurację.

Podczas pisania treści w dowolnej formie przez API wstaw odwołania w następującej składni:

```text focus={1-5}
[tool id="tool_abc123"]
[kb id="kb_abc123"]
[procedure id="agtprc_abc123"]
[system_tool id="end_call"]
{{customer_id}}
```

Odwołanie inline do procedury musi używać procedury tego samego agenta. Zobacz [Ograniczenia](/docs/pl/eleven-agents/customization/procedures#limitations), aby poznać zakres agenta i działanie duplikacji.

Odwołanie w wyzwalaczu pozwala uruchomić procedurę na podstawie wyniku zasobu, na przykład *Gdy `get_user` zwraca poziom „gold”*. Odwołanie w treści mówi agentowi, aby wywołał lub sprawdził zasób w tym kroku.

Dokumenty bazy wiedzy, do których odwołuje się procedura, zawsze używają trybu `auto` [użycia](/docs/pl/eleven-agents/customization/knowledge-base#how-your-agent-uses-knowledge): gdy RAG jest włączony dla agenta, pobiera on odpowiednie fragmenty zamiast umieszczać cały dokument w prompcie. Jeśli dokument jest też dołączony do agenta, stosowany jest dla niego tryb użycia agenta, dlatego dołącz go do agenta w trybie `prompt`, aby zachować pełny tekst w prompcie.

![Menu ukośnika w edytorze procedury](/docs/_fern-img/8625ffec0f5584619e6ccb97720fd86f2e8d3cd0061308ad87b57f176e5535e3.webp)

Jeśli zasób, do którego się odwołano, zostanie później usunięty lub twoje konto straci do niego dostęp, tag będzie oznaczony jako uszkodzony. Etykieta **Błędy** u góry edytora wyświetla te odwołania: *nieprawidłowe*, jeśli zasób już nie istnieje, albo *niedostępne*, jeśli istnieje, ale twoje konto nie ma do niego dostępu. Otwórz etykietę, aby sprawdzić, którego kroku dotyczy problem, i popraw lub usuń odwołanie.

![Okno błędów z listą nieprawidłowych
odwołań](/docs/_fern-img/e9ec6b19be2992da80a726883baf53265a5d5b38621373cd7e60375c944674cd.webp)

## Podprocedury

Podprocedura ma pusty wyzwalacz. Agent może uruchomić ją tylko z innej procedury, która się do niej odwołuje.

Używaj podprocedur, aby [współdzielić kroki](#composing-procedures) w ramach jednego agenta i zmniejszyć liczbę procedur dostępnych jednocześnie. Nadaj procedurze wejściowej wyzwalacz, odwołaj się w jej treści do powiązanych podprocedur, a ich wyzwalacze pozostaw puste.

Podprocedura eskalacji może zawierać kroki przekazania rozmowy człowiekowi. Odwołaj się do niej z procedur zwrotu środków i anulowania, a jej wyzwalacz pozostaw pusty. Agent może eskalować jako krok dowolnej z tych procedur, ale poza nimi podprocedura pozostanie niedostępna.

## Importowanie z dokumentu

Możesz zacząć od istniejącej standardowej procedury operacyjnej (SOP). Wybierz **Z SOP** w menu **+** na liście procedur, a następnie prześlij plik.

Obsługiwane formaty: `PDF`, `DOCX`, `TXT`, `MD`, `HTML`, `EPUB`. Pliki muszą mieć maksymalnie 20 MB.

Importer analizuje dokument, rozpoznaje maksymalnie 10 odrębnych procedur i tworzy dla każdej szkic z wygenerowaną nazwą, wyzwalaczem i treścią. Otwórz każdy szkic, aby go dopracować. Jeśli dokument zawiera więcej niż 10 SOP-ów, przed przesłaniem podziel go na mniejsze pliki.

![Okno przesyłania SOP](/docs/_fern-img/716601fc90dea757e23971e5aabe063e6a66fc0f75878247dc9f1fc3011f5197.webp)

## Zarządzanie procedurą w dowolnej formie

#### Tworzenie w panelu

Otwórz agenta w [panelu](https://elevenlabs.io/app/agents), a następnie wybierz **Procedury**.
Użyj **+**, aby utworzyć procedurę w dowolnej formie. Dodaj wyzwalacz i napisz instrukcje w
edytorze treści, a następnie opublikuj zmiany agenta.

#### Zarządzanie przez API

Procedury w dowolnej formie przechowują markdown w `content`.

### Wymagania wstępne

* Klucz API ElevenLabs w zmiennej środowiskowej `ELEVENLABS_API_KEY`.
* Docelowe `agent_id` i `branch_id`. Operacje na gałęziach opisuje [Wersjonowanie agenta](/docs/pl/eleven-agents/operate/versioning).
* Wersja `2.60.0` lub nowsza pakietu Python `elevenlabs` albo pakietu JavaScript `@elevenlabs/elevenlabs-js`.

Szkice procedur są [przypisane do użytkownika i gałęzi](/docs/pl/eleven-agents/operate/versioning#drafts). Publikacja zapisuje zmiany procedur
w nowej wersji agenta w tej gałęzi. Szkice innych użytkowników pozostają bez zmian.

### Utwórz szkic

```python focus={1,5-15}
from elevenlabs import CreateProcedureRequestModel, ElevenLabs

elevenlabs = ElevenLabs()

procedure = elevenlabs.conversational_ai.agents.procedures.create(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t",
    request=CreateProcedureRequestModel(
        name="Refund request",
        type="free_form",
        trigger="When the user asks to refund, return, or get money back for an order",
        content="Ask for the order ID, then look it up with [tool id=\"tool_abc123\"].",
    ),
)

print(procedure.procedure_id)
```

```typescript focus={5-15}
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

const procedure = await elevenlabs.conversationalAi.agents.procedures.create(
  "agent_7101k5zvyjhmfg983brhmhkd98n6",
  "agtbranch_0901k4aafjxxfxt93gd841r7tv5t",
  {
    name: "Refund request",
    type: "free_form",
    trigger: "When the user asks to refund, return, or get money back for an order",
    content: "Ask for the order ID, then look it up with [tool id=\"tool_abc123\"].",
  }
);

console.log(procedure.procedureId);
```

```bash focus={1-8}
curl -X POST "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6/branches/agtbranch_0901k4aafjxxfxt93gd841r7tv5t/procedures" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Refund request",
    "type": "free_form",
    "trigger": "When the user asks to refund, return, or get money back for an order",
    "content": "Ask for the order ID, then look it up with [tool id=\"tool_abc123\"]."
  }'
```

Odpowiedź zawiera nowe `procedure_id`. Aby zaktualizować szkic, wywołaj
`PATCH /procedures/{procedure_id}/draft` z `name`, `content`, `type` i jawnym
`trigger`.

Użyj niepustego `trigger` dla procedury wejściowej. W przypadku
[podprocedury](#sub-procedures) użyj pustego ciągu znaków.

### Opublikuj zmiany

Zaktualizuj agenta w gałęzi, aby opublikować szkice procedur w dowolnej formie w nowej wersji.
Żądanie nie wymaga pól w treści; publikacja używa szkiców w ich obecnej formie.

```python focus={5-8}
from elevenlabs import ElevenLabs

elevenlabs = ElevenLabs()

elevenlabs.conversational_ai.agents.update(
    agent_id="agent_7101k5zvyjhmfg983brhmhkd98n6",
    branch_id="agtbranch_0901k4aafjxxfxt93gd841r7tv5t",
)
```

```typescript focus={5-7}
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

const elevenlabs = new ElevenLabsClient();

await elevenlabs.conversationalAi.agents.update("agent_7101k5zvyjhmfg983brhmhkd98n6", {
  branchId: "agtbranch_0901k4aafjxxfxt93gd841r7tv5t",
});
```

```bash focus={1-5}
curl -X PATCH \
  "https://api.elevenlabs.io/v1/convai/agents/agent_7101k5zvyjhmfg983brhmhkd98n6?branch_id=agtbranch_0901k4aafjxxfxt93gd841r7tv5t" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Informacje o usuwaniu i odrzucaniu szkiców znajdziesz w sekcji [Zarządzanie procedurami](/docs/pl/eleven-agents/customization/procedures#manage-procedures), a pełne schematy endpointów w [dokumentacji API procedur](/docs/pl/api-reference/agents/procedures/).

## Dobre praktyki

> **Tip**
>
> Agent musi wybrać właściwą procedurę na podstawie jej wyzwalacza i wykonać jej treść. Bardziej
> zaawansowane modele robią to pewniej, gdy rośnie liczba procedur. Dostępne opcje znajdziesz w sekcji
> [Modele](/docs/pl/eleven-agents/customization/llm).

Dobre pisanie procedur oznacza dobre napisanie dwóch części: wyzwalacza, który uruchamia procedurę wtedy, gdy trzeba, oraz treści, którą agent potrafi wykonać.

### Dopracowywanie procedury

Zalecamy zacząć od małej skali i używać [testów agenta](/docs/pl/eleven-agents/customization/agent-testing), aby sprawdzić każdą zmianę przed wprowadzeniem kolejnej.

#### Napisz krótką procedurę

Napisz wyzwalacz i krótką treść. Rozwijaj treść tylko wtedy, gdy test pokaże, że agent
potrzebuje więcej instrukcji.

#### Dodaj testy wyzwalacza

Utwórz testy symulacji dla próśb, które powinny uruchomić procedurę, oraz dla podobnych próśb,
które nie powinny jej uruchamiać. Większość błędów wynika z wyzwalacza, dlatego napisz więcej
takich testów niż pełnych symulacji.

#### Dodaj pełną symulację

Utwórz test symulacji, który uruchamia całą procedurę i sprawdza wynik.

#### Uruchom testy i napraw błędy

Gdy test się nie powiedzie, popraw wyzwalacz lub treść, a potem uruchom ponownie każdy test.

> **Tip**
>
> Aby szybko dopracować wyzwalacz, utwórz test symulacji, którego [historia czatu](/docs/pl/eleven-agents/customization/agent-testing#simulation-testing) kończy się prośbą
> użytkownika, i ustaw **Maksymalną liczbę tur rozmowy** na `1`. Agent odpowie raz, co wystarczy,
> aby sprawdzić, czy prośba uruchamia właściwą procedurę, a każde uruchomienie będzie krótkie. Kryterium
> sukcesu zapisz jako *Agent uruchomił procedurę zwrotu środków*. Bez historii czatu agent z pierwszą
> wiadomością wykorzysta jedyną turę na powitanie, więc test niczego nie sprawdzi.

Gdy test lub rozmowa na żywo się nie powiedzie, poszukaj kategorii błędu, która za tym stoi. Jeśli agent powiedział coś nieprawidłowego, dodanie *Nie mów tego* naprawi jedną rozmowę. Przeszukaj wcześniejsze rozmowy pod kątem podobnych błędów i napisz jedną instrukcję, która obejmie je wszystkie. Przyczyna może też leżeć w bazie wiedzy lub konfiguracji agenta. [Architect](/docs/pl/eleven-agents/operate/architect) może przeprowadzić takie wyszukiwanie: otwórz nieudaną rozmowę, wybierz **Architect** i poproś go o znalezienie podobnych błędów oraz zaproponowanie rozwiązania. Architect może też zamienić rozmowę w test.

### Pisanie wyzwalaczy

#### Wyzwalacze powinny być konkretne i rozłączne

Nakładające się lub niejasne wyzwalacze powodują uruchamianie niewłaściwej procedury. Lepiej użyć *Gdy użytkownik prosi o
anulowanie subskrypcji* niż \_Gdy użytkownik ma pytanie dotyczące konta \_.

#### Pisz z perspektywy użytkownika

Opisz, o co prosi użytkownik, a nie co powinien zrobić agent. Wyzwalacze sformułowane jako
działania agenta są mniej niezawodne. Lepiej użyć *Gdy użytkownik prosi o anulowanie subskrypcji* niż \_Anuluj
subskrypcję użytkownika \_.

#### Uwzględnij sposób, w jaki użytkownicy naprawdę pytają

Zbyt wąski wyzwalacz może pominąć rzeczywiste prośby, gdy użytkownik sformułuje je inaczej. Uwzględnij
warianty, których użytkownik może użyć. *Gdy użytkownik prosi o zwrot środków, zwrot produktu lub odzyskanie pieniędzy za
zamówienie* działa pewniej niż \_Gdy użytkownik prosi o zwrot środków \_. [Przeszukaj wcześniejsze rozmowy](/docs/pl/eleven-agents/customization/agent-analysis/smart-search), aby sprawdzić, jak użytkownicy
formułują prośbę.

#### Przekazuj między powiązanymi procedurami

Użytkownicy czasem zmieniają prośbę w trakcie procedury, a sam wyzwalacz może nie
uruchomić właściwej. W przypadku zmiany, którą często widzisz w wcześniejszych rozmowach, dodaj odwołanie inline
do drugiej procedury w treści pierwszej. Na przykład napisz \_Jeśli użytkownik chce
zwrot środków zamiast wymiany, uruchom \_, a następnie dodaj odwołanie inline do procedury zwrotu środków. Jeśli
większość procedur wymaga przekazania, zamiast tego bardziej rozróżnij wyzwalacze.

### Pisanie treści

#### Używaj trybu rozkazującego

Zapisuj kroki jako instrukcje dla agenta: *Wyszukaj ostatnie zamówienie klienta* zamiast \_Powinieneś
wyszukać ostatnie zamówienie klienta \_. Bezpośrednie instrukcje są łatwiejsze do wykonania niż
sugestie.

#### Wyjaśnij, dlaczego krok jest ważny

Uzasadnienie można zastosować do przypadków brzegowych, których procedura nie wymienia. Krótkie *ponieważ potrzebujemy
identyfikatora zamówienia, aby zwrócić środki* pomaga agentowi obsłużyć sytuacje, których kroki nie przewidziały.
Unikaj poleceń MUSI zapisanych wielkimi literami i sztywnych skryptów, gdy jednozdaniowe wyjaśnienie zrobi to samo.

#### Mów, co robić, zamiast czego unikać

Opisz zachowanie, którego oczekujesz. *Jeśli nie możesz znaleźć zamówienia, poproś użytkownika o potwierdzenie identyfikatora
zamówienia* działa lepiej niż \_Nie wymyślaj szczegółów zamówienia \_. W przypadku błędów o wysokim
koszcie dodaj też [zabezpieczenie](/docs/pl/eleven-agents/best-practices/guardrails).

#### Używaj kroków, gdy kolejność ma znaczenie

Numerowane kroki pomagają, gdy agent musi wykonywać działania w ustalonej kolejności. W przypadku decyzji wymagających oceny kilka
zdań wskazówek często działa lepiej, zwłaszcza w przypadku bardziej zaawansowanych modeli.

#### Przechowuj fakty w bazie wiedzy

Procedura opisuje, co agent powinien zrobić w danej sytuacji. Konkretne informacje, takie jak
ceny, szczegóły planów czy godziny otwarcia, należą do [bazy wiedzy](/docs/pl/eleven-agents/customization/knowledge-base). Odwołaj się do dokumentu z procedury,
która go potrzebuje. Na przykład zamiast wymieniać w procedurze cenę każdego planu,
napisz *Podaj cenę z*, a następnie dodaj odwołanie inline do dokumentu z cennikiem.

### Łączenie procedur

#### Pisz jedną procedurę na sytuację

Jeśli jedna sytuacja jest podzielona na kilka wąskich procedur, agent ma więcej wyzwalaczy do
wyboru i częściej uruchamia niewłaściwą. Jeśli dwie procedury uruchamiałyby się na tę samą
prośbę, połącz je. Treść dłuższa niż około 3000 znaków zwykle obejmuje więcej niż jedną
sytuację.

#### Przenieś wspólne kroki do podprocedury

Jeśli te same kroki pojawiają się w wielu procedurach (weryfikacja tożsamości klienta, wyszukiwanie
zamówienia, eskalacja do człowieka), przenieś je do [podprocedury](#sub-procedures) i
odwołaj się do niej z każdej potrzebującej jej procedury przez menu ukośnika. Utrzymywanie wspólnych kroków w jednym
miejscu zapewnia spójność wszystkich procedur, które ich używają.

#### Używaj podprocedur do działań reaktywnych

Użyj podprocedury dla działania, które agent powinien wykonać tylko wtedy, gdy poprosi o to inna procedura,
na przykład weryfikacji tożsamości lub eskalacji. Bez wyzwalacza nie konkuruje ona z procedurami
wejściowymi na początku rozmowy. Mniej opcji wyzwalacza pomaga utrzymać skupione kierowanie.

#### Odwołuj się do narzędzi z procedury, która ich używa

Odwołuj się do narzędzia z procedury, która go używa, zamiast dołączać je do całego agenta. Dzięki temu
narzędzie pozostaje poza niepowiązanymi rozmowami. W procedurze w dowolnej formie narzędzie jest dostępne
tylko wtedy, gdy procedura należy do pięciu ostatnio uruchomionych, dlatego wspomnij o zadaniu narzędzia także
w wyzwalaczu, na przykład *lub gdy trzeba wyszukać zamówienie*. Zobacz
[Ograniczenia](/docs/pl/eleven-agents/customization/procedures#limitations).

#### Używaj promptu systemowego dla globalnego zachowania

Ton, tożsamość, zasady odmowy i zabezpieczenia należą do [promptu systemowego](/docs/pl/eleven-agents/best-practices/prompting-guide).
Kroki dotyczące konkretnych zadań umieszczaj w procedurach.

#### Procedury są wersjonowane razem z agentem

Procedury są częścią konfiguracji agenta, więc podczas publikacji nowej wersji agenta tworzona jest ich migawka.
Aby wrócić do wcześniejszego zestawu procedur, przywróć wcześniejszą wersję agenta.
Zobacz [Wersjonowanie agenta](/docs/pl/eleven-agents/operate/versioning).

#### Zacznij od istniejącej dokumentacji

Jeśli twój zespół ma już SOP-y, użyj importera, aby zamienić je w szkice, a następnie je dopracuj.