From a248835ecac8eaab14a4e48299363aaba7c7d18d Mon Sep 17 00:00:00 2001 From: Valery Antopol Date: Wed, 18 Nov 2026 21:58:46 +0400 Subject: [PATCH 1/3] docs: add the Cloud Agents section --- docs/build/cloud_agents/ai_providers.md | 81 +++++++++++ docs/build/cloud_agents/extensions.md | 160 +++++++++++++++++++++ docs/build/cloud_agents/get_started.md | 68 +++++++++ docs/build/cloud_agents/manage_agents.md | 113 +++++++++++++++ docs/build/cloud_agents/overview.md | 85 +++++++++++ docs/build/cloud_agents/presets.md | 97 +++++++++++++ docs/build/cloud_agents/secrets.md | 88 ++++++++++++ docs/build/cloud_agents/troubleshooting.md | 143 ++++++++++++++++++ docs/build/llms_txt_include_head.md | 2 +- docs/build/overview.md | 1 + sidebars.js | 14 ++ 11 files changed, 851 insertions(+), 1 deletion(-) create mode 100644 docs/build/cloud_agents/ai_providers.md create mode 100644 docs/build/cloud_agents/extensions.md create mode 100644 docs/build/cloud_agents/get_started.md create mode 100644 docs/build/cloud_agents/manage_agents.md create mode 100644 docs/build/cloud_agents/overview.md create mode 100644 docs/build/cloud_agents/presets.md create mode 100644 docs/build/cloud_agents/secrets.md create mode 100644 docs/build/cloud_agents/troubleshooting.md diff --git a/docs/build/cloud_agents/ai_providers.md b/docs/build/cloud_agents/ai_providers.md new file mode 100644 index 0000000..8bc3a2d --- /dev/null +++ b/docs/build/cloud_agents/ai_providers.md @@ -0,0 +1,81 @@ +--- +description: Connect a ChatGPT subscription, a provider API key, or your own OpenAI or Anthropic compatible endpoint, so cloud agents can use its models. +--- + +# Connect an AI provider + +Cloud agents call models through the AI providers that you connect. You connect them once on the **Cloud agents** > **AI providers** page, and every new agent can use their models. Model use is billed by your AI provider, separately from the machine. + +You can connect providers in three ways: + +| Way | What you bring | Models | +|---|---|---| +| Subscription | A ChatGPT plan. You sign in with a code, without an API key. | The models of your ChatGPT plan | +| API key | A key of **Fluence inference**, **OpenAI**, **Z.ai**, or **OpenRouter** | The models of that provider | +| Custom | The base URL and API key of an OpenAI or Anthropic compatible API | The models that the endpoint lists | + +You can connect several at once. The **Providers** card shows how many sources are connected, and the **Overview** panel shows the **ChatGPT** state and the number of **Provider keys**. + +Keys are checked when you add them, stored, and never shown again. To change a key, save a new one. + +## Sign in with a ChatGPT subscription + +With a subscription, agents use your ChatGPT plan instead of an API key. + +1. Open **Cloud agents** > **AI providers** and select **Subscription**. +2. If the page shows a **ChatGPT** row with **Connect**, click **Connect**. +3. Click **Sign in with ChatGPT**. The console shows an address and a code. +4. Open the address, sign in to ChatGPT, and type the code. The console shows how many minutes the code is good for. +5. Wait until the subscription shows **Active**. The page refreshes by itself. + +A subscription shows one of these states: + +| State | Meaning | +|---|---| +| **Waiting for code** | You started the sign-in and have not entered the code yet | +| **Active** | Agents can use the subscription | +| **Needs sign-in** | The sign-in no longer works. Click **Sign in again**. | +| **Forgetting…** | The subscription is being removed | + +You can sign in more than one subscription. Agents use the one marked **selected**. The others stay signed in as spares. To switch, click **Use this one** on an active subscription. + +To remove a subscription, click **Forget** and confirm with **Forget subscription**. If you forget the selected one, the most recently signed-in active subscription takes its place. With none left, new agents cannot use ChatGPT models until you sign in again. + +## Add an API key + +1. Open **Cloud agents** > **AI providers** and select **API key**. +2. Click **Connect** next to **Fluence inference**, **OpenAI**, **Z.ai**, or **OpenRouter**. +3. Paste the key. The link under the field opens the page where the provider issues keys. +4. Click **Save key**. The row shows **Ready**. + +To replace a key, click **Change**, paste the new key, and click **Save key**. To remove it, click **Change**, then **Remove**, and confirm with **Remove key**. New agents can no longer use the models of that provider through a key until you add one again. + +A **Fluence inference** key needs the inference permission. The console reads the models of the key once, when you save it. If the key gives no model list, the console refuses it. + +## Connect your own endpoint + +Use **Custom** for any OpenAI or Anthropic compatible API, for example a model that you serve yourself. + +1. Open **Cloud agents** > **AI providers** and select **API key**. +2. In the **Custom** row, click **Connect**. +3. Enter the provider name, for example `vllm`. Use up to 48 lowercase letters, digits, and hyphens, starting with a letter or a digit. You cannot change the name later. +4. Enter the base URL, for example `https://llm.example.com/v1`. +5. Choose **OpenAI protocol** or **Anthropic protocol**. +6. Enter the API key. +7. Click **Add provider**. + +When you save, Fluence asks the address for its model list. The address must be reachable from the public internet and must answer with a list of models. If it does not, the console refuses the provider. + +Agents name the models of a custom provider as `custom-/`, for example `custom-vllm/llama-3.1-8b`. + +To change the address, the protocol, or the key, click **Change** on the provider row and then **Save provider**. An empty key field keeps the stored key. To remove the provider with its key, click **Remove** and confirm with **Remove provider**. + +## How models are named + +A model has the form `provider/model`. The launch form lists the models of all connected providers, each with its provider. You normally pick a model from the list. + +When the console cannot load the list, or the connected providers list no models, the **Model** field becomes a text field. Enter the model as `provider/model`. + +## Changes and running agents + +An agent takes its AI providers at launch. A new key, a removed provider, or a new subscription applies to new launches. Running agents keep what they started with. diff --git a/docs/build/cloud_agents/extensions.md b/docs/build/cloud_agents/extensions.md new file mode 100644 index 0000000..315e926 --- /dev/null +++ b/docs/build/cloud_agents/extensions.md @@ -0,0 +1,160 @@ +--- +description: Give cloud agents remote MCP servers, OpenCode plugins, and skills repositories. How MCP server secrets are sent, plugin package formats, variables, limits, and common mistakes. +--- + +# Add MCP servers, plugins, and skills + +Extensions give an agent more than its model and its repository. You add them once on the **Cloud agents** > **Extensions** page, and every new agent gets them. There are three kinds: + +| Kind | What it gives the agent | +|---|---| +| MCP servers | Tools that the agent can call during a task, served by a remote MCP server | +| OpenCode plugins | Packages that extend the agent itself | +| Skills repositories | Git repositories with skills that the agent can use | + +An agent takes its extensions at launch. Changes apply to new launches. Running agents keep what they started with. The **Details** panel of an agent shows how many extensions it was launched with. + +## MCP servers + +An MCP server here is a remote server that the agent reaches over HTTP. Each has a name, a URL, and an optional secret. The agent cannot start a local MCP server from a command. + +### Add an MCP server + +If the server needs a key, first add the key as a named secret on the **Secrets** page. See [Add a named secret](./secrets.md#add-a-named-secret). + +1. Open **Cloud agents** > **Extensions**. +2. In the **MCP servers** card, click **Add MCP server**. +3. Enter the name, for example `docs`. Use lowercase letters, digits, hyphens, and underscores. Each server needs its own name. +4. Enter the URL of the MCP endpoint, for example `https://mcp.example.com/mcp`. +5. Optional: choose the secret that holds the key of the server. **No secret** sends no key. +6. If you chose a secret, choose how the key is sent. See [How the key is sent](#how-the-key-is-sent). +7. Click **Add server**. + +The server row shows its URL and the name of its secret, or **no secret**. + +To change a server, click **Change** on its row and then **Save server**. To remove it, click **Change**, then **Remove**. + +### How the key is sent + +The agent sends the secret in a request header on each call to the server. You choose one of two headers: + +| Option | Header the server receives | When to use it | +|---|---|---| +| **Authorization: Bearer \** | `Authorization: Bearer` followed by the secret value | The default. It fits most MCP servers, for example GitHub, Linear, and Notion. | +| **X-API-KEY: \** | `X-API-KEY` with the secret value | When the documentation of the service names the `X-API-KEY` header, for example the Fluence MCP server. | + +The server record holds only the name of the secret, never its value. The value is the one stored on the **Secrets** page when the agent launches. + +You cannot send a secret in any other header, add custom headers, or put a secret into the URL from the form. If a server accepts its key only in a query string or a custom header, it does not fit. + +### Example: the Fluence MCP server + +To let an agent manage your Fluence resources, connect the [Fluence MCP server](../../build_with_ai/mcp.md): + +1. Create an API key in **Settings** > **API keys**. See [API keys](../settings.md#api-keys). +2. On **Cloud agents** > **Secrets**, add a secret, for example `fluence_api_key`, with the key as its value. +3. On **Cloud agents** > **Extensions**, add an MCP server with the URL `https://api.fluence.dev/mcp`, the secret `fluence_api_key`, and **X-API-KEY: \**. + +### If the secret is missing + +An MCP server can name a secret that no longer exists, for example after you removed the secret. Then: + +- The preset page shows **Missing secret** with the name of the secret and the server that uses it. The preset list shows the number of missing secrets. +- A launch from that preset is refused. The message names the secret and what uses it. + +To fix it, add the secret again under the same name on the **Secrets** page, or choose another secret for the server. + +### Tips for MCP servers + +- Use the exact endpoint URL from the documentation of the service. Many servers serve MCP on a path such as `/mcp`, not on the site root. +- Give each server a short name that says what it is, for example `linear` or `docs`. +- If a tool call fails with an authorization error, check the header first. A key sent as **Authorization: Bearer** does not work on a server that expects `X-API-KEY`, and the other way round. +- Paste only the key as the secret value. Do not add `Bearer` in front of it. +- The agent's machine reaches the server over the internet. A server on your laptop or in a private network does not work. +- A failed tool call shows in the conversation under **Used N tools**, marked as failed. + +## OpenCode plugins + +A plugin is a package that the agent installs at start. You name the package and, if the plugin needs settings, its variables. + +### Add a plugin + +1. Open **Cloud agents** > **Extensions**. +2. In the **OpenCode plugins** card, click **Add plugin**. +3. Enter the plugin package. See [Plugin package formats](#plugin-package-formats). +4. Optional: click **Add variable**, and enter a variable name and a value. The value is stored as typed and stays visible in the console. +5. Optional: click **Add secret variable**, enter a variable name, and choose a secret. The plugin gets the value of that secret under the variable name. +6. Click **Add plugin**. + +The plugin row shows the package, the number of variables and secret variables, and the secrets it uses. + +To change a plugin, click **Change** on its row and then **Save plugin**. To remove it, click **Change**, then **Remove**. + +### Plugin package formats + +| Format | Example | Notes | +|---|---|---| +| npm package | `opencode-example-plugin`, `opencode-example-plugin@1.2.0`, `@scope/plugin@latest` | A version or a tag after `@` is optional | +| HTTPS archive | `https://example.com/plugins/plugin-1.2.0.tgz` | The address starts with `https://`, ends with `.tgz`, and has no credentials, query string, or fragment | +| GitHub repository | `github:owner/repo`, `github:owner/repo#v1.2.0` | A public repository whose root package carries a built plugin. A branch, tag, or commit after `#` is optional | + +Pin a version, a tag, or a commit. An unpinned package can change between two launches. + +### Variables and secret variables + +A plugin has two kinds of variables: + +| | Variable | Secret variable | +|---|---|---| +| Holds | A value that you type | The name of a secret from the **Secrets** page | +| Shown in the console | Yes | Only the secret name | +| Use it for | Settings that are not sensitive, for example a URL or a mode | Tokens and keys | + +Never type a token into a plain variable. It stays readable in the console. + +A variable name uses letters, digits, and underscores, and does not start with a digit. All plugins of an agent share one set of environment variables. If two plugins set the same variable, they must set it to the same value or the same secret. Otherwise the console refuses the save and names both sides. + +A secret variable lets a plugin read a secret under the name the plugin expects. For example, a plugin that reads `LINEAR_TOKEN` can take it from your secret `linear_api_key`. + +### Plugin order and limits + +Plugins reach the agent in the order of the list. A new plugin goes to the end, and a changed plugin keeps its place. The console has no control to reorder plugins. To move a plugin to the end, remove it and add it again. + +The limits are: + +| Limit | Value | +|---|---| +| Plugins in one preset | 100 | +| Length of the plugin package | 2,048 bytes | +| Variables per plugin | 128 | +| Secret variables per plugin | 128 | +| Length of a variable name | 128 characters | +| Length of a variable value | 8,192 bytes, with no control characters such as line breaks | + +A variable cannot be both a variable and a secret variable of the same plugin. These variable names are reserved and refused: `GH_TOKEN`, `OPENCODE_CONFIG`, any name that starts with `GIT_`, and any name that starts with `Profile_`. + +If a plugin names a missing secret, the preset shows **Missing secret**, and a launch from it is refused, the same as for an [MCP server](#if-the-secret-is-missing). + +## Skills repositories + +A skills repository is a Git repository with skills that the agent can use. Each repository is cloned into its own directory on the machine. + +1. Open **Cloud agents** > **Extensions**. +2. In the **Skills repositories** card, click **Add skills repository**. +3. Enter the URL of the repository, for example `https://github.com/owner/skills`. +4. Click **Add repository**. + +Add each repository once. To change or remove one, click **Change** on its row. + +## Extensions and presets + +With only the **Default** preset, every extension goes to every new agent, and you can skip this section. + +When you have more than one preset, each preset includes its own set of extensions: + +- Each form on the **Extensions** page shows a **Presets** group. Select the presets that include the extension. A new extension is selected for all presets. +- Each row shows where the extension is included: **All presets**, or the names of the presets. **Differs in** names the presets whose copy of the extension is not the one shown. +- **Remove** takes the extension out of every preset. +- You can also choose the extensions of one preset on its page. See [Choose the extensions of a preset](./presets.md#choose-the-extensions-of-a-preset). + +If a save reaches some presets and not others, the console says in which presets it was not saved. Fix the cause and save again. diff --git a/docs/build/cloud_agents/get_started.md b/docs/build/cloud_agents/get_started.md new file mode 100644 index 0000000..e804c20 --- /dev/null +++ b/docs/build/cloud_agents/get_started.md @@ -0,0 +1,68 @@ +--- +description: Set up cloud agents once in the Fluence Console, then launch your first agent with a task, a model, and a repository. +--- + +# Launch your first cloud agent + +This guide takes you from an empty **Cloud agents** section to a working agent. You connect an AI provider and add a GitHub token once. After that, each launch asks only for a task, a model, and a repository. For what an agent is and how it is billed, see [Cloud agents concepts](./overview.md). + +Before you start, you need: + +- A Fluence account. The machine of the agent is billed to it. See [Payment and balance management](../balance.md). +- Access to models: a ChatGPT plan, an API key of a supported provider, or your own OpenAI or Anthropic compatible endpoint. +- A GitHub token with access to the repository the agent works on. + +## Open Cloud agents + +In the sidebar of the Fluence Console, open **Cloud agents**. The first time, the console connects the section to your account by itself and shows **Connecting Cloud agents…**. There is nothing to click. + +The section has five tabs: **Agents**, **Presets**, **AI providers**, **Secrets**, and **Extensions**. Before your first agent, the **Agents** tab shows **Launch your first agent** with the setup steps. + +If the console shows **Your role cannot use Cloud agents**, your role in the account lacks the access the message names. Ask the account owner for a role that grants it. + +## Connect an AI provider + +1. Open the **AI providers** tab. +2. Under **Providers**, choose how agents reach models: + - To use your ChatGPT plan, select **Subscription** and click **Sign in with ChatGPT**. If the page shows a **ChatGPT** row with **Connect** instead, click **Connect** first. Then open the address the console shows, and type the code. + - To use an API key, select **API key**, click **Connect** next to the provider, paste the key, and click **Save key**. +3. Check that the provider row shows **Ready**, or that **ChatGPT** in the **Overview** panel reads **Signed in**. + +For all options, including your own endpoint, see [Connect an AI provider](./ai_providers.md). + +## Add a GitHub token + +1. Open the **Secrets** tab. +2. In the **GitHub token** card, click **Connect**. +3. Paste a token and click **Save token**. + +The token needs access to every repository you give an agent: read access to clone, write access to push and open pull requests. See [Add a GitHub token and secrets](./secrets.md). + +## Launch the agent + +1. Open the **Agents** tab and click **Create new agent**. When you already have agents, the button reads **New agent**. +2. In the **Task** step, describe the work in **Task**, for example "Add a health check endpoint to the API, cover it with a test and open a pull request." Optional: enter an **Agent name**. +3. In the **Model** step, choose a model. The list comes from your connected AI providers. +4. In the **Machine** step, check the machine and its hourly price. The machine belongs to the preset. To use another size, click **Change in preset**. +5. In the **Repository** step, enter the **Repository URL**, for example `https://github.com/owner/repository`. +6. Check the **Review** panel: the model, the repository, the machine, and the **Price**. The panel below it lists the AI providers, secrets, and extensions that the agent gets. +7. Click **Launch agent**. + +The console opens the agent page. The agent starts on the task right after launch. + +If **Launch agent** is disabled, the line under it says what is missing: **Connect an AI provider to launch.** or **Add a GitHub token to launch.** + +If the console cannot confirm the launch, it opens the agent list. Check the list before you launch again. Otherwise you can end up with two agents. + +## Follow the work + +On the agent page, the state goes from **Pending** through **Preparing** to **Working**. Creating the machine takes a few minutes. The step next to the state shows the progress, for example **Raising the machine**. + +When the agent works, its replies and tool calls appear in the conversation. When the turn ends, the state becomes **Idle**. Send another message to continue, or stop the agent when the work is done. See [Work with a cloud agent](./manage_agents.md). + +## Stop the agent + +1. On the agent page, open the menu in the **Details** panel and click **Stop**. +2. Click **Stop agent** to confirm. + +The agent stops, and its machine is released. An agent that you leave idle is stopped by itself after the idle time of its preset. diff --git a/docs/build/cloud_agents/manage_agents.md b/docs/build/cloud_agents/manage_agents.md new file mode 100644 index 0000000..4b9327b --- /dev/null +++ b/docs/build/cloud_agents/manage_agents.md @@ -0,0 +1,113 @@ +--- +description: Launch cloud agents, read their conversation, send messages, steer or queue a turn, interrupt a turn, stop an agent, and launch a copy in the Fluence Console. +--- + +# Work with a cloud agent + +You launch and manage cloud agents in the Fluence Console under **Cloud agents** > **Agents**. For states, turns, and pricing, see [Cloud agents concepts](./overview.md). + +## Launch an agent + +Before the first launch, connect an AI provider and add a GitHub token. See [Launch your first cloud agent](./get_started.md). + +1. On the **Agents** tab, click **New agent**. +2. If you have more than one preset, choose the **Preset**. With only the **Default** preset, the form does not show this field. +3. Optional: enter an **Agent name**, up to 128 bytes on one line. +4. In **Task**, describe the work. The task is the first message the agent gets. It can be up to 20,000 characters. +5. In **Model**, choose a model. +6. In **Repository URL**, enter an `https://` address without credentials, for example `https://github.com/owner/repository`. +7. Check the **Review** panel and click **Launch agent**. + +When you choose another preset, the form takes its default model and fills the task and the repository if you left them empty. The **Machine** step shows the machine of the preset. To change it, click **Change in preset**. + +### Repositories + +A launch needs a repository. The agent clones it with the GitHub token: + +- The token needs read access to clone, and write access to push and open pull requests. +- The **Repository** step shows **Token checked**, **Token not checked**, or **No GitHub token**. A checked token is valid, but the console learns only at launch whether it reaches this repository. +- An agent that cannot clone the repository fails. Its page shows **The repository could not be prepared on the agent's machine.** Check the address and the access of the token, then launch again. + +An agent works on one repository. To work on another one, launch another agent. + +## Agent list + +The list shows each agent with its repository as the title, its **Last turn**, **Model**, **Price** per hour, **Updated** time, and **State**. + +- **Last turn** shows **Running**, **OK**, or the reason the last turn went badly. +- By default, the list shows active agents. Ended and failed agents are hidden. To see them, change the state filter, or click **Show all**. +- **Search agents** matches the repository, the agent name, and the agent ID. +- To sort by the last change, click **Updated**. + +The list refreshes by itself every 10 seconds. + +## Agent page + +Click an agent to open its page. It has the conversation on the left and the **Details** panel on the right. + +The **Details** panel shows the **Status**, **Name**, **Model**, **Repository**, **Machine**, the number of **Extensions** the agent was launched with, and the **Price** of the machine per hour. If the agent failed, the panel says why. + +The conversation shows: + +- Your messages, each with its time, how it was sent, and its delivery label. +- The replies of the agent, which appear while the agent writes them. To copy a reply, click the copy button under it. +- **Used N tools** for the tools the agent called in a turn. Click it to see each tool and what it worked on. A failed call is marked, and the list opens by itself when a call failed. +- A line when a turn did not end well: **This turn failed.**, **This turn was interrupted.**, or **It is not known how this turn ended.** + +While the agent works, the conversation shows **Agent is working…**. The page refreshes by itself every 5 seconds while the agent is starting, working, or stopping. + +## Send a message + +Type in the field under the conversation. A message can be up to 20,000 characters. What happens depends on the state of the agent: + +| Agent state | What you can do | +|---|---| +| **Idle** | Press **Enter** or click **Send**. The message starts a new turn at once. | +| **Working** | Click **Queue** or press **Enter** to run the message as its own turn after the running one. Click **Steer now** or press **Ctrl+Enter** (**⌘+Enter** on macOS) to hand it to the running turn at its next step. | +| **Pending**, **Preparing** | Wait. The agent takes messages once it is **Working** or **Idle**. | +| **Stopping**, **Ended**, **Failed** | The agent no longer takes messages. | + +Press **Shift+Enter** for a new line. + +Use **Steer now** to correct the agent while it works, for example "Do not touch the migrations." Use **Queue** for the next piece of work. A queued message runs as a separate turn with its own time limit. + +### Delivery labels + +Each message that you send shows a label: + +| Label | Meaning | +|---|---| +| **Queued** | Accepted, waiting for its turn | +| **Sending** | Being handed to the agent | +| **Delivered** | The agent has it | +| **unknown — checking** | Fluence is checking whether the agent got it. Wait. Do not send it again, or the agent can get it twice. | +| **Failed** | It did not run. The reason is shown next to it. | +| **Cancelled** | It never ran. It was still waiting when the agent was stopped or ended. | + +If a running turn is cut short, a message that you steered into it and that did not run shows **Failed**. A queued message is kept and runs as the next turn. + +If the console cannot confirm that a message was sent, it says so. Wait for the conversation to refresh. The message appears there if it was sent. + +## Interrupt a turn + +To stop what the agent is doing and keep the agent, interrupt the turn: + +1. On the agent page, open the menu in the **Details** panel. +2. Click **Interrupt agent**. The menu shows it only while the agent is **Working**. + +The running turn stops, and the agent becomes **Idle**. It keeps its machine and its conversation, and it takes your next message. + +## Stop an agent + +1. Open the menu in the **Details** panel of the agent page, or the menu on the agent's row in the list. +2. Click **Stop**, and confirm with **Stop agent**. + +The agent stops, and its machine is released. Messages that have not run yet will not run. You cannot start a stopped agent again. Anything the agent did not push to the repository is gone with the machine. + +An idle agent also stops by itself after the idle time of its preset. See [Idle stop](./overview.md#idle-stop). + +## Launch a copy + +To start a new agent with the settings of an existing one, open the menu of the agent and click **Launch a copy**. The launch form opens with the name, task, model, and repository of that agent, and with its preset if the preset still exists. Change what you need, and click **Launch agent**. + +The copy is a new agent on a new machine. It does not continue the conversation of the first one. diff --git a/docs/build/cloud_agents/overview.md b/docs/build/cloud_agents/overview.md new file mode 100644 index 0000000..cbe06f8 --- /dev/null +++ b/docs/build/cloud_agents/overview.md @@ -0,0 +1,85 @@ +--- +description: "Cloud agents concepts: a coding agent on its own machine in your Fluence account, what it gets at launch, turns and messages, agent states, idle stop, and pricing." +--- + +# Cloud agents concepts + +A cloud agent is a coding agent that runs on its own machine in your Fluence account. You give it a task, a model, and a repository. The agent clones the repository, works on the task, and answers in a conversation on its page. If its GitHub token has write access, it can push branches and open pull requests. + +You work with cloud agents in the Fluence Console under **Cloud agents**. To launch one, see [Launch your first cloud agent](./get_started.md). + +## How a cloud agent works + +Each launch creates one agent on one machine: + +1. You launch an agent from a preset. The preset gives the machine size and the extensions. You give the task, the model, and the repository. +2. Fluence creates a machine in your account and prepares it: the repository, the secrets, the AI providers, and the extensions. +3. The agent starts on the task right after launch. Its replies and the tools it used appear in the conversation. +4. You send more messages while the agent works or after it finishes a turn. +5. The agent ends when you stop it, or when it stays idle for the idle time of its preset. Its machine is released. + +The agent runs [OpenCode](https://opencode.ai). The models it can use come from the AI providers that you connect. + +## What an agent gets at launch + +You set up three things once, and every new agent gets them: + +| Console page | What it holds | +|---|---| +| **AI providers** | How agents reach models: a ChatGPT subscription, API keys of known providers, or your own endpoint. See [Connect an AI provider](./ai_providers.md). | +| **Secrets** | The GitHub token that agents clone repositories with, and named secrets for MCP servers and plugins. See [Add a GitHub token and secrets](./secrets.md). | +| **Extensions** | MCP servers, OpenCode plugins, and skills repositories. See [Add MCP servers, plugins, and skills](./extensions.md). | + +An agent takes its AI providers, secrets, and extensions at launch. Changes on these pages apply to new launches. Running agents keep what they started with. To give a running agent a change, stop it and launch a new one. + +## Presets + +A preset says what an agent runs with: a default model, a machine, and the extensions it includes. A preset can also carry a default repository and task. + +Every account has the **Default** preset. Agents launch from it when you choose no other. You need more presets only when you want different machines, models, or extensions for different work. See [Create and edit presets](./presets.md). + +## Turns and messages + +The agent works in turns. The task you launch with starts the first turn. Each later message starts a new turn or joins the running one: + +- To an idle agent, a message starts a new turn at once. +- To a working agent, you choose. **Steer now** hands the message to the running turn at its next step. **Queue** runs the message as its own turn after the running one. + +A turn has a time limit. A turn launched from the console can run for up to 6 hours. A turn that produces no output for too long is also stopped. When a limit stops a turn, the agent stays and takes the next message. + +See [Work with a cloud agent](./manage_agents.md). + +## Agent states + +| State | Meaning | +|---|---| +| **Pending** | The launch is accepted, and Fluence is finding or creating the machine | +| **Preparing** | The machine is ready, and the repository and the agent are being prepared on it | +| **Working** | A turn is running | +| **Idle** | The agent has no turn running and waits for a message | +| **Stopping** | The agent is stopping, and its machine is being released | +| **Ended** | The agent was stopped, or it stayed idle for the idle time | +| **Failed** | The agent could not start or lost its machine. Its page says why. | + +**Ended** and **Failed** are final. A final agent stays in your list with its conversation, but takes no more messages. + +While an agent is **Pending** or **Preparing**, its page shows the current step next to the state: **Accepted**, **Finding a machine**, **Raising the machine**, **Machine ready**, **Connecting to the machine**, or **Handing over the task**. + +## Idle stop + +A machine does not run forever. When an agent stays idle for the idle time of its preset, the machine shuts down and the agent is stopped. Its state becomes **Ended**. + +You set the idle time in whole hours in the **Machine** block of a preset, in the **Idle hours** field. An empty field takes the default. + +To continue the work of an ended agent, launch a copy of it. The copy starts on a new machine with a new conversation. + +## Pricing + +A cloud agent has two costs: + +- The machine. You pay for it by the hour while it runs, at the hourly price of its size. The console shows the price in the **Machine** step and the **Review** panel of the launch form, in the agent list, and on the agent page. The **Review** panel also shows what a month costs if the machine runs nonstop. +- The model. Model use is billed by your AI provider, not by the machine price. + +You pay for the machine only while it runs. The idle stop limits what a forgotten agent can cost. Sizes and prices depend on the cluster of the preset. + +The machine is billed to your Fluence account. See [Payment and balance management](../balance.md). diff --git a/docs/build/cloud_agents/presets.md b/docs/build/cloud_agents/presets.md new file mode 100644 index 0000000..78c5a91 --- /dev/null +++ b/docs/build/cloud_agents/presets.md @@ -0,0 +1,97 @@ +--- +description: Create and edit cloud agent presets in the Fluence Console. A preset holds the default model, the machine size, cluster and idle time, the extensions, and launch defaults. +--- + +# Create and edit presets + +A preset says what an agent runs with: a model, a machine, and the extensions it includes. A preset can also carry a default repository and task. Every launch goes from a preset. + +Your account has the **Default** preset. Agents launch from it when you choose no other, and it cannot be renamed or deleted. Create more presets when different work needs a different machine, model, or set of extensions, for example a large machine for one repository. + +You manage presets on the **Cloud agents** > **Presets** page. + +## What a preset holds + +| Block | Fields | If you leave it empty | +|---|---|---| +| **Model** | **Default model** | Each launch names a model | +| **Machine** | **Cluster**, **VM size**, **Idle hours** | The default cluster, the default size, and the default idle time | +| **Extensions** | The MCP servers, plugins, and skills repositories that the preset includes | The agent gets no extensions | +| **Launch defaults** | **Repository URL**, **Task** | The launch form asks for them | +| **Advanced** | **Environment**, **AI profile** | The secrets and the AI providers of the account | + +An agent takes a copy of its preset at launch. If you edit or delete a preset later, agents already launched from it are not changed. + +## Preset list + +The list shows each preset with its **Model**, **Secrets**, **Machine**, and **Extensions**: + +- **Model** shows the default model, or **Named at launch**. +- **Secrets** shows **Account** when the preset uses the secrets of the **Secrets** page. A badge such as **1 missing** shows how many secrets the preset needs and does not have. +- **Machine** shows the size and its hourly price. + +To launch an agent from a preset, click **Launch** on its row. + +## Create a preset + +1. Open **Cloud agents** > **Presets** and click **New preset**. +2. Enter a **Name**: up to 64 characters, different from the names of your other presets. +3. Click **Create preset**. + +The new preset starts as a copy of the default preset. After that it lives on its own. Changing the default preset later does not change it. + +The console opens the page of the new preset, where you edit its blocks. + +## Edit a preset + +Open the preset from the list. The page shows each block with its current values. To change a block, click **Edit** next to its title, change the fields, and click **Save**. + +### Choose the default model + +In **Model**, choose the **Default model** from the models of your AI providers. The launch form opens with this model selected. To make each launch name a model, choose **None — each launch names one**. + +### Choose the machine + +In **Machine**, set where and on what the agent runs: + +- **Cluster**: where the machine is created. Sizes and prices depend on it. **Provider default** leaves the choice to Fluence. +- **VM size**: the size of the machine. Each size shows its vCPU, RAM, disk, and hourly price. **Default** takes the default size of the cluster. The console shows the price that you pay while the machine runs. +- **Idle hours**: whole hours without work before the machine shuts down and an idle agent on it is stopped. Enter 1 or more. An empty field takes the default. + +When you change the cluster, the console keeps the size if the new cluster also sells it. Otherwise it falls back to the default size of that cluster. + +The launch form does not ask for a machine. To launch on another machine, change it in the preset, or launch from another preset. + +### Choose the extensions of a preset + +In **Extensions**, select the MCP servers, plugins, and skills repositories that the preset includes, and click **Save**. The list shows the extensions of your account. To add or change an extension itself, click **Manage extensions**. See [Add MCP servers, plugins, and skills](./extensions.md). + +If a selected extension names a secret that the preset does not have, the console marks it **Missing secret**. Add the secret before you launch. A launch from a preset with a missing secret is refused. + +### Set launch defaults + +In **Launch defaults**, optionally enter a **Repository URL** and a **Task**. The launch form opens with them filled in, and you can still change them for each launch. + +The repository URL is an `https://` address with a path and no credentials in it, for example `https://github.com/owner/repo`. + +### Rename or delete a preset + +To rename a preset, click **Rename**, enter the new name, and click **Save**. + +To delete a preset, click **Delete** and confirm with **Delete preset**. Agents already launched from it keep running. Its secrets stay as they are. + +## Use separate secrets or AI providers for a preset + +Most presets use the secrets and the AI providers of the account, and you can skip this section. The **Advanced** block is for two cases: a preset that needs a second GitHub token, or a preset that needs its own set of AI providers. + +- **Environment** is a set of secrets: one GitHub token and named secrets. The secrets of the **Secrets** page are the environment of the account. To create another one, click **Manage environments**, then **New environment**, and give it a name. Then choose it in **Environment**. To edit its secrets, click **Manage secrets**. +- **AI profile** is a set of AI providers: subscriptions, keys, and custom endpoints. The providers of the **AI providers** page are the default profile. **Account default** uses whichever profile is the default when an agent starts. To create or clone a profile, click **Manage AI profiles**. + +The **Advanced** block also lists the secrets that the preset needs, each marked **Set** or **Missing**. + +Keep these in mind: + +- The default model of a preset must be a model that its AI profile offers. If you choose a profile that does not offer the stored model, the console clears the model and asks you to choose another one in **Model**. +- The MCP servers and plugins of a preset take their secrets from the environment of the preset. A secret of the same name in another environment is a different secret. +- Saving the secrets of an environment makes a new version. Running agents keep the version they started with. New agents get the latest. +- Deleting an environment destroys its secrets. A profile cannot be deleted while it is the default or holds a subscription. diff --git a/docs/build/cloud_agents/secrets.md b/docs/build/cloud_agents/secrets.md new file mode 100644 index 0000000..158c902 --- /dev/null +++ b/docs/build/cloud_agents/secrets.md @@ -0,0 +1,88 @@ +--- +description: Add the GitHub token that cloud agents clone repositories with, and named secrets for MCP servers and plugins. How secrets reach the agent as environment variables. +--- + +# Add a GitHub token and secrets + +The **Cloud agents** > **Secrets** page holds what every new agent gets: one GitHub token, and any number of named secrets for MCP servers and plugins. + +Fluence stores a secret value when you save it and never shows it again. The console shows only names, dates, and what uses each secret. To change a value, save a new one. + +## Add the GitHub token + +Agents clone repositories with the GitHub token. A launch needs it: without a token, the launch form shows **Add a GitHub token to launch.** + +1. Open **Cloud agents** > **Secrets**. +2. In the **GitHub token** card, click **Connect**. If a token is already stored, the button reads **Change**. +3. Paste the token and click **Save token**. + +Give the token access to every repository you hand an agent: + +- Read access lets the agent clone. +- Write access lets the agent push and open pull requests. + +You can use either kind of GitHub token: + +| Token kind | Permissions | +|---|---| +| Fine-grained | **Contents**, **Pull requests**, **Actions**, and **Issues**, each with read and write access. **Contents** with read-only access is enough to only read. | +| Classic | The `repo` scope. Add `workflow` to let the agent change GitHub Actions workflows. | + +If an organization blocks fine-grained tokens or holds them for approval, use a classic token. + +When you save a token, Fluence asks GitHub about it. The card then shows the result: + +- **Token checked**: GitHub accepted the token. The card shows the GitHub account that owns it, the date of the check, and the expiry date if the token has one. +- **Token not checked**: the token is saved, but GitHub could not be asked. The card gives the reason. + +The check confirms that the token is valid. It does not confirm access to a specific repository. That shows only at launch, when the agent clones. + +On the machine, the agent gets the token in the `GH_TOKEN` environment variable. + +## Add a named secret + +A named secret is a value with a name, for example `npm_token`. MCP servers and plugins use a secret by its name. + +1. Open **Cloud agents** > **Secrets**. +2. In the **Secrets** card, click **Add a secret**. +3. Enter the name. Use up to 64 lowercase letters, digits, and underscores. +4. Enter the value. +5. Click **Add secret**. + +Each secret row shows what uses it, for example **Used by 1 MCP server and 2 plugins**, or **Not used yet**. + +To store a new value, click **Change** on the row, enter the value, and click **Save secret**. You cannot rename a secret. Add a new one instead. + +To remove a secret, click **Change**, then **Remove**, and confirm with **Remove secret**. New launches no longer get it. Before you remove a secret that is in use, take it out of the MCP servers and plugins that name it. A launch from a preset that names a missing secret is refused. + +## How secrets reach the agent + +The console never shows a secret value, and an MCP server or plugin record holds only the name of a secret. + +On the machine, each named secret is an environment variable of the agent. The variable is the secret name in uppercase: + +| Secret name | Environment variable | +|---|---| +| `npm_token` | `NPM_TOKEN` | +| `linear_api_key` | `LINEAR_API_KEY` | + +A secret also reaches the agent in these ways: + +- An MCP server sends the secret that you choose for it in a request header. See [MCP servers](./extensions.md#mcp-servers). +- A plugin gets a secret under a variable name that you choose, as a secret variable. See [OpenCode plugins](./extensions.md#opencode-plugins). + +Some names cannot be used, because their variable belongs to the machine or to the agent itself. The console refuses a secret whose variable would be one of these: + +- `GH_TOKEN` and any variable that starts with `GIT_`. +- Variables of the agent process, for example `PATH`, `HOME`, `NODE_OPTIONS`, `HTTPS_PROXY`, and any variable that starts with `OPENCODE_`, `NPM_CONFIG_`, or `XDG_`. +- `OPENAI_API_KEY`, which an OpenAI key on the **AI providers** page fills. + +A name that starts with a digit is also refused, because it makes no valid variable. Choose another name, for example `npm_registry_token` instead of `npm_config_token`. + +:::warning +Anything the agent can read, it can also print or send. Give an agent only the secrets that its task needs, and prefer tokens with narrow permissions and an expiry date. +::: + +## Changes and running agents + +An agent takes its secrets at launch. A new or changed secret applies to new launches. Running agents keep what they started with. To give a running agent a new value, stop it and launch a new one. diff --git a/docs/build/cloud_agents/troubleshooting.md b/docs/build/cloud_agents/troubleshooting.md new file mode 100644 index 0000000..50392dc --- /dev/null +++ b/docs/build/cloud_agents/troubleshooting.md @@ -0,0 +1,143 @@ +--- +description: Limits of cloud agents in the Fluence Console, the refusals and failures you can meet at launch and during work, what each one means, and how to fix it. +--- + +# Troubleshoot cloud agents + +This page lists the limits of cloud agents and the messages that the Fluence Console shows when something goes wrong, with what to do about each. + +## Limits + +| What | Limit | +|---|---| +| Agent name | 128 bytes, on one line | +| Task and each message | 20,000 characters | +| Repository | One per agent, required, an `https://` address without credentials | +| Time per turn | 6 hours for a turn launched from the console | +| Idle time | Whole hours, 1 or more, set in the preset. An empty field takes the default. | +| Agents alive at once | Limited per account. A launch over the limit is refused. | +| Preset name | 64 characters, unique among your presets | +| Secret name | 64 lowercase letters, digits, and underscores | +| Custom provider name | 48 lowercase letters, digits, and hyphens | +| Plugins in one preset | 100 | + +For the limits of plugin variables, see [Plugin order and limits](./extensions.md#plugin-order-and-limits). + +## The section does not open + +| Message | What to do | +|---|---| +| **Connecting Cloud agents…** | Wait. The console connects the section to your account by itself. | +| **Could not connect Cloud agents** | Click **Retry**. | +| **Your role cannot use Cloud agents** | Your role lacks the access that the message names. Ask the account owner for a role that grants it. | + +## The launch is closed or refused + +The line under **Launch agent** says why the button is disabled: + +| Message | What to do | +|---|---| +| **Connect an AI provider to launch.** | Connect a provider on the **AI providers** page. See [Connect an AI provider](./ai_providers.md). | +| **Add a GitHub token to launch.** | Add a token on the **Secrets** page. See [Add the GitHub token](./secrets.md#add-the-github-token). | +| **Reload the page to launch.** | The console could not read your setup. Reload the page. | + +The form checks its fields when you click **Launch agent**: + +| Message | What to do | +|---|---| +| **Describe the task** | Fill in **Task** | +| **Choose a model** | Choose or enter a model | +| **Enter a repository URL** | Fill in **Repository URL**. A launch needs a repository. | +| **Enter an https:// repository URL without credentials** | Use an address such as `https://github.com/owner/repository`. Do not put a user name or a token into the address. SSH addresses are not accepted. | +| **Use a shorter name**, **Use a name without line breaks** | Shorten the agent name, or remove line breaks from it | +| **This form expired. Reload the page.** | Reload the page and launch again | + +A launch can also be refused after you click **Launch agent**. The console shows the reason: + +| Reason | What to do | +|---|---| +| A secret that an MCP server or a plugin names is missing | Add the secret on the **Secrets** page, or change the extension. The preset page marks it **Missing secret**. | +| The model is not available | Choose a model from the list. If you typed it, check the `provider/model` form and that the provider is connected. | +| The ChatGPT subscription is not active | On the **AI providers** page, click **Sign in again**, or select another subscription | +| The limit of agents is reached | Stop an agent that you no longer need, then launch again | +| The preset, its secrets, or its AI providers no longer exist | Reload the page and choose another preset, or fix the preset on its page | + +If the console shows **Launch not confirmed**, it could not learn whether the agent was launched. Check the agent list before you launch again. + +## The agent failed + +A failed agent shows the reason in the **Details** panel of its page. + +| Message | What it means and what to do | +|---|---| +| **The agent's machine could not be created.** | Fluence could not create the machine. Launch again. If it repeats, choose another size or cluster in the preset. | +| **The repository could not be prepared on the agent's machine.** | The agent could not clone the repository. Check the address and that the GitHub token has access to it, then launch again. | +| **The agent's machine does not offer the model the agent was launched with.** | The model is not served by your providers. Launch again with a model from the list. | +| **The AI profile's subscription sign-in no longer works. Sign in again.** | Sign in to ChatGPT again on the **AI providers** page, then launch again | +| **The models of the AI profile's subscription could not be read.** | Check the subscription on the **AI providers** page, then launch again | +| **The agent's machine is gone.**, **The agent's machine could not be found.**, **The agent's machine is being shut down.** | The machine ended under the agent. Launch a copy. | +| **The agent's machine refused to start the agent.**, **The agent could not be confirmed as started on its machine.**, **The agent's session on its machine was lost.** | The agent did not start or was lost on the machine. Launch a copy. | +| **The agent stopped because of an error.** | An error without a known reason. Launch a copy. If it repeats, contact support. | + +To launch again with the same settings, open the menu and click **Launch a copy**. + +## A turn went wrong + +A turn can go wrong while the agent itself stays alive. The agent becomes **Idle** and takes your next message. The conversation shows **This turn failed.**, **This turn was interrupted.**, or **It is not known how this turn ended.** The **Last turn** column of the agent list shows a short reason: + +| Reason | What it means | What to do | +|---|---|---| +| `interrupted` | You interrupted the turn | Send the next message | +| `turn_budget_exceeded` | The turn ran out of its time limit | Send a message to continue. Split large work into smaller tasks. | +| `turn_silence_exceeded` | The turn produced no output for too long and was stopped | Send a message to continue. If it repeats, try another model. | +| `unknown` | The reason could not be told | Send the message again | +| Another reason | An error of the model or the provider, for example a rejected key, a rate limit, or an exhausted quota | Check the key, the plan, and the limits at your AI provider. Then send the message again, or launch a new agent with another model. | + +## An extension does not work + +| Symptom | What to check | +|---|---| +| The preset shows **Missing secret** | The extension names a secret that the preset does not have. Add it on the **Secrets** page under the same name. | +| Calls to an MCP server fail with an authorization error | The header. Most servers take **Authorization: Bearer \**. Some take **X-API-KEY: \**. Also check that the secret value is the key alone, without `Bearer`. | +| The agent has no tools of an MCP server | The URL of the endpoint, and that the server is reachable from the internet. Also check that the preset of the agent includes the server. | +| A change to an extension or a secret has no effect | A running agent keeps what it started with. Stop it and launch a new one. | +| The console refuses a plugin | The package format, a reserved or repeated variable name, or two plugins that set one variable to different values. See [OpenCode plugins](./extensions.md#opencode-plugins). | +| The console refuses a secret name | The name makes a reserved environment variable. See [How secrets reach the agent](./secrets.md#how-secrets-reach-the-agent). | + +## Questions + +### Can I launch an agent without a repository? + +No. A launch needs a repository, and the agent clones it with the GitHub token. + +### Can the agent open a pull request? + +Yes, if the GitHub token has write access to the repository. With read access only, the agent can clone and read, but it cannot push. + +### Can I see the value of a secret or a key that I saved? + +No. Fluence stores the value and never shows it again. Save a new value if you lost the old one. + +### Can I change the model, the machine, or the secrets of a running agent? + +No. An agent keeps what it was launched with. Stop it and launch a copy with the new settings. + +### Can I restart an ended agent? + +No. **Ended** and **Failed** are final. Click **Launch a copy** to start a new agent with the same task, model, and repository. + +### Can I rename or delete an agent? + +No. The name is set at launch. Ended and failed agents stay in the list and are hidden by default. + +### Why did my agent end by itself? + +It stayed idle for the idle time of its preset. To keep idle agents longer, raise **Idle hours** in the **Machine** block of the preset. A longer idle time means that you pay for the machine longer. + +### Do I pay while the agent is idle? + +Yes. You pay for the machine while it runs, also when the agent waits for a message. The machine is released when the agent stops or ends. + +### Does Fluence charge for the model? + +The machine price does not include model use. Your AI provider bills it under your key or your subscription. diff --git a/docs/build/llms_txt_include_head.md b/docs/build/llms_txt_include_head.md index 613b9c8..4bbd91c 100644 --- a/docs/build/llms_txt_include_head.md +++ b/docs/build/llms_txt_include_head.md @@ -2,6 +2,6 @@ > Guides for renting GPU and CPU compute on Fluence Cloud: the Fluence Console at console.fluence.ai, the Fluence API at api.fluence.dev, accounts, balance, and billing. -If you are new to Fluence Cloud, start with the [Overview](https://fluence.dev/docs/build/overview.md). It lists what you can rent and the ways to work with Fluence Cloud. The CPU Cloud and GPU Cloud sections each start with a concepts page about resources, statuses, and billing. For code, start with the [API overview](https://fluence.dev/docs/build/api/overview.md). New integrations use the Public v3 API. +If you are new to Fluence Cloud, start with the [Overview](https://fluence.dev/docs/build/overview.md). It lists what you can rent and the ways to work with Fluence Cloud. The CPU Cloud and GPU Cloud sections each start with a concepts page about resources, statuses, and billing. The Cloud Agents section covers coding agents that run on their own machines in your account, starting with [Cloud agents concepts](https://fluence.dev/docs/build/cloud_agents/overview.md). For code, start with the [API overview](https://fluence.dev/docs/build/api/overview.md). New integrations use the Public v3 API. AI agents can fund an account and sign in without a human. See [Pay with x402](https://fluence.dev/docs/build/api/x402.md). To connect an MCP client, see [Connect an AI client through MCP](https://fluence.dev/docs/build_with_ai/mcp.md). diff --git a/docs/build/overview.md b/docs/build/overview.md index b187ff4..54f5756 100644 --- a/docs/build/overview.md +++ b/docs/build/overview.md @@ -27,6 +27,7 @@ The sidebar of the Fluence Console has these sections: |---|---| | **Public cloud** | CPU virtual machines on the **Compute** page, disks on **Storage**, and public IP addresses, VPCs, and security groups on **Network** | | **GPU cloud** | Renting GPU containers, VMs, and bare metal servers on the **Marketplace** page, and managing them on the **Instances** page | +| **Cloud agents** | Coding agents that run on machines in your account: the **Agents** list, **Presets**, **AI providers**, **Secrets**, and **Extensions**. See [Cloud agents concepts](./cloud_agents/overview.md). | | **Billing** | Your balance, top-ups, promo codes, and usage. The balance in the page header also links here. | | **Settings** | Your profile, API keys, SSH keys, and the **MCP** page with configurations for AI clients | | **Support** | Opens an email to support@fluence.ai | diff --git a/sidebars.js b/sidebars.js index c15302d..8495ea6 100644 --- a/sidebars.js +++ b/sidebars.js @@ -29,6 +29,20 @@ const sidebars = { "build/gpu_cloud/manage_instances", ], }, + { + type: "category", + label: "Cloud Agents", + items: [ + "build/cloud_agents/overview", + "build/cloud_agents/get_started", + "build/cloud_agents/ai_providers", + "build/cloud_agents/secrets", + "build/cloud_agents/extensions", + "build/cloud_agents/presets", + "build/cloud_agents/manage_agents", + "build/cloud_agents/troubleshooting", + ], + }, { type: "category", label: "API", From dd8f77de1a659f0aa9ff57c910834e9f9a96c697 Mon Sep 17 00:00:00 2001 From: Valery Antopol Date: Wed, 18 Nov 2026 21:58:46 +0400 Subject: [PATCH 2/3] docs: tighten the Cloud Agents pages - Overview: open with what cloud agents give you (managed agent, isolated machine, reproducible setup, control from the console, MCP, or the API). Describe the life of an agent in words instead of a state table, and drop the preset references. - Secrets: say that values are stored encrypted and deleted on removal, and that a fine-grained GitHub token does not reach organization repositories by default. - Remove the role message, the unconfirmed launch and message notes, the model text field, the tab list, and the description of the conversation contents. --- docs/build/cloud_agents/ai_providers.md | 6 +-- docs/build/cloud_agents/get_started.md | 6 +-- docs/build/cloud_agents/manage_agents.md | 13 +----- docs/build/cloud_agents/overview.md | 53 ++++++++-------------- docs/build/cloud_agents/secrets.md | 4 +- docs/build/cloud_agents/troubleshooting.md | 7 +-- 6 files changed, 30 insertions(+), 59 deletions(-) diff --git a/docs/build/cloud_agents/ai_providers.md b/docs/build/cloud_agents/ai_providers.md index 8bc3a2d..710e893 100644 --- a/docs/build/cloud_agents/ai_providers.md +++ b/docs/build/cloud_agents/ai_providers.md @@ -44,7 +44,7 @@ To remove a subscription, click **Forget** and confirm with **Forget subscriptio ## Add an API key 1. Open **Cloud agents** > **AI providers** and select **API key**. -2. Click **Connect** next to **Fluence inference**, **OpenAI**, **Z.ai**, or **OpenRouter**. +2. Click **Connect** next to the provider. 3. Paste the key. The link under the field opens the page where the provider issues keys. 4. Click **Save key**. The row shows **Ready**. @@ -72,9 +72,7 @@ To change the address, the protocol, or the key, click **Change** on the provide ## How models are named -A model has the form `provider/model`. The launch form lists the models of all connected providers, each with its provider. You normally pick a model from the list. - -When the console cannot load the list, or the connected providers list no models, the **Model** field becomes a text field. Enter the model as `provider/model`. +A model has the form `provider/model`. The launch form lists the models of all connected providers, each with its provider. You pick a model from the list. ## Changes and running agents diff --git a/docs/build/cloud_agents/get_started.md b/docs/build/cloud_agents/get_started.md index e804c20..ba66bdd 100644 --- a/docs/build/cloud_agents/get_started.md +++ b/docs/build/cloud_agents/get_started.md @@ -16,9 +16,7 @@ Before you start, you need: In the sidebar of the Fluence Console, open **Cloud agents**. The first time, the console connects the section to your account by itself and shows **Connecting Cloud agents…**. There is nothing to click. -The section has five tabs: **Agents**, **Presets**, **AI providers**, **Secrets**, and **Extensions**. Before your first agent, the **Agents** tab shows **Launch your first agent** with the setup steps. - -If the console shows **Your role cannot use Cloud agents**, your role in the account lacks the access the message names. Ask the account owner for a role that grants it. +Before your first agent, the **Agents** tab shows **Launch your first agent** with the setup steps. ## Connect an AI provider @@ -52,8 +50,6 @@ The console opens the agent page. The agent starts on the task right after launc If **Launch agent** is disabled, the line under it says what is missing: **Connect an AI provider to launch.** or **Add a GitHub token to launch.** -If the console cannot confirm the launch, it opens the agent list. Check the list before you launch again. Otherwise you can end up with two agents. - ## Follow the work On the agent page, the state goes from **Pending** through **Preparing** to **Working**. Creating the machine takes a few minutes. The step next to the state shows the progress, for example **Raising the machine**. diff --git a/docs/build/cloud_agents/manage_agents.md b/docs/build/cloud_agents/manage_agents.md index 4b9327b..044d213 100644 --- a/docs/build/cloud_agents/manage_agents.md +++ b/docs/build/cloud_agents/manage_agents.md @@ -4,7 +4,7 @@ description: Launch cloud agents, read their conversation, send messages, steer # Work with a cloud agent -You launch and manage cloud agents in the Fluence Console under **Cloud agents** > **Agents**. For states, turns, and pricing, see [Cloud agents concepts](./overview.md). +You launch and manage cloud agents in the Fluence Console under **Cloud agents** > **Agents**. For turns, idle stop, and pricing, see [Cloud agents concepts](./overview.md). ## Launch an agent @@ -47,14 +47,7 @@ Click an agent to open its page. It has the conversation on the left and the **D The **Details** panel shows the **Status**, **Name**, **Model**, **Repository**, **Machine**, the number of **Extensions** the agent was launched with, and the **Price** of the machine per hour. If the agent failed, the panel says why. -The conversation shows: - -- Your messages, each with its time, how it was sent, and its delivery label. -- The replies of the agent, which appear while the agent writes them. To copy a reply, click the copy button under it. -- **Used N tools** for the tools the agent called in a turn. Click it to see each tool and what it worked on. A failed call is marked, and the list opens by itself when a call failed. -- A line when a turn did not end well: **This turn failed.**, **This turn was interrupted.**, or **It is not known how this turn ended.** - -While the agent works, the conversation shows **Agent is working…**. The page refreshes by itself every 5 seconds while the agent is starting, working, or stopping. +The page refreshes by itself every 5 seconds while the agent is starting, working, or stopping. ## Send a message @@ -86,8 +79,6 @@ Each message that you send shows a label: If a running turn is cut short, a message that you steered into it and that did not run shows **Failed**. A queued message is kept and runs as the next turn. -If the console cannot confirm that a message was sent, it says so. Wait for the conversation to refresh. The message appears there if it was sent. - ## Interrupt a turn To stop what the agent is doing and keep the agent, interrupt the turn: diff --git a/docs/build/cloud_agents/overview.md b/docs/build/cloud_agents/overview.md index cbe06f8..5eea056 100644 --- a/docs/build/cloud_agents/overview.md +++ b/docs/build/cloud_agents/overview.md @@ -1,22 +1,33 @@ --- -description: "Cloud agents concepts: a coding agent on its own machine in your Fluence account, what it gets at launch, turns and messages, agent states, idle stop, and pricing." +description: "Cloud agents concepts: managed coding agents on isolated machines in your Fluence account, controlled from the console, MCP, or the API. What an agent gets at launch, turns and messages, idle stop, and pricing." --- # Cloud agents concepts -A cloud agent is a coding agent that runs on its own machine in your Fluence account. You give it a task, a model, and a repository. The agent clones the repository, works on the task, and answers in a conversation on its page. If its GitHub token has write access, it can push branches and open pull requests. +Cloud agents are managed coding agents. Each agent runs on its own isolated virtual machine in your Fluence account. You give it a task, a model, and a repository. Fluence creates the machine, sets up the agent on it, and releases the machine when the work is done. -You work with cloud agents in the Fluence Console under **Cloud agents**. To launch one, see [Launch your first cloud agent](./get_started.md). +The agent clones the repository, works on the task, and answers in a conversation on its page. If its GitHub token has write access, it can push branches and open pull requests. + +With cloud agents you get: + +- A managed agent. You do not rent or configure a server. You launch an agent, and you pay for its machine only while it runs. +- An isolated machine. Each agent has its own virtual machine, with no SSH access and no static public IP address. +- A reproducible setup. You set up AI providers, secrets, MCP servers, plugins, and skills once. Every new agent starts with the same setup, so you do not configure each machine by hand. +- Control from the console, MCP, or the API. You launch agents, send them messages, and stop them in the Fluence Console, through [Fluence MCP](../../build_with_ai/mcp.md), or through the API. + +To launch your first agent in the Fluence Console, see [Launch your first cloud agent](./get_started.md). ## How a cloud agent works Each launch creates one agent on one machine: -1. You launch an agent from a preset. The preset gives the machine size and the extensions. You give the task, the model, and the repository. -2. Fluence creates a machine in your account and prepares it: the repository, the secrets, the AI providers, and the extensions. +1. You launch an agent with a task, a model, and a repository. +2. Fluence creates a machine of the selected size in your account and prepares it: the repository, the secrets, the AI providers, and the extensions. 3. The agent starts on the task right after launch. Its replies and the tools it used appear in the conversation. 4. You send more messages while the agent works or after it finishes a turn. -5. The agent ends when you stop it, or when it stays idle for the idle time of its preset. Its machine is released. +5. The agent runs until you stop it, or until it stays idle for the selected idle time. Then its machine is released. + +A stopped agent stays in your list with its conversation, but takes no more messages. The agent runs [OpenCode](https://opencode.ai). The models it can use come from the AI providers that you connect. @@ -32,12 +43,6 @@ You set up three things once, and every new agent gets them: An agent takes its AI providers, secrets, and extensions at launch. Changes on these pages apply to new launches. Running agents keep what they started with. To give a running agent a change, stop it and launch a new one. -## Presets - -A preset says what an agent runs with: a default model, a machine, and the extensions it includes. A preset can also carry a default repository and task. - -Every account has the **Default** preset. Agents launch from it when you choose no other. You need more presets only when you want different machines, models, or extensions for different work. See [Create and edit presets](./presets.md). - ## Turns and messages The agent works in turns. The task you launch with starts the first turn. Each later message starts a new turn or joins the running one: @@ -49,29 +54,11 @@ A turn has a time limit. A turn launched from the console can run for up to 6 ho See [Work with a cloud agent](./manage_agents.md). -## Agent states - -| State | Meaning | -|---|---| -| **Pending** | The launch is accepted, and Fluence is finding or creating the machine | -| **Preparing** | The machine is ready, and the repository and the agent are being prepared on it | -| **Working** | A turn is running | -| **Idle** | The agent has no turn running and waits for a message | -| **Stopping** | The agent is stopping, and its machine is being released | -| **Ended** | The agent was stopped, or it stayed idle for the idle time | -| **Failed** | The agent could not start or lost its machine. Its page says why. | - -**Ended** and **Failed** are final. A final agent stays in your list with its conversation, but takes no more messages. - -While an agent is **Pending** or **Preparing**, its page shows the current step next to the state: **Accepted**, **Finding a machine**, **Raising the machine**, **Machine ready**, **Connecting to the machine**, or **Handing over the task**. - ## Idle stop -A machine does not run forever. When an agent stays idle for the idle time of its preset, the machine shuts down and the agent is stopped. Its state becomes **Ended**. - -You set the idle time in whole hours in the **Machine** block of a preset, in the **Idle hours** field. An empty field takes the default. +A machine does not run forever. When an agent stays idle for the selected idle time, the machine shuts down and the agent is stopped. The idle time is a whole number of hours. -To continue the work of an ended agent, launch a copy of it. The copy starts on a new machine with a new conversation. +To continue the work of a stopped agent, launch a copy of it. The copy starts on a new machine with a new conversation. ## Pricing @@ -80,6 +67,6 @@ A cloud agent has two costs: - The machine. You pay for it by the hour while it runs, at the hourly price of its size. The console shows the price in the **Machine** step and the **Review** panel of the launch form, in the agent list, and on the agent page. The **Review** panel also shows what a month costs if the machine runs nonstop. - The model. Model use is billed by your AI provider, not by the machine price. -You pay for the machine only while it runs. The idle stop limits what a forgotten agent can cost. Sizes and prices depend on the cluster of the preset. +You pay for the machine only while it runs. The idle stop limits what a forgotten agent can cost. Sizes and prices depend on the selected cluster. The machine is billed to your Fluence account. See [Payment and balance management](../balance.md). diff --git a/docs/build/cloud_agents/secrets.md b/docs/build/cloud_agents/secrets.md index 158c902..a83ec7c 100644 --- a/docs/build/cloud_agents/secrets.md +++ b/docs/build/cloud_agents/secrets.md @@ -6,7 +6,7 @@ description: Add the GitHub token that cloud agents clone repositories with, and The **Cloud agents** > **Secrets** page holds what every new agent gets: one GitHub token, and any number of named secrets for MCP servers and plugins. -Fluence stores a secret value when you save it and never shows it again. The console shows only names, dates, and what uses each secret. To change a value, save a new one. +Fluence stores every secret value encrypted, the GitHub token and the named secrets alike. After you save a value, the console never shows it again. It shows only names, dates, and what uses each secret. To change a value, save a new one. When you remove a secret, Fluence deletes its stored value. ## Add the GitHub token @@ -28,6 +28,8 @@ You can use either kind of GitHub token: | Fine-grained | **Contents**, **Pull requests**, **Actions**, and **Issues**, each with read and write access. **Contents** with read-only access is enough to only read. | | Classic | The `repo` scope. Add `workflow` to let the agent change GitHub Actions workflows. | +By default, a fine-grained token reaches only the repositories of your own account, not the repositories of an organization. To work on an organization repository, select the organization as the **Resource owner** when you create the token. One token has one resource owner. + If an organization blocks fine-grained tokens or holds them for approval, use a classic token. When you save a token, Fluence asks GitHub about it. The card then shows the result: diff --git a/docs/build/cloud_agents/troubleshooting.md b/docs/build/cloud_agents/troubleshooting.md index 50392dc..280c8e0 100644 --- a/docs/build/cloud_agents/troubleshooting.md +++ b/docs/build/cloud_agents/troubleshooting.md @@ -29,7 +29,6 @@ For the limits of plugin variables, see [Plugin order and limits](./extensions.m |---|---| | **Connecting Cloud agents…** | Wait. The console connects the section to your account by itself. | | **Could not connect Cloud agents** | Click **Retry**. | -| **Your role cannot use Cloud agents** | Your role lacks the access that the message names. Ask the account owner for a role that grants it. | ## The launch is closed or refused @@ -46,7 +45,7 @@ The form checks its fields when you click **Launch agent**: | Message | What to do | |---|---| | **Describe the task** | Fill in **Task** | -| **Choose a model** | Choose or enter a model | +| **Choose a model** | Choose a model in **Model** | | **Enter a repository URL** | Fill in **Repository URL**. A launch needs a repository. | | **Enter an https:// repository URL without credentials** | Use an address such as `https://github.com/owner/repository`. Do not put a user name or a token into the address. SSH addresses are not accepted. | | **Use a shorter name**, **Use a name without line breaks** | Shorten the agent name, or remove line breaks from it | @@ -57,13 +56,11 @@ A launch can also be refused after you click **Launch agent**. The console shows | Reason | What to do | |---|---| | A secret that an MCP server or a plugin names is missing | Add the secret on the **Secrets** page, or change the extension. The preset page marks it **Missing secret**. | -| The model is not available | Choose a model from the list. If you typed it, check the `provider/model` form and that the provider is connected. | +| The model is not available | Choose a model from the list, and check that its provider is connected. | | The ChatGPT subscription is not active | On the **AI providers** page, click **Sign in again**, or select another subscription | | The limit of agents is reached | Stop an agent that you no longer need, then launch again | | The preset, its secrets, or its AI providers no longer exist | Reload the page and choose another preset, or fix the preset on its page | -If the console shows **Launch not confirmed**, it could not learn whether the agent was launched. Check the agent list before you launch again. - ## The agent failed A failed agent shows the reason in the **Details** panel of its page. From 59c69ad08f3d3a32b50fe706fc5f2ca25e6b1634 Mon Sep 17 00:00:00 2001 From: Valery Antopol Date: Thu, 19 Nov 2026 00:14:08 +0400 Subject: [PATCH 3/3] docs: fix review findings in the Cloud Agents pages - Overview: the machine is released on stop or idle, not when the work is done. Say that the machine also runs while the agent is idle, and that unpushed work is gone with the machine. - Get started: repeat the unpushed work warning at the stop step. - Secrets: a fine-grained token needs Workflows, not Actions, to change workflow files. Move the name example next to the reserved prefixes it belongs to. --- docs/build/cloud_agents/get_started.md | 2 +- docs/build/cloud_agents/overview.md | 8 +++++--- docs/build/cloud_agents/secrets.md | 6 ++++-- 3 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/build/cloud_agents/get_started.md b/docs/build/cloud_agents/get_started.md index ba66bdd..3b0db64 100644 --- a/docs/build/cloud_agents/get_started.md +++ b/docs/build/cloud_agents/get_started.md @@ -61,4 +61,4 @@ When the agent works, its replies and tool calls appear in the conversation. Whe 1. On the agent page, open the menu in the **Details** panel and click **Stop**. 2. Click **Stop agent** to confirm. -The agent stops, and its machine is released. An agent that you leave idle is stopped by itself after the idle time of its preset. +The agent stops, and its machine is released. Anything the agent did not push to the repository is gone with the machine. An agent that you leave idle is stopped by itself after the idle time of its preset. diff --git a/docs/build/cloud_agents/overview.md b/docs/build/cloud_agents/overview.md index 5eea056..88aecfc 100644 --- a/docs/build/cloud_agents/overview.md +++ b/docs/build/cloud_agents/overview.md @@ -4,7 +4,7 @@ description: "Cloud agents concepts: managed coding agents on isolated machines # Cloud agents concepts -Cloud agents are managed coding agents. Each agent runs on its own isolated virtual machine in your Fluence account. You give it a task, a model, and a repository. Fluence creates the machine, sets up the agent on it, and releases the machine when the work is done. +Cloud agents are managed coding agents. Each agent runs on its own isolated virtual machine in your Fluence account. You give it a task, a model, and a repository. Fluence creates the machine, sets up the agent on it, and releases the machine when you stop the agent or when it stays idle. The agent clones the repository, works on the task, and answers in a conversation on its page. If its GitHub token has write access, it can push branches and open pull requests. @@ -27,7 +27,7 @@ Each launch creates one agent on one machine: 4. You send more messages while the agent works or after it finishes a turn. 5. The agent runs until you stop it, or until it stays idle for the selected idle time. Then its machine is released. -A stopped agent stays in your list with its conversation, but takes no more messages. +An agent that stopped or failed stays in your list with its conversation, but takes no more messages. The agent runs [OpenCode](https://opencode.ai). The models it can use come from the AI providers that you connect. @@ -58,6 +58,8 @@ See [Work with a cloud agent](./manage_agents.md). A machine does not run forever. When an agent stays idle for the selected idle time, the machine shuts down and the agent is stopped. The idle time is a whole number of hours. +Anything the agent did not push to the repository is gone with the machine. Ask the agent to push its work before you leave it idle. + To continue the work of a stopped agent, launch a copy of it. The copy starts on a new machine with a new conversation. ## Pricing @@ -67,6 +69,6 @@ A cloud agent has two costs: - The machine. You pay for it by the hour while it runs, at the hourly price of its size. The console shows the price in the **Machine** step and the **Review** panel of the launch form, in the agent list, and on the agent page. The **Review** panel also shows what a month costs if the machine runs nonstop. - The model. Model use is billed by your AI provider, not by the machine price. -You pay for the machine only while it runs. The idle stop limits what a forgotten agent can cost. Sizes and prices depend on the selected cluster. +You pay for the machine only while it runs. It also runs while the agent is idle and waits for a message. The idle stop limits what a forgotten agent can cost. Sizes and prices depend on the selected cluster. The machine is billed to your Fluence account. See [Payment and balance management](../balance.md). diff --git a/docs/build/cloud_agents/secrets.md b/docs/build/cloud_agents/secrets.md index a83ec7c..521b1ce 100644 --- a/docs/build/cloud_agents/secrets.md +++ b/docs/build/cloud_agents/secrets.md @@ -25,7 +25,7 @@ You can use either kind of GitHub token: | Token kind | Permissions | |---|---| -| Fine-grained | **Contents**, **Pull requests**, **Actions**, and **Issues**, each with read and write access. **Contents** with read-only access is enough to only read. | +| Fine-grained | **Contents**, **Pull requests**, and **Issues**, each with read and write access. Add **Workflows** to let the agent change GitHub Actions workflows. **Contents** with read-only access is enough to only read. | | Classic | The `repo` scope. Add `workflow` to let the agent change GitHub Actions workflows. | By default, a fine-grained token reaches only the repositories of your own account, not the repositories of an organization. To work on an organization repository, select the organization as the **Resource owner** when you create the token. One token has one resource owner. @@ -79,7 +79,9 @@ Some names cannot be used, because their variable belongs to the machine or to t - Variables of the agent process, for example `PATH`, `HOME`, `NODE_OPTIONS`, `HTTPS_PROXY`, and any variable that starts with `OPENCODE_`, `NPM_CONFIG_`, or `XDG_`. - `OPENAI_API_KEY`, which an OpenAI key on the **AI providers** page fills. -A name that starts with a digit is also refused, because it makes no valid variable. Choose another name, for example `npm_registry_token` instead of `npm_config_token`. +Choose another name, for example `npm_registry_token` instead of `npm_config_token`. + +A name that starts with a digit is also refused, because it makes no valid variable. :::warning Anything the agent can read, it can also print or send. Give an agent only the secrets that its task needs, and prefer tokens with narrow permissions and an expiry date.