forge obs verb is a read-only query that returns a JSON document with an exit code and complete next commands, and every log line carries its trace ID. Why this helps an agent explains the design.
Before you begin
- A Forge API deployed to a hosted environment: Deploy a Go API with managed Postgres.
- Forge v1.6.1 or later in the project (
reliant forge --version). obs:readon the organization. Under Reliant, the credential helper grants it from your own account. A CI or automation token needsobs:read, minted at forge.reliantlabs.io/settings/tokens.
ListProducts counts in-stock products with a typo, in_stok, in its SQL.
1
Give the agent the tools
In a Reliant chat there is nothing to set up: the agent’s shell already has Signing in asks which organization, projects and tools the connector may use; revoke it under Settings → Access tokens.
reliant forge, signed in. Ask it to start with reliant forge agent skill load debug, which sets the read-only order this guide follows.In Claude Code or Cursor, add two MCP servers. The local one carries the repo tools (skills, shapes, lint); the hosted Reliant Forge connector carries the telemetry tools (obs_status, obs_issues, obs_issue, obs_logs, obs_traces, obs_check) after you sign in:terminal
.cursor/mcp.json
2
Ask what is wrong now
terminal
Output (trimmed)
api request fails. With --json, its suggested[] names the next commands.3
Read the error logs
The caller sees only
{"code":"internal","message":"internal server error"}. The cause is in the logs:terminal
Output (trimmed)
4
Follow one failing request
List failing traces, then print one as a tree:The database span names the failing statement. With
terminal
Output (trimmed)
--json the document also carries the release live when the trace started (v4.4.0).5
Pull the issue as JSON
--fields keeps only what the agent needs:terminal
Output (trimmed)
handlers_crud.go, found the call into CountInStockProducts, and proposed a one-line fix: in_stok to in_stock. Find the release that caused an error covers issues and releases in depth.6
Reproduce it on your machine
The same verbs read Each JSON line in
dev, your local stack. Start it with reliant forge env up dev, call the RPC, and every log is a file:terminal
Output
api.log carries trace_id, code.file.path and code.line.number, so reliant forge obs trace <id> prints the same tree locally. Browser errors land beside them: grep '\[browser:error\]' .forge/logs/dev/*.log. Stop the stack with reliant forge env down dev.7
Ship the fix and verify it
Review the diff, then cut and deploy a release as usual (The error rate is 0%. The issue’s alert keeps firing until someone resolves the issue, which is triage, not a read. To judge the whole release, run
reliant forge env build prod --release v4.4.1, then reliant forge env deploy prod v4.4.1 --yes). Send traffic and check:terminal
Output
reliant forge obs check prod --wait --json.What this does not do
- The agent only reads.
obsreads change nothing; resolving, assigning or commenting on an issue needsobs:triage, and the agent does not deploy or roll back here. You review the fix and ship it. - There is no automatic rollback. You recover by deploying an earlier or fixed release.
- An alert does not fix itself. Turning alerts into investigated issues and pull requests is two steps with a person between them: Turn production alerts into GitHub issues.
- Reads are rate limited per credential: today, 60 telemetry reads a minute per organization, on a query lane separate from the console, so a looping agent cannot blank your dashboards. Release-health reads (
obs check) get 6 a minute with a burst of 40. A refused read exits 2. - Monitoring needs sign-in; there is no anonymous path. Database rows are a separate grant: Let AI agents query production data.
Troubleshooting
exit 2 from an obs read
exit 2 from an obs read
Forge could not look: a missing
obs:read scope (does not carry the obs:read scope), a rate limit or quota, or telemetry that is off. It does not mean “no errors”. Read the document’s error, fix that, and run the read again. See the exit codes./bin/sh: 1: forge: not found
/bin/sh: 1: forge: not found
env up dev has only reliant forge to call. The fix is in Build a Go and React app.Next steps
Find the release that caused an error
Go from an issue to the release and commits that introduced it, then resolve it.
Let agents query production data
Give an agent read-only, audited SQL against production.
Why this helps an agent
Exit codes, skills,
shapes and the forge MCP server.Querying with forge obs
Every verb, the JSON contract and the exit codes.