The open-source agent harness - the runtime layer that turns an LLM into a working agent.
docs: align SDK cookbook and agent spec with the live API (#334)
Bhavesh Patel4fc9551f0bf6
diff --git a/docs/api/overview.mdx b/docs/api/overview.mdxindex cf0e5fbcc..4aeaae4e9 100644--- a/docs/api/overview.mdx+++ b/docs/api/overview.mdx@@ -72,7 +72,7 @@ Jane's follow-ups about the refund stay in `sess-7f2a9c1b`. Bob's question runs```json Session for Jane's refund issue wrap{"id": "sess-7f2a9c1b",- "agent": { "type": "ref", "agent_id": "agent-support-bot" },+ "agent": { "type": "reference", "id": "agt_01jc...", "name": "support-bot" },"title": "Refund for ORD-2031","created_by": "trueforge-default","created_at": "2026-06-24T10:00:00Z",diff --git a/docs/api/use-agent.mdx b/docs/api/use-agent.mdxindex 41eb2d0c9..e3d30c49d 100644--- a/docs/api/use-agent.mdx+++ b/docs/api/use-agent.mdx@@ -1,7 +1,7 @@---title: 'Use an agent'sidebarTitle: 'Use an agent'-description: 'Run a saved agent with the TypeScript SDK: a complete example, then recipes for streaming, approvals, questions, threads, and reconnects.'+description: 'Run a saved agent with the TypeScript SDK: a Quick Start, then recipes for streaming, approvals, questions, threads, and reconnects.'---The recipe book for running an agent with [`@truefoundry/trueforge-sdk`](https://www.npmjs.com/package/@truefoundry/trueforge-sdk). New here? Install and stream your first turn in the [SDK Quickstart](/api/quickstart) first. For the mental model (Agent → Session → Turn → Event → Delta), see [Concepts](/api/overview); for every event field, see the [turn events reference](#turn-events-reference) at the bottom of this page.@@ -30,7 +30,7 @@ const client = new TrueForge({Point `baseUrl` at your running TrueForge server; `http://localhost:8790` is the Quickstart default. When [OIDC login](/authentication/overview) is enabled, pass `token` (an ID token from your IdP; see [Get a token and connect](/api/quickstart#get-a-token-and-connect)). When login is off, omit it.-## A complete example+## Quick StartThe [Concepts](/api/overview) page explains the model with a conceptual `support-bot`; here is a real agent you can run. In the [Quickstart](/quickstart) you built **`web-research-brief`**, an agent with Exa web search and the web-artifacts-builder skill. Here it is from the SDK: open a session on that agent, stream one research turn, and print the brief as it arrives. It fans out to [subagents](/key-features/subagents), so you'll see their threads in the same stream. It has no approval gate, so it runs end to end without pausing; for the approval and question pauses, see [Handle pauses](#handle-pauses).@@ -68,20 +68,6 @@ for await (const { data: event } of stream.withMetadata()) {That's the core loop: open a session, stream a turn, print the reply as it arrives, and read the final `turn.done`. This version writes each delta straight to stdout. The [next section](#create-and-stream-a-turn) keeps an id-keyed event index, the pattern the pause recipes build on. The rest of the page is a reference for each piece, plus the pauses (approvals, questions, MCP auth) a real agent runs into.-## At a glance--| Method | What it does |-| --- | --- |-| `sessions.create` | Open a session (by agent name or inline spec) |-| `sessions.list` | List sessions (newest-first; filter by `agentId`) |-| `sessions.createTurnStream` | Create a turn and stream its events (SSE) |-| `sessions.createTurn` | Create a turn without streaming (then poll `getTurn`) |-| `sessions.getTurn` | Fetch a turn's current `state` |-| `sessions.listTurns` | List a session's turns (oldest-first) |-| `sessions.subscribeToTurn` | Reconnect to a running turn's stream |-| `sessions.listTurnEvents` | Replay a finished turn's events (already merged) |-| `sessions.cancel` | Cancel the running turn |-## SessionsA **session** is the conversation context for one issue; it persists across turns. Persist `session.id` to resume later.@@ -489,7 +475,7 @@ if (turn.state.status === 'running') {### Subagent threads-A turn stream interleaves the root agent and any parallel [subagents](/key-features/subagents), exactly what the [complete example](#a-complete-example) above does. Every event carries a `threadId`:+A turn stream interleaves the root agent and any parallel [subagents](/key-features/subagents), exactly what the [Quick Start](#quick-start) above does. Every event carries a `threadId`:- `"main"`: the root agent.- A unique id: a subagent thread. [`thread.created`](#thread-created) and [`thread.done`](#thread-done) bracket its lifecycle.diff --git a/docs/create-agent/overview.mdx b/docs/create-agent/overview.mdxindex c24b08cda..845db64a3 100644--- a/docs/create-agent/overview.mdx+++ b/docs/create-agent/overview.mdx@@ -232,7 +232,7 @@ const { data: session } = await client.sessions.create({The `manifest` you save (or the inline `spec`) is the agent spec below — every field, with defaults.-```json A complete example+```json{"model": {"name": "anthropic/claude-sonnet-4-6",