Create Agent From Config

Create a config-based agent, optionally deploying it.

Set deploy=false to save as draft without deploying.

POST/agents/config

Authorization

AuthorizationBearer token · headerrequired

Query parameters

deployboolean

default: true

Request body

requiredapplication/json

namestringrequired

Agent display name

min length 1 · max length 200

descriptionstring | null

Human-readable context for the agent

Show properties

Any of:

string

string

null

null

enabledboolean

Kill switch. When false, the Flink runtime accepts the deploy but stops emitting output — used by support to disable a runaway tenant agent without a full cancel/redeploy.

default: true

agentTypeAgentTypeEnum

Agent type — derived from the tool list post-validation; client-supplied value is overwritten

Allowed:workflowreact

inputAgentInputConfigrequired

Input configuration for the agent.

Show properties

topicPatternstringrequired

Regex pattern for input topics, e.g. '^(orders)$'

min length 1 · max length 1024

inputSerializationAgentSerializationEnum

Input deserialization format

Allowed:JsonConfluentAvroConfluent

fieldsstring[] | null

Column-level filter - only these fields sent to LLM

Show properties

Any of:

string[]

Array of string

string

null

null

createTableSQLstring | null

Flink SQL CREATE TABLE (required if filterSQL is set)

Show properties

Any of:

string

string

null

null

filterSQLstring | null

WHERE clause predicate for row-level filtering

Show properties

Any of:

string

string

null

null

outputAgentOutputConfigrequired

Output configuration for the agent.

Show properties

topicstringrequired

Fixed output topic name

min length 1 · max length 249

deadLetterTopicstring | null

DLQ topic name

Show properties

Any of:

string

string

null

null

outputSerializationAgentSerializationEnum

Output serialization format

Allowed:JsonConfluentAvroConfluent

schemaobject

Output schema: {field_name: TYPE_STRING}

llmAgentLlmConfigrequired

Inline LLM configuration embedded on the agent.

Carries provider, credentials, model, and tuning controls as a single blob. The FE prefills the form from a saved :class:AgentLlmConnection (which now carries default model + tuning + reasoning controls) and the user can override per-agent before save; the resulting blob is stored verbatim and shipped to the Flink runtime at deploy.

Two credential shapes (XOR, mirrors :class:ValidateLlmRequest):

Inline - apiKey is filled directly. The BE KMS-encrypts it at save and decrypts it at deploy / test-run.
Linked - llmConnectionId references a row in agent_connections.llmConnections and apiKey is left empty. The BE resolves the real key server-side at deploy and at test-run via :func:agents_service.resolve_saved_llm_credentials, so the browser never needs to hold (or re-paste) the stored plaintext when editing an existing agent.

provider == ollama accepts an empty key without a link (the runtime is local and unauthenticated).

Show properties

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

modelstringrequired

Model name, e.g. claude-sonnet-4-20250514

min length 1

apiKeystring

API key - use '${SECRET:ENV_VAR_NAME}' for env var resolution. Empty when llmConnectionId is set.

max length 512 · default: ""

llmConnectionIdstring | null

Tenant-scoped reference to agent_connections.llmConnections[].id. When set with an empty apiKey, the BE resolves the real key server-side at deploy and at test-run.

Show properties

Any of:

string

string

null

null

baseUrlstring | null

Base URL for OpenAI-compatible proxies

Show properties

Any of:

string

string

null

null

temperaturenumber | null

Sampling temperature (null = matrix-skipped)

Show properties

Any of:

number

number

null

null

maxTokensinteger | null

Max output tokens (null = matrix-skipped)

Show properties

Any of:

integer

integer

null

null

timeoutinteger | null

Request timeout in seconds (null = matrix-skipped)

Show properties

Any of:

integer

integer

null

null

reasoningEffortstring | null

OpenAI / GPT-5 reasoning effort. The accepted set is per-model: the matrix in app/utils/llm_capabilities.py rejects values not in caps.reasoning_effort_values for the chosen provider+model.

Show properties

Any of:

string

string

null

null

thinkingBudgetTokensinteger | null

Anthropic Claude 4 extended-thinking budget (tokens). Non-null enables thinking.

Show properties

Any of:

integer

integer

null

null

ollamaThinkboolean | null

Ollama 'think' toggle for reasoning models

Show properties

Any of:

boolean

boolean

null

null

maxRetriesinteger | null

Universal — max retry attempts on LLM call. Accepted by every provider.

Show properties

Any of:

integer

integer

null

null

regionstring | null

Bedrock: AWS region (e.g. us-east-1). Ignored for non-bedrock providers.

Show properties

Any of:

string

string

null

null

strictboolean | null

openai-responses: enable JSON-schema strict mode.

Show properties

Any of:

boolean

boolean

null

null

storeboolean | null

openai-responses: server-side response storage flag.

Show properties

Any of:

boolean

boolean

null

null

instructionsstring | null

openai-responses: system-level instructions passed as a top-level Responses param.

Show properties

Any of:

string

string

null

null

additionalKwargsobject | null

openai-responses / azure-openai: free-form extra request params forwarded verbatim by the runtime.

Show properties

Any of:

object

object

null

null

apiVersionstring | null

azure-openai: Azure OpenAI API version (e.g. '2024-02-01'). Required for azure-openai.

Show properties

Any of:

string

string

null

null

azureEndpointstring | null

azure-openai: Azure resource endpoint (e.g. https://<resource>.openai.azure.com). Required.

Show properties

Any of:

string

string

null

null

azureUrlPathModestring | null

azure-openai: URL path resolution — AUTO / LEGACY / UNIFIED. Optional.

Show properties

Any of:

string

string

null

null

promptsAgentPromptConfigrequired

Prompt configuration for the agent.

The final system prompt is auto-assembled by build_system_prompt() from the agent type template + output schema + tool descriptions + custom_instructions. The system field stores the assembled result (set by the backend, not the user).

Show properties

systemstring

Assembled system prompt (auto-generated by backend)

max length 8000 · default: ""

customInstructionsstring

User-provided instructions appended to the auto-generated prompt

max length 8000 · default: ""

userstring

User prompt template - {input_json} is replaced with the input record

max length 2000 · default: "<record>{input_json}</record>"

mcpServerAgentMcpServerConfig | null

Shared MCP server config for all MCP tools

Show properties

Any of:

AgentMcpServerConfig

projectKeyIdstring | null

ID of an agentic-enabled Project Key. When set, deploy-time resolves the Streamkap MCP serverUrl + auth header from the PK row. Mutually exclusive with serverUrl - one or the other, never both.

Show properties

Any of:

string

string

null

null

serverUrlstring | null

External MCP server URL. Required when projectKeyId is unset. Server-stamped from the PK row when projectKeyId is set.

Show properties

Any of:

string

string

null

null

headersobject

Auth headers for MCP server

null

null

toolsAgentToolConfig[]

Agent tools (MCP, HTTP, transform)

Show properties

Array of AgentToolConfig

namestringrequired

Tool name (must be unique)

min length 1 · max length 100

typeAgentToolTypeEnumrequired

Tool type: http, transform, or mcp

Allowed:httptransformmcp

descriptionstring

Tool description for the LLM

max length 2000 · default: ""

configobject

Type-specific configuration

parametersAgentToolParameterConfig[]

Tool parameters the LLM can provide

Show properties

Array of AgentToolParameterConfig

namestringrequired

Parameter name

min length 1 · max length 100

typestring

Parameter type (string, number, boolean)

max length 50 · default: "string"

descriptionstring

Parameter description for the LLM

max length 2000 · default: ""

memoryAgentMemoryConfig | null

Memory config (short-term + long-term)

Show properties

Any of:

AgentMemoryConfig

keyFieldstring | null

Field to partition memory by (e.g. 'customer_id'). Default: topic key

Show properties

Any of:

string

string

null

null

shortTermAgentShortTermMemoryConfig

Short-term (conversation) memory config.

Show properties

enabledboolean

Enable short-term memory

default: false

ttlMsinteger

Time-to-live in milliseconds (default: 1 hour)

min 0 · default: 3600000

maxEntriesinteger

Max conversation entries per key

min 1 · max 100 · default: 20

longTermAgentLongTermMemoryConfig

Long-term (vector store) memory config.

References a saved AgentVectorStoreConnection by id. At deploy time the resolver reads the connection's apiKey + endpoint and composes the inline vectorStore block the Java runtime expects.

Legacy agents may still carry destinationId (a Pinecone destination connector from the old flow). The deploy resolver handles both: if vectorStoreConnectionId is set it wins; otherwise it falls back to the legacy destinationId path. New agents created through the FE always use vectorStoreConnectionId.

Show properties

enabledboolean

Enable long-term memory

default: false

vectorStoreConnectionIdstring | null

Reference to a saved AgentVectorStoreConnection. Resolved at deploy time.

Show properties

Any of:

string

string

null

null

namespacestring | null

Per-agent namespace override (falls back to connection's defaultNamespace)

Show properties

Any of:

string

string

null

null

destinationIdstring | null

(Legacy) ObjectId of a Pinecone destination connector. Prefer vectorStoreConnectionId.

Show properties

Any of:

string

string

null

null

null

null

knowledgeBasesAgentKnowledgeBaseRef[]

Knowledge bases this agent can query at runtime for RAG

max items 10

Show properties

Array of AgentKnowledgeBaseRef

idstringrequired

Knowledge base entity ID

min length 1 · max length 64

namestring

Display name (denormalized for UI)

max length 200 · default: ""

processingAgentProcessingConfig

Processing configuration for the agent.

Show properties

parallelisminteger

Parallelism

min 1 · max 128 · default: 1

checkpointIntervalMininteger

Checkpoint interval in minutes

min 1 · max 60 · default: 5

maxIterationsinteger

Max tool-call iterations per record (react type only)

min 1 · max 25 · default: 10

maxTokensPerHourinteger

Per-TaskManager rolling-hour token budget. 0 = unlimited. When exceeded, records pass through with a _budget_exceeded: true marker.

min 0 · default: 0

Responses

200

Successful Response

_idstringrequired

namestringrequired

job_typeapp__models__api__agents_api_models__flink_jobs__FlinkJobTypeEnumrequired

Allowed:pyflinkjaragent_configknowledge_base

statusFlinkJobStatusEnumrequired

Allowed:CREATEDDEPLOYINGRUNNINGCANCELLINGCANCELLEDFAILEDFINISHED

desired_statusFlinkJobStatusEnum | null

Show properties

Any of:

FlinkJobStatusEnum

string

null

null

flink_job_namestringrequired

flink_job_idstring | null

Show properties

Any of:

string

string

null

null

parallelisminteger

default: 1

error_messagestring | null

Show properties

Any of:

string

string

null

null

agent_configobject | null

Show properties

Any of:

object

object

null

null

created_bystring | null

Show properties

Any of:

string

string

null

null

created_timestampstring<date-time> | null

Show properties

Any of:

string<date-time>

string<date-time>

null

null

updated_timestampstring<date-time> | null

Show properties

Any of:

string<date-time>

string<date-time>

null

null

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/config' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "description": "string",
  "enabled": true,
  "agentType": "workflow",
  "input": {
    "topicPattern": "string",
    "inputSerialization": "JsonConfluent",
    "fields": [
      "string"
    ],
    "createTableSQL": "string",
    "filterSQL": "string"
  },
  "output": {
    "topic": "string",
    "deadLetterTopic": "string",
    "outputSerialization": "JsonConfluent",
    "schema": {
      "property1": "STRING",
      "property2": "STRING"
    }
  },
  "llm": {
    "provider": "anthropic",
    "model": "string",
    "apiKey": "",
    "llmConnectionId": "string",
    "baseUrl": "string",
    "temperature": 0,
    "maxTokens": 1,
    "timeout": 1,
    "reasoningEffort": "none",
    "thinkingBudgetTokens": 0,
    "ollamaThink": true,
    "maxRetries": 0,
    "region": "string",
    "strict": true,
    "store": true,
    "instructions": "string",
    "additionalKwargs": {},
    "apiVersion": "string",
    "azureEndpoint": "string",
    "azureUrlPathMode": "AUTO"
  },
  "prompts": {
    "system": "",
    "customInstructions": "",
    "user": "<record>{input_json}</record>"
  },
  "mcpServer": {
    "projectKeyId": "string",
    "serverUrl": "string",
    "headers": {
      "property1": "string",
      "property2": "string"
    }
  },
  "tools": [
    {
      "name": "string",
      "type": "http",
      "description": "",
      "config": {},
      "parameters": [
        {
          "name": "string",
          "type": "string",
          "description": ""
        }
      ]
    }
  ],
  "memory": {
    "keyField": "string",
    "shortTerm": {
      "enabled": false,
      "ttlMs": 3600000,
      "maxEntries": 20
    },
    "longTerm": {
      "enabled": false,
      "vectorStoreConnectionId": "string",
      "namespace": "string",
      "destinationId": "string"
    }
  },
  "knowledgeBases": [
    {
      "id": "string",
      "name": ""
    }
  ],
  "processing": {
    "parallelism": 1,
    "checkpointIntervalMin": 5,
    "maxIterations": 10,
    "maxTokensPerHour": 0
  }
}'

const response = await fetch("https://api.streamkap.com/agents/config", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"name\": \"string\",\n  \"description\": \"string\",\n  \"enabled\": true,\n  \"agentType\": \"workflow\",\n  \"input\": {\n    \"topicPattern\": \"string\",\n    \"inputSerialization\": \"JsonConfluent\",\n    \"fields\": [\n      \"string\"\n    ],\n    \"createTableSQL\": \"string\",\n    \"filterSQL\": \"string\"\n  },\n  \"output\": {\n    \"topic\": \"string\",\n    \"deadLetterTopic\": \"string\",\n    \"outputSerialization\": \"JsonConfluent\",\n    \"schema\": {\n      \"property1\": \"STRING\",\n      \"property2\": \"STRING\"\n    }\n  },\n  \"llm\": {\n    \"provider\": \"anthropic\",\n    \"model\": \"string\",\n    \"apiKey\": \"\",\n    \"llmConnectionId\": \"string\",\n    \"baseUrl\": \"string\",\n    \"temperature\": 0,\n    \"maxTokens\": 1,\n    \"timeout\": 1,\n    \"reasoningEffort\": \"none\",\n    \"thinkingBudgetTokens\": 0,\n    \"ollamaThink\": true,\n    \"maxRetries\": 0,\n    \"region\": \"string\",\n    \"strict\": true,\n    \"store\": true,\n    \"instructions\": \"string\",\n    \"additionalKwargs\": {},\n    \"apiVersion\": \"string\",\n    \"azureEndpoint\": \"string\",\n    \"azureUrlPathMode\": \"AUTO\"\n  },\n  \"prompts\": {\n    \"system\": \"\",\n    \"customInstructions\": \"\",\n    \"user\": \"<record>{input_json}</record>\"\n  },\n  \"mcpServer\": {\n    \"projectKeyId\": \"string\",\n    \"serverUrl\": \"string\",\n    \"headers\": {\n      \"property1\": \"string\",\n      \"property2\": \"string\"\n    }\n  },\n  \"tools\": [\n    {\n      \"name\": \"string\",\n      \"type\": \"http\",\n      \"description\": \"\",\n      \"config\": {},\n      \"parameters\": [\n        {\n          \"name\": \"string\",\n          \"type\": \"string\",\n          \"description\": \"\"\n        }\n      ]\n    }\n  ],\n  \"memory\": {\n    \"keyField\": \"string\",\n    \"shortTerm\": {\n      \"enabled\": false,\n      \"ttlMs\": 3600000,\n      \"maxEntries\": 20\n    },\n    \"longTerm\": {\n      \"enabled\": false,\n      \"vectorStoreConnectionId\": \"string\",\n      \"namespace\": \"string\",\n      \"destinationId\": \"string\"\n    }\n  },\n  \"knowledgeBases\": [\n    {\n      \"id\": \"string\",\n      \"name\": \"\"\n    }\n  ],\n  \"processing\": {\n    \"parallelism\": 1,\n    \"checkpointIntervalMin\": 5,\n    \"maxIterations\": 10,\n    \"maxTokensPerHour\": 0\n  }\n}"
});

import requests

response = requests.post(
    "https://api.streamkap.com/agents/config",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"name\": \"string\",\n  \"description\": \"string\",\n  \"enabled\": true,\n  \"agentType\": \"workflow\",\n  \"input\": {\n    \"topicPattern\": \"string\",\n    \"inputSerialization\": \"JsonConfluent\",\n    \"fields\": [\n      \"string\"\n    ],\n    \"createTableSQL\": \"string\",\n    \"filterSQL\": \"string\"\n  },\n  \"output\": {\n    \"topic\": \"string\",\n    \"deadLetterTopic\": \"string\",\n    \"outputSerialization\": \"JsonConfluent\",\n    \"schema\": {\n      \"property1\": \"STRING\",\n      \"property2\": \"STRING\"\n    }\n  },\n  \"llm\": {\n    \"provider\": \"anthropic\",\n    \"model\": \"string\",\n    \"apiKey\": \"\",\n    \"llmConnectionId\": \"string\",\n    \"baseUrl\": \"string\",\n    \"temperature\": 0,\n    \"maxTokens\": 1,\n    \"timeout\": 1,\n    \"reasoningEffort\": \"none\",\n    \"thinkingBudgetTokens\": 0,\n    \"ollamaThink\": true,\n    \"maxRetries\": 0,\n    \"region\": \"string\",\n    \"strict\": true,\n    \"store\": true,\n    \"instructions\": \"string\",\n    \"additionalKwargs\": {},\n    \"apiVersion\": \"string\",\n    \"azureEndpoint\": \"string\",\n    \"azureUrlPathMode\": \"AUTO\"\n  },\n  \"prompts\": {\n    \"system\": \"\",\n    \"customInstructions\": \"\",\n    \"user\": \"<record>{input_json}</record>\"\n  },\n  \"mcpServer\": {\n    \"projectKeyId\": \"string\",\n    \"serverUrl\": \"string\",\n    \"headers\": {\n      \"property1\": \"string\",\n      \"property2\": \"string\"\n    }\n  },\n  \"tools\": [\n    {\n      \"name\": \"string\",\n      \"type\": \"http\",\n      \"description\": \"\",\n      \"config\": {},\n      \"parameters\": [\n        {\n          \"name\": \"string\",\n          \"type\": \"string\",\n          \"description\": \"\"\n        }\n      ]\n    }\n  ],\n  \"memory\": {\n    \"keyField\": \"string\",\n    \"shortTerm\": {\n      \"enabled\": false,\n      \"ttlMs\": 3600000,\n      \"maxEntries\": 20\n    },\n    \"longTerm\": {\n      \"enabled\": false,\n      \"vectorStoreConnectionId\": \"string\",\n      \"namespace\": \"string\",\n      \"destinationId\": \"string\"\n    }\n  },\n  \"knowledgeBases\": [\n    {\n      \"id\": \"string\",\n      \"name\": \"\"\n    }\n  ],\n  \"processing\": {\n    \"parallelism\": 1,\n    \"checkpointIntervalMin\": 5,\n    \"maxIterations\": 10,\n    \"maxTokensPerHour\": 0\n  }\n}",
)

Response

{
  "_id": "string",
  "name": "string",
  "job_type": "pyflink",
  "status": "CREATED",
  "desired_status": "CREATED",
  "flink_job_name": "string",
  "flink_job_id": "string",
  "parallelism": 1,
  "error_message": "string",
  "agent_config": {},
  "created_by": "string",
  "created_timestamp": "2019-08-24T14:15:22Z",
  "updated_timestamp": "2019-08-24T14:15:22Z"
}

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