> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stewrd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# SDKs

> Official SDKs for the Stewrd API.

## TypeScript / Node.js

Install the official TypeScript SDK:

```bash theme={null}
npm install @stewrd/sdk
```

### Quick Start

```typescript theme={null}
import { Stewrd } from '@stewrd/sdk'

const stewrd = new Stewrd('sk-stw_your_key')

const result = await stewrd.agent.run({
  message: 'Research the top 5 CRM tools and create a comparison spreadsheet',
  capabilities: ['research', 'documents'],
})

console.log(result.message)
console.log(result.files[0].url)
```

### Streaming

```typescript theme={null}
const stream = await stewrd.agent.stream({
  message: 'Write a detailed analysis',
})

for await (const event of stream) {
  if (event.type === 'token') process.stdout.write(event.content)
  if (event.type === 'tool_start') console.log(`Using ${event.tool}...`)
  if (event.type === 'done') console.log('\n\nTokens:', event.usage.tokens_used)
}
```

### Custom Tools (Function Calling)

Use `runWithTools` to let the agent call your functions — the SDK handles the loop automatically:

```typescript theme={null}
const result = await stewrd.agent.runWithTools(
  {
    message: 'Check order #12345 and email the customer a summary',
    tools: [
      {
        name: 'get_order',
        description: 'Look up an order by ID',
        parameters: {
          type: 'object',
          properties: { order_id: { type: 'string' } },
          required: ['order_id'],
        },
      },
      {
        name: 'send_email',
        description: 'Send an email to a customer',
        parameters: {
          type: 'object',
          properties: {
            to: { type: 'string' },
            subject: { type: 'string' },
            body: { type: 'string' },
          },
          required: ['to', 'subject', 'body'],
        },
      },
    ],
  },
  async (toolCall) => {
    // Execute the tool in your system and return the result as a string
    if (toolCall.name === 'get_order') {
      const order = await db.orders.findById(toolCall.arguments.order_id as string)
      return JSON.stringify(order)
    }
    if (toolCall.name === 'send_email') {
      await emailService.send(toolCall.arguments)
      return JSON.stringify({ sent: true })
    }
    return JSON.stringify({ error: 'Unknown tool' })
  }
)

console.log(result.message)
```

For more control, use `submitToolOutputs` directly to handle the loop yourself. See the [Custom Tools guide](/tools) for details.

### Error Handling

```typescript theme={null}
import { Stewrd, StewrdError } from '@stewrd/sdk'

try {
  await stewrd.agent.run({ message: '...' })
} catch (err) {
  if (err instanceof StewrdError) {
    console.log(err.status)  // 401
    console.log(err.code)    // 'invalid_api_key'
    console.log(err.message) // 'Invalid API key'
  }
}
```

<Card title="View on GitHub" icon="github" href="https://github.com/dodenbach/stewrd-sdk">
  Source code, issues, and full API reference.
</Card>

<Card title="View on npm" icon="npm" href="https://www.npmjs.com/package/@stewrd/sdk">
  @stewrd/sdk on npm
</Card>

## Python

Install the official Python SDK:

```bash theme={null}
pip install stewrd
```

### Quick Start

```python theme={null}
from stewrd import Stewrd

stewrd = Stewrd("sk-stw_your_key")

result = stewrd.agent.run(
    message="Research the top 5 CRM tools and create a comparison spreadsheet",
    capabilities=["research", "documents"],
)

print(result.message)
print(result.files[0].url)
```

### Streaming

```python theme={null}
for event in stewrd.agent.stream(message="Write a detailed analysis"):
    if event.type == "token":
        print(event.content, end="")
    if event.type == "tool_start":
        print(f"Using {event.tool}...")
    if event.type == "done":
        print(f"\n\nTokens: {event.usage.tokens_used}")
```

### Error Handling

```python theme={null}
from stewrd import Stewrd, StewrdError

try:
    stewrd.agent.run(message="...")
except StewrdError as e:
    print(e.status)   # 401
    print(e.code)     # "invalid_api_key"
    print(e.message)  # "Invalid API key"
```

<Card title="View on GitHub" icon="github" href="https://github.com/dodenbach/stewrd-python">
  Source code, issues, and full API reference.
</Card>

<Card title="View on PyPI" icon="python" href="https://pypi.org/project/stewrd/">
  stewrd on PyPI
</Card>

## Available SDKs

| Language             | Package                                                    | Status    |
| :------------------- | :--------------------------------------------------------- | :-------- |
| TypeScript / Node.js | [`@stewrd/sdk`](https://www.npmjs.com/package/@stewrd/sdk) | Available |
| Python               | [`stewrd`](https://pypi.org/project/stewrd/)               | Available |

## Using Fetch Directly

The Stewrd API is a single REST endpoint, so it's straightforward to use with `fetch` in any language:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const response = await fetch('https://api.stewrd.dev/v1/agent', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.STEWRD_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      message: 'Your task here',
    }),
  })

  const data = await response.json()
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.stewrd.dev/v1/agent',
      headers={
          'Authorization': f'Bearer {STEWRD_API_KEY}',
          'Content-Type': 'application/json',
      },
      json={
          'message': 'Your task here',
      },
  )

  data = response.json()
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.stewrd.dev/v1/agent \
    -H "Authorization: Bearer sk-stw_your_key" \
    -H "Content-Type: application/json" \
    -d '{"message": "Your task here"}'
  ```
</CodeGroup>