AI Functions¶

An AI Function wraps an LLM as a first-class Poly resource. You set a system prompt, typed arguments, and optional tool functions (API or server functions the model may call). After generate, it appears in the SDK as poly.<context>.<name>.

Shipped in Release 33. Use the v2 API under /functions/ai. The older /ai-functions (slug / GPT-plugin) surface is deprecated for new work.

Before you execute¶

API key needs permission to manage AI functions (v1 manageAiFunctions) to create or update, and execute to run them.
Create a tenant config variable that holds your provider API key. Execute fails until that is set.
Default provider is openai, default model is gpt-5.5, default apiType is responses.

AI Function execute is metered separately from server function executions. For current SKUs and tiers see PolyAPI pricing.

Create¶

POST /functions/ai. name is required.

{
    "name": "summarizeTicket",
    "context": "support",
    "description": "Summarize a support ticket",
    "systemPrompt": "You are a support assistant.",
    "toolFunctionIds": ["<api-or-server-function-id>"],
    "toolFunctions": [
        {
            "id": "<function-id>",
            "argumentConfig": {
                "apiKey": { "source": "variable", "variableId": "<vari-id>" },
                "query": { "source": "ai" }
            }
        }
    ],
    "enabled": true
}

Useful optional fields (Create v2 DTO):

Field	Role
`context`	Namespace; SDK path `poly.<context>.<name>`. Default visibility is `ENVIRONMENT`.
`provider` / `model`	LLM. Defaults `openai` / `gpt-5.5`.
`systemPrompt`	Model instructions.
`systemPromptVariableId`	Load the system prompt from a Vari instead of (or in addition to) the inline field.
`inputTemplate`	Optional template for building model input from arguments.
`arguments`, `returnType`, `returnTypeSchema`, `outputSchema`, `errorSchema`	Typed I/O. A structured `errorSchema` failure may return HTTP 422.
`toolFunctionIds`	API or server function ids the model may call.
`toolFunctions`	Same tools, plus per-argument `argumentConfig`.
`clientPromptEnabled` / `clientPromptRequired` / `clientPromptArgName`	Optional caller prompt argument.
`router` / `routerServerFunctionId`	If `router` is true, skip the LLM and forward args to that server function. Both fields are required together. The server function must share the AI Function I/O signature.
`enabled`	Default `true`.

Also: GET/PATCH/DELETE /functions/ai/:id, GET /functions/ai to list.

Execute¶

POST /functions/ai/:id/execute with a JSON object of argument names to values. Requires an API key with Execute and access to the function.

POST /functions/ai/{id}/execute
Authorization: Bearer <api-key>
Content-Type: application/json

{ "ticketText": "Customer cannot log in" }

Then generate the SDK:

$ npx poly generate

$ python -m polyapi generate

TypeScript and Python both render AI Functions. Call poly.<context>.<name>(...) the same way you call other generated functions.

Tools¶

Attach tools with toolFunctionIds (ids only) and/or toolFunctions (ids plus argument sources).

Each tool argument source is one of:

`source`	Fill
`ai`	Model chooses the value (default if omitted)
`hardcoded`	Fixed value you store on the tool config
`argument`	Taken from the AI Function’s own execute arguments
`variable`	Taken from a Vari (`variableId`)

Helper: POST /functions/ai/resolve-tool-functions with body { "ids": ["…"] }.

Logs¶

TEXT executions only. GET /functions/ai/:id/logs.

Query params:

lastHours or lastDays (not both)
limit (max 100)
executionId, keyword, level

DELETE /functions/ai/:id/logs clears stored logs for that function.

Permissions¶

Action	v1 flag / v2 resource
Create	`manageAiFunctions`, then create
Update / delete	Entity access + `manageAiFunctions`
Execute	Entity access + `execute` (separate from manage). API key required on the request.
v2 catalog	Resource `aiFunctions` (execute, create, update, delete, read)

Keys that already had manageApiFunctions were granted manageAiFunctions in the permissions migration.

Limits and caveats¶

Do not use the legacy /ai-functions slug API for new work.
Chat traffic is also subject to a chat-questions rate limit on the API.

Related: Functions (when to use a server or API function as a tool), Vari Variables (keys and prompt Vari).