Agent Toolkits

Toolkits are shareable collections of tools that extend AI agent capabilities. They provide a standardized way to connect agents to external APIs, handle authentication, and share integrations with the community.

Architecture

Toolkits follow a three-layer architecture:

How It Works

1. Creator builds a toolkit with credential requirements and tools
2. User installs the toolkit to their account
3. User configures credentials (maps their API keys/secrets)
4. Agent can now invoke the toolkit's tools with full authentication

Creating a Toolkit

Define your toolkit with metadata and credential requirements:

// Toolkit definition
{
  "name": "weather-api",
  "title": "Weather API",
  "description": "Get weather data for any location worldwide",
  "category": "api-integration",
  "tags": ["weather", "geo", "forecast"],
  "credential_requirements": [
    {
      "key_name": "WEATHER_API_KEY",
      "label": "Weather API Key",
      "credential_type": "api_key",
      "is_required": true,
      "description": "Your OpenWeatherMap API key"
    }
  ]
}

Toolkit Properties

Credential Types

Toolkits support multiple authentication methods:

Credential Definition

{
  "key_name": "API_KEY",           // Unique key identifier
  "label": "Your API Key",         // User-friendly label
  "credential_type": "api_key",    // Type of credential
  "is_required": true,             // Whether required
  "description": "Get your key from...",
  "placeholder": "sk_live_...",    // Input placeholder
  "validation_pattern": "^sk_"     // Optional regex validation
}

OAuth Configuration

For OAuth credentials, provide an oauth_config object:

{
  "key_name": "ACCESS_TOKEN",
  "label": "OAuth Access Token",
  "credential_type": "oauth",
  "is_required": true,
  "oauth_config": {
    "authorization_url": "https://api.example.com/oauth/authorize",
    "token_endpoint": "https://api.example.com/oauth/token",
    "scopes": ["read", "write"],
    "client_id_credential_key": "APP_KEY",
    "client_secret_credential_key": "APP_SECRET",
    "pkce_enabled": true
  }
}

OAuth Config Properties

Complete OAuth Example

// OAuth toolkit with client credentials + access token
{
  "name": "schwab-api",
  "title": "Schwab Trading API",
  "description": "Trade stocks via Schwab API",
  "credential_requirements": [
    {
      "key_name": "SCHWAB_APP_KEY",
      "label": "Schwab App Key (Client ID)",
      "credential_type": "api_key",
      "is_required": true
    },
    {
      "key_name": "SCHWAB_APP_SECRET",
      "label": "Schwab App Secret",
      "credential_type": "api_key",
      "is_required": true
    },
    {
      "key_name": "SCHWAB_ACCESS_TOKEN",
      "label": "OAuth Access Token",
      "credential_type": "oauth",
      "is_required": true,
      "oauth_config": {
        "authorization_url": "https://api.schwabapi.com/v1/oauth/authorize",
        "token_endpoint": "https://api.schwabapi.com/v1/oauth/token",
        "scopes": ["api"],
        "client_id_credential_key": "SCHWAB_APP_KEY",
        "client_secret_credential_key": "SCHWAB_APP_SECRET",
        "pkce_enabled": true
      }
    }
  ]
}

Creating Tools

Tools are the individual endpoints agents can invoke. Each tool defines an HTTP request or workflow wrapper.

HTTP Tool

{
  "name": "get-weather",
  "title": "Get Weather",
  "description": "Get current weather for a location",
  "tool_type": "http",
  "endpoint_config": {
    "method": "GET",
    "url": "https://api.openweathermap.org/data/2.5/weather"
  },
  "input_schema": {
    "type": "object",
    "properties": {
      "city": {
        "type": "string",
        "description": "City name"
      },
      "units": {
        "type": "string",
        "enum": ["metric", "imperial"],
        "default": "metric"
      }
    },
    "required": ["city"]
  },
  "credential_keys": ["WEATHER_API_KEY"]
}

Workflow Tool

Wrap a FlowDot workflow as a toolkit tool:

{
  "name": "analyze-sentiment",
  "title": "Analyze Sentiment",
  "description": "Analyze text sentiment using AI workflow",
  "tool_type": "workflow",
  "workflow_hash": "abc123xyz",
  "input_schema": {
    "type": "object",
    "properties": {
      "text": {
        "type": "string",
        "description": "Text to analyze"
      }
    },
    "required": ["text"]
  }
}

Input Schema

Use JSON Schema to define tool inputs:

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query"
    },
    "limit": {
      "type": "number",
      "description": "Max results",
      "default": 10,
      "minimum": 1,
      "maximum": 100
    },
    "filters": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Filter tags"
    }
  },
  "required": ["query"]
}

Using Toolkits

Once a toolkit is created, users can install and use it:

1. Install the Toolkit

Add a toolkit to your account from the marketplace or by ID:

// Via MCP
mcp__flowdot__install_toolkit({ toolkit_id: "abc123" })

2. Configure Credentials

Map the toolkit's credential requirements to your stored secrets:

// Map your credentials
mcp__flowdot__update_toolkit_installation({
  installation_id: "inst_123",
  credential_mapping: {
    "WEATHER_API_KEY": "my-openweather-key"
  }
})

3. Invoke Tools

Call any tool from the installed toolkit:

// Invoke a tool
mcp__flowdot__invoke_toolkit_tool({
  installation_id: "inst_123",
  tool_name: "get-weather",
  inputs: { city: "San Francisco", units: "imperial" }
})

4. Check Credentials Status

Verify all required credentials are configured:

// Check credential status
mcp__flowdot__check_toolkit_credentials({
  installation_id: "inst_123"
})

MCP Integration

The FlowDot MCP server provides 15+ tools for toolkit management:

Example: Building a Toolkit via MCP

// 1. Create the toolkit
const toolkit = await mcp__flowdot__create_agent_toolkit({
  name: "github-api",
  title: "GitHub API",
  description: "Interact with GitHub repositories",
  category: "api-integration",
  credential_requirements: [{
    key_name: "GITHUB_TOKEN",
    label: "GitHub Personal Access Token",
    credential_type: "bearer",
    is_required: true
  }]
});

// 2. Add a tool
await mcp__flowdot__create_toolkit_tool({
  toolkit_id: toolkit.hash,
  name: "list-repos",
  title: "List Repositories",
  description: "List user's GitHub repositories",
  tool_type: "http",
  endpoint_config: {
    method: "GET",
    url: "https://api.github.com/user/repos"
  },
  input_schema: {
    type: "object",
    properties: {
      per_page: { type: "number", default: 30 }
    }
  },
  credential_keys: ["GITHUB_TOKEN"]
});

// 3. Make it public
await mcp__flowdot__toggle_toolkit_visibility({
  toolkit_id: toolkit.hash,
  visibility: "public"
});

Best Practices

• Clear descriptions: Help agents understand when to use each tool
• Validate inputs: Use JSON Schema constraints (min, max, enum, pattern)
• Handle errors: Return meaningful error messages from your API
• Rate limiting: Consider API limits when designing tools
• Credential security: Never log or expose credential values
• OAuth PKCE: Always enable PKCE for OAuth integrations
• Granular tools: Create focused, single-purpose tools

Related Documentation