---
title: "Update Agent Config"
method: PUT
path: "/agents/{job_id}/config"
tags: ["Agents"]
---

# Update Agent Config

`PUT /agents/{job_id}/config`

Update a config-based agent's config and redeploy.

Merges the provided fields into the existing config, then triggers
savepoint -> cancel -> redeploy with the new config. The caller's email
is recorded on the paired history row (M3) - for admin-app mode this is
the admin's email, not the tenant user's.

## Path parameters

- `job_id` string, required

## Request body

- UpdateAgentConfigRequest — Request body for PUT /agents/{id}/config - update agent config and redeploy.
  - `description` string, nullable — Human-readable context for the agent
  - `enabled` boolean, nullable — Kill switch — set false to disable output emission without cancel/redeploy.
  - `input` AgentInputConfig — Input configuration for the agent.
    - `topicPattern` string, required — Regex pattern for input topics, e.g. '^(orders)$'
    - `inputSerialization` 'JsonConfluent' | 'AvroConfluent'
    - `fields` string[], nullable — Column-level filter - only these fields sent to LLM
    - `createTableSQL` string, nullable — Flink SQL CREATE TABLE (required if filterSQL is set)
    - `filterSQL` string, nullable — WHERE clause predicate for row-level filtering
  - `output` AgentOutputConfig — Output configuration for the agent.
    - `topic` string, required — Fixed output topic name
    - `deadLetterTopic` string, nullable — DLQ topic name
    - `outputSerialization` 'JsonConfluent' | 'AvroConfluent'
    - `schema` object — Output schema: {field_name: TYPE_STRING}
  - `llm` AgentLlmConfig — 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`): 1. **Inline** - ``apiKey`` is filled directly. The BE KMS-encrypts it at save and decrypts it at deploy / test-run. 2. **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).
    - `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, required — Model name, e.g. claude-sonnet-4-20250514
    - `apiKey` string — API key - use '${SECRET:ENV_VAR_NAME}' for env var resolution. Empty when llmConnectionId is set.
    - `llmConnectionId` string, nullable — 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.
    - `baseUrl` string, nullable — Base URL for OpenAI-compatible proxies
    - `temperature` number, nullable — Sampling temperature (null = matrix-skipped)
    - `maxTokens` integer, nullable — Max output tokens (null = matrix-skipped)
    - `timeout` integer, nullable — Request timeout in seconds (null = matrix-skipped)
    - `reasoningEffort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh', nullable — 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.
    - `thinkingBudgetTokens` integer, nullable — Anthropic Claude 4 extended-thinking budget (tokens). Non-null enables thinking.
    - `ollamaThink` boolean, nullable — Ollama 'think' toggle for reasoning models
    - `maxRetries` integer, nullable — Universal — max retry attempts on LLM call. Accepted by every provider.
    - `region` string, nullable — Bedrock: AWS region (e.g. us-east-1). Ignored for non-bedrock providers.
    - `strict` boolean, nullable — openai-responses: enable JSON-schema strict mode.
    - `store` boolean, nullable — openai-responses: server-side response storage flag.
    - `instructions` string, nullable — openai-responses: system-level instructions passed as a top-level Responses param.
    - `additionalKwargs` object, nullable — openai-responses / azure-openai: free-form extra request params forwarded verbatim by the runtime.
    - `apiVersion` string, nullable — azure-openai: Azure OpenAI API version (e.g. '2024-02-01'). Required for azure-openai.
    - `azureEndpoint` string, nullable — azure-openai: Azure resource endpoint (e.g. https://<resource>.openai.azure.com). Required.
    - `azureUrlPathMode` 'AUTO' | 'LEGACY' | 'UNIFIED', nullable — azure-openai: URL path resolution — AUTO / LEGACY / UNIFIED. Optional.
  - `prompts` AgentPromptConfig — 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).
    - `system` string — Assembled system prompt (auto-generated by backend)
    - `customInstructions` string — User-provided instructions appended to the auto-generated prompt
    - `user` string — User prompt template - {input_json} is replaced with the input record
  - `mcpServer` AgentMcpServerConfig — Top-level MCP server config shared across all MCP tools. Two shapes (hard cutover): - **Streamkap MCP** (internal toolbelt): ``projectKeyId`` set, ``serverUrl`` and ``headers`` resolved server-side at deploy time from the agentic-enabled Project Key. The legacy "saved Streamkap MCP card" path (match-by-serverUrl against ``agent_connections.mcpConnections[source==streamkap]``) is gone. - **External MCP**: ``serverUrl`` + ``headers`` set inline; ``projectKeyId`` omitted. Headers are still composed at deploy time from the matching saved external connection (bearer / custom-header).
    - `projectKeyId` string, nullable — 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.
    - `serverUrl` string, nullable — External MCP server URL. Required when projectKeyId is unset. Server-stamped from the PK row when projectKeyId is set.
    - `headers` object — Auth headers for MCP server
  - `tools` AgentToolConfig[], nullable
    - `name` string, required — Tool name (must be unique)
    - `type` 'http' | 'transform' | 'mcp', required
    - `description` string — Tool description for the LLM
    - `config` object — Type-specific configuration
    - `parameters` AgentToolParameterConfig[] — Tool parameters the LLM can provide
      - `name` string, required — Parameter name
      - `type` string — Parameter type (string, number, boolean)
      - `description` string — Parameter description for the LLM
  - `memory` AgentMemoryConfig — Memory configuration for the agent.
    - `keyField` string, nullable — Field to partition memory by (e.g. 'customer_id'). Default: topic key
    - `shortTerm` AgentShortTermMemoryConfig — Short-term (conversation) memory config.
      - `enabled` boolean — Enable short-term memory
      - `ttlMs` integer — Time-to-live in milliseconds (default: 1 hour)
      - `maxEntries` integer — Max conversation entries per key
    - `longTerm` AgentLongTermMemoryConfig — 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``.
      - `enabled` boolean — Enable long-term memory
      - `vectorStoreConnectionId` string, nullable — Reference to a saved AgentVectorStoreConnection. Resolved at deploy time.
      - `namespace` string, nullable — Per-agent namespace override (falls back to connection's defaultNamespace)
      - `destinationId` string, nullable — (Legacy) ObjectId of a Pinecone destination connector. Prefer vectorStoreConnectionId.
  - `knowledgeBases` AgentKnowledgeBaseRef[], nullable — Knowledge bases this agent can query at runtime for RAG
    - `id` string, required — Knowledge base entity ID
    - `name` string — Display name (denormalized for UI)
  - `processing` AgentProcessingConfig — Processing configuration for the agent.
    - `parallelism` integer — Parallelism
    - `checkpointIntervalMin` integer — Checkpoint interval in minutes
    - `maxIterations` integer — Max tool-call iterations per record (react type only)
    - `maxTokensPerHour` integer — Per-TaskManager rolling-hour token budget. 0 = unlimited. When exceeded, records pass through with a `_budget_exceeded: true` marker.
  - `changeNote` string, nullable

## Response `200`

Successful Response

- AppModelsApiAgentsApiModelsFlinkJobsFlinkJobResponse
  - `_id` string, required
  - `name` string, required
  - `job_type` 'pyflink' | 'jar' | 'agent_config' | 'knowledge_base', required
  - `status` 'CREATED' | 'DEPLOYING' | 'RUNNING' | 'CANCELLING' | 'CANCELLED' | 'FAILED' | 'FINISHED', required
  - `desired_status` 'CREATED' | 'DEPLOYING' | 'RUNNING' | 'CANCELLING' | 'CANCELLED' | 'FAILED' | 'FINISHED'
  - `flink_job_name` string, required
  - `flink_job_id` string, nullable
  - `parallelism` integer
  - `error_message` string, nullable
  - `agent_config` object, nullable
  - `created_by` string, nullable
  - `created_timestamp` string, date-time, nullable
  - `updated_timestamp` string, date-time, nullable

## 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/revisions/8aea6143d003/schema)