Database Tools

The Database category covers DynamoDB and PostgreSQL integrations. All tools support optional state enrichment to automatically inject session context into stored records.

Table of contents

1. Tools
2. Tool reference
   1. dynamodb_put_item
   2. postgres_insert
   3. postgres_execute
3. State enrichment
4. Environment variables
   1. DynamoDB
   2. PostgreSQL

---

Tools

Tool	Description
dynamodb_put_item()	Write an item to DynamoDB
postgres_insert()	Insert a row into PostgreSQL as JSONB
postgres_execute()	Execute a parameterized SQL query

---

Tool reference

dynamodb_put_item

dynamodb_put_item(
    payload: str,
    table_name: str = "",
    partition_key: str = "",
    sort_key: str = "",
    enrich: bool = False
) -> str

Writes a JSON item to DynamoDB. Falls back to DYNAMODB_TABLE_NAME, DYNAMODB_PARTITION_KEY, and DYNAMODB_SORT_KEY env vars when parameters are omitted. When enrich=True, merges conversation_map.json fields into the item.

Returns: JSON with success (bool), table_name, partition_key, partition_key_value, sort_key, sort_key_value, error

---

postgres_insert

postgres_insert(table: str, payload: str, enrich: bool = False) -> str

Inserts a JSON payload into the specified PostgreSQL table as a JSONB column. When enrich=True, merges session state into the payload before insert.

Returns: JSON with success (bool), table_name, rows_affected, error

---

postgres_execute

postgres_execute(query: str, params: str = "[]") -> str

Executes a parameterized SQL query using %s placeholders. params must be a JSON array of values.

postgres_execute(
    query="UPDATE runs SET status = %s WHERE id = %s",
    params='["completed", 42]'
)

Returns: JSON with success (bool), rows_affected, error

---

State enrichment

When enrich=True, conversation_map.json fields are merged into the item/row before it is written. This is useful for automatically tagging records with session metadata (agent name, correlation ID, etc.).

---

Environment variables

DynamoDB

Variable	Required	Default	Description
DYNAMODB_TABLE_NAME	Yes*	—	Table name (*required unless passed per-call)
DYNAMODB_PARTITION_KEY	No	session_id	Partition key attribute name
DYNAMODB_SORT_KEY	No	—	Sort key attribute name (omit if table has no sort key)
DYNAMODB_ENDPOINT_URL	No	—	Custom DynamoDB endpoint (for local testing with DynamoDB Local)
IS_EVALUATION	No	false	Evaluation mode flag

PostgreSQL

Variable	Required	Default	Description
POSTGRES_HOST	Yes	—	Database host
POSTGRES_NAME	Yes	—	Database name
POSTGRES_USERNAME	Yes	—	Username
POSTGRES_PASSWORD	Yes	—	Password
POSTGRES_PORT	No	5432	Port
POSTGRES_TABLE	No	—	Default table name
IS_EVALUATION	No	false	Evaluation mode flag