Skip to main content
Agents are purpose-driven compositions that bundle tools from multiple providers into a single, testable unit. Where individual schemas wrap a single API, agents combine the right tools for a specific task — for example, a crypto research agent might pull from CoinGecko, Etherscan, and DeFi Llama simultaneously.
This page covers the practical guide for building agents. For the full specification and validation rules, see Agents Specification.

​
Agent Architecture

An agent manifest (agent.mjs) declares everything the agent needs: which tools to use, which model to target, how the agent should behave, and how to verify it works.

​
Agent Manifest

Each agent is defined by an agent.mjs file with export const main: 
export const main = {
    name: 'crypto-research',
    version: 'flowmcp/3.0.0',
    description: 'Cross-provider crypto analysis agent',
    model: 'anthropic/claude-sonnet-4-5-20250929',
    systemPrompt: 'You are a crypto research agent...',
    tools: [
        'coingecko/tool/simplePrice',
        'coingecko/tool/coinMarkets',
        'etherscan/tool/getContractAbi',
        'defillama/tool/getProtocolTvl'
    ],
    prompts: {
        'research-guide': { file: './prompts/research-guide.mjs' }
    },
    skills: {
        'token-analysis': { file: './skills/token-analysis.mjs' }
    },
    resources: {},
    tests: [
        {
            _description: 'Token price lookup',
            input: 'What is the current price of Bitcoin?',
            expectedTools: ['coingecko/tool/simplePrice'],
            expectedContent: ['bitcoin', 'price', 'USD']
        },
        {
            _description: 'Contract analysis',
            input: 'Analyze the USDC contract on Ethereum',
            expectedTools: ['etherscan/tool/getContractAbi'],
            expectedContent: ['USDC', 'contract']
        },
        {
            _description: 'DeFi protocol TVL',
            input: 'What is the TVL of Aave?',
            expectedTools: ['defillama/tool/getProtocolTvl'],
            expectedContent: ['Aave', 'TVL']
        }
    ],
    sharedLists: ['evmChains']
}

​
Three Content Layers

Agents separate concerns into three distinct layers that shape how the agent thinks, understands, and acts.

Persona

Field: systemPromptWho the agent IS. Defines personality, expertise, and behavioral boundaries.“You are a crypto research analyst who provides data-driven insights…”

Explanations

Field: promptsHow tools work. Provides context about data formats, API quirks, and interpretation guidance.“CoinGecko returns prices in the base currency. Always convert to USD for comparison…”

Instructions

Field: skillsStep-by-step workflows. Guides the agent through multi-tool sequences for complex tasks.“Step 1: Search token by name. Step 2: Fetch OHLCV data. Step 3: Calculate metrics…”
LayerFieldPurposeExample
PersonasystemPromptWho the agent IS”You are a crypto research analyst…”
ExplanationspromptsHow tools work”CoinGecko returns prices in…”
InstructionsskillsStep-by-step workflows”Step 1: Search token. Step 2: Fetch OHLCV…”

​
Tool Cherry-Picking

Tools use the full ID format: namespace/type/name. This lets you pick exactly the tools an agent needs from any provider — no need to include an entire provider’s toolkit. 
coingecko/tool/simplePrice        # Specific tool from CoinGecko
coingecko/tool/coinMarkets        # Another tool from the same provider
etherscan/tool/getContractAbi     # Tool from a different provider
defillama/tool/getProtocolTvl     # Yet another provider
Select only the tools that serve the agent’s purpose. A crypto research agent does not need every CoinGecko endpoint — just simplePrice and coinMarkets might be enough.

​
Agent Tests

Every agent must have a minimum of 3 tests. This ensures the agent’s tool selection and output quality are verified across different usage scenarios.
Tests validate agent behavior at three levels:
LevelFieldWhat it checksDeterministic?
Tool UsageexpectedToolsDid the agent call the right tools?Yes
ContentexpectedContentDoes the output contain expected keywords?Partial
QualityManual reviewIs the output coherent and useful?No
Each test case defines an input prompt, the tools the agent should reach for, and keywords the response should contain: 
{
    _description: 'Token price lookup',
    input: 'What is the current price of Bitcoin?',
    expectedTools: ['coingecko/tool/simplePrice'],
    expectedContent: ['bitcoin', 'price', 'USD']
}
  • expectedTools is deterministic — the agent must call exactly these tools for the given input.
  • expectedContent is a partial check — the response should contain these strings, but additional content is fine.
  • Quality review is manual — read the output and verify it makes sense as a coherent answer.

​
Directory Structure

Each agent lives in its own directory within the catalog’s agents/ folder: 
agents/crypto-research/
├── agent.mjs              # Manifest (export const main)
├── prompts/
│   └── research-guide.mjs
├── skills/
│   └── token-analysis.mjs
└── resources/             # Optional own databases
The agent.mjs file is the entry point. Prompts and skills are referenced by relative path from the manifest and follow the same format as schema-level skills and prompt architecture.