Agent Builder Kit

A lightweight starter kit to build, test and iterate on OpenAI-powered agents. This repo contains opinionated scaffolding (prompts, agent wiring, and common helpers) to accelerate building agent workflows using the @openai/agents package.

Quick overview

• Opinionated structure for agent projects (prompts, agents, graph helpers).
• Minimal dependencies — the runtime agent functionality uses @openai/agents.
• TypeScript source in src/ so you can iterate with ts-node or a normal build step.

This repository is a developer-oriented kit rather than a published npm package. Use it as a local starting point for building, experimenting and composing agents.

Requirements

• Node.js 18+ (or a recent LTS)
• An OpenAI API key available as the environment variable OPENAI_API_KEY

Install

From the project root:

npm install
# Recommended dev tools for TypeScript development (optional):
npm install --save-dev typescript ts-node @types/node

If you only plan to run compiled JS, add a tsconfig.json and compile with npx tsc before running node.

Environment

Create a .env or export your key in the shell. Example (macOS / zsh):

export OPENAI_API_KEY="sk-..."

Project structure

• src/agents/ — agent composition and exports (glue code that wires prompts, tools and the OpenAI agent runtime).
• src/prompt/ — prompt templates and prompt-building helpers.
• src/common/ — shared utilities, types and helpers.
• src/graph/ — graph/flow utilities for composing multi-step agent flows.

Note: at the time of writing some src files are scaffolds. Implementations should export clear, minimal APIs for other modules and examples.

Usage examples

Below are two ways to run code from this repo while developing. Replace the example paths with real module exports as you implement them.

1. Run TypeScript directly with ts-node (fast for development):

npx ts-node src/someExample.ts

2. Compile and run with tsc + node:

npx tsc
node dist/someExample.js

Example agent wiring (pseudo-code). Adjust to your exports when src/agents is implemented:

// src/examples/runAgent.ts
import { buildAgent } from '../src/agents'
import { createPrompt } from '../src/prompt'

async function main() {
  const prompt = createPrompt({ goal: 'Summarize recent release notes' })
  const agent = buildAgent({ apiKey: process.env.OPENAI_API_KEY })
  const result = await agent.run(prompt)
  console.log(result.output)
}

main()

If you prefer using @openai/agents directly, the kit's helpers should make it easier to plug prompts and tools into the agent runtime.

Development notes

• Add small, focused exports to src/agents, src/prompt and src/common so consumers (examples/tests) can import them.
• Keep the public surface small and stable; prefer composition over single large entrypoints.

Recommended dev scripts you can add to package.json:

"scripts": {
  "build": "tsc",
  "dev": "ts-node src/examples/runAgent.ts",
  "lint": "eslint . --ext .ts,.js"
}

Testing

There are no tests yet. Add a small test harness (Jest, Vitest, or even node-based scripts) that exercises the agent wiring with a fake/mock OpenAI client for fast CI.

Contributing

1. Fork and create a feature branch.
2. Open a PR with a clear description and a short demo/example showing how to use what you added.

Tips:

• Add a minimal example under src/examples/ that can be run with npx ts-node.
• When adding breaking changes, update README usage and examples.

License

This project is currently licensed under ISC (see package.json).

Troubleshooting

• If you see runtime errors related to missing types or ts-node, install the recommended dev dependencies above.
• If OpenAI calls fail, verify OPENAI_API_KEY is set and valid.

---

If you'd like, I can also:

• Add a tsconfig.json and a minimal example file under src/examples/ and a dev script so npm run dev works.
• Add a basic Makefile or package.json scripts for a complete dev flow.

Tell me which you'd prefer and I’ll add it.