Write a custom code tool

Create a Custom Code tool for calculations and data processing that do not need network access. The Python input and output models become the tool contract the agent sees.

Prerequisites

Permission to manage organization tools.
A deterministic Python task that can run without an internet connection.
Vault secrets for any sensitive values the code needs.

Create the draft

Dashboard
API

Go to Global Tools, choose New tool, then select Custom Code. Enter a precise tool name and Instructions. Instructions maps to the API description field.

The New tool page with Custom Code highlighted — Select Custom Code from the New tool page

Define the source in a JSON request body.

tool.json

{
  "name": "calculate_discount",
  "description": "Calculate a percentage discount for an order subtotal.",
  "tool_type": "code",
  "code_src": "from pydantic import BaseModel, Field\n\nclass Input(BaseModel):\n    subtotal: float = Field(..., ge=0)\n    percent: float = Field(..., ge=0, le=100)\n\nclass Output(BaseModel):\n    discount: float\n    total: float\n\ndef handler(input: Input) -> Output:\n    discount = round(input.subtotal * input.percent / 100, 2)\n    return Output(discount=discount, total=round(input.subtotal - discount, 2))",
  "declared_secrets": [],
  "dependencies": [],
  "argument_defaults": {}
}

Request

curl -X POST https://api.agents.slng.ai/v1/agents/tools \
  -H "Authorization: Bearer $SLNG_API_KEY" \
  -H "Content-Type: application/json" \
  -d @tool.json

Define typed input and output

Define a Pydantic Input model, an Output model, and a synchronous handler(input: Input) -> Output function. Add field descriptions so the model knows which values to supply.Return the declared output model. Keep logs useful for testing, but return the data the agent needs from the handler.

Add dependencies and secrets

List each dependency as an exact version such as pydantic==2.11.7. Packages with URLs, environment markers, or extras are rejected.Declare Vault secret names separately from the source. Do not place secret values in code or logs. The environment exposes only the declared secrets.

Dashboard
API

Expand Metadata, select the Vault secrets the tool can access, and enter the pinned packages in Dependencies.

The Custom Code metadata panel with the Dependencies field highlighted — Configure Vault secrets and Python dependencies

Add the allowed Vault secret names to declared_secrets and the pinned packages to dependencies in the tool request.

Build the tool

Dashboard
API

Save the draft, then choose Build tool.

The Custom Code editor with Build tool highlighted — Build the tool after defining its code and metadata

Save the draft, then send POST /v1/agents/tools/{tool_id}/introspect.

The build installs the pinned dependencies, imports the declared modules, and derives the argument schema from the Pydantic models.

Test and publish

Run representative input, check the structured output and logs, then publish. You must have a valid schema, available secrets and dependencies, and a successful run for the current draft.

Attach the published version

Attach the version to an agent and verify it in a test call. See Attach a tool to an agent.

Environment limits

Custom Code runs in an isolated environment with no internet access. Use an API Request tool or MCP server for network calls. Avoid unbounded loops, large payloads, and large output objects. A run that exceeds its time or data limit returns a failure instead of partial output. Code tools can run on call start, first user message, and tool success or failure. They cannot run on call end. See Run a tool on call events.

Get started

Regions

Execution layer

Agent Builder

Models

Integrate

Prerequisites

Environment limits

​Prerequisites

​Environment limits

Prerequisites

Environment limits