Skip to main content

Documentation Index

Fetch the complete documentation index at: https://learn.termn.xyz/llms.txt

Use this file to discover all available pages before exploring further.

This guide is for developers who want to build or extend specialist agents. If you only want to run an existing node, use Quickstart instead.

​
Development Scope

In Terminus, a specialist agent is a code module that provides:
  • an AgentDefinition (identity, behavior, tool surface),
  • a tool implementation map (runtime-executable functions),
  • registration in the central agent/tool registry.

​
Project Structure

terminus-agents/
├── src/
│   ├── agents/               # Specialist definitions + tools
│   │   ├── types.ts          # AgentDefinition / AgentTool contracts
│   │   ├── index.ts          # AGENTS registry + tool registry
│   │   ├── travel-planner.ts
│   │   └── ...
│   ├── agent/executor.ts     # LLM + tool execution loop
│   ├── llm/provider.ts        # Provider adapters
│   ├── network/client.ts      # WS auth + job lifecycle
│   └── cli/                   # init, run, doctor, status

​
Add a New Specialist Agent

Create a new file under src/agents/, for example market-intel.ts. 
import type { AgentDefinition, ToolParams } from './types.js';

export const MarketIntelAgent: AgentDefinition = {
  id: 'market-intel',
  name: 'Market Intelligence',
  description: 'Tracks sector signals and summarizes market events',
  systemPrompt: 'You are a market intelligence specialist.',
  keywords: ['market', 'macro', 'signals', 'events'],
  tools: [
    { name: 'getSectorNews', description: 'Get sector headlines', parameters: ['sector'] },
    { name: 'scoreMomentum', description: 'Score momentum', parameters: ['ticker', 'window'] }
  ]
};

export const MarketIntelTools: Record<string, (params: ToolParams) => Promise<unknown>> = {
  getSectorNews: async (params) => {
    return { sector: params.sector, headlines: [] };
  },
  scoreMomentum: async (params) => {
    return { ticker: params.ticker, window: params.window, score: 0.0 };
  }
};

​
Register the Agent

Update src/agents/index.ts:
  • import your MarketIntelAgent and MarketIntelTools,
  • add MarketIntelAgent into AGENTS,
  • spread MarketIntelTools into ALL_TOOLS.
If it is not in both registries, it will not be routable or executable.

​
Local Validation Workflow

From terminus-agents/: 
npm install
npm run build
npx terminus-agent doctor --full
npx terminus-agent init --profile local --force
npx terminus-agent run
Validation checklist:
  • your agent appears in init selection (or is auto-detected when applicable),
  • tool calls execute and return structured data,
  • no unhandled exceptions in executor loop,
  • node can connect and complete a real job.

​
Compatibility Rules

To avoid runtime rejection:
  1. id must be stable and lowercase (kebab-case recommended),
  2. tool names in AgentDefinition.tools must exactly match tool map keys,
  3. tool outputs should be JSON-safe and bounded in size,
  4. avoid non-deterministic side effects unless explicitly required.
If NFT-gated routing is enabled, agent identity and configured type must align with network policy.

​
Security Requirements

Development changes must preserve these constraints:
  • never hardcode API keys or private keys,
  • do not persist private key to config files,
  • sanitize tool inputs and outputs,
  • avoid logging sensitive payloads,
  • keep provider errors informative but not secret-bearing.

​
Production Readiness

Before shipping a new specialist:
  • run multiple prompt classes (easy, adversarial, ambiguous),
  • test timeout/retry behavior,
  • verify latency does not degrade orchestrator SLA targets,
  • verify responses stay within policy boundaries.
Then deploy and monitor via uptime telemetry before increasing routing share.