{"id":50573247,"url":"https://github.com/anthony-maio/agent-harness-90m","last_synced_at":"2026-06-04T20:01:28.969Z","repository":{"id":358687979,"uuid":"1242588688","full_name":"anthony-maio/agent-harness-90m","owner":"anthony-maio","description":"Minimal agent harness: task intake, tool registry, policy gate, budget, logs, reports. Companion repo for Build Your First Agent Harness in 90 Minutes.","archived":false,"fork":false,"pushed_at":"2026-05-18T16:21:03.000Z","size":17,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T17:14:25.371Z","etag":null,"topics":["agent-harness","ai-agent","ai-safety","llm","python","tool-use","tutorial"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anthony-maio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-18T15:05:17.000Z","updated_at":"2026-05-18T16:21:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/anthony-maio/agent-harness-90m","commit_stats":null,"previous_names":["anthony-maio/agent-harness-90m"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/anthony-maio/agent-harness-90m","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthony-maio%2Fagent-harness-90m","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthony-maio%2Fagent-harness-90m/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthony-maio%2Fagent-harness-90m/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthony-maio%2Fagent-harness-90m/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anthony-maio","download_url":"https://codeload.github.com/anthony-maio/agent-harness-90m/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthony-maio%2Fagent-harness-90m/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33917184,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-harness","ai-agent","ai-safety","llm","python","tool-use","tutorial"],"created_at":"2026-06-04T20:01:27.299Z","updated_at":"2026-06-04T20:01:28.962Z","avatar_url":"https://github.com/anthony-maio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agent-harness-90m\n\nA minimal agent harness in Python. Task intake, tool registry, policy gate, budget enforcement, structured logging, and post-run reports -- everything an LLM agent needs to run safely except the model itself.\n\nBuilt as the companion repo for [Build Your First Agent Harness in 90 Minutes](https://anthonymaio.substack.com).\n\n## Quickstart\n\n```bash\ngit clone https://github.com/anthony-maio/agent-harness-90m.git\ncd agent-harness-90m\npip install -e .\ncp .env.example .env\n```\n\nAdd your keys to `.env`:\n\n```bash\nOPENAI_API_KEY=sk-...          # or any litellm-supported provider\nBRAVE_API_KEY=BSA...           # free: https://brave.com/search/api/\n```\n\nRun the example task:\n\n```bash\npython agent.py run tasks/example_research.md\n```\n\nDry run (no LLM calls, just parse and validate):\n\n```bash\npython agent.py run tasks/example_research.md --dry-run\n```\n\nAuto-approve all policy prompts (for trusted tasks):\n\n```bash\npython agent.py run tasks/example_research.md --yes\n```\n\n## How it works\n\n```\ntask.md -\u003e runner -\u003e LLM -\u003e tool calls -\u003e policy gate -\u003e executor -\u003e log\n                      ^                        |\n                      |                        v\n                   memory \u003c--------------- evaluator\n```\n\n1. You write a task in Markdown (what to do, which tools, what's blocked, when it's done)\n2. The runner hands it to an LLM with tool definitions from the registry\n3. Every tool call passes through the policy gate before execution\n4. The budget tracker kills the run if limits are hit\n5. Everything gets logged as structured JSONL\n6. A Markdown report is generated when the run ends\n\n## Project structure\n\n```\nagent-harness-90m/\n  agent.py              # CLI entry point\n  harness.yaml          # Main config (model, tools, policy, budget)\n  harness/\n    runner.py           # Main agent loop\n    task.py             # Task file parser\n    tools.py            # Tool registry and execution\n    policy.py           # Policy gate and approval prompts\n    budget.py           # Budget enforcement\n    logger.py           # Structured JSONL logging\n    memory.py           # File-based memory layer\n    report.py           # Post-run report generation\n  tools/\n    read_file.py        # Read files from workspace\n    write_file.py       # Write files to workspace\n    list_files.py       # List workspace directory contents\n    web_search.py       # Brave Search API (free tier, stub fallback)\n    summarize.py        # LLM-based text summarization\n  tasks/\n    example_research.md # Example: research brief\n    example_digest.md   # Example: weekly digest\n  policies/\n    default.yaml        # Default policy rules\n  logs/                 # JSONL logs (gitignored)\n  reports/              # Run reports (gitignored)\n  memory.md             # Persistent memory file\n```\n\n## Writing tasks\n\nTasks are Markdown files with four sections:\n\n```markdown\n# Task\nWhat the agent should do.\n\n# Allowed tools\n- tool_name_1\n- tool_name_2\n\n# Cannot do\n- blocked_action_1\n\n# Done means\n- completion criterion 1\n- completion criterion 2\n```\n\nSee `tasks/example_research.md` for a working example.\n\n## Adding tools\n\n1. Create a Python file in `tools/` with `NAME`, `DESCRIPTION`, `PARAMETERS`, and `execute()`\n2. Add the tool to `harness.yaml` under `tools:` with a risk level\n3. The registry auto-discovers it on the next run\n\n## Configuration\n\nEverything lives in `harness.yaml`:\n\n- **model** -- provider, model name, temperature, max tokens\n- **budget** -- max LLM calls, tool calls, wall-clock seconds\n- **tools** -- tool names, descriptions, risk levels\n- **policy** -- approval requirements, blocked tools, workspace boundary\n- **logging** -- log file paths\n- **memory** -- memory file path\n\n### Local models\n\nFor Ollama or other local providers, change the model config:\n\n```yaml\nmodel:\n  provider: \"ollama\"\n  name: \"llama3.2\"\n```\n\nNo API key needed. The harness uses litellm, so any supported provider works.\n\n## Dependencies\n\n- [litellm](https://github.com/BerriAI/litellm) -- unified LLM API (supports OpenAI, Anthropic, Ollama, OpenRouter, Azure, and 100+ others)\n- [pyyaml](https://pyyaml.org/) -- config parsing\n- [python-dotenv](https://github.com/theskumar/python-dotenv) -- env file loading\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanthony-maio%2Fagent-harness-90m","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanthony-maio%2Fagent-harness-90m","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanthony-maio%2Fagent-harness-90m/lists"}