Skip to main content
Agents are purpose-driven tool compositions that bundle tools from multiple providers for a specific task. They replace the simpler “Groups” concept from v2.0.0 with full manifest definitions including model binding, system prompts, and testable behavior.
This page documents the v3.0.0 Agent system. For the full specification, see 06-agents.md.

​
Agent vs Provider

AspectProviderAgent
ScopeSingle API sourceMultiple providers combined
PromptsModel-neutralModel-specific with testedWith
ModelNone (any model can use)Bound to specific LLM
PurposeExpose dataAccomplish tasks
TestsPer-tool deterministicTool selection + content assertions

​
Manifest Format

Each agent is defined by a manifest.json file in the catalog’s agents/ directory. 
{
    "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 analyst...",
    "tools": [
        "coingecko-com/tool/simplePrice",
        "etherscan/tool/getContractAbi",
        "defillama/tool/getProtocolTvl"
    ],
    "tests": [
        {
            "_description": "Basic token lookup",
            "input": "What is the current price of Ethereum?",
            "expectedTools": ["coingecko-com/tool/simplePrice"],
            "expectedContent": ["price", "USD"]
        }
    ]
}

​
Required Fields

FieldTypeDescription
namestringAgent name (kebab-case)
descriptionstringHuman-readable purpose
versionstringMust be "flowmcp/3.0.0"
modelstringTarget LLM (OpenRouter format with /)
systemPromptstringAgent persona and behavioral instructions
toolsstring[]Tool IDs in namespace/type/name format
testsarrayMinimum 3 test cases

​
Optional Fields

FieldTypeDefaultDescription
maxRoundsnumber10Maximum LLM interaction rounds
maxTokensnumber4096Maximum tokens per response
promptsstring[][]Relative paths to prompt files
sharedListsstring[][]Required shared list names
inputSchemaobject—JSON Schema for agent input

​
Agent Tests

Each agent must have at least 3 tests. Tests validate tool selection (deterministic) and optionally content assertions. 
{
    "_description": "Cross-provider DeFi analysis",
    "input": "Compare TVL of Aave on Ethereum vs Arbitrum",
    "expectedTools": ["defillama/tool/getProtocolTvl"],
    "expectedContent": ["TVL", "Ethereum", "Arbitrum"]
}
  • expectedTools — Deterministic: the agent must call exactly these tools
  • expectedContent — Partial: the response should contain these strings

​
Validation Rules

CodeRule
AGT001manifest.json must exist and be valid JSON
AGT002name must be kebab-case
AGT003version must be "flowmcp/3.0.0"
AGT004model must use OpenRouter format (contains /)
AGT005tools[] must not be empty
AGT006Each tool ID must be valid (namespace/type/name)
AGT007tests[] must have minimum 3 entries
AGT008Each test must have _description, input, expectedTools

​
CLI Commands

# Import an agent from a catalog
flowmcp import-agent crypto-research

# The agent's tools are activated locally
flowmcp list