@readysetcloud/agent

One agent. Every app.

This is the AI agent behind everything in Ready, Set, Cloud. I wanted one place to go whenever I need an agent, whether it’s a chat window in a dashboard or something that runs at 2 AM while I’m asleep. Three of its four types run on a shared service you call. The fourth is a build tool you run yourself.

Start here

Which agent do you need?

Answer a question or two and I’ll point you at the right page. (No JavaScript? All four answers are listed below.)

Side by side

The four types, compared

Picked one already? Here’s how it stacks up against the others.

Where each agent type runs SHARED SERVICE · HOSTEDANYWHERE · LIBRARYYOUR STACK · BUILD TOOLChatbrowser conversationcreateAssistantTaskone run, result eventrunAgentTaskOne-shottyped answerrunAgentPersistent agentwoken · paced · keeps goals and promisesdefinePersistentAgentroutehandleTaskemitCheckInyour router · task Lambda · cron · tablewss + Cognitoreadysetcloud.agenta function callagency.<name>
Chat and tasks run on the shared rsc-core service. A one-shot is a function call you can make from anywhere. A persistent agent is a build tool: definePersistentAgent hands your app the handlers, and your stack runs them under the agent’s own event source.
ChatTaskOne-shotPersistent agent
What it isA conversation streamed to a browser“Do this, then tell me”One stateless call, one typed answerA long-lived agent with a job to do
Started byA person opening a socketAn API call or a Run Agent Task eventYour code calling runAgentYour trigger rules and its own scheduled check-ins
IdentityThe verified userA user, or an allowlisted systemWhatever your code passesIts own: system <type>/<agentId>, with a persona
LivesOne session (snapshots ~30 days)One runOne callIndefinitely: state carries across every run
KeepsSnapshots, per-user memoryA task row with the resultNothingAn agenda, commitments, cooldowns
Paces itselfNoNoNoYes: cooldowns and human-like delays
Runs onShared runtimeShared task LambdaAnywhereYour stack
Entry pointcreateAssistantrequestAgentTask, runAgentTaskrunAgentdefinePersistentAgent
In the wild

What people build with it

These are real patterns running across the ecosystem today. The tag tells you which type each one is built on.

Quick start

Copy, paste, go

Install it, then pick a tab.

npm install @readysetcloud/agent

Node 22 or newer. If a Lambda doesn’t need the Strands runtime, import from ./memory or ./agency and it stays out of your bundle. Full details are on npm.

import { requestAgentTask } from '@readysetcloud/agent/memory';

// Fire and forget from any first-party Lambda. All it needs is events:PutEvents.
const { taskId } = await requestAgentTask({
  principal: { type: 'system', id: 'newsletter' },
  request: 'Summarize this week’s new blog comments as three bullets.',
});
// Listen for "Agent Task Completed" with this taskId.
# As the signed-in caller. Waits up to ~25s for the answer.
curl -X POST "$CORE_API_URL/agent/tasks" \
  -H "Authorization: Bearer $ID_TOKEN" -H "Content-Type: application/json" \
  -d '{"request":"Summarize this week’s new blog comments.","wait":true}'
import { Chat } from '@readysetcloud/ui/chat';

// getConnectionUrl returns the socket URL plus the bearer subprotocol (see the Chat guide).
const { sessionId } = await authed('/agent/sessions', { systemPrompt });
<Chat sessionId={sessionId} userId={user.sub} getConnectionUrl={getConnectionUrl} title="Assistant" />
import { runAgent } from '@readysetcloud/agent';
import { z } from 'zod';

const { output } = await runAgent({
  input: draft,
  systemPrompt: 'You are a grammar and spelling reviewer.',
  outputSchema: z.object({ suggestions: z.array(z.object({ span: z.string(), fix: z.string() })) }),
});
import { definePersistentAgent } from '@readysetcloud/agent/agency';

export const reviewer = definePersistentAgent({
  name: 'reviewer',
  profile: (agentId) => loadReviewer(agentId),          // persona + pacing, or null
  rules: { 'Pull Request Opened': { kind: 'review', agents: ({ detail }) => detail.reviewers, request: ({ detail }) => `Review #${detail.pr}` } },
  checkIn: { agents: () => listReviewerIds() },
  tasks: { review: (ctx) => review(ctx), check_in: (ctx) => followUp(ctx) },
  observe: async (ctx) => ({ needs: await openReviewRequests(ctx.agentId) }),
});

export const route = (event) => reviewer.route(event);            // your router Lambda
export const task = (event) => reviewer.handleTask(event.detail); // your task Lambda
import { runAgent, createAssistant, runAgentTask } from '@readysetcloud/agent';  // the runtime
import { requestAgentTask, createSession } from '@readysetcloud/agent/memory';   // Strands-free data plane
import { routeTrigger, reconcileAgenda } from '@readysetcloud/agent/agency';     // Strands-free agency
Under the hood

How a request gets around

Three rules shape everything here. Identity is verified at the edge. Behavior comes from data. Results leave as events.

Architecture: callers, identity edge, hosts, and the shared agent core CALLERSEDGE · IDENTITYHOSTSAGENT COREBrowsersigned-in userApp or workflowcalls the CoreApiFirst-party backendschedule · workflowJWT authorizerAgentCore inboundCoreApiCognito authorizerDefault event busaccount-internalAgentCore Runtimechat · WebSocketRunAgentTaskFunctiontasks · in-Lambda@readysetcloud/agentBedrock modelany model idToolsregistry · MCPDynamoDBsessions · tasks · stateAgentCore Memoryper user · chat123456789
Every path checks identity at the edge, then runs the same @readysetcloud/agent core. Chat streams back over its socket. Tasks announce their result on the bus. The steps play in order, so pause it if you want to take in the whole picture.
  1. 1Before connecting, the app creates a session (POST /agent/sessions) and asks for a socket URL (POST /agent/connect).
  2. 2The browser opens wss:// with its Cognito ID token as the bearer subprotocol.
  3. 3The inbound JWT authorizer validates the token; the runtime reads the verified sub, loads the session, and refuses a non-owner.
  4. 4stream_event frames, then complete, stream back over the same socket.
  5. 5POST /agent/tasks records a PENDING task as the verified caller (or an allowlisted system)…
  6. 6…and emits Run Agent Task on the bus, then polls its own row for up to ~25 seconds.
  7. 7First-party backends emit Run Agent Task directly, now or later through Schedule Event. Persistent agents never come this way. They run in your stack under their own source.
  8. 8The task Lambda claims the task row (exactly one delivery wins) and runs one turn.
  9. 9Agent Task Completed goes back on the bus for any consumer, success or failure.
Everything it can do, and where to read about it
CapabilityHowWhere to readTypes
Talk to a Bedrock modelAny Bedrock model id; the default is us.amazon.nova-lite-v1:0. Pin a model per session or per call.Reference → EnvironmentAll
Remember a conversationStrands snapshots in DynamoDB, keyed by session, so a reconnect resumes exactly where it left off.Chat → MemoryChat · Task
Remember a person across sessionsAgentCore Memory extracts facts and preferences per verified user and injects the relevant ones each turn. Chat runtime only.Chat → MemoryChat
Call first-party toolsA host registry of named tool() factories a session opts into by name. Built-ins: http_request, notebook.Tools → First-partyAll
Call external tools over MCPA session lists MCP servers by URL; the host allowlists hosts and forwards an authority-minted identity header.Tools → MCPAll
Return structured outputrunAgent({ outputSchema }) forces the model to emit against a Zod schema and returns the validated object.Tasks → One-shotOne-shot · Persistent (in handlers)
Run as a system, not a personA system principal for ecosystem work with no owning user. Free on the internal bus, allowlisted over the API.Tools → PrincipalsTask · Persistent
Act on events, with pacingTrigger rules route events to agents through atomic gates (cooldowns, once-per keys) with seeded, deadline-aware delays.Agency → Waking upPersistent
Pursue goals and keep promisesTyped agendas reconciled from observed state and commitments with an explicit lifecycle, both stored per agent.Agency → GoalsPersistent
Run laterA delayed task rides the bus-level Schedule Event primitive; no scheduler client or IAM role in the caller.Tasks → LaterTask · Persistent