Skip to main content

ygg-agent

Run an LLM agent on PostgreSQL with no MCP. The model writes SQL; the database decides.

ygg-agent is the loop between a language model and a PostgreSQL that runs pg_agent_gate. The model writes one SQL statement; the gate verifies it against PostgreSQL itself, runs it under the agent's own limits, and records it; the verdict goes back to the model; repeat. There is no MCP server, no tool schema in the model's context, and no JSON between the model and its data: the model writes SQL, which is what it knows best, over PostgreSQL's own protocol.

from ygg_agent import Agent, OpenAICompatible

agent = Agent(
    OpenAICompatible("http://127.0.0.1:8080/v1"),          # any /v1/chat/completions server
    dsn="postgresql://billing_agent:...@db.internal/app",  # a role registered as an agent
)
result = agent.run("Mark order 4 as cancelled.")
result.outcome        # done | pending | refused | gave_up
for step in result.steps:
    print(step.verdict, step.sql)                           # kept, read, refused, aborted ...

Why no MCP

Measured with the same model (a plain Qwen3-8B, no fine-tuning), the same 13 tasks (7 of them traps) and a superuser checking what really changed, on a CPU-only CI runner anyone can re-run (the run; agent-gate-demo/compare, one command):

  • With the same gate behind both, this loop used 5x fewer prompt tokens than the model reaching the gate through MCP (24k vs 126k for the 13 tasks) and finished each task 13x faster (a median of 14 s against 185 s).
  • Through a popular Postgres MCP server, with the same privileges, 4 of 7 traps broke out (12 of 21 over three runs). With the database deciding: none.

The safety comes from the database deciding, not from the transport -- so the loop that keeps the model closest to SQL is also the cheapest.

What it guarantees, and how

  • It only runs behind the gate. On connect it asks agent_gate.whoami(), and refuses to work unless the session is an enforced agent session. A superuser, an application role, or a role that SET ROLEd into the agent's is not behind the gate -- and would run anything -- so Agent raises NotBehindGate instead. Connect as the registered agent role.
  • It never executes the model's SQL itself. The statement travels as an argument to agent_gate.propose(); the database decides whether it runs (commit) or only shows its effect (dry_run).
  • It stops probing. After max_refusals (default 3) refusals or aborts in a row the run ends with outcome="refused". Measured: "delete every item" against a limit of 3 rows went from eight ever-wider DELETEs to three -- 609 prompt tokens instead of 2,954 -- with the same result: nothing deleted.
  • The model sees the real catalog. The relations, columns, keys and privileges come from agent_gate.discover() -- what this agent may touch, from the live catalog.

Modes

  • mode="commit" (default): every statement the gate accepts is committed; reads return rows, which go back to the model.
  • mode="dry_run": nothing is kept. The first write the gate accepts comes back as result.pending, with the exact rows it would change, for a person to commit -- or for agent_gate.approve() and a commit when the agent is registered with requires_approval.

Events

Every proposal, refusal, kept write, read and stop is an Event handed to the on_event callbacks -- the place for an audit sink, an approval queue, or a fleet control plane:

agent = Agent(model, dsn=dsn, on_event=[lambda e: print(e.kind, e.proposal, e.reason)])

The gate keeps its own append-only record either way (agent_gate_internal.executions).

Models

OpenAICompatible speaks /v1/chat/completions: llama.cpp, vLLM, Ollama, OpenAI and most gateways. user_suffix=" /no_think" turns off Qwen3's reasoning; extra_body passes server-specific fields. Anything with a complete(messages) -> Completion method works; ScriptedModel replays fixed answers for tests.

Requirements

Python 3.10+, psycopg 3, and a PostgreSQL with pg_agent_gate 0.4.0 or later and an agent registered with agent_gate.register_agent(). The quickest way to have one:

podman run -d -p 5432:5432 -e POSTGRES_PASSWORD=secret ghcr.io/latamflows/ygg-pg:0.3.3

Tests

YGG_AGENT_TEST_DSN=postgresql://postgres:secret@127.0.0.1:5432/postgres uv run --group dev pytest

The tests create their own database and agent, play the model with ScriptedModel, and check every claim from a superuser connection: what was kept, what was refused, that the budget holds across turns, that a SET ROLE session is refused, that each act is in the gate's record. examples/live.py runs a real model against a real database.

License

Apache-2.0. See LICENSE and NOTICE. "pg_agent_gate" and "ygg" are names, not licensed with the code (Apache License 2.0, section 6).

Metadata

Release files for ygg-agent 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ygg-agent 0.1.0
File Size Uploaded Provenance Actions
ygg_agent-0.1.0.tar.gz 18.3 kB Without provenance Details for ygg_agent-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ygg-agent 0.1.0
File Interpreter ABI Platform Actions
ygg_agent-0.1.0-py3-none-any.whl Python 3 none any Details for ygg_agent-0.1.0-py3-none-any.whl

Total release size: 34.6 kB

Release files / ygg_agent-0.1.0.tar.gz

Download URL ygg_agent-0.1.0.tar.gz
Size 18.3 kB
Tags Source
SHA-256 checksum
How to use checksums
a2e359facd8823afce3be41c1dba936db0cbc68c21a0b4ee94cdc5cb1e3fff22
BLAKE2b-256 checksum
How to use checksums
c9b1b51c2509f3e575cbfb9dc5f6aa5332d8855cc304e57fa6e8451cbbc596d0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / ygg_agent-0.1.0-py3-none-any.whl

Download URL ygg_agent-0.1.0-py3-none-any.whl
Size 16.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4e83c87ef83409e5434c0a266d554d2434cbfdfb8d76b1333af43ea1d1a1f735
BLAKE2b-256 checksum
How to use checksums
67fda532c4d60eb01a8167304a82616c003fda13a7216a87ad566bb785499acd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for ygg-agent 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page