Do something, then report back

Let’s follow one

Say your newsletter stack wants a summary of last week’s blog comments every Monday morning. Nobody is signed in, there’s no socket, and something downstream is waiting on the answer. Here’s everything that happens, in order.

1. 0 ms

   The request goes out

   Your Lambda calls requestAgentTask. It puts one Run Agent Task event on the bus and returns a taskId right away. All it needed was events:PutEvents.

   The task carries an identity, its principal. This one is a service, so it runs as system. A task started by a signed-in person runs as their verified sub instead.

   import { requestAgentTask } from '@readysetcloud/agent/memory';
   
   const { taskId } = await requestAgentTask({
     principal: { type: 'system', id: 'newsletter' },
     request: 'Summarize last week’s blog comments as three bullets.',
     // optional: sessionId, systemPrompt, modelId, temperature, maxTokens, tools, mcpServers
   });

2. ~20 ms

   EventBridge delivers it. Maybe twice.

   EventBridge promises at-least-once delivery, and “at least” is doing a lot of work in that sentence 😅. Two copies of your event can land on two Lambda containers at the same moment. That’s fine. The next stop is built for exactly this.

3. ~25 ms

   Exactly one delivery claims it

   startTask is a conditional write that moves the task row to RUNNING, but only from absent, PENDING, or FAILED. DynamoDB lines the writes up, so one delivery wins. The loser hands back the existing result or reports that it’s still running.

   Before it even gets that far, a TaskResultCache in the container catches a duplicate that lands on the same instance. That’s purely a speed-up. A cache miss is always correct.

4. ~30 ms

   The winner builds the agent and runs

   Only now does anything expensive happen. buildAgent loads the session config, connects MCP servers, and creates the assistant. A duplicate never got this far, so it cost next to nothing. Then the agent runs one buffered turn.

5. ~8 s

   The result is recorded

   finishTask writes COMPLETED with the output, or FAILED with the error, and only if the row is still RUNNING. Completed rows stick around for 24 hours.

   Status	Meaning
   PENDING	Created by the API so a GET sees it before the runtime picks it up. Optional.
   RUNNING	Claimed by exactly one invocation.
   COMPLETED	Finished; output holds the assistant text.
   FAILED	The run threw; error holds the message. A retry may claim it again.

6. ~8 s

   Everyone hears about it

   Agent Task Completed goes out no matter how it ended. Your newsletter stack listens for its taskId and carries on. Anything else that cares can listen too, without ever reading the agent’s table.

   {
     "source": "readysetcloud.agent",
     "detail-type": "Agent Task Completed",
     "detail": { "taskId": "6d1f...", "status": "COMPLETED", "output": "• ...", "principal": { "type": "system", "id": "newsletter" } }
   }

You don’t have to start from a Lambda

Every path ends up as the same event, landing on the same consumer, with the same result at the end. Pick based on who’s calling and whether they can wait.

Questions you’ll have eventually

curl -X POST "$CORE_API_URL/agent/tasks" \
  -H "Authorization: Bearer $ID_TOKEN" -H "Content-Type: application/json" \
  -d '{"request": "Draft release notes from the last 10 commits.", "wait": true}'

# 200 { "taskId": "...", "status": "COMPLETED", "output": "..." }
# 202 { "taskId": "...", "status": "RUNNING" }  → watch the event or GET /agent/tasks/{taskId}

{
  "Source": "newsletter",
  "DetailType": "Schedule Event",
  "Detail": {
    "name": "digest-2026-10-07",
    "at": "2026-10-07T09:00:00",
    "timezone": "America/Chicago",
    "whenPast": "send",
    "event": {
      "source": "readysetcloud.agent",
      "detailType": "Run Agent Task",
      "detail": { "taskId": "digest-2026-10-07", "principal": { "type": "system", "id": "newsletter" }, "request": "..." }
    }
  }
}

import { runAgentTask, createAssistant, getSessionConfig, TaskResultCache } from '@readysetcloud/agent';

const cache = new TaskResultCache();   // module scope, reused across warm invocations

export const handler = async ({ detail }) => {
  const { taskId, principal, request, sessionId } = detail;
  return runAgentTask({
    taskId, principal, request, sessionId, cache,
    buildAgent: async () => {
      const config = sessionId ? await getSessionConfig(sessionId) : null;
      if (config && config.userId !== principal.id) throw new Error('not your session');
      const agent = createAssistant({ sessionId: sessionId ?? `task-${taskId}`, systemPrompt: config?.systemPrompt });
      return { agent, cleanup: async () => { /* disconnect MCP clients */ } };
    },
  });
};