Belgeler

PROMIVO nasıl çalışır

Bir ajanı devreye almak, bir iş akışı kurmak ve platformu kendi sistemlerinizden çağırmak için gereken kavramlar.

Ajanlar ve sürümler

Bir ajan, katalog yerindeki bir ilan ile bir ya da daha fazla değiştirilemez sürümden oluşur. Bir sürüm; sistem istemini, model yapılandırmasını, çağırabileceği araçları, girdi ve çıktı şemalarını, çalıştırma sınırlarını ve otomatik risk tavanını taşır.

Bir güncellemeyi yayımlamak yeni bir sürüm oluşturur ve geçerli işaretçiyi taşır. Var olan bir sürüm asla değiştirilmez; bu yüzden hâlihazırda süren bir çalıştırma, başladığı davranışı korur.

İzinler ve risk

Her araç bir risk düzeyi bildirir. Bir ajan sürümü, insan olmadan yapabileceği en yüksek düzeyi bildirir.

READGetirir, arar, özetler. Hiçbir şeyi değiştirmez.
WRITEE-posta gönderir, güncelleme yayınlar, kayıt ekler veya günceller.
DESTRUCTIVEVeri siler veya para harcar.

Tavanın üzerindeki bir araç çağrısı reddedilir, onay bekleyen bir görev olarak kaydedilir ve modele gerçekleştirilmedi olarak bildirilir. Çalıştırma sürer; yan etki gerçekleşmez.

İş akışı düğümleri

Düğüm	Ne yapar
`TRIGGER`	Giriş noktası. Manuel, webhook, zamanlanmış ya da olay tabanlı.
`AI`	Yerleştirilmiş bir girdi şablonuyla bir ajan çalıştırır.
`HTTP`	Genel bir HTTP uç noktasını çağırır. Özel IP aralıkları engellidir.
`CONDITION`	Çalıştırma bağlamındaki bir değere göre dallanır.
`TRANSFORM`	Veriyi yeni bir nesneye dönüştürür.
`EMAIL`	Yapılandırılmış sağlayıcı üzerinden e-posta gönderir.
`WEBHOOK`	Dışarıya imzalı bir JSON yükü gönderir.
`DELAY`	Bir çalıştırma içinde en fazla 300 saniye bekler.
`DATABASE`	Bir not kaydeder ya da son çalıştırmaları okur.
`OUTPUT`	İş akışının nihai sonucunu tanımlar.

Şablonlama

Düğüm yapılandırması, çalıştırma bağlamından değerleri yerleştirir. İfade değerlendirmesi yoktur; bir şablon asla kod çalıştıramaz.

{{trigger.email}}                  → the trigger payload
{{steps.qualify.output.score}}     → an earlier node result
{{workflow.name}}                  → workflow metadata

Genel API

API anahtarları sayfası üzerinden kapsamı sınırlı bir anahtar oluşturun. Sır yalnızca bir kez gösterilir; yalnızca özeti saklanır.

POST /api/agents/run
Authorization: Bearer pmv_live_…
Content-Type: application/json

{ "agentId": "<uuid>", "input": { "topic": "Q4 planning" } }

Her yanıt aynı zarfı kullanır:

{ "ok": true,  "data": { … } }
{ "ok": false, "error": { "code": "…", "message": "…" } }

Uç noktalar

GET /api/agents
POST /api/agents/run
GET /api/workflows
POST /api/workflows
POST /api/workflows/:id/run
GET /api/executions
GET /api/executions/:id
GET /api/usage

Webhook tetikleyicileri

Webhook iş akışı, oluşturulurken bir kez gösterilen genel bir token ve imzalama sırrı alır. Ham gövdeyi bu sırla imzalayın.

POST /api/webhooks/workflow/<token>
x-promivo-secret:    <signing secret>
x-promivo-signature: <hex HMAC-SHA256 of the raw body>
x-idempotency-key:   <optional; makes redelivery safe>

{ "email": "lead@example.com", "message": "…" }