From ebc7990d4ab53fc93cec1376653375d842572c12 Mon Sep 17 00:00:00 2001 From: M N V Sai Krishna Date: Mon, 24 Aug 2026 17:52:32 -0700 Subject: [PATCH 1/3] Add content-builder example and install script. Ship a installable agent example plus `pnpm example:install` so contributors can try TrueForge from the repo without hand-wiring agents. Co-authored-by: Cursor --- examples/README.md | 29 ++++ examples/content-builder/README.md | 146 ++++++++++++++++++ examples/content-builder/agent.json | 28 ++++ examples/content-builder/api/curl.sh | 29 ++++ .../content-builder/api/javascript_fetch.mjs | 101 ++++++++++++ .../content-builder/api/python_requests.py | 84 ++++++++++ examples/content-builder/prompts.md | 15 ++ examples/content-builder/requires.json | 21 +++ examples/content-builder/sdk/run.mjs | 55 +++++++ package.json | 1 + scripts/install-example.mjs | 122 +++++++++++++++ 11 files changed, 631 insertions(+) create mode 100644 examples/README.md create mode 100644 examples/content-builder/README.md create mode 100644 examples/content-builder/agent.json create mode 100755 examples/content-builder/api/curl.sh create mode 100644 examples/content-builder/api/javascript_fetch.mjs create mode 100644 examples/content-builder/api/python_requests.py create mode 100644 examples/content-builder/prompts.md create mode 100644 examples/content-builder/requires.json create mode 100644 examples/content-builder/sdk/run.mjs create mode 100644 scripts/install-example.mjs diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000000..ebe6b066df --- /dev/null +++ b/examples/README.md @@ -0,0 +1,29 @@ +# 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; Parallel web MCP and `web-artifacts-builder` skill installed automatically | + +Start TrueForge: + +```bash +npx @truefoundry/trueforge +``` + +Install an example from this repository: + +```bash +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` — realistic requests to try in the UI +- `README.md` — UI, SDK, and HTTP API access +- `api/` and `sdk/` — runnable clients (where applicable) + +Examples install definitions into TrueForge; the harness executes them. They do not run a separate agent server. diff --git a/examples/content-builder/README.md b/examples/content-builder/README.md new file mode 100644 index 0000000000..d04864fae1 --- /dev/null +++ b/examples/content-builder/README.md @@ -0,0 +1,146 @@ +# 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 | `parallel-web` | Web search via [Parallel Search MCP](https://docs.parallel.ai/integrations/mcp/search-mcp) (free tier, no API key required) | +| Skill | `web-artifacts-builder` | Builds `article.md` and `preview.html` in the sandbox | + +The agent researches a topic with Parallel web search, then uses the skill to produce downloadable Markdown and HTML in the sandbox. + +## Prerequisites + +- Node.js 22 or newer +- A running TrueForge instance with at least one model under **Settings → Models** + +Parallel Search MCP is free without authentication. Optional: add a Parallel API key under **Settings → MCP Servers** for higher rate limits. + +## Install the example + +Start TrueForge: + +```bash +npx @truefoundry/trueforge +``` + +From a clone of this repository, install the agent and its dependencies: + +```bash +pnpm example:install content-builder +``` + +Override the server URL, token, or model when needed: + +```bash +TRUEFORGE_URL=https://trueforge.example.com \ +TRUEFORGE_TOKEN=your-id-token \ +TRUEFORGE_MODEL=anthropic/claude-sonnet-4-6 \ +pnpm example:install content-builder +``` + +## 1. Access via UI + +Open [http://localhost:8790](http://localhost:8790), go to **Agents Library**, find **content-builder**, and click **Try**. + +Try a prompt from [prompts.md](./prompts.md), for example: + +> Write a 1,200-word article for engineering leaders explaining why agent harnesses matter once an AI agent moves from prototype to production. Research current sources, cite them, and produce a polished HTML preview. + +When the turn completes, download files from the chat: + +```text +output/ +├── article.md +├── preview.html +└── social/ # when social content is requested +``` + +## 2. Access via SDK + +Install the TypeScript SDK (skip if you are in the TrueForge monorepo and already built the SDK): + +```bash +npm i @truefoundry/trueforge-sdk +``` + +Run the example script: + +```bash +node sdk/run.mjs +``` + +The script opens a session on `content-builder`, streams one turn, and prints the assistant reply as it arrives. Set `TRUEFORGE_BASE_URL`, `TRUEFORGE_TOKEN`, `TRUEFORGE_AGENT`, or `TRUEFORGE_PROMPT` to customize. + +Minimal inline version: + +```typescript +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 for production. Research first.', + }, + ], +}); + +for await (const { data: event } of stream.withMetadata()) { + if (event.type === 'model.message.delta' && event.threadId === 'main') { + process.stdout.write(event.content ?? ''); + } +} +``` + +See [SDK Quickstart](https://trueforge.dev/api/quickstart) and [Use an agent](https://trueforge.dev/api/use-agent) for sessions, approvals, and reconnects. + +## 3. Access via HTTP API + +All clients use the same two calls: + +1. `POST /api/v1/sessions` with `{ "agent": { "name": "content-builder" } }` +2. `POST /api/v1/sessions/{session_id}/turns` with `{ "input": [{ "type": "user.message", "content": "..." }] }` — returns a Server-Sent Events stream of turn events + +### curl + +```bash +chmod +x api/curl.sh +./api/curl.sh +``` + +### JavaScript (fetch) + +```bash +node api/javascript_fetch.mjs +``` + +### Python (requests) + +```bash +pip install requests +python api/python_requests.py +``` + +When OIDC login is enabled, set `TRUEFORGE_TOKEN` to your ID token for all API and SDK examples. + +## Files in this example + +| File | Purpose | +| --------------- | ------------------------------------------------------- | +| `agent.json` | Agent definition (`$DEFAULT_MODEL` resolved at install) | +| `requires.json` | Parallel MCP + skill + sandbox requirements | +| `prompts.md` | Sample user requests | +| `api/` | curl, fetch, and Python HTTP examples | +| `sdk/run.mjs` | TypeScript SDK example | + +Credentials are never stored in the example. Configure authenticated connectors in TrueForge Settings. diff --git a/examples/content-builder/agent.json b/examples/content-builder/agent.json new file mode 100644 index 0000000000..62039ae63b --- /dev/null +++ b/examples/content-builder/agent.json @@ -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 parallel-web MCP server to search the web and read ranked excerpts 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": "parallel-web", + "enable_tools": ["@all"], + "require_approval_for_tools": [], + "preload": false + } + ], + "skills": [ + { + "name": "web-artifacts-builder" + } + ], + "config": { + "sandbox": { + "enabled": true, + "file_downloads": true + } + } + } +} diff --git a/examples/content-builder/api/curl.sh b/examples/content-builder/api/curl.sh new file mode 100755 index 0000000000..a153e50f17 --- /dev/null +++ b/examples/content-builder/api/curl.sh @@ -0,0 +1,29 @@ +#!/usr/bin/env bash +# Stream one turn against the content-builder agent using curl. +# Prerequisites: content-builder installed (pnpm example:install content-builder). +set -euo pipefail + +BASE_URL="${TRUEFORGE_URL:-http://localhost:8790}" +TOKEN="${TRUEFORGE_TOKEN:-}" +AGENT_NAME="${TRUEFORGE_AGENT:-content-builder}" +PROMPT="${TRUEFORGE_PROMPT:-Write a 600-word article for engineering leaders on why agent harnesses matter in production. Research the topic first and cite sources.}" + +auth_args=() +if [[ -n "$TOKEN" ]]; then + auth_args+=(-H "Authorization: Bearer ${TOKEN}") +fi + +session_json=$(curl -sS "${auth_args[@]}" \ + -X POST "${BASE_URL}/api/v1/sessions" \ + -H 'Content-Type: application/json' \ + -d "{\"agent\":{\"name\":\"${AGENT_NAME}\"}}") + +session_id=$(node -e 'const d=JSON.parse(process.argv[1]); process.stdout.write(d.data.id)' "$session_json") +echo "session: ${session_id}" + +turn_body=$(node -e 'const prompt=process.argv[1]; process.stdout.write(JSON.stringify({input:[{type:"user.message",content:prompt}]}))' "$PROMPT") + +curl -sS -N "${auth_args[@]}" \ + -X POST "${BASE_URL}/api/v1/sessions/${session_id}/turns" \ + -H 'Content-Type: application/json' \ + -d "${turn_body}" diff --git a/examples/content-builder/api/javascript_fetch.mjs b/examples/content-builder/api/javascript_fetch.mjs new file mode 100644 index 0000000000..67ad003bcb --- /dev/null +++ b/examples/content-builder/api/javascript_fetch.mjs @@ -0,0 +1,101 @@ +/** + * Stream one turn against content-builder with fetch (no SDK). + * + * node api/javascript_fetch.mjs + * + * Env: TRUEFORGE_URL, TRUEFORGE_TOKEN (optional), TRUEFORGE_AGENT, TRUEFORGE_PROMPT + */ +const baseUrl = (process.env.TRUEFORGE_URL ?? 'http://localhost:8790').replace(/\/+$/, ''); +const token = process.env.TRUEFORGE_TOKEN; +const agentName = process.env.TRUEFORGE_AGENT ?? 'content-builder'; +const prompt = + process.env.TRUEFORGE_PROMPT ?? + 'Write a 600-word article for engineering leaders on why agent harnesses matter in production. Research the topic first and cite sources.'; + +function headers() { + const h = { 'content-type': 'application/json' }; + if (token) { + h.authorization = `Bearer ${token}`; + } + return h; +} + +async function apiRequest({ path, method = 'GET', body }) { + const response = await fetch(`${baseUrl}${path}`, { + method, + headers: headers(), + body: body === undefined ? undefined : JSON.stringify(body), + }); + if (!response.ok) { + const text = await response.text(); + throw new Error(`${method} ${path} failed (${response.status}): ${text}`); + } + return response; +} + +function parseSseChunk(buffer) { + const events = []; + const blocks = buffer.split('\n\n'); + const remainder = blocks.pop() ?? ''; + for (const block of blocks) { + const dataLine = block + .split('\n') + .find(line => line.startsWith('data:')); + if (!dataLine) { + continue; + } + const payload = dataLine.slice('data:'.length).trim(); + if (payload) { + events.push(JSON.parse(payload)); + } + } + return { events, remainder }; +} + +async function main() { + const sessionResponse = await apiRequest({ + path: '/api/v1/sessions', + method: 'POST', + body: { agent: { name: agentName } }, + }); + const { data: session } = await sessionResponse.json(); + console.log(`session: ${session.id}`); + + const turnResponse = await apiRequest({ + path: `/api/v1/sessions/${encodeURIComponent(session.id)}/turns`, + method: 'POST', + body: { + input: [{ type: 'user.message', content: prompt }], + }, + }); + + const reader = turnResponse.body?.getReader(); + if (!reader) { + throw new Error('Turn response has no body stream'); + } + + const decoder = new TextDecoder(); + let buffer = ''; + while (true) { + const { done, value } = await reader.read(); + if (done) { + break; + } + buffer += decoder.decode(value, { stream: true }); + const parsed = parseSseChunk(buffer); + buffer = parsed.remainder; + for (const event of parsed.events) { + if (event.type === 'model.message.delta' && event.thread_id === 'main') { + process.stdout.write(event.content ?? ''); + } + if (event.type === 'turn.done') { + console.log('\n\nstatus:', event.state?.status); + } + } + } +} + +main().catch(error => { + console.error(error instanceof Error ? error.message : error); + process.exitCode = 1; +}); diff --git a/examples/content-builder/api/python_requests.py b/examples/content-builder/api/python_requests.py new file mode 100644 index 0000000000..17569b4daa --- /dev/null +++ b/examples/content-builder/api/python_requests.py @@ -0,0 +1,84 @@ +""" +Stream one turn against content-builder with Python requests. + + pip install requests + python api/python_requests.py + +Env: TRUEFORGE_URL, TRUEFORGE_TOKEN (optional), TRUEFORGE_AGENT, TRUEFORGE_PROMPT +""" + +import json +import os +import sys + +import requests + +BASE_URL = os.environ.get("TRUEFORGE_URL", "http://localhost:8790").rstrip("/") +TOKEN = os.environ.get("TRUEFORGE_TOKEN") +AGENT_NAME = os.environ.get("TRUEFORGE_AGENT", "content-builder") +PROMPT = os.environ.get( + "TRUEFORGE_PROMPT", + "Write a 600-word article for engineering leaders on why agent harnesses matter in production. " + "Research the topic first and cite sources.", +) + + +def headers() -> dict[str, str]: + h = {"content-type": "application/json"} + if TOKEN: + h["authorization"] = f"Bearer {TOKEN}" + return h + + +def create_session() -> str: + response = requests.post( + f"{BASE_URL}/api/v1/sessions", + headers=headers(), + json={"agent": {"name": AGENT_NAME}}, + timeout=60, + ) + if not response.ok: + raise RuntimeError(f"create session failed ({response.status_code}): {response.text}") + return response.json()["data"]["id"] + + +def stream_turn(session_id: str) -> None: + response = requests.post( + f"{BASE_URL}/api/v1/sessions/{session_id}/turns", + headers=headers(), + json={"input": [{"type": "user.message", "content": PROMPT}]}, + stream=True, + timeout=600, + ) + if not response.ok: + raise RuntimeError(f"create turn failed ({response.status_code}): {response.text}") + + buffer = "" + for chunk in response.iter_content(chunk_size=None, decode_unicode=True): + if not chunk: + continue + buffer += chunk + while "\n\n" in buffer: + block, buffer = buffer.split("\n\n", 1) + data_line = next((line for line in block.split("\n") if line.startswith("data:")), None) + if not data_line: + continue + payload = data_line[len("data:"):].strip() + if not payload: + continue + event = json.loads(payload) + if event.get("type") == "model.message.delta" and event.get("thread_id") == "main": + sys.stdout.write(event.get("content") or "") + sys.stdout.flush() + if event.get("type") == "turn.done": + print("\n\nstatus:", event.get("state", {}).get("status")) + + +def main() -> None: + session_id = create_session() + print(f"session: {session_id}") + stream_turn(session_id) + + +if __name__ == "__main__": + main() diff --git a/examples/content-builder/prompts.md b/examples/content-builder/prompts.md new file mode 100644 index 0000000000..3e4d1fadf2 --- /dev/null +++ b/examples/content-builder/prompts.md @@ -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 Parallel web search, 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 Parallel web search 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 Parallel web search and clearly label trade-offs rather than declaring one universal winner. diff --git a/examples/content-builder/requires.json b/examples/content-builder/requires.json new file mode 100644 index 0000000000..33932f456c --- /dev/null +++ b/examples/content-builder/requires.json @@ -0,0 +1,21 @@ +{ + "mcp_servers": [ + { + "type": "remote", + "name": "parallel-web", + "url": "https://search.parallel.ai/mcp", + "description": "Search the web and get ranked results with extracted content." + } + ], + "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 +} diff --git a/examples/content-builder/sdk/run.mjs b/examples/content-builder/sdk/run.mjs new file mode 100644 index 0000000000..3bb1826c37 --- /dev/null +++ b/examples/content-builder/sdk/run.mjs @@ -0,0 +1,55 @@ +/** + * Stream one turn against content-builder with @truefoundry/trueforge-sdk. + * + * npm i @truefoundry/trueforge-sdk + * node sdk/run.mjs + * + * From this monorepo (after pnpm --filter @truefoundry/trueforge-sdk build): + * node examples/content-builder/sdk/run.mjs + * + * Env: TRUEFORGE_BASE_URL or TRUEFORGE_URL, TRUEFORGE_TOKEN (optional), TRUEFORGE_AGENT, TRUEFORGE_PROMPT + */ +async function loadSdk() { + try { + return await import('@truefoundry/trueforge-sdk'); + } catch { + return await import( + new URL('../../../packages/trueforge-sdk/dist/esm/index.mjs', import.meta.url).href + ); + } +} + +const { TrueForge } = await loadSdk(); + +const baseUrl = ( + process.env.TRUEFORGE_BASE_URL ?? + process.env.TRUEFORGE_URL ?? + 'http://localhost:8790' +).replace(/\/+$/, ''); +const token = process.env.TRUEFORGE_TOKEN; +const agentName = process.env.TRUEFORGE_AGENT ?? 'content-builder'; +const prompt = + process.env.TRUEFORGE_PROMPT ?? + 'Write a 600-word article for engineering leaders on why agent harnesses matter in production. Research the topic first and cite sources.'; + +const client = new TrueForge({ + baseUrl, + ...(token ? { token } : {}), + timeoutInSeconds: 600, +}); + +const { data: session } = await client.sessions.create({ agent: { name: agentName } }); +console.log(`session: ${session.id}`); + +const stream = await client.sessions.createTurnStream(session.id, { + input: [{ type: 'user.message', content: prompt }], +}); + +for await (const { data: event } of stream.withMetadata()) { + if (event.type === 'model.message.delta' && event.threadId === 'main') { + process.stdout.write(event.content ?? ''); + } + if (event.type === 'turn.done') { + console.log('\n\nstatus:', event.state.status); + } +} diff --git a/package.json b/package.json index c54fe7d9b6..7f07d04c47 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/scripts/install-example.mjs b/scripts/install-example.mjs new file mode 100644 index 0000000000..dd2d098bb2 --- /dev/null +++ b/scripts/install-example.mjs @@ -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 '); + } + + 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; +}); From 7c7f5e5cfc88bcf1c369f69603b944e123cd0712 Mon Sep 17 00:00:00 2001 From: M N V Sai Krishna Date: Mon, 24 Aug 2026 19:10:29 -0700 Subject: [PATCH 2/3] Simplify content-builder examples to README snippets. Drop runnable API/SDK scripts; keep short curl, fetch, and Python examples inline. Co-authored-by: Cursor --- examples/README.md | 14 +- examples/content-builder/README.md | 163 +++++++++--------- examples/content-builder/api/curl.sh | 29 ---- .../content-builder/api/javascript_fetch.mjs | 101 ----------- .../content-builder/api/python_requests.py | 84 --------- examples/content-builder/sdk/run.mjs | 55 ------ 6 files changed, 85 insertions(+), 361 deletions(-) delete mode 100755 examples/content-builder/api/curl.sh delete mode 100644 examples/content-builder/api/javascript_fetch.mjs delete mode 100644 examples/content-builder/api/python_requests.py delete mode 100644 examples/content-builder/sdk/run.mjs diff --git a/examples/README.md b/examples/README.md index ebe6b066df..7cea8c22fa 100644 --- a/examples/README.md +++ b/examples/README.md @@ -6,15 +6,8 @@ Working agents you can install into a running TrueForge instance and try from th | ------------------------------------ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | [Content Builder](./content-builder) | Research-driven content creator: sourced article, HTML preview, optional social posts | One model; Parallel web MCP and `web-artifacts-builder` skill installed automatically | -Start TrueForge: - ```bash npx @truefoundry/trueforge -``` - -Install an example from this repository: - -```bash pnpm example:install content-builder ``` @@ -22,8 +15,7 @@ Each example includes: - `agent.json` — one model, one system prompt, one MCP, one skill - `requires.json` — connectors, skills, and runtime capabilities -- `prompts.md` — realistic requests to try in the UI -- `README.md` — UI, SDK, and HTTP API access -- `api/` and `sdk/` — runnable clients (where applicable) +- `prompts.md` — sample requests for the UI +- `README.md` — UI, SDK, and HTTP API snippets -Examples install definitions into TrueForge; the harness executes them. They do not run a separate agent server. +Examples install definitions into TrueForge; the harness runs them. diff --git a/examples/content-builder/README.md b/examples/content-builder/README.md index d04864fae1..e5fa370bdf 100644 --- a/examples/content-builder/README.md +++ b/examples/content-builder/README.md @@ -2,54 +2,29 @@ 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 | `parallel-web` | Web search via [Parallel Search MCP](https://docs.parallel.ai/integrations/mcp/search-mcp) (free tier, no API key required) | -| Skill | `web-artifacts-builder` | Builds `article.md` and `preview.html` in the sandbox | +| 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 | `parallel-web` | Web search via [Parallel Search MCP](https://docs.parallel.ai/integrations/mcp/search-mcp) (free, no API key required) | +| Skill | `web-artifacts-builder` | Builds `article.md` and `preview.html` in the sandbox | -The agent researches a topic with Parallel web search, then uses the skill to produce downloadable Markdown and HTML in the sandbox. - -## Prerequisites - -- Node.js 22 or newer -- A running TrueForge instance with at least one model under **Settings → Models** - -Parallel Search MCP is free without authentication. Optional: add a Parallel API key under **Settings → MCP Servers** for higher rate limits. - -## Install the example - -Start TrueForge: +## Install ```bash npx @truefoundry/trueforge -``` - -From a clone of this repository, install the agent and its dependencies: - -```bash pnpm example:install content-builder ``` -Override the server URL, token, or model when needed: +Needs a model under **Settings → Models**. Override with `TRUEFORGE_URL`, `TRUEFORGE_TOKEN`, or `TRUEFORGE_MODEL` if needed. -```bash -TRUEFORGE_URL=https://trueforge.example.com \ -TRUEFORGE_TOKEN=your-id-token \ -TRUEFORGE_MODEL=anthropic/claude-sonnet-4-6 \ -pnpm example:install content-builder -``` - -## 1. Access via UI - -Open [http://localhost:8790](http://localhost:8790), go to **Agents Library**, find **content-builder**, and click **Try**. +## 1. UI -Try a prompt from [prompts.md](./prompts.md), for example: +Open [http://localhost:8790](http://localhost:8790) → **Agents Library** → **content-builder** → **Try**. -> Write a 1,200-word article for engineering leaders explaining why agent harnesses matter once an AI agent moves from prototype to production. Research current sources, cite them, and produce a polished HTML preview. +Sample prompts: [prompts.md](./prompts.md). -When the turn completes, download files from the chat: +When done, download from chat: ```text output/ @@ -58,89 +33,115 @@ output/ └── social/ # when social content is requested ``` -## 2. Access via SDK - -Install the TypeScript SDK (skip if you are in the TrueForge monorepo and already built the SDK): +## 2. SDK ```bash npm i @truefoundry/trueforge-sdk ``` -Run the example script: - -```bash -node sdk/run.mjs -``` - -The script opens a session on `content-builder`, streams one turn, and prints the assistant reply as it arrives. Set `TRUEFORGE_BASE_URL`, `TRUEFORGE_TOKEN`, `TRUEFORGE_AGENT`, or `TRUEFORGE_PROMPT` to customize. - -Minimal inline version: - -```typescript +```js import { TrueForge } from '@truefoundry/trueforge-sdk'; -const client = new TrueForge({ - baseUrl: 'http://localhost:8790', - timeoutInSeconds: 600, -}); +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 for production. Research first.', - }, - ], + 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' && event.threadId === 'main') { - process.stdout.write(event.content ?? ''); - } + if (event.type === 'model.message.delta') process.stdout.write(event.content ?? ''); } ``` -See [SDK Quickstart](https://trueforge.dev/api/quickstart) and [Use an agent](https://trueforge.dev/api/use-agent) for sessions, approvals, and reconnects. +## 3. HTTP API -## 3. Access via HTTP API - -All clients use the same two calls: - -1. `POST /api/v1/sessions` with `{ "agent": { "name": "content-builder" } }` -2. `POST /api/v1/sessions/{session_id}/turns` with `{ "input": [{ "type": "user.message", "content": "..." }] }` — returns a Server-Sent Events stream of turn events +Same flow for every client: create a session, then create a turn with `stream: false` and poll until it finishes. ### curl ```bash -chmod +x api/curl.sh -./api/curl.sh +# 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) -```bash -node api/javascript_fetch.mjs +```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 api/python_requests.py ``` -When OIDC login is enabled, set `TRUEFORGE_TOKEN` to your ID token for all API and SDK examples. +```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 ` on every request (SDK: pass `token`). -## Files in this example +## Files | File | Purpose | | --------------- | ------------------------------------------------------- | | `agent.json` | Agent definition (`$DEFAULT_MODEL` resolved at install) | | `requires.json` | Parallel MCP + skill + sandbox requirements | | `prompts.md` | Sample user requests | -| `api/` | curl, fetch, and Python HTTP examples | -| `sdk/run.mjs` | TypeScript SDK example | -Credentials are never stored in the example. Configure authenticated connectors in TrueForge Settings. +Credentials are never stored here — configure them in TrueForge Settings. diff --git a/examples/content-builder/api/curl.sh b/examples/content-builder/api/curl.sh deleted file mode 100755 index a153e50f17..0000000000 --- a/examples/content-builder/api/curl.sh +++ /dev/null @@ -1,29 +0,0 @@ -#!/usr/bin/env bash -# Stream one turn against the content-builder agent using curl. -# Prerequisites: content-builder installed (pnpm example:install content-builder). -set -euo pipefail - -BASE_URL="${TRUEFORGE_URL:-http://localhost:8790}" -TOKEN="${TRUEFORGE_TOKEN:-}" -AGENT_NAME="${TRUEFORGE_AGENT:-content-builder}" -PROMPT="${TRUEFORGE_PROMPT:-Write a 600-word article for engineering leaders on why agent harnesses matter in production. Research the topic first and cite sources.}" - -auth_args=() -if [[ -n "$TOKEN" ]]; then - auth_args+=(-H "Authorization: Bearer ${TOKEN}") -fi - -session_json=$(curl -sS "${auth_args[@]}" \ - -X POST "${BASE_URL}/api/v1/sessions" \ - -H 'Content-Type: application/json' \ - -d "{\"agent\":{\"name\":\"${AGENT_NAME}\"}}") - -session_id=$(node -e 'const d=JSON.parse(process.argv[1]); process.stdout.write(d.data.id)' "$session_json") -echo "session: ${session_id}" - -turn_body=$(node -e 'const prompt=process.argv[1]; process.stdout.write(JSON.stringify({input:[{type:"user.message",content:prompt}]}))' "$PROMPT") - -curl -sS -N "${auth_args[@]}" \ - -X POST "${BASE_URL}/api/v1/sessions/${session_id}/turns" \ - -H 'Content-Type: application/json' \ - -d "${turn_body}" diff --git a/examples/content-builder/api/javascript_fetch.mjs b/examples/content-builder/api/javascript_fetch.mjs deleted file mode 100644 index 67ad003bcb..0000000000 --- a/examples/content-builder/api/javascript_fetch.mjs +++ /dev/null @@ -1,101 +0,0 @@ -/** - * Stream one turn against content-builder with fetch (no SDK). - * - * node api/javascript_fetch.mjs - * - * Env: TRUEFORGE_URL, TRUEFORGE_TOKEN (optional), TRUEFORGE_AGENT, TRUEFORGE_PROMPT - */ -const baseUrl = (process.env.TRUEFORGE_URL ?? 'http://localhost:8790').replace(/\/+$/, ''); -const token = process.env.TRUEFORGE_TOKEN; -const agentName = process.env.TRUEFORGE_AGENT ?? 'content-builder'; -const prompt = - process.env.TRUEFORGE_PROMPT ?? - 'Write a 600-word article for engineering leaders on why agent harnesses matter in production. Research the topic first and cite sources.'; - -function headers() { - const h = { 'content-type': 'application/json' }; - if (token) { - h.authorization = `Bearer ${token}`; - } - return h; -} - -async function apiRequest({ path, method = 'GET', body }) { - const response = await fetch(`${baseUrl}${path}`, { - method, - headers: headers(), - body: body === undefined ? undefined : JSON.stringify(body), - }); - if (!response.ok) { - const text = await response.text(); - throw new Error(`${method} ${path} failed (${response.status}): ${text}`); - } - return response; -} - -function parseSseChunk(buffer) { - const events = []; - const blocks = buffer.split('\n\n'); - const remainder = blocks.pop() ?? ''; - for (const block of blocks) { - const dataLine = block - .split('\n') - .find(line => line.startsWith('data:')); - if (!dataLine) { - continue; - } - const payload = dataLine.slice('data:'.length).trim(); - if (payload) { - events.push(JSON.parse(payload)); - } - } - return { events, remainder }; -} - -async function main() { - const sessionResponse = await apiRequest({ - path: '/api/v1/sessions', - method: 'POST', - body: { agent: { name: agentName } }, - }); - const { data: session } = await sessionResponse.json(); - console.log(`session: ${session.id}`); - - const turnResponse = await apiRequest({ - path: `/api/v1/sessions/${encodeURIComponent(session.id)}/turns`, - method: 'POST', - body: { - input: [{ type: 'user.message', content: prompt }], - }, - }); - - const reader = turnResponse.body?.getReader(); - if (!reader) { - throw new Error('Turn response has no body stream'); - } - - const decoder = new TextDecoder(); - let buffer = ''; - while (true) { - const { done, value } = await reader.read(); - if (done) { - break; - } - buffer += decoder.decode(value, { stream: true }); - const parsed = parseSseChunk(buffer); - buffer = parsed.remainder; - for (const event of parsed.events) { - if (event.type === 'model.message.delta' && event.thread_id === 'main') { - process.stdout.write(event.content ?? ''); - } - if (event.type === 'turn.done') { - console.log('\n\nstatus:', event.state?.status); - } - } - } -} - -main().catch(error => { - console.error(error instanceof Error ? error.message : error); - process.exitCode = 1; -}); diff --git a/examples/content-builder/api/python_requests.py b/examples/content-builder/api/python_requests.py deleted file mode 100644 index 17569b4daa..0000000000 --- a/examples/content-builder/api/python_requests.py +++ /dev/null @@ -1,84 +0,0 @@ -""" -Stream one turn against content-builder with Python requests. - - pip install requests - python api/python_requests.py - -Env: TRUEFORGE_URL, TRUEFORGE_TOKEN (optional), TRUEFORGE_AGENT, TRUEFORGE_PROMPT -""" - -import json -import os -import sys - -import requests - -BASE_URL = os.environ.get("TRUEFORGE_URL", "http://localhost:8790").rstrip("/") -TOKEN = os.environ.get("TRUEFORGE_TOKEN") -AGENT_NAME = os.environ.get("TRUEFORGE_AGENT", "content-builder") -PROMPT = os.environ.get( - "TRUEFORGE_PROMPT", - "Write a 600-word article for engineering leaders on why agent harnesses matter in production. " - "Research the topic first and cite sources.", -) - - -def headers() -> dict[str, str]: - h = {"content-type": "application/json"} - if TOKEN: - h["authorization"] = f"Bearer {TOKEN}" - return h - - -def create_session() -> str: - response = requests.post( - f"{BASE_URL}/api/v1/sessions", - headers=headers(), - json={"agent": {"name": AGENT_NAME}}, - timeout=60, - ) - if not response.ok: - raise RuntimeError(f"create session failed ({response.status_code}): {response.text}") - return response.json()["data"]["id"] - - -def stream_turn(session_id: str) -> None: - response = requests.post( - f"{BASE_URL}/api/v1/sessions/{session_id}/turns", - headers=headers(), - json={"input": [{"type": "user.message", "content": PROMPT}]}, - stream=True, - timeout=600, - ) - if not response.ok: - raise RuntimeError(f"create turn failed ({response.status_code}): {response.text}") - - buffer = "" - for chunk in response.iter_content(chunk_size=None, decode_unicode=True): - if not chunk: - continue - buffer += chunk - while "\n\n" in buffer: - block, buffer = buffer.split("\n\n", 1) - data_line = next((line for line in block.split("\n") if line.startswith("data:")), None) - if not data_line: - continue - payload = data_line[len("data:"):].strip() - if not payload: - continue - event = json.loads(payload) - if event.get("type") == "model.message.delta" and event.get("thread_id") == "main": - sys.stdout.write(event.get("content") or "") - sys.stdout.flush() - if event.get("type") == "turn.done": - print("\n\nstatus:", event.get("state", {}).get("status")) - - -def main() -> None: - session_id = create_session() - print(f"session: {session_id}") - stream_turn(session_id) - - -if __name__ == "__main__": - main() diff --git a/examples/content-builder/sdk/run.mjs b/examples/content-builder/sdk/run.mjs deleted file mode 100644 index 3bb1826c37..0000000000 --- a/examples/content-builder/sdk/run.mjs +++ /dev/null @@ -1,55 +0,0 @@ -/** - * Stream one turn against content-builder with @truefoundry/trueforge-sdk. - * - * npm i @truefoundry/trueforge-sdk - * node sdk/run.mjs - * - * From this monorepo (after pnpm --filter @truefoundry/trueforge-sdk build): - * node examples/content-builder/sdk/run.mjs - * - * Env: TRUEFORGE_BASE_URL or TRUEFORGE_URL, TRUEFORGE_TOKEN (optional), TRUEFORGE_AGENT, TRUEFORGE_PROMPT - */ -async function loadSdk() { - try { - return await import('@truefoundry/trueforge-sdk'); - } catch { - return await import( - new URL('../../../packages/trueforge-sdk/dist/esm/index.mjs', import.meta.url).href - ); - } -} - -const { TrueForge } = await loadSdk(); - -const baseUrl = ( - process.env.TRUEFORGE_BASE_URL ?? - process.env.TRUEFORGE_URL ?? - 'http://localhost:8790' -).replace(/\/+$/, ''); -const token = process.env.TRUEFORGE_TOKEN; -const agentName = process.env.TRUEFORGE_AGENT ?? 'content-builder'; -const prompt = - process.env.TRUEFORGE_PROMPT ?? - 'Write a 600-word article for engineering leaders on why agent harnesses matter in production. Research the topic first and cite sources.'; - -const client = new TrueForge({ - baseUrl, - ...(token ? { token } : {}), - timeoutInSeconds: 600, -}); - -const { data: session } = await client.sessions.create({ agent: { name: agentName } }); -console.log(`session: ${session.id}`); - -const stream = await client.sessions.createTurnStream(session.id, { - input: [{ type: 'user.message', content: prompt }], -}); - -for await (const { data: event } of stream.withMetadata()) { - if (event.type === 'model.message.delta' && event.threadId === 'main') { - process.stdout.write(event.content ?? ''); - } - if (event.type === 'turn.done') { - console.log('\n\nstatus:', event.state.status); - } -} From b01f5b8c5379d34f6e38056fc2126c52548b63e1 Mon Sep 17 00:00:00 2001 From: M N V Sai Krishna Date: Mon, 24 Aug 2026 20:20:11 -0700 Subject: [PATCH 3/3] Align the content-builder example with the docs walkthrough. Use the shipped Exa catalog connector instead of Parallel, and name the TypeScript client as @truefoundry/trueforge-sdk. Co-authored-by: Cursor --- docs/introduction.mdx | 2 +- examples/README.md | 6 +++--- examples/content-builder/README.md | 16 ++++++++-------- examples/content-builder/agent.json | 4 ++-- examples/content-builder/prompts.md | 6 +++--- examples/content-builder/requires.json | 6 +++--- 6 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/introduction.mdx b/docs/introduction.mdx index 6c8a06cd0f..a8b6e0d028 100644 --- a/docs/introduction.mdx +++ b/docs/introduction.mdx @@ -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). diff --git a/examples/README.md b/examples/README.md index 7cea8c22fa..bc13f25ab8 100644 --- a/examples/README.md +++ b/examples/README.md @@ -2,9 +2,9 @@ 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; Parallel web MCP and `web-artifacts-builder` skill installed automatically | +| 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 diff --git a/examples/content-builder/README.md b/examples/content-builder/README.md index e5fa370bdf..1ba06dfe59 100644 --- a/examples/content-builder/README.md +++ b/examples/content-builder/README.md @@ -2,12 +2,12 @@ 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 | `parallel-web` | Web search via [Parallel Search MCP](https://docs.parallel.ai/integrations/mcp/search-mcp) (free, no API key required) | -| Skill | `web-artifacts-builder` | Builds `article.md` and `preview.html` in the sandbox | +| 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 @@ -16,7 +16,7 @@ npx @truefoundry/trueforge pnpm example:install content-builder ``` -Needs a model under **Settings → Models**. Override with `TRUEFORGE_URL`, `TRUEFORGE_TOKEN`, or `TRUEFORGE_MODEL` if needed. +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 @@ -141,7 +141,7 @@ When OIDC login is enabled, send `Authorization: Bearer ` on every req | File | Purpose | | --------------- | ------------------------------------------------------- | | `agent.json` | Agent definition (`$DEFAULT_MODEL` resolved at install) | -| `requires.json` | Parallel MCP + skill + sandbox requirements | +| `requires.json` | Exa MCP + skill + sandbox requirements | | `prompts.md` | Sample user requests | Credentials are never stored here — configure them in TrueForge Settings. diff --git a/examples/content-builder/agent.json b/examples/content-builder/agent.json index 62039ae63b..29726fe7c1 100644 --- a/examples/content-builder/agent.json +++ b/examples/content-builder/agent.json @@ -4,10 +4,10 @@ "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 parallel-web MCP server to search the web and read ranked excerpts 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.", + "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": "parallel-web", + "name": "exa", "enable_tools": ["@all"], "require_approval_for_tools": [], "preload": false diff --git a/examples/content-builder/prompts.md b/examples/content-builder/prompts.md index 3e4d1fadf2..38ed6397ca 100644 --- a/examples/content-builder/prompts.md +++ b/examples/content-builder/prompts.md @@ -4,12 +4,12 @@ Use these in the UI, or set `TRUEFORGE_PROMPT` when running the API or SDK examp ## 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 Parallel web search, support important claims with sources, and produce a polished HTML preview. +> 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 Parallel web search before writing and avoid generic AI marketing language. +> 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 Parallel web search and clearly label trade-offs rather than declaring one universal winner. +> 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. diff --git a/examples/content-builder/requires.json b/examples/content-builder/requires.json index 33932f456c..44d35d7e39 100644 --- a/examples/content-builder/requires.json +++ b/examples/content-builder/requires.json @@ -2,9 +2,9 @@ "mcp_servers": [ { "type": "remote", - "name": "parallel-web", - "url": "https://search.parallel.ai/mcp", - "description": "Search the web and get ranked results with extracted content." + "name": "exa", + "url": "https://mcp.exa.ai/mcp", + "description": "Search the web, fetch page contents, and find similar pages." } ], "skills": [