npm package: @mantyx/ts-sdk
Description: Vendor-agnostic agent runtime for Mantyx: AgentSpec to OpenAI, Google Gemini, or Anthropic Claude, with an A2A protocol adapter.
Latest version: 0.1.0

# @mantyx/ts-sdk

Vendor-agnostic agent runtime for Mantyx. Converts a well-defined `AgentSpec` to **OpenAI**, **Google (Gemini)**, or **Anthropic (Claude)** format and runs the agent.

## Install

```bash
npm install @mantyx/ts-sdk
```

## Documentation

- **This package (Docusaurus):** [mantyx-ai.github.io/mantyx-ts-sdk](https://mantyx-ai.github.io/mantyx-ts-sdk/) — enable **Settings → Pages → Build and deployment → GitHub Actions** on the repository the first time you deploy.
- **Mantyx platform:** [mantyx.io](https://mantyx.io/) and [platform docs](https://mantyx.io/docs/getting-started) (product, agents, webhooks, orchestration).
- **Develop locally:** from the repo root, run `npm run docs:dev` and open the URL Docusaurus prints (default [http://localhost:3000](http://localhost:3000)). Production build: `npm run docs:build`.

## Usage

```ts
import { runAgent, type AgentSpec, type Message } from "@mantyx/ts-sdk";

const spec: AgentSpec = {
  name: "My Agent",
  systemPrompt: "You are a helpful assistant.",
  model: "gpt-4o-mini",
  provider: "openai",
  providerConfig: {
    apiKey: process.env.OPENAI_API_KEY!,
    baseUrl: undefined,
  },
  tools: [
    {
      name: "get_weather",
      description: "Get the weather for a location",
      execute: async (args) => {
        return JSON.stringify({ temp: 72, condition: "sunny" });
      },
    },
  ],
};

const messages: Message[] = [{ role: "user", content: "What's the weather?" }];
const reply = await runAgent(spec, messages);
```

## Types

- **AgentSpec** – Vendor-agnostic agent definition (name, systemPrompt, model, provider, tools, etc.)
- **ResolvedTool** – Tool with `name`, `description`, and `execute` function
- **Message** – Chat message with `role` and `content`

## Providers

Set `provider` on `AgentSpec` to one of:

- **openai** — Chat Completions / Responses path via `@openai/agents` and the OpenAI SDK
- **google** — Gemini via `@google/adk`
- **anthropic** — Claude via `@anthropic-ai/sdk` (Messages API with tool loop)

`providerConfig` always includes `apiKey`; optional `baseUrl` overrides the vendor default (e.g. OpenAI-compatible proxies).

## A2A Adapter

Expose any agent via the Agent-to-Agent protocol so it can be invoked by A2A clients:

```ts
import { createA2aAdapter, runAgent } from "@mantyx/ts-sdk";

const adapter = createA2aAdapter({
  agentCard: {
    name: "My Agent",
    url: "https://example.com/api/a2a/agents/my-agent",
    description: "A helpful assistant",
  },
  runner: {
    run: (messages) => runAgent(spec, messages),
  },
});

// Handle HTTP request (framework-agnostic)
const response = await adapter.handleRequest({
  method: req.method,
  url: req.url,
  headers: req.headers,
  body: JSON.stringify(req.body),
});
```

Supports:

- **GET** `/.well-known/agent-card.json` — Agent Card for discovery
- **POST** with JSON-RPC `message/send` or REST `message:send` — Send message and get reply

## Development

```bash
pnpm install
pnpm run build
pnpm test
```

## Publishing (`@mantyx` on npm)

This package is scoped as **`@mantyx/ts-sdk`**. Publishing requires membership in the [npm `@mantyx` organization](https://www.npmjs.com/org/mantyx) and an automation or publish token.

1. **From this monorepo:** `pnpm --filter @mantyx/ts-sdk publish --access public` (after bumping `version` in `ts-sdk/package.json`).
2. **From a dedicated public repo:** copy the contents of this directory to the repository root (including `.github/`), run `pnpm install`, commit `pnpm-lock.yaml`, set `repository` / `bugs` / `homepage` in `package.json` if needed, then tag (e.g. `v0.2.0`) and push. Configure the **`NPM_TOKEN`** secret for GitHub Actions; the `publish` workflow publishes on `v*` tags.

## License

MIT — see [LICENSE](./LICENSE).