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

# Hono

> Build lightweight agent APIs with Hono and the Polpo SDK.

[Hono](https://hono.dev) is an ultrafast web framework that runs on Cloudflare Workers, Bun, Deno, and Node.js. Polpo's own API is built with Hono — it's a natural fit for building agent-powered backends.

## Install

```bash theme={null}
npm install hono @polpo-ai/sdk
```

## Chat proxy endpoint

Create an OpenAI-compatible proxy that injects your API key server-side:

```typescript theme={null}
import { Hono } from "hono";
import { stream } from "hono/streaming";
import { PolpoClient } from "@polpo-ai/sdk";

const app = new Hono();

const client = new PolpoClient({
  baseUrl: "https://{project}.polpo.cloud",
  apiKey: process.env.POLPO_API_KEY!,
});

app.post("/api/chat", async (c) => {
  const { messages, agent } = await c.req.json();

  const completion = client.chatCompletionsStream({ agent, messages });

  return stream(c, async (s) => {
    for await (const chunk of completion) {
      await s.write(`data: ${JSON.stringify(chunk)}\n\n`);
    }
    await s.write("data: [DONE]\n\n");
  }, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache",
    },
  });
});

export default app;
```

## Webhook receiver

Handle Polpo webhook events in a Hono route:

```typescript theme={null}
app.post("/webhooks/polpo", async (c) => {
  const event = await c.req.json();

  switch (event.event) {
    case "task:transition":
      console.log(`Task ${event.data.taskId} → ${event.data.to}`);
      break;
    case "completion:finished":
      console.log(`Completion finished: ${event.data.taskId}`);
      // Trigger downstream workflow
      break;
  }

  return c.json({ ok: true });
});
```

## Task management API

Wrap Polpo operations behind your own authenticated endpoints:

```typescript theme={null}
import { bearerAuth } from "hono/bearer-auth";

app.use("/api/*", bearerAuth({ token: process.env.APP_SECRET! }));

app.post("/api/tasks", async (c) => {
  const { title, description, agent, group } = await c.req.json();

  const task = await client.createTask({
    title,
    description,
    assignTo: agent,
    group,
  });

  return c.json(task);
});

app.get("/api/tasks", async (c) => {
  const tasks = await client.getTasks({
    status: c.req.query("status"),
  });
  return c.json(tasks);
});

app.get("/api/agents", async (c) => {
  const agents = await client.getAgents();
  return c.json(agents);
});
```

## Deploy

Hono runs everywhere:

```bash theme={null}
# Cloudflare Workers
npx wrangler deploy

# Bun
bun run index.ts

# Node.js
npx tsx index.ts
```

<Tip>
  Since Polpo itself runs on Hono + Cloudflare Workers, the SDK is heavily tested in this environment.
</Tip>