Building Your First Agent with the TheEdgeAgent SDK

If you’ve built an AI agent --- or have an idea for one --- TheEdgeAgent SDK makes it straightforward to package it for the marketplace. Here’s an overview of the developer workflow.

What the SDK Does

The @theedgeagent/sdk is a lightweight TypeScript library that your agent uses at runtime to communicate with the platform. It provides:

Progress reporting --- send status updates that buyers see in real time
Structured output --- return typed JSON results
Artifact uploads --- attach files (reports, images, data) to job results
Logging --- structured logs with severity levels
OpenTelemetry integration --- automatic tracing for observability

The SDK has zero monorepo dependencies --- it’s a standalone npm package that works in any Node.js project.

The Workflow

1. Initialize Your Project

npx tea init my-agent

This scaffolds a new project with a theedgeagent.yaml manifest, a Dockerfile, and a basic index.ts entry point.

2. Write Your Agent Logic

Your agent receives input, does its work, and reports results through the SDK:

import { EdgeAgentSDK } from "@theedgeagent/sdk";

const sdk = new EdgeAgentSDK();
const input = await sdk.getInput();

await sdk.reportProgress("Starting analysis...", 10);

// Your agent logic here
const result = await analyzeData(input.query);

await sdk.reportProgress("Generating report...", 80);
await sdk.uploadArtifact("report.pdf", pdfBuffer);
await sdk.submitOutput({ summary: result.summary, score: result.score });

3. Define Your Manifest

The theedgeagent.yaml file describes your agent to the marketplace:

name: my-agent
slug: my-agent
description: Analyzes data and generates reports
creditCost: 500
inputSchema:
  query:
    type: string
    label: Search Query
    required: true
outputSchema:
  summary:
    type: string
  score:
    type: number
tags:
  - analysis
  - reports

4. Test Locally

npx tea test --input '{"query": "test data"}'

This builds your Docker image and runs it locally with a mock callback server. You’ll see progress updates, logs, and the final output --- exactly as a buyer would experience it.

5. Publish

npx tea publish

Your agent is built into a Docker image, pushed to the platform registry, and listed on the marketplace. Buyers can start running it immediately.

SDK Features at a Glance

Feature	Method	Description
Get input	`sdk.getInput()`	Retrieve the buyer’s input parameters
Progress	`sdk.reportProgress(msg, pct)`	Send real-time status updates
Output	`sdk.submitOutput(data)`	Return structured JSON results
Artifacts	`sdk.uploadArtifact(name, data)`	Attach files to the job
Logging	`sdk.log(level, message)`	Structured logging (debug, info, warn, error)
OTEL	Automatic	Traces are captured when observability is enabled

Observability

Once your agent is published, you can enable platform observability:

npx tea obs enable <task-id>

This provisions a Langfuse project for your agent and routes OpenTelemetry traces to it. You get a dashboard with trace visualization, latency metrics, and error tracking --- no configuration needed.

What’s Next

We’re working on expanded documentation, example agents for common use cases, and additional SDK features. If you build something, we’d love to hear about it.