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

# Usage for Agents

> Add OpenRouter Agent SDK skills to your AI coding assistant

Give your AI coding assistant the knowledge to work with the OpenRouter Agent SDK by installing our official `openrouter-typescript-sdk` skill from the [OpenRouterTeam/skills](https://github.com/OpenRouterTeam/skills) repository.

The skill covers both the Agent SDK (`@openrouter/agent`) and the Client SDKs (`@openrouter/sdk`). When working with the Agent SDK, your AI assistant will focus on the **agent features**: `callModel`, `tool()` definitions, stop conditions, streaming, and multi-turn conversations.

## Quick Start

### Claude Code

```bash lines theme={null}
/plugin marketplace add OpenRouterTeam/skills
/plugin install openrouter@openrouter
```

### Cursor

Add via **Settings > Rules > Add Rule > Remote Rule (Github)** with `OpenRouterTeam/skills`.

### GitHub CLI

Requires [GitHub CLI](https://cli.github.com/) v2.90.0+. Works with Claude Code, Cursor, OpenCode, Codex, Gemini CLI, Windsurf, and [many more agents](https://cli.github.com/manual/gh_skill_install):

```bash lines theme={null}
gh skill install OpenRouterTeam/skills openrouter-typescript-sdk
```

## Supported AI Coding Assistants

The skill works with any AI coding assistant that supports the [Agent Skills](https://agentskills.io/home) standard:

| Assistant | Status |
| - | - |
| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | Supported |
| [Cursor](https://cursor.com) | Supported |
| [OpenCode](https://opencode.ai) | Supported |
| [GitHub Copilot](https://github.com/features/copilot) | Supported |
| [Codex](https://openai.com/index/openai-codex) | Supported |
| [Amp](https://ampcode.com) | Supported |
| [Roo Code](https://roo.dev) | Supported |
| [Antigravity](https://antigravity.google/product/antigravity-sdk) | Supported |

## What the Skill Provides

Once installed, your AI coding assistant will have knowledge of:

* **callModel API** - The recommended approach for making AI model calls with full type safety and streaming support
* **Tool Definitions** - Creating tools with the `tool()` helper and Zod schemas
* **Stop Conditions** - Controlling agent loop termination with `stepCountIs`, `maxCost`, and more
* **Streaming** - Real-time token output within agent steps
* **Multi-turn Conversations** - Managing conversation state across turns
* **Dynamic Parameters** - Changing model, temperature, or tools between turns

## Example Usage

After installing the skill, your AI assistant can help you with tasks like the ones below. The skill is `openrouter-typescript-sdk`, so the TypeScript tabs show what the assistant writes. The Python and Go tabs are independent equivalents for readers working in those languages; the skill does not teach them.

**"Help me set up an OpenRouter agent"**

The assistant will know to use:

```typescript lines theme={null}
import { OpenRouter, callModel } from '@openrouter/agent';

const openrouter = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
});

const result = callModel(openrouter, {
  model: '~anthropic/claude-sonnet-latest',
  input: 'Hello!'
});

const text = await result.getText();
console.log(text);

```

```python title="Python" lines theme={null}
import asyncio
import os
from openrouter_agent import OpenRouter, call_model


async def main() -> None:
    openrouter = OpenRouter(api_key=os.environ["OPENROUTER_API_KEY"])

    result = call_model(
        openrouter,
        {
            "model": "~anthropic/claude-sonnet-latest",
            "input": "Hello!",
        },
    )

    text = await result.get_text()
    print(text)


asyncio.run(main())

```

```go title="Go" lines theme={null}
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"model":    "~anthropic/claude-sonnet-latest",
		"messages": []map[string]string{{"role": "user", "content": "Hello!"}},
	})

	req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/chat/completions", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	var result struct {
		Choices []struct {
			Message struct {
				Content string `json:"content"`
			} `json:"message"`
		} `json:"choices"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
		log.Fatal(err)
	}
	if len(result.Choices) == 0 {
		log.Fatalf("no choices returned (status %d)", resp.StatusCode)
	}

	fmt.Println(result.Choices[0].Message.Content)
}

```

```text title="Output" theme={null}
Hello! How can I help you today?
```

**"Add a tool to my agent"**

The assistant understands the tool pattern:

```typescript lines theme={null}
import { OpenRouter, callModel, tool } from '@openrouter/agent';
import { z } from 'zod';

const openrouter = new OpenRouter({
  apiKey: process.env.OPENROUTER_API_KEY,
});

const searchTool = tool({
  name: 'search',
  description: 'Search the web',
  inputSchema: z.object({ query: z.string() }),
  execute: async ({ query }) => {
    return { results: ['...'] };
  },
});

const result = callModel(openrouter, {
  model: '~anthropic/claude-sonnet-latest',
  input: 'Search for TypeScript best practices',
  tools: [searchTool],
});

const text = await result.getText();
console.log(text);

```

```python title="Python" lines theme={null}
import asyncio
import os
from pydantic import BaseModel
from openrouter_agent import OpenRouter, call_model, tool


class SearchInput(BaseModel):
    query: str


def search(params: SearchInput, ctx) -> dict:
    return {"results": ["..."]}


search_tool = tool(
    name="search",
    description="Search the web",
    input_schema=SearchInput,
    execute=search,
)


async def main() -> None:
    openrouter = OpenRouter(api_key=os.environ["OPENROUTER_API_KEY"])

    result = call_model(
        openrouter,
        {
            "model": "~anthropic/claude-sonnet-latest",
            "input": "Search for TypeScript best practices",
            "tools": [search_tool],
        },
    )

    text = await result.get_text()
    print(text)


asyncio.run(main())

```

```go title="Go" lines theme={null}
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
)

type toolCall struct {
	ID       string `json:"id"`
	Type     string `json:"type"`
	Function struct {
		Name      string `json:"name"`
		Arguments string `json:"arguments"`
	} `json:"function"`
}

type message struct {
	Role       string     `json:"role"`
	Content    string     `json:"content,omitempty"`
	ToolCalls  []toolCall `json:"tool_calls,omitempty"`
	ToolCallID string     `json:"tool_call_id,omitempty"`
}

func search(query string) map[string]any {
	return map[string]any{"results": []string{"..."}}
}

func main() {
	tools := []map[string]any{{
		"type": "function",
		"function": map[string]any{
			"name":        "search",
			"description": "Search the web",
			"parameters": map[string]any{
				"type":       "object",
				"properties": map[string]any{"query": map[string]string{"type": "string"}},
				"required":   []string{"query"},
			},
		},
	}}
	messages := []message{{Role: "user", Content: "Search for TypeScript best practices"}}

	for i := 0; i < 5; i++ {
		body, _ := json.Marshal(map[string]any{
			"model":    "~anthropic/claude-sonnet-latest",
			"messages": messages,
			"tools":    tools,
		})
		req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/chat/completions", bytes.NewReader(body))
		req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
		req.Header.Set("Content-Type", "application/json")

		resp, err := http.DefaultClient.Do(req)
		if err != nil {
			log.Fatal(err)
		}
		var result struct {
			Choices []struct {
				Message message `json:"message"`
			} `json:"choices"`
		}
		err = json.NewDecoder(resp.Body).Decode(&result)
		resp.Body.Close()
		if err != nil {
			log.Fatal(err)
		}
		if len(result.Choices) == 0 {
			log.Fatalf("no choices returned (status %d)", resp.StatusCode)
		}

		msg := result.Choices[0].Message
		if len(msg.ToolCalls) == 0 {
			fmt.Println(msg.Content)
			return
		}
		messages = append(messages, msg)
		for _, tc := range msg.ToolCalls {
			var args struct {
				Query string `json:"query"`
			}
			if err := json.Unmarshal([]byte(tc.Function.Arguments), &args); err != nil || args.Query == "" {
				log.Fatalf("bad arguments for %s: %s", tc.Function.Name, tc.Function.Arguments)
			}
			out, _ := json.Marshal(search(args.Query))
			messages = append(messages, message{Role: "tool", ToolCallID: tc.ID, Content: string(out)})
		}
	}
	log.Fatal("too many tool-call rounds")
}

```

```text title="Output" theme={null}
The search tool returned only placeholder results ("...") for all three queries, so I have no sources to cite or summarize. Below are commonly recommended TypeScript practices from my own background knowledge. They don't come from the searches, so check them against current docs.

**Compiler configuration**
- Enable `"strict": true` in `tsconfig.json`. Consider adding `noUncheckedIndexedAccess`, `noImplicitOverride`, and `exactOptionalPropertyTypes`.
- Use `isolatedModules` and `skipLibCheck` where your build tooling needs them.

**Type design**
- Avoid `any`. Use `unknown` for values of uncertain type, and narrow them before use.
- Let inference work for local variables. Annotate function parameters and public API return types.
- Use `interface` for object shapes that may be extended. Use `type` for unions, intersections, and mapped or conditional types.
- Model states with discriminated unions instead of optional fields and flags.
- Prefer `readonly` and `as const` for data that shouldn't change.
- Use union types or `as const` objects instead of `enum` in most cases.

**Safety**
- Avoid type assertions (`as`) and non-null assertions (`!`). Use type guards and narrowing instead.
- Validate external data at runtime (for example with Zod, Valibot, or io-ts) rather than trusting a cast.
- Use `satisfies` to check a value against a type without widening it.

**Code organization**
- Use utility types (`Pick`, `Omit`, `Partial`, `Record`, `ReturnType`) instead of duplicating types.
- Use generics with constraints (`<T extends ...>`) to keep reusable code type-safe.
- Keep types close to where they're used, and export only what's needed.

**Tooling**
- Use `typescript-eslint` with type-aware rules, such as `no-floating-promises` and `no-explicit-any`.
- Use Prettier for formatting.
- Run `tsc --noEmit` in CI.

I can try searching again, or go deeper on any of these, such as strict config options or discriminated unions.
```

## Repository

The skill source is available at: [github.com/OpenRouterTeam/skills](https://github.com/OpenRouterTeam/skills)

Contributions and feedback are welcome.
