update sdk readme

Author: charleslien

sdk/README.md

@@ -28,7 +28,7 @@ async function main() {
   })
 
   // First run
-  const run1 = await client.run({
+  const runOrError1 = await client.run({
     // The agent id. Any agent on the store (https://codebuff.com/store)
     agent: 'codebuff/[email protected]',
     prompt: 'Create a simple calculator class',
@@ -37,16 +37,23 @@ async function main() {
       console.log('Codebuff Event', JSON.stringify(event))
     },
   })
+  if (!runOrError1.success) {
+    throw new Error('Run failed' + runOrError1.error.message)
+  }
+  const run1 = runOrError1.value
 
   // Continue the same session with a follow-up
-  const run2 = await client.run({
+  const runOrError2 = await client.run({
     agent: 'codebuff/[email protected]',
     prompt: 'Add unit tests for the calculator',
     previousRun: run1, // <-- this is where your next run differs from the previous run
     handleEvent: (event) => {
       console.log('Codebuff Event', JSON.stringify(event))
     },
   })
+  if (!runOrError2.success) {
+    throw new Error('Run failed: ' + runOrError2.error.message)
+  }
 }
 
 main()
@@ -77,7 +84,7 @@ async function main() {
     id: 'my-custom-agent',
     model: 'x-ai/grok-4-fast',
     displayName: 'Sentiment analyzer',
-    toolNames: ['fetch_api_data'] // Defined below!
+    toolNames: ['fetch_api_data'], // Defined below!
     instructionsPrompt: `
 1. Describe the different sentiments in the given prompt.
 2. Score the prompt along the following 5 dimensions:
@@ -109,7 +116,7 @@ async function main() {
     },
   })
 
-  const { output } = await client.run({
+  const runOrError = await client.run({
     // Run a custom agent by id. Must match an id in the agentDefinitions field below.
     agent: 'my-custom-agent',
     prompt: "Today I'm feeling very happy!",
@@ -123,6 +130,10 @@ async function main() {
       console.log('Codebuff Event', JSON.stringify(event))
     },
   })
+  if (!runOrError.success) {
+    throw new Error('Run failed: ' + runOrError.error.message)
+  }
+  const { output } = runOrError.value
 
   if (output.type === 'error') {
     console.error(`The run failed:\n${output.message}`)
@@ -164,9 +175,13 @@ Runs a Codebuff agent with the specified options.
 
 #### Returns
 
-Returns a Promise that resolves to a `RunState` object which can be passed into subsequent runs via the `previousRun` parameter to resume the conversation.
+Returns a Promise that resolves to either a "success" or a "failure" object.
+
+- The "success" object contains a `RunState` object which can be passed into subsequent runs via the `previousRun` parameter to resume the conversation.
+- The "failure" object contains an `Error` object with a `name`, `message`, and `stack` properties.
 
 The `RunState` object contains:
+
 - `sessionState`: Internal state to be passed to the next run
 - `output`: The agent's output (text, error, or other types)
 

sdk/examples/readme-example-1.ts

@@ -0,0 +1,40 @@
+import { CodebuffClient } from '@codebuff/sdk'
+
+async function main() {
+  const client = new CodebuffClient({
+    // You need to pass in your own API key here.
+    // Get one here: https://www.codebuff.com/api-keys
+    apiKey: process.env.CODEBUFF_API_KEY,
+    cwd: process.cwd(),
+  })
+
+  // First run
+  const runOrError1 = await client.run({
+    // The agent id. Any agent on the store (https://codebuff.com/store)
+    agent: 'codebuff/[email protected]',
+    prompt: 'Create a simple calculator class',
+    handleEvent: (event) => {
+      // All events that happen during the run: agent start/finish, tool calls/results, text responses, errors.
+      console.log('Codebuff Event', JSON.stringify(event))
+    },
+  })
+  if (!runOrError1.success) {
+    throw new Error('Run failed' + runOrError1.error.message)
+  }
+  const run1 = runOrError1.value
+
+  // Continue the same session with a follow-up
+  const runOrError2 = await client.run({
+    agent: 'codebuff/[email protected]',
+    prompt: 'Add unit tests for the calculator',
+    previousRun: run1, // <-- this is where your next run differs from the previous run
+    handleEvent: (event) => {
+      console.log('Codebuff Event', JSON.stringify(event))
+    },
+  })
+  if (!runOrError2.success) {
+    throw new Error('Run failed: ' + runOrError2.error.message)
+  }
+}
+
+main()

sdk/examples/readme-example-2.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod/v4'
+
+import { CodebuffClient, getCustomToolDefinition } from '@codebuff/sdk'
+
+import type { AgentDefinition } from '@codebuff/sdk'
+
+async function main() {
+  const client = new CodebuffClient({
+    // Note: You need to pass in your own API key.
+    // Get it here: https://www.codebuff.com/profile?tab=api-keys
+    apiKey: process.env.CODEBUFF_API_KEY,
+    // Optional directory agent runs from (if applicable).
+    cwd: process.cwd(),
+  })
+
+  // Define your own custom agents!
+  const myCustomAgent: AgentDefinition = {
+    id: 'my-custom-agent',
+    model: 'x-ai/grok-4-fast',
+    displayName: 'Sentiment analyzer',
+    toolNames: ['fetch_api_data'], // Defined below!
+    instructionsPrompt: `
+1. Describe the different sentiments in the given prompt.
+2. Score the prompt along the following 5 dimensions:
+  happiness, sadness, anger, fear, and surprise.`,
+    // ... other AgentDefinition properties
+  }
+
+  // And define your own custom tools!
+  const myCustomTool = getCustomToolDefinition({
+    toolName: 'fetch_api_data',
+    description: 'Fetch data from an API endpoint',
+    inputSchema: z.object({
+      url: z.url(),
+      method: z.enum(['GET', 'POST']).default('GET'),
+      headers: z.record(z.string(), z.string()).optional(),
+    }),
+    exampleInputs: [{ url: 'https://api.example.com/data', method: 'GET' }],
+    execute: async ({ url, method, headers }) => {
+      const response = await fetch(url, { method, headers })
+      const data = await response.text()
+      return [
+        {
+          type: 'json' as const,
+          value: {
+            message: `API Response: ${data.slice(0, 5000)}...`,
+          },
+        },
+      ]
+    },
+  })
+
+  const runOrError = await client.run({
+    // Run a custom agent by id. Must match an id in the agentDefinitions field below.
+    agent: 'my-custom-agent',
+    prompt: "Today I'm feeling very happy!",
+
+    // Provide custom agent and tool definitions:
+    agentDefinitions: [myCustomAgent],
+    customToolDefinitions: [myCustomTool],
+
+    handleEvent: (event) => {
+      // All events that happen during the run: agent start/finish, tool calls/results, text responses, errors.
+      console.log('Codebuff Event', JSON.stringify(event))
+    },
+  })
+  if (!runOrError.success) {
+    throw new Error('Run failed: ' + runOrError.error.message)
+  }
+  const { output } = runOrError.value
+
+  if (output.type === 'error') {
+    console.error(`The run failed:\n${output.message}`)
+  } else {
+    console.log('The run succeeded with output:', output)
+  }
+}
+
+main()