​
Overview

In addition to one-off sandbox executions, AVM lets you save code blocks as reusable tools. Once you’ve finalized a working version of your code through sandbox runs, you can save it as a tool that agents can call repeatedly without having to regenerate or redeploy the code.

Tools provide several key benefits:

  • Reusability: Invoke the same logic on-demand without regenerating code
  • Versioning: Track and manage different versions of your tools
  • Deterministic execution: Treat tools as callable functions within your agent’s toolset
  • Collaboration: Make tools public for sharing across teams and organizations

​
Creating a Tool

After testing your code with sandbox runs, you can save it as a reusable tool. Tools are created with specific inputs, environment variables, and a code block that defines their functionality.

curl -X POST https://api.avm.codes/api/tools \
  -H "avm-x-api-key: $AVM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "hello_tool",
    "description": "A tool that says hello",
    "isPublic": false,
    "code": "import os\napi_key = os.getenv(\"API_KEY\")\ndebug_mode = os.getenv(\"DEBUG\")\noutput = {{\"param1\": param1, \"param2\": param2, \"api_key\": api_key, \"debug\": debug_mode}}\nprint(\"Hello, World!\")",
    "language": "python",
    "inputs": ["param1", "param2"],
    "envVariables": ["API_KEY", "DEBUG"],
    "revisionName": "v1.0.0"
  }'

​
Tool Parameters

  • name: A unique identifier for your tool
  • description: Clear explanation of what the tool does
  • isPublic: Whether the tool can be used by other users
  • code: The Python code that will be executed
  • inputs: Array of input parameters the tool expects
  • envVariables: Array of environment variables the tool uses
  • revisionName: Version identifier for tracking changes

Only Python code is supported at the moment by AVM tools. The inputs and envVariables fields are optional.

​
Executing Tools

Once a tool is saved, it can be re-executed anytime using the execute endpoint. This allows for consistent, repeatable execution of your code logic.

curl -X POST https://api.avm.codes/api/tools/95/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",
      "DEBUG": "true"
    }
  }'

​
Tool Execution Response

The response includes structured output from your tool execution:

{
  "id": 101,
  "runId": "run_456def",
  "status": "COMPLETED",
  "stdout": "Hello, World!",
  "outputs": {
    "param1": "value1",
    "param2": 2,
    "api_key": "secret123",
    "debug": "true"
  },
  "errorMessage": null,
  "creditsConsumed": 1,
  "createdAt": "2025-01-01T10:05:00.000Z",
  "modifiedAt": "2025-01-01T10:05:02.000Z"
}

The outputs section reflects the output dictionary defined in your code block, making it easy to pass structured data back to the calling agent or workflow.

​
Public Tools

Tools can be made public, allowing any agent to call them as part of their own toolchain. This enables:

  • Shared utilities: Common logic available across teams
  • Open collaboration: Community-driven tool development
  • Reduced duplication: Reuse existing solutions instead of rebuilding
  • Faster development: Agents can leverage pre-built functionality

When creating public tools, ensure your code doesn’t contain sensitive information or API keys. Use environment variables for any secrets or configuration.

​
Tool Versioning

Tools support versioning through the revisionName field, allowing you to:

  • Track changes over time
  • Maintain backward compatibility
  • Test new versions while keeping stable releases
  • Reference specific versions in your workflows

​
Organizing Tools into Toolkits

For more complex workflows, tools can be grouped into toolkits — structured collections of reusable tools. Toolkits let agents compose multi-step behaviors from atomic building blocks and organize functionality into logical domains.

Tools must be created before they can be added to toolkits. Consider the relationship between your tools when designing your overall workflow architecture.

SDKToolkits