Create a tool

POST /v1/tools

A request an agent can make mid-conversation, in a project. Attach it to agents by name in their definitions. Its address may not be on this deployment's network, and a credential it names must be a tool credential assigned to the project — sent only where it already goes, or pinned there if this is its first use. Needs tools:write and a live key.

Body

Sent as JSON. A field this operation does not take is refused, so a typo fails loudly.

Field	Type	Required	Description
`description`	string	Yes
`http`	object	Yes	`method`, `url`, `headers`, `auth` — `{"type": "bearer", "vault_key_id": …}` names a credential from `POST /v1/vault/secrets` — and `timeout_ms`.
`name`	string	Yes	What the model calls it: letters, digits and underscores.
`parameters`	object	Yes	The JSON Schema of what the model sends it.
`project_id`	string (uuid)	Yes	The project it belongs to.
`speaking_hint`	string	No

Answer

201 with ToolObject.

Errors

Every error is a problem document with a stable code.

Status	When
`401`	The key is missing, mistyped, unknown, revoked or expired.
`403`	A credential sent somewhere it does not go yet, or a test key.
`409`	The project already has a tool by that name, or it is frozen.
`422`	The tool's shape, its address or its credential will not do.
`429`	Too many requests for this key or its organization; see `Retry-After`.
`500`	Something went wrong on our side. Quote the `request_id` to support.

Examples

Create a tool

#!/bin/sh
# Create a tool. Give it to agents by name in their definitions. With a live key.
curl -sS --fail-with-body -X POST "https://api.aigently.ai/v1/tools" \
  -H "Authorization: Bearer $AIGENTLY_API_KEY" \
  --json '{
  "project_id": "0b1c2d3e-4f5a-6b7c-8d9e-0f1a2b3c4d5e",
  "name": "lookup_order",
  "description": "Look up the status of an order by its number.",
  "parameters": {
    "type": "object",
    "properties": {
      "order_id": {
        "type": "string",
        "description": "The order number."
      }
    },
    "required": [
      "order_id"
    ]
  },
  "http": {
    "method": "GET",
    "url": "https://orders.aigently.ai/v1/orders/{order_id}",
    "auth": {
      "type": "bearer",
      "vault_key_id": "2e4a6c8e-0a2c-4e4a-d6c8-e0a2c4e6a8ca"
    }
  },
  "speaking_hint": "One moment while I look that up."
}'

Try it

Sends this request to the API from your browser, with a test key. Nothing it does rings a phone.