---
title: "Suggest Agent System Prompt"
method: POST
path: "/agents/system-prompt-suggestion"
tags: ["Agents"]
---

# Suggest Agent System Prompt

`POST /agents/system-prompt-suggestion`

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.

## Request body

- SystemPromptSuggestionRequest — Request body for ``POST /agents/system-prompt-suggestion``. Mirrors ``ValidateLlmRequest`` for the credential half (inline apiKey or savedConnectionId, with the same XOR rule) and adds the agent-context fields the meta-prompt needs to draft a starter ``customInstructions`` block. The runtime ``build_system_prompt`` already injects the per-agentType base template, schema field listing, and tool signatures - so the LLM is asked to produce *only* the user-facing instructions slot, never the boilerplate wrapper. See ``app.services.agent_prompt_suggester`` for the meta-prompt that enforces that.
  - `provider` 'anthropic' | 'openai' | 'openai-responses' | 'ollama' | 'azure' | 'azure-openai' | 'bedrock' | 'qwen' | 'openai-compatible', required — 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.
  - `model` string
  - `apiKey` string — Raw key - never stored
  - `baseUrl` string, nullable
  - `savedConnectionId` string, nullable — If set, BE resolves provider/apiKey/baseUrl from the tenant's saved llmConnection by id and ignores the inline ``apiKey`` / ``baseUrl``.
  - `agentType` string, required — Agent type (e.g. react, workflow)
  - `agentName` string, nullable
  - `description` string, nullable
  - `inputTopics` string[]
  - `selectedFields` string[]
  - `tools` ToolContext[] — Tool name + description list. Replaces the older toolNames-only shape.
    - `name` string, required — Tool name as referenced in the agent
    - `description` string — What the tool does, free-form
  - `outputSchema` OutputSchemaField[]
    - `name` string, required — Output field name
    - `type` string, required — Output field type as the wizard renders it
  - `filterSQL` string, nullable — Active record-filter (matches AgentInputConfig.filterSQL). Anchors the LLM's prompt to the actual shape of records reaching the agent.
  - `existingCustomInstructions` string, nullable — Existing draft to refine. Matches the FE textarea cap.
  - `generationHint` string, nullable — 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.

## Response `200`

Successful Response

- SystemPromptSuggestionResponse — Response body for ``POST /agents/system-prompt-suggestion``. Token counts come straight from the provider's ``usage`` block (zeroed when the provider didn't return one). ``model`` / ``provider`` echo back the resolved values so the FE can display "generated with anthropic / claude-sonnet-4-5" alongside the suggestion.
  - `generatedPrompt` string, required
  - `tokensIn` integer, required
  - `tokensOut` integer, required
  - `model` string, required
  - `provider` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/streamkap/apis/streamkap-rest-api.md) · [All operations](https://skmtc.net/streamkap/apis/streamkap-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/streamkap/streamkap-rest-api/versions/8aea6143d003/schema)