> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamkap.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build an Agent

> Deploy a Streamkap streaming agent step by step — pick an input topic, configure the model, tools, and output schema, preview a run, and deploy

Agents are created in a five-step wizard. This guide walks through each step, previewing a run before you deploy. Open **Agentic → Agents** and click **Deploy an agent**.

## Prerequisites

* An **LLM connection** with the Chat capability — see [Connections](/streaming-agents-connections). The wizard prompts you to add one if none exist. Where available, you can pick the [Streamkap Default LLM](/streaming-agents-connections#streamkap-default-connections) to try an agent without bringing your own key.
* An **input Kafka topic** the agent will read from. Any topic works — from a source, a transform, another agent, or your own producer.
* For the **Streamkap MCP** tool, an agentic-enabled [Project Key](/project-keys).

Deploying and editing agents requires the `write:agents` permission.

## Step 1 — Template

Start from a preset — **Classify**, **Enrich**, **Route**, or **Redact PII** — or choose **Custom Agent** to start from scratch. A preset fills in the system prompt and a matching output schema, so you only name the agent, pick an input topic, and edit from there. Presets are single-pass with no tools; for a multi-step (ReAct) or retrieval (RAG) agent, choose **Custom Agent** and add your own tools or knowledge bases. In edit mode this step is skipped.

| Preset         | What it does                                                                          | Output fields                      |
| -------------- | ------------------------------------------------------------------------------------- | ---------------------------------- |
| **Classify**   | Assigns each record to a single category with a confidence score.                     | `category`, `confidence`           |
| **Enrich**     | Adds derived fields (sentiment, priority, summary) while keeping the original record. | `sentiment`, `priority`, `summary` |
| **Route**      | Chooses a destination for each record, with a short reason.                           | `destination`, `reason`            |
| **Redact PII** | Masks personally identifiable information and flags whether any was found.            | `redacted_text`, `contained_pii`   |

## Step 2 — Input

Set what the agent reads and how records reach the model.

* **Agent name** (required) and an optional **description**.
* **Input topic** (required) — select one topic. An agent reads from exactly one topic.
* **Filter & fields** (optional) — restrict which records the agent processes and which fields reach the model:
  * Build a filter with the **Visual Builder** (field / operator / value rules) or write **Raw SQL**. Use **Preview matching records** to test the filter against recent topic data.
  * Under **Fields sent to the LLM**, choose which fields to include. Fewer fields means lower token cost.
* **Input format** — auto-detected, or set the serialization (JSON or Avro) explicitly.
* **Knowledge Bases** (optional) — attach up to 10 running knowledge bases; the agent gets a retrieval tool for each. See [Knowledge Bases](/streaming-agents-knowledge-bases).

<Note>
  The agent receives each record's value from the input topic. Use **Fields sent to the LLM** to limit which fields reach the model and keep token cost down.
</Note>

## Step 3 — Agent

Configure the model and behavior. Each row opens a side drawer.

### Model

Pick a saved **LLM connection** — the provider, model, and key all come from it. Optionally override per-agent tuning: temperature, max tokens, timeout, and (where the model supports it) reasoning effort and extended thinking.

### System Prompt

Write your **custom instructions** — the guidance that shapes the agent's behavior (up to 8,000 characters). Streamkap assembles the full system prompt from a base template, your output schema, your tools, and these instructions, so the 8,000-character limit applies to your instructions, not the assembled prompt. Use **Generate** or **Refine with AI** to draft or improve them, and **Show base prompt** to see the full assembled prompt.

### Tools

<Info>
  Adding one or more tools turns the agent into a **ReAct** agent — the model can call tools and loop on their results. An agent with no tools is a **Workflow** agent that makes a single LLM pass per record.
</Info>

Click **Add tool** and choose a type:

| Tool              | What it does                                                                                                                                                                                          |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **HTTP**          | Calls an external API. Optionally references an [HTTP connection](/streaming-agents-connections#http-connections) for the base URL and headers. Set method, URL, headers, body template, and timeout. |
| **Script**        | Runs a JavaScript or Python transformation you write inline.                                                                                                                                          |
| **External MCP**  | Calls tools from an [external MCP server](/streaming-agents-connections#external-mcp-servers). Discover tools and choose which to expose.                                                             |
| **Streamkap MCP** | Lets the agent operate your Streamkap platform via an agentic-enabled [Project Key](/project-keys).                                                                                                   |

For HTTP and Script tools, give each a **name**, a **description** (shown to the model so it knows when to call the tool), and any **parameters**. For **External MCP**, discover the server's tools and choose which to expose. For **Streamkap MCP**, select a Project Key that has **Use with agents** enabled, and optionally restrict which platform tools the agent can call — see [Streamkap MCP](/streaming-agents-connections#streamkap-mcp).

### Memory

Optionally carry context across records, keyed by a record field:

* **Short-term** — time-boxed context with a TTL (1 hour, 6 hours, 24 hours, or 7 days).
* **Long-term** — persisted to a vector store connection.

### Processing

* **Max reasoning steps** — the tool-use loop cap for ReAct agents (1–25).
* **Parallelism** — how many records the agent processes concurrently.
* **Checkpoint interval** (advanced) — how often the job checkpoints.

## Step 4 — Output

Define what the agent writes.

* **Output topic** — where results are written (auto-derived from the agent name; editable). Each output topic can be written by only one agent.
* **Output serialization** — JSON or Avro.
* **Output schema** (optional) — declare fields and scalar types (String, Double, Integer (32-bit), Long (64-bit), Boolean; nested objects and arrays aren't supported). The model's response is validated against the schema; records that don't match are routed to the dead-letter topic. With no schema, the raw LLM response is written through.

<Note>
  The **dead-letter topic** is derived automatically as `dlq.<output-topic>` and isn't an editable field. Set up a consumer on it so failed records aren't missed — see [Manage Agents](/streaming-agents-manage#dead-letter-topic).
</Note>

## Step 5 — Review & Deploy

Review the summary cards for each section. Use the pencil on any card to jump back to that step. Then deploy — or save a draft to finish later.

* **Deploy an agent** — deploys the job immediately.
* **Save as Draft** — saves the configuration without deploying. The agent appears with a **Draft** status; deploy it later from the [Agents list](/streaming-agents-manage).

## Preview a Run

Before deploying, use **Preview** to run a single record end-to-end without deploying. Paste a **record (JSON)** — or **Pull from topic** to grab a recent one — and click **Run preview**. Preview runs on **Anthropic**, **OpenAI**, and **Ollama** connections; other providers (Azure, Azure OpenAI, AWS Bedrock, OpenAI Responses) run only once the agent is deployed.

Preview shows the outcome (completed, stopped at the step cap, timed out, or errored), the iterations, tokens in and out, latency, a step-by-step timeline, and whether the output matches your schema.

<Warning>
  A preview makes **real LLM, MCP, and HTTP tool calls** billed to your provider. **Memory and Script tools are not executed** in preview — they only run once the agent is deployed. Each run is capped at 15 seconds and one record.
</Warning>

## After Deploying

The agent starts processing its input topic. Track it from the [Agents list](/streaming-agents-manage), the agent detail page, and [Agent Observability](/streaming-agents-observability). To change a running agent — including offset behavior on redeploy — see [Manage Agents](/streaming-agents-manage).