Concepts

Agents

The core execution unit — a configured AI assistant with a system prompt, model, and tools.

An agent is the smallest independently executable unit in UnderOcean. It bundles together everything needed to have a model respond to input:

  • A system prompt (versioned — editing it creates a new agent version)
  • A provider configuration (which model, via which provider)
  • Generation parameters: temperature, max tokens
  • Optional reasoning effort (none | low | medium | high) — when set on a model that supports extended thinking/reasoning, its reasoning trace is streamed and persisted alongside the answer; see Executions & Streaming
  • Optional response format — make every answer JSON that follows a JSON Schema; see Executions & Streaming
  • Optional tool assignments (see MCP)
  • Optional memory configuration (see Context Management)
  • Optional knowledge base access for Agentic-RAG

Configuration rules

Agent writes are validated, so a bad value is a 422 that names the problem instead of a failure at run time:

  • name is trimmed and cannot be empty; system_prompt is at most 100,000 characters.
  • llm_provider_config_id must be an LLM provider of the agent's project or organization (not an embedding provider, not another organization's).
  • knowledge_config.knowledge_base_ids and mcp_server_ids must exist in the agent's own project and cannot repeat.
  • memory_config accepts strategy (summarization | hybrid), max_tokens_before_summary, max_summary_tokens, enable_key_extraction, extraction_interval and memory_retrieval_k; guardrails_config accepts the guardrail switches as real booleans. Unknown keys are refused. Fields you leave out take their default on create and keep their current value on update.
  • Switching on toxic_content_filter needs an OpenAI provider (on api.openai.com, no custom base URL) in the agent's project or organization; without one the write is a 422 with code: "guardrail_unavailable" (see Guardrails).
  • Unknown top-level fields are refused too.
  • response_format is {"type": "json_schema", "json_schema": {"name", "schema", "strict"}} (or {"type": "text"} / null for free text). The schema must be a valid JSON Schema whose root is an object, at most 32,000 characters, with $refs that stay inside it (#/...); with strict: true every object also needs additionalProperties: false and all its properties in required. PATCH with null clears it. It is part of an agent's version history.

Versioning

Agents are versioned rather than mutated in place. Updating the system prompt creates a new version; past versions remain available for rollback and for correlating historical executions with the prompt that produced them.

Beyond the prompt, every agent also has a bounded version history of its whole configuration (the last 10 versions, with the same merging, sealing and restore behavior as flows). The agent page has a History button, updates accept expected_revision to avoid overwriting concurrent edits (409 revision_conflict), and an execution can run a saved version with the version parameter.

The agent page is also kept in step with changes made elsewhere, such as by the AI assistant or in another tab: while the form has no unsaved edits it reloads the newer content by itself, and a save always carries the revision the form was loaded with, so a stale form can never silently overwrite newer work — you get the revision-conflict dialog instead.

Execution

An agent is executed by creating an execution resource. Every execution runs on the same orchestration engine, so streaming, checkpointing, and reasoning-step visibility apply uniformly whether you're running a single agent or a multi-step flow. See Executions & Streaming.

Guardrails

Guardrails are switches on the agent (guardrails_config, all off by default). They follow the OWASP guidance for LLM applications (LLM01 prompt injection, LLM02 sensitive information disclosure, LLM05 improper output handling) and the "fail securely" principle: a guardrail that is on but cannot work never skips silently. Guardrails are one layer of defence, not a guarantee — keep tools least-privileged and treat model output as untrusted.

SwitchChecksNotes
prompt_injection_shielduser input, before the model callPhrase patterns in English, Turkish, German, French and Spanish, matched after normalization: invisible characters removed, Unicode folded (full-width, look-alike Cyrillic/Greek letters, accents), spaced-out letters, leetspeak, Base64/hex payloads decoded. Catches known phrasings, not every paraphrase.
toxic_content_filteruser input, before the model callOpenAI omni-moderation-latest (multilingual). Needs an OpenAI provider.
pii_redactionanswer, and the stored run inputFixed-format identifiers with checksums, see below.
data_leakage_preventionanswerAPI keys and tokens (OpenAI/Anthropic, GitHub, Slack, Stripe, Google, AWS, JWT, Bearer/Basic), password=/secret=, private-key blocks, credentials inside URLs and secrets in URL query strings.
sensitive_topic_guardanswerAppends a medical/legal/financial disclaimer.
garbled_output_filter, output_injection_guardanswerSee below.

When a guardrail cannot run. The toxic filter calls the OpenAI moderation endpoint, so it needs an OpenAI provider without a custom base URL (custom endpoints, Azure and other vendors do not serve it); the agent's own provider is used when it qualifies, otherwise the oldest OpenAI provider of the project or organization. Saving an agent with the filter on, or starting a run, without such a provider is a 422 with code: "guardrail_unavailable" (toxic_content_filter requires a moderation-capable provider). If the provider disappears or the moderation endpoint cannot be reached while a run is in progress, the request is blocked with that reason rather than answered unchecked (fail-closed). The agent page shows a notice next to the switch.

Observability. Whenever a guardrail blocks a request or changes a response, the run carries a step event with phase: "guardrail", action (blocked | changed), guardrails (the switch names) and content. The same step is kept in the stored run (reasoning.steps), and for flows in the step trace of the Agent node. Comparing a run with a switch on and off therefore shows exactly what it did.

With PII redaction on, e-mail addresses, phone numbers, card numbers (Luhn-checked), IBANs, IP addresses, Turkish national IDs (checksum-checked) and Turkish tax numbers (checksum-checked, only when labelled, e.g. Vergi No:; a bare 10-digit number is too ambiguous) are masked in the response, and in the stored run input once the run ends. This also holds for a flow run whose Agent node uses an agent with the switch on: the flow's stored input and step trace are masked, and so is the Agent node's session memory: it is stored masked, with the original values kept encrypted beside it, so later turns still see them and nothing has to be asked again.

Names and places are deliberately not masked. Detecting them needs a language-specific model, and the ones available to us are unreliable on Turkish: on ordinary Turkish sentences they labelled a person or place in sentences that contained none ("Garanti Belgesi", "Haftaya Salı", "nasıl sıfırlayabilirim") and rewrote "bu isteği yerine getiremiyorum" as <PERSON>. Masking those would corrupt answers while still missing real names, so they are left alone until a Turkish-capable model with an acceptable false-positive rate is available. If you must not store names, do not rely on this switch for them.

The garbled output filter blocks a response that looks corrupted. It checks the prose of the answer (code blocks are exempt) for: raw model control tokens, several writing systems mixed in one passage or inside single words, long runs of the same character or phrase, replacement or unassigned characters, template syntax such as {{ }}, and an abnormal share of symbols (digits, emoji, tables, URLs and valid JSON do not count). The typical catch is the multilingual noise a model produces at temperature 2.0. A blocked response is replaced by a short "Response blocked" message that says why. Independently of this filter, model control tokens and invisible characters are always removed from answers, see Output normalization.

The output injection guard checks the answer for injected-instruction markers (a pattern layer, always on) and, when your administrator has enabled the optional prompt-injection classification model, with that model as well. Without it the guard runs the pattern layer only.

On this page