Reference Architecture for Trustworthy Agentic AI Systems
The command line, long an imperative tool of fixed commands (ls, grep, git), is becoming agentic. Tools like Gemini CLI, Claude Code, and Auto-GPT let you state a goal in natural language; the agent plans, calls tools, iterates, and asks for approval. The CLI is a clean lens on trustworthy agentic design because it exposes every stage in the open — and because, underneath the brand names, these tools share one architecture.
The through-line: most agentic tools follow the same pattern — capture intent, assemble context, plan, execute tools behind guardrails, then render results. Planning styles differ (ReAct for exploration, plan-and-execute for predictable multi-step work, JSON runners for scripted pipelines), so choose by task, not brand. And success depends as much on contracts and scoping — versioned context files, explicit path scopes, sandboxing — as on the model itself.
Why the CLI is a distinct niche
Chat interfaces and agentic IDEs get more attention, but the CLI meets developers where they run infrastructure and git: the shell. Its headless, composable nature lets it chain system commands in ways a GUI-bound agent can’t — though the line blurs as CLI agents integrate with editors like VS Code for diff views.
A worked example
Consider bootstrapping a repository with standard docs and scripts. Instead of hand-writing each file, one instruction drives the whole thing:
Add a CONTRIBUTING.md, a PULL_REQUEST_TEMPLATE.md, and a scripts/smoke-check.sh that runs a configurable command and exits non-zero on failure; update the README to document both, and open a PR.
The stages below trace that prompt from intent to pull request.
Stage 1: Intent capture and context
Before planning, the agent grounds itself in the project. It links the task to the working directory, manages session state, and reads per-project config from dotfolders (/.gemini, /.claude) so recurring settings don’t need flags. Beyond the prompt, it pulls from several implicit signals:
Context files. Markdown files describing how the repo is built, tested, and conventioned — onboarding docs for the agent (GEMINI.md, CLAUDE.md):
# GEMINI.md (excerpt)
## 1. Project Philosophy
This is a High-Performance SaaS Backend.
* **Core Principle:** Readability over cleverness. Explicit is better than implicit.
* **Architecture:** Hexagonal Architecture (Ports & Adapters).
* **Safety:** Zero-trust security model. All inputs must be validated via Pydantic.
## 2. Tech Stack & Standards
* **Language:** Python 3.11+ (Strict Typing required).
* **Framework:** FastAPI (Async default).
* **Database:** PostgreSQL (via SQLAlchemy 2.0 async session).
* **Testing:** Pytest (Coverage must remain >90%).
Skills. Rather than stuffing every instruction into context, some tools package expertise as modular folders (a SKILL.md each). Progressive disclosure keeps this cheap: the agent sees only skill names and descriptions up front, and reads the full instructions only when a task needs them — generalist by default, specialist on demand.
Codebase signals. The agent scans for existing scripts/, .github/, README.md, and language artifacts like pyproject.toml for a high-level read of conventions.
IDE focus. Optionally, open files and selections from a connected editor.
Stage 2: Planning styles
With context loaded, each tool runs its control loop differently:
- ReAct (Gemini) — think, call a tool, observe, repeat. Great for discovery, like finding missing folders or policies, and for adapting mid-task.
- Plan-and-execute (Claude) — propose a checklist you approve, then execute step by step with policy hooks. More control and transparency, because you review the plan first.
- JSON runner (Auto-GPT) — emit thoughts plus a command as JSON that a runner executes each cycle. Machine-readable, easy to automate and integrate.
Claude — plan preview:
Plan:
1. Create scripts/smoke-check.sh (POSIX sh; reads CMD from env; exits non-zero on failure)
2. Create CONTRIBUTING.md (how to run smoke check locally)
3. Create .github/PULL_REQUEST_TEMPLATE.md (checklist includes smoke check)
4. Update README.md with scripts/ and PR template instructions
5. Run smoke-check; commit; open PR
Approve? [y/n]
Auto-GPT — explicit JSON with thoughts and commands:
{
"thoughts": {"text": "Create smoke-check, docs, template; update README; run script; commit/PR"},
"command": {"name": "write_file", "args": {"path": "scripts/smoke-check.sh", "content": "#!/bin/sh\n: \"${CMD:=echo ok}\" \n$CMD || { echo \"smoke failed\" >&2; exit 1; }\necho \"ok\""}}
}
Stage 3: Tool calls and MCP
The agent uses its tools to propose changes — for example, showing a diff via a file-edit tool:
*** scripts/smoke-check.sh
+#!/bin/sh
+set -eu
+# CMD can be overridden: CMD="make test" ./scripts/smoke-check.sh
+: "${CMD:=printf ok}"
+$CMD >/dev/null 2>&1 || { echo "smoke failed" >&2; exit 1; }
+echo "ok"
Tooling has shifted from bespoke integrations to an open standard: the Model Context Protocol (MCP). Backed by multiple vendors, MCP is a universal port for AI applications — instead of hardcoding an integration per database or API, you run local MCP servers (PostgreSQL, Slack, GitHub) that the agent discovers at startup. One agent can then query a database, read tickets, and edit code in a single workflow. Policy stays explicit through mechanisms like Claude’s hooks (restrict write paths, auto-chmod, run lint/tests after writes) or Gemini’s extensions — different knobs, same outcome.
Stage 4: Human-in-the-loop guardrails
You keep control of risky actions. Gemini requires approval before side-effecting writes or shell commands. Claude offers confirmations and hooks that block policy-violating writes or run checks first. Auto-GPT pauses for yes/no unless continuous mode is on. For exploration, a containerized sandbox isolates the file system and processes.
Stage 5: Execution and iteration
Once files exist, the agent runs the script and adjusts to the outcome. Missing scripts/ directory? Gemini creates it and retries. Script not executable? A Claude hook applies chmod +x. The loop of observe-reason-act repeats until execution succeeds and the docs are complete.
Stage 6: Rendering and stopping
The CLI shows a syntax-highlighted view of tool calls and diffs. You can open diffs in your editor to tweak manually or instruct the agent to revise. Batch approvals are most efficient — review all scripts and docs together before one sign-off. On a clean smoke check with approved diffs, the agent branches, commits, and opens a draft PR.
Using agentic CLIs well
- Treat context files as build assets. Keep
GEMINI.md/CLAUDE.mdbeside your README, concise and focused on build/test steps, config locations, gotchas, and safe-to-edit directories. Program the environment for the agent rather than re-prompting it every time. - Scope aggressively. Point the agent at the folder that matters (
services/payments/, not the whole monorepo) and pass explicit@filehints. Tighter scope means tighter diffs, fewer hallucinations, and faster iterations. - Sandbox to prevent accidents. Gemini CLI offers ephemeral containerized execution; Claude Code typically runs in dev containers or routes actions through a containerized runner; Auto-GPT has no sandbox flag but should run inside Docker.
- Match the tool to the task. Gemini CLI for discovery-heavy, generalist work in the Google ecosystem; Claude Code for concrete plans, robust coding, and policy enforcement; GitHub Copilot CLI for fast natural-language-to-shell; Aider or Open Interpreter for local models, tight git ergonomics, or an unrestricted shell.
- Prompt like an engineer. Use a four-part contract: goal, constraints, required artifacts, success checks. Not essays.
- Instrument it. Track PR cycle time, agent diff size, and rework percentage to tune both the agent and your operating contracts.
Where this is heading
Agentic CLIs are becoming connective tissue across tools, OS, and cloud:
- Unified surfaces — IDEs and operating systems merging (Windsurf, Cursor).
- Persistent background services — daemon agents that monitor and fix errors proactively.
- Extension ecosystems — “app stores” for agent capabilities, blurring generalist and specialist.
Keep going
Beneath the varying brand names, agentic tools share one architectural DNA — and trustworthiness comes not from the model alone but from the contracts, scopes, and approval gates wrapped around it.
