Using knowledge stores

Create the agent

$
ast project create writer-agent --model anthropic
$
cd writer-agent

This generates the starter source and astropods.yml.

Declare the store

Add a knowledge block to astropods.yml:

1
spec: blueprint/v1
2
name: writer-agent
3
4
agent:
5
  build:
6
    context: .
7
    dockerfile: Dockerfile
8
9
knowledge:
10
  writer:
11
    provider: postgres

You only set the provider — no host, port, or password. Supported values: postgres, mysql, redis, qdrant, neo4j, and pinecone.

Read the connection in your code

The connection details arrive as environment variables:

1
import os
2
import psycopg2  # replace with your database driver
3
4
conn = psycopg2.connect(
5
    host=os.environ["POSTGRES_HOST"],
6
    port=os.environ["POSTGRES_PORT"],
7
    user=os.environ["POSTGRES_USER"],
8
    password=os.environ["POSTGRES_PASSWORD"],
9
    dbname=os.environ["POSTGRES_DB"],
10
)

1
import { Pool } from "pg"; // replace with your database driver
2
3
const pool = new Pool({
4
  host: process.env.POSTGRES_HOST,
5
  port: Number(process.env.POSTGRES_PORT),
6
  user: process.env.POSTGRES_USER,
7
  password: process.env.POSTGRES_PASSWORD,
8
  database: process.env.POSTGRES_DB,
9
});

Postgres gives you separate fields, not a single URL. Redis, Qdrant, and Neo4j also get a <PREFIX>_URL variable.

Run it locally

$
ast project start

The CLI starts a Postgres container next to your agent with the same POSTGRES_* variables wired in. Your data persists across restarts. Logs stream in the foreground; Ctrl+C to stop.

Push a blueprint

$
ast login
$
ast blueprint push writer-agent

The blueprint records that the agent needs a writer Postgres store. It does not contain any credentials.

Deploy from the dashboard

Go to Blueprints, find writer-agent, and click Deploy. In the form:

1. Set variables — fill in ANTHROPIC_API_KEY, either as a value or from your vault.
2. Choose how the store is backed — each store has a Local / Shared toggle:
   • Local (default) — the platform creates a managed Postgres database just for this agent.
   • Shared — point the store at a database you’ve connected to the account. One database can back several agents, so they share the same data. Pick it from the dropdown.
3. Deploy — submit the form.

To use Shared, connect the database first under Knowledge > Add store (host, port, database, credentials — stored encrypted). Only matching, Ready stores can be selected. See Knowledge stores for connecting a database in a private network.

The agent then appears under Agents with its live status.