Skip to main content
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.