ai_complete
Call a platform AI model for a project. ai_catalog lists current models and prices; docs({topic:"sw.ai"}) explains the full contract.
With neither provider nor model, the call uses free gpt-6-luna: 10 requests/minute and 200/day per project owner on every plan, 8,192 estimated input tokens including system/tools/history, and at most 1,024 output tokens. Standard service, reasoning disabled, 20-second provider deadline including the body. No paid fallback, BYOK charge, or automatic paid repair.
Explicit provider/model selection uses that model's normal billing path, including explicitly selecting gpt-6-luna. Included workers-ai models retain their separate limits. ai_catalog lists the valid model IDs.
messages is a JSON-stringified array of {role,content}. For text use result.text; result.content contains text/tool_use blocks. With response_schema, the result carries result.parsed and result.parse_error. Paid OpenAI/Anthropic responses may report pending cost: unknown is not zero, and repeating a successful model call does not settle accounting.
Tool-capable models accept Anthropic-shaped tool definitions and tool_result messages. A caller-chosen conversation_id together with subject_type and subject_id retains history under that scope; that caller key continues the conversation on later ai_complete calls. ai_conversation_list, ai_conversation_delete, and ai_conversation_fork take the same scope. Later turns send only new messages. History works across supported providers. Free-default overflow truncates history for the request and never runs paid summarization. For larger conversations and explicit paid compaction read docs({topic:"sw.ai"}).
Structured output: pass response_schema as a JSON-stringified JSON Schema, without caller tools or streaming.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"project_id": "<project_id>",
"messages": "<messages>"
},
"name": "ai_complete"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Optional concrete model ID or alias from ai_catalog. Explicit selection uses the paid path unless cataloged as included. | |
| tools | No | Optional JSON-stringified Anthropic tool definitions. Passed through unchanged. | |
| system | No | Optional system prompt | |
| messages | Yes | JSON-stringified array of {role, content} messages. content is a string OR Anthropic content-block array (for tool_result multi-turn). | |
| provider | No | Optional provider from ai_catalog. Omission of both provider and model selects free starter chat. Explicit providers use their normal pricing. | |
| compaction | No | Optional truncate (default) or summarize. Free default always truncates; explicit paid summarization can incur an additional model charge. Details: docs sw.ai. | |
| max_tokens | No | Optional output-token budget, default 1024. Free default capped at 1024; explicit models have their catalog limits. | |
| project_id | Yes | Project ID (UUID), subdomain, or slug — resolved server-side, no UUID lookup needed. 'default' also works when the account has exactly one project; multi-project accounts must name one (the error lists them). | |
| subject_id | No | Required with conversation_id. Conversation owner id. Conversation reads take the same scope. | |
| tool_choice | No | Optional JSON-stringified Anthropic tool_choice directive (e.g. {"type":"auto"} or {"type":"tool","name":"fs_search"}). | |
| subject_type | No | Required with conversation_id. Conversation owner type; 'app_user' is for signed-in app users. Conversation reads take the same scope. | |
| conversation_id | No | Optional caller-chosen chat key (any string up to 128 chars). The same key on later ai_complete calls loads prior turns. Reading, deleting or forking the saved record takes the id that ai_conversation_list returns when called without conversation_id. | |
| response_schema | No | Optional JSON-stringified JSON Schema. The response exposes parsed and parse_error. This field cannot combine with tools or stream; the free default makes no repair request. | |
| history_max_tokens | No | Optional retained-history token budget (estimated), default 32000. New messages/system are counted against the overall input cap too. | |
| history_max_messages | No | Optional. Cap on the number of stored history messages prepended on this call. Oldest dropped first. Default 50. Only applies when conversation_id is set. |