Quickstart

This page creates an agent, an environment and a session, then streams the session's events.

Before you start

A coreloop API key, from your organization's API keys page. The key selects the organization.
A provider key on the same organization: OpenRouter, OpenAI or Anthropic. coreloop refuses a session at creation when no key serves the model.

Install the SDK

coreloop speaks the Anthropic wire contract, so the official SDKs work with no plugin. Install the one for your language.

npm install @anthropic-ai/sdk

Every Anthropic SDK reads ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY from the environment, so pointing one at coreloop takes two exports.

cURL

export CORELOOP_API_KEY="your-coreloop-key"

# Every Anthropic SDK reads these two.
export ANTHROPIC_BASE_URL="https://coreloop.run/anthropic"
export ANTHROPIC_API_KEY="$CORELOOP_API_KEY"

Or set the base URL on the client.

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://coreloop.run/anthropic",
  apiKey: process.env.CORELOOP_API_KEY,
});

The SDK appends /v1 to the base URL itself. It also sends anthropic-version and anthropic-beta. coreloop accepts both and requires neither.

Create your first session

1. Create an agent

The agent holds the model, the system prompt and the tools. agent_toolset_20260401 is the hosted toolset, bash and the file tools inside the session's sandbox.

const agent = await client.beta.agents.create({
  name: "Code Reviewer",
  model: "claude-sonnet-5",
  system: "You review pull requests.",
  tools: [{ type: "agent_toolset_20260401" }],
});

console.log(agent.id, agent.version);

2. Create an environment

An environment names the sandbox configuration. Create it once and reference it from every session.

const environment = await client.beta.environments.create({
  name: "reviews",
  config: { type: "cloud" },
});

3. Start a session

A session references one agent and one environment. initial_events starts the first turn at creation, so the agent is already working when the call returns.

const session = await client.beta.sessions.create({
  agent: agent.id,
  environment_id: environment.id,
  title: "PR 412",
  initial_events: [
    {
      type: "user.message",
      content: [{ type: "text", text: "Review PR 412." }],
    },
  ],
});

4. Read the stream

The stream carries every event written after it opened. The session goes to session.status_idle when the agent has nothing more to do.

const stream = await client.beta.sessions.events.stream(session.id);

loop: for await (const event of stream) {
  switch (event.type) {
    case "agent.message":
      for (const block of event.content) {
        if (block.type === "text") process.stdout.write(block.text);
      }
      break;
    case "agent.tool_use":
      console.log(`[${event.name}]`);
      break;
    case "session.status_idle":
      break loop;
  }
}

What happens

The session resolves your provider key for the agent's model, and again at every turn.
A container starts on the first tool call and keeps its filesystem between turns.
The session appends every message, tool call, tool result and status change to the transcript, whether or not anything is reading it.
The turn ends at session.status_idle. The session stays open. Send another message and it runs again.

Agents, versions, effort levels and per-session overrides.
Events and streaming, the event types, paging the transcript, steering a running turn.
Tools, what the toolset does, and how to make a tool ask first.
Skills, upload a folder the agent reads when it needs it.

Overview Agents