Skip to content
Browse documentation
typescript sdk

Define and run an agent

Create a typed definition, choose an execution runtime, and own the resulting Agent lifetime.

Start with explicit behavior

This deterministic example needs no model credential. It separates the reusable definition from the local execution handler.

import {
  createAgent,
  createEmbeddedAgentRuntime,
  defineAgent,
} from "@smoothie-framework/runtime/agent";

const definition = defineAgent<string, string>({
  id: "echo",
  instructions: "Return the supplied text.",
});
const agent = createAgent(definition, {
  runtime: createEmbeddedAgentRuntime({
    tenantId: "example",
    projectId: "support",
  }),
  handler: async invocation => invocation.input ?? "",
});

await agent.start();
try {
  const result = await (await agent.startRun("Hello")).wait();
  console.log(result);
} finally {
  await agent.stop();
}

Choose model-backed execution when needed

For the standard model loop, declare run: "model" and an explicit model selection, and inject a configured InferenceRuntime into the Agent runtime. Declare the Tool superset in trusted code; a run may narrow it, not add arbitrary Tools.

Generic TypeScript input/output parameters are not external value validation. Add supported input/output contracts when accepting data from HTTP, persistence or another untrusted boundary.

Embedded defaults are in-memory and single-process. Use durable stores and explicit host recovery when a run must survive process loss; starting an Agent is not a production-readiness check.