# Agent Harness Patterns

> How AI agents work, from scratch: the agent loop, tools, hooks, memory, compaction and subagents, explained level by level with TypeScript and Python code.

The patterns are a track of levels: each one adds a single piece to the agent loop, so read them in order. Every pattern explains the problem, shows the pattern built from scratch in TypeScript and Python, and then the same pattern with astorlm, the open-source TypeScript agent SDK. Each link below is the pattern as clean Markdown.

## Patterns

- [0. Your toolkit](https://harnesspatterns.dev/patterns/your-toolkit.md): The pieces before any agent: the model, the system prompt, the messages you resend, and a first tool.
- [1. What is an agent?](https://harnesspatterns.dev/patterns/what-is-an-agent.md): The difference between calling a model, building a workflow, and letting the model decide what to do.
- [2. Agent Loop](https://harnesspatterns.dev/patterns/agent-loop.md): Call the model, run the tools it asks for, hand back the results, and repeat until it's done.
- [3. Designing a tool](https://harnesspatterns.dev/patterns/designing-a-tool.md): Name, description and schema: all the model ever knows about a tool.
- [4. When to stop](https://harnesspatterns.dev/patterns/when-to-stop.md): end_turn, turn limits and terminal tools: the ways to end the loop.
- [5. Errors in the loop](https://harnesspatterns.dev/patterns/errors-in-the-loop.md): A failing tool doesn't break the agent: the error goes back as a result and the model recovers.
- [6. Streaming and events](https://harnesspatterns.dev/patterns/streaming.md): The reply arrives as it's written, and the loop announces every step to whoever is listening.
- [7. Hooks](https://harnesspatterns.dev/patterns/hooks.md): The points where your code steps into the loop: before each turn, each model call, each tool run.
- [8. Prompt caching](https://harnesspatterns.dev/patterns/prompt-caching.md): Keep the start of every request the same, and the provider reads it from cache: faster and cheaper.
- [9. The backpack fills up](https://harnesspatterns.dev/patterns/compaction.md): What happens when the history no longer fits the context window, and how to compact it.
- [10. MCP](https://harnesspatterns.dev/patterns/mcp.md): Plug in tools from any server with one standard protocol, and discover them when you connect.
- [11. On-demand skills](https://harnesspatterns.dev/patterns/skills.md): A light catalog always at hand, and the full manual only when needed.
- [12. Sessions](https://harnesspatterns.dev/patterns/sessions.md): Save the conversation as it happens, pick it up another day, or fork it to try another path.
- [13. Memory](https://harnesspatterns.dev/patterns/memory.md): Remembering across sessions: saved history, files and search by meaning.
- [14. Fresh laps](https://harnesspatterns.dev/patterns/fresh-laps.md): When the job outgrows one session: a fresh agent each lap, with the progress saved in files.
- [15. Observability and evals](https://harnesspatterns.dev/patterns/observability.md): See what the agent did, what it cost, and whether it did it well.
- [16. Plan and reflect](https://harnesspatterns.dev/patterns/plan-and-reflect.md): Think the plan through before touching anything, and review the result before handing it over.
- [17. Human in the loop](https://harnesspatterns.dev/patterns/human-in-the-loop.md): Ask for permission, take corrections mid-way, and escalate when in doubt.
- [18. Security and sandboxing](https://harnesspatterns.dev/patterns/security.md): Lock up what the agent runs, and distrust what it reads.
- [19. Subagents](https://harnesspatterns.dev/patterns/subagents.md): Hand a subtask to another agent with its own clean context.
- [20. Proactive agents](https://harnesspatterns.dev/patterns/proactive-agents.md): Agents that wake up on their own: a heartbeat, a cheap check first, and a message only when it matters.

## astorlm SDK

- [README](https://raw.githubusercontent.com/aralde/astorLM/main/README.md): install, quick start and the full API of astorlm, as Markdown.
- [Documentation](https://aralde.github.io/astorLM/): the astorlm wiki.
- [npm package](https://www.npmjs.com/package/astorlm): `pnpm add astorlm`.
- [Source code](https://github.com/aralde/astorLM): the GitHub repository.

## Translations

- [Español](https://harnesspatterns.dev/es): every pattern in Spanish, each one also as Markdown at `/es/patterns/<slug>.md`.
- [Português](https://harnesspatterns.dev/pt): every pattern in Brazilian Portuguese, each one also as Markdown at `/pt/patterns/<slug>.md`.
- [Français](https://harnesspatterns.dev/fr): every pattern in French, each one also as Markdown at `/fr/patterns/<slug>.md`.
- [简体中文](https://harnesspatterns.dev/zh): every pattern in Simplified Chinese, each one also as Markdown at `/zh/patterns/<slug>.md`.

## Optional

- [Everything in one file](https://harnesspatterns.dev/llms-full.txt): all patterns concatenated, for a single fetch.
- [Guide for AI agents](https://harnesspatterns.dev/agents): how to connect a coding assistant to these docs.