Agentuity Docs

Agentuity projects use minimal configuration. Most setup happens in code, not config files.

agentuity.json

The project configuration file:

{
  "name": "my-project",
  "orgId": "org_...",
  "projectId": "proj_..."
}

No agent definitions, no trigger configurations. Those live in your code.

app.ts

The app entry point configures your application:

import { createApp } from '@agentuity/runtime';
 
const { server, logger } = await createApp();
 
logger.debug('Running %s', server.url);

With Lifecycle Hooks

Use setup to initialize resources (databases, clients) and shutdown to clean up:

import { createApp } from '@agentuity/runtime';
 
const { server, logger } = await createApp({
  setup: async () => {
    // Initialize resources, return app state
    // Available in agents via ctx.app
    const db = await connectDatabase();
    return { db };
  },
  shutdown: async (state) => {
    // Clean up resources
    await state.db.close();
  },
});
 
logger.debug('Running %s', server.url);

With Custom Services

import { createApp } from '@agentuity/runtime';
 
const { server, logger } = await createApp({
  // CORS configuration
  cors: {
    origin: ['https://myapp.com'],
    credentials: true,
  },
 
  // Custom storage implementations (optional)
  services: {
    keyvalue: myCustomKV,
    vector: myCustomVector,
  },
});

Event Listeners

Listen for agent and session lifecycle events:

import { createApp } from '@agentuity/runtime';
 
const app = await createApp();
 
app.addEventListener('agent.started', (event, agent, ctx) => {
  app.logger.info('Agent started', { name: agent.metadata.name });
});
 
app.addEventListener('agent.completed', (event, agent, ctx) => {
  app.logger.info('Agent completed', { session: ctx.sessionId });
});

Environment Variables

# Required
AGENTUITY_SDK_KEY=...        # API key for Agentuity services
 
# Optional
AGENTUITY_LOG_LEVEL=info     # trace, debug, info, warn, error
AGENTUITY_PORT=3500          # Dev server port (default: 3500)
 
# LLM Provider Keys (optional; if using your own API keys instead of the AI Gateway)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
 
# Frontend-accessible (exposed to browser)
AGENTUITY_PUBLIC_API_URL=... # Any AGENTUITY_PUBLIC_* vars are bundled into frontend

AI Gateway

If you don't set provider API keys, LLM requests are routed through the Agentuity AI Gateway using your SDK key. This provides unified billing and monitoring.

Public Environment Variables

Environment variables prefixed with AGENTUITY_PUBLIC_ are exposed to the frontend bundle and visible in the browser. Never put secrets or API keys in AGENTUITY_PUBLIC_* variables.

Infrastructure as Code

Unlike traditional platforms, Agentuity defines infrastructure in your route files:

// src/api/index.ts
import { createRouter } from '@agentuity/runtime';
import scheduler from '@agent/scheduler';
import emailHandler from '@agent/email-handler';
 
const router = createRouter();
 
// Cron job - runs every hour
router.cron('0 * * * *', async (c) => {
  await scheduler.run({ task: 'cleanup' });
  return c.text('OK');
});
 
// Email trigger
router.email('support@mycompany.com', async (email, c) => {
  const result = await emailHandler.run({
    from: email.fromEmail(),
    subject: email.subject(),
    body: email.text(),
  });
  return c.text('Processed');
});
 
export default router;

This approach means:

Deployments are self-contained: rolling back restores exact configuration
Version control: your infrastructure changes are tracked in Git
No config drift: what's in code is what runs

Next Steps

HTTP Routes: Define HTTP endpoints
Cron Jobs: Schedule recurring tasks
AI Gateway: Configure LLM providers

Need Help?

Join our Community for assistance or just to hang with other humans building agents.

Send us an email at hi@agentuity.com if you'd like to get in touch.

Please Follow us on

If you haven't already, please Signup for your free account now and start building your first agent!

App Configuration