Tools

Tools are actions your agent can take during a conversation: check an order, find a customer, book an appointment. On the agent's Tools page you add two kinds: an HTTP request (one call to your API, set up in a form) and a Function (code that can make several calls and calculate). This page covers HTTP tools and the built-in tools. Functions have their own page.

How the agent uses a tool

The model sees each tool's name, its description and its inputs. While it answers, it decides whether a tool would help, fills in the inputs from the conversation, and Peki makes the call for it. The model reads the result and continues, maybe calling another tool, then writes the reply.

Your API key is added by Peki on the way out. The model never sees it, and neither does the browser.

Add an HTTP tool

1. Open the agent and go to Tools.
2. Below the list, click HTTP request. A tool called New tool opens.
3. Fill in Title, Description the AI sees, the Request (method and URL) and the Inputs.
4. If your API needs a key, open Advanced — API key, headers, response fields, timeout and choose one.
5. Use Try it to make a real call and check What the AI sees.
6. Publish the agent. Tools are part of the draft: customers get the new tool only after you publish. The Test panel uses the draft right away.

A tool with a problem shows it in plain words on its card (for example Enter the API URL (https://…)), and the draft doesn't save until you fix it.

tip

You can also ask the Copilot to build a tool from your API docs. It reads the docs, creates the tool and tests it with realistic input.

Tool settings

Basics

Setting	What it does	Limit / default
Title	The name people see in Peki.	Required, up to 80 characters
Name the AI calls	The tool's name for the model, like order_status. Filled from the title while you haven't changed it.	Lowercase letters, digits and _, starting with a letter, up to 64 characters. Unique among the agent's tools and Functions.
Description the AI sees	When to use the tool. The model decides from this alone, so be specific.	Required, up to 1,000 characters

A good description says what the tool does, when to use it and what it needs: "Looks up where an order is when the customer gives an order number. Needs the order number (5–8 digits)."

Request

Setting	What it does	Default
Method	GET, POST, PUT, PATCH or DELETE.	GET
URL	The full http:// or https:// address, up to 2,000 characters. Put inputs in the path as {name}, like https://api.yourshop.com/orders/{order_id}.	—

How Peki builds the request from the inputs the model filled in:

• Inputs written as {name} in the URL replace the placeholder, URL-encoded.
• With GET and DELETE, the other inputs are sent as query parameters: ?email=ana%40example.com.
• With POST, PUT and PATCH, the other inputs are sent as a JSON body, with content-type: application/json. Optional inputs the model left out are not sent.
• Peki asks for JSON with an accept: application/json header.

If the URL has a {placeholder} that isn't an input yet, the card shows a button like Add order_id as an input.

note

The body is always a flat JSON object of the inputs, with the input names as keys. If your API needs a different shape (nested objects, arrays, a fixed field), use a Function instead.

Inputs

Inputs are what the model fills in. Click Add input to add one, and click an input to edit it.

Setting	What it does	Default
Name	The parameter name, sent as-is to your API. Letters, digits and _, up to 64 characters. Must be unique in the tool.	input_1
Type	Text, Number or Yes / no.	Text
Required	The model must fill it in. A call without it fails with Missing input: <name>.	On
Description the AI sees	How to fill it, like "the order number, 5–8 digits". Up to 300 characters.	Empty
Needs the real personal data	See below.	Off

A tool can have up to 20 inputs.

Personal data in inputs

With personal-data protection on (the default), the model never sees identifiers like TC kimlik numbers, card numbers, IBANs, phone numbers or emails. It sees placeholders like [PHONE_1] instead. So by default, a tool input filled from the conversation also gets the placeholder.

Turn on Needs the real personal data for inputs where your API needs the real value: the API gets the customer's real value, while the AI only ever sees a placeholder like [TCKN_1]. The trace of the call keeps the placeholder too. Personal data that comes back in a tool's response is also replaced with placeholders before the model reads it.

See Guardrails and privacy.

Approval

Setting	What it does	Default
Needs approval	The agent asks the team before calling it; you approve in the Inbox. The call waits with the exact values it would send.	Off
When rejected	Tell the customer (the agent says it can't be done) or Stay silent.	Tell the customer

Use it for actions that change something: refunds, cancellations, bookings. See Approvals.

Advanced

Open Advanced — API key, headers, response fields, timeout.

Setting	What it does	Default
API key	No key, Bearer token (sent as Authorization: Bearer <key>) or Key in a header (sent in the header you name, like X-API-Key). Then choose a key or + Add a new key.	No key
Headers	Extra headers sent with every call, like Accept-Language: en. Values are fixed text.	None, up to 20
Response fields the AI sees	One field per line, as a dot path like carrier.name. Only these reach the AI. Empty sends the whole response.	Empty, up to 50 fields
Timeout	How long to wait for your API: 3, 5, 10, 20 or 30 seconds.	10 seconds
Max response length (characters)	The longest result the AI reads: 1,000, 2,000, 4,000, 8,000 or 16,000. Longer results are cut and end with …(truncated).	4,000

warning

Never put an API key in Headers or in the URL. Header values are stored as plain text in the agent's settings and are visible to everyone who can open the agent. Use API key instead: Keys are stored encrypted and added to the request on our side. The AI never sees them.

Keys

Keys (secrets) are saved per agent, encrypted. After saving, Peki shows only the last four characters. Each key has Allowed sites: the key is only ever sent to these sites (host names; *.yourshop.com for all subdomains). When you add a key from a tool, the allowed site defaults to the tool's own host.

A key goes only to its allowed sites, whatever the tool's URL says. If you point a tool at another host, the card warns you: This key may only be sent to api.yourshop.com, not api.other.com. An admin can change its sites in Settings → Secrets.

Add and manage keys under Settings → Secrets. See Variables and secrets.

Response fields

Response fields keep the model's input small and focused. For this response:

{
  "id": "48213",
  "status": "shipped",
  "carrier": { "name": "UPS", "tracking": "1Z999AA10123456784" },
  "items": [
    { "name": "Trail Runner 2", "size": 42, "sku": "TR2-42" },
    { "name": "Running socks", "size": "M", "sku": "SK-M" }
  ],
  "internal_notes": "VIP, called twice"
}

with these response fields:

status
carrier.name
carrier.tracking
items.name

the model reads:

{"status":"shipped","carrier.name":"UPS","carrier.tracking":"1Z999AA10123456784","items.name":["Trail Runner 2","Running socks"]}

• A path through an array collects the value from every element (items.name above).
• Use a number to pick one element: items.0.name is "Trail Runner 2".
• Fields that don't exist in the response are left out.
• Personal data in the response is replaced with placeholders either way.

Try it

Every tool has a Try it row. Type a value for each input and click Run (or press Enter). You see ✓ HTTP 200 or the error, and how long it took. Click See response to compare:

• What the AI sees: the result exactly as the model would read it, after response fields and the length limit.
• Raw response: what your API sent back, with the method and URL that was called (up to 20,000 characters).

warning

Try it makes a real call with the values you type, with your real key. A POST or DELETE really creates or deletes something, and Needs approval doesn't apply to Try it. Use test data or a test environment for write actions. Only editors, admins and owners can run it.

If your API echoes the key back (error messages often do), Peki masks it (···· plus at most the last four characters) before the model or anyone in Peki sees it.

Security limits

Tools call your API from Peki's servers through a network guard. These limits protect your workspace and ours; you can't turn them off.

• Only http and https URLs.

• No private or local addresses. Requests to these are refused with Requests to … are not allowed (private or local network):

  Range	What it is
  127.0.0.0/8, ::1	This machine (localhost)
  10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7	Private networks
  169.254.0.0/16, fe80::/10	Link-local, including cloud metadata services
  100.64.0.0/10	Carrier-grade NAT
  0.0.0.0/8, 192.0.0.0/24, 198.18.0.0/15, 240.0.0.0/4, ::, 64:ff9b::/96	Reserved and special-purpose ranges
  224.0.0.0/4, ff00::/8	Multicast

• The address is checked after DNS. A public host name that resolves to a private address is refused too, so a DNS record can't point a tool at an internal service.

• Redirects are not followed. A 301 or 302 comes back as an error (HTTP 301). Use the final URL in the tool.

• Responses are capped at 1 MB. A bigger response fails with Response too large. Use a narrower endpoint or query parameters that return less.

• Keys go only to their allowed sites, as described above.

Your API must be reachable from the public internet. To connect an internal system, expose a public HTTPS endpoint for it (for example through an API gateway) and protect it with a key.

Errors

Problems shown on the card

Message	What to do
Give it a title	Fill in Title.
The AI name may only use lowercase letters, digits and _	Fix Name the AI calls.
Another tool already uses this AI name	Names are shared by HTTP tools and Functions. Pick another.
web_search is a built-in tool name	See reserved names.
Describe when the AI should use it	Fill in Description the AI sees.
Enter the API URL (https://…)	Use a full URL with a host.
{order_id} in the URL is not an input yet	Add the input, or click Add order_id as an input.
Choose an API key / Enter the header name for the key	Finish the API key setting, or set it to No key.

Errors when the tool runs

When a call fails, the model reads the error as the tool's result and can tell the customer, retry with different input, or hand off. The same errors show in Try it and in the conversation's trace.

Error	Cause	What to do
HTTP 404, HTTP 500, …	Your API answered with a non-2xx status. The model reads {"error": "HTTP 404", "body": …}, up to 1,000 characters.	Check the URL and inputs in Try it. Describe valid input formats in the input descriptions.
Missing input: order_id	A required input was empty.	Say in the tool description what the tool needs, or make the input optional.
Request timed out after 10000 ms	Your API was slower than Timeout.	Raise the timeout or speed up the endpoint.
Response too large (over 1000000 bytes)	The response was over 1 MB.	Return less data.
Requests to … are not allowed (private or local network)	The URL points to a private address.	Use a public endpoint.
This API key may only be sent to …	The tool's host isn't in the key's allowed sites.	Point the tool at the right host, or ask an admin to change the key's sites.
This API key has no allowed sites yet…	The key has no sites.	An admin sets them in Settings → Secrets.
The API key for this tool was deleted	The key was removed.	Choose another key.
This API key belongs to another agent	Keys belong to one agent.	Add a key for this agent.
This API key is not assigned to an agent yet…	An old key not assigned to any agent.	An admin assigns it in Settings → Secrets.
This key is a webhook signing key…	Signing keys only check incoming webhook signatures and are never sent.	Choose a regular key.

Built-in tools

Besides your own tools, Peki gives the agent built-in tools, depending on its settings. You don't set them up on the Tools page.

Tool	What it does	Offered when
request_human	Asks a person from your team to join the conversation.	Handoff is on (the default). Not in automations. See Human handoff.
web_search	Searches the web for current information and returns the top 5 results.	Web search is on (off by default).
read_page	Reads one web page as plain text.	Web search is on.
load_skill	Loads a skill's instructions.	The agent has skills. See Skills.
save_<table>, find_<table>	Save and look up records.	The agent has record tables. See Records.
ask_<name>	Asks another agent of the workspace for help.	The agent has team members. See Agent teams.

Knowledge isn't a tool: Peki searches the agent's knowledge automatically for each message. See Knowledge.

Names like web_search, read_page, request_human, load_skill and need_info are reserved. Your tools and Functions can't use them, nor the names your record tables and team members already use.

Tools in automations

When an automation runs a task, the agent only gets the tools you allowed for it. In a dry run, tools that send anything other than GET are not called: the model reads that the call was skipped. See Automations.

Examples

Order status (GET, path input)

Setting	Value
Title	Order status
Name the AI calls	order_status
Description	Looks up where an order is. Use when the customer gives an order number or asks where their package is.
Request	GET https://api.yourshop.com/v1/orders/{order_id}
Inputs	order_id, Text, required: "The order number, 5–8 digits, without #"
API key	Bearer token, key "ShopX API", allowed site api.yourshop.com
Response fields	status, carrier.name, carrier.tracking, estimated_delivery

The call for order 48213:

GET https://api.yourshop.com/v1/orders/48213
accept: application/json
authorization: Bearer ••••••••

Find a customer (GET, query input with personal data)

Setting	Value
Name the AI calls	find_customer
Description	Finds the customer's account by email. Use before answering questions about their account.
Request	GET https://api.yourshop.com/v1/customers
Inputs	email, Text, required, Needs the real personal data on
Response fields	name, tier, open_orders

The model fills email with a placeholder like [EMAIL_1]; Peki sends the real address:

GET https://api.yourshop.com/v1/customers?email=ana%40example.com

Book an appointment (POST, JSON body, approval)

Setting	Value
Title	Request appointment
Name the AI calls	request_appointment
Description	Requests an appointment slot. Use only after the patient confirmed the treatment, the day and their phone number.
Request	POST https://booking.brightsmile.example/api/requests
Inputs	name (Text), phone (Text, Needs the real personal data), treatment (Text), day (Text: "YYYY-MM-DD"), first_visit (Yes / no, optional)
API key	Key in a header: X-API-Key
Needs approval	On, When rejected: Tell the customer

The request after approval:

POST https://booking.brightsmile.example/api/requests
content-type: application/json
x-api-key: ••••••••

{"name":"Ana Lopez","phone":"+1 415 555 0134","treatment":"Cleaning","day":"2026-11-04","first_visit":true}

Limits

Limit	Value
HTTP tools per agent	30
Functions per agent	30
Inputs per tool	20
Headers per tool	20
Response fields per tool	50
URL length	2,000 characters
Timeout	Up to 30 seconds (3, 5, 10, 20 or 30 in the menu), default 10
Response read from your API	1 MB
Result the AI reads	Up to 20,000 characters (1,000–16,000 in the menu), default 4,000

Related

• Functions
• Skills
• Variables and secrets
• Guardrails and privacy
• Testing
• Approvals
• Limits