Use your coding agent
Section titled “Use your coding agent”Choose an icon to open a prefilled prompt. Select your project, review, and send.
View prompt
Read https://submilli.ai/docs/tutorials/use-the-http-api/ as the source for this setup.
Inspect my project and follow this guide to create agent.ts and submilli.ts. Reuse valid local Submilli connection settings and provider credentials. If SUBMILLI_SERVER, SUBMILLI_SERVER_TOKEN, or SUBMILLI_BLUEPRINT is missing, ask for that value or its local configuration source. Do not invent values, expose secrets, create a Blueprint, or change the server. Ask for missing provider credentials without printing them. Install only the missing dependencies shown in this guide. Preserve its tool restrictions and session cleanup. Run the file with --check to verify the connection without a model request. Leave the files ready for the exact Try it out command.
After setup, try it out.
Set up manually
Section titled “Set up manually”The files read this terminal’s environment; they do not automatically load
.env files. Use your running server’s base URL and registered Blueprint.
Replace these values before running the files:
export SUBMILLI_SERVER='your-server-base-url'export SUBMILLI_SERVER_TOKEN='your-server-token'export SUBMILLI_BLUEPRINT='your-registered-blueprint'export OPENAI_API_KEY='your-openai-api-key'Use the HTTP API when a harness has no MCP client or when your application needs to build and name the model’s tools itself. This guide uses the Vercel AI SDK. The application fetches Submilli’s tool descriptions, opens a session, and closes it after the conversation.
Before you start:
- Run
submilli-serverand keepSUBMILLI_SERVER_TOKENexported. - Register a Blueprint, then set
SUBMILLI_BLUEPRINTto its registered name. The calculation below assumes the Blueprint has no required variables. The sample calls no external tools. - Install Node.js 22 or later and set the API key for your model provider.
Start the project
Section titled “Start the project”mkdir vercel-ai-submilli && cd vercel-ai-submillinpm init -ynpm pkg set type=modulenpm install ai @ai-sdk/openai zodnpm install --save-dev tsx typescript @types/nodeConnect the agent
Section titled “Connect the agent”Create agent.ts in the project directory and paste the code below:
import { openai } from "@ai-sdk/openai";import { generateText, stepCountIs } from "ai";import { openSession } from "./submilli.ts";
const args = process.argv.slice(2);const checking = args.length === 1 && args[0] === "--check";const prompt = args.join(" ");if (!checking && !prompt.trim()) { throw new Error("Usage: npx tsx agent.ts '<message>' (or --check)");}
const submilli = await openSession({ server: process.env.SUBMILLI_SERVER ?? "http://127.0.0.1:8128", token: required("SUBMILLI_SERVER_TOKEN"), blueprint: required("SUBMILLI_BLUEPRINT"),});
try { if (checking) { console.log("Connected to Submilli."); } else { const result = await generateText({ // Change this model ID to use another OpenAI model. model: openai("gpt-5-mini"), system: "Use Submilli to do calculations in TypeScript. Return the execution result.", tools: submilli.tools, prompt, stopWhen: stepCountIs(10), onStepFinish({ toolCalls, toolResults }) { if (toolCalls.length > 0) console.dir({ toolCalls, toolResults }, { depth: null }); }, }); console.log(result.text); }} finally { await submilli.close();}
function required(name: string): string { const value = process.env[name]; if (!value) throw new Error(`${name} is not set`); return value;}stopWhen lets the SDK continue after a tool result. The default stops after
one step, before the model can use that result. onStepFinish prints the tool
calls and results so you can verify execution separately from the final answer.
Build the tools
Section titled “Build the tools”Create submilli.ts beside agent.ts and paste the code below:
import { tool, type ToolSet } from "ai";import { z } from "zod";
export interface SessionOptions { server: string; token: string; /** Name of a Blueprint already registered on this server. */ blueprint: string; /** Trusted application values required by the Blueprint. */ variables?: Record<string, string>; /** Harness-supplied secrets required by the Blueprint. */ secrets?: Record<string, string>;}
export interface Session { tools: ToolSet; close(): Promise<void>;}
interface Prompt { prompt: string; tools: { search: string; docs: string; builtins_list: string; builtins_docs: string; last_run: string; };}
export async function openSession(options: SessionOptions): Promise<Session> { const call = (url: string, method = "GET", body?: unknown): Promise<Response> => fetch(url, { method, headers: { Authorization: `Bearer ${options.token}`, ...(body === undefined ? {} : { "content-type": "application/json" }), }, body: body === undefined ? undefined : JSON.stringify(body), });
const blueprint = `${options.server}/v1/blueprints/${encodeURIComponent(options.blueprint)}`; const describe: Prompt = await json(await call(`${blueprint}/prompt`));
const { session_id } = await json( await call(`${options.server}/v1/sessions`, "POST", { blueprint: options.blueprint, variables: options.variables ?? {}, secrets: options.secrets ?? {}, }), ); const session = `${options.server}/v1/sessions/${session_id}`;
return { tools: { submilli__typescript__execute: tool({ description: describe.prompt, inputSchema: z.object({ code: z.string() }), execute: async ({ code }) => { const run = await json(await call(`${session}/execute`, "POST", { code })); return { result: run.result, console: run.console, error: run.error }; }, }), submilli__typescript__last_run: tool({ description: describe.tools.last_run, inputSchema: z.object({}), execute: async () => json(await call(`${session}/last-run`)), }), submilli__typescript__packages__search: tool({ description: describe.tools.search, inputSchema: z.object({ query: z.string().default("") }), execute: async ({ query }) => json(await call(`${blueprint}/packages/search?${new URLSearchParams({ q: query })}`)), }), submilli__typescript__packages__docs: tool({ description: describe.tools.docs, inputSchema: z.object({ name: z.string() }), execute: async ({ name }) => { const response = await call( `${blueprint}/packages/docs?${new URLSearchParams({ name })}`, ); if (!response.ok) throw new Error(await response.text()); return response.text(); }, }), submilli__typescript__builtins__list: tool({ description: describe.tools.builtins_list, inputSchema: z.object({}), execute: async () => json(await call(`${blueprint}/builtins`)), }), submilli__typescript__builtins__docs: tool({ description: describe.tools.builtins_docs, inputSchema: z.object({ names: z.array(z.string()) }), execute: async ({ names }) => { const query = new URLSearchParams(names.map((name) => ["name", name])); return json(await call(`${blueprint}/builtins/docs?${query}`)); }, }), }, close: async () => { const response = await call(session, "DELETE"); if (!response.ok) throw new Error(`could not close session: HTTP ${response.status}`); }, };}
async function json(response: Response): Promise<any> { const body = await response.json(); if (!response.ok) { throw new Error( `submilli-server answered ${response.status}: ${body.message ?? body.error}`, ); } return body;}The execute tool accepts only code. The application fixes the Blueprint,
variables, and secrets when it opens the session, outside the model’s control.
Fetch the execute description from the server: it describes the supported
TypeScript, Packages, built-ins, and selected Blueprint. The finally block
closes the session even when generation fails.
This wrapper passes only the six submilli__typescript__* tools it builds to
generateText; it does not declare an application-tool catalog in the tools
field of POST /v1/sessions, and it does not handle suspended responses or
POST /v1/runs/{run_id}/resume. Direct Vercel AI SDK tools can still be added
when the application needs them, but those calls bypass Submilli and execute
through the harness’s own path. For a governed migration,
declare the application tools in POST /v1/sessions, grant tools.call in the
Blueprint, execute the callback in the harness, and resume the run with
POST /v1/runs/{run_id}/resume. See the application tools section
for the suspended-run and result contract.
If your Blueprint has required variables or harness secrets, pass them in
openSession({ variables, secrets }) from trusted application state. The
HTTP API reference defines
validation, rebinding after a restart, failures, and the complete session
contract.
Check the connection
Section titled “Check the connection”With the setup environment active, run this without a model request:
npx tsx agent.ts --checkLook for Connected to Submilli.. This checks the server and registered
Blueprint; the model runs only when you supply a message.
Try it out
Section titled “Try it out”npx tsx agent.ts \ 'Run this program through Submilli and report its result:export function main(): number { return 2 + 2; }'In the printed step data, confirm a call to
submilli__typescript__execute and a tool result containing 4. The
final assistant text alone does not verify where the calculation ran. This
sample uses the model provider for the Vercel AI SDK conversation. The
TypeScript program itself only computes a value and calls no Package,
application tool, or external service.
See the HTTP API reference for endpoint schemas, execute results, idempotency, errors, and application-tool callbacks. See How Submilli works with harnesses for the boundary between the harness, Submilli, and the selected Blueprint.