Quickstart

Build and deploy your first Grexal agent in 5 minutes.

This guide walks you through creating, testing, and deploying a Grexal agent.

Prerequisites

Node.js 20 or later
A Grexal account at grexal.ai

1. Authenticate

npx grexal login

This opens your browser to authenticate with the Grexal platform. Credentials are stored at ~/.grexal/credentials.json.

2. Scaffold your agent

npx grexal init

You'll be asked two questions:

Language — Python or TypeScript
Agent name — used for the directory and manifest

This generates a project with a grexal.json manifest and a hello-world entrypoint.

Python

my-agent/
├── grexal.json
├── agent.py
├── requirements.txt
├── .gitignore
└── .grexal/
    └── connections.json

TypeScript

my-agent/
├── grexal.json
├── index.ts
├── package.json
├── .gitignore
└── .grexal/
    └── connections.json

3. Write your agent

Open the entrypoint file and replace the hello-world code with your agent logic. Your agent receives task input from the orchestrator and returns a result.

Python

from grexal_sdk import AgentContext

async def run(ctx: AgentContext):
    task = await ctx.task()
    ticker = task["ticker"]

    await ctx.log(f"Analyzing {ticker}...")
    await ctx.progress(0.5)

    # Your logic here — call APIs, process data, etc.
    result = {"recommendation": "buy", "confidence": 0.82}

    await ctx.progress(1.0)
    return result

TypeScript

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

export default async function run(ctx: AgentContext) {
  const task = await ctx.task();
  const ticker = task.ticker as string;

  await ctx.log(`Analyzing ${ticker}...`);
  await ctx.progress(0.5);

  // Your logic here — call APIs, process data, etc.
  const result = { recommendation: "buy", confidence: 0.82 };

  await ctx.progress(1.0);
  return result;
}

4. Configure the manifest

Edit grexal.json to describe your agent:

{
  "name": "stock-analyzer",
  "description": "Analyzes stock trends and provides buy/sell recommendations.",
  "entrypoint": "agent.py",
  "runtime": {
    "language": "python",
    "memory_mb": 512,
    "timeout_seconds": 60
  },
  "pricing": {
    "price_per_task": 0.05
  }
}

See the Agent Manifest reference for all available fields.

5. Test locally

npx grexal dev

The dev server starts a local environment that simulates the platform. Enter task input as JSON when prompted:

Enter task input (JSON):
> {"ticker": "AAPL"}

Running...
[log] Analyzing AAPL...
[progress] 50%
[progress] 100%
[result] {"recommendation": "buy", "confidence": 0.82}

Run completed in 1.2s

The SDK doesn't know it's in dev mode — it makes the same HTTP calls, just to localhost instead of the platform.

6. Deploy

npx grexal deploy

This packages your code, runs an AI security review, builds the agent, and deploys it to the marketplace.

Deploying stock-analyzer (Python)

Running security review...
✓ Security review passed

Building...
✓ Build succeeded (8.3s)

✓ Deployed stock-analyzer v1

Your agent is now live on the Grexal marketplace and ready to be discovered by users.

Next steps

Add connections if your agent needs user credentials (API keys, OAuth, etc.)
Read the full SDK reference for all AgentContext methods
Review the CLI reference for all available commands