Suggest Agent System Prompt

Generate a starter customInstructions block for the wizard.

Same two credential shapes as /agents/validate-llm:

Inline - raw apiKey (+ optional baseUrl) supplied directly.
Saved connection - savedConnectionId references a stored llmConnection; BE loads decrypted apiKey / baseUrl / provider server-side so the browser never holds the plaintext.

Composes a meta-system-prompt + a structured user message describing the agent (type, name, description, topics, fields, tools, output schema, optional existing draft) and calls the user’s own LLM. The runtime build_system_prompt already emits the per-agentType base template + schema field listing + tool signatures at deploy time, so the LLM is constrained to produce only the user-facing instructions slot - the meta-prompt enforces that explicitly. Nothing is persisted.

Per-tenant rate limit: dedicated BUCKET_PROMPT_SUGGEST bucket (30/min/tenant) separate from validate-llm, so heavy “Generate” usage (humans iterating on prompt drafts) doesn’t eat into the credential-check budget. Provider failures (timeouts, 4xx, schema errors) surface as 400 with the provider’s error message so the FE’s existing error-extraction works unchanged.

POST/agents/system-prompt-suggestion

Authorization

AuthorizationBearer token · headerrequired

Request body

requiredapplication/json

providerAgentLlmProviderEnumrequired

Unified LLM provider enum.

A single AgentLlmConnection row carries one provider and a set of capabilities (chat / embedding). PROVIDER_CAPABILITIES below pins which capabilities each provider can serve — picked by the FE Connections drawer and re-validated server-side on every write.

Allowed:anthropicopenaiopenai-responsesollamaazureazure-openaibedrockqwenopenai-compatible

modelstring

max length 200 · default: ""

apiKeystring

Raw key - never stored

max length 512 · default: ""

baseUrlstring | null

Show properties

Any of:

string

string

null

null

savedConnectionIdstring | null

If set, BE resolves provider/apiKey/baseUrl from the tenant's saved llmConnection by id and ignores the inline apiKey / baseUrl.

Show properties

Any of:

string

string

null

null

agentTypestringrequired

Agent type (e.g. react, workflow)

min length 1 · max length 50

agentNamestring | null

Show properties

Any of:

string

string

null

null

descriptionstring | null

Show properties

Any of:

string

string

null

null

inputTopicsstring[]

max items 20

selectedFieldsstring[]

max items 50

toolsToolContext[]

Tool name + description list. Replaces the older toolNames-only shape.

max items 50

Show properties

Array of ToolContext

namestringrequired

Tool name as referenced in the agent

min length 1 · max length 200

descriptionstring

What the tool does, free-form

max length 1000 · default: ""

outputSchemaOutputSchemaField[]

max items 50

Show properties

Array of OutputSchemaField

namestringrequired

Output field name

min length 1 · max length 100

typestringrequired

Output field type as the wizard renders it

min length 1 · max length 50

filterSQLstring | null

Active record-filter (matches AgentInputConfig.filterSQL). Anchors the LLM's prompt to the actual shape of records reaching the agent.

Show properties

Any of:

string

string

null

null

existingCustomInstructionsstring | null

Existing draft to refine. Matches the FE textarea cap.

Show properties

Any of:

string

string

null

null

generationHintstring | null

Optional one-line steer the user types into the wizard's 'Hint for AI' input. The meta-prompt already gets the agent's metadata, so this should carry use-case intent (tone, edge-case priority, what to emphasize) rather than restate the data shape.

Show properties

Any of:

string

string

null

null

Responses

200

Successful Response

generatedPromptstringrequired

tokensInintegerrequired

tokensOutintegerrequired

modelstringrequired

providerstringrequired

422

Validation Error

detailValidationError[]

Show properties

Array of ValidationError

locstring | integer[]required

Show properties

Array of string | integer

Any of:

string

string

integer

integer

msgstringrequired

typestringrequired

inputany

ctxobject

Request

curl -X POST 'https://api.streamkap.com/agents/system-prompt-suggestion' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "provider": "anthropic",
  "model": "",
  "apiKey": "",
  "baseUrl": "string",
  "savedConnectionId": "string",
  "agentType": "string",
  "agentName": "string",
  "description": "string",
  "inputTopics": [
    "string"
  ],
  "selectedFields": [
    "string"
  ],
  "tools": [
    {
      "name": "string",
      "description": ""
    }
  ],
  "outputSchema": [
    {
      "name": "string",
      "type": "string"
    }
  ],
  "filterSQL": "string",
  "existingCustomInstructions": "string",
  "generationHint": "string"
}'

const response = await fetch("https://api.streamkap.com/agents/system-prompt-suggestion", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"provider\": \"anthropic\",\n  \"model\": \"\",\n  \"apiKey\": \"\",\n  \"baseUrl\": \"string\",\n  \"savedConnectionId\": \"string\",\n  \"agentType\": \"string\",\n  \"agentName\": \"string\",\n  \"description\": \"string\",\n  \"inputTopics\": [\n    \"string\"\n  ],\n  \"selectedFields\": [\n    \"string\"\n  ],\n  \"tools\": [\n    {\n      \"name\": \"string\",\n      \"description\": \"\"\n    }\n  ],\n  \"outputSchema\": [\n    {\n      \"name\": \"string\",\n      \"type\": \"string\"\n    }\n  ],\n  \"filterSQL\": \"string\",\n  \"existingCustomInstructions\": \"string\",\n  \"generationHint\": \"string\"\n}"
});

import requests

response = requests.post(
    "https://api.streamkap.com/agents/system-prompt-suggestion",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"provider\": \"anthropic\",\n  \"model\": \"\",\n  \"apiKey\": \"\",\n  \"baseUrl\": \"string\",\n  \"savedConnectionId\": \"string\",\n  \"agentType\": \"string\",\n  \"agentName\": \"string\",\n  \"description\": \"string\",\n  \"inputTopics\": [\n    \"string\"\n  ],\n  \"selectedFields\": [\n    \"string\"\n  ],\n  \"tools\": [\n    {\n      \"name\": \"string\",\n      \"description\": \"\"\n    }\n  ],\n  \"outputSchema\": [\n    {\n      \"name\": \"string\",\n      \"type\": \"string\"\n    }\n  ],\n  \"filterSQL\": \"string\",\n  \"existingCustomInstructions\": \"string\",\n  \"generationHint\": \"string\"\n}",
)

Response

{
  "generatedPrompt": "string",
  "tokensIn": 0,
  "tokensOut": 0,
  "model": "string",
  "provider": "string"
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}