Agent SDK

The Ploy Agent SDK (@meetploy/agent-sdk) wraps Ploy primitives -- state, workflows, timers, and file storage -- into a single createAgent() call. You get a fully functional AI agent with a durable tick loop, built-in tools, per-user workspaces, and lifecycle hooks out of the box.

What You Get

• Durable workflow tick loop -- AI calls and tool execution survive failures and restarts
• Built-in tools -- Memory, artifacts, scheduling, and MCP server integration
• Per-user workspaces -- Conversation history, memory, and settings isolated per user
• Type-safe custom tools -- defineTool() infers argument types from JSON Schema
• Lifecycle hooks -- React to memory changes, artifacts, scheduled tasks, and run completion with full env access
• Message queuing -- Messages received during an active run are queued and processed in order
• Commands -- Built-in /reset, /debug, /tools, and MCP management

Quick Start

Install the SDK:

pnpm add @meetploy/agent-sdk

Configure your ploy.yaml:

kind: worker
ai: true
state:
  STATE: default
fs:
  FILES: default
workflow:
  AGENT_WORKFLOW: agent_run
timer:
  SCHEDULER: default

Create your agent:

import { createAgent, defineTool } from "@meetploy/agent-sdk";

const weatherTool = defineTool({
	name: "get_weather",
	description: "Get the current weather for a city",
	parameters: {
		type: "object",
		properties: {
			city: { type: "string", description: "City name" },
		},
		required: ["city"],
	},
	async execute(args, ctx) {
		// args.city is typed as string
		const response = await fetch(`https://wttr.in/${args.city}?format=3`);
		return await response.text();
	},
});

export default createAgent({
	systemPrompt: "You are a helpful weather assistant.",
	tools: [weatherTool],
	handle(req, env, agent) {
		// Your custom HTTP handler -- parse the request,
		// call agent.handleMessage(), return a response
		return new Response("OK");
	},
});

That's it. The SDK handles the durable workflow loop, AI calls, tool execution, workspace persistence, and message queuing automatically.

How It Works

When a user sends a message:

1. handleMessage() loads or creates the user's workspace
2. If a run is already active, the message is queued
3. Otherwise, a durable workflow is triggered
4. The workflow loops: call the AI, execute any tool calls, repeat
5. When the AI responds without tool calls, the run completes
6. Any queued messages trigger a new run

Next Steps

• createAgent() -- Configuration options and the handle function
• Tools -- Built-in tools and defining custom tools with defineTool()
• Hooks -- Lifecycle hooks for reacting to agent events
• State & Workspaces -- Per-user workspace management and the StateManager
• Commands -- Built-in commands for users
• Workflows -- How the durable tick loop works