AI agents

Instead of prose the model returns a structured tool-call block naming the tool, its arguments and a call id. Your code executes the tool, appends a tool-result turn carrying that same id, and calls the model again with the extended history.

The model sees only three things: the tool's name, its natural-language description, and the JSON Schema describing its parameters. Implementation code, docstrings and internal comments never reach it, so everything it needs must live in those three fields.

One assistant turn can carry several independent tool-call blocks. All of them are answered in a single following turn holding one result block per call, each matched by the call id it echoes — never by array position or completion order.

An exception ends the agent's turn; a tool result flagged as an error keeps the loop alive and hands the model a fact it can act on. The model can then fix an argument, pick another tool, or report honestly that the step failed.

Every tool definition is loaded into the prompt at once, so hundreds of them cost tens of thousands of tokens and force the model to discriminate between many near-identical options in a single pass. Crowding plus semantic overlap pushes selection accuracy down.

Thought is the model's reasoning about what to do next, action is the tool call it emits, and observation is the real tool result appended back into the prompt. The loop repeats until the model answers instead of acting.

A written plan survives what the conversation does not. Context gets truncated, summarized or crowded out on long runs, so an external plan file keeps the goal and per-step status stable and re-readable, and doubles as an audit trail of what the agent actually did.

ReAct calls the model once per step and picks each action from the latest observation. Plan-and-execute calls the model once upfront to write the whole step list, then runs those steps with little or no further reasoning.

Detection comes from checking each step against an expected outcome instead of assuming success. Three signals dominate: an explicit tool error, tool output that contradicts an assumption the plan was built on, and a postcondition check on the step's result that fails.

Size each subtask so its completion can be checked objectively and it still fits one focused stretch of work. Too coarse and nobody can tell whether it succeeded; too fine and per-step overhead costs more than the work itself.

Working memory holds what the agent is using right now for the current task. Episodic memory records what happened in past sessions. Semantic memory stores durable facts. Procedural memory holds learned how-to — reusable skills the agent can apply again.

Agentic recall — the agent calling a memory tool when it notices it needs a fact — wins when most turns need no memory and precision matters. Pre-injected top-k wins for a small always-relevant profile and tight latency budgets.

The context window is the input assembled for one model call — bounded, rebuilt by your code every time, and gone afterwards. Memory is durable state stored outside the model that the agent deliberately writes and reads back. Continuity comes from the store, not the window.

Write triggers trade freshness for cost. Per-turn extraction catches everything but adds a model call to every turn. End-of-session extraction is cheaper and better informed. An explicit remember tool is precise but captures only what someone thought to flag.

Every memory read must be constrained by a scope key — user, tenant, session or project — derived from the authenticated session, applied inside the query before ranking. Semantic search has no notion of ownership, so nothing but an explicit filter keeps one user's memories out of another's context.

Gate by blast radius, not by tool name. Anything irreversible, externally visible, or above a value threshold — money movement, production schema changes, outbound messages, deletions — needs a human. Reads and cheaply reversible writes run automatically.

Self-correction needs a signal the model did not produce. Failing tests, compiler errors and schema violations are outside evidence of a defect. Pure self-judgment re-samples the same model that wrote the output, so it rarely catches what it already missed.

Agent loops end naturally when the model returns a final answer with no tool call, or calls an explicit done tool. They end forcibly on a max-iteration cap, a wall-clock deadline, a token or cost budget, or an unrecoverable error.

Persist the loop's state to a durable checkpoint, emit the approval request, and let the process exit. When the human answers — hours or days later, on a different machine — load the checkpoint, inject the decision, and resume from the interrupt point. Never block a thread.

A challenge like "are you sure?" supplies doubt, not evidence. Models tend to go along with implied disagreement, so the second pass often swaps a correct but unusual detail — an exact date, an odd spelling — for a more ordinary-sounding one, lowering accuracy.

Spawning subagents adds no reasoning capacity — it is the same model. The gain is that each worker's noisy intermediate output stays in its own window, so the orchestrator attends to a small set of distilled findings instead of a bloated transcript full of dead ends.

The orchestrator owns the goal: it splits the work, delegates, and assembles the answer. Each subagent runs its own loop in a separate context window, sees only its assigned task, and hands back a short summary rather than its full transcript.

Match the tool to the control you need. LangGraph gives explicit graph control flow with durable checkpointed state for production. CrewAI reaches a working prototype fastest with role-based crews. Vendor SDKs are the shortest path to that provider's newest capabilities.

Isolated workers cannot see each other's decisions, so two of them editing the same artifact make incompatible implicit choices that the orchestrator cannot reconcile from summaries. Keep writes with one designated agent; let the rest return read-only findings or proposals.

It pays when the work is read-heavy, splits into independent parallel pieces, and the result can be checked — research, broad search, breadth-first exploration. It does not pay for latency-sensitive, high-volume or tightly sequential tasks where a single agent or plain workflow is adequate.

Tool-using agents fail in recognizable categories: invented tool names, invalid arguments, the wrong real tool, non-progressing loops, drift from the original goal, and false claims of success. Each has a different fix, so classifying the failure is the first debugging step.

pass^k is the share of tasks an agent solves on all k repeated attempts, so it measures reliability rather than best-case ability. A single run hides variance: roughly 90% per-attempt success clears all 8 attempts on only about 43% of tasks.

Final-answer scoring cannot tell a clean four-step solution from a forty-step flail that stumbled onto the same output, and it credits answers reached by luck. Trajectory metrics score the path: tool choices, ordering, and wasted steps.

Treat the reference trajectory's tool calls as ground truth. Precision is the share of the agent's calls that appear in the reference; recall is the share of reference calls the agent made. Then, on matched calls only, score arguments separately.

A false success claim: the agent narrates completion over a failed side effect. It is dangerous because nothing crashed, so the run looks green while the work never landed. Only an independent post-condition check catches it.