Agent Registry — Ajan Havuzu Standardı

Ana sayfa › AI ile Geliştirme › Agent Registry — Ajan Havuzu

🗃️Agent Registry — Ajan Havuzu Standardı

📑 Bu sayfada

R.1 Neden Agent Registry?
R.2 Ajan Tanımı & Artifact'ten Farkı
R.3 Agent ID & Klasör Yapısı
R.4 Zorunlu Metadata Şeması (agent.yaml)
R.5 README.md Şablonu (Ajan)
R.6 Lifecycle: alpha → beta → GA → deprecated → retired
R.7 RBAC — Kim ne yapabilir?
R.8 Discovery & Marketplace UX
R.9 Eval Eşikleri & Otomatik Geri Çekme
R.10 Versiyonlama & Geriye Uyumluluk

Komtaş çalışanlarının geliştirdiği AI ajanlarını tek bir keşfedilebilir, denetlenebilir ve yeniden kullanılabilir havuzda toplamak için tasarlanmış registry standardı. Artifact Repository nasıl excel/html/script türlerini standardize ediyorsa, Agent Registry de "agent" türünü standardize eder.

📘 Bu sayfa neyi çözer? s-artifact sayfasında "Gelecek Faz: Skills Repository" notu vardı. Bu sayfa o gelecek fazın tasarım belgesidir: ajanlar için hangi metadata, hangi onay, hangi runtime, hangi audit?

R.1 Neden Agent Registry?

❌ Registry olmadan

Aynı ajan 5 farklı ekip tarafından yeniden geliştiriliyor (tekrar maliyeti)
Ajanın güvenlik review'undan geçip geçmediği belirsiz
Hangi ajanın hangi modeli/MCP server'ı kullandığı kayıtsız
Ajan davranışı bozulduğunda kim sahipli, kim müdahale edecek belirsiz
Token maliyetleri kim ödüyor sorusu cevapsız

✅ Registry ile

Çalışanlar mevcut ajanı keşfedip tekrar kullanır
Onay süreci tek standart kapı kontrolünden geçer
Audit/incident response için tek doğru kaynak
Maliyet & performans her ajan için trend olarak görünür
Deprecate edilen ajan otomatik trafik kesilir

R.2 Ajan Tanımı & Artifact'ten Farkı

Ajan = Bir LLM'i, bir veya daha fazla aracı (tool/MCP), bir sistem promptunu, bir guardrail setini ve bir runtime'ı tek bir adlandırılmış birimde birleştiren çalıştırılabilir dijital varlıktır. Artifact statik bir çıktıdır (rapor, dashboard); ajan ise çağrı başına yeniden hesaplayan bir hizmettir.

Boyut	Artifact (s-artifact)	Agent (bu sayfa)
Doğa	Statik dosya	Çalışan servis
Çağrı maliyeti	Sıfır (yalnızca açılışta)	Token ücreti var
Sürüm yönetimi	SemVer + dosya kopyası	SemVer + container image hash
Onay kapsamı	Veri sınıfı + erişim	Veri sınıfı + güvenlik review + eval baseline
Audit	Erişim logu	Her çağrı için Langfuse trace
Lifecycle	created → updated → archived	alpha → beta → GA → deprecated → retired

R.3 Agent ID & Klasör Yapısı

Agent ID formatı: AGT-[DEP]-[YYYY]-[NNN] — örn. AGT-FIN-2026-001, AGT-IT-2026-007.

Komtas-AI-Agents/
├── Finans/
│   ├── AGT-FIN-2026-001-NakitAkisAsistani/
│   │   ├── agent.yaml          ← Zorunlu — registry'nin okuduğu manifest
│   │   ├── README.md           ← İnsan dokümantasyonu
│   │   ├── system_prompt.md    ← Versiyonlu sistem promptu
│   │   ├── tools/              ← Tool tanımları (JSON Schema)
│   │   │   ├── query_cashflow.json
│   │   │   └── send_alert.json
│   │   ├── evals/              ← RAGAS test seti + sonuçlar
│   │   │   ├── golden_questions.jsonl
│   │   │   └── baseline_v1.0.0.json
│   │   ├── guardrails.yaml     ← Lakera/Presidio politikaları
│   │   ├── CHANGELOG.md
│   │   └── deploy/             ← Helm values veya Copilot Studio export
│   └── AGT-FIN-2026-002-.../
├── Hukuk/
├── IT/
└── [Departman]/

R.4 Zorunlu Metadata Şeması (agent.yaml)

Alan	Tip	Açıklama	Zorunlu?
`agent_id`	string	AGT-DEP-YYYY-NNN	✅
`name`	string	İnsan tarafından okunabilir ad	✅
`description`	string	2-3 cümle — Copilot vektörize eder	✅
`owner`	string	Sahip kişi (e-posta) + yedek	✅
`department`	string	Resmi departman	✅
`version`	semver	1.2.0	✅
`lifecycle`	enum	alpha / beta / ga / deprecated / retired	✅
`model`	string	claude-sonnet-4-6 / gpt-4o / gemini-2.5-pro	✅
`fallback_model`	string	Birincil model arızalanırsa	Opsiyonel
`max_iterations`	int	Tool-use döngü sınırı	✅
`tools`	list	Tool adları (her biri JSON şemasıyla tanımlı)	✅
`mcp_servers`	list	Bağlanılan MCP server URL'leri (scope ile)	Opsiyonel
`data_classification`	enum	kamu / dahili / gizli / kisitli	✅
`guardrails`	object	{lakera: true, presidio: true, custom: [...]}	✅
`human_in_loop`	object	{required_for: ["send_email", "create_invoice"]}	Önerilir
`eval`	object	{ragas: {faithfulness_min: 0.85, answer_relevancy_min: 0.8}}	✅
`cost_center`	string	Token chargeback için departman/proje kodu	✅
`token_budget_monthly`	int	Aylık üst sınır (USD)	✅
`runtime`	enum	n8n / copilot-studio / komtas-copilot / cloud-run	✅
`endpoint`	url	Üretim çağrı endpoint'i	✅
`tags`	list	Arama için etiketler	✅
`kvkk_dpia`	url	DPIA dokümanı linki (kişisel veri varsa)	⚠️ Şartlı

Örnek agent.yaml

agent_id: AGT-IG-2026-003
name: Müşteri Araştırma Asistanı
description: |
  Verilen şirket adı için web ve CRM'den son 6 aylık haberler,
  finansal göstergeler ve toplantı geçmişini özetler.
owner: kadir.evciler@komtas.com.tr
backup_owner: pinar.baydar@komtas.com.tr
department: Iş Geliştirme
version: 1.1.0
lifecycle: ga
model: claude-sonnet-4-6
fallback_model: claude-haiku-4-5-20251001
max_iterations: 8
tools:
  - web_search
  - hubspot_company_lookup
  - sharepoint_meeting_notes
mcp_servers:
  - url: http://komtas-mcp:8080/sse
    scopes: [contracts:read, customers:read]
data_classification: dahili
guardrails:
  lakera: true
  presidio: true
  custom:
    - block_competitor_negative_framing
human_in_loop:
  required_for:
    - send_external_email
    - create_crm_task
eval:
  ragas:
    faithfulness_min: 0.85
    answer_relevancy_min: 0.80
  golden_set: evals/golden_questions.jsonl
cost_center: IG-2026-Sales
token_budget_monthly: 250
runtime: cloud-run
endpoint: https://agents.komtas.internal/customer-research/v1
tags: [is-gelistirme, musteri, arastirma, brief, hubspot]
kvkk_dpia: https://komtas.sharepoint.com/dpia/AGT-IG-2026-003.docx

R.5 README.md Şablonu (Ajan)

# [Ajan Adı]

> Tek cümle: ajanın çözdüğü problem

## Hızlı Başla
- Endpoint: `POST {{endpoint}}`
- Örnek payload: `{"query": "Acme Inc son 3 aydaki gelişmeler"}`
- Çalışma süresi: ~8-12 sn (p95)

## Ne yapar / Ne yapmaz
✅ Yapar: web aramalı şirket brief'i, son toplantı notu özeti
❌ Yapmaz: müşteri kişisel bilgisi sorgulama, dış e-posta gönderme

## Veri Sınıfı & Erişim
- data_classification: dahili
- access: İş Geliştirme + Sales departmanı

## Tool/MCP bağımlılıkları
- web_search (DuckDuckGo wrapper)
- HubSpot CRM read-only
- SharePoint meeting notes search

## Eval & Kalite
- RAGAS faithfulness: 0.87 (eşik 0.85) ✅
- 50 golden test sorusu evals/golden_questions.jsonl içinde
- Aylık otomatik regression koşar

## Maliyet
- Aylık bütçe: $250
- Çağrı başına ortalama: ~$0.04
- Cost center: IG-2026-Sales

## Sahiplik & Olay Müdahalesi
- Birincil sahip: kadir.evciler@komtas.com.tr
- Yedek: pinar.baydar@komtas.com.tr
- Slack kanalı: #agent-customer-research

## Versiyon Geçmişi
- 1.1.0 (2026-04-15) — fallback model eklendi
- 1.0.0 (2026-03-01) — GA

R.6 Lifecycle: alpha → beta → GA → deprecated → retired

α alpha

→

β beta

→

✓ GA

→

deprecated

→

retired

Faz	Kim çağırabilir?	SLO	Çıkış kriterleri
alpha	Sadece geliştirici + Yedek	Yok	10+ başarılı manuel test
beta	Pilot grup (5-15 kullanıcı)	p95 < 30 sn	RAGAS baseline geçti, NPS >= 7
GA	access listesindeki herkes	p95 < 15 sn, %99.5 uptime	—
deprecated	Mevcut kullanıcılar (uyarı banner ile)	—	Geçiş süresi tamamlandı
retired	Hiç kimse — endpoint 410 döner	—	—

R.7 RBAC — Kim ne yapabilir?

Rol	Çağır	Kod düzenle	Versiyon yayınla	Konfig değiştir	Audit log oku	Retire et
Owner	✅	✅	✅ (beta dahil)	✅	✅	✅
Maintainer	✅	✅	⚠️ Owner onayıyla	✅	✅	❌
Operator	✅	❌	❌	✅ (kota/feature flag)	✅	❌
Viewer	✅	❌	❌	❌	❌	❌
Auditor	❌	❌	❌	❌	✅	❌
Governance	—	—	✅ (GA promote)	—	✅	✅ (acil)

R.8 Discovery & Marketplace UX

Komtaş CoPilot içinde "Ajan Kataloğu" sayfası, kullanıcının doğal dilde "müşteri brief'i için bir ajan var mı?" sorusunu yanıtlar. Backend Qdrant'ta vektör araması yapar (description + tags), erişim filtresini RBAC'a göre uygular.

🔍 Doğal dil sorgu

→

Qdrant vektör arama

→

RBAC filtre

→

Top 5 ajan kart

→

"Şimdi Çalıştır" butonu

Ajan Kart UI Önerisi

Müşteri Araştırma Asistanı

AGT-IG-2026-003 · v1.1.0 · GA

✓ Erişimin var

Verilen şirket adı için son 6 aylık haberler, finansal göstergeler ve toplantı geçmişini özetler.

⏱ ~10 sn 💰 ~$0.04/çağrı ⭐ 4.6 (38 oy)

is-gelistirme musteri hubspot

R.9 Eval Eşikleri & Otomatik Geri Çekme

Her GA ajanı için günlük otomatik eval koşar. Eşiklerin altına düşerse Governance ekibine alarm + otomatik deprecated öneri.

Metrik	Yeşil	Sarı (uyarı)	Kırmızı (otomatik deprecate önerisi)
RAGAS faithfulness	≥ 0.85	0.75 - 0.85	< 0.75
RAGAS answer relevancy	≥ 0.80	0.70 - 0.80	< 0.70
p95 latency	< 15 sn	15 - 30 sn	> 30 sn (3 gün üst üste)
Hata oranı (5xx)	< 0.5%	0.5% - 2%	> 2%
Aylık bütçe kullanımı	< 100%	100% - 130%	> 130% (2 ay üst üste)
Lakera flag oranı	< 1%	1% - 5%	> 5% (manuel review)

📌 İlgili RAGAS metodolojisi: RAGAS Değerlendirme (s4) · Langfuse trace standartları: Gözlemlenebilirlik (s6)

R.10 Versiyonlama & Geriye Uyumluluk

PATCH (1.0.x): Bug fix, prompt iyileştirmesi, eval skorunu artıran değişiklik. Sözleşme aynı, geriye uyumlu.
MINOR (1.x.0): Yeni tool, opsiyonel parametre, geriye uyumlu sözleşme genişlemesi.
MAJOR (x.0.0): Endpoint imzası değişti, çıktı şeması değişti, kullanıcı kodu güncellemesi gerek. Eski sürüm en az 90 gün deprecated kalır.

⚠️ Sunset Politikası Bir ajan retire edildiğinde eski endpoint HTTP 410 Gone + body içinde yeni ajan ID'si döner. Çağıran taraf 7 gün içinde geçişi tamamlamak zorundadır. Saklanan trace'ler 1 yıl audit amaçlı tutulur.

← ÖncekiArtifact Repository Sonraki →Ajan Onay Akışı