Build your first agent

AgentsKit is the composable JavaScript and TypeScript foundation for agent runtimes, tools, memory, RAG, and interfaces. This guide starts with a real runtime that succeeds without an account, then shows the one seam you replace to use a model.

• For: JavaScript and TypeScript developers evaluating AgentsKit.
• Maturity: Beta. The core contracts are stable; the wider runtime continues to evolve.
• First proof: a complete local run in one file, with no hidden service.

#Run your first agent locally

Create an empty project with Node.js 20 or newer:

mkdir first-agent && cd first-agent
npm init -y
npm install @agentskit/core @agentskit/runtime tsx

Create agent.ts:

import type { AdapterFactory } from '@agentskit/core'
import { createRuntime } from '@agentskit/runtime'

const localAdapter: AdapterFactory = {
  createSource(request) {
    const task = request.messages.at(-1)?.content ?? 'your task'

    return {
      async *stream() {
        yield {
          type: 'text' as const,
          content: `Agent ready. I received: ${task}`,
        }
        yield { type: 'done' as const }
      },
      abort() {},
    }
  },
}

async function main() {
  const runtime = createRuntime({ adapter: localAdapter })
  const result = await runtime.run('Plan my first production agent')
  console.log(result.content)
}

void main()

Run it:

npx tsx agent.ts

You should see:

Agent ready. I received: Plan my first production agent

No account, API key, or network call is required. The example uses the same AdapterFactory and createRuntime contracts as a provider-backed agent, so this first result is executable documentation rather than pseudocode.

#Understand the two moving parts

flowchart LR
  T["Your task"] --> R["AgentsKit runtime"]
  R --> A["Adapter contract"]
  A --> S["Streaming response"]
  S --> R
  R --> O["Typed run result"]

• The runtime owns the agent loop, messages, tools, memory, and events.
• The adapter turns a provider or local implementation into one streaming contract.

That boundary is why you can validate behavior locally and connect a model without rewriting orchestration.

#Connect a model provider

When the local run works, install the provider adapters:

npm install @agentskit/adapters

Replace localAdapter with the provider you want:

import { createRuntime } from '@agentskit/runtime'
import { openai } from '@agentskit/adapters'

const runtime = createRuntime({
  adapter: openai({
    apiKey: process.env.OPENAI_API_KEY!,
    model: 'gpt-4o',
  }),
})

const result = await runtime.run('Plan my first production agent')
console.log(result.content)

Set OPENAI_API_KEY and run the same command. You can use Anthropic, Gemini, Ollama, or another supported provider through the same seam.

#Grow only when the task needs it

1. Add a tool when the agent must act.
2. Add memory when it must retain useful context.
3. Add RAG when answers need your own sources.
4. Add observability before production traffic.
5. Add evals before changing prompts or models confidently.

#Continue in the ecosystem

• Need working source to adapt? Browse the AgentsKit Registry.
• Need the same agent across chat surfaces? Use AgentsKit Chat.
• Need repeatable engineering standards? Follow the Agents Playbook.
• Need agent-readable repository handoffs? Add Doc Bridge.
• Need low-noise verification? Run AgentsKit Code Review.
• Need orchestration and governance? Continue to AgentsKit OS.

Every step is optional. AgentsKit remains the foundation; the link appears where that adjacent product solves the next concrete problem.