AI CLI
Agentic AI — building blocks, the loop, and safe operation
The core parts of an LLM agent — model, tools, state, and a human-approval gate — plus the perceive-plan-act-observe loop and how to test, monitor, and keep it safe.
Quick reference — reach for these first
{"name":"search_docs","description":"Search our docs. Read-only.","input_schema":{"type":"object","properties":{"query":{"type":"string"}},"required":["query"]}}Give the model one typed contract per tool. A strict schema with required fields is what cuts hallucinated args.perceive -> plan -> act -> observe -> repeatEach turn: read state, pick a tool, call it, feed the result back. Stop on done or MAX_STEPS.if tool.side_effects: await human_approve(call)Read-only tools run free; any write/send/delete/pay waits for an explicit human yes.args = Schema.validate(call.input) # reject, don't guessValidate tool input against the schema before running. On failure return an error the model can retry on.success = passed / total # + tool_error_rate, p95_latency, $ / taskScore the agent on a fixed question set before and after every change. 'Seems better' is not a number.The agent loop — model, tools, state, and the approval gate
Text equivalent: An agent loop. The model (an LLM such as Opus 4.x or Sonnet) sits in the center. It perceives from State/memory and writes plans back to it (plan, remember). To act, it either calls Read tools (search, fetch) directly with no gate, or sends a write/send/delete/pay action through a human-approval gate (approve?) that only forwards the call once a human approves. Tool results flow back to the model as the observe step, and the whole cycle repeats until the task is done or a MAX-steps cap is hit.
Common tasks
Concept · Example / pattern · Why it matters
| Concept | Example / pattern | Why it matters |
|---|---|---|
| Model | Opus 4.x for planning; Sonnet for cheap high-volume steps | The reasoning engine. Capability vs cost-per-step is your main tuning lever. |
| Tools | JSON-schema functions the model may call | Tools are the agent's only way to affect the world, so each is an error and attack surface. |
| State / memory | messages[] + a scratchpad or vector store of prior results | Without carried state the agent repeats work and loses the thread across turns. |
| Human-approval gate | pause before any write / send / delete / pay tool | Keeps irreversible actions under a person's control; the core safety boundary. |
| The agent loop | while not done and steps < MAX: plan -> act -> observe | A bounded loop; the MAX cap is what stops runaway behavior when it stalls. |
| Tool-error handling | return {"error": msg} to the model, don't raise | A structured error lets the model correct itself; an exception just ends the task. |
| Retries & timeouts | per-call timeout; retry idempotent reads with backoff | Flaky tools shouldn't hang the loop or duplicate a side effect. |
| Guardrails | allowlist tools; validate inputs + outputs; sandbox | Constrain what the agent can do before trusting what it decides to do. |
| Observability | log every prompt, tool call, args, result, and token count | You can't debug or improve a run you can't replay. |
| Cost controls | cap steps, tokens, and $ / task; alert on breach | Loops and growing context turn into a surprise bill fast. |
| Eval harness | fixed Q&A set scored on every change, as a CI gate | Turns 'feels better' into a measured number and catches regressions before deploy. |
| Prompt-injection defense | treat tool / retrieved output as data, never as instructions | A web page or doc the agent reads can hijack it if the agent obeys text it fetched. |
Worked example — a read-only documentation assistant, from task to monitoring
BUILD IT
SYSTEM = """You answer questions about OUR product docs.
You may ONLY call search_docs. You cannot write, send, or browse the
open web. If the docs don't cover it, say so. Cite the doc path."""
# scope is now a contract, not a hope{"name":"search_docs",
"description":"Search our docs. Returns up to 5 snippets. Read-only.",
"input_schema":{"type":"object",
"properties":{"query":{"type":"string"},
"k":{"type":"integer","maximum":5}},
"required":["query"]}}for step in range(MAX_STEPS): # MAX_STEPS = 6
r = model(messages, tools=[search_docs])
if r.stop_reason != "tool_use": break
args = validate(r.tool.input) # reject bad args
out = search_docs(**args) # read-only call
messages += [r.tool, {"tool_result": out}]cases = load("eval/doc_qa.jsonl") # 40 hand-labeled Qs
for c in cases:
a = run_agent(c.q)
c.pass = c.expected_doc in a.citations and not a.refused
print(f"success {sum(p)}/{len(cases)} tool_err {errs}/{calls}")
# success 34/40 (85%) tool_err 1/58 p95 2.3s $0.004/qmetrics = ["task_success", "tool_error_rate", "p95_latency", "cost_per_task"]
# alert if success < 80% OR cost_per_task > $0.02 OR tool_error_rate > 5%
# week 1: success 88%, tool_err 1.2%, p95 2.1s, $0.005/taskTroubleshooting — symptom → first check → next check
| Symptom | First check | Establishes | Next check |
|---|---|---|---|
| Hallucinated tool args (wrong/invented fields) | Log raw call.input and validate it against the schema | Bad arguments vs a bad tool result | Return a schema error for retry; tighten descriptions and add enums/required |
| Infinite / runaway tool loop | Count steps per task in the logs | Missing stop condition vs no forward progress | Enforce MAX_STEPS and a no-progress detector that breaks the loop |
| Silent tool failure (agent acts on nothing) | Check whether the tool returned an explicit error vs an empty success | A swallowed exception vs a genuinely empty result | Make tools return {"error": ...} explicitly; never return empty on failure |
| Runaway cost / token spend | Break down tokens, steps, and $ per task in the logs | Long growing context vs a step explosion | Cap steps/tokens, prune history, and use a cheaper model for routine steps |
| Prompt injection (agent obeys fetched content) | Did a tool/retrieved result contain instructions the agent then followed? | Untrusted content being treated as commands | Isolate tool output as data, re-assert system rules, and gate every write |
| Low task success on the eval set | Replay the failing cases and group them by cause | A prompt gap vs a tool/retriever gap vs a model gap | Fix the dominant failure class, then re-run the full eval before shipping |
References
- Anthropic — Tool use (function calling)docs.anthropic.com
- Anthropic — Building effective agentsanthropic.com
- Anthropic — Mitigate jailbreaks & prompt injectionsdocs.anthropic.com
- OpenAI — Function calling guideplatform.openai.com
- OWASP — Top 10 for LLM Applications (LLM01 Prompt Injection)genai.owasp.org
Provider-agnostic; examples use a generic LLM tool-use / function-calling API (Claude Opus 4.x / Sonnet shown generically). Pseudocode is Python-ish; placeholders in CAPS; app.shipreadymetrics.com (scm.cc) is a fictional example host.