Building Custom Agents with Domain Tool Schemas: Step-by-Step Engineering Guide

# Building Custom Agents with Domain Tool Schemas: Step-by-Step Engineering Guide

While Kyronix provides built-in reference agents (`coding`, `research`, `database`, and `sales`), production application requirements vary widely. You might need an AI agent that executes analytical SQL queries against an internal database pool, triggers GitHub Actions workflows, or interacts with custom internal REST APIs.

**Kyronix Custom Agents** enable developers to define custom AI personas with dynamic tool parameter schemas in the Kyronix Console and execute local tool handlers via `@kyronixai/executer`.

---

System Architecture: Custom Tool Schema Flow

11. Define Custom Agent      2. LLM Prompt Injection       3. Local Execution Handler
2 ┌────────────────────┐      ┌──────────────────────┐      ┌─────────────────────────┐
3 │ Kyronix Console    │      │ Kyronix Cloud API    │      │ @kyronixai/executer     │
4 │  ├── Tool: sql     │─────►│  ├── Injects Tool    │─────►│  ├── executor.register()│
5 │  └── Params: query │      │  └── Generates KML   │      │  └── Runs local DB pool │
6 └────────────────────┘      └──────────────────────┘      └─────────────────────────┘

---

Step 1: Register Your Custom Agent in the Kyronix Console

1. Navigate to your [Kyronix Dashboard](/dashboard) and click on **My Agents**. 2. Click **+ Create Custom Agent**. 3. Fill out agent metadata: - **Name**: `Analytics Engineer` - **Description**: `Executes analytical SQL queries on Postgres and summarizes revenue reports.` 4. Define Custom Tool Schemas: - **Tool Name**: `execute_sql` - **Description**: `Executes a SQL query against analytical database.` - **Parameters**: `sql_query, limit` 5. Click **Save Agent**. Your Custom Agent will be assigned a unique hashed **Agent ID** (`kyr_agent_8b5b6ad518947f52745da13120938bd7`).

---

Step 2: Implement Local Tool Handlers (`@kyronixai/executer`)

On your workstation or server daemon process, initialize `KyronixExecuter` and register the custom tool handler for `execute_sql`:

1// client-daemon.ts
2import { KyronixExecuter } from '@kyronixai/executer';

const dbPool = new Pool({ connectionString: process.env.DATABASE_URL });

// 1. Initialize local executor connected to WebSocket tunnel const executor = new KyronixExecuter({ wsUrl: 'ws://localhost:8080/ws' });

// 2. Register local tool execution handler for 'execute_sql' executor.register('execute_sql', async (args) => { const { sql_query, limit = 10 } = args; console.log(`[DB EXECUTOR] Executing: ${sql_query} (limit: ${limit})`);

try { const client = await dbPool.connect(); const result = await client.query(`${sql_query} LIMIT ${limit}`); client.release();

return { success: true, rowCount: result.rowCount, rows: result.rows }; } catch (error: any) { return { success: false, error: error.message }; } });

console.log('Custom Agent local executor listening over WebSocket tunnel...'); ```

---

Step 3: Execute Custom Agent via `@kyronixai/runtime`

From your backend runtime application, execute your Custom Agent using `runCustomAgent`:

1// backend-server.ts
2import express from 'express';
3import { Kyronix } from '@kyronixai/runtime';

const app = express(); app.use(express.json());

const ws = new WebSocket('ws://localhost:8080/ws'); const kyronix = new Kyronix({ apiKey: process.env.KYRONIX_API_KEY!, projectId: process.env.KYRONIX_PROJECT_ID!, ws });

app.post('/api/run-analytics', async (req, res) => { const { userPrompt } = req.body;

try { // 1. Single-shot Custom Agent execution const runResult = await kyronix.runCustomAgent({ agentId: 'kyr_agent_8b5b6ad518947f52745da13120938bd7', input: userPrompt });

console.log('LLM KML Response:', runResult.response);

// 2. Dispatch KML execution over WebSocket tunnel const outcomes = await kyronix.executeKmlOverWs(runResult.response);

res.json({ success: true, kmlPlan: runResult.response, outcomes }); } catch (error: any) { res.status(500).json({ error: error.message }); } });

app.listen(3000, () => console.log('Analytics Server running on port 3000')); ```

---

Step 4: Multi-Turn Conversational Memory with Custom Agents

For complex workflows where follow-up prompts are required, pass `customAgentId` into session turns:

1

// Turn 1: Execute initial custom query const turn1 = await session.send('Fetch total signups grouped by country', { customAgentId: 'kyr_agent_8b5b6ad518947f52745da13120938bd7' }); const outcomes1 = await kyronix.executeKmlOverWs(turn1.response);

// Turn 2: Follow-up question inherits previous conversation memory const turn2 = await session.send('Now calculate the conversion rate for those countries'); const outcomes2 = await kyronix.executeKmlOverWs(turn2.response); ```

---

Summary

With Kyronix Custom Agents, you can easily build **tailored domain AI workforce tools** with custom parameters while retaining local execution safety and zero-firewall WebSocket dispatch.