# Run your first agent

Install the SDK, create a session, and stream a complete execution from your backend.

## Before you begin

Create a Wkala account. Verify your email. Wait for operator approval. The operator assigns your provider, models, and limits. Create a key in [your dashboard](/dashboard/keys). Start with read and run permissions. Add configure permission to register tools, skills, or profiles.

Keep the service key in your backend. Never put it in a browser bundle, a public environment variable, or a copied AI prompt. Browser clients use same-origin `/app`.

## 1. Install the SDK

### Python

Python 3.11 or newer is supported. Install the downloadable release artifact.

```bash
python -m pip install "wkala @ https://wkala.okal.io/downloads/wkala-0.1.0-py3-none-any.whl"
```

For a bare Go service, pass `base_url="http://localhost:8080/v1"` to the client. The Compose ingress uses `http://localhost:8088/v1`; native multi-service development uses `http://localhost:18080/v1`; production uses the configured public origin. Python also accepts an origin-style override for compatibility.


### TypeScript

Use Node 22.13 or newer. Install the downloadable release artifact.

```bash
npm install "https://wkala.okal.io/downloads/wkala-client-0.1.0.tgz"
```

For a bare Go service, pass `baseUrl: "http://localhost:8080/v1"` to the server client. The Compose ingress uses `http://localhost:8088/v1`; native multi-service development uses `http://localhost:18080/v1`; production uses the configured public origin.


## 2. Set the key

Set this variable in your backend environment:

```bash
export WKALA_API_KEY="your-private-service-key"
```

## 3. Create and observe a run

This example creates a session and submits a release checklist task. It observes updates and inspects the final result. Persist the generated request ID before submission when your application must recover after a restart.

### Python

Save this as `first_agent.py`:

```python
import asyncio
import os
import uuid

from wkala import AgentClient, SnapshotUpdate


async def main():
    async with AgentClient(api_key=os.environ["WKALA_API_KEY"]) as agents:
        session = await agents.sessions.create(title="First task")
        request_id = str(uuid.uuid4())
        run = await session.send(
            "Draft a concise release checklist for a web application.",
            idempotency_key=request_id,
        )
        print("Session:", session.id, "Run:", run.id)
        async with run.stream() as stream:
            async for update in stream:
                if isinstance(update, SnapshotUpdate):
                    print("Snapshot restored")
                else:
                    print(update.type, update.model_dump(mode="json", by_alias=True))
        result = await run.result()
        print(result.status, result.stop_reason)
        print(result.messages)


asyncio.run(main())
```

Run it:

```bash
python first_agent.py
```


### TypeScript

Save this JavaScript-compatible example as `first_agent.mjs`:

```typescript
import { createServerClient } from "@wkala/client/server"

const apiKey = process.env.WKALA_API_KEY
if (!apiKey) {
  throw new Error("Set WKALA_API_KEY in your backend environment")
}
const agents = createServerClient({ apiKey })

const session = await agents.sessions.create({ title: "First task" })
const requestId = crypto.randomUUID()
const run = await session.send(
  "Draft a concise release checklist for a web application.",
  { idempotencyKey: requestId },
)
console.log("Session:", session.id, "Run:", run.id)

for await (const event of run.events()) {
  console.log(event.type, event.data)
}

const result = await run.result()
console.log(result.run.status, result.run.stop_reason)
console.log(result.messages)
```

Run it:

```bash
node first_agent.mjs
```


`send()` returns after admission. The service continues executing while your application observes it. The result includes messages, tool calls, backend invocations, interactions, and usage. Failed or cancelled executions remain inspectable. Check the status and stop reason. If the run needs input, observation can remain open until another authorized component responds. Follow [approvals and questions](/docs/raw/interactions?locale=en).

### Python

Release 0.1.0 is supplied as a downloadable wheel. The install command does not assume a registry publication. Find checksums and downloads on the [documentation home](/llms.txt?locale=en).


### TypeScript

Release 0.1.0 is supplied as a downloadable npm archive. The install command does not assume a registry publication. Find checksums and downloads on the [documentation home](/llms.txt?locale=en).


## 4. Choose the next boundary

- [Stream messages and tools](/docs/raw/streaming?locale=en).
- [Connect backend tools](/docs/raw/backend-tools?locale=en).
- [Connect a React interface](/docs/raw/react?locale=en) through your authenticated backend.
- [Understand cost and limits](/docs/raw/usage-and-limits?locale=en) before admitting production work.
