@meistrari/tela-sdk-js 2.12.0 → 2.13.0

package/README.md

@@ -19,6 +19,7 @@ The Tela SDK for JavaScript provides a simple and powerful way to interact with
   - [File Handling](#file-handling)
   - [Tasks API](#tasks-api)
   - [Vault API](#vault-api)
+  - [Agents API](#agents-api)
 - [Migration Guide from v1.x to v2](#migration-guide-from-v1x-to-v2)
   - [Breaking Changes](#breaking-changes)
   - [Migration Checklist](#migration-checklist)
@@ -715,6 +716,97 @@ const stream = await tela.vault.stream('vault://abc-123')
 
 This is particularly useful when reading task input files: `tela.tasks.getInputFiles(id)` returns the file references, and `tela.vault.download(file.url)` downloads them in one call.
 
+### Agents API
+
+The Agents API runs **agents** — an agent is a configured project (with its own instructions and skills) that executes a prompt asynchronously, streaming its steps until it produces a result. Agents run through the standard Tela API, so no extra configuration is needed: authentication and the vault are shared. Agents are identified by their **agentId**.
+
+```typescript
+const tela = new TelaSDK({ apiKey: 'your-api-key' })
+
+// Discover agents, then get a handle by id (mirrors `tela.canvas.get`)
+const agents = await tela.agents.list()
+const agent = await tela.agents.get(agents[0].id)
+
+// Run the published agent and await the final result
+const result = await agent.execute({
+    prompt: 'Summarize the latest tickets',
+}).result
+
+console.log(result.content)
+```
+
+`execute()` runs the **published** version by default (pass `{ draft: true }` to run the current draft). It returns a promise-like handle — consume **either** `.result` **or** `.stream` (they share one underlying stream). Stream the session's events as they happen:
+
+```typescript
+for await (const event of agent.execute({ prompt: 'Investigate the failing build' }).stream) {
+    switch (event.kind) {
+        case 'status':
+            console.log('status:', event.status)
+            break
+        case 'steps':
+            console.log('steps:', event.steps)
+            break
+        case 'result':
+            console.log('result:', event.result)
+            break
+        case 'error':
+            throw new Error(event.error)
+    }
+}
+```
+
+Or subscribe to lifecycle events and read state:
+
+```typescript
+const execution = await agent.execute({ prompt: 'Refactor the auth module' })
+execution.on('status', status => console.log(status))
+execution.on('step', steps => console.log(steps))
+execution.on('result', result => console.log(result))
+execution.on('error', err => console.error(err))
+
+await execution.result
+console.log(execution.sessionId, execution.status)
+```
+
+**Inputs & attachments** — provide values for the agent's declared inputs (keyed by name) plus ad-hoc file attachments:
+
+```typescript
+await agent.execute({
+    prompt: 'Review this contract',
+    inputs: {
+        document: tela.createFile(buffer, { name: 'contract.pdf', mimeType: 'application/pdf' }),
+        focus: 'liability clauses',
+    },
+    attachments: [{ vaultRef: 'vault://...', filename: 'reference.txt' }],
+}).result
+```
+
+**Multi-turn** — continue the same session with another instruction:
+
+```typescript
+const execution = await agent.execute({ prompt: 'Draft a migration plan' })
+await execution.result
+await execution.continue({ prompt: 'Now implement step 1' }).result
+```
+
+**Cancel / recover** an in-flight or failed run:
+
+```typescript
+await execution.cancel() // aborts the stream and cancels server-side
+await execution.recover() // resume a failed/terminal session
+```
+
+**Resume / inspect** a session by id — useful for resumable workflows, dashboards, and background jobs:
+
+```typescript
+const execution = await tela.agents.getSession('session-uuid') // resumable: .stream / .result / .cancel / .recover
+const timeline = await tela.agents.getTimeline('session-uuid') // duration + token/cost metrics
+await tela.agents.cancel('session-uuid')
+await tela.agents.endSession('session-uuid')
+```
+
+`TelaFile` inputs and attachments are uploaded to the vault automatically. `execute()` defaults the prompt to `"Execute"` for input-driven agents, and `.result` resolves on `completed` **or** `waiting_messages` (check `.status` and `.continue()` from a paused turn).
+
 ## Migration Guide from v1.x to v2
 
 Version 2.0 of the Tela SDK introduces significant improvements to type safety, schema validation, and API design. This guide will help you migrate your code from v1.x to v2.