Build your first AI agent from scratch in Python: a web research agent

An open-source web research agent implemented in a single Python file without an agent framework has been released under the Apache-2.0 license alongside an essay on the Humanbound blog. As reported in github.com's report, the program runs with httpx as its sole runtime dependency installed via uv. It equips an execution loop with four tools: search Wikipedia, fetch a page, save a note, and read notes, storing findings across runs in a local SQLite file.

This report analyzes the architecture, execution mechanics, evaluation methods, and network attack surfaces of single-file agent implementations. It is intended for software engineers, security analysts, and AI developers seeking to evaluate autonomous tool usage without third-party framework layers. By examining agent.py, model dependencies, and offline testing harnesses, technical practitioners can understand how autonomous agents maintain state and where unhardened retrieval logic introduces operational risk into developer environments.

Build your first AI agent from scratch: what actually changed

The release introduces agent.py as a functional reference architecture that eliminates complex agent orchestration libraries in favor of a straightforward loop. Operating with httpx as its single dependency, the script communicates with any OpenAI-compatible API endpoint. Configuration is managed through environment variables including AGENT_BASE_URL, AGENT_API_KEY, and AGENT_MODEL, with gpt-4o-mini acting as default. Users can direct traffic to OpenRouter using openai/gpt-5.6-luna or execute locally through Ollama with llama3.1:8b. When supplied with PRICE_IN_PER_MTOK and PRICE_OUT_PER_MTOK rates, the trace calculates estimated costs from API usage metadata.

The repository contains recorded execution traces, model answers, and message histories saved on 23 October 2026 within the examples directory. A hardening review pass improved the codebase by strengthening the HTML extractor, refining SQLite queries, improving error handling inside run_tool, and rewording the read_notes tool description. The first-attempt directory preserves early trial runs recorded before read_notes matched on any word. In the postfix directory, two consecutive runs execute the hardened code against the same prompt, with the second run successfully reading notes stored during the initial search.

Build your first AI agent from scratch: how it works

The research workflow centers on four specific tools: search Wikipedia, fetch a page, save a note, and read notes. Invoked with a command line query, uv runs agent.py while separating operational logging from primary output. Diagnostics stream to standard error, final conclusions print to standard output, and passing dump messages.json exports conversational history. The agent enters an execution cycle governed by MAX_STEPS and TOKEN_BUDGET, terminating automatically once boundaries are reached. Discovered findings are inserted into a SQLite file, establishing durable cross-session recall without requiring an external database server.

Testing avoids external API calls by running pytest alongside a scripted local mock server, requiring neither an active network connection nor secret keys. Performance during tool calling varies based on model capacity. In a logged trial using Ollama with llama3.1:8b, the model attempted to answer a query on prompt injection history relying exclusively on search snippet text rather than fetching the underlying web page, generating an incorrect response. Meanwhile, measure_pages.py generates page-sizes.txt, tracking token loads across web pages by dividing character lengths by four to monitor context consumption.

Build your first AI agent from scratch: why it matters now

Operating an autonomous web retrieval agent introduces critical security challenges because all fetched text originates from untrusted public web pages. Adversarial content can steer the model through prompt injection payloads embedded in retrieved HTML. Because notes persist inside the local SQLite database across runs, poisoned content recorded during a compromised search remains saved on disk. This persistent storage can mislead subsequent agent runs on entirely different topics, transforming a single compromised web page into a recurring source of model manipulation. Such persistent vectors demonstrate the necessity of validating stored memory.

Network interactions carry additional operational hazards. The fetch_url tool accepts public addresses but rejects private and loopback destinations, while intentionally refusing to follow HTTP redirects so that every network hop is verified independently. However, the system resolves a domain name during the initial verification check, while the HTTP client resolves it a second time when establishing the actual connection. This gap creates an opening for DNS rebinding attacks, where an adversarial DNS server passes initial validation before redirecting the connection to an internal private address.

Build your first AI agent from scratch: who is affected

Engineers implementing autonomous web retrieval tools are directly impacted by the operational boundaries exposed in this design. By foregoing large framework wrappers, developers obtain unmediated access to agent internals but must independently handle cost containment and data exfiltration controls. Because fetch_url requests any public address, queries carrying outbound data in URL query strings can leak confidential information. In addition, the script does not check robots.txt directives, creating compliance and scraping issues for developers deploying retrieval loops against external web servers without custom rate-limiting or permission filters.

Security teams auditing autonomous AI pipelines face novel verification hurdles with stateful agents. The Humanbound open-source testing tool evaluates agents over HTTP, finding vulnerabilities that it is specifically configured to test. However, clean evaluation results from Humanbound do not constitute proof of safety against unmodeled attacks. Teams relying on small local language models like llama3.1:8b are also affected by tool calling deficiencies, which cause systems to bypass retrieval tools and deliver inaccurate conclusions, forcing teams to rely on commercial model endpoints for dependable research execution.

Build your first AI agent from scratch: what to watch

Engineers deploying this architecture in production must address several network and execution limitations. A robust production implementation must connect directly to the specific IP address validated during initial checks, eliminating the window for DNS rebinding. Operators should also monitor cost controls, as total expense in agent.py is constrained solely by MAX_STEPS and TOKEN_BUDGET. Tracking API usage numbers and setting PRICE_IN_PER_MTOK alongside PRICE_OUT_PER_MTOK allows teams to audit model expenditures, though external billing caps remain necessary to prevent unexpected resource exhaustion. Developers must examine these parameters before running deep recursive research.

Future evaluations will track whether small local models improve their tool selection and parameter generation capabilities. The project demonstrates that gpt-4o-mini handles tool calling reliably, whereas local instances like llama3.1:8b fail to invoke multi-step retrieval. Released under the Apache-2.0 license, this unhardened codebase provides a clear baseline for reading agent logic before placing trust in automated workflows. As developers adapt the code, community inspection of run_tool error handling, HTML extraction routines, and SQLite note queries will determine how well minimal agents balance simplicity with operational resilience.