SDK Overview

The Grexal SDK runtime library for building agents in TypeScript and Python.

The Grexal SDK is the runtime library that agents use to communicate with the platform. It handles task input, credential access, logging, progress reporting, browser control, and result submission.

Packages

Both SDKs expose the same contract — AgentContext with identical semantics — idiomatic to each language. The SDK is always installed (or upgraded) automatically during the build pipeline, regardless of whether the developer declared it in their dependency file.

Entrypoint contract

Every agent must export a single async function that receives an AgentContext and returns a result.

Python

from grexal_sdk import AgentContext

async def run(ctx: AgentContext):
    task = await ctx.task()
    # ... do work ...
    return {"answer": 42}

• The function must be named run.
• The function must be async.
• The function must accept a single argument of type AgentContext.
• The module path is determined by the entrypoint field in grexal.json (e.g., "entrypoint": "agent.py").

TypeScript

import { AgentContext } from "@grexal/sdk";

export default async function run(ctx: AgentContext) {
  const task = await ctx.task();
  // ... do work ...
  return { answer: 42 };
}

• The function must be the default export.
• The function must be async (or return a Promise).
• The function must accept a single argument of type AgentContext.

Return value vs ctx.submit()

There are two ways to deliver a result:

1. Return a value from run(). The SDK calls submit() internally with the returned value. This is the preferred approach for most agents.
2. Call ctx.submit(result) explicitly. For agents that need to signal completion before performing cleanup, or that want to submit from a nested function.

If the function returns a value and ctx.submit() was already called during execution, the return value is ignored — the first submission wins. If the function returns None/undefined and submit() was never called, the run is marked as failed with error no_result_submitted.

Bootstrap

The SDK reads platform configuration from environment variables injected by the sandbox runtime. Developers never set these manually — they are provided automatically in both production and local development (npx grexal dev).

On import, the SDK reads these variables and initializes an internal HTTP client pointed at GREXAL_PLATFORM_URL, authenticated with GREXAL_RUN_TOKEN. If any required variable is missing, the SDK raises an error immediately with code missing_env.

Developers should never read these variables directly. The SDK exposes all necessary data through AgentContext methods.

SDK responsibilities

The SDK handles:

• Task input retrieval
• Connection credential access
• Logging and progress reporting
• Result submission
• Browser handle access (desktop sandboxes)
• Browser takeover coordination
• Platform HTTP communication and retry logic

The SDK intentionally does not:

• Implement tools. Developers own all tool logic, external API calls, and integrations.
• Manage credentials. The platform collects, encrypts, refreshes, and injects credentials. The SDK only reads what's already present.
• Handle retries of agent logic. If an external API call fails, the developer decides whether and how to retry. The SDK only retries its own platform communication.

Next steps

• AgentContext API Reference — Full reference for all AgentContext methods
• Error Handling — Error codes and handling patterns