Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/introduction.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ The services the loop talks to — [model providers](/models), [MCP servers](/mc
Everything the server does is exposed as an API, so anything you see in the UI you can automate:

- REST + Server-Sent Events, with an OpenAPI spec and interactive docs at `/api/v1/docs`
- A TypeScript SDK (`@truefoundry/trueforge-core`) to create and call agents from your own code
- A TypeScript SDK (`@truefoundry/trueforge-sdk`) to create and call agents from your own code

See the [SDK Quickstart](/api/quickstart).

Expand Down
21 changes: 21 additions & 0 deletions examples/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
# TrueForge Examples

Working agents you can install into a running TrueForge instance and try from the Agents Library, SDK, or HTTP API.

| Example | What it does | Requirements |
| ------------------------------------ | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| [Content Builder](./content-builder) | Research-driven content creator: sourced article, HTML preview, optional social posts | One model; Exa MCP and `web-artifacts-builder` skill installed automatically |

```bash
npx @truefoundry/trueforge
pnpm example:install content-builder
```

Each example includes:

- `agent.json` — one model, one system prompt, one MCP, one skill
- `requires.json` — connectors, skills, and runtime capabilities
- `prompts.md` — sample requests for the UI
- `README.md` — UI, SDK, and HTTP API snippets

Examples install definitions into TrueForge; the harness runs them.
147 changes: 147 additions & 0 deletions examples/content-builder/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,147 @@
# Content Builder

A simple **content creator** agent for learning TrueForge. It uses exactly one model, one system prompt, one MCP server, and one skill.

| Piece | Name | Role |
| ------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------- |
| Model | Your configured default (`$DEFAULT_MODEL` at install) | Writes and reasons |
| System prompt | `instructions` in `agent.json` | Research-first content workflow |
| MCP | `exa` | Web search via [Exa](https://exa.ai) (catalog connector; no API key required) |
| Skill | `web-artifacts-builder` | Builds `article.md` and `preview.html` in the sandbox |

## Install

```bash
npx @truefoundry/trueforge
pnpm example:install content-builder
```

Needs a model under **Settings → Models**. Skills need a sandbox under **Settings → Sandbox providers** (Daytona). Override with `TRUEFORGE_URL`, `TRUEFORGE_TOKEN`, or `TRUEFORGE_MODEL` if needed.

## 1. UI

Open [http://localhost:8790](http://localhost:8790) → **Agents Library** → **content-builder** → **Try**.

Sample prompts: [prompts.md](./prompts.md).

When done, download from chat:

```text
output/
├── article.md
├── preview.html
└── social/ # when social content is requested
```

## 2. SDK

```bash
npm i @truefoundry/trueforge-sdk
```

```js
import { TrueForge } from '@truefoundry/trueforge-sdk';

const client = new TrueForge({ baseUrl: 'http://localhost:8790', timeoutInSeconds: 600 });

const { data: session } = await client.sessions.create({ agent: { name: 'content-builder' } });

const stream = await client.sessions.createTurnStream(session.id, {
input: [{ type: 'user.message', content: 'Write a short blog post on agent harnesses. Research first.' }],
});

for await (const { data: event } of stream.withMetadata()) {
if (event.type === 'model.message.delta') process.stdout.write(event.content ?? '');
}
```

## 3. HTTP API

Same flow for every client: create a session, then create a turn with `stream: false` and poll until it finishes.

### curl

```bash
# Create a session
SESSION=$(curl -s http://localhost:8790/api/v1/sessions \
-H 'Content-Type: application/json' \
-d '{"agent":{"name":"content-builder"}}' | jq -r .data.id)

# Start a turn (non-streaming)
TURN=$(curl -s "http://localhost:8790/api/v1/sessions/$SESSION/turns" \
-H 'Content-Type: application/json' \
-d '{"stream":false,"input":[{"type":"user.message","content":"Write a short blog post on agent harnesses. Research first."}]}' \
| jq -r .data.id)

# Poll until done
curl -s "http://localhost:8790/api/v1/sessions/$SESSION/turns/$TURN" | jq .
```

### JavaScript (fetch)

```js
const base = 'http://localhost:8790';

const { data: session } = await fetch(`${base}/api/v1/sessions`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ agent: { name: 'content-builder' } }),
}).then(r => r.json());

let { data: turn } = await fetch(`${base}/api/v1/sessions/${session.id}/turns`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
stream: false,
input: [{ type: 'user.message', content: 'Write a short blog post on agent harnesses. Research first.' }],
}),
}).then(r => r.json());

while (turn.state.status === 'running') {
await new Promise(r => setTimeout(r, 1000));
({ data: turn } = await fetch(`${base}/api/v1/sessions/${session.id}/turns/${turn.id}`).then(r => r.json()));
}

console.log(turn.state.output?.content ?? turn.state);
```

### Python (requests)

```bash
pip install requests
```

```python
import time
import requests

base = "http://localhost:8790"

session = requests.post(f"{base}/api/v1/sessions", json={"agent": {"name": "content-builder"}}).json()["data"]

turn = requests.post(
f"{base}/api/v1/sessions/{session['id']}/turns",
json={
"stream": False,
"input": [{"type": "user.message", "content": "Write a short blog post on agent harnesses. Research first."}],
},
).json()["data"]

while turn["state"]["status"] == "running":
time.sleep(1)
turn = requests.get(f"{base}/api/v1/sessions/{session['id']}/turns/{turn['id']}").json()["data"]

print(turn["state"].get("output", {}).get("content") or turn["state"])
```

When OIDC login is enabled, send `Authorization: Bearer <id_token>` on every request (SDK: pass `token`).

## Files

| File | Purpose |
| --------------- | ------------------------------------------------------- |
| `agent.json` | Agent definition (`$DEFAULT_MODEL` resolved at install) |
| `requires.json` | Exa MCP + skill + sandbox requirements |
| `prompts.md` | Sample user requests |

Credentials are never stored here — configure them in TrueForge Settings.
28 changes: 28 additions & 0 deletions examples/content-builder/agent.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
{
"name": "content-builder",
"manifest": {
"model": {
"name": "$DEFAULT_MODEL"
},
"instructions": "You are a content creator. Turn a topic and audience into a polished, factual content package.\n\nResearch before you write: use the Exa MCP server to search the web and pull content from authoritative sources. Keep URLs with your notes. Do not invent facts, quotes, or statistics.\n\nUse the web-artifacts-builder skill in the sandbox to produce the final deliverables. Always create `output/article.md` and `output/preview.html`. The Markdown article needs a title, short summary, structured body, optional call to action, and a Sources section listing URLs you actually used. The HTML preview must be a polished, self-contained rendering of the same article with no external scripts. When the user asks for social posts, also add platform-specific files under `output/social/`.\n\nBefore finishing, check for unsupported claims, repetition, and audience fit. In your final reply, summarize what you created and list every generated file.",
"mcp_servers": [
{
"name": "exa",
"enable_tools": ["@all"],
"require_approval_for_tools": [],
"preload": false
}
],
"skills": [
{
"name": "web-artifacts-builder"
}
],
"config": {
"sandbox": {
"enabled": true,
"file_downloads": true
}
}
}
}
15 changes: 15 additions & 0 deletions examples/content-builder/prompts.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Prompts to try

Use these in the UI, or set `TRUEFORGE_PROMPT` when running the API or SDK examples.

## Blog post

> Write a 1,200-word article for engineering leaders explaining why agent harnesses matter once an AI agent moves from a prototype to production. Use a practical, direct tone. Research with Exa, support important claims with sources, and produce a polished HTML preview.

## Product launch package

> Create a launch package for an open-source agent harness aimed at platform engineering teams. Produce a technical blog post, a LinkedIn post, and a five-post social thread. Research the current agent framework landscape with Exa before writing and avoid generic AI marketing language.

## Opinionated comparison

> Write a balanced comparison of hosted agent harnesses and in-process agent frameworks for a staff engineer choosing an architecture. Cover deployment, tool security, persistence, observability, and operational ownership. Research current primary sources with Exa and clearly label trade-offs rather than declaring one universal winner.
21 changes: 21 additions & 0 deletions examples/content-builder/requires.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
{
"mcp_servers": [
{
"type": "remote",
"name": "exa",
"url": "https://mcp.exa.ai/mcp",
"description": "Search the web, fetch page contents, and find similar pages."
}
],
"skills": [
{
"type": "git",
"name": "web-artifacts-builder",
"url": "https://github.com/anthropics/skills",
"path": "skills/web-artifacts-builder",
"ref": "main",
"description": "Build self-contained web artifacts that render as interactive standalone pages."
}
],
"sandbox": true
}
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@
"changeset:sdk-regen": "bash scripts/changeset-sdk-regen.sh",
"clean:all": "node scripts/clean.mjs --dependencies",
"clean": "node scripts/clean.mjs",
"example:install": "node scripts/install-example.mjs",
"dev:infra": "docker compose -f docker-compose.dev.yml up",
"dev:no-watch": "STANDALONE=false NODE_ENV=development pnpm --parallel --filter @truefoundry/trueforge --filter frontend dev:no-watch",
"dev:server:ui": "pnpm --filter frontend build && pnpm --filter @truefoundry/trueforge build:frontend-assets && STANDALONE=false NODE_ENV=development pnpm --parallel --filter @truefoundry/trueforge-core --filter @truefoundry/trueforge dev",
Expand Down
122 changes: 122 additions & 0 deletions scripts/install-example.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,122 @@
import { readFile } from 'node:fs/promises';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';

const workspaceRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
const exampleNamePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;

function getHeaders() {
const headers = { 'content-type': 'application/json' };
const token = process.env.TRUEFORGE_TOKEN;
if (token) {
headers.authorization = `Bearer ${token}`;
}
return headers;
}

function getBaseUrl() {
return (process.env.TRUEFORGE_URL ?? 'http://localhost:8790').replace(/\/+$/, '');
}

async function apiRequest({ path, method = 'GET', body }) {
const response = await globalThis.fetch(`${getBaseUrl()}${path}`, {
method,
headers: getHeaders(),
body: body === undefined ? undefined : JSON.stringify(body),
});

const text = await response.text();
const payload = text ? JSON.parse(text) : {};
if (!response.ok) {
const detail = payload.error?.message ?? text ?? response.statusText;
throw new Error(`${method} ${path} failed (${String(response.status)}): ${detail}`);
}
return payload;
}

async function readJson(path) {
return JSON.parse(await readFile(path, 'utf8'));
}

async function resolveModel() {
if (process.env.TRUEFORGE_MODEL) {
return process.env.TRUEFORGE_MODEL;
}

const response = await apiRequest({ path: '/api/v1/models' });
const model = response.data?.[0]?.name;
if (!model) {
throw new Error(
'No configured model found. Add one under Settings → Models or set TRUEFORGE_MODEL before installing.',
);
}
return model;
}

async function installMissingResources({ path, resources }) {
const configured = await apiRequest({ path });
const configuredNames = new Set(configured.data.map(item => item.name));

for (const manifest of resources) {
if (configuredNames.has(manifest.name)) {
continue;
}
await apiRequest({ path, method: 'PUT', body: { manifest } });
console.log(`Configured ${manifest.name}`);
}
}

async function installAgent({ definition, model }) {
const manifest = globalThis.structuredClone(definition.manifest);
manifest.model.name = manifest.model.name === '$DEFAULT_MODEL' ? model : manifest.model.name;

const agents = await apiRequest({ path: '/api/v1/agents' });
const existing = agents.data.find(agent => agent.name === definition.name);
if (existing) {
await apiRequest({
path: `/api/v1/agents/${encodeURIComponent(existing.id)}`,
method: 'PUT',
body: { manifest },
});
console.log(`Updated agent ${definition.name}`);
return;
}

await apiRequest({
path: '/api/v1/agents',
method: 'POST',
body: { name: definition.name, manifest },
});
console.log(`Installed agent ${definition.name}`);
}

async function main() {
const exampleName = process.argv[2];
if (!exampleName || !exampleNamePattern.test(exampleName)) {
throw new Error('Usage: pnpm example:install <example-name>');
}

const exampleDirectory = join(workspaceRoot, 'examples', exampleName);
const [definition, requirements, model] = await Promise.all([
readJson(join(exampleDirectory, 'agent.json')),
readJson(join(exampleDirectory, 'requires.json')),
resolveModel(),
]);

await installMissingResources({
path: '/api/v1/settings/mcp-servers',
resources: requirements.mcp_servers ?? [],
});
await installMissingResources({
path: '/api/v1/settings/skills',
resources: requirements.skills ?? [],
});
await installAgent({ definition, model });

console.log(`Open ${getBaseUrl()} and try ${definition.name} from the Agents Library.`);
}

main().catch(error => {
console.error(error instanceof Error ? error.message : error);
process.exitCode = 1;
});