---
title: "Bind tools to an agent"
method: PUT
path: "/v1/agents/{id}/tools"
tags: ["Agents"]
---

# Bind tools to an agent

`PUT /v1/agents/{id}/tools`

## Request

- Base URL: `https://api.pyai.com`
- URL: `https://api.pyai.com/v1/agents/{id}/tools`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Replace the agent's tool bindings. Each entry references a tool id from `GET /v1/tools`. Requires the `omni:session` scope.

## Path parameters

- `id` string, required

## Request body

- AgentToolBinding[]
  - `tool_id` string, required
  - `enabled` boolean
  - `config` object: Customer SETTINGS for this tool on this agent, keyed by the tool's config_schema field keys (e.g. { from_number, provider_api_key }). Fields marked secret are encrypted at rest and returned masked ('********'); re-send the mask (or omit) to keep the stored value.
  - `name` string: Present on agent reads when the tool resolves.
  - `description` string
  - `input_schema` object: Per-call model argument schema. Present on agent reads when the tool resolves.
  - `execution` 'hosted' | 'server' | 'engine' | 'client': Resolved execution mode. Present on agent reads when the tool resolves.

## Response `200`

Updated bindings

- AgentToolBindingList
  - `object` string
  - `data` AgentToolBinding[]
    - `tool_id` string, required
    - `enabled` boolean
    - `config` object: Customer SETTINGS for this tool on this agent, keyed by the tool's config_schema field keys (e.g. { from_number, provider_api_key }). Fields marked secret are encrypted at rest and returned masked ('********'); re-send the mask (or omit) to keep the stored value.
    - `name` string: Present on agent reads when the tool resolves.
    - `description` string
    - `input_schema` object: Per-call model argument schema. Present on agent reads when the tool resolves.
    - `execution` 'hosted' | 'server' | 'engine' | 'client': Resolved execution mode. Present on agent reads when the tool resolves.

## Other responses

- `400`: Invalid binding
- `401`: Missing or invalid API key (`code: unauthorized`)
- `404`: No such agent or tool

---

[API](https://skmtc.dev/pyai/apis/pyai-api.md) · [All operations](https://skmtc.dev/pyai/apis/pyai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pyai/apis/pyai-api/revisions/271a1539185b?raw)