Skip to main content

Quickstart: build your first agent

In about five minutes, you will run an agent locally using Forge's embedded mode. It needs no database, queue, or server. createAgent wires the reference in-memory adapters, model registry, tool registry, and default engine for you.

1. Prerequisites​

  • Node.js 20 or later
  • An Anthropic API key

2. Install​

npm install @forge/agentkit @ai-sdk/anthropic

@ai-sdk/anthropic is an optional peer dependency because Forge supports more than one provider. The default embedded catalog uses Anthropic models.

3. Configure your model credential​

export ANTHROPIC_API_KEY="your-api-key"

In Windows PowerShell:

$env:ANTHROPIC_API_KEY="your-api-key"

4. Create agent.ts​

import { createAgent } from "@forge/agentkit/providers";

const agent = createAgent({
  manifest: {
    id: "assistant",
    name: "Assistant",
    instructions: "You are a helpful assistant. Be concise.",
    modelPolicy: { role: "smart" }, // resolved by capability, never a hardcoded model id
  },
});

The default catalog maps role: "smart" and role: "fast" to Claude models, using the ANTHROPIC_API_KEY from your environment. Pass models / roleAssignments / providerCredentials to use your own catalog or a different provider.

5. Run a turn​

const result = await agent.run({
  conversationId: "conv-1",
  message: "Draft a one-line launch tweet for our analytics dashboard.",
});

console.log(result.text); // the assistant's reply

Each run executes the turn to completion through the durable worker and returns once the run reaches a terminal state. Token/cost usage is recorded as the turn streams.

You should see a one-line launch post. The exact wording varies because a model generated it.

What you just built​

PartWhat it does
ModelForge resolves the smart role to a configured Anthropic model.
InstructionsThe stable behavior you give the agent.
ConversationconversationId groups messages and lets the next run load earlier turns.
RunOne durable execution of the agent for a message.
Outputresult.text is the convenience text response; result.parts contains typed output and tool events.

6. Continue the conversation​

await agent.run({ conversationId: "conv-1", message: "Make it more playful." });

Because the conversation carries its own history, you don't re-send prior context — Forge loads the conversation's messages and assembles the prompt under the model's token budget for you. State persists across turns on the same conversationId.

Next​