Use Orloi with AI agents ​

Orloi writes operational history into your Postgres database. AI agents can use that history to answer questions, prepare updates, investigate unusual activity, or suggest process improvements.

This guide explains how to give an agent safe read-only access to Orloi data.

The basic rule ​

Do not give an AI agent your application owner database connection string.

Create a dedicated read-only database role for agent access. Give that role access only to the orloi schema, then use that role when connecting agents, MCP servers, internal tools, notebooks, or dashboards.

Choose the right connection method ​

How you provide the connection depends on where the agent runs.

Local coding agents ​

Use this for tools that run on your machine or inside your development environment, such as local coding agents, terminal agents, or editor agents.

Store the read-only connection string in an environment variable:

bash
export ORLOI_DATABASE_URL="postgresql://orloi_agent_reader:password@db.example.com:5432/app_database?sslmode=require"

Then prompt the agent using the variable name, not the raw connection string:

text
Use the Orloi SKILL.md instructions.

Connect to Postgres using ORLOI_DATABASE_URL from the environment.
Analyze sync_id syn_123 for the last 14 days.

Summarize unusual activity, repeated manual edits, open alerts, and metrics that changed.
Do not print or expose the database connection string.
Do not dump raw payloads.
Include the tables and time window you used.

You do not need to paste the connection string into every prompt. Configure it once in the agent environment, shell, project secrets, or local .env workflow.

Do not commit .env files or connection strings to source control.

MCP-based agents ​

Use this when your AI tool supports MCP.

Configure a Postgres MCP server with the read-only Orloi connection string. The connection string should be passed to the MCP server as a secret or environment variable, not typed into normal chat prompts.

The agent then talks to the MCP server, and the MCP server talks to Postgres.

This is usually the cleanest setup because the credential belongs to the tool configuration, not the conversation.

Still use a read-only database role. MCP makes connection setup more natural, but it does not replace database permissions.

Hosted or cowork-style agents ​

Use this for agents that run in someone else's hosted environment and do not clearly expose secure secret handling.

Do not paste a raw database connection string into a normal chat message.

Use one of these safer options instead:

  • a managed secrets feature, if the product provides one;
  • an MCP connector configured outside the conversation;
  • a small internal API that exposes only the specific Orloi queries you allow;
  • a bounded export from Orloi, such as a report or time-limited CSV;
  • a temporary read-only credential that can be revoked after use.

If the product does not make credential handling clear, assume the chat content is not the right place for database credentials.

Internal apps and custom agents ​

If you are building your own agent, dashboard, notebook, Slack workflow, or internal tool, store the read-only Orloi connection string in your normal secret manager.

The application should connect to Postgres directly using the read-only role.

Keep the read path and action path separate. Orloi can provide context, but you should separately decide which systems the agent is allowed to change.

Create a read-only connection ​

Run this from an admin or owner database connection.

Replace the role name and password before running it:

sql
create role orloi_agent_reader
  login
  password 'replace-with-a-long-random-password';

grant usage on schema orloi to orloi_agent_reader;
grant select on all tables in schema orloi to orloi_agent_reader;
grant select on all sequences in schema orloi to orloi_agent_reader;

alter default privileges in schema orloi
  grant select on tables to orloi_agent_reader;

alter default privileges in schema orloi
  grant select on sequences to orloi_agent_reader;

Then create a connection string for that role:

text
postgresql://orloi_agent_reader:replace-with-password@db.example.com:5432/app_database?sslmode=require

Use this connection string only for agent analysis and custom read-only tools.

What should agents query first? ​

For most agent workflows, start with derived Orloi data rather than raw events.

Good starting points:

  • compacted events;
  • metrics;
  • reports;
  • process summaries;
  • alerts;
  • collaborator and automation summaries.

Raw events are useful when the agent needs audit-level detail or must explain exactly which source changes support a conclusion.

Example questions ​

Agents can use Orloi data to answer questions such as:

  • What changed for this account before the escalation?
  • Which deals are repeatedly moving backward?
  • Which records have stalled longer than usual?
  • Which handoffs happen most often?
  • Which process steps look repetitive enough to automate?
  • What should an agent know before drafting an update?
  • Which metric values changed, and which raw events contributed to those values?
text
Use the Orloi SKILL.md instructions.

Connect to the read-only Orloi database using the configured connection method.
Analyze sync_id syn_123 for the last 14 days.

Answer these questions:

1. What unusual activity happened?
2. Which records or processes appear stalled?
3. Which metrics changed meaningfully?
4. Which repeated manual edits may be candidates for automation?
5. Which raw events support the most important conclusions?

Do not expose credentials.
Do not dump raw payloads.
Prefer compacted events, reports, metrics, and summaries before raw events.
Include the tables and time window you used.

Security checklist ​

Before giving an agent access, check that:

  • the agent uses a dedicated read-only database role;
  • the role has access only to the Orloi objects it needs;
  • the connection string is stored as a secret, environment variable, or MCP configuration;
  • the connection string is not pasted into normal chat unless there is no better option;
  • the agent is instructed not to print credentials or raw payloads;
  • any action-taking workflow uses a separate, explicitly approved action path;
  • temporary credentials can be revoked when no longer needed.

Treat the orloi schema as Orloi-managed. If an agent writes its own analysis back to Postgres, keep those objects in a separate schema unless you have explicitly designed an integration with Orloi-managed tables.