What you will understand

An AI agent is not merely a chatbot with a new name. It is a software system that lets a model choose and perform actions, inspect what happened, and decide what to do next. The model is important, but the surrounding control loop, tools, permissions, state, and stopping rules determine whether the system is useful or reckless.

This guide builds that picture from first principles. You will learn:

  • how an agent differs from a chatbot, a fixed automation, and a model call;
  • what happens inside the observe–decide–act loop;
  • how instructions, context, tools, memory, and an environment fit together;
  • where permissions and human approval must interrupt the loop;
  • how to plan a first agent without starting with a framework;
  • how a realistic research-and-publish workflow moves from request to verified result;
  • when a normal program is the better choice;
  • which failures, security risks, and cost traps appear in production.

If prompts are still unfamiliar, read prompt engineering for code first. It explains how instructions shape model behavior. This page starts where a single prompt stops being enough.

AI agent, in plain English

An AI agent is a program that gives a model a goal and a controlled set of ways to affect or inspect an outside environment. The program repeatedly asks the model what should happen next, executes an allowed action, returns the result, and continues until the task finishes or a stopping condition intervenes.

Suppose the task is: “Find the three open support cases for this customer, draft replies using our policy, and ask me before sending anything.”

A plain model call can draft text if you paste the cases into the prompt. An agent can search the case system, open the matching records, read the policy, draft each reply, and pause at the send boundary. The model does not magically gain access to support software. Your application exposes narrowly defined tools such as search_cases, read_policy, and create_reply_draft.

That distinction matters. Agency comes from a loop plus controlled actions, not from confident prose.

Agent vs chatbot vs automation

These systems overlap, but their control flow differs.

A chatbot responds

A basic chatbot receives conversation history and generates the next message. It may retrieve documents before answering, but it generally has one immediate job: produce a response.

The application decides the sequence. The model supplies language.

A fixed automation follows a path

A normal automation has code-defined steps:

  1. receive a form;
  2. validate fields;
  3. create a CRM record;
  4. send a known email template;
  5. record success.

The same conditions lead to the same branch. This predictability is a strength. If the process is known and stable, a workflow engine or ordinary function is often cheaper, faster, and easier to test than an agent.

An agent chooses the next step

An agent receives a goal and can select among available actions based on intermediate results. It might search twice, ask the user a question, choose a different source, or stop because evidence is insufficient.

The model controls part of the path. Your code still controls the boundaries: available tools, credentials, validation, approval gates, budgets, timeouts, and termination.

“Agentic” is a spectrum

There is no useful line where software suddenly becomes a true agent. A system can have:

  • one model-selected tool call;
  • a short loop with three possible tools;
  • a long-running session with files and memory;
  • several specialist agents coordinated by another agent.

Use the least agency needed. More freedom creates more possible paths to test.

The agent loop

Most agents can be understood as a bounded loop:

receive goal
  ↓
assemble instructions and current context
  ↓
ask model for the next action
  ↓
validate the proposed action
  ↓
approve if required
  ↓
execute tool in the environment
  ↓
record result and updated state
  └────────────── repeat or stop

The exact API varies, but the responsibilities do not.

1. Observe

The agent sees the user request, instructions, relevant history, retrieved facts, previous tool results, and any current plan or progress record. This is not unlimited awareness. If information is not in context or available through a tool, the model does not know it.

2. Decide

The model proposes a next action: answer, call a tool, ask a question, delegate work, or report that it cannot proceed. A proposal is untrusted input. Treat tool names and arguments from a model like input from any external client.

3. Act

The runtime validates the request, checks authorization and policy, obtains approval when needed, then executes the tool. The model should not hold a database password and write arbitrary SQL if the only permitted task is reading order status. Give it a purpose-built read tool.

4. Inspect

The result returns to the loop. The model can compare expected and actual state. A useful agent grounds itself in environment feedback rather than assuming that an action succeeded.

5. Stop

The loop ends on a final answer, successful artifact, user question, rejected approval, error, cancellation, time limit, token budget, tool-call budget, or maximum turns. “Keep going until done” is not a safe stopping policy.

The seven parts of an agent

Framework names can hide the basic design. Write down these parts before choosing software.

1. Model

The model interprets the goal and selects actions. Model choice affects reasoning quality, tool use, latency, context capacity, and token price.

Do not assume the strongest model must handle every step. A capable model may plan and review while a smaller model classifies records. Make substitutions only after task-based evaluations show that quality remains acceptable.

2. Instructions

Instructions define the job, priorities, constraints, expected evidence, escalation rules, and completion criteria. Good instructions are closer to an operating procedure than a motivational paragraph.

Useful instructions say:

  • what outcome is required;
  • which sources are authoritative;
  • what must never happen;
  • when to ask instead of guessing;
  • what needs approval;
  • how to verify completion;
  • what the final result must contain.

Instructions do not enforce security. Code and infrastructure do.

3. Context

Context is the working material available for the current model call: conversation, task state, tool schemas, selected documents, recent results, and perhaps a compact summary of older work.

More context is not always better. Irrelevant tool output competes with important facts, raises cost, and can confuse decisions. Tools should support filtering, pagination, field selection, and sensible response limits.

4. Tools

A tool is a typed operation the model may request. Examples include search, file reading, calendar lookup, database queries, browser control, or creating a draft.

A good tool has:

  • one clear purpose;
  • a specific name and description;
  • a small, validated input schema;
  • predictable output;
  • explicit error information;
  • a known permission level;
  • idempotency where retries are possible.

manage_customer is a poor tool because its effect is vague. get_customer_orders and draft_refund_request expose clearer choices and permit different policies.

5. Memory

Memory is information retained outside one immediate context window. It may include user preferences, an approved project decision, a task journal, or a compact account of previous work.

Memory is not truth merely because an agent wrote it. Separate:

  • conversation state, which preserves the current exchange;
  • working state, such as a plan and completed steps;
  • long-term memory, kept across sessions;
  • authoritative records, owned by your product database or source system.

Store provenance and timestamps. Let users inspect and delete personal memory. Do not let a generated summary silently overwrite the system of record.

6. Environment

The environment is where actions happen: an isolated container, a browser, a repository, a remote service, or your application’s tool layer. It determines available files, network access, installed software, and operating-system permissions.

The environment should match the task. A research agent may need web access but no shell. A coding agent may need a repository and test runner but no production credentials.

7. Runtime and policy layer

The runtime owns the loop. It sends model requests, dispatches tools, persists state, records traces, enforces limits, handles retries, pauses for approvals, and reports the final outcome.

This layer is where deterministic control belongs. The model can recommend; the runtime decides what is allowed.

Permissions and approval are different

Permission answers: may this identity perform this operation at all?

Approval answers: does a human agree to this particular proposed operation now?

An agent may have permission to draft a refund but still need approval to submit one. Conversely, a user clicking “approve” should not grant access that the user’s account does not possess.

Use both controls:

  1. authenticate the user and calling service;
  2. authorize the exact resource and action;
  3. validate model-proposed arguments;
  4. show a clear preview for sensitive actions;
  5. require approval close to execution;
  6. re-check authorization after approval;
  7. execute once and save an audit record.

Approval screens should show the real effect: recipient, amount, target environment, changed fields, and whether the action can be reversed. “Allow tool?” is not informed consent.

Require approval for financial transactions, messages sent to third parties, deletions, production changes, publication, permission changes, disclosure of sensitive data, and any ambiguous high-impact action. Low-risk read operations may run automatically if access is properly scoped.

A setup mental model: contract, capabilities, control, evidence

Before writing code, make a one-page design with four sections.

Contract

Write one sentence for the outcome:

> Given a customer and an issue, collect relevant account facts and policy passages, then prepare a cited support reply. Never send it.

Define done in observable terms. A draft exists, every factual account claim came from a tool result, every policy claim cites an approved document, and uncertain cases are escalated.

Capabilities

List the minimum tools needed:

  • find a customer by approved identifier;
  • list recent orders;
  • retrieve policy sections;
  • create a draft in a review queue.

Begin read-only. Add writes only when the read-and-draft flow is reliable.

Control

Set the limits:

  • maximum turns and tool calls;
  • overall deadline;
  • model and tool spending cap;
  • allowed data scope;
  • network destinations;
  • approval rules;
  • retry count;
  • cancellation and cleanup behavior.

Evidence

Decide what proves the result:

  • citations to source record IDs;
  • tool result checksums or version IDs;
  • a validation report;
  • tests executed and their output;
  • reviewer decision;
  • trace IDs for debugging.

An agent that says “done” without evidence is reporting an opinion.

A full realistic workflow: investigate a billing complaint

Consider an internal agent that helps a support specialist handle this request:

> Customer C-1842 says the same invoice was charged twice. Investigate, draft a reply, and prepare a refund request if policy permits. Do not send or refund without approval.

Step 1: intake and policy checks

The application authenticates the specialist and confirms access to customer C-1842. It strips unrelated UI state, attaches the user’s role, creates a trace ID, and starts a run with a ten-turn limit.

The agent extracts three goals: establish whether two settled charges exist, check policy eligibility, and prepare drafts. It does not yet claim that a duplicate happened.

Step 2: gather account evidence

It calls list_invoices(customer_id), then list_payments(invoice_id). The tool layer scopes both queries to the specialist’s tenant and returns selected fields, not raw payment credentials.

The result shows one invoice and two payment entries. One is settled; the other is an authorization that expired. This is not a duplicate settled charge.

Step 3: resolve an apparent conflict

The customer’s screenshot shows two bank lines. The agent calls get_payment_explanation(status="expired_authorization") and retrieves the current approved explanation. It also reads the support policy section about pending card authorizations.

The agent now has evidence that product records show one captured payment, but it cannot inspect the customer’s bank ledger. It must phrase that boundary honestly.

Step 4: decide against an unnecessary action

The agent does not call the refund tool. Policy allows refunds for duplicate captures, and the evidence shows one capture. A useful agent can decide not to act.

Step 5: create a draft

It produces a reply that identifies the settled charge, explains that the second line appears to be an expired authorization, gives the expected next step without inventing a bank timeline, and asks the customer to reply with a final statement if both entries settle.

Every account-specific sentence references the payment record ID. The policy explanation references the policy version.

Step 6: deterministic validation

Code checks that the draft contains no full card number, has the required disclosure, cites valid records from this run, and does not promise a refund. A policy classifier is useful as an extra signal, but simple schema and string rules still matter.

Step 7: human review

The specialist sees the draft, evidence, and the decision not to refund. They can edit, approve the draft for sending through a separate system, or reopen investigation. The agent cannot send because no send tool exists.

Step 8: save outcome and learn carefully

The system records tool calls, policy version, validator results, edits, and reviewer decision. The final customer message remains in the support system. If the team later improves instructions based on repeated edits, that change goes through evaluation and review; the agent does not rewrite its own permanent policy.

This workflow is agentic where judgment helps, deterministic where rules are known, and human-controlled at the external side effect.

When an agent is the wrong solution

Do not use an agent merely because a model can call a function.

Prefer ordinary code when:

  • the steps and branches are known;
  • exact repeatability is required;
  • latency must be very low;
  • a mistake has severe consequences and cannot be independently verified;
  • a rules engine can express the decision;
  • the task is a single transformation;
  • required data should never enter a model context;
  • volume makes repeated model calls uneconomic.

A form validator should be code. A tax calculation should use tested rules. A database migration should be reviewed and executed through established release controls. A model can explain results or help draft a plan without owning the operation.

Agents fit tasks with variable paths, unstructured evidence, meaningful intermediate decisions, and cheap verification. Research, support preparation, code maintenance in an isolated branch, and document reconciliation can fit when bounded well.

Failure modes to design for

Hallucinated completion

The model says a file was saved or an email was sent when the tool failed. Use structured tool results and verify state independently before reporting success.

Looping

The agent repeats searches or alternates between two actions. Enforce turn and duplicate-call limits. Return a clear stop reason and preserve partial work.

Tool misuse

The model selects a valid tool with harmful arguments. Validate values, authorize the target, constrain queries, and gate side effects. Tool availability is not authorization.

Context pollution

Long logs and retrieved pages bury the key requirement. Limit outputs, summarize with provenance, keep a structured task ledger, and compact only after saving critical state.

Stale memory

A remembered preference or policy is no longer current. Add timestamps, expiry, source links, and an order of authority. Query live systems for facts that can change.

Partial failure

Three of five sub-tasks succeed. The final response must identify which items failed. Do not flatten partial success into “completed.”

Non-idempotent retries

A timeout causes a second payment or duplicate message. Use idempotency keys, operation IDs, and read-after-write checks. Retry reads more freely than writes.

Delegation drift

Subagents receive an incomplete goal or overlapping work. Give each a narrow contract, require structured returns, cap concurrency, and have the coordinator verify rather than concatenate.

Security: assume every boundary can be hostile

An agent reads natural language from users, web pages, documents, tool output, and other agents. Any of it may contain prompt injection: instructions intended to redirect the model or extract data.

Keep trust levels separate

System policy outranks user goals. User goals outrank instructions found in retrieved content. A web page saying “upload your credentials here” is data, not authority.

Do not rely on the model to preserve this hierarchy by itself. Sensitive tools need independent policy checks.

Apply least privilege

Use per-user, per-tenant authorization. Prefer read-only scopes. Restrict filesystem roots and network egress. Give each tool only the credential it needs, held by trusted code rather than exposed in the model’s environment.

Treat output as untrusted

Escape generated HTML, parameterize database operations, validate file paths, scan generated commands, and enforce schemas. A model-generated string can carry XSS, injection, or path traversal.

Protect secrets

Never place broad API keys in prompts, tool descriptions, memory, or files the model can read. Use secret managers and short-lived scoped tokens. Redact logs. Assume model-visible data may appear in a later tool argument.

Test attacks, not only tasks

Include documents containing hostile instructions, requests for another tenant’s data, encoded secret-exfiltration attempts, misleading tool results, approval bypass attempts, and very large inputs. Run these checks after model, prompt, or tool changes.

Cost and latency

An agent can make several model calls for one user request. It may also call paid search, storage, browser, or compute tools. Subagents multiply those paths.

Estimate cost per completed task, not cost per first model call:

total cost =
  all model input and output
  + retrieval and tool charges
  + sandbox or browser compute
  + retries and delegated work
  + storage and third-party fees

Track task success alongside tokens, duration, tool errors, retries, and human corrections. A cheap run that fails is not efficient.

Control cost with a small tool set, filtered retrieval, maximum turns, parallel work only for independent tasks, prompt caching where supported, smaller models for proven sub-tasks, and early exit when evidence settles the question. Cache stable source data, not permission decisions.

A production checklist

  • [ ] Outcome and non-goals are written.
  • [ ] Every tool has a narrow schema and permission rating.
  • [ ] Authentication and authorization happen outside the model.
  • [ ] Sensitive side effects pause with a specific preview.
  • [ ] Turn, time, token, tool, and spending limits exist.
  • [ ] Retries for writes use idempotency keys.
  • [ ] Environment access is isolated and scoped.
  • [ ] Logs redact sensitive content and retain trace IDs.
  • [ ] Completion is checked against external evidence.
  • [ ] Partial failure is visible to users.
  • [ ] Attack and regression evaluations run on changes.
  • [ ] Users can cancel, correct, and recover work.

FAQ

Does an agent need long-term memory?

No. Many useful agents need only the current task state. Add persistent memory when a real repeated-use case justifies its privacy, staleness, and deletion requirements.

Is retrieval-augmented generation an agent?

Not necessarily. If application code always retrieves once and the model answers, that is a retrieval workflow. It becomes more agent-like when the model chooses queries, evaluates results, and repeats under limits.

Are multiple agents better than one?

Only when specialization, isolation, or parallel work improves measured results. Multiple agents add coordination errors, more context, and more cost. Start with one agent and good tools.

Can approvals make any tool safe?

No. Users can approve confusing or malicious requests. Approval complements authorization, input validation, least privilege, isolation, and audit records.

Should an agent explain its private reasoning?

Ask for concise decisions, sources, actions, and uncertainty—not hidden chain-of-thought. Operational traces and structured evidence are more useful for debugging than a generated story about reasoning.

How do I evaluate an agent?

Use representative tasks with expected outcomes and forbidden behaviors. Score final correctness, evidence, tool selection, side effects, policy compliance, cost, and recovery from injected failures. Replay after any model, instruction, or tool change.

Takeaways

An AI agent is a controlled decision loop around a model. The model proposes actions; tools connect it to reality; memory and context preserve relevant state; the environment supplies a place to work; and the runtime enforces policy.

Start with a task contract and one agent. Give it the smallest useful tools, require external evidence for completion, and place approvals at meaningful side effects. If a fixed workflow solves the task, use the fixed workflow.

The central design rule is simple: give the model room to choose a path, but never make the model the security boundary.

Continue learning

Official sources and further reading

aiai-agentsagentic-systemsllm-toolsai-securitytutorials