Copyright (c) 2024 Continual, Inc. All rights reserved.

# Continual SDK

This package contains the Continual SDK.

## Usage

To use the SDK, install it using your preferred package manager:

```bash
pnpm install @continual/sdk
```

To run the SDK, use the `continual` command:

```bash
npx continual --help
```

To create a custom agent, create a file like `continual-agents.ts`:

```typescript
#!/usr/bin/env tsx
import { createContinualOpenAiModel, createTool, webserver } from "@continual/sdk";
import { z } from "zod";

// Optional: Define custom tools
const customTool = createTool({
  name: "exampleTool",
  description: "An example tool that does something useful",
  input: z.object({
    param1: z.string().describe("First parameter"),
    param2: z.number().describe("Second parameter"),
  }),
  output: z.string(),
  run: async function* ({ input }) {
    // Tool implementation
    return `Processed ${input.param1} and ${input.param2}`;
  },
});

// Set up the webserver with agents
webserver({
  agents: {
    myAgent: {
      model: createContinualOpenAiModel({ model: "gpt-4o" }),
      instructions: "You are a helpful assistant that provides clear and accurate information.",
      tools: {
        customTool,
        // You can add more tools here
      },
      chatGreetingMessage: "Hello! How can I help you today?",
    },
  },
});
```

Create a file that will register an MCP app in `continual-apps.ts`:

```typescript
#!/usr/bin/env tsx
import { gmailApp, hubspotApp, notionApp, slackApp } from "/path/to/apps";
import { appserver, createContinualSDKClient } from "@continual/sdk";

appserver({
  apps: {
    gmail: {
      name: "Gmail",
      description: "A set of tools for interacting with Gmail. Requires OAuth2 authentication.",
      app: gmailApp,
    },
    hubspot: {
      name: "Hubspot",
      description: "A set of tools for interacting with Hubspot. Requires OAuth2 authentication.",
      app: hubspotApp,
    },
    notion: {
      name: "Notion",
      description: "A set of tools for interacting with Notion. Requires OAuth2 authentication.",
      app: notionApp,
    },
    slack: {
      name: "Slack",
      description: "A set of tools for interacting with Slack. Requires OAuth2 authentication.",
      app: slackApp,
    },
  },
  client: createContinualSDKClient(),
});
```

Before you run this, you need to set up the following environment variables. By default, the SDK
will try to read these from your environment variables file in the `.env` file in your project root.

- `CONTINUAL_API_KEY`: Your Continual API key.
- `CONTINUAL_API_URL`: The URL of the Continual service. By default this is
  `https://console.continual.ai/api`.
- `CONTINUAL_SERVICE_URI`: The URL of this service. This needs to be a URL that the Continual
  service can reach this service at. For deployment to production this needs to be a public URL. For
  development, you can use `ngrok` to create a public URL.
- `CONTINUAL_APP_SERVICE_URI`: MCP apps are not served on the same port as the agents. This can be a
  different port on the same host as the above.

NOTE: by default, when running/deploying it will try to execute the following commands in parallel:

```bash
pnpm dlx tsx continual-agents.ts
pnpm dlx tsx continual-apps.ts
```

If you want to use different commands to run your service, you have 2 options:

1. Set the `CONTINUAL_AGENTS_EXECUTION_COMMAND` and `CONTINUAL_APPS_EXECUTION_COMMAND` in your
   `.env` file
2. Specify commands directly with the `-c` flag when deploying:

```bash
npx continual deploy -u -n my-custom-agent -c "pnpm dlx tsx my-custom-script.ts" -c "pnpm dlx tsx another-script.ts"
```

To deploy your service to a managed environment, use:

```bash
npx continual deploy -n my-custom-agent
```

This will package up your local directory (see additional options for the deploy command as well)
and deploy to a managed environment.

If you want to run this locally (or in any other environment), you can use the command:

```bash
npx continual deploy -u -n my-custom-agent
```

This will run the service in "unmanaged mode", executing all commands in parallel. The process will
properly handle interruption signals (Ctrl+C), ensuring all child processes are terminated
gracefully.

Additionally if you want to not deploy the application but just the agent, you can use the command:

```bash
pnpm dlx tsx continual-agents.ts
```
