Prompt: build a simple AI agent with tool calls (framework-agnostic)

# Prompt: build a simple AI agent with tool calls (framework-agnostic)

Give this prompt to your coding agent (or a chat assistant) to build a small, working agent from scratch.
It describes the agent loop itself, so it works with any model API that supports tool calling (also called function calling).
Fill in the brackets first.

---

Build a small, working AI agent with tool calling. Keep it simple and readable: one main file plus one file for tools. Do not use an agent framework; write the loop yourself so I can understand every step.

## What the agent should do
- Goal: [e.g. "Answer questions about my local Markdown notes and create new notes on request"]
- Tools it needs: [e.g. `search_notes(query)`, `read_note(path)`, `create_note(title, body)`]
- Language and runtime: [Python 3.11+ | TypeScript on Node.js 20+]
- Model provider: [PROVIDER AND MODEL NAME]. Use the provider's official SDK at the version I have installed, and check its documentation for the exact tool-calling request and response format. Do not guess field names.
- Interface: [command-line chat loop | single command with an argument | small HTTP endpoint]

## Architecture
1. Tool registry. Each tool has a name, a one-sentence description written for the model, a JSON Schema for its parameters, and a plain function that implements it. The registry produces the tool definitions in the format the provider expects.
2. Agent loop:
   - Send the system prompt, the conversation so far and the tool definitions to the model.
   - If the model returns tool calls, validate the arguments against the schema, run each tool, and append each result to the conversation in the format the provider expects (matched to its tool call ID if the API uses IDs).
   - If the model returns a final answer with no tool calls, print it and stop.
   - Repeat, with a hard limit of [8] steps per user request. If the limit is reached, stop and tell the user what was done so far.
3. System prompt. Write a short one that states the agent's goal, when to use each tool, that it must not invent tool results, and that it should ask the user when a request is ambiguous.

## Safety and reliability
- Tools that change things (write, delete, send, pay) must ask the user to confirm in the terminal before they run. Read-only tools can run without asking.
- Restrict file tools to one folder: [PATH]. Reject paths that escape it (for example with `..`).
- Catch tool errors and return them to the model as a short error message, instead of crashing, so the model can recover or explain.
- Truncate long tool results (for example to [4,000] characters) and say that they were truncated.
- Read the API key from an environment variable (for example `[PROVIDER]_API_KEY`) and fail with a clear message if it is missing. Never print the key or write it to a log.
- Add a timeout to every network call.

## Observability
- Log each step to the console in a readable way: the step number, which tool was called with which arguments, a short preview of the result, and the token usage if the API returns it.
- Add a `--verbose` flag that also prints the full messages sent to the model.

## Deliverables
1. The code, with a short README: setup, environment variables, how to run it, and how to add a new tool.
2. Unit tests for each tool function and for argument validation, which do not call the model.
3. One test of the loop that uses a fake model client returning scripted tool calls, so the loop can be tested offline.
4. A list of three example requests I can try, and what the agent should do for each one.

Work step by step: first show me the file structure and the tool schemas, wait for my approval, then write the code.