Skip to content

feat(extras): add AgentcoreSession.invoke - #1264

Draft
ParidelPooya wants to merge 1 commit into
mainfrom
feat/agentcore-session-e6
Draft

ParidelPooya wants to merge 1 commit into
mainfrom
feat/agentcore-session-e6

Conversation

@ParidelPooya

Copy link
Copy Markdown
Contributor

What

Adds session.invoke(context, name, input, options) to agentcoreSession. One call runs one job in the session and returns the job's result.

Why

agentcoreSession (#1260) creates the session and stops it, but its handler cannot send a job yet. This item adds the job call.

Change

  • The handler receives an AgentcoreSession. The internal AgentcoreSessionHandle type is removed.
  • invoke runs one job with the existing runJob helper, in a child context named after the job, in the context passed to invoke. It passes a stop that does nothing, because the session stops the session in its own finally.
  • invoke reads the Region and encodes the input with the existing functionRegion and encodeInput from agentcore.ts, which are now exported inside the package. So an input error rejects the returned promise before any durable operation of the job, as in agentcore().
  • The job's child context uses agentcoreErrorMapper(jobName). So a failed job rejects inside the handler as AgentcoreJobFailedError, AgentcoreTimeoutError or AgentcoreDeliveryError.
  • The session's child context uses a new agentcoreSessionErrorMapper. It restores an AgentCore error to its class, and passes any other error to callerErrorMapper. So a job error that leaves the handler reaches the caller with its class. A plain handler error is still a ChildContextError, as before.
  • callerErrorMapper is the SDK-error rule of sessionErrorMapper in compute/microvm/errors.ts, moved into its own function. sessionErrorMapper now calls it. Its behavior does not change, and the MicroVM tests pass without edits.
  • rebuildAgentcoreError is the class lookup of agentcoreErrorMapper, moved into its own function so both AgentCore mappers use it.
  • agentcoreSession is exported from @aws/durable-execution-sdk-js-extras/compute/agentcore, with @public and @experimental tags.

What this copies from MicrovmSession.invoke

  • Each job is its own child context named name, created in the context that the caller passes. The handle holds no context of its own.
  • Input errors are caught before the job's child context and returned as a rejected DurablePromise.
  • The job's child context uses the operation's error mapper (microvmErrorMapper(jobName) there, agentcoreErrorMapper(jobName) here).
  • The session's child context uses a session mapper: restore the compute error class, otherwise apply the SDK-error rule (sessionErrorMapper there, agentcoreSessionErrorMapper here, with the shared callerErrorMapper).

Decisions that the issue did not cover

Simpler options considered (rule 2)

  • No session error mapper: a job error that leaves the handler then reaches the caller as ChildContextError, not as its AgentCore class. The "leaves the session" tests fail.
  • Reuse agentcoreErrorMapper as the session mapper: it turns every handler error into AgentcoreError, which is wrong for caller code.

Testing

  • npm test in the extras package: 613 passed, 1 skipped (34 test files passed, 1 skipped). tsc --noEmit and npm run lint pass.
  • New tests in src/compute/agentcore/__tests__/session.test.ts (7):
    • two jobs in a row use the same session ID, each has its own callback ID, each job is a child context named after the job, and the session stops once;
    • the job is created in the context passed to invoke (a nested child context);
    • a job failure rejects in the handler as AgentcoreJobFailedError, and the handler can then run a second job in the same session;
    • a job failure that leaves the session reaches the caller as AgentcoreJobFailedError, AgentcoreTimeoutError and AgentcoreDeliveryError, the same on the first run and on replay;
    • an input that JSON cannot encode rejects the returned promise, is not thrown, and creates no durable operation of the job.
  • Edited existing test: "stops the session after a handler error, and fails with that error" now also asserts errorType ChildContextError. The expectation is the behavior on main. It is added so that the session mapper's fallback has a test.
  • Mutation check (rule 4). Each mutation below fails at least one test:
    1. remove the job's error mapper;
    2. remove the session's error mapper;
    3. make the session mapper's fallback return the error unchanged;
    4. make the job stop the session;
    5. run the job without its own child context;
    6. create the job in the session's child context instead of the passed context;
    7. throw the input error instead of returning a rejected promise.

Closes #1235
Part of #1245

Twin: aws/aws-durable-execution-sdk-python#944

The agentcoreSession handler now receives an AgentcoreSession. Its
invoke runs one job in the session through runJob, in a child context
named after the job, in the context passed to invoke. The session
stops the session, so the job's stop does nothing.

A job failure keeps its Agentcore* class in the handler and after it
leaves the session, as in microvmSession. agentcoreSession is exported
from the compute/agentcore entry point.

Closes #1235

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[AgentCore session] E6: Add session.invoke

1 participant