​
Overview

Toolkits are structured collections of reusable tools that enable more complex agent workflows. Instead of managing individual tools separately, toolkits allow you to:

  • Compose multi-step behaviors from atomic building blocks
  • Modularize complex logic into organized packages
  • Organize functionality into logical domains (e.g., scraping, parsing, exporting)
  • Share environment variables across all tools in the toolkit
  • Execute tools in sequence with coordinated inputs and outputs

​
Creating a Toolkit

Start by creating an empty toolkit that acts as a container for your tools. You’ll add tools to it later using the appropriate API calls.

curl -X POST https://api.avm.codes/api/toolkit \
  -H "avm-x-api-key: $AVM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my_toolkit",
    "description": "A toolkit with multiple reusable tools",
    "isPublic": false,
    "envVariables": {
      "API_KEY": "your-production-api-key",
      "DEBUG": "false"
    }
  }'

​
Toolkit Parameters

  • name: A unique identifier for your toolkit
  • description: Clear explanation of the toolkit’s purpose
  • isPublic: Whether the toolkit can be used by other users
  • envVariables: Shared environment variables for all tools in the toolkit

Environment variables defined at the toolkit level are shared across all tools within that toolkit, providing consistent configuration management.

​
Adding Tools to a Toolkit

Once you have both a toolkit and saved tools, you can add tools to the toolkit. This allows you to compose a toolkit as a package of tools that share the same environment variables and can be executed together.

curl -X POST https://api.avm.codes/api/toolkit/12/tools \
  -H "avm-x-api-key: $AVM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toolId": 95,
    "revisionId": 0
  }'

You can optionally include a revisionId to specify a particular version of the tool to use. If omitted, AVM will automatically use the latest revision.

​
Removing Tools from a Toolkit

If some tools in your toolkit are no longer needed, you can remove them to keep the toolkit lean and relevant.

curl -X DELETE https://api.avm.codes/api/toolkit/12/tools \
  -H "avm-x-api-key: $AVM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{{ "toolId": 95 }}'

​
Executing Toolkits

Once your toolkit is ready, you can execute all tools in sequence. Toolkit execution allows you to run all associated tools in a predefined order while sharing the same environment variables across all of them.

curl -X POST https://api.avm.codes/api/toolkit/12/execute/sync \
  -H "avm-x-api-key: $AVM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "param1": "value1",
      "param2": 2
    },
    "envVariables": {
      "API_KEY": "secret123"
    },
    "toolIds": [95, 96]
  }'

​
Execution Options

You have several options when executing toolkits:

  • Subset execution: Specify toolIds to run only specific tools from the toolkit
  • Execution order: Tools run in the order specified in the toolIds array
  • Environment override: Send a JSON object to override part or all of the environment variables saved in the toolkit configuration

​
Toolkit Execution Response

The response includes results from all executed tools:

{
  "runs": [
    {
      "id": 1,
      "runId": "run_abc123",
      "userId": 42,
      "apiKeyId": 123,
      "toolRevisionId": 201,
      "toolkitId": 12,
      "inputs": {
        "param1": "value1",
        "param2": 2
      },
      "stdout": "Hello, World!",
      "outputs": {
        "param1": "value1",
        "param2": 2,
        "api_key": "secret123",
        "debug": "true"
      },
      "status": "COMPLETED",
      "creditsConsumed": 2.5,
      "errorMessage": null,
      "createdAt": "2025-01-01T10:00:00Z",
      "modifiedAt": "2025-01-01T10:00:02Z"
    }
  ],
  "totalCreditsConsumed": 2.5,
  "error": null
}

​
Toolkit Design Patterns

​
Domain-Specific Toolkits

Organize tools by functional domain:

  • Data Processing Toolkit: Tools for parsing, cleaning, and transforming data
  • Web Scraping Toolkit: Tools for fetching, extracting, and formatting web content
  • Analysis Toolkit: Tools for statistical analysis, visualization, and reporting

​
Pipeline Toolkits

Create toolkits that represent end-to-end workflows:

  • ETL Pipeline: Extract → Transform → Load operations
  • Content Generation: Research → Write → Format → Publish
  • Testing Suite: Setup → Execute → Validate → Report

​
Utility Toolkits

Group commonly used helper functions:

  • String Processing: Validation, formatting, parsing utilities
  • File Operations: Reading, writing, converting file formats
  • API Integrations: Authentication, requests, response handling

Before creating a toolkit, ensure you have already created the individual tools you want to include. Tools must exist before they can be added to a toolkit.

​
Public Toolkits

Like individual tools, toolkits can be made public to enable:

  • Shared workflows: Complete processes available to the community
  • Best practices: Standardized approaches to common tasks
  • Collaboration: Teams can build upon each other’s toolkit designs

When creating public toolkits, ensure that all included tools and environment variables are appropriate for public use.

ToolsCode Generation Evaluations