Skip to main content

​
What is a Session?

A Session represents a single execution attempt of an agent. It answers questions like:
  • Did my agent run?
  • Is it running, waiting, completed, or failed?
  • What state did it produce?
  • Is it waiting for human input?
  • What happened during this run?
A Session is not:
  • a conversation
  • a workflow
  • a background job
  • a LangChain run
A Session is an explicit execution record.
OpenSink never executes your agent. It only stores what happened during execution.

​
Why Sessions exist

Once agents move beyond experiments, teams need:

Resumability

Pause execution, wait for input, and resume without losing state.

Visibility

See what agents are doing, when they ran, and what they produced.

Control

Safely introduce human approval without rebuilding infrastructure.

Durability

Persist state outside memory, processes, and prompts.
Sessions provide this without introducing workflows, orchestration, or magic.

​
Session lifecycle

A Session progresses through a small, intentional state machine:
1

Created

A new session is created when an agent begins execution.
2

Running

The agent is actively executing.
3

Waiting for input

Execution is paused, waiting for external input (e.g. human approval).
4

Completed

Execution finished successfully or failed.

​
Session state

Each Session contains a state object. This state:
  • is controlled entirely by the agent
  • persists across pauses and restarts
  • is not interpreted by OpenSink
Example: 
{
  "portfolio_risk": "medium",
  "proposed_trades": [
    { "ticker": "AAPL", "amount": 5000 },
    { "ticker": "MSFT", "amount": 3000 }
  ]
}
State is not memory injection. It is durable system state owned by the agent.

​
Requesting input (human-in-the-loop)

Agents can pause execution and request input. This is how OpenSink enables:
  • approvals
  • confirmations
  • parameter selection
  • safe execution

​
Example request

{
  "key": "approve_trades",
  "message": "Approve the following trades",
  "schema": {
    "type": "object",
    "properties": {
      "approved": {
        "type": "boolean",
        "title": "Approve all trades?"
      }
    },
    "required": ["approved"]
  }
}
When a request exists:
  • the Session enters waiting_for_input
  • OpenSink renders a UI from the schema
  • execution stops

​
Resuming execution

When input is submitted:
  • OpenSink stores the response
  • OpenSink calls your agent’s execution endpoint
  • your agent loads the Session
  • execution continues from state
OpenSink does not:
  • branch logic
  • decide outcomes
  • execute steps

​
Execution contract

Each agent exposes one execution endpoint: 
POST /agents/:agent_id/execute
Execution logic inside your agent: 
if (!session) {
  session = createSession()
}

if (session.waiting_for_input) {
  handleInput(session)
} else {
  runNextStep(session)
}
This keeps control inside your code — not the platform.

​
Example: Trading agent

Risk, Money, and Trading

A trading agent that:
  • reads market news
  • proposes trades
  • waits for approval
  • executes safely
Sessions enable:
  • resumable execution
  • approval checkpoints
  • auditability
Without workflows, queues, or orchestration engines.

​
What Sessions intentionally do not do

❌ Orchestrate steps
❌ Execute jobs
❌ Inject memory
❌ Define workflows
❌ Replace agent frameworks Sessions stay simple so your agents stay powerful.

​
When to use Sessions

Use Sessions when:
  • agents run in the real world
  • humans must approve actions
  • execution must be resumable
  • failures must be visible
If agents matter — Sessions belong.