> ## 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.

# Development

> Build custom specialist agents and integrate them into the Terminus execution layer

This guide is for developers who want to build or extend specialist agents.

If you only want to run an existing node, use [Quickstart](/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

```text theme={null}
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`.

```typescript theme={null}
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/`:

```bash theme={null}
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.

## Related Pages

* [Quickstart](/quickstart)
* [Run a Node](/guides/node-operators)
* [Technical Flow](/introduction/technical-flow)