@agentskit/core

npm install @agentskit/core

import type { ToolDefinition, ToolExecutionContext } from '@agentskit/core'

export const myTool: ToolDefinition = {
  name: 'greet',
  description: 'Greets a user by name.',
  schema: {
    type: 'object',
    properties: { name: { type: 'string' } },
    required: ['name'],
  },
  async execute(args: Record<string, unknown>, _ctx: ToolExecutionContext) {
    const name = String(args.name ?? 'world')
    return `Hello, ${name}!`
  },
}

import { createChatController } from '@agentskit/core'
import { anthropic } from '@agentskit/adapters'

const chat = createChatController({
  adapter: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY!, model: 'claude-sonnet-4-6' }),
})

chat.subscribe(() => {
  console.log(chat.getState().status, chat.getState().messages.length)
})

await chat.send('Hello')

import {
  AgentsKitError,
  AdapterError,
  ToolError,
  MemoryError,
  ConfigError,
  RuntimeError,
  SandboxError,
  SkillError,
  ErrorCodes,
} from '@agentskit/core'

class AgentsKitError extends Error {
  readonly code: string       // e.g. 'AK_TOOL_EXEC_FAILED'
  readonly hint: string | undefined   // actionable fix
  readonly docsUrl: string | undefined // direct docs link
  readonly cause: unknown     // original error, if any
}

error[AK_ADAPTER_MISSING]: No adapter provided
  --> Hint: Pass an adapter when creating the chat controller, e.g.
            createChatController({ adapter: openai({ apiKey, model: 'gpt-4o' }) })
  --> Docs: https://www.agentskit.io/docs/data/providers

import { ErrorCodes } from '@agentskit/core'

ErrorCodes.AK_ADAPTER_MISSING          // adapter not provided
ErrorCodes.AK_ADAPTER_STREAM_FAILED    // streaming call failed
ErrorCodes.AK_TOOL_NOT_FOUND          // tool name not registered
ErrorCodes.AK_TOOL_EXEC_FAILED        // execute() threw
ErrorCodes.AK_TOOL_PEER_MISSING       // optional tool peer is not installed
ErrorCodes.AK_TOOL_INVALID_INPUT      // tool arguments or proposal are invalid
ErrorCodes.AK_TOOL_QUOTA_EXCEEDED     // tool execution exceeds its quota
ErrorCodes.AK_TOOL_FORBIDDEN          // tool execution is denied by policy
ErrorCodes.AK_MEMORY_LOAD_FAILED      // memory.load() failed
ErrorCodes.AK_MEMORY_SAVE_FAILED      // memory.save() failed
ErrorCodes.AK_MEMORY_DESERIALIZE_FAILED // corrupt persisted state
ErrorCodes.AK_MEMORY_PEER_MISSING     // optional memory backend is not installed
ErrorCodes.AK_MEMORY_REMOTE_HTTP      // remote memory request failed
ErrorCodes.AK_CONFIG_INVALID          // missing or bad config
ErrorCodes.AK_RUNTIME_INVALID_INPUT   // runtime input is invalid
ErrorCodes.AK_RUNTIME_STEP_FAILED     // a runtime step failed
ErrorCodes.AK_RUNTIME_DELEGATE_FAILED // delegated agent execution failed
ErrorCodes.AK_SANDBOX_DENIED          // sandbox policy denied execution
ErrorCodes.AK_SANDBOX_INVALID_TOOL    // tool is invalid for the sandbox
ErrorCodes.AK_SANDBOX_PEER_MISSING    // optional sandbox backend is not installed
ErrorCodes.AK_SANDBOX_BACKEND_FAILED  // sandbox backend failed
ErrorCodes.AK_SKILL_INVALID           // skill definition is invalid
ErrorCodes.AK_SKILL_DUPLICATE         // skill identity is duplicated

import { AgentsKitError, ToolError, ErrorCodes } from '@agentskit/core'

try {
  await runtime.run(task)
} catch (err) {
  if (err instanceof ToolError) {
    if (err.code === ErrorCodes.AK_TOOL_EXEC_FAILED) {
      console.error('Tool execution failed:', err.hint)
      console.error('See:', err.docsUrl)
    }
  } else if (err instanceof AgentsKitError) {
    // any other AgentsKit-originating error
    console.error(err.toString())
  } else {
    throw err // re-throw unknown errors
  }
}

import { ToolError, ErrorCodes } from '@agentskit/core'

export const myTool = {
  name: 'fetch_record',
  async execute(args: { id: string }) {
    const record = await db.find(args.id)
    if (!record) {
      throw new ToolError({
        code: ErrorCodes.AK_TOOL_EXEC_FAILED,
        message: `Record ${args.id} not found`,
        hint: 'Check that the id exists before calling fetch_record.',
        cause: undefined,
      })
    }
    return record
  },
}

import { defineTool } from '@agentskit/core'

const getWeather = defineTool({
  name: 'get_weather',
  description: 'Get the current weather for a city.',
  schema: {
    type: 'object',
    properties: {
      city: { type: 'string', description: 'City name, e.g. "Madrid"' },
      units: { type: 'string', enum: ['metric', 'imperial'] },
    },
    required: ['city'],
  } as const,
  async execute(args) {
    // args.city  → string   (required)
    // args.units → string | undefined  (optional)
    const res = await fetch(`https://wttr.in/${args.city}?format=j1`)
    return res.json()
  },
})

import type { InferSchemaType } from '@agentskit/core'

const schema = {
  type: 'object',
  properties: {
    query: { type: 'string' },
    limit: { type: 'integer' },
  },
  required: ['query'],
} as const

type SearchArgs = InferSchemaType<typeof schema>
// { query: string; limit?: number }