Documentation

Overview

Liberty Agents is a platform for building and running autonomous AI agents. An agent receives a goal, makes a plan, calls tools, checks the results, and repeats until the task is done.

The platform has three connected parts: an agent runtime, a skill system based on skill.md files, and an API gateway that gives you one key for many model providers.

Quickstart

Go from zero to your first running agent in five steps.

1. Join the waitlist and get a key

Sign up on the home page. When access opens you receive an invitation email and can create a key in the dashboard. Keys start with lib_live_.

2. Store the key as an environment variable

export LIBERTY_API_KEY=lib_live_xxxxxxxxxxxxxxxx

3. Call your first model

curl https://api.libertyagents.xyz/v1/chat \
  -H "Authorization: Bearer $LIBERTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-sonnet",
    "messages": [{"role": "user", "content": "Hello, Liberty!"}]
  }'

4. Create your first skill

mkdir -p skills/summarize-article
cat > skills/summarize-article/SKILL.md <<'MD'
---
name: summarize-article
description: Summarize a long article into 5 key points
---
Read the article, then write the 5 main points in plain English.
MD

5. Run an agent

import { Liberty } from "@liberty/agents";

const liberty = new Liberty({ apiKey: process.env.LIBERTY_API_KEY });
const run = await liberty.agents.run({
  model: "google/gemini-flash",
  skills: ["./skills/summarize-article"],
  goal: "Summarize https://example.com/article",
});
console.log(run.output);

Core concepts

• Goal: the end objective in natural language. Example: research three competitors and build a pricing table.
• Run: one execution of an agent from goal to final result. Each run has an ID, a step log, and a cost.
• Step: one turn of the loop. The agent thinks, picks a tool, runs it, and reads the result.
• Skill: a package of instructions loaded when relevant.
• Tool: a callable capability, with permissions you control.
• Model: the LLM behind the agent. It can be changed per run, even per step.

Autonomous agents

Liberty agents work in a simple loop that is easy to audit.

goal → plan → choose tool → execute → observe → (repeat) → final answer

Autonomy levels

Safety limits

• max_steps: the maximum number of steps per run.
• max_cost: the maximum cost per run. The run stops when it is reached.
• timeout: the total time limit.
• allowed_tools: the list of tools the agent may use.

{
  "goal": "Check prices of 3 competitors",
  "mode": "guided",
  "limits": { "max_steps": 25, "max_cost_usd": 0.5, "timeout_s": 300 },
  "allowed_tools": ["web.search", "web.fetch"]
}

Skill.md

A skill is a folder containing a SKILL.md file and, if needed, scripts or supporting files. The agent reads only the name and description up front. The full content loads when the agent decides the skill is relevant, which keeps context small.

Folder structure

skills/
└── market-research/
    ├── SKILL.md
    ├── templates/report.md
    └── scripts/calc_prices.py

SKILL.md format

---
name: market-research
description: Research competitors and write a one-page report. Use when asked for market analysis.
tools: [web.search, web.fetch]
---

# Goal
Produce a comparison report of 3 competitors.

# Steps
1. Find competitors with web.search.
2. Fetch each pricing page with web.fetch.
3. Fill in templates/report.md.

# Rules
- Cite a source for every number.
- If data is missing, write "not found".

Frontmatter fields

Writing good skills

• Make the description specific about when to use the skill, not only what it contains.
• Break big tasks into numbered steps.
• Include one example input and output.
• Move long references into separate files to keep SKILL.md short.
• Test with several different goals before sharing.

Tools

Custom tools

liberty.tools.register({
  name: "send_email",
  description: "Send an email to one recipient",
  input: { to: "string", subject: "string", body: "string" },
  permission: "write",
  handler: async ({ to, subject, body }) => { /* send the email */ },
});

Memory

Agents have two kinds of memory: run memory (the context of the current run) and long-term memory (facts you allow to be stored across runs). Long-term memory is optional and can be deleted at any time from the dashboard.

• scope: per agent, per project, or per user.
• retention: set how long memory is kept.
• export and delete: available through the API and dashboard.

API gateway

The gateway is a single endpoint that forwards your request to the model provider you choose. You use one Liberty key, one request format, and one response format.

Your app → Liberty Gateway → Anthropic | Google | OpenAI | Mistral | ...

Free access

Early access members get a free monthly quota for supported models. Quota is counted in credits and may differ between models. Once the quota is used up, requests return 429 unless you add your own provider key.

Bring your own key (BYOK)

You can store your Anthropic, Gemini, OpenAI or other provider keys in the dashboard. Requests to those models then use your key, with no Liberty quota limit.

Providers and models

Model names use the format provider/model. The live model list is shown in the dashboard and may change as providers update.

Provider	Example names	Notes
Anthropic	anthropic/claude-sonnet, anthropic/claude-haiku	Claude: reasoning, code, long documents
Google	google/gemini-pro, google/gemini-flash	Gemini: multimodal, long context
OpenAI	openai/gpt-4o, openai/gpt-4o-mini	ChatGPT / GPT
Mistral	mistral/large, mistral/small	European models, cost efficient
Meta	meta/llama-70b	Llama, open weights
xAI	xai/grok	Grok
DeepSeek	deepseek/chat, deepseek/reasoner	Low cost
Cohere	cohere/command	Retrieval and enterprise
Groq	groq/llama-70b	Very fast inference
Alibaba	qwen/max	Qwen, multilingual

Authentication

Every request uses the Authorization header with the Bearer scheme.

Authorization: Bearer lib_live_xxxxxxxxxxxxxxxx

• Never put keys in client-side code or public repositories.
• Create a separate key for each app so it is easy to revoke.
• Rotate keys regularly from the dashboard.

Chat API

POST /v1/chat creates a response from any model using one format.

Request

Response

{
  "id": "msg_01H...",
  "model": "anthropic/claude-sonnet",
  "content": "Hello! How can I help?",
  "usage": { "input_tokens": 12, "output_tokens": 9, "credits": 0.0004 },
  "finish_reason": "stop"
}

Python example

import os, requests

r = requests.post(
    "https://api.libertyagents.xyz/v1/chat",
    headers={"Authorization": f"Bearer {os.environ['LIBERTY_API_KEY']}"},
    json={"model": "openai/gpt-4o-mini",
          "messages": [{"role": "user", "content": "Explain autonomous agents."}]},
)
print(r.json()["content"])

Streaming

Set stream to true to receive Server-Sent Events. Each event carries a chunk of text.

event: delta
data: {"text":"Hello"}

event: delta
data: {"text":", Liberty!"}

event: done
data: {"usage":{"input_tokens":12,"output_tokens":9}}

Rate limits

Response headers show your remaining limit: X-RateLimit-Remaining and X-RateLimit-Reset. On a 429, wait for the Retry-After time and retry with exponential backoff.

Errors

{ "error": { "code": 429, "type": "rate_limited", "message": "Quota reached. Try again in 30 seconds." } }

Security and privacy

• API keys are stored as hashes and shown only once, when created.
• Provider keys (BYOK) are encrypted at rest.
• Agent code runs in an isolated sandbox with no network access unless you allow it.
• Write actions can require manual approval.
• You can request data deletion at any time.

Prompt injection

Content from web pages or files that an agent reads is data, not instructions. Limit write tools, use guided mode, and review step logs for tasks that touch sensitive data.

Best practices

• Start in guided mode and move to autonomous once results are consistent.
• Always set max_cost and max_steps.
• Use small models for simple steps and larger models for hard reasoning.
• Keep run logs for auditing and debugging.
• Write small, focused skills instead of one huge skill.

FAQ

Is it really free?

Early access includes a limited free quota. Details are announced at launch. After that you can continue with BYOK.

Do I need an account with Anthropic, Google or OpenAI?

Not for the free quota. A provider account is only needed if you use BYOK.

Can skills be used with any model?

Yes. Skill.md is plain Markdown, so it is not tied to one provider.

How is my waitlist number decided?

By signup order. Signing up again with the same email shows the same number.

Changelog