KV Store Read (KV_STORE_READ)

Reads a value that was saved earlier under a name (key). Use it as a step, or connect it to an Agent’s Tools port. It pairs with KV Store Write.

Category: Data Sources · Deployed: yes · Tool-capable: yes

Docker only. The saved values live on the agent server’s own disk. On Kubernetes the agent server refuses a pipeline that runs this module. Use it with agents that run on Docker.

Ports

Port Kind Purpose

Key (in_key)

Input

A JSON object from the previous module with the field key (see below)

Value (out_value)

Output

The result of the lookup as a JSON object (see Result)

Tool (tool_mcp)

Tool

Connect it to an Agent’s Tools port so the agent can look up keys itself

Properties

Field Required Meaning

Collection Name (collectionName)

Yes

The group of saved values to read from. It must match the name in KV Store Write exactly, including upper and lower case. A collection that does not exist yet is simply empty

Static Key (fallback) (key)

No

The key to read when the previous module sends none. Used only as a step. Not used as a tool, because the agent always names the key

If Collection Name is empty, the pipeline cannot be assigned to an agent, and the designer lists the missing field. If a saved pipeline is deployed anyway, the module is left out. If it was connected to an Agent’s Tools port, it is removed from that agent’s tools too.

What the previous module can send (step)

When the previous module sends a JSON object with a text field key, that key is read. If the field is missing or blank, the Static Key is used. Plain text from the previous module is not used as a key. If there is neither a key nor a Static Key, the step fails with an error.

Result

As a step, the output is a JSON object:

Field Meaning

found

true if the key exists, false if not

key

The key that was looked up

value

The saved value. null when nothing was found

collectionName

The collection that was read

A key that does not exist is not an error. The step passes on found: false and value: null.

As a tool

Connected to an Agent’s Tools port, the module gives the agent two functions:

  • kv_read_<collection name>: look up the value of one key. The agent must send key.

  • kv_list_keys_<collection name>: list every key of the collection, with their number. It takes no arguments.

So the agent can first see which keys exist and then read one. The agent gets the same values as in the table above.

Use cases

  • Memory between runs: read what an earlier run saved. A scheduled pipeline with the session mode NEW_EACH_RUN has no other way to carry something forward.

  • Cache: check for a stored result before you do expensive work.

  • As a tool: the agent finds stored context on demand.

Notes

  • Saved values stay with Docker only. The agent keeps them on a volume. They survive stop and start of the agent, and they are deleted when you delete the agent. On Kubernetes the pipeline is refused.

  • The collection is a plain key and value list. You cannot search inside values. Choose keys that you can rebuild later. As a tool, the agent can list the keys.

  • Several agents do not share values. Each agent has its own store.