specialagent 😎
An agent is just something that acts (agent comes from the Latin agere, to do). Of course, all computer programs do something, but computer agents are expected to do more: operate autonomously, perceive their environment, persist over a prolonged time period, adapt to change, and create and pursue goals.
Designed with educational use in mind, this agent harness is intentionally only a few hundred lines of readable, dependency-free Python. It acts on its environment by running shell commands and receives output of those commands as percepts to drive subsequent actions.
Features
- Tool use. The agent has 4 tools:
exec- Runbashcommandswrite- Overwrites the contents of a filereplace- Find and replace in file
- Prefetching to make obvious tools calls before calling an LLM
- Run
cat {filename}for any mentioned files that exist - Run
cat {skill.md}for any skills mentioned by name near the start of the prompt - Run
cat makefileand similar for common project files
- Run
Security
This package allows LLMs to directly execute shell commands. It should never be used without appropriate sandboxing.
Usage
uvx specialagent
or
pipx specialagent
Configuration
In its default configuration, the agent will attempt to use the model hosted at http://127.0.0.1:8080/v1/chat/completions (the llama.cpp default). Alternatives may be provided by env variables. For example, to use Gemma 4 31B hosted on AI Studio:
export LLM_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/chat/completions
export LLM_API_KEY=your-api-key-here
export LLM_MODEL=gemma-4-31b-it
1 maintainer
Release files for specialagent 0.17.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| specialagent-0.17.0.tar.gz | 6.4 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| specialagent-0.17.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 12.7 kB
Release files / specialagent-0.17.0.tar.gz
| Download URL | specialagent-0.17.0.tar.gz |
|---|---|
| Size | 6.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
59b7d268962ea3234a2bf8f36cef6347bc7c0c05f9f8d5e6b984eb11c3273a0f
|
|
BLAKE2b-256 checksum How to use checksums |
d6756991b61a6b755ddfefe19e1d00a388b094222f6ab8ff2307b9a4eb647aa0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / specialagent-0.17.0-py3-none-any.whl
| Download URL | specialagent-0.17.0-py3-none-any.whl |
|---|---|
| Size | 6.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7588cd4fff8e04d59a1ffe326b0206f1158289b1f1d6fb9f5a04318e372ec255
|
|
BLAKE2b-256 checksum How to use checksums |
24cf5afdafea36206d7035394132977446a0e6807f4900474a02c6f18443add2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
