101 lines
3.8 KiB
Markdown
101 lines
3.8 KiB
Markdown
# Autonomous Registration & Introspection (v2.0)
|
|
In AgentServer v2.0, tool definition is radically simple: one `@xmlify` dataclass + handler + description. **No manual XSDs, no fragile JSON item mappings, no custom prompt engineering.** The organism auto-generates everything needed for validation, routing, and LLM wiring.<br/>
|
|
Manual XSDs, grammars, and tool descriptions are obsolete. Listeners **autonomously generate** their contracts and metadata at registration time. Introspection is a privileged core facility.
|
|
|
|
## The Developer Experience
|
|
|
|
Declare your payload contract as an `@xmlify` dataclass + a pure handler function that returns raw bytes. Register with a name and description. That's it.
|
|
|
|
```python
|
|
from xmlable import xmlify
|
|
from dataclasses import dataclass
|
|
from xml_pipeline import Listener, bus # bus is the global MessageBus
|
|
|
|
@xmlify
|
|
@dataclass
|
|
class AddPayload:
|
|
"""Addition capability."""
|
|
a: int = 0 # First operand
|
|
b: int = 0 # Second operand
|
|
|
|
def add_handler(payload: AddPayload) -> bytes:
|
|
result = payload.a + payload.b
|
|
return f"<result>{result}</result>".encode("utf-8")
|
|
|
|
# LLM example: multi-payload emission tolerated
|
|
def agent_handler(payload: AgentPayload) -> bytes:
|
|
return b"""
|
|
<thought>Analyzing...</thought>
|
|
<tool-call xmlns="https://xml-pipeline.org/ns/search/v1">
|
|
<query>weather</query>
|
|
</tool-call>
|
|
""".strip()
|
|
|
|
Listener(
|
|
payload_class=AddPayload,
|
|
handler=add_handler,
|
|
name="calculator.add",
|
|
description="Adds two integers and returns their sum." # Mandatory for usable tool prompts
|
|
).register() # ← XSD, example, prompt auto-generated + registered
|
|
```
|
|
|
|
The bus validates input against the XSD, deserializes to the dataclass instance, calls the handler, wraps output bytes in `<dummy></dummy>`, and extracts multiple payloads if emitted.
|
|
|
|
## Autonomous Chain Reaction on Registration
|
|
|
|
1. **XSD Synthesis**
|
|
From `@xmlify` payload_class → generates/caches `schemas/calculator.add/v1.xsd`.
|
|
Namespace: `https://xml-pipeline.org/ns/calculator/v1` (derived or explicit). Root = lowercase class name.
|
|
|
|
2. **Example & Prompt Synthesis**
|
|
From dataclass fields + description:
|
|
```
|
|
Tool: calculator.add
|
|
Description: Adds two integers and returns their sum.
|
|
|
|
Example Input:
|
|
<add>
|
|
<a>40</a>
|
|
<b>2</b>
|
|
</add>
|
|
|
|
Params: a(int) - First operand, b(int) - Second operand
|
|
Returns: Raw XML fragment (e.g., <result>)
|
|
```
|
|
Auto-injected into wired agents' system prompts.
|
|
|
|
3. **Registry Update**
|
|
Bus catalogs by `name` and `(namespace, root)`. Ready for routing + meta queries.
|
|
|
|
## Introspection: Privileged Meta Facility
|
|
|
|
Query the core MessageBus via reserved `https://xml-pipeline.org/ns/meta/v1`:
|
|
|
|
```xml
|
|
<message ...>
|
|
<payload xmlns="https://xml-pipeline.org/ns/meta/v1">
|
|
<request-schema>
|
|
<capability>calculator.add</capability>
|
|
</request-schema>
|
|
</payload>
|
|
</message>
|
|
```
|
|
|
|
Core handler returns XSD bytes, example XML, or prompt fragment.
|
|
Controlled per YAML (`meta.allow_schema_requests: "admin"` etc.). No topology leaks.
|
|
|
|
Other ops: `request-example`, `request-prompt`, `list-capabilities`.
|
|
|
|
## Multi-Handler Organs
|
|
|
|
Need multiple functions in one service? Register separate listeners or subclass Listener for shared state.
|
|
|
|
## Key Advantages
|
|
|
|
- **Zero Drift**: Edit dataclass → restart/hot-reload → XSD/example/prompt regenerate.
|
|
- **Attack-Resistant**: lxml XSD validation → typed instance → handler.
|
|
- **LLM-Tolerant**: Raw bytes output → dummy extraction supports multi-payload and dirty streams.
|
|
- **Sovereign Wiring**: YAML agents get live prompt fragments at startup.
|
|
- **Discoverable**: Namespaces served live at https://xml-pipeline.org/ns/... for tools and federation.
|
|
|
|
*The tool declares its contract and purpose. The organism enforces and describes it exactly.*
|