Software agents
Read repositories, edit files, run tests and use version control. Their strongest evidence comes from the actual workspace and test results.
Key need: precise scope and verification
THE AI AGENT FIELD GUIDECONCEPTS / DIAGRAMS / PRACTICE VOL. 01
For anyone curious about AI agents
From talking
to doing.
How does a language model become an agent?
Follow the path from next-token prediction to tools, memory and sustained action.
ContextWORKING INPUT
ToolsACTIONS
MemoryRECALL
FeedbackRESULTS
AIModelREASONING CORE
Connect capability to action
NOTE
One idea to rememberAn agent works toward a goal, observes results, chooses the next step and keeps acting until it reaches a valid stopping condition.
IDEA / 001The path through this guide
Conversation->Tools->Action loop->Reusable experience
01 THE STARTING POINT
Start with a model that can continue a conversation.
A model generates tokens from context. An application turns that ability into a structured conversation.
A generative language model predicts the next token from the input and the text already generated. Tokens may be whole words, parts of words, punctuation or characters. The simple prediction objective can produce complex behavior because training captures broad patterns in language, code and other data.
Chat applications arrange messages by role. System or developer messages define application instructions, user messages contain requests, assistant messages contain prior model output, and tool messages carry results from external actions. The exact roles and precedence depend on the model API.
| Role | Purpose |
|---|---|
| system | Platform-level identity and global rules. |
| developer | Application behavior and output constraints when supported. |
| user | The current request and supporting material. |
| assistant | Responses and tool calls produced by the model. |
| tool | Results returned by an external function or service. |
Context is working memory, not unlimited storage
Every instruction, message, tool definition and tool result consumes context. When history grows, the application must remove, summarize or retrieve information selectively. The following simulation uses illustrative units rather than a real model limit.
Interactive context windowIllustrative capacity
42 / 100 unitsContext space available
Fixed instructionsConversation historyFree space
The history is now represented by a shorter summary. Important details may need to be retrieved again.
Add a turn to see how history consumes the context window. These numbers are illustrative.
Key point
A model only sees what the application places in the current request. Memory systems work by selecting useful information and putting it back into context.
02 FROM WORDS TO ACTIONS
Tools let a model affect and inspect the outside world.
The model proposes a structured call. The host validates and executes it, then returns the result.
A tool definition normally contains a name, a description and an input schema. The model does not execute the function itself. It emits a tool call, and the host program decides whether the call is allowed, validates its arguments, performs the operation and records the result.
Tool calling flowHost-controlled execution
User goalWhat should happen?
->Model callTool name and arguments
->HostValidate and execute
->ResultReturn evidence
Illustrative tool definition
{
"name": "read_file",
"description": "Read a file in the active workspace",
"inputSchema": {
"type": "object",
"properties": {"path": {"type": "string"}},
"required": ["path"]
}
}Capability is not permission
A model may know that a delete tool exists, but the host still controls which paths, accounts and operations are permitted.
Results are evidence
A tool result can fail, time out or return incomplete data. The agent must inspect the real status instead of assuming success.
03 A CONNECTION STANDARD
MCP standardizes how hosts connect to tools and resources.
Model Context Protocol separates the agent host from the systems that provide capabilities.
An MCP host manages the user experience and model loop. An MCP client maintains a connection to a server. The server exposes tools, resources or prompts. During initialization the two sides negotiate protocol capabilities; the client can then list available items and call a selected tool.
MCP does not decide what the model should do, run the entire agent loop or replace authorization. It provides a consistent transport and discovery layer. The host remains responsible for model requests, permissions, confirmations and state.
| Part | Responsibility |
|---|---|
| Host | Owns the application, model loop and user controls. |
| Client | Connects one host session to one MCP server. |
| Server | Publishes tools, resources and prompt templates. |
| Transport | Carries protocol messages through local or remote channels. |
When MCP is useful
Use it when a capability should be reusable across compatible hosts, needs structured discovery, or must connect to a long-running service. A small local function may remain simpler when reuse and protocol boundaries add no value.
04 THE ACTION LOOP
An agent repeatedly observes, decides, acts and checks feedback.
The loop matters more than a single clever response.
01ObserveRead evidence
02DecideForm a hypothesis
03ActUse a tool
04FeedbackInspect the result
05Decide againContinue or stop
AGENT LOOP01 / 05
OBSERVE
Inspect what happened
Read the failure and the expected behavior before changing code.
read_file("tests/login.test.js")Observe
Decide
Act
Feedback
Decide again
01 / 05 / Observe
Valid completion
The acceptance criteria are met and the evidence supports the result.
Other valid exits
The agent may wait for input, report a blocker or stop at an explicit safety boundary. A step limit is not proof of success.
05 REUSABLE EXPERIENCE
Skills package repeatable methods for an agent.
A skill explains how to perform a class of tasks and can include scripts, references and templates.
Tools provide actions. Skills provide procedures for choosing and combining those actions. A useful skill states when it applies, what inputs are required, which steps to follow, how to validate the result and when to stop or ask for help.
Progressive disclosure keeps context small: the agent first sees a short skill description, loads the full instructions only when relevant, and opens supporting files only as needed.
LEVEL 1
->Description
When this skill applies
LEVEL 2
->Instructions
The complete workflow
LEVEL 3
Resources
Scripts and references
Skill or MCP?
Use a skill for reusable know-how and local workflow. Use MCP for a reusable service boundary. A skill can call MCP tools, so the two approaches often work together.
06 THE RUNTIME AROUND THE MODEL
The harness turns model output into controlled work.
A model alone is not an agent product.
The harness assembles prompts, exposes tools, executes approved calls, records state, manages retries, compacts context and presents progress to the user. It also defines the boundaries that the model cannot enforce by itself.
Agent harnessORCHESTRATION AND CONTROL
Model adapterTool registryPermission checksState storeContext managerEvent logApproval UIRecovery logic
Human in the loop
Ask for confirmation before consequential, destructive or external actions. Show the exact target and effect, not a vague approval request.
Human on the loop
For lower-risk work, let the agent proceed while keeping progress visible, actions reversible and interruption available.
07 THE AGENT LANDSCAPE
Different agents optimize for different environments.
The same loop can power coding, research, browser work and personal automation.
Research agents
Search multiple sources, extract evidence, compare claims and produce cited summaries.
Key need: source quality and synthesis
Browser and desktop agents
Operate interfaces through screenshots, accessibility trees and input actions.
Key need: state awareness and safe confirmation
Workflow versus agent
Use a fixed workflow when steps and branches are known. Use an agent when the path depends on evidence discovered during execution. Combine them when a reliable outer workflow contains agentic subtasks.
08 CONNECTING TO REAL WORK
A work agent needs identity, systems, knowledge and accountability.
Connecting an agent to a workplace adds operational responsibilities beyond model quality.
A useful work agent combines role instructions, access to approved systems, organizational knowledge, reusable skills, a secure execution environment and a communication channel. The architecture must preserve who requested an action, which credentials were used and what changed.
Work agent architectureConceptual view
Chat or taskRequest and identity
->Agent harnessRules and state
->Skills and MCPMethods and connections
->Business systemsApproved actions
Identity
Map the requesting person and agent service account.
Least privilege
Limit access by task, system and environment.
Audit trail
Record calls, approvals, results and final changes.
Recovery
Make interrupted work resumable and important actions reversible.
09 RELIABLE AGENT ENGINEERING
Reliability comes from boundaries, evidence and feedback.
Better prompts help, but dependable systems also need engineering controls.
Define acceptance criteria
State what must be true before the task is complete.
Limit authority
Give only the tools, data and permissions needed for the task.
Verify real outcomes
Inspect files, API responses, tests and deployed behavior.
Treat failure as state
Report timeouts, partial results and blocked actions explicitly.
Separate data from instructions
Untrusted pages and documents may contain prompt injection attempts.
Keep a useful trace
Log decisions and tool results without exposing unnecessary secrets.
Prompt injection
Content retrieved from the web, email or files can contain instructions aimed at the agent. Treat external content as data, keep trusted policy separate, restrict tools and require confirmation for consequential actions.
10 PRACTICAL GUIDANCE
Give agents useful context without burying the task.
Good agent use is an information design problem.
Put stable project rules in a short entry document and link to focused references. Keep task-specific evidence close to the current task. Load long documentation only when it becomes relevant.
Do not solve uncertainty by adding more instructions indiscriminately. Clarify the goal, expose the right tools, request evidence, and let the agent ask when a business decision cannot be inferred safely.
| Need | Best starting point |
|---|---|
| Stable project rules | Repository instructions |
| Detailed domain knowledge | Focused documentation or knowledge base |
| Repeatable procedure | Skill with validation steps |
| External service connection | MCP server or a direct tool integration |
| Deterministic sequence | Conventional workflow |
THE CORE IDEA
An agent is a model inside a controlled feedback system.
Models choose likely next actions. Tools create effects. The harness enforces permissions and state. Feedback lets the system correct course. People define goals and remain responsible for consequential decisions.
A EXTENSION
Memory, vector retrieval and RAG
Long-term memory is an external information system, not a hidden unlimited context window.
A memory pipeline extracts candidate facts, stores them with metadata, retrieves relevant items for a new task and injects selected content into the prompt. Retrieval-augmented generation applies the same pattern to documents and knowledge sources.
Vector search finds semantically similar chunks, while filters and keyword search can enforce identity, time, project or exact-term constraints. Reranking improves precision. The final answer still depends on what the system selected and how trustworthy the source is.
SourceMessages or documents
->Chunk and indexText, vectors, metadata
->RetrieveSearch and rerank
->ContextSelected evidence
Memory quality
Store only useful information, attach provenance, handle updates and deletion, and prevent one user or project from retrieving another user's private data.
B EXTENSION
Multi-agent collaboration
Multiple agents can explore independent work in parallel, but coordination is not free.
A lead agent can split a goal into bounded subtasks, send each task with the necessary context, wait for results and reconcile conflicts. Subagents should return evidence, limitations and any changes they made. The lead remains responsible for reviewing and integrating the result.
Parallelism helps when subproblems are independent. It hurts when every worker needs the same changing state, repeats the same search or edits overlapping files. More agents also increase model usage, latency and the chance that summaries omit important details.
Use multiple agents when
The work divides cleanly, each result is independently verifiable and the integration cost is controlled.
Prefer one agent when
The task is short, tightly sequential or depends on continuous edits to the same state.
Coordination contract
Define each agent's input, authority, file or system scope, output format, stopping condition and the owner responsible for resolving disagreement.
KEEP EXPLORING
Sources and further reading
This guide teaches concepts. Diagrams, capacities and execution traces are illustrative; check product and protocol documentation for exact behavior.
01
Building effective agentsAnthropic / agents and workflows
Link02Conversation stateOpenAI / context and state
Link03Function callingOpenAI / tool calling
Link04MCP architectureModel Context Protocol
Link05What are Agent Skills?Reusable capabilities
Link06Effective context engineeringContext organization
Link