From OpenAPI Spec to In-App Copilot in 60 Minutes

What you need

Before you start:

An OpenAPI 3.x spec (JSON or YAML) for your backend, or a GraphQL endpoint with introspection enabled
A React (or Next.js) frontend
A backend endpoint that can mint short-lived, user-scoped JWTs for the copilot

That last one matters. Agent Koan executes API calls as the end user, not as a service account. The copilot inherits all your existing permission logic (RBAC, tenant isolation, feature flags) without you writing any new authorization rules.

Step 1: Create a project (5 minutes)

Sign in to the Agent Koan dashboard and create a new project. Give it a name (e.g., "Acme CRM") and paste your OpenAPI spec URL or upload the JSON file.

Agent Koan parses the spec and generates a tool catalog: one tool per endpoint, grouped by tag. Each tool gets a name, description, parameter schema, and a default risk level based on the HTTP method:

Method	Default risk
GET	Low
POST	Medium
PUT	Medium
PATCH	Medium
DELETE	High

You can override any of these in the dashboard.

Step 2: Configure your tools (15 minutes)

This is where you decide what the copilot can and can't do.

Enable endpoints. Everything is disabled by default. Toggle on the ones you want the copilot to access. Start small: maybe 5 read endpoints and 1-2 write endpoints.

Set risk levels. For each tool:

Low: Executes without confirmation (good for read endpoints)
Medium: Shows a confirmation card before executing
High: Shows a confirmation card with full field preview, plus an optional approver

Add constraints. You can add parameter constraints per tool: enum restrictions, max lengths, required fields. For example, you might restrict CreateOpportunity so that stage can only be "Prospecting" or "Qualification".

Edit descriptions. The auto-generated descriptions are usually fine, but you can tweak them. Better descriptions mean better tool selection.

Step 3: Set up auth (15 minutes)

Agent Koan needs a way to get a user-scoped token for each session. The simplest approach:

Create a backend endpoint (e.g., POST /api/agent-koan-token)
This endpoint authenticates the current user (from your session/cookie)
It mints a short-lived JWT with the user's ID, tenant ID, and scopes
Returns it as plain text

// Example: Express.js
app.post('/api/agent-koan-token', requireAuth, (req, res) => {
  const token = jwt.sign(
    { sub: req.user.id, tenant: req.user.tenantId },
    process.env.AGENT_KOAN_SECRET,
    { expiresIn: '15m' }
  );
  res.send(token);
});

Step 4: Embed the widget (10 minutes)

Install the SDK:

npm install @agentkoan/widget

Add the component to your app:

import { AgentKoan } from '@agentkoan/widget'

function App() {
  return (
    <div>
      {/* Your existing app */}
      <AgentKoan
        projectId="proj_abc123"
        getUserToken={() =>
          fetch('/api/agent-koan-token', { method: 'POST' })
            .then(r => r.text())
        }
      />
    </div>
  )
}

That's it. The widget handles the conversation UI, tool selection, confirmation flows, and execution.

Step 5: Test and ship (15 minutes)

Open your app in staging. Click the copilot widget and try a few things:

"Show me all open opportunities" (read action, low risk, executes immediately)
"Create an opportunity for Acme, $50k, close date March 30" (write action, medium risk, shows confirmation card)
"Delete the opportunity for Beta Corp" (high risk, shows full preview before executing)

Check the dashboard logs to see every tool call, its parameters, status code, and latency.

When it looks good, ship to production. You can start in read-only mode and turn on write actions gradually.

What's next

Once the basic integration is working:

Add more endpoints to the allowlist
Tune risk levels and constraints
Watch usage and success rates in the dashboard
Roll out to more users with feature flags

You don't need to build agent infrastructure from scratch. Your API exists. Your auth works. Agent Koan connects the two and adds the guardrails.

Join the waitlist →