Running Agents Without HTTP

Execute agents programmatically for cron jobs, bots, CLI tools, and background workers

Sometimes your agent logic needs to run without an incoming HTTP request. createAgentContext() gives standalone code the same infrastructure that HTTP handlers get automatically: tracing, sessions, and storage access.

Basic Usage

import { createAgentContext } from '@agentuity/runtime';
import chatAgent from '@agent/chat';
 
const ctx = createAgentContext();
const result = await ctx.invoke(() => chatAgent.run({ message: 'Hello' }));

The invoke() method executes your agent with full infrastructure support: tracing, session management, and access to all storage services.

Options

Option	Type	Description
`sessionId`	`string`	Custom session ID. Auto-generated from trace context if not provided
`trigger`	`string`	Trigger type for telemetry: `'discord'`, `'cron'`, `'websocket'`, `'manual'`
`thread`	`Thread`	Custom thread for conversation state
`session`	`Session`	Custom session instance
`parentContext`	`Context`	Parent OpenTelemetry context for distributed tracing

External Cron Job Example

For scheduled tasks managed outside of Agentuity:

import { createApp, createAgentContext } from '@agentuity/runtime';
import cron from 'node-cron';
import cleanupAgent from '@agent/cleanup';
 
await createApp();
 
// Run cleanup every hour
cron.schedule('0 * * * *', async () => {
  const ctx = createAgentContext({ trigger: 'cron' });
 
  await ctx.invoke(async () => {
    await cleanupAgent.run({ task: 'expired-sessions' });
  });
});

Built-in Cron Support

For most scheduled tasks, use router.cron() instead. It handles infrastructure automatically without needing createAgentContext. Use standalone execution only when you need external cron management.

Multiple Agents in Sequence

Run multiple agents within a single invoke() call to share the same session and tracing context:

const ctx = createAgentContext();
 
const result = await ctx.invoke(async () => {
  // First agent analyzes the input
  const analysis = await analyzeAgent.run({ text: userInput });
 
  // Second agent generates response based on analysis
  const response = await respondAgent.run({
    analysis: analysis.summary,
    sentiment: analysis.sentiment,
  });
 
  return response;
});

Reusing Contexts

Create a context once and reuse it for multiple invocations:

const ctx = createAgentContext({ trigger: 'websocket' });
 
// Each invoke() gets its own session and tracing span
websocket.on('message', async (data) => {
  const result = await ctx.invoke(() => messageAgent.run(data));
  websocket.send(result);
});

What's Included

Full Infrastructure Support

Standalone contexts provide the same infrastructure as HTTP request handlers:

Tracing: OpenTelemetry spans with proper hierarchy
Sessions: Automatic save/restore via providers
Threads: Conversation state management
Storage: Full access to kv, stream, vector
Background tasks: waitUntil support for fire-and-forget work
Session events: Start/complete events for observability

Next Steps

Calling Other Agents: Agent-to-agent communication patterns
Cron Routes: Built-in scheduled task support
State Management: Thread and session state

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!