Building an Agent

Prerequisites

Before building an agent, you should be familiar with:

• The CR Agents Overview
• Basic JavaScript/TypeScript
• REST API concepts

You'll also need:

• A Creation Rights account on any paid plan (Studio, Agency, Studio Pro, or Enterprise)
• Node.js 18+ installed locally
• The CR CLI installed (npm install -g @creationrights/cli)

Agent SDK Setup

Install the Agent SDK in your project:

npm install @creationrights/agent-sdk

Authenticate the CLI with your API key:

cr auth login

Creating Your First Agent

1. Scaffold the Agent

Use the CLI to generate the boilerplate:

cr agent init my-first-agent
cd my-first-agent

This creates:

my-first-agent/
  agent.config.json    # Agent metadata and permissions
  src/
    index.ts           # Entry point
    handler.ts         # Main execution logic
  tests/
    handler.test.ts    # Test file
  package.json

2. Define the Configuration

Edit agent.config.json to declare your agent's identity and permissions:

{
  "name": "my-first-agent",
  "displayName": "My First Agent",
  "description": "A custom agent that tags assets based on content analysis.",
  "version": "1.0.0",
  "permissions": ["assets:read", "assets:write"],
  "inputs": {
    "asset_ids": {
      "type": "array",
      "items": { "type": "string" },
      "description": "IDs of assets to process"
    }
  }
}

3. Implement the Handler

The handler is the core of your agent. It receives inputs and uses platform tools to perform work.

import { AgentHandler, AgentContext } from "@creationrights/agent-sdk"
 
export const handler: AgentHandler = async (ctx: AgentContext) => {
  const { asset_ids } = ctx.inputs
 
  const results = []
 
  for (const assetId of asset_ids) {
    // Fetch asset metadata
    const asset = await ctx.platform.assets.get(assetId)
 
    // Analyse the asset content
    const analysis = await ctx.ai.analyse(asset.url, {
      prompt: "Describe this asset and suggest relevant tags.",
    })
 
    // Apply tags
    await ctx.platform.assets.update(assetId, {
      tags: analysis.suggestedTags,
    })
 
    results.push({
      assetId,
      tags: analysis.suggestedTags,
    })
  }
 
  return { results }
}

4. Test Locally

Run the agent in development mode:

cr agent dev

This starts a local execution environment that simulates the platform. You can send test inputs:

cr agent test --input '{"asset_ids": ["test-asset-1"]}'

5. Deploy

When you're ready, deploy the agent to your workspace:

cr agent deploy

The agent will be available in your workspace's agent catalogue.

Agent Lifecycle

Versioning

Each deployment creates a new version. Previous versions remain available for rollback.

cr agent deploy --version 1.1.0

Environment Variables

Store secrets and configuration in environment variables:

cr agent env set MY_SECRET=abc123

Access them in your handler via ctx.env.MY_SECRET.

Logging

Use the built-in logger for structured logging:

ctx.log.info("Processing asset", { assetId })
ctx.log.warn("Unusual metadata detected", { field: "rights" })
ctx.log.error("Failed to process", { error: err.message })

Logs are visible in the agent execution history on the dashboard.

Best Practices

• Keep agents focused. Each agent should do one thing well
• Handle errors gracefully. Use try/catch and return meaningful error messages
• Respect rate limits. Add delays between API calls when processing many items
• Test thoroughly. Write tests for edge cases before deploying
• Use semantic versioning. Bump versions appropriately for breaking changes