Building a Claude Code Agent in a Python File

A coding agent like Claude Code relies on an API call loop integrated within a software framework. Here’s what this entails in practice, from prerequisites to local execution, as well as the tooling mechanisms, dialogue with models, and the limits of context and memory.

Running the Agent Locally with a Single Python File

A minimal agent fits into a single file, tiny_agent.py. It requires Python 3.10 or a newer version and does not add any other dependencies. The configuration can be done through a .env file with AGENT_PROVIDER=groq and a GROQ_API_KEY, or without a key by pulling a local model via Ollama (ollama pull qwen3:4b) and then launching python tiny_agent.py -p ollama. The same client can target multiple providers, including Groq, OpenRouter, NVIDIA, or a local engine, by simply modifying the required parameters.

During a session, the interface indicates the provider groq, the model openai/gpt-oss-120b, the ask mode, and an estimate of about ~8/16,000 tokens available. It displays a workspace, offers /help for commands, and exit to quit. An instruction like “create fib.py that prints the first 10 Fibonacci numbers, then execute it” can lead the agent to produce a write_file tool call with JSON path and content arguments. The program is organized around five small classes topped with a fine command line.

What Makes an Agent: Loop, Tools, Rules, Memory, and Interface

The difference between a simple chatbot and an agent lies in the ability to call tools. A model only generates text: it does not read a file or execute a command by itself. Tools are described to the model in JSON format, with their name and expected parameters. When it decides to use them, the model returns a structured JSON instead of a regular response; the host code then executes the actual function and sends back the result as a tool message, which the model reads before deciding on the next steps. In practice, an agent resembles a while loop around an API call, with the rest pertaining to safeguards, memory, and an interface. The same model can behave very differently depending on this framework: tool selection, what enters the context, and authorization rules condition the outcomes.

Dialoguing with Models: Standard JSON and Interchangeable Providers

Interaction with a hosted model occurs through a web API: a JSON is sent, and a JSON is received. A concrete example is a POST to https://api.groq.com/openai/v1/chat/completions with a Bearer authorization, a model name, and a list of messages. The so-called OpenAI chat completions format is accepted by many providers, making the client largely portable. Switching providers is limited to three elements: the URL, the API key, and the model name. Free tiers impose rate limits per minute or per day; beyond that, the service may return a 429 Too Many Requests and a Retry-After header with a delay to observe. A robust client waits for this delay and then retries instead of stopping.

Language Models Predict Each Token Sequentially

A large language model like Claude, Gemini, or GPT does one thing: predict the next token. Systems manipulate tokens rather than words; it can be noted that a token averages about three-quarters of an English word, that a thousand words equate to about 1,300 tokens, and that a rough rule of thumb is four characters per token. The amount of usable information at once depends on the context window: instructions, exchanges, read files, and tool outputs must fit together to be considered. What is not included is invisible to the model. Between two calls, the model has no memory, shifting the responsibility of memory to the application. Long conversations cost more, as they are resent in full with each request, and eventually exceed the available window, necessitating summarization or the exclusion of elements.