create-agentuity 0.0.3 → 0.0.4

package/AGENTS.md

@@ -2,25 +2,199 @@
 
 ## Commands
 
-- **Build**: `bun run build` (compiles agents, APIs, and web app)
-- **Dev server**: `bun run dev` (starts development server at http://localhost:3000)
+- **Build**: `bun run build` (compiles your application)
+- **Dev**: `bun run dev` (starts development server)
 - **Typecheck**: `bun run typecheck` (runs TypeScript type checking)
-- **Install**: `bun install`
 
 ## Architecture
 
-- **Runtime**: Bun-based Agentuity server app using Hono framework
-- **Structure**: Agent-based architecture with agents in `src/agents/<name>/`
-- **Entry point**: app.ts creates server via `@agentuity/server`
-- **Build output**: `.agentuity/` contains generated code (app.js, etc)
-- **Agent pattern**: Each agent has `agent.ts` (handler + schema) and optional `route.ts` (HTTP routes)
-- **Dependencies**: Uses Zod for validation, Hono for routing, @agentuity packages for framework
+- **Runtime**: Bun server runtime
+- **Framework**: Hono (lightweight web framework)
+- **Build tool**: `@agentuity/bundler` compiles to `.agentuity/` directory
+- **Frontend**: React with `@agentuity/react` hooks
+
+## Project Structure
+
+```
+{{PROJECT_NAME}}/
+├── src/
+│   ├── agents/          # Agent definitions
+│   │   └── hello/       # Example "hello" agent
+│   │       ├── agent.ts # Agent handler
+│   │       └── route.ts # Agent HTTP routes
+│   ├── apis/            # Custom API routes
+│   │   └── status/      # Example status endpoint
+│   └── web/             # React web application
+│       └── app.tsx      # Main React component
+├── app.ts               # Application entry point
+├── tsconfig.json        # TypeScript configuration
+└── package.json         # Dependencies and scripts
+```
 
 ## Code Style
 
-- **TypeScript**: Strict mode, ESNext target, bundler moduleResolution, allowImportingTsExtensions
-- **Imports**: Use @agentuity/\* for framework imports, relative paths for local modules
-- **Agents**: Export default agent from agent.ts, define Zod schemas for input/output
-- **Routes**: Use createRouter() from @agentuity/server, access agents via c.agent.<name>.run()
-- **Validation**: Use @hono/zod-validator for request validation
-- **Naming**: Agent folders are lowercase, use camelCase for variables/functions
+- **TypeScript-first** - All code is TypeScript
+- **Async/await** - All agent handlers are async
+- **Zod schemas** - Use Zod for input/output validation
+- **Functional** - Prefer functional patterns over classes
+- **Type-safe** - Leverage TypeScript generics and inference
+
+## Creating Agents
+
+### Agent Structure
+
+Each agent should be in its own folder under `src/agents/`:
+
+```typescript
+// src/agents/my-agent/agent.ts
+import { type AgentContext, createAgent } from '@agentuity/server';
+import { z } from 'zod';
+
+const agent = createAgent({
+  schema: {
+    input: z.object({
+      message: z.string()
+    }),
+    output: z.object({
+      response: z.string()
+    }),
+  },
+  handler: async (ctx: AgentContext, input) => {
+    // Use ctx.logger for logging (not console.log)
+    ctx.logger.info('Processing message:', input.message);
+    
+    // Access storage
+    await ctx.kv.set('last-message', input.message);
+    
+    return { response: `Processed: ${input.message}` };
+  },
+});
+
+export default agent;
+```
+
+### Agent Routes (Optional)
+
+Add custom HTTP routes for your agent:
+
+```typescript
+// src/agents/my-agent/route.ts
+import { createRouter } from '@agentuity/server';
+import { zValidator } from '@hono/zod-validator';
+import agent from './agent';
+
+const router = createRouter();
+
+// GET endpoint
+router.get('/', async (c) => {
+  const result = await c.agent['my-agent'].run({ message: 'Hello!' });
+  return c.json(result);
+});
+
+// POST endpoint with validation
+router.post('/', zValidator('json', agent.inputSchema!), async (c) => {
+  const data = c.req.valid('json');
+  const result = await c.agent['my-agent'].run(data);
+  return c.json(result);
+});
+
+export default router;
+```
+
+## Agent Context API
+
+Every agent handler receives an `AgentContext` with:
+
+- `ctx.logger` - Structured logger (use instead of console.log)
+- `ctx.tracer` - OpenTelemetry tracer for distributed tracing
+- `ctx.sessionId` - Unique session identifier
+- `ctx.kv` - Key-value storage interface
+- `ctx.objectstore` - Object/blob storage
+- `ctx.stream` - Stream storage
+- `ctx.vector` - Vector embeddings storage
+- `ctx.agent` - Access to other agents
+- `ctx.waitUntil()` - Defer cleanup tasks
+
+## Adding API Routes
+
+Create custom routes in `src/apis/`:
+
+```typescript
+// src/apis/my-route/route.ts
+import { createRouter } from '@agentuity/server';
+
+const router = createRouter();
+
+router.get('/', (c) => {
+  return c.json({ status: 'ok' });
+});
+
+export default router;
+```
+
+## Frontend Development
+
+Use `@agentuity/react` hooks to call agents from your React components:
+
+```typescript
+// src/web/app.tsx
+import { useAgent } from '@agentuity/react';
+
+function MyComponent() {
+  const { data, run } = useAgent('hello');
+
+  const handleClick = async () => {
+    const result = await run({ name: 'World' });
+    console.log(result);
+  };
+
+  return (
+    <div>
+      <button onClick={handleClick}>Call Agent</button>
+      {data && <div>{data}</div>}
+    </div>
+  );
+}
+```
+
+## Best Practices
+
+- **Use structured logging** - Always use `ctx.logger`, never `console.log`
+- **Validate inputs** - Define Zod schemas for all agent inputs/outputs
+- **Handle errors** - Use try/catch and return meaningful error messages
+- **Type everything** - Leverage TypeScript for type safety
+- **Keep agents focused** - One agent should do one thing well
+- **Use storage abstractions** - Use `ctx.kv`, `ctx.objectstore`, etc. instead of direct database access
+
+## Environment Variables
+
+Create a `.env` file in the project root:
+
+```env
+# Example environment variables
+API_KEY=your-api-key
+DATABASE_URL=your-database-url
+```
+
+Access them in your code:
+
+```typescript
+const apiKey = process.env.API_KEY;
+```
+
+## Deployment
+
+Build for production:
+
+```bash
+bun run build
+```
+
+The compiled application will be in `.agentuity/`. Deploy this directory to your hosting provider.
+
+## Learn More
+
+- [Agentuity Documentation](https://agentuity.dev)
+- [Bun Documentation](https://bun.sh/docs)
+- [Hono Documentation](https://hono.dev/)
+- [Zod Documentation](https://zod.dev/)

package/README.md

@@ -2,57 +2,142 @@
 
 A new Agentuity project created with `create-agentuity`.
 
-## Getting Started
+## What You Get
 
-### Install Dependencies
+A fully configured Agentuity project with:
 
-```bash
-bun install
-```
-
-### Build
+- ✅ **TypeScript** - Full type safety out of the box
+- ✅ **Bun runtime** - Fast JavaScript runtime and package manager
+- ✅ **Hot reload** - Development server with auto-rebuild
+- ✅ **Example agent** - Sample "hello" agent to get started
+- ✅ **React frontend** - Pre-configured web interface
+- ✅ **API routes** - Example API endpoints
+- ✅ **Type checking** - TypeScript configuration ready to go
 
-Build your application with:
+## Project Structure
 
-```bash
-bun run build
+```
+my-app/
+├── src/
+│   ├── agents/          # Agent definitions
+│   │   └── hello/
+│   │       └── agent.ts # Example agent
+│   ├── apis/            # Custom API routes
+│   │   └── route.ts     # Example route
+│   └── web/             # React web application
+│       └── app.tsx      # Main React component
+├── app.ts               # Application entry point
+├── setup.ts             # Initial setup script
+├── tsconfig.json        # TypeScript configuration
+├── package.json         # Dependencies and scripts
+└── README.md            # Project documentation
 ```
 
-This will compile your agents, APIs, and web application into the `.agentuity` directory.
+## Available Commands
 
-### Development Server
+After creating your project, you can run:
 
-Start the development server:
+### Development
 
 ```bash
 bun run dev
 ```
 
-Your app will be available at http://localhost:3000
+Starts the development server at http://localhost:3000
 
-### Typecheck
+### Build
 
-Run TypeScript type checking:
+```bash
+bun run build
+```
+
+Compiles your application into the `.agentuity/` directory
+
+### Type Check
 
 ```bash
 bun run typecheck
 ```
 
-## Project Structure
+Runs TypeScript type checking
 
-- `src/agents/` - Agent definitions
-- `src/apis/` - API routes
-- `src/web/` - Web application (React)
-- `app.ts` - Application entry point
+## Next Steps
+
+After creating your project:
+
+1. **Customize the example agent** - Edit `src/agents/hello/agent.ts`
+2. **Add new agents** - Create new folders in `src/agents/`
+3. **Add API routes** - Create new routes in `src/apis/`
+4. **Customize the UI** - Edit `src/web/app.tsx`
+5. **Configure your app** - Modify `app.ts` to add middleware, configure services, etc.
+
+## Creating Custom Agents
+
+Create a new agent by adding a folder in `src/agents/`:
+
+```typescript
+// src/agents/my-agent/agent.ts
+import { type AgentContext, createAgent } from '@agentuity/server';
+import { z } from 'zod';
+
+const agent = createAgent({
+	metadata: {
+		description: 'My amazing agent',
+	},
+	schema: {
+		input: z.object({
+			message: z.string(),
+		}),
+		output: z.object({
+			response: z.string(),
+		}),
+	},
+	handler: async (ctx: AgentContext, input) => {
+		return { response: `Processed: ${input.message}` };
+	},
+});
+
+export default agent;
+```
+
+## Adding API Routes
+
+Create custom routes in `src/apis/` or add routes to an agent folder:
+
+```typescript
+// src/agents/my-agent/route.ts
+import { createRouter } from '@agentuity/server';
+import { zValidator } from '@hono/zod-validator';
+import agent from './agent';
+
+const router = createRouter();
+
+router.get('/', async (c) => {
+	const result = await c.agent.myAgent.run({ message: 'Hello!' });
+	return c.json(result);
+});
+
+router.post('/', zValidator('json', agent.inputSchema!), async (c) => {
+	const data = c.req.valid('json');
+	const result = await c.agent.myAgent.run(data);
+	return c.json(result);
+});
+
+export default router;
+```
 
 ## Learn More
 
 - [Agentuity Documentation](https://agentuity.dev)
 - [Bun Documentation](https://bun.sh/docs)
+- [Hono Documentation](https://hono.dev/)
+- [Zod Documentation](https://zod.dev/)
 
-## Next Steps
+## Requirements
+
+- [Bun](https://bun.sh/) v1.0 or higher
+- TypeScript 5+
+
+## License
 
-1. Edit `src/agents/hello/agent.ts` to customize your agent
-2. Add new routes in `src/apis/`
-3. Customize the web interface in `src/web/app.tsx`
-4. Deploy your application to production
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "create-agentuity",
-	"version": "0.0.3",
+	"version": "0.0.4",
 	"module": "index.ts",
 	"type": "module",
 	"files": [