trustgraph/docs/tech-specs/tool-services.sw.md

layout	title	parent
default	Huduma za Zana: Zana za Wakala Zinazoweza Kuunganishwa Kwenye Mfumo	Swahili (Beta)

Huduma za Zana: Zana za Wakala Zinazoweza Kuunganishwa Kwenye Mfumo

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.

Hali

Imetekelezwa

Muhtasari

Maelezo haya yanafafanua mfumo wa zana za wakala ambazo zinaweza kuunganishwa kwenye mfumo, zinazojulikana kama "huduma za zana". Tofauti na aina za zana zilizojumuishwa awali (KnowledgeQueryImpl, McpToolImpl, n.k.), huduma za zana huruhusu zana mpya kuletwa kwa:

1. Kuanzisha huduma mpya iliyojengwa kwenye Pulsar
2. Kuongeza maelezo ya usanidi ambayo huambia wakala jinsi ya kuiita

Hii inaruhusu uboreshaji bila kubadilisha mfumo msingi wa wakala.

Dhana

Neno	Ufafanuzi
Zana Iliyojumuishwa	Aina za zana zilizopo zilizo na matumizi yaliyopangwa mapema katika tools.py
Huduma ya Zana	Huduma ya Pulsar ambayo inaweza kuita kama zana ya wakala, iliyoainishwa na maelezo ya huduma
Zana	Toleo lililosanidiwa ambalo linarejelea huduma ya zana, lililowezeshwa kwa wakala/LLM

Hii ni mfumo wa tabaka mbili, sawa na zana za MCP: MCP: Seva ya MCP inaainisha kiolesura cha zana → Usanidi wa zana huirejelea Huduma za Zana: Huduma ya zana inaainisha kiolesura cha Pulsar → Usanidi wa zana huirejelea

Asili: Zana Zilizopo

Utendaji wa Zana Iliyojumuishwa

Zana kwa sasa zinafafanuliwa katika trustgraph-flow/trustgraph/agent/react/tools.py na matumizi yaliyopangwa:

class KnowledgeQueryImpl:
    async def invoke(self, question):
        client = self.context("graph-rag-request")
        return await client.rag(question, self.collection)

Kila aina ya zana: Ina huduma ya Pulsar iliyopangwa tayari ambayo inaitumia (k.m., graph-rag-request) Inajua njia sahihi ya kuita kwenye mteja (k.m., client.rag()) Ina vigezo vilivyopangwa ambavyo vimefafuliwa katika utekelezaji

Usajili wa Zana (service.py:105-214)

Zana huzamilishwa kutoka kwa usanidi na sehemu ya type ambayo inaelekeza kwenye utekelezaji:

if impl_id == "knowledge-query":
    impl = functools.partial(KnowledgeQueryImpl, collection=data.get("collection"))
elif impl_id == "text-completion":
    impl = TextCompletionImpl
# ... etc

Usanifu

Mfumo wa Tabaka Mbili

Tabaka la 1: Kisajili cha Huduma ya Zana

Huduma ya zana inaelezea kiolesura cha huduma ya Pulsar. Inaangazia: Mizinga ya Pulsar kwa ombi/jibu Vigezo vya usanidi ambavyo vinahitajika na zana zinazotumia huduma hiyo

{
  "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}
  ]
}

Huduma ya zana ambayo haihitaji vigezo vya usanidi:

{
  "id": "calculator",
  "request-queue": "non-persistent://tg/request/calc",
  "response-queue": "non-persistent://tg/response/calc",
  "config-params": []
}

Kategoria ya 2: Kisajili cha Zana

Zana inarejelea huduma ya zana na hutoa: Maelezo ya vigezo ya usanidi (yakinayo na mahitaji ya huduma) Meta-data ya zana kwa wakala (jina, maelezo) Ufafanuzi wa hoja kwa mfumo wa lugha (LLM)

{
  "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"
    }
  ]
}

Zana nyingi zinaweza kurejelea huduma moja kwa usanidi tofauti:

{
  "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"
    }
  ]
}

Muundo wa Ombi

Wakati zana inaitwa, ombi kwa huduma ya zana linajumuisha: user: Kutoka ombi la wakala (utumiaji wa pamoja) config: Maelezo ya usanidi yaliyokandwa katika umbizo la JSON kutoka kwa maelezo ya zana arguments: Majadilisho yaliyokandwa katika umbizo la JSON kutoka kwa mfumo wa lugha kubwa (LLM)

{
  "user": "alice",
  "config": "{\"collection\": \"customers\"}",
  "arguments": "{\"question\": \"What are the top customer complaints?\"}"
}

Huduma ya zana hupokea haya kama dictionaries yaliyochanganishwa katika njia ya invoke.

Utendakazi wa Huduma ya Zana ya Jumla

Darasa la ToolServiceImpl huita huduma za zana kulingana na usanidi:

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)

Maamuzi ya Ubunifu

Mfumo wa Uwekaji wa Tabaka Mbili

Huduma za zana zinafuata mfumo wa tabaka mbili, sawa na zana za MCP:

1. Huduma ya Zana: Inaelezea kiolesura cha huduma ya Pulsar (mada, vigezo muhimu vya usanidi)
2. Zana: Inarejelea huduma ya zana, hutoa maadili ya usanidi, inaelezea hoja za LLM

Tofauti hii inaruhusu: Huduma moja ya zana kutumika na zana nyingi zenye usanidi tofauti Tofauti wazi kati ya kiolesura cha huduma na usanidi wa zana Ujuzi wa matumizi wa maelezo ya huduma

Ramani ya Ombi: Kupitisha na Kifurushi

Ombi kwa huduma ya zana ni kifurushi kilicho na muundo, kinachojumuisha: user: Inasambazwa kutoka ombi la wakala kwa ajili ya utumiaji wa pamoja Maadili ya usanidi: Kutoka kwa maelezo ya zana (k.m., collection) arguments: Hoja zilizotolewa na LLM, zinazopitishwa kama kamusi

Kidhibiti cha wakala huchanganua jibu la LLM kuwa act.arguments kama kamusi (agent_manager.py:117-154). Kamusi hii inajumuishwa katika kifurushi cha ombi.

Usimamizi wa Mpango: Bila Aina

Maombi na majibu hutumia kamusi zisizo na aina. Hakuna uthibitishaji wa mpango katika ngazi ya wakala - huduma ya zana inawajibika kwa uthibitishaji wa pembejeo zake. Hii hutoa uwezo mkubwa wa kufafanua huduma mpya.

Kiolesura cha Mteja: Mada za Moja kwa Moja za Pulsar

Huduma za zana hutumia mada za moja kwa moja za Pulsar bila kuhitaji usanidi wa mtiririko. Maelezo ya huduma-ya-zana yanaelezea majina kamili ya folyo:

{
  "id": "joke-service",
  "request-queue": "non-persistent://tg/request/joke",
  "response-queue": "non-persistent://tg/response/joke",
  "config-params": [...]
}

Hii inaruhusu huduma kuwa zimepakwa kwenye nafasi yoyote.

Usimamizi wa Makosa: Mfumo wa Makosa wa Kawaida

Majibu ya huduma ya zana yanafuata mfumo wa sasa wa muundo na sehemu ya error:

@dataclass
class Error:
    type: str = ""
    message: str = ""

Muundo wa majibu: Mafanikio: error ni None, majibu yana matokeo Kosa: error imejaa na type na message

Hii inafanana na muundo uliotumika katika huduma zingine (e.g., PromptResponse, QueryResponse, AgentResponse).

Uhusiano wa Ombi/Jibu

Maombi na majibu yanahusishwa kwa kutumia id katika vipengele vya ujumbe wa Pulsar:

Ombi linajumuisha id katika vipengele: properties={"id": id} Majibu (mengi) yanajumuisha id sawa: properties={"id": id}

Hii inafuata muundo uliopo katika codebase (e.g., agent_service.py, llm_service.py).

Usaidizi wa Uhamaji (Streaming)

Huduma za zana zinaweza kurejesha majibu ya uhamaji:

Ujumbe mwingi wa majibu wenye id sawa katika vipengele Kila jibu linajumuisha end_of_stream: bool Jibu la mwisho lina end_of_stream: True

Hii inafanana na muundo uliotumika katika AgentResponse na huduma zingine za uhamaji.

Usimamizi wa Majibu: Kurudisha Kamba (String)

Zana zote zilizopo zinafuata muundo huo: kupokea hoja kama orodha, kurejesha matokeo kama kamba.

Zana	Usimamizi wa Majibu
KnowledgeQueryImpl	Inarejea client.rag() moja kwa moja (kamba)
TextCompletionImpl	Inarejea client.question() moja kwa moja (kamba)
McpToolImpl	Inarejea kamba, au json.dumps(output) ikiwa si kamba
StructuredQueryImpl	Inaweka matokeo katika kamba
PromptImpl	Inarejea client.prompt() moja kwa moja (kamba)

Huduma za zana zinafuata mkataba huo: Huduma inarejea jibu la kamba (matokeo) Ikiwa jibu si kamba, linabadilishwa kupitia json.dumps() Hakuna usanidi wa uondoaji unaohitajika katika maelezo

Hii huweka maelezo kuwa rahisi na kuweka jukumu kwa huduma kurejesha jibu la maandishi linalofaa kwa wakala.

Mwongozo wa Usanidi

Ili kuongeza huduma mpya ya zana, vipengele viwili vya usanidi vinahitajika:

1. Usanidi wa Huduma ya Zana

Inahifadhiwa chini ya ufunguo wa usanidi tool-service. Inaelezea folyo za Pulsar na vigezo vinavyopatikana vya usanidi.

Uwanja	Inahitajika	Maelezo
id	Ndiyo	Kitambulisho cha kipekee kwa huduma ya zana
request-queue	Ndiyo	Mada kamili ya Pulsar kwa maombi (e.g., non-persistent://tg/request/joke)
response-queue	Ndiyo	Mada kamili ya Pulsar kwa majibu (e.g., non-persistent://tg/response/joke)
config-params	Hapana	Safu ya vigezo vya usanidi ambavyo huduma inakubali

Kila kiparamu cha usanidi kinaweza kuainisha: name: Jina la kiparamu (inahitajika) required: Ikiwa kiparamu lazima kipewe na zana (cha kawaida: bandia)

Mfano:

{
  "id": "joke-service",
  "request-queue": "non-persistent://tg/request/joke",
  "response-queue": "non-persistent://tg/response/joke",
  "config-params": [
    {"name": "style", "required": false}
  ]
}

2. Usanidi wa Zana

Hifadhiwa chini ya ufunguo wa tool. Inaelezea zana ambayo wakala anaweza kutumia.

Sehemu	Inahitajika	Maelezo
type	Ndiyo	Lazima iwe "tool-service"
name	Ndiyo	Jina la zana linaloonyeshwa kwa LLM
description	Ndiyo	Maelezo ya kile ambacho zana inafanya (yanaonyeshwa kwa LLM)
service	Ndiyo	Kitambulisho cha huduma ya zana inayotumiwa
arguments	Hapana	Safu ya maelezo ya hoja kwa ajili ya LLM
(vigezo vya usanidi)	Hubadilika	Vigezo vyovyote vya usanidi vilivyobainishwa na huduma

Kila hoja inaweza kubainisha: name: Jina la hoja (inahitajika) type: Aina ya data, kwa mfano, "string" (inahitajika) description: Maelezo yanayoonyeshwa kwa LLM (inahitajika)

Mfano:

{
  "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)"
    }
  ]
}

Upakiaji wa Mipangilio

Tumia tg-put-config-item ili kupakia mipangilio:

# 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

Wakala-mtawala lazima uanzishwe tena ili kuchukua usanidi mpya.

Maelezo ya Utendaji

Mpango

Aina za ombi na majibu katika trustgraph-base/trustgraph/schema/services/tool_service.py:

@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

Upande wa Server: Huduma ya DynamicToolService

Darasa la msingi katika trustgraph-base/trustgraph/base/dynamic_tool_service.py:

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()

Upande wa Mteja: Huduma ya ToolServiceImpl

Utendaji katika trustgraph-flow/trustgraph/agent/react/tools.py:

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)

Faili

Faili	Madhumuni
trustgraph-base/trustgraph/schema/services/tool_service.py	Mifumo ya ombi/jibu
trustgraph-base/trustgraph/base/tool_service_client.py	Mteja wa kutumia huduma
trustgraph-base/trustgraph/base/dynamic_tool_service.py	Darasa la msingi kwa utekelezaji wa huduma
trustgraph-flow/trustgraph/agent/react/tools.py	Darasa la ToolServiceImpl
trustgraph-flow/trustgraph/agent/react/service.py	Kupakia usanidi

Mifano: Huduma ya Utani

Mfano wa huduma katika trustgraph-flow/trustgraph/tool_service/joke/:

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}"

Usanidi wa huduma za zana:

{
  "id": "joke-service",
  "request-queue": "non-persistent://tg/request/joke",
  "response-queue": "non-persistent://tg/response/joke",
  "config-params": [{"name": "style", "required": false}]
}

Usanidi wa zana:

{
  "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"}
  ]
}

Ulinganishi na Matoleo ya Zamani

Aina za zana zilizopo zilizojumuishwa zinaendelea kufanya kazi bila kubadilishwa. tool-service ni aina mpya ya zana pamoja na aina zilizopo (knowledge-query, mcp-tool, n.k.).

Mambo ya Kuzingatia Baadaye

Huduma Zinajitangaza Zenyewe

Uboreshaji wa siku zijazo unaweza kuruhusu huduma kuchapisha maelezo yao wenyewe:

Huduma huchapisha kwenye mada iliyojulikana ya tool-descriptors wakati wa kuanza. Wakala husajili na kusajili zana kwa njia ya moja kwa moja. Inaruhusu uunganishaji halisi wa "plug-and-play" bila mabadiliko ya usanidi.

Hii ni nje ya upeo wa utekelezaji wa awali.

Marejeleo

Utaratibu wa sasa wa zana: trustgraph-flow/trustgraph/agent/react/tools.py Usajili wa zana: trustgraph-flow/trustgraph/agent/react/service.py:105-214 Schemas za wakala: trustgraph-base/trustgraph/schema/services/agent.py