@aifluens/agent-kit

The local copy-paste runtime for the AIFluensLab learning labs. The lab code you see imports from @aifluens/agent-kit; this package makes those imports real so you can run the same snippet on your own machine, with your own provider key.

import { Agent } from "@aifluens/agent-kit";

const agent = new Agent({
  model: "claude-sonnet",
  systemPrompt: "You are a friendly billing support rep.",
  temperature: 0.4,
});

const response = await agent.run("Hi, can you help me?");
console.log(response);

npm install @aifluens/agent-kit @langchain/anthropic @langchain/core
export LLM_PROVIDER="anthropic"          # which provider to use (required)
export ANTHROPIC_API_KEY="sk-ant-..."
npx tsx agent.ts

This is a learner-convenience runtime. The hosted platform runs a more featured version (tracing, observability, retries, managed credentials); agent-kit keeps just what you need to see your agent work locally.

Install matrix

agent-kit keeps the base install tiny and loads extras only when a lab needs them:

| You want to run… | Also install | | --- | --- | | Basic agents (M1, M2, M9) on Anthropic | @langchain/anthropic @langchain/core | | …on OpenAI | @langchain/openai | | …on Google Gemini | @langchain/google-genai | | …on Google Vertex AI | @langchain/google-vertexai | | …on AWS Bedrock | @langchain/aws | | Retrieval / RAG (M4) | pg @xenova/transformers | | MCP / connections (M5) | (nothing extra — uses built-in fetch) |

Bring your own key (BYOK)

You pick the provider explicitly with the LLM_PROVIDER env var — it is read verbatim and is never inferred from the model string. Set LLM_PROVIDER to one of anthropic, openai, google, bedrock, azure-openai, vertex, then set that provider's standard public env var(s). The model you pass to Agent is just the model id.

| LLM_PROVIDER | Example model | Env var(s) | | --- | --- | --- | | anthropic | claude-sonnet / claude-opus-4-8 | ANTHROPIC_API_KEY | | openai | gpt-4o-mini | OPENAI_API_KEY | | google | gemini-1.5-flash | GOOGLE_API_KEY | | bedrock | anthropic.claude-3-5-sonnet | AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, AWS_SESSION_TOKEN? | | azure-openai | <deployment> | AZURE_OPENAI_API_KEY, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_VERSION? | | vertex | gemini-1.5-pro | GOOGLE_APPLICATION_CREDENTIALS, GCP_PROJECT, GCP_LOCATION? |

LLM_PROVIDER is required — if it is unset or not one of the values above, agent-kit throws a clear error listing the valid values rather than guessing.

Friendly Anthropic shortnames resolve automatically: claude-sonnet → claude-sonnet-4-6, claude-opus → claude-opus-4-8, claude-haiku → claude-haiku-4-5-20251001.

Switch providers by changing LLM_PROVIDER (and setting that provider's key) — nothing in the lab code changes:

export LLM_PROVIDER="openai"
export OPENAI_API_KEY="sk-..."

const agent = new Agent({ model: "gpt-4o-mini", systemPrompt: "…", temperature: 0.4 });

Run M4 (retrieval) locally

The Retriever searches your own Postgres + pgvector database, using the same public Xenova/all-MiniLM-L6-v2 (384-dim) embeddings the platform uses, so results are comparable.

# 1. A Postgres with pgvector (Docker is easy):
docker run -d -e POSTGRES_PASSWORD=pw -p 5432:5432 pgvector/pgvector:pg16
export DATABASE_URL="postgres://postgres:pw@localhost:5432/postgres"

# 2. Create the schema (ships with this package):
psql "$DATABASE_URL" -f node_modules/@aifluens/agent-kit/schema.sql

# 3. Load your documents (chunks + embeds them):
npm install pg @xenova/transformers
npx agent-kit-ingest ./docs/*.md --kb 1

# 4. Run the M4 lab. `new Retriever()` searches kb 1 by default
#    (override with AGENT_KIT_KB_ID or new Retriever({ kbId })).
npx tsx retriever.ts

search(query, { topK, searchType }) supports searchType: "vector" | "keyword" | "hybrid" (hybrid fuses both legs with Reciprocal Rank Fusion). The first embed downloads the model (~30 MB) once and caches it.

Run M5 (MCP / connections) locally

Point MCPClient / callConnectionHttp at your own MCP or HTTP server via AGENT_KIT_CONNECTIONS — a JSON map of provider → { kind, url, token? }:

export AGENT_KIT_CONNECTIONS='{
  "helpdesk-sandbox": { "kind": "mcp",  "url": "http://localhost:8000/mcp" },
  "helpdesk-http":    { "kind": "http", "url": "http://localhost:8001", "token": "secret" }
}'
npx tsx agent-mcp.ts

• MCPClient.connect(provider) speaks MCP Streamable HTTP: it runs the initialize → tools/list handshake and returns the discovered tools ready to spread into new Agent({ tools }).
• callConnectionHttp(provider, { method, path, query?, body? }) makes a plain HTTP request to the configured base URL (with Authorization: Bearer <token> if you set one).

You supply the server. Any MCP server that speaks Streamable HTTP, or any HTTP API, works.

API

| Export | What it is | | --- | --- | | Agent | new Agent(options).run(input) — the agent loop. input is a string or { role, content }[]. | | tool | tool({ name, description, parameters, handler }) — define a tool (parameters is JSON Schema). | | Guardrail | new Guardrail(name, { position, scope? }) — illustrative input/output guardrails. | | Retriever | new Retriever().search(query, { topK, searchType }) — local pgvector search (M4). | | MCPClient | MCPClient.connect(provider) — MCP tool discovery against your server (M5). | | callConnectionHttp | raw HTTP to a configured connection (M5). |

License

MIT.