2026-04-10 23:20:41 -04:00
---
layout: default
title: "Araç Hizmetleri: Dinamik Olarak Eklenebilen Ajan Araçları
parent: "Turkish (Beta)"
---
2026-04-11 01:08:44 +00:00
# Araç Hizmetleri: Dinamik Olarak Eklenebilen Ajan Araçları
2026-04-10 23:20:41 -04:00
> **Beta Translation:** This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.
2026-04-11 01:08:44 +00:00
## Durum
Uygulandı
## Genel Bakı
Bu özellik, "araç hizmetleri" olarak adlandı ı ı ı `KnowledgeQueryImpl` , `McpToolImpl` , vb.) aksine, araç hizmetleri, aşağı ı ı
1. Yeni bir Pulsar tabanlı ı ı ı
2. Ajanı ı ı ı ı ı ı ı ı ı
Bu, çekirdek ajan-yanı
## Terminoloji
| Terim | Tanı
|------|------------|
| **Yerleşik Araç** | `tools.py` içinde sabit kodlanmı
| **Araç Hizmeti** | Bir hizmet açı ı ı ı ı
| **Araç** | Bir hizmet aracı ı ı ı ı ı
Bu, MCP araçları ı
MCP: MCP sunucusu araç arayüzünü tanı ı ı ı
Araç Hizmetleri: Araç hizmeti Pulsar arayüzünü tanı ı ı ı
## Arka Plan: Mevcut Araçlar
### Yerleşik Araç Uygulaması
Araçlar şu anda `trustgraph-flow/trustgraph/agent/react/tools.py` içinde, türlenmiş uygulamalarla tanı ı ı
```python
class KnowledgeQueryImpl:
async def invoke(self, question):
client = self.context("graph-rag-request")
return await client.rag(question, self.collection)
```
Her araç türü:
Çağı ı ı `graph-rag-request` )
İstemci üzerinde çağrı `client.rag()` )
Uygulamada tanı ı
### Araç Kaydı
Araçlar, bir uygulamaya eşleyen `type` alanı ı ı
```python
if impl_id == "knowledge-query":
impl = functools.partial(KnowledgeQueryImpl, collection=data.get("collection"))
elif impl_id == "text-completion":
impl = TextCompletionImpl
# ... etc
```
## Mimari
### İki Katmanlı
#### 1. Katman: Araç Hizmeti Tanı ı ı ı
Bir araç hizmeti, bir Pulsar hizmeti arayüzünü tanı ı
İstek/yanı ı ı
Onu kullanan araçlardan gerektirdiği yapı ı
```json
{
"id": "custom-rag",
"request-queue": "non-persistent://tg/request/custom-rag",
"response-queue": "non-persistent://tg/response/custom-rag",
"config-params": [
{"name": "collection", "required": true}
]
}
```
Herhangi bir yapı ı
```json
{
"id": "calculator",
"request-queue": "non-persistent://tg/request/calc",
"response-queue": "non-persistent://tg/response/calc",
"config-params": []
}
```
#### 2. Seviye: Araç Açı ı
Bir araç, bir araç hizmetine başvurur ve şunları
Yapı ı ı
Aracı ı ı
LLM için argüman tanı ı
```json
{
"type": "tool-service",
"name": "query-customers",
"description": "Query the customer knowledge base",
"service": "custom-rag",
"collection": "customers",
"arguments": [
{
"name": "question",
"type": "string",
"description": "The question to ask about customers"
}
]
}
```
Birden fazla aracı ı ı ı ı ı
```json
{
"type": "tool-service",
"name": "query-products",
"description": "Query the product knowledge base",
"service": "custom-rag",
"collection": "products",
"arguments": [
{
"name": "question",
"type": "string",
"description": "The question to ask about products"
}
]
}
```
### İstek Formatı
Bir araç çağrı ı ı ı ı
`user` : Aracı ı ı ı
`config` : Araç açı ı ı ı ı ı ı
`arguments` : LLM'den alı ı ı
```json
{
"user": "alice",
"config": "{\"collection\": \"customers\"}",
"arguments": "{\"question\": \"What are the top customer complaints?\"}"
}
```
Araç hizmeti, bunları `invoke` yönteminde ayrı ı ı ı ı
### Genel Araç Hizmeti Uygulaması
Bir `ToolServiceImpl` sı ı ı ı ı ı ı
```python
class ToolServiceImpl:
def __init__ (self, context, request_queue, response_queue, config_values, arguments, processor):
self.request_queue = request_queue
self.response_queue = response_queue
self.config_values = config_values # e.g., {"collection": "customers"}
# ...
async def invoke(self, **arguments):
client = await self._get_or_create_client()
response = await client.call(user, self.config_values, arguments)
if isinstance(response, str):
return response
else:
return json.dumps(response)
```
## Tasarı ı
### İki Katmanlı
Araç hizmetleri, MCP araçları ı
1. **Araç Hizmeti** : Pulsar hizmet arayüzünü (konu, gerekli yapı ı ı
2. **Araç** : Bir araç hizmetine başvurur, yapı ı ı ı ı
Bu ayrı ı
Farklı ı ı ı ı
Hizmet arayüzü ve araç yapı ı ı ı ı
Hizmet tanı ı ı ı
### İstek Eşleme: Zarf ile Doğrudan İletim
Bir araç hizmetine yapı ı ı ı ı ı
`user` : Çoklu kiracı ı ı ı ı
Yapı ı ı ı `collection` ).
`arguments` : LLM tarafı
Aracı ı ı ı `act.arguments` olarak bir sözlükte (`agent_manager.py:117-154` ) ayrı ı ı ı
### Şema İşleme: Türsüz
İstekler ve yanı ı ı ı ı ı ı ı
### İstemci Arayüzü: Doğrudan Pulsar Konuları
Araç hizmetleri, akı ı ı ı ı ı ı ı ı ı
```json
{
"id": "joke-service",
"request-queue": "non-persistent://tg/request/joke",
"response-queue": "non-persistent://tg/response/joke",
"config-params": [...]
}
```
Bu, hizmetlerin herhangi bir ad alanı ı ı ı ı ı
### Hata Yönetimi: Standart Hata Kuralı
Ara hizmet yanı ı `error` alanı ı ı
```python
@dataclass
class Error:
type: str = ""
message: str = ""
```
Yanı ı ı
Başarı `error` , `None` ise, yanı
Hata: `error` , `type` ve `message` ile doldurulur.
Bu, mevcut hizmet şemaları ı ı `PromptResponse` , `QueryResponse` , `AgentResponse` ).
### İstek/Yanı
İstekler ve yanı `id` kullanı
İstek, özelliklerde `id` içerir: `properties={"id": id}`
Yanı ı `id` 'ı `properties={"id": id}`
Bu, kod tabanı ı ı `agent_service.py` , `llm_service.py` ).
### Akı
Araç hizmetleri, akı ı ı
Aynı `id` 'a sahip çoklu yanı ı
Her yanı `end_of_stream: bool` alanı ı
Son yanı `end_of_stream: True` 'a sahiptir
Bu, `AgentResponse` ve diğer akı ı ı
### Yanı
Tüm mevcut araçlar aynı ı ı **argümanları ı .
| Araç | Yanı
|------|------------------|
| `KnowledgeQueryImpl` | `client.rag()` 'i doğrudan döndürür (dize) |
| `TextCompletionImpl` | `client.question()` 'i doğrudan döndürür (dize) |
| `McpToolImpl` | Bir dize döndürür veya dize değilse `json.dumps(output)` döndürür |
| `StructuredQueryImpl` | Sonucu bir dizeye dönüştürür |
| `PromptImpl` | `client.prompt()` 'i doğrudan döndürür (dize) |
Araç hizmetleri aynı
Hizmet, bir dize yanı ı
Yanı `json.dumps()` aracı ı ı
Tanı ı ı ı ı ı ı
Bu, tanı ı ı ı ı ı ı ı ı
## Yapı ı ı
Yeni bir araç hizmeti eklemek için, iki yapı ı
### 1. Araç Hizmeti Yapı ı ı
`tool-service` yapı ı ı ı ı ı ı ı ı ı
| Alan | Gerekli | Açı
|-------|----------|-------------|
| `id` | Evet | Araç hizmeti için benzersiz tanı ı ı
| `request-queue` | Evet | İstekler için tam Pulsar konusu (örneğin, `non-persistent://tg/request/joke` ) |
| `response-queue` | Evet | Yanı `non-persistent://tg/response/joke` ) |
| `config-params` | Hayı ı ı
Her yapı ı ı
`name` : Parametre adı
`required` : Parametrenin araçlar tarafı ı ı
Örnek:
```json
{
"id": "joke-service",
"request-queue": "non-persistent://tg/request/joke",
"response-queue": "non-persistent://tg/response/joke",
"config-params": [
{"name": "style", "required": false}
]
}
```
### 2. Araç Yapı ı ı
`tool` anahtarı ı ı ı ı ı ı ı
| Alan | Gerekli | Açı
|-------|----------|-------------|
| `type` | Evet | `"tool-service"` olmalı ı
| `name` | Evet | LLM'ye sunulan araç adı
| `description` | Evet | Aracı ı ı ı
| `service` | Evet | Çağrı
| `arguments` | Hayı ı ı
| *(yapı ı | Değişken | Hizmet tarafı ı ı ı
Her argüman aşağı
`name` : Argüman adı
`type` : Veri türü, örneğin `"string"` (gerekli)
`description` : LLM'ye gösterilen açı
Örnek:
```json
{
"type": "tool-service",
"name": "tell-joke",
"description": "Tell a joke on a given topic",
"service": "joke-service",
"style": "pun",
"arguments": [
{
"name": "topic",
"type": "string",
"description": "The topic for the joke (e.g., programming, animals, food)"
}
]
}
```
### Yapı ı ı
Yapı ı ı `tg-put-config-item` 'ı ı
```bash
# Load tool-service config
tg-put-config-item tool-service/joke-service < joke-service.json
# Load tool config
tg-put-config-item tool/tell-joke < tell-joke.json
```
Aracı ı ı ı ı ı ı
## Uygulama Detayları
### Şema
`trustgraph-base/trustgraph/schema/services/tool_service.py` içindeki istek ve yanı
```python
@dataclass
class ToolServiceRequest:
user: str = "" # User context for multi-tenancy
config: str = "" # JSON-encoded config values from tool descriptor
arguments: str = "" # JSON-encoded arguments from LLM
@dataclass
class ToolServiceResponse:
error: Error | None = None
response: str = "" # String response (the observation)
end_of_stream: bool = False
```
### Sunucu Tarafı
`trustgraph-base/trustgraph/base/dynamic_tool_service.py` içindeki temel sı ı
```python
class DynamicToolService(AsyncProcessor):
"""Base class for implementing tool services."""
def __init__ (self, **params):
topic = params.get("topic", default_topic)
# Constructs topics: non-persistent://tg/request/{topic}, non-persistent://tg/response/{topic}
# Sets up Consumer and Producer
async def invoke(self, user, config, arguments):
"""Override this method to implement the tool's logic."""
raise NotImplementedError()
```
### İstemci Tarafı
`trustgraph-flow/trustgraph/agent/react/tools.py` içindeki uygulama:
```python
class ToolServiceImpl:
def __init__ (self, context, request_queue, response_queue, config_values, arguments, processor):
# Uses the provided queue paths directly
# Creates ToolServiceClient on first use
async def invoke(self, **arguments):
client = await self._get_or_create_client()
response = await client.call(user, config_values, arguments)
return response if isinstance(response, str) else json.dumps(response)
```
### Dosyalar
| Dosya | Amaç |
|------|---------|
| `trustgraph-base/trustgraph/schema/services/tool_service.py` | İstek/yanı ı
| `trustgraph-base/trustgraph/base/tool_service_client.py` | Hizmetleri çağı
| `trustgraph-base/trustgraph/base/dynamic_tool_service.py` | Hizmet uygulaması ı ı ı ı
| `trustgraph-flow/trustgraph/agent/react/tools.py` | `ToolServiceImpl` sı ı ı
| `trustgraph-flow/trustgraph/agent/react/service.py` | Yapı ı
### Örnek: Şaka Hizmeti
`trustgraph-flow/trustgraph/tool_service/joke/` 'da bir örnek hizmet:
```python
class Processor(DynamicToolService):
async def invoke(self, user, config, arguments):
style = config.get("style", "pun")
topic = arguments.get("topic", "")
joke = pick_joke(topic, style)
return f"Hey {user}! Here's a {style} for you:\n\n{joke}"
```
Araç hizmeti yapı ı ı
```json
{
"id": "joke-service",
"request-queue": "non-persistent://tg/request/joke",
"response-queue": "non-persistent://tg/response/joke",
"config-params": [{"name": "style", "required": false}]
}
```
Araç yapı ı ı
```json
{
"type": "tool-service",
"name": "tell-joke",
"description": "Tell a joke on a given topic",
"service": "joke-service",
"style": "pun",
"arguments": [
{"name": "topic", "type": "string", "description": "The topic for the joke"}
]
}
```
### Geriye Dönük Uyumluluk
Mevcut, yerleşik araç türleri, herhangi bir değişiklik olmadan çalı
`tool-service` , mevcut türlerin (`knowledge-query` , `mcp-tool` , vb.) yanı ı
## Gelecek Planları
### Kendini Tanı
Gelecekteki bir geliştirmede, hizmetlerin kendi tanı ı ı ı ı
Hizmetler, başlatı ı ı `tool-descriptors` konusuna yayı
Aracı ı
Yapı ı ı ı ı
Bu, ilk uygulamada kapsam dı ı ı
## Referanslar
Mevcut araç uygulaması `trustgraph-flow/trustgraph/agent/react/tools.py`
Araç kaydı `trustgraph-flow/trustgraph/agent/react/service.py:105-214`
Aracı ı `trustgraph-base/trustgraph/schema/services/agent.py`
