GETTING STARTED
Quick Start
This guide walks you through installing the SDK, creating your first AI agent, and executing it. You will be up and running in under 5 minutes.
Prerequisites
Before you begin, make sure you have the following installed on your machine:
- -Node.js 18+ — Download from nodejs.org
- -npm or yarn — Included with Node.js
- -A YourAutomation account — Sign up at the dashboard
1. Install the SDK
Install the YourAutomation SDK using your preferred package manager:
npm
npm install @yourautomation/sdk
yarn
yarn add @yourautomation/sdk
pnpm
pnpm add @yourautomation/sdk
2. Get Your API Key
Navigate to your dashboard at app.yourautomation.ai/settings/keys and create a new API key. You will receive a key in the format:
ya_live_sk_1234567890abcdef...
Note
Store your API key securely. Never commit it to version control. Use environment variables in production.
3. Initialize the Client
Create a new file and initialize the YourAutomation client:
src/agent.ts
import { YourAutomation } from "@yourautomation/sdk";
// Initialize with your API key
const client = new YourAutomation({
apiKey: process.env.YA_API_KEY!,
});
The client handles authentication, retries, rate limiting, and connection pooling automatically. You can also pass additional options:
Advanced configuration
const client = new YourAutomation({
apiKey: process.env.YA_API_KEY!,
baseUrl: "https://api.yourautomation.ai/v1", // default
timeout: 30000, // request timeout in ms
maxRetries: 3, // automatic retry count
debug: false, // enable debug logging
});
4. Create Your First Agent
Agents are the core primitive. Each agent has a model, a system prompt that defines its behavior, and optional tools it can call:
Create a support agent
const agent = await client.agents.create({
name: "Support Agent",
model: "claude-sonnet-4-20250514",
systemPrompt: `You are a helpful customer support agent for Acme Corp.
You have access to order lookup and inventory tools.
Always be polite, concise, and helpful.
If you cannot resolve an issue, escalate to a human agent.`,
parameters: {
temperature: 0.3,
maxTokens: 1024,
},
});
console.log("Agent created:", agent.id);
// => "agt_abc123def456"
5. Execute the Agent
Send a message to your agent and get a response:
Execute
const result = await client.agents.execute(agent.id, {
input: "What is the status of order #12345?",
});
console.log(result.output);
// => "I'd be happy to help you check on order #12345..."
console.log(result.usage);
// => { inputTokens: 142, outputTokens: 89, totalTokens: 231 }
The response includes the agent's output text, token usage, tool calls made, and execution metadata.
6. Add Custom Tools
Tools let your agent take actions in the real world. Define tools using JSON Schema for parameter validation:
Define tools
const agent = await client.agents.create({
name: "Support Agent",
model: "claude-sonnet-4-20250514",
systemPrompt: "You are a helpful support agent...",
tools: [
{
name: "lookup_order",
description: "Look up an order by its ID",
parameters: {
type: "object",
properties: {
orderId: {
type: "string",
description: "The order ID (e.g., #12345)",
},
},
required: ["orderId"],
},
handler: "https://api.acme.com/webhooks/lookup-order",
},
{
name: "create_ticket",
description: "Create a support ticket",
parameters: {
type: "object",
properties: {
subject: { type: "string" },
priority: {
type: "string",
enum: ["low", "medium", "high", "urgent"],
},
description: { type: "string" },
},
required: ["subject", "priority"],
},
handler: "https://api.acme.com/webhooks/create-ticket",
},
],
});
Note
Tool handlers receive a POST request with the tool parameters as the JSON body. They must return a JSON response that the agent will use to continue the conversation.
7. Enable Streaming
For real-time responses, enable streaming to receive tokens as they are generated:
Streaming execution
const stream = await client.agents.execute(agent.id, {
input: "Explain your return policy",
stream: true,
});
for await (const event of stream) {
switch (event.type) {
case "text_delta":
process.stdout.write(event.text);
break;
case "tool_call":
console.log("Tool called:", event.name);
break;
case "done":
console.log("\nTokens used:", event.usage.totalTokens);
break;
}
}
8. Multi-Turn Conversations
Agents maintain conversation context across multiple turns using conversation IDs:
Multi-turn
// Start a conversation
const turn1 = await client.agents.execute(agent.id, {
input: "I want to return a product",
});
// Continue the same conversation
const turn2 = await client.agents.execute(agent.id, {
input: "It's order #12345, the blue widget",
conversationId: turn1.conversationId,
});
// The agent remembers the full context
const turn3 = await client.agents.execute(agent.id, {
input: "Yes, please process the return",
conversationId: turn1.conversationId,
});
Next Steps
You now have a working AI agent. Here is what to explore next:
- -Authentication — Learn about API key management and permissions
- -Agent Types — Explore 8 pre-built agent templates
- -Tools & Functions — Build powerful tool integrations
- -Memory & Context — Manage conversation state and long-term memory
- -Best Practices — Production patterns and performance tips