Introduction to Finlay

Recommended path for new developers

Follow these steps to create your first agent.

Key capabilities

Finlay agents combine several core capabilities that work together to enable autonomous task execution. These capabilities are what differentiate agents from simple automation scripts or chatbots.

Installation

The Finlay SDK is available for Node.js 18+ and provides full TypeScript support with comprehensive type definitions for all APIs. The SDK handles authentication, request signing, response parsing, and automatic retries for transient errors.

Install the SDK using your preferred package manager:

npm install @finlay/sdk

Set your API key as an environment variable:

export FINLAY_API_KEY="your-api-key"

Basic example

Create and run a simple agent:

import { Finlay } from '@finlay/sdk'

const finlay = new Finlay()

const agent = await finlay.agents.create({
  name: 'research-assistant',
  description: 'Searches the web and summarizes findings',
  tools: ['web_search', 'summarize']
})

const result = await agent.run({
  task: 'Find the latest news on AI agents'
})

console.log(result.output)

The agent will:

1. Parse the task and plan the approach
2. Call the web_search tool to find relevant articles
3. Call the summarize tool to condense the findings
4. Return the structured result

Architecture

Finlay agents run in a managed execution environment with built-in observability and error handling. The architecture is designed for reliability at scale.

Tools

Tools are capabilities that agents can invoke. Each tool has a name, description, and typed parameters.

Built-in tools

Custom tools

Define tools that wrap your own APIs:

import { defineTool } from '@finlay/sdk'

const slackTool = defineTool({
  name: 'send_slack',
  description: 'Send a message to a Slack channel',
  parameters: {
    type: 'object',
    properties: {
      channel: { type: 'string' },
      message: { type: 'string' }
    },
    required: ['channel', 'message']
  },
  execute: async ({ channel, message }) => {
    await slack.chat.postMessage({ channel, text: message })
    return { success: true }
  }
})

Memory

Agents can store and retrieve information across sessions using the memory system.

// Store a fact
await agent.memory.store({
  type: 'semantic',
  content: 'User prefers brief summaries'
})

// Query memory
const memories = await agent.memory.search({
  query: 'user preferences',
  limit: 5
})

Runs

A run represents a single execution of an agent. Every run is captured with full traceability.

Runs progress through states: pending → running → completed or failed.

// Start async run
const run = await agent.run({
  task: 'Analyze Q3 data',
  async: true
})

// Wait for completion
const result = await finlay.runs.wait(run.id)

// Get trace for debugging
const trace = await finlay.runs.trace(run.id)

Platform features

Execution

Every agent run is executed in an isolated, managed environment. Finlay handles provisioning, scaling, and teardown automatically — you never interact with infrastructure directly.

Scheduling

Run agents automatically on a schedule using cron expressions, interval-based triggers, or event-driven webhooks. The scheduler handles timezone normalization, missed run recovery, and concurrency limits.

Web IDE

Build, test, and debug agents directly in your browser without any local setup. The Web IDE includes a code editor, live log viewer, run history, and an integrated terminal for testing tool calls.

Local Development

Use the Finlay CLI to develop and test agents locally before deploying to the platform. The local runtime mirrors the production execution environment so you never encounter environment-specific bugs at deploy time.

Integrations Overview

Finlay ships with 100+ pre-built integrations across productivity, communication, developer tools, CRMs, and data platforms. Each integration is fully typed, handles OAuth flows automatically, and includes built-in retry logic.

OAuth Apps

For integrations that require delegated user authorization, Finlay manages the full OAuth 2.0 flow on your behalf. Tokens are encrypted at rest, refreshed automatically, and scoped to the minimum permissions required.

Webhooks

Trigger agent runs in response to external events using webhooks. Finlay provides a unique HTTPS endpoint per agent that accepts JSON payloads and passes them as the run input.

Custom Tools

Extend your agents with custom tools that wrap any logic — from internal APIs to complex data transformations. Tools are defined as typed functions and made available to agents at runtime.

Authentication

All API requests are authenticated using API keys. Keys are scoped to a project and can be restricted to specific endpoints, IP ranges, and rate limits.

Permissions

Role-based access control (RBAC) lets you define exactly what each team member can do within a project. Roles are additive and can be customized per workspace.

Audit Logs

Every action taken by users or agents is recorded in an immutable audit log. Logs capture the actor, action, timestamp, IP address, and before/after state of any mutated resource.

Compliance

Finlay is built to meet the compliance requirements of modern enterprises. We maintain certifications and controls that allow our customers to operate in regulated industries.

CLI Reference

The Finlay CLI provides commands for managing agents, triggering runs, tailing logs, and deploying from your local environment.

Configuration

Agent configuration is defined in a finlay.config.ts file at the root of your project. This file controls agent defaults, tool allowlists, memory settings, and execution policies.

SDK reference

Primary SDK modules:

REST API

Base URL:

https://api.finlay.codes/v1

Authentication:

curl https://api.finlay.codes/v1/agents \
  -H "Authorization: Bearer your_api_key"

Endpoints

Support