AI Agents Toolkit (TypeScript + Python)
Agent starters in TypeScript and Python: tool use, memory, MCP and evals.
Who it's for
- You are building an agent into a product or an internal tool and want to start from code you can read, not a framework you have to learn first.
- You need the parts that matter in production: step limits, token budgets, approval before write tools, a trace of every call and evals you can run in CI.
- Your team works in TypeScript, Python or both, and you want the same patterns in each language.
Not for you if you want a no-code agent builder, or if you are committed to a specific agent framework.
What's inside
Two matching codebases built directly on the provider SDKs (Anthropic Messages API and OpenAI Responses API), with no agent framework.
- Agent loop: max steps, a token budget, timeouts, parallel tool calls, tool errors returned to the model, stop reasons and a step trace, with approval for write tools.
- Memory: a conversation window with summary compaction and a long-term store ranked by keywords and recency.
- Structured output: JSON validated with zod or pydantic, with one repair retry and a clean failure.
- Workflows: a router and an orchestrator-workers pattern.
- MCP: a client that turns an MCP server's tools into agent tools, and a demo server.
- Evals: JSONL datasets shared by both languages, six graders (including an LLM judge), a table, a JSON report and an exit code for CI.
- Examples: 7 runnable TypeScript examples and 7 runnable Python examples, one per topic. Every example runs offline with a scripted model when no API key is set.
- Runnable TypeScript examples
- 7
- typescript/examples/01-tool-use.ts
- typescript/examples/02-memory.ts
- typescript/examples/03-structured-output.ts
- typescript/examples/04-router.ts
- typescript/examples/05-orchestrator.ts
- typescript/examples/06-mcp.ts
- typescript/examples/07-evals.ts
- Runnable Python examples
- 7
- python/examples/ex01_tool_use.py
- python/examples/ex02_memory.py
- python/examples/ex03_structured_output.py
- python/examples/ex04_router.py
- python/examples/ex05_orchestrator.py
- python/examples/ex06_mcp.py
- python/examples/ex07_evals.py
- TypeScript library modules
- 28
- typescript/src/agent/approval.ts
- typescript/src/agent/loop.ts
- typescript/src/agent/tools.ts
- typescript/src/agent/trace.ts
- typescript/src/cli.ts
- typescript/src/evals/dataset.ts
- typescript/src/evals/graders.ts
- typescript/src/evals/json-schema.ts
- typescript/src/evals/run.ts
- typescript/src/index.ts
- typescript/src/llm/anthropic.ts
- typescript/src/llm/defaults.ts
- typescript/src/llm/fake.ts
- typescript/src/llm/index.ts
- typescript/src/llm/openai.ts
- typescript/src/llm/provider.ts
- typescript/src/mcp/client.ts
- typescript/src/mcp/demo-server.ts
- typescript/src/memory/store.ts
- typescript/src/memory/window.ts
- typescript/src/smoke.ts
- typescript/src/structured/extract.ts
- typescript/src/tools/calculator.ts
- typescript/src/tools/files.ts
- typescript/src/tools/http-get.ts
- typescript/src/tools/notes.ts
- typescript/src/workflows/orchestrator.ts
- typescript/src/workflows/router.ts
- Python library modules
- 35
- python/agents_toolkit/__init__.py
- python/agents_toolkit/agent/__init__.py
- python/agents_toolkit/agent/approval.py
- python/agents_toolkit/agent/loop.py
- python/agents_toolkit/agent/tools.py
- python/agents_toolkit/agent/trace.py
- python/agents_toolkit/cli.py
- python/agents_toolkit/evals/__init__.py
- python/agents_toolkit/evals/dataset.py
- python/agents_toolkit/evals/graders.py
- python/agents_toolkit/evals/json_schema.py
- python/agents_toolkit/evals/run.py
- python/agents_toolkit/llm/__init__.py
- python/agents_toolkit/llm/anthropic.py
- python/agents_toolkit/llm/defaults.py
- python/agents_toolkit/llm/fake.py
- python/agents_toolkit/llm/openai.py
- python/agents_toolkit/llm/provider.py
- python/agents_toolkit/mcp/__init__.py
- python/agents_toolkit/mcp/client.py
- python/agents_toolkit/mcp/demo_server.py
- python/agents_toolkit/memory/__init__.py
- python/agents_toolkit/memory/store.py
- python/agents_toolkit/memory/window.py
- python/agents_toolkit/smoke.py
- python/agents_toolkit/structured/__init__.py
- python/agents_toolkit/structured/extract.py
- python/agents_toolkit/tools/__init__.py
- python/agents_toolkit/tools/calculator.py
- python/agents_toolkit/tools/files.py
- python/agents_toolkit/tools/http_get.py
- python/agents_toolkit/tools/notes.py
- python/agents_toolkit/workflows/__init__.py
- python/agents_toolkit/workflows/orchestrator.py
- python/agents_toolkit/workflows/router.py
- Offline tests
- 18
- python/tests/test_evals.py
- python/tests/test_graders.py
- python/tests/test_loop.py
- python/tests/test_mcp.py
- python/tests/test_memory.py
- python/tests/test_providers.py
- python/tests/test_structured.py
- python/tests/test_tools.py
- python/tests/test_workflows.py
- typescript/tests/evals.test.ts
- typescript/tests/graders.test.ts
- typescript/tests/loop.test.ts
- typescript/tests/mcp.test.ts
- typescript/tests/memory.test.ts
- typescript/tests/providers.test.ts
- typescript/tests/structured.test.ts
- typescript/tests/tools.test.ts
- typescript/tests/workflows.test.ts
- Eval datasets (JSONL)
- 3
- evals/datasets/extraction.jsonl
- evals/datasets/routing.jsonl
- evals/datasets/tool-use.jsonl
- Guides
- 6
- docs/choosing-a-model.md
- docs/concepts.md
- docs/evals.md
- docs/extending.md
- docs/mcp.md
- docs/safety.md
Files
Files
Files
Files
Files
Files
Files
In the zip · 123 files · 218 KB
- CHANGELOG.md
- LICENSE.md
- README.md
- docs/6 files
- evals/4 files
- python/58 files
- typescript/52 files
Setup
Requirements
- Node.js 22.12 or newer for the TypeScript starters
- Python 3.11 or newer for the Python starters
- An Anthropic or OpenAI API key to run the examples against a real model (the examples also run offline with a scripted model, and the tests need no key)
- TypeScript:
cd ai-agents-toolkit/typescript && npm ci. cp .env.example .envand addANTHROPIC_API_KEYorOPENAI_API_KEY, or leave it empty to run offline.npm run example:tool-use: you see the question, a trace of each model and tool call, an approval prompt for the delete tool, the answer and the token count.- Python: create a virtualenv in
ai-agents-toolkit/python, install the requirements and runpython -m examples.ex01_tool_use. - Run the tests (no API key needed) and the offline evals in either language.
Time to first result: about 2 minutes.
Tested with
Clean-install test passed on 2026-10-01 (darwin-arm64, node 22.23.2, npm 10.9.8, python Python 3.14.3): extract, base, typescript, python, schemas, docs, acceptance.
Licence
You may use this product in unlimited personal and commercial projects, including client work. You may not resell, redistribute, sublicense or share the product itself, in whole or in part, including as a template, starter kit or course material. One purchase covers one person.
The full licence is in LICENSE.md inside the zip. Site terms: /terms.
Questions
When can I buy it?
When the last check is done: the smoke runs of both halves against a live model with an API key. The offline tests already pass on a clean install. I haven't set a date; leave your email above and I'll tell you when it's on sale.
Do I need an API key?
Only for real model runs (Anthropic or OpenAI, billed by the provider). Without a key the examples use a scripted fake model and the tests and offline evals run as normal.
TypeScript or Python?
Pick the language of the project the agent will live in: TypeScript for Node, Next.js, serverless functions and CLIs; Python next to data work, FastAPI or Django services and scheduled jobs. Both halves have the same modules, examples, trace shapes and eval format.
How do updates work?
New versions go to your Gumroad library; download them from there. Changes are listed in the CHANGELOG inside the zip.
Can I use it for client work?
Yes. Agents you build from it, for yourself or for clients, are yours. You can't resell or share the toolkit itself.