Agenten in Ihren Chats

Ihr erster Agent

1. Öffnen Sie @agentfather und senden Sie /newagent. Wählen Sie einen Namen und einen eindeutigen Nickname mit _agent am Ende (7–32 Zeichen).
2. Klicken Sie in der Antwort auf die Token-Schaltfläche. Bestätigen und speichern Sie den Token auf Ihrem Server. Er erscheint einmal in einem separaten Dialog, nie im Chatverlauf.
3. Starten Sie das Python-Beispiel auf Ihrem Server und schreiben Sie dem Agenten. Logik und KI laufen in Ihrer Infrastruktur; die Erstellung eines Agenten startet kein Modell.

curl https://znosin.com/api/agent/v1/me \
  -H "Authorization: Bearer $ZNOSIN_AGENT_TOKEN"

ZNOSIN_AGENT_TOKEN · Python 3.10+

Verfügbar in v1

Empfange Aktionen mit GET /updates?callbacks=true. Updates enthalten message oder callback. Die Daten kommen vom Server, der Benutzer steht in callback.from. Prüfe die Berechtigungen in deinem System. Antworte über POST /callbacks/{id}/answer mit text und showAlert. Der Client wartet bis zu 10 Sekunden; Aktionen verfallen nach 120 Sekunden. Identische Antworten sind wiederholbar. Aktionen erzeugen keine Chatnachricht. Webhooks und das Hochladen ausgehender Medien sind noch nicht verfügbar.

API-Referenz

HTTPS und JSON. Senden Sie Authorization: Bearer <token>. Erfolg enthält ok und result; Fehler ok:false und error. Nachrichtenzeiten sind Unix-Millisekunden. Alle Felder stehen im OpenAPI-Schema.

https://znosin.com/api/agent/v1

POST /api/agent/v1/messages

{
  "chatId": "CHAT_ID_FROM_UPDATE",
  "text": "Hello!",
  "clientId": "d73d940c-9166-4a39-8e35-c3f7888995ee"
}

PUT /api/agent/v1/commands

{
  "language": "de",
  "commands": [
    {
      "command": "help",
      "description": "Agent-API-Anleitung"
    }
  ]
}

Befehle und Schaltflächen

Ergänze markup in POST /messages oder PATCH /messages/{id}: inline-Zeilen enthalten Aktionen (text, id, data), HTTPS-Links (text, url) oder Mini-Apps (text, appId). reply-Tastaturen senden normale Antworten an den Agenten. oneTime blendet die Tastatur nach Verwendung aus, type remove entfernt sie. Beim Bearbeiten erhält ein ausgelassenes markup die Schaltflächen; null entfernt sie.

{
  "chatId": "CHAT_ID_FROM_UPDATE",
  "text": "Choose an action",
  "clientId": "d73d940c-9166-4a39-8e35-c3f7888995ee",
  "markup": {
    "type": "inline",
    "rows": [
      [
        {
          "text": "Confirm",
          "id": "confirm",
          "data": "confirm:123"
        },
        {
          "text": "Cancel",
          "id": "cancel",
          "data": "cancel:123"
        }
      ],
      [
        {
          "text": "Website",
          "url": "https://znosin.com"
        },
        {
          "text": "Calculator",
          "appId": "calculator"
        }
      ]
    ]
  }
}

Gib / im Chat ein, um Befehle zu sehen. In Gruppen adressiert die Auswahl mit /command@nickname genau einen Agenten. Menüs unterstützen alle sieben Sprachen. Entwickler registrieren bis zu 20 Befehle je Sprache mit PUT /commands.

/setcommands @nickname de · @agentfather

{
  "type": "reply",
  "rows": [
    [
      "Yes",
      "No"
    ],
    [
      "Help"
    ]
  ],
  "oneTime": true
}

8 rows × 4 buttons · 64 characters/label · 256 UTF-8 bytes/data · HTTPS

Sprache des Benutzers

Eingehende Nachrichten und Schaltflächenaktionen enthalten from.language_code: en, ru, uk, de, fr, pl oder zh. Der Wert beschreibt die Oberflächensprache des Absenders beim Erstellen des Ereignisses, auch in Gruppen. Alte Ereignisse, unbekannte Präferenzen und Agent-Nachrichten liefern null; wählen Sie eine Ersatzsprache im eigenen Code. Neustarts und Wiederholungen erhalten den Wert. Spätere Nachrichten, Bearbeitungen oder Geräteeinstellungen ändern ihn nicht. Weiterleitungen tragen die Sprache der weiterleitenden Person, nicht des ursprünglichen Autors. Dies ist eine Client-Präferenz, keine Spracherkennung oder Berechtigung. Clients senden X-Znosin-Language, unterstützt durch Accept-Language als Rückfall. Ihr Code übersetzt Antworten und Schaltflächen. AgentFather folgt bereits der Oberfläche; /language ru legt die Sprache fest, /language auto aktiviert die automatische Auswahl.

{
  "from": {
    "id": "USER_ID",
    "name": "Alex",
    "nickname": "alex",
    "language_code": "de"
  }
}

Zugriff und Datenschutz

Ein Agent kann keine private Unterhaltung beginnen. Ein Mensch schreibt zuerst; /stop sperrt weitere Nachrichten, /start setzt mit neuen Eingaben fort. In Gruppen sieht er nach seinem Beitritt nur Befehle wie /help oder /help@name_agent und Antworten auf eigene Nachrichten. Keine zitierte Historie, alten Nachrichten, E-Mails, Wallets oder Kontoschlüssel des Besitzers. Entfernen aus der Gruppe widerruft den Zugriff.

Zuverlässige Zustellung

Long Polling wartet bis zu 25 Sekunden und antwortet bei neuen Nachrichten. Verwenden Sie einen Consumer pro Agent und speichern Sie nextOffset, auch bei leeren Ergebnissen. Wiederholen Sie Sendungen mit gleicher clientId und gleichem Inhalt. Die Warteschlange hält bis zu 10.000 Eingaben für maximal 24 Stunden; reset meldet Ablauf oder Überlauf. Limits: 180 Anfragen/Minute, 60 Sendungen/Minute pro Agent, 30 pro Chat. Beachten Sie Retry-After bei 429 und 503; warten Sie bei Netzwerkfehlern zunehmend länger.

Agent verwalten

Befehle in @agentfather: /myagents, /token @nickname, /disable @nickname, /enable @nickname, /setname @nickname Name und /setdescription @nickname Beschreibung. Rotation widerruft den alten Token sofort. Deaktivierung widerruft ihn und leert die Warteschlange. Nach Aktivierung ist ein neuer Token nötig. /language en|ru|uk|de|fr|pl|zh wählt die Sprache, /language auto folgt der Oberfläche. Maximal 20 Agenten pro Besitzer.

KI-Modell verbinden

Ersetzen Sie das Echo durch einen Modellaufruf auf Ihrem Server. Informieren Sie Nutzer über an den Modellanbieter gesendete Daten. Behandeln Sie Nachrichten und Dateien als nicht vertrauenswürdig, begrenzen Sie Werkzeugrechte und verlangen Sie Bestätigung bei sensiblen Aktionen. Tokens und Modellschlüssel gehören weder in Prompts noch in Client-Code.