Aufgaben und Kontext

Erstellen Sie eine aktive Task Guard-Task pro Agent-Sitzung, rufen Sie den aktuellen Vertrag zu Beginn jedes Arbeitszyklus ab, zeichnen Sie aussagekräftige Meilensteine auf und vervollständigen oder überführen Sie ihn explizit.

Starten Sie eine Aufgabe#

Verwendung POST /v1/task-guard/tasks. POST /v1/task-guard/sessions ist ein Alias mit der gleichen Anfrage und Antwort.

Benötigt task_guard:tasks:write.

curl -X POST "https://api.maetra.io/v1/task-guard/tasks" \
  -H "Authorization: Bearer $MAETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_ref": "conversation_01JY8Q",
    "title": "Ship approval flow",
    "objective": "Add and verify the customer refund approval flow.",
    "constraints": ["Do not change billing provider configuration."],
    "in_scope": ["API route", "dashboard UI", "tests"],
    "out_of_scope": ["Production deployment"],
    "success_criteria": ["Lint and tests pass", "Approval can be completed end to end"],
    "agent_name": "release-agent",
    "host_type": "CUSTOM_API",
    "integration_mode": "ADVISORY",
    "confirmation_capable": true,
    "effect_reporting_capable": true,
    "idempotency_key": "task-start-01JY8Q"
  }'

session_ref, objective, und entweder idempotency_key oder direct_user_event_id erforderlich sind. Die Wiederverwendung des gleichen Ereignisschlüssels mit einer anderen Anforderung gibt einen Konflikt zurück.

{
  "ok": true,
  "session_id": "tgs_01JY8R",
  "session_ref": "conversation_01JY8Q",
  "task": {
    "id": "tgt_01JY8S",
    "sequence": 1,
    "status": "active",
    "title": "Ship approval flow",
    "completed_at": null
  },
  "contract_version": 1,
  "anchor": {
    "objective": "Add and verify the customer refund approval flow.",
    "constraints": ["Do not change billing provider configuration."],
    "in_scope": ["API route", "dashboard UI", "tests"],
    "out_of_scope": ["Production deployment"],
    "success_criteria": ["Lint and tests pass", "Approval can be completed end to end"],
    "decisions": [],
    "open_questions": [],
    "accepted_expansions": [],
    "anchor_hash": "sha256:…",
    "anchor_text": "…"
  },
  "host": {
    "type": "custom_api",
    "integration_mode": "advisory"
  },
  "next_action": "Call get_task_context after compaction and check_task_alignment before meaningful actions."
}

Das Starten eines neuen Ziels in einer bestehenden Sitzung ersetzt die vorherige aktive Aufgabe. Eine nachfolgende Aufgaben- oder Vertragsrevision erfordert eine direct_user_event_id. In ENFORCED Modus, Task-Übergänge müssen den vertrauenswürdigen Host-Benutzerereignis-Endpunkt unten verwenden.

Den aktiven Kontext abrufen#

Verwenden Sie entweder den Endpunkt:

GET /v1/task-guard/tasks/{taskId}
GET /v1/task-guard/tasks/{taskId}/context

Beide erfordern task_guard:tasks:read und die aktuelle Aufgabe, Vertragsversion, Anker, Host-Modus zurückzugeben und next_action.

curl "https://api.maetra.io/v1/task-guard/tasks/tgt_01JY8S/context" \
  -H "Authorization: Bearer $MAETRA_API_KEY"

Kontextaktualisierung zu Beginn eines neuen Arbeitszyklus, nach Kontextkompaktierung oder Neustart und immer dann, wenn eine Ausrichtungsprüfung zurückkehrt CONTEXT_REFRESH_REQUIRED.

Rekordfortschritte#

Verwendung POST /v1/task-guard/tasks/{taskId}/progress Nach einem bedeutsamen Meilenstein.

Benötigt task_guard:tasks:write.

{
  "summary": "API route and validation are complete.",
  "completed": ["Implemented the refund approval endpoint"],
  "next_steps": ["Connect the dashboard form", "Run integration tests"],
  "new_dependencies": [],
  "open_questions": [],
  "current_step": "Implement dashboard integration",
  "idempotency_key": "progress-01JY9A"
}

Die Antwort gibt das neue zurück contract_version, aktueller Schritt, Aufgaben-ID und nächste Aktion. Überprüfen Sie jeden Artikel in new_dependencies mit dem Ausrichtungsendpunkt, bevor auf ihn eingewirkt wird.

Pause, Lebenslauf oder Abbrechen#

Diese Lifecycle-Endpunkte erfordern task_guard:tasks:write und keine beantragende Stelle:

POST /v1/task-guard/tasks/{taskId}/pause
POST /v1/task-guard/tasks/{taskId}/resume
POST /v1/task-guard/tasks/{taskId}/cancel

Pausieren oder Annullieren widerruft aktive Anpassungszuschüsse. Wiederaufnahme gibt die Aufgabe zurück an active. Jede Antwort enthält task_id, status, und updated_at.

Abschluss der Aufgabe#

Verwendung POST /v1/task-guard/tasks/{taskId}/complete wenn die Ziel- und Erfolgskriterien erfüllt sind.

Benötigt task_guard:tasks:write.

{
  "summary": "Refund approvals are implemented and verified end to end.",
  "completion_event_id": "complete-01JY9Z"
}

{
  "ok": true,
  "task_id": "tgt_01JY8S",
  "status": "completed",
  "summary": "Refund approvals are implemented and verified end to end.",
  "completed_at": "2026-07-20T13:42:18.000Z"
}

Veranstaltungen für vertrauenswürdige Host-Benutzer#

POST /v1/task-guard/sessions/{sessionId}/user-events Starten einer nachfolgenden Aufgabe oder Überarbeiten der aktiven Aufgabe aus einer verifizierten Direktbenutzeranweisung. Es akzeptiert die gleichen Felder wie die Startanforderung und erfordert zusätzlich direct_user_event_id.

Dieser Endpunkt erfordert:

task_guard:confirmations:write
ein API-Schlüssel, der als vertrauenswürdiger Task Guard-Bestätigungsnachweis gekennzeichnet ist
a session_ref Übereinstimmung mit der referenzierten Task Guard-Sitzung

Verwenden Sie diesen Endpunkt für Task-Starts und Übergänge in ENFORCED Integrationen.