openAgent

1import { Config, Effect, Formatter, Layer, Schema, Stream } from "effect"
2import { LLM, LLMClient, Message, ProviderID, Tool, ToolRuntime } from "@opencode-ai/llm"
3import { Route, Auth, Endpoint, Framing, Protocol, RequestExecutor, WebSocketExecutor } from "@opencode-ai/llm/route"
4import { OpenAI } from "@opencode-ai/llm/providers"
5 
6/**
7 * A runnable walkthrough of the LLM package use-site API.
8 *
9 * Run from `packages/llm` with an OpenAI key in the environment:
10 *
11 *   OPENAI_API_KEY=... bun example/tutorial.ts
12 *
13 * The file is intentionally written as a normal TypeScript program. You can
14 * hover imports and local values to see how the public API is typed.
15 */
16 
17const apiKey = Config.redacted("OPENAI_API_KEY")
18 
19// 1. Pick a model. The provider helper records provider identity, protocol
20// choice, capabilities, deployment options, authentication, and defaults.
21const model = OpenAI.configure({
22  apiKey,
23  generation: { maxTokens: 160 },
24  providerOptions: {
25    openai: { store: false },
26  },
27}).model("gpt-4o-mini")
28 
29// 2. Build a provider-neutral request. This is useful when reusing one request
30// across generate and stream examples.
31//
32// Options can live on both the configured route/provider facade and the request:
33//
34//   - `generation`: common controls such as max tokens, temperature, topP/topK,
35//     penalties, seed, and stop sequences.
36//   - `providerOptions`: namespaced provider-native behavior. For example,
37//     OpenAI cache keys and store behavior, Anthropic thinking, Gemini thinking
38//     config, or OpenRouter routing/reasoning.
39//   - `http`: last-resort serializable overlays for final request body, headers,
40//     and query params. Prefer typed `providerOptions` when a field is stable.
41//
42// Route/provider options are defaults. Request options override them for this call.
43const request = LLM.request({
44  model,
45  system: "You are concise and practical.",
46  prompt: "Tell me a joke",
47  generation: { maxTokens: 80, temperature: 0.7 },
48  providerOptions: {
49    openai: { promptCacheKey: "tutorial-joke" },
50  },
51})
52 
53// `http` is intentionally not needed for normal calls. This shows the shape for
54// newly released provider fields before they deserve a typed provider option.
55const rawOverlayExample = LLM.request({
56  model,
57  prompt: "Show the final HTTP overlay shape.",
58  http: {
59    body: { metadata: { example: "tutorial" } },
60    headers: { "x-opencode-tutorial": "1" },
61    query: { debug: "1" },
62  },
63})
64 
65// 3. `generate` sends the request and collects the event stream into one
66// response object. `response.text` is the collected text output.
67const generateOnce = Effect.gen(function* () {
68  const response = yield* LLM.generate(request)
69 
70  console.log("\n== generate ==")
71  console.log("generated text:", response.text)
72  console.log("usage", Formatter.formatJson(response.usage, { space: 2 }))
73})
74 
75// 4. `stream` exposes provider output as common `LLMEvent`s for UIs that want
76// incremental text, reasoning, tool input, usage, or finish events.
77const streamText = LLM.stream(request).pipe(
78  Stream.tap((event) =>
79    Effect.sync(() => {
80      if (event.type === "text-delta") process.stdout.write(`\ntext: ${event.text}`)
81      if (event.type === "finish") process.stdout.write(`\nfinish: ${event.reason}\n`)
82    }),
83  ),
84  Stream.runDrain,
85)
86 
87// 5. Tools are typed with Effect Schema. Provider turns remain explicit:
88// advertise definitions on the request, stream one turn, dispatch local calls,
89// then persist/build follow-up history in the enclosing product flow.
90const tools = {
91  get_weather: Tool.make({
92    description: "Get current weather for a city.",
93    parameters: Schema.Struct({ city: Schema.String }),
94    success: Schema.Struct({ forecast: Schema.String }),
95    execute: (input) => Effect.succeed({ forecast: `${input.city}: sunny, 72F` }),
96  }),
97}
98 
99const streamWithTools = Effect.gen(function* () {
100  const request = LLM.request({
101    model,
102    prompt: "Use get_weather for San Francisco, then answer in one sentence.",
103    generation: { maxTokens: 80, temperature: 0 },
104    tools: Tool.toDefinitions(tools),
105  })
106  const events = Array.from(yield* LLM.stream(request).pipe(Stream.runCollect))
107  for (const event of events) {
108    if (event.type === "tool-call") console.log("tool call", event.name, event.input)
109    if (event.type === "text-delta") process.stdout.write(event.text)
110    if (event.type !== "tool-call" || event.providerExecuted) continue
111    const dispatched = yield* ToolRuntime.dispatch(tools, event)
112    console.log("tool result", event.name, dispatched.result)
113 
114    // A durable agent would persist these messages before starting another
115    // raw model turn. This tutorial keeps the boundary visible instead.
116    const followUp = LLM.updateRequest(request, {
117      messages: [
118        ...request.messages,
119        Message.assistant([event]),
120        Message.tool({ ...event, result: dispatched.result }),
121      ],
122    })
123    console.log("follow-up history messages:", followUp.messages.length)
124  }
125})
126 
127// 6. `generateObject` is the structured-output helper. It forces a synthetic
128// tool call internally, so the same call site works across providers instead of
129// depending on provider-specific JSON mode flags.
130const WeatherReport = Schema.Struct({
131  city: Schema.String,
132  forecast: Schema.String,
133  highFahrenheit: Schema.Number,
134})
135 
136const generateStructuredObject = Effect.gen(function* () {
137  const response = yield* LLM.generateObject({
138    model,
139    system: "Return only structured weather data.",
140    prompt: "Give me today's weather for San Francisco.",
141    schema: WeatherReport,
142    generation: { maxTokens: 120, temperature: 0 },
143  })
144 
145  console.log("\n== generateObject ==")
146  console.log(Formatter.formatJson(response.object, { space: 2 }))
147})
148 
149// If the shape is only known at runtime, pass raw JSON Schema instead. The
150// `.object` type is `unknown`; callers that need static types should validate it.
151const generateDynamicObject = LLM.generateObject({
152  model,
153  prompt: "Extract the city and forecast from: San Francisco is sunny.",
154  jsonSchema: {
155    type: "object",
156    properties: {
157      city: { type: "string" },
158      forecast: { type: "string" },
159    },
160    required: ["city", "forecast"],
161  },
162})
163 
164// -----------------------------------------------------------------------------
165// Part 2: provider composition with a fake provider
166// -----------------------------------------------------------------------------
167 
168// A protocol is the provider-native API shape: common request -> body, response
169// frames -> common events. This fake one turns text prompts into a JSON body
170// and treats every SSE frame as output text.
171const FakeBody = Schema.Struct({
172  model: Schema.String,
173  input: Schema.String,
174})
175type FakeBody = Schema.Schema.Type<typeof FakeBody>
176 
177const FakeProtocol = Protocol.make<FakeBody, string, string, void>({
178  // Protocol ids are open strings, so external packages can define their own
179  // protocols without changing this package.
180  id: "fake-echo",
181  body: {
182    schema: FakeBody,
183    from: (request) =>
184      Effect.succeed({
185        model: request.model.id,
186        input: request.messages
187          .flatMap((message) => message.content)
188          .filter((part) => part.type === "text")
189          .map((part) => part.text)
190          .join("\n"),
191      }),
192  },
193  stream: {
194    event: Schema.String,
195    initial: () => undefined,
196    step: (_, frame) => Effect.succeed([undefined, [{ type: "text-delta", id: "text-0", text: frame }]] as const),
197    onHalt: () => [{ type: "finish", reason: "stop" }],
198  },
199})
200 
201// An route is the runnable binding for that protocol. It adds the deployment
202// axes that the protocol deliberately does not know: URL, auth, and framing.
203const FakeAdapter = Route.make({
204  id: "fake-echo",
205  provider: "fake-echo",
206  protocol: FakeProtocol,
207  endpoint: Endpoint.path("/v1/echo", { baseURL: "https://fake.local" }),
208  auth: Auth.passthrough,
209  framing: Framing.sse,
210})
211 
212// A provider module exports a configured facade. Configuration happens before
213// model selection; model selectors accept ids only.
214const FakeEcho = {
215  id: ProviderID.make("fake-echo"),
216  configure: () => ({
217    id: ProviderID.make("fake-echo"),
218    model: (id: string) => FakeAdapter.model({ id }),
219  }),
220}
221 
222// `LLMClient.prepare` is the lower-level inspection hook: it compiles through
223// body conversion, validation, endpoint, auth, and HTTP construction without
224// sending anything over the network.
225const inspectFakeProvider = Effect.gen(function* () {
226  const prepared = yield* LLMClient.prepare(
227    LLM.request({
228      model: FakeEcho.configure().model("tiny-echo"),
229      prompt: "Show me the provider pipeline.",
230    }),
231  )
232 
233  console.log("\n== fake provider prepare ==")
234  console.log("route:", prepared.route)
235  console.log("body:", Formatter.formatJson(prepared.body, { space: 2 }))
236})
237 
238// Provide the LLM runtime and the HTTP request executor once. Keep one path
239// enabled at a time so the tutorial can demonstrate generate, prepare, stream,
240// or tool-loop behavior without spending tokens on every example.
241const requestExecutorLayer = RequestExecutor.fetchLayer
242const llmDeps = Layer.mergeAll(requestExecutorLayer, WebSocketExecutor.layer)
243const llmClientLayer = LLMClient.layer.pipe(Layer.provide(llmDeps))
244 
245const program = Effect.gen(function* () {
246  // yield* generateOnce
247  // yield* inspectFakeProvider
248  // yield* LLMClient.prepare(rawOverlayExample).pipe(Effect.andThen((prepared) => Effect.sync(() => console.log(prepared.body))))
249  // yield* streamText
250  // yield* generateStructuredObject
251  // yield* generateDynamicObject.pipe(Effect.andThen((response) => Effect.sync(() => console.log(response.object))))
252  yield* streamWithTools
253}).pipe(Effect.provide(Layer.mergeAll(llmDeps, llmClientLayer)))
254 
255Effect.runPromise(program)
256