diff --git a/AGENTS.md b/AGENTS.md index 55f438d..384525d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,6 +4,10 @@ This repository contains the Mintlify source for [docs.tilebox.com](https://docs.tilebox.com). Use this file to keep documentation updates consistent with the current information architecture, writing style, and tooling. +## Required Writing Skill + +Always read and respect the `writing-technical-content` skill before writing, drafting, revising, or outlining technical documentation, guides, or long-form content in this repository. + ## Information Architecture Navigation is defined in `docs.json` and currently follows this top-level structure: diff --git a/agentic-development/agent-skills.mdx b/agentic-development/agent-skills.mdx new file mode 100644 index 0000000..99a75cc --- /dev/null +++ b/agentic-development/agent-skills.mdx @@ -0,0 +1,45 @@ +--- +title: Agent Skills +description: Install Tilebox skills that teach AI agents how to work with Tilebox tools and workflows. +icon: wand-magic-sparkles +--- + +Tilebox skills are task-level instructions for AI agents. They explain how to use the Tilebox CLI, which command patterns to prefer, and how to approach common workflows such as dataset management and job monitoring. + +## Install Tilebox skills + +Install the skills from the Tilebox skills repository. + +```bash +npx skills add tilebox/skills +``` + + + + Browse the source repository for the Tilebox agent skills. + + + +After installation, your agent can load the relevant skill before working on a Tilebox task. + +## Included skills + +Tilebox skills cover common agent workflows around the CLI, datasets, workflows, jobs, and automations. + +| Skill | What it covers | +| --- | --- | +| `using-tilebox-cli` | Authentication, `--json`, `jq`, `agent-context`, and documentation search | +| `managing-tilebox-datasets` | Creating schemas, updating metadata, and querying datasets | +| `managing-tilebox-jobs` | Submitting jobs, monitoring status, reading logs, and inspecting spans | +| `working-with-tilebox-automations` | Working with triggers, automations, and storage locations | +| `writing-tilebox-workflows` | Writing Tilebox workflow tasks and task runners | + +## How to use skills with agents + +Ask your agent to load the most specific Tilebox skill for the task. For example, use `managing-tilebox-datasets` for schema work and `managing-tilebox-jobs` for workflow execution or observability tasks. + +```text Prompt +Load the relevant Tilebox skills. Use the Tilebox CLI to submit a Sentinel-2 mosaic job, then monitor it until it completes. +``` + +Skills work best with the Tilebox CLI. The CLI gives the agent repeatable terminal commands, and skills tell it how to combine those commands safely. Use MCP as an alternative when the agent runs in a web or chat environment without practical terminal access. diff --git a/agentic-development/ai-interfaces.mdx b/agentic-development/ai-interfaces.mdx new file mode 100644 index 0000000..e7ecb00 --- /dev/null +++ b/agentic-development/ai-interfaces.mdx @@ -0,0 +1,29 @@ +--- +title: AI interfaces +description: Choose the right Tilebox interface for AI-assisted work. +icon: route +--- + +Tilebox gives agents multiple ways to get context and take action. The right interface depends on whether the agent needs live Tilebox access, repeatable terminal commands, workflow instructions, or documentation-only context. + +## Interface guide + +| Interface | Use it for | What it gives the agent | +| --- | --- | --- | +| [Tilebox CLI](/agentic-development/tilebox-cli) | Default setup for coding agents, terminal operations, automation, and CI-friendly workflows | Structured command output, command discovery, and predictable inputs | +| [Agent Skills](/agentic-development/agent-skills) | Repeated Tilebox tasks across datasets, jobs, and automations | Instructions for composing CLI commands into end-to-end workflows | +| [Tilebox MCP](/agentic-development/tilebox-mcp) | Web-based agents, chat tools, or MCP-capable clients where terminal access is limited | Authenticated tools for datasets, workflows, and documentation search | +| [Tilebox SDKs](/sdks/introduction) | Application code and production integrations | Language-native APIs for Python and Go | +| [`llms-full.txt`](https://docs.tilebox.com/llms-full.txt) | Documentation-only context | A static markdown bundle of the Tilebox documentation | + +## How the interfaces fit together + +Use the CLI when an agent can run terminal commands. This is the default interface for repository-based coding agents because commands are explicit, repeatable, and easy to inspect. Use skills when the agent needs guidance for multi-step Tilebox tasks, such as creating datasets or monitoring workflow jobs. + +Use the MCP server when an agent cannot easily run terminal commands. This is common for web-based agents and chat tools where the agent can call hosted tools but cannot access a shell. MCP is also useful when you want an AI client to access Tilebox documentation search and live Tilebox tools without installing local software. + +The interfaces are complementary. For example, a coding agent can use the CLI to inspect available commands with `tilebox agent-context` and use the `managing-tilebox-jobs` skill to monitor a submitted workflow job. A web-based agent can use the MCP server for documentation search and live Tilebox access instead. + +## Recommended defaults + +For AI-assisted development in a codebase, install the CLI and Tilebox skills. Add MCP when your agent runs outside a terminal environment or when you prefer a hosted tool connection from a web or chat interface. diff --git a/agentic-development/onboard-your-agent.mdx b/agentic-development/onboard-your-agent.mdx new file mode 100644 index 0000000..4dd4c8f --- /dev/null +++ b/agentic-development/onboard-your-agent.mdx @@ -0,0 +1,63 @@ +--- +title: Onboard your agent +description: Configure an AI agent with the Tilebox CLI and Tilebox skills. +icon: rocket +--- + +This tutorial gives an AI agent the default Tilebox setup for repository-based work: the Tilebox CLI and Tilebox skills. After completing it, your agent can inspect available CLI commands, run commands with structured output, and use Tilebox-specific skills for datasets, jobs, and automations. + + + + Install the Tilebox CLI with the install script. + + ```bash + curl -fsSL https://cli.tilebox.com/install.sh | sh + ``` + + The CLI is the default interface for coding agents because it works in the same terminal where the agent edits files, runs tests, and applies changes. + + + Set `TILEBOX_API_KEY` in the environment where your agent runs. You can create an API key in the [Tilebox Console](https://console.tilebox.com/settings/api-keys). + + ```bash + export TILEBOX_API_KEY="YOUR_TILEBOX_API_KEY" + ``` + + Use a key with the smallest permissions needed for the task you want the agent to perform. + + + Install the Tilebox skills so your agent has task-level instructions for working with the CLI and Tilebox resources. + + ```bash + npx skills add tilebox/skills + ``` + + The skills cover CLI usage, dataset management, job monitoring, workflow authoring, and automations. + + + Configure the Tilebox MCP server when your agent cannot easily use terminal commands, for example in a web-based chat tool. The server uses OAuth, so you do not need to add API keys or headers to the configuration. + + ```json + { + "mcpServers": { + "tilebox": { + "url": "https://mcp.tilebox.com/mcp" + } + } + } + ``` + + When the client connects, sign in with your Tilebox account and select the team the agent should use. + + + Ask your agent to inspect its Tilebox capabilities before assigning a larger task. + + ```text Prompt + Check your Tilebox setup. Confirm whether the `tilebox` CLI is installed, whether you can inspect commands with `tilebox agent-context`, which Tilebox skills are available, and which datasets are available. Do not modify any Tilebox resources. + ``` + + + +## Next steps + +Continue with [Tilebox CLI](/agentic-development/tilebox-cli) for agent-friendly command patterns, or use [AI interfaces](/agentic-development/ai-interfaces) to decide when MCP is a better fit than terminal commands. diff --git a/agentic-development/overview.mdx b/agentic-development/overview.mdx new file mode 100644 index 0000000..e155bd7 --- /dev/null +++ b/agentic-development/overview.mdx @@ -0,0 +1,33 @@ +--- +title: AI Overview +description: Learn how Tilebox supports agentic development through the CLI, agent skills, the MCP server, and documentation context. +icon: brain-circuit +--- + +AI-assisted development in Tilebox is built around giving agents the same operational context that developers use: current documentation, authenticated access to Tilebox resources, and predictable tools for running actions. The section explains how to connect agents to Tilebox, which interface to use for each task, and how the Tilebox CLI and skills help agents work with datasets and workflows. + +## How Tilebox supports agents + +Tilebox supports agents through a CLI-based setup. The CLI gives agents a deterministic terminal interface with structured output, machine-readable command discovery, and file-based inputs. Agent skills teach agents how to compose CLI commands into common Tilebox tasks, while the MCP server is available for AI tools where terminal access is limited, such as web-based chat agents. + + + + Configure an agent with the Tilebox CLI, Tilebox skills, and documentation context. + + + Decide when to use MCP, the CLI, skills, SDKs, or documentation context. + + + Connect AI tools to the Tilebox MCP server when terminal access is not available. + + + Install the CLI, authenticate it, and use agent-friendly command patterns. + + + Install Tilebox skills that teach agents how to work with Tilebox tools. + + + +## Recommended setup + +Use [Onboard your agent](/agentic-development/onboard-your-agent) if you want an AI coding agent to help with Tilebox work in a repository. It covers the default setup with CLI installation, CLI authentication, Tilebox skills, and documentation context. Use the MCP setup when your agent runs in a web or chat environment where commands and terminals are not easy to use. diff --git a/agentic-development/tilebox-cli.mdx b/agentic-development/tilebox-cli.mdx new file mode 100644 index 0000000..15d4351 --- /dev/null +++ b/agentic-development/tilebox-cli.mdx @@ -0,0 +1,70 @@ +--- +title: Tilebox CLI +description: Install, authenticate, and use the Tilebox CLI in AI-assisted development workflows. +icon: terminal +--- + +The Tilebox CLI is a command-line interface for humans, agents, and automation. It helps AI-assisted workflows by exposing Tilebox operations through explicit commands, supporting structured output, and letting agents inspect the command tree before taking action. + +Use the CLI as the default Tilebox interface for coding agents that can run terminal commands. It keeps actions visible in the shell, works with existing development workflows, and pairs with Tilebox skills for multi-step tasks. + +## Install the CLI + +Install the Tilebox CLI with the install script. + +```bash +curl -fsSL https://cli.tilebox.com/install.sh | sh +``` + +## Authenticate + +The CLI reads the `TILEBOX_API_KEY` environment variable. Create an API key in the [Tilebox Console](https://console.tilebox.com/settings/api-keys), then export it in the shell or agent environment that runs CLI commands. + +```bash +export TILEBOX_API_KEY="YOUR_TILEBOX_API_KEY" +``` + +Use API keys with the smallest permissions needed for the agent's task. + +## Discover commands with agent-context + +Agents should inspect the CLI instead of guessing command names and flags. The `agent-context` command returns machine-readable information about the available command tree, arguments, flags, and descriptions. + +```bash +tilebox agent-context +``` + +Use this before asking an agent to create datasets, submit jobs, or manage automations with the CLI. + +## Prefer JSON output + +Use `--json` when the agent needs to parse command output. Structured output is easier for agents to inspect, filter, and pass to follow-up commands than terminal tables. + +```bash +tilebox dataset list --json +``` + +## Use files and standard input for generated input + +For larger inputs, prefer file-based flags instead of long shell-quoted strings. The CLI supports input patterns such as `--schema-file`, `--input-file`, `--spatial-extent-file`, and `--description-file`. Many file flags also support `-` for reading from standard input. + +```bash +tilebox dataset create --schema-file schema.json +``` + +```bash +# Read from stdin. +cat schema.json | tilebox dataset create --schema-file - +``` + +This pattern is safer for agents because generated JSON, geometry, and descriptions do not need to be embedded in one fragile shell command. + +## Use the CLI with Tilebox skills + +The Tilebox skills include guidance for using the CLI in agent workflows. Install them when you want an agent to combine CLI commands into higher-level tasks such as managing datasets, monitoring jobs, or configuring automations. + +```bash +npx skills add tilebox/skills +``` + +After installing the skills, ask your agent to inspect `tilebox agent-context` and follow the relevant Tilebox skill before running commands that change resources. If your agent cannot use a terminal, configure the [Tilebox MCP server](/agentic-development/tilebox-mcp) instead. diff --git a/agentic-development/tilebox-mcp.mdx b/agentic-development/tilebox-mcp.mdx new file mode 100644 index 0000000..2fed56c --- /dev/null +++ b/agentic-development/tilebox-mcp.mdx @@ -0,0 +1,65 @@ +--- +title: Tilebox MCP +description: Configure the Tilebox MCP server for AI tools that support the Model Context Protocol. +icon: plug +--- + +The Tilebox MCP server connects AI tools to Tilebox through the Model Context Protocol. It exposes tools for working with Tilebox datasets and workflows, and it includes documentation search so agents can retrieve current Tilebox context before answering questions or taking action. + +Use MCP when your agent cannot easily use terminal commands. For coding agents with shell access, the [Tilebox CLI](/agentic-development/tilebox-cli) and [Agent Skills](/agentic-development/agent-skills) are the default setup. MCP is a good fit for web-based agents, chat tools, or hosted AI clients that support MCP but do not run local commands. + +## What the MCP server provides + +The MCP server at `https://mcp.tilebox.com/mcp` provides tools for: + +- Accessing and interacting with Tilebox datasets and workflows +- Searching the Tilebox documentation + +When an MCP-capable client has the server configured, it can invoke relevant tools during a conversation. For example, when you ask about a dataset, the agent can query the Tilebox MCP server for the current schema and include that information in its response. + +## Authentication + +The Tilebox MCP server uses OAuth. When your AI client connects, you are redirected to sign in with your Tilebox account and select a team. You do not need to configure API keys or custom headers for MCP authentication. + +## Configure an MCP client + +Add the Tilebox MCP server using the HTTP transport when your AI client supports MCP. + +```json +{ + "mcpServers": { + "tilebox": { + "url": "https://mcp.tilebox.com/mcp" + } + } +} +``` + +## Configure Claude Code + +Run the following command to add the Tilebox MCP server to Claude Code: + +```bash +claude mcp add --transport http "Tilebox" https://mcp.tilebox.com/mcp +``` + +## Use multiple teams + +If you need to access multiple Tilebox teams, add a separate MCP server entry for each team. Each entry goes through its own OAuth flow and can be authorized for a different team. + +```json +{ + "mcpServers": { + "tilebox-team1": { + "url": "https://mcp.tilebox.com/mcp" + }, + "tilebox-team2": { + "url": "https://mcp.tilebox.com/mcp" + } + } +} +``` + + +Use clear server names when configuring multiple teams so your agent can choose the correct Tilebox workspace for each task. + diff --git a/ai-assistance.mdx b/ai-assistance.mdx deleted file mode 100644 index 37b570f..0000000 --- a/ai-assistance.mdx +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: AI Assistance -description: Large Language Models (LLMs) are powerful tools for exploring and learning about Tilebox. This section explains how to provide them with Tilebox-specific context for tailored, relevant and up-to-date responses. -icon: brain-circuit ---- - -## Tilebox MCP Server - -The Model Context Protocol (MCP) is an open protocol that creates standardized connections between AI applications and -external services. Tilebox provides such an MCP server that exposes tools for listing, querying and retrieving the schema -of datasets, as well as tools for interacting with workflows. - -### How the Tilebox MCP server can help - -When an AI tool like Claude, Cursor, or ChatGPT has the Tilebox MCP server configured, it can proactively invoke relevant -tools. For example, when asking a question about a specific dataset, the AI tool can query the Tilebox MCP server for the -dataset schema and include the correct, and up-to-date information about it in the response. - -The Tilebox MCP server at `https://mcp.tilebox.com/mcp` provides tools for: -- Accessing and interacting with Tilebox datasets and workflows -- Searching the Tilebox documentation - -It requires authentication via OAuth. When connecting, you'll be redirected to sign in with your Tilebox account and select a team to use the MCP server for. -When configured, AI agents can query datasets, interact with workflows, and search the documentation for detailed context on specific topics. - -### Configuring the Tilebox MCP server - -To configure your AI tools to use the Tilebox MCP server, you need to point it to the correct URL using the `http` transport. -Authentication is handled automatically via OAuth, no API key or headers required. - -```json -{ - "mcpServers": { - "tilebox": { - "url": "https://mcp.tilebox.com/mcp" - } - } -} -``` - -### For Claude Desktop - -Run the following command to add the Tilebox MCP server to Claude: - -```bash -claude mcp add --transport http "Tilebox" https://mcp.tilebox.com/mcp -``` - - -If you need to access multiple teams, add a separate MCP server instance for each one. For example: - -```json -{ - "mcpServers": { - "tilebox-team1": { - "url": "https://mcp.tilebox.com/mcp" - }, - "tilebox-team2": { - "url": "https://mcp.tilebox.com/mcp" - } - } -} -``` - -Each instance will go through its own OAuth flow, allowing you to authorize a different team. - - -## Providing the full Tilebox documentation as context - -As an alternative to using the MCP server's documentation search, you can also provide the full Tilebox documentation as context to your AI assistant or language model. -To do so, you can download the complete documentation as a plain text file below. - - -Download the complete Tilebox documentation as a plain text file to share with your AI assistant or language model. - - -The full content of the Tilebox documentation is available in plain markdown format at [https://docs.tilebox.com/llms-full.txt](https://docs.tilebox.com/llms-full.txt). Upload this document to your AI assistant or LLM to provide it with Tilebox-specific context. - - -The [Documentation Context](https://docs.tilebox.com/llms-full.txt) is updated whenever the documentation changes. If you download the file, refresh it occasionally to stay up-to-date. - diff --git a/changelog.mdx b/changelog.mdx index 9a58db0..b4fe9f1 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -40,7 +40,7 @@ icon: rss ## MCP Server for Datasets and Workflows - Introducing the [Tilebox MCP server](/ai-assistance), which provides tools for AI agents to access and interact with Tilebox datasets and workflows. + Introducing the [Tilebox MCP server](/agentic-development/tilebox-mcp), which provides tools for AI agents to access and interact with Tilebox datasets and workflows. diff --git a/console.mdx b/console.mdx index 5648dbb..8bf1692 100644 --- a/console.mdx +++ b/console.mdx @@ -1,7 +1,7 @@ --- title: Console description: A web interface for exploring your datasets and workflows, managing API keys and team members, and keeping track of your usage of the Tilebox platform. -icon: terminal +icon: display --- The [Tilebox Console](https://console.tilebox.com) is a web interface that enables you to explore your datasets and workflows, manage your account and API keys, add collaborators to your team and monitor your usage. diff --git a/docs.json b/docs.json index 5ec0ec1..618d352 100644 --- a/docs.json +++ b/docs.json @@ -27,10 +27,20 @@ "introduction", "quickstart", "console", - "ai-assistance", "authentication" ] }, + { + "group": "Agentic Development", + "pages": [ + "agentic-development/overview", + "agentic-development/onboard-your-agent", + "agentic-development/ai-interfaces", + "agentic-development/tilebox-cli", + "agentic-development/tilebox-mcp", + "agentic-development/agent-skills" + ] + }, { "group": "Datasets", "pages": [ @@ -303,7 +313,7 @@ { "anchor": "Console", "href": "https://console.tilebox.com", - "icon": "terminal" + "icon": "display" }, { "anchor": "Book a Demo",