# Plans, invoices, and usage
Source: https://docs.tale.dev/cloud/billing

Your Cloud service agreement determines what you pay for hosting, support, seats, and storage. Model usage is a separate consideration: the provider and model you use affect the cost of each AI request.

## Understand the charges

Tale offers the free, self-hosted Community edition and Enterprise for managed Cloud or supported self-hosted deployments. Both include the same product features. Enterprise adds professional services and support; it does not unlock a separate set of product controls.

The [pricing page](https://tale.dev/pricing) is the source for current seat and storage rates, billing periods, and included services. It lists AI usage at provider rates without a markup. Use your agreed quote and service agreement for the terms that apply to your organization.

## Find an invoice or change billing details

Contact the Tale team through your Enterprise support channel for invoices, billing details, seat changes, or questions about a charge. There is no **Settings > Billing** page in the shared product interface. Usage dashboards are operational records, not an invoice portal.

When querying a charge, include the billing period, organization, and invoice reference. Never include provider keys or API keys.

## Understand model usage

Open [Usage analytics](https://docs.tale.dev/platform/admin/governance/usage-analytics) to see the usage recorded by the platform. Use the date range and model or user breakdowns to find what generated the activity.

A displayed usage cost and a final invoice serve different purposes. Your commercial agreement and the provider’s billing rules determine the amount payable; do not treat a dashboard total as a final invoice or tax statement.

<Tip>

Before rolling out a new model, try a representative task and review its quality and recorded usage. A cheaper request is useful only if it produces a result your team can use.

</Tip>

## Set limits for the workspace

Use [Policies and limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits) to configure the controls your team needs. Check the scope of each rule and test it with an account in that scope. Platform limits apply to the activity they govern; they do not change the terms of your hosting contract.

For self-hosted Community, you operate the infrastructure and pay your chosen providers directly. The same usage and policy pages help you understand that activity.

# Understand Cloud data residency
Source: https://docs.tale.dev/cloud/data-residency

Data residency covers where your data is stored and where it is processed. Choosing a Cloud region addresses the hosted service; it does not by itself determine where every model provider or connected service handles your data.

## Confirm the hosting arrangement

Confirm your instance’s primary region, backup locations, retention, recovery objectives, and support process with Tale before onboarding. Use the service agreement and data-processing documents for the commitments that apply to your deployment. Do not infer a backup city or recovery guarantee from a region label in the product.

The Cloud service is operated by Tale. Configuration files, database credentials, and host environment variables are operator responsibilities. The [self-hosted configuration reference](https://docs.tale.dev/self-hosted/configuration/data-residency) explains the technical model for operators.

## Follow the data through a request

A chat message travels to your Tale instance. When the assistant uses knowledge, relevant content is retrieved from the organization’s knowledge store. The message and selected context are then sent to the model provider used for that response. A tool may contact another service, such as a website or a connected application.

| Data flow | What to confirm |
| --- | --- |
| Stored chats, documents, and configuration | The agreed hosting and backup locations |
| Knowledge indexing | Which embedding provider receives document content |
| Model inference | The selected provider’s endpoint, processing terms, and retention |
| Connectors and web tools | Which external systems receive requests and content |
| Operational records | The agreed handling of logs, backups, and support access |

A provider may offer regional or locally hosted endpoints. Verify the endpoint actually configured; its brand name alone does not establish where processing occurs.

<Tip>

Review the embedding provider as well as the chat model. A document can be sent for embedding during indexing before anyone asks a question about it.

</Tip>

## Review a new integration

Before connecting a service, identify what data the intended task will send and which account the connector uses. Check the service’s processing terms, restrict its access, and test with non-sensitive example content. Record the decision alongside your [security review](https://docs.tale.dev/cloud/trust-and-compliance).

## Change the region

Arrange a region change with Tale. It requires a migration plan covering stored data, backups, external endpoints, downtime, and validation. Creating a second organization does not move the first organization’s data.

The [migration planning guide](https://docs.tale.dev/cloud/migrate-to-self-hosted) lists the questions and verification steps that also apply when moving between Cloud regions.

# Tale Cloud
Source: https://docs.tale.dev/cloud

Tale Cloud is the managed way to run Tale. Your team uses the same product features as the open-source edition, while Tale operates the service under your Enterprise agreement.

## Start with your next task

<CardGroup cols="2">

<Card title="Get access to your instance" href="https://docs.tale.dev/cloud/onboarding">

Request an instance or join the one your organization already uses.

</Card>

<Card title="Understand charges and invoices" href="https://docs.tale.dev/cloud/billing">

Separate service charges from model usage and find the right support channel.

</Card>

<Card title="Review where data goes" href="https://docs.tale.dev/cloud/data-residency">

Check hosting arrangements and the providers and tools that process content.

</Card>

<Card title="Prepare a security review" href="https://docs.tale.dev/cloud/trust-and-compliance">

Gather certification evidence and review your responsibilities.

</Card>

<Card title="Plan a move to your infrastructure" href="https://docs.tale.dev/cloud/migrate-to-self-hosted">

Coordinate an operator-assisted migration and verify the destination.

</Card>

</CardGroup>

For chats, projects, agents, and settings, use the [Platform guides](https://docs.tale.dev/platform). Cloud pages cover the hosting service and its responsibilities; the product workflows are shared.

# Plan a move to self-hosted Tale
Source: https://docs.tale.dev/cloud/migrate-to-self-hosted

Moving from Cloud to self-hosted Tale transfers responsibility for the infrastructure to your team. Plan the move with Tale and the operator of the destination so application data, knowledge, files, configuration, and encryption keys remain consistent.

Plan an operator-assisted transfer of the databases, files, configuration and required secrets. Individual API exports cover selected resources; they do not replace a consistent backup of the instance.

## Decide what the move must preserve

List the organizations and data to move, the permitted downtime, the target version, and the people who will approve the result. Confirm the infrastructure requirements in the [self-hosted installation guide](https://docs.tale.dev/self-hosted/install/quickstart).

| Area | Questions to resolve before the move |
| --- | --- |
| Application database | Which backup is the consistent source, and which versions can restore it? |
| Knowledge stores | Which per-organization stores, indexes, and embedding settings must move? |
| Files and configuration | Which object-store data and configuration directories belong to the deployment? |
| Encryption | Which encryption and signing keys must be retained securely? |
| External services | Which callback URLs, webhook destinations, credentials, or network rules change? |
| Background work | Which runs must finish or be paused before the final copy? |

Use the [backup and restore guide](https://docs.tale.dev/self-hosted/operate/backups-and-restore) with your operator. Do not substitute a collection of API exports for that plan.

## Rehearse on an isolated destination

Restore a copy into an isolated environment before the cutover. Keep outbound automations and scheduled jobs controlled so the rehearsal cannot send duplicate messages or make unintended external changes.

Verify sign-in, roles, representative documents, project files, a chat response, and the configuration of critical integrations. Compare counts and selected records with the source. A service that boots has passed only the first check.

## Agree on the cutover and recovery

Write down who freezes writes, takes the final copy, changes routing, and validates the new instance. Agree on what triggers a rollback and how to prevent both instances accepting changes at once. Keep the source and verified backups available until the migration is accepted.

Update public origins, TLS, SSO callbacks, and integration destinations as required by the new address. Existing sessions or external credentials may need renewal; test them rather than assuming they transfer.

## Hand over operation

Confirm monitoring, backup schedules, restore ownership, upgrade procedures, and support contacts. Record the accepted checks and tell the team which address to use. Your next ongoing responsibilities are [upgrades](https://docs.tale.dev/self-hosted/operate/upgrades), [observability](https://docs.tale.dev/self-hosted/operate/observability/operations), and rehearsed restores.

# Get started on Tale Cloud
Source: https://docs.tale.dev/cloud/onboarding

Cloud onboarding starts with the instance your organization will use. Once you have access, the same chat, project, and administration guides apply as on a self-hosted instance.

## Join an existing instance

Ask your administrator for the instance address and sign-in method. Open that address and use your own account. If the organization uses SSO, follow its sign-in flow rather than creating a second account.

After signing in, follow [send your first message](https://docs.tale.dev/get-started/quickstart). If you cannot see the expected organization or project, ask the administrator to check membership, role, and project sharing.

## Set up a new Cloud service

<Steps>

<Step title="Arrange the instance">

[Request a demo](https://tale.dev/request-demo) or contact the Tale team. Agree on the hosting region, service terms, identity requirements, and the person who will administer the workspace. Use [data residency](https://docs.tale.dev/cloud/data-residency) and [security and compliance](https://docs.tale.dev/cloud/trust-and-compliance) to prepare those decisions.

</Step>

<Step title="Complete the workspace setup">

Use the instance address and setup instructions supplied by Tale. If the first-run wizard is shown, create the initial account and organization. If an organization is already present, open it; creating another organization produces a separate workspace.

If organization creation is managed by the operator, the organization picker does not offer a creation action. A direct setup link explains the restriction. Contact the operator to request another workspace.

<Frame caption="The workspace name identifies the organization your team will use.">

![The organization creation wizard shows the Organization name field.](https://docs.tale.dev/images/get-started/org-create-wizard.webp)

</Frame>

</Step>

<Step title="Connect a provider and add the team">

Follow [set up a workspace](https://docs.tale.dev/get-started/admins) to add provider credentials, verify a model response, and create member accounts with the appropriate roles. The workspace can exist before a provider is ready; a working chat is the check that model access is configured.

</Step>

</Steps>

## Confirm the first useful workflow

Choose one task the team actually needs: discuss a document, organize project work, or test a project agent. Check the result with the intended user role. [Use Tale with your team](https://docs.tale.dev/get-started/members) and [create a project agent](https://docs.tale.dev/get-started/editors) provide the next steps.

<Tip>

Test with a small, non-sensitive sample before importing a large collection. This lets you check access and data flows while the setup is still small enough to understand.

</Tip>

## Get help with access or setup

For account and project access, start with your organization’s administrator. For instance availability, service configuration, or contract questions, use your agreed Tale support channel. Include the instance address, time, action, and displayed error; exclude passwords and keys.

# Security and compliance
Source: https://docs.tale.dev/cloud/trust-and-compliance

Ruler GmbH, the company behind Tale, is ISO/IEC 27001 certified. The certification covers its Tale Enterprise offering and services. For a security review, ask your Tale contact for the applicable certificate, its scope, and supporting documents for the service your organization has purchased.

Product controls support your organization’s processes. Whether a particular use meets your obligations also depends on your configuration, connected providers, and operating procedures.

## Prepare a review

Bring together your service agreement, data-processing agreement, the relevant certification evidence, and a description of your deployment. The [privacy policy](https://docs.tale.dev/legal/privacy) and [subprocessor information](https://docs.tale.dev/legal/subprocessors) provide additional context. Record the version and scope of each document in your review.

Clarify which organization and deployment the review covers. A certification statement is not a substitute for checking whether a particular service or configuration falls within the report’s scope.

## Know who is responsible

| Area | Tale on Cloud | Your organization |
| --- | --- | --- |
| Hosting and maintenance | Operates the agreed service | Chooses the service and coordinates changes |
| Identity and access | Provides account, role, and SSO controls | Adds members, grants access, and reviews it |
| Model providers and connectors | Provides integration controls | Chooses services, credentials, and permitted uses |
| Usage and content policies | Provides policy controls and records | Configures rules and responds to events |
| Data requests and retention | Provides the supported workflows | Determines requirements and authorizes actions |

For self-hosted deployments, your operator also owns the infrastructure responsibilities. Enterprise support arrangements depend on your agreement.

## Check the controls in the product

- [Members and roles](https://docs.tale.dev/platform/admin/members-and-roles) define access. Review inactive accounts and elevated roles.
- [Enterprise SSO](https://docs.tale.dev/platform/admin/enterprise-sso) connects your identity provider. Test both sign-in and recovery before requiring it.
- [Audit logs](https://docs.tale.dev/platform/admin/governance/audit-logs) help investigate recorded actions. Use [audit-log integrity](https://docs.tale.dev/self-hosted/operate/security/audit-log-integrity) when evaluating tamper evidence and its limits.
- [Guardrails](https://docs.tale.dev/platform/admin/governance/guardrails), [legal hold](https://docs.tale.dev/platform/admin/governance/legal-hold), and [data-subject requests](https://docs.tale.dev/platform/admin/governance/data-subject-requests) support specific processes; read their scope before relying on them.

## Report an incident

Use your agreed Enterprise support channel for a service incident. Report a suspected vulnerability through [GitHub’s private security reporting](https://github.com/tale-project/tale/security) or `security@tale.dev`. Include the affected version and reproduction details without sending credentials or personal data in a public issue.

For a review of where data travels, continue with [Cloud data residency](https://docs.tale.dev/cloud/data-residency).

# Edit configuration with a coding agent
Source: https://docs.tale.dev/develop/ai-assisted-development

Use a coding agent to help edit a CLI-managed Tale configuration project. The project includes instructions, example configuration and a selected source reference. You still need to review the proposed change and verify which organizations it will affect.

This is different from contributing to Tale’s application source. For a source checkout, start with [Contributor setup](https://docs.tale.dev/develop/contributor-setup) and the repository’s own `AGENTS.md`.

## A worked setup

Install the [Tale CLI](https://docs.tale.dev/self-hosted/install/cli-install), then create a new directory for the configuration project:

```bash
tale init agent-config-example --no-env
cd agent-config-example
ls -a
```

The following is an excerpt of the generated paths:

```text
AGENTS.md
CLAUDE.md
default/
.gitignore
.tale/
tale.json
```

`--no-env` skips environment setup; it does not create a runnable deployment or generate `.env`. This is useful when you want to inspect configuration before starting containers. `tale dev` performs environment setup when you later launch locally. Review the [quickstart prerequisites](https://docs.tale.dev/self-hosted/install/quickstart) first.

Open this directory in your coding editor. Ask the agent to read `AGENTS.md`, the relevant existing configuration and the source under `.tale/reference/` before proposing a change.

## The two instruction files

`AGENTS.md` contains Tale’s configuration guidance. `CLAUDE.md` points to that file so there is one maintained set of project instructions. The CLI also recognizes an existing `AGENT.md`, or a `CLAUDE.md` already stored under `.claude/`.

The CLI owns the section between its `tale:begin` and `tale:end` comment markers. Put your project-specific conventions outside that section; initialization and updates preserve that surrounding content. Do not put credentials into either instruction file.

The CLI does not generate separate Cursor, Windsurf or Copilot rule files. If an editor does not automatically load the project instructions, explicitly include them in the agent’s context. Check the actual configuration schemas rather than relying on the agent’s memory of an earlier release.

## What lives where

| Path | How to use it |
| --- | --- |
| `default/agents/` | Agent configuration catalog, including the supplied coding-agent example. |
| `default/automations/` | Automation definitions available to install or deploy. Presence on disk does not mean an automation is active. |
| `default/skills/` | Skill bundles, including document and visual-analysis skills. Each bundle is a directory. |
| `default/branding/` | Branding configuration and image assets for the template. |
| `default/governance/` | Policy and retention examples. Follow the formats of the files generated by your CLI. |
| `default/README.md` | Explains the template and automatic-install behavior of its catalog. |
| `.tale/reference/` | Selected implementation source embedded in the CLI. Read it; changes here are replaced by regeneration. It is not a complete repository checkout. |
| `.tale/orgs/<slug>/<domain>/` | Runtime configuration of actual organizations created in the app. |
| `.tale/checksums.json` | Records scaffolded-file hashes so updates can distinguish your edits from generated content. |

`default/` is the template for new organizations, not a deployable organization itself. Editing it does not by itself update an existing organization. The `.tale/` directory and secret sidecars are ignored by Git; public template files are intended for version control.

## Keep the mirror fresh

`tale update` updates the CLI within its current release line and refreshes generated project content. It regenerates the reference, updates managed instruction sections, adds new catalog files and updates files whose checksums show no local changes. Locally changed catalog files are preserved unless you use `--force`.

Use `tale update --dry-run` to inspect the proposed changes. Keep a version-controlled copy of your public configuration and protected backups of runtime configuration and secrets. Do not treat `.tale/reference/` as a place to maintain a fork. Updating the CLI does not roll running containers; follow [Upgrades](https://docs.tale.dev/self-hosted/operate/upgrades) when changing the deployed version.

## Cursor: config plane vs runtime plane

An editor agent working in this directory changes local configuration files. A Tale [project agent](https://docs.tale.dev/platform/projects/project-agents) using the Cursor harness runs work in a Tale-managed sandbox. These are separate execution contexts with separate credentials and consequences.

The sandbox harness uses its configured provider account and model. Giving your editor the project instructions does not configure that account. Follow [Harnesses](https://docs.tale.dev/platform/agents/harnesses) for runtime setup.

## Review and apply a proposal

1. Ask for one bounded change and name whether it belongs to the new-organization template or an existing organization.
2. Check every changed path, schema field, slug and referenced credential. Keep secrets out of the prompt and public diff.
3. Validate or test through the corresponding product surface. For an automation, inspect validation results and run its mock tests before deployment.
4. Review the deployment plan and the destination organization. `tale deploy --override` can replace runtime configuration with the local copy; use it only for a deliberate, reviewed overwrite.
5. Read back the configuration and exercise the behavior after deployment.

If the agent proposes a field absent from the installed schema, stop at validation and correct the proposal. If an edit to `default/` leaves an existing organization unchanged, check the destination instead of repeatedly deploying the template.

# API reference
Source: https://docs.tale.dev/develop/api-reference

The REST API lets you read and change Tale resources with an API key: projects, files, tasks, automations, runs and chat threads. Start with [your first API request](https://docs.tale.dev/get-started/developers) to verify access, then use the operation-specific sections below.

Your instance serves the field-level OpenAPI schema at `/openapi.json` and an interactive reference at `/docs`. Use that instance’s schema when generating a client. This page explains permissions, scope, asynchronous work and errors that apply across those operations.

## A worked request

Set `TALE_URL` to your application origin, `TALE_API_KEY` to your key, and `TALE_ORG_SLUG` to the intended organization. Keep secrets in the environment. Begin with an identity check before creating resources:

```bash
curl --fail-with-body --compressed "$TALE_URL/api/v1/me" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG"
```

A `200` response identifies `user`, the selected `organization`, all current `organizations`, deployment `capabilities`, and this `key`'s name and expiration. Check the organization and role before continuing. The examples below use placeholder project, file, and run IDs: obtain actual IDs from a previous response rather than copying a display name or guessing an ID.

### Read every page of a list

List responses use named collections, not a bare array. The instance's OpenAPI `200` schemas declare `x-tale-pagination`; use it to choose the correct loop.

| Family | Requests | Response and stopping rule |
| --- | --- | --- |
| Keyset | `cursor`, `limit` | Rows plus `isDone` and `continueCursor`; stop at `isDone: true` |
| Offset: website pages only | `cursor` or `offset`, never both | `pages`, `total`, `offset`, `hasMore`, plus `isDone` and a signed `continueCursor` |
| Unpaginated | No `cursor` or `limit` | Named array containing the complete set or the operation's bounded roster |

For keyset lists, send `continueCursor` back unchanged. Do not decode or increment it. At the last page it is empty; sending that empty value again returns `400 INVALID_QUERY`, not the first page. Each operation declares its limit ceiling: usually 100 or 200, and 500 for task comments. Larger query limits are clamped.

Contacts and products are ordered by `updatedAt`, then `id`, both descending. Editing a record while you page can move it ahead of your cursor, so that pass may miss the change. For a full reconciliation, compare each record’s `updatedAt` and repeat complete passes; a cursor does not provide a snapshot of a changing directory. Hub documents, projects, project files, and websites use newest-first `createdAt` order.

Contacts, products, documents, knowledge entries, threads, messages, websites, and notification exports put their keyset rows under `page`. Runs, deliveries, task comments, projects, and project files use their resource name, such as `runs` or `files`. Run lists are newest first, default to 50, and accept limits of 1–200. `GET /api/v1/runs` lists accessible runs across automations.

Automations, agents, skills, folders, models, browser sessions, versions, and triggers are unpaginated. A website-page request with both `cursor` and `offset` receives `400 INVALID_QUERY`; the signed next-offset cursor also works with the normal keyset loop.

## Authentication

Create keys in **Settings > API > REST** as an Owner, Admin, or Developer, or as a member an Admin granted a competence that is used with a key (`tale:models.api`, `tale:notifications.export`, or `tale:rest.act-as`); anyone else is refused with `403 API_KEY_CREATE_FORBIDDEN`; [API keys](https://docs.tale.dev/platform/admin/api-keys) explains the UI. A key appears once and acts as the user who created it. This REST surface does not create, list, rotate, or revoke keys.

| Header | Rule |
| --- | --- |
| `Authorization: Bearer <key>` | The only supported API-key location; preserve the whole opaque string, including its `tale` prefix |
| `X-Organization-Slug: <slug>` | Select a current membership; always send it in reusable integrations |
| `x-api-key` | Rejected with `401`, even beside a valid Bearer header; it cannot turn an API key into an app session. On the Anthropic-compatible [model endpoint](https://docs.tale.dev/develop/api-reference#model-endpoints), the refusal says to pass the key as an auth token instead: `ANTHROPIC_AUTH_TOKEN` for Claude Code, `authToken` or `auth_token` for the Anthropic SDKs, with `ANTHROPIC_API_KEY` unset (contract 3.6.0) |

A user with exactly one organization can omit the organization header. With several memberships, every request needs it, including reads. The dashboard's selected organization never selects API scope. Slugs are matched without regard to case; blank or whitespace-only values count as absent.

| Organization selection | Result |
| --- | --- |
| Several memberships, no slug | `400 ORG_SLUG_REQUIRED` |
| Unknown slug, or a value that cannot be a slug | `404 ORG_SLUG_INVALID` |
| Existing organization without membership, or with a disabled one | `403 ORG_FORBIDDEN` |
| Valid membership | Request proceeds under that organization and role |

Each of the three refusals lists the organizations you can select in `data.organizations`, as `slug` and `name` pairs. Disabled memberships are left out, so the list is empty when none remains. Retry with one of the listed slugs.

`GET /api/v1/me` also returns the membership list as `organizations`. Its `key.expiresAt` is epoch milliseconds, or `null` for a non-expiring key: rotate unattended credentials before expiry causes `401`. `key.name` identifies the credential in use.

Check both the role and the resource scope before offering an operation. Project readers can chat, comment, and create tasks, and they can change and start the tasks they created or are assigned to; changes to other resources and to other people's tasks require edit access.

| Capability returned by `/me` | What it permits |
| --- | --- |
| `developer` | The Owner, Admin, and Developer roles can start arbitrary live runs, cancel or delete runs, bind or unbind triggers, delete automations, and install or uninstall project automations. These REST operations return `403 ROLE_FORBIDDEN` without it. MCP also checks this capability for saving, deploying, and other privileged tools, using its own error envelope. Validation and mock tools remain available to members. Project access is checked separately. |
| `deploymentEditor` | The operator allowlist permits browser-session import and revocation. An administrative role alone does not grant this capability. |
| `notificationExport` | The key may export members’ notifications through `GET /api/v1/notifications/sync`. Owners and Admins have it through their role; any other member only while an Admin’s `tale:notifications.export` grant is live — see [Delegate the export without an Admin role](https://docs.tale.dev/develop/api-reference#delegate-the-export-without-an-admin-role). Without it, the export returns `403 ROLE_FORBIDDEN`. |
| `skillPublish` | The key may share a skill with the whole organization through `PUT /api/v1/skills/{slug}`. Every member may while the organization has no skill sharing policy; under one, only the roles it admits and members holding a live `tale:skills.publish` grant — see [Save and synchronize skill bundles](https://docs.tale.dev/develop/api-reference#save-and-synchronize-skill-bundles). Without it, such a save returns `403 SKILL_PUBLISH_FORBIDDEN`. |
| `actAs` | The key may name an `actor` — the verified member a relayed gesture is recorded for — on `POST …/runs/{runId}/asks/{askId}` and `POST …/tasks/{taskId}/review`. Owners and Admins have it through their role; any other member only while an Admin’s `tale:rest.act-as` grant is live — see [Name the member the gesture is for](https://docs.tale.dev/develop/api-reference#name-the-member-the-gesture-is-for). An `actor` sent without it returns `403 ROLE_FORBIDDEN`. |
| `modelApi` | The key may call the [compatible model endpoints](https://docs.tale.dev/develop/api-reference#model-endpoints): the organization has turned them on, and the key holder may call them. Owners, Admins, and Developers may through their role; any other member only while an Admin's `tale:models.api` grant is live. Without it, those routes answer `403 MODEL_API_DISABLED` or `403 MODEL_API_FORBIDDEN` (contract 3.6.0). |

## What every request is held to

### JSON and query validation

Send JSON encoded as UTF-8. Invalid UTF-8, NUL characters, unpaired UTF-16 surrogates in keys or values, and integer values beyond 2^53 − 1 return `400 INVALID_BODY`. Represent large identifiers as strings. Nested validation issues include the full field path, such as `messages.0.createdAt`. IDs are strings and timestamps are epoch milliseconds. A timestamp you send is a whole number of milliseconds from `0` to `8640000000000000` (275760-09-13, the latest instant a JavaScript `Date` can hold); any other value returns `400 INVALID_BODY`. A skill’s `updatedAt` records when its `SKILL.md` was written.

| Input | Rule |
| --- | --- |
| Unknown body key | `400 INVALID_BODY`, with the key named in the issue |
| Duplicate JSON key | Last value wins |
| Unknown, repeated, or blank query parameter | `400 INVALID_QUERY` |
| Query on a write operation | Rejected; writes take no query parameters |
| Query `limit` outside its range | Clamped to the operation's range |
| Body number outside its range | `400 INVALID_BODY`; search `limit` and `maxOutputTokens` are examples |
| `Content-Type` | Bodies are parsed as JSON regardless of this header; this surface does not return `415` |
| `Accept` | JSON operations return JSON even when this header requests another format or excludes JSON; there is no `406` |

### Request-size and arrival limits

| Body | Maximum |
| --- | --- |
| Default JSON request | 1 MiB |
| Inline document content | 32 MiB |
| Model endpoint request | 32 MiB |
| Contact bulk import | 8 MiB |
| Conversation snapshot | 8 MiB |
| Staged conversation upload | 30 MiB |
| Skill save | 4 MiB |
| Delivery claim, failure report, or acknowledgement | 64 KiB |

An oversized body receives `413 BODY_TOO_LARGE`. When the declared length exceeds the cap, the platform rejects before reading the body; otherwise it stops at the first chunk over the cap. It never buffers the complete oversized body. Upload-specific rules can be lower than these transport limits.

Headers and body must finish arriving within 15 minutes. A 30 MiB body needs roughly 35 KB/s to meet that deadline. A slower request receives `408 REQUEST_TIMEOUT` and the connection closes. Use a faster link, smaller supported requests, or the two-step project upload, which transfers file bytes outside this JSON arrival window.

### Methods and response identifiers

Existing read routes accept `HEAD`, with the uncompressed `GET` length and no body; `HEAD` is never compressed. `OPTIONS` is keyless and returns `204` with `Allow`. An unsupported verb on an existing route returns `405 METHOD_NOT_ALLOWED` and its allowed verbs. One trailing slash is tolerated.

The production REST surface is server-to-server and does not enable CORS. Keep API keys behind your own backend. The keyless status JSON is a separate CORS-enabled surface.

Every API response includes `X-Request-Id`. To correlate a request with logs, send up to 255 characters drawn from letters, digits, `_`, `-`, and `=`. An invalid value is replaced by a fresh UUID; the response contains the value actually used. `429`, `500`, `413`, and `414` also include `requestId` in the JSON envelope. Two refusals are the exception, because the edge's HTTP parser answers them before a request exists to log: the bare `431` for headers over the 64 KiB budget and the bare `400` for a control character in a header value carry no `X-Request-Id`, no envelope and no `X-Tale-Api-Version` — there is nothing to quote, and the request itself is what to change.

`Idempotency-Key` is read only by the operations that declare it — a run start, a chat send; the OpenAPI document lists them, and the webhook endpoints read it as a delivery id under their own rule. Any other operation ignores the header: its at-most-once guard is the natural key its body names — a contact's `externalId`, a task's `(externalSystem, externalId)`, a project's `externalItemId`. An `Expect: 100-continue` draws one `100 Continue` from the edge as soon as it starts forwarding the body; the platform's own verdict — a `413` for a declared length over the cap — still arrives before a body byte is read.

Responses from `/api/v1` and webhook routes include `X-Tale-Api-Version`; see [Versioning](https://docs.tale.dev/develop/api-reference#versioning). Keyless `/api/health`, `/status`, `/status.json`, and `/openapi.json` do not implement that contract and have no version header.

<Accordion title="Advanced HTTP and proxy behavior">

The URL, including query, is limited to 32 KiB; a larger one gets `414 URI_TOO_LONG` before route lookup. Request headers have a 64 KiB edge budget. HTTP/1.1 permits a few KiB of slack before a bare `431`, so a 66 KiB URL can still reach the platform and receive `414`. HTTP/2 enforces the header budget exactly by closing the connection without a response.

Header control characters below 0x20, except tab, and DEL are rejected before the platform: HTTP/1.1 receives a bare text `400` with no `X-Request-Id`; HTTP/2 resets the stream or closes a connection carrying a body.

Malformed HTTP/1.1 chunk framing, such as a non-hexadecimal chunk size or missing CRLF, receives `400 BODY_CHUNK_MALFORMED` at the edge. Correct the HTTP client or intermediary that encoded the request; retrying the same malformed bytes will not help.

For an oversized declared body, the HTTP/1.1 edge may drain up to 256 KiB before delivering the refusal, although the platform reads none. If a body ends before its declared length, HTTP/2 returns `400 BODY_LENGTH_MISMATCH`, unless the platform's over-cap `413` won the race. HTTP/1.1 waits for the missing bytes until the 15-minute arrival deadline.

Edge refusals have their own request ID and no `X-Tale-Api-Version`: the proxy does not know the application contract. Examples include a dot-segment `404`, `BODY_LENGTH_MISMATCH`, `BODY_CHUNK_MALFORMED`, and `502`/`503`/`504 UPSTREAM_UNAVAILABLE` during a restart. A `503 DATABASE_UNAVAILABLE` is the platform's own answer while its database restarts, so it carries the platform's request ID and `X-Tale-Api-Version` like any other platform response. Do not assume every intermediary response has the API's JSON envelope.

</Accordion>

## Caching, compression and partial reads

### Reuse unchanged responses

Every JSON read — a `GET` that returns **200** — carries an `ETag` computed over its bytes and `Cache-Control: private, no-cache`: keep the answer, and send the tag back as `If-None-Match` on the next read. An unchanged resource returns **304** with no body, so a poller that watches a finished run, an idle thread or a document's indexing state spends a round trip instead of the payload.

Send the tag back exactly as you received it: behind the compressing edge the tag of a compressed answer reads `"…-gzip"` or `"…-zstd"`, and that form matches, as does the weak `W/"…"` form; the 304 carries the tag the API computed. File content — `GET /api/v1/projects/{id}/files/{documentId}/content` and a Hub document's `GET /api/v1/documents/{id}/content` alike — honours `If-None-Match` and `If-Modified-Since` against the `ETag` and `Last-Modified` it issues, the same way — a mirror re-downloads a file only when its bytes changed.

The date is judged at the whole-second precision an HTTP date carries, and `If-None-Match` decides alone when both travel; on a content-only Hub document `Last-Modified` is the document's own `updatedAt`, which a title or metadata patch moves too, so a mirror that tracks bytes sends the `ETag`. A **304** still counts as one request against the [rate limits](https://docs.tale.dev/develop/rate-limits).

```bash
# The first read answers 200 and its ETag; the repeat with that tag answers 304
curl -sS --compressed -D - -o /dev/null "https://your-host.example.com/api/v1/projects/<projectId>/runs/<runId>?fields=status,finishedAt" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG" \
  -H 'If-None-Match: "<etag from the previous answer>"'
```

### Request compression

JSON and text responses are compressed when the request offers `gzip` or `zstd` in `Accept-Encoding` — `curl --compressed` does, and every HTTP library can — above a floor of about 512 bytes; `br` is not served. A compressed answer's `Content-Length`, when present, is the compressed size (a large answer streams without one) and its `ETag` reads with the `-gzip`/`-zstd` suffix, as above; a `HEAD` is never compressed and reports the uncompressed length. Request compression for large JSON responses when your HTTP client supports it. The benefit depends on the response content; it does not reduce the number of requests charged to your rate budget.

### Read only the fields you need

Where a resource is large and a read needs only part of it, the operation says so: a run read takes `?fields=status,finishedAt` (any keys of the run, comma-separated) and returns exactly those keys, and a run listing that inlines full rows through `?include=` reads at most 25 rows per page and returns at most 8 MiB of them — it ends at the last row that fits, `isDone: false`, with a `continueCursor` at that row, so keep following the cursor until `isDone`.

## Sign in to an application with Tale

Tale is also an OpenID Connect issuer. A registered application sends you through Tale's native login and consent; it receives a signed identity with a verified email and membership in the one organization bound to its client. An API key does not authenticate a person for this flow.

Register the application with an active Owner or Admin session whose selected organization equals `TALE_ORG_ID`. `TALE_ORIGIN` is your Tale origin and `TALE_SESSION_COOKIE` is that session's cookie header. Use the application's exact HTTPS callback; HTTP is accepted only on loopback for local development:

```bash
curl -sS --compressed -X POST "$TALE_ORIGIN/api/app/identity/clients?orgId=$TALE_ORG_ID" \
  -H "Cookie: $TALE_SESSION_COOKIE" \
  -H "Origin: $TALE_ORIGIN" \
  -H "Content-Type: application/json" \
  -d '{"key":"office-app","name":"Office application","redirectUri":"https://office.example.com/api/auth/oauth2/callback/tale"}'
```

The first response is **201** with `{ "created": true, "client": { "client_id": "…", "client_secret": "…", … } }`. Store the secret in the application's secret environment. Repeating the same key and configuration returns **200**, `created: false`, and the same client ID without the secret. A changed callback or policy returns **409** so a rerun cannot silently redirect an existing integration.

| Purpose          | Endpoint or requirement                                                      |
| ---------------- | ---------------------------------------------------------------------------- |
| Issuer           | `https://your-host.example.com/api/auth`                                     |
| Discovery        | `GET /api/auth/.well-known/openid-configuration`                             |
| Authorization    | `GET /api/auth/oauth2/authorize`                                             |
| Code exchange    | `POST /api/auth/oauth2/token`, `client_secret_basic` or `client_secret_post` |
| Signing keys     | `GET /api/auth/jwks`                                                         |
| Current identity | `GET /api/auth/oauth2/userinfo`, bearer access token                         |
| Requested scopes | `openid profile email tale:organization`                                     |

Use a maintained OIDC client with authorization code flow, S256 PKCE, one-use state and a nonce. Validate the issuer, audience, RS256 signature, expiry and nonce of the ID token, then require `email_verified: true`. The `https://tale.dev/organization` claim contains `{ "id", "slug", "role" }` for the registered organization. Every ID token also carries `acr: "0"`. Discovery lists `"0"` under `acr_values_supported` and `acr` under `claims_supported`. Tale asserts no stronger authentication context, MFA enforcement included, so do not gate on `acr`. Releases from v0.5.45 documented `urn:mace:incommon:iap:bronze` while the token already carried `"0"`; a relying party pinned to the URN must accept `"0"`. Discovery's `prompt_values_supported` names what the issuer honours — `none`, `login`, `consent`; `select_account` and `create` are not offered.

The ID token carries the standard claims of the scopes you request, with the values userinfo returns, so you can read them without a userinfo request. `email` adds `email` and `email_verified`. `profile` adds `name`, split into `given_name` (every word but the last) and `family_name` (the last word) when the name has two or more words, and `picture` when the account has one.

Tale rechecks current membership and native MFA enforcement before issuing tokens and when reading userinfo; the application remains responsible for its own account access policy. Codes, access tokens and ID tokens expire after five minutes, and a code can be redeemed once. Dynamic registration, implicit grants and refresh tokens are disabled.

Access tokens serve only native userinfo; external resource audiences are disabled. Use native API keys for REST requests.

### Handle identity-provider errors

Errors follow RFC 6749 and RFC 6750 — what a maintained client expects. `userinfo` returns **401** `invalid_token` with a `WWW-Authenticate: Bearer` challenge for an invalid or expired access token — every five-minute expiry walks this path, so treat it as a sign-in, not a retry — and **401** with the bare challenge when the token is missing; a token without the `openid` scope returns **403** `insufficient_scope`.

The token and authorization endpoints answer `{ "error", "error_description" }`: a grant other than `authorization_code` is `unsupported_grant_type`, a malformed request — a missing `grant_type` included — `invalid_request`, with the description naming the parameter (`grant_type is required`, `client_id is required`, `response_type must be one of "code"`). A body of the wrong media type on a JSON-only endpoint (a form posted to `register`) returns **400** `invalid_request` naming the type it takes — there is no 415 on this surface.

An authorization request whose `client_id` names no registered client is redirected to the issuer's own error page — never to the `redirect_uri` it sent — with `error=invalid_client` and a description that says the client is unknown, so a mistyped id is not mistaken for a missing one. Discovery lists `https://tale.dev/organization` under `claims_supported`; it also advertises the provider's introspection, revocation and end-session endpoints, which the flow above does not need.

### Rotate or disable an application client

For a reviewed client key, `POST /api/app/identity/clients/office-app/rotate-secret?orgId=<orgId>` with `{}` returns a new `client_secret` once and retires the old secret. `POST /api/app/identity/clients/office-app/status?orgId=<orgId>` with `{ "disabled": true }` blocks new authorizations; `false` restores the same client. Both require the same current organization, administrator session, Origin header and JSON content type as registration. Deleting an organization removes its clients and consent grants.

## Endpoint groups

For a project resource under `/api/v1`, put its project ID in the URL. These request bodies do not accept `projectId`; strict schemas reject it with **400**. The resource must belong to the named project and be visible to the key holder, otherwise the call returns **404**. Responses may include `projectId` as resource metadata. Organization catalogs, such as automation definitions and skill bundles, keep their organization paths.

Every **201** that creates one addressable resource carries `Location` — the resource's own path, relative to the request URL — so a generic client follows it whatever shape the body has (`{id}` on a contact, `{project}` on a project, `{task}` on a task); the bulk contact import creates many and carries none.

Automation authoring is separate from this REST surface. Use the [MCP endpoint](https://docs.tale.dev/develop/mcp-endpoint) or the app’s editor to save, validate, test, and deploy definitions. `tale deploy` releases deployment configuration; it is not a REST authoring endpoint.

| Resource | Route and scope |
| --- | --- |
| Automations | `/api/v1/automations/...`<br>Organization definitions, versions, triggers and the projects each is installed in; delete a definition; start and list runs that have no project. |
| Project automations | `/api/v1/projects/{id}/automations/...`<br>List installed automations, install or uninstall one, start and list this project's runs. |
| Runs | `/api/v1/runs`, `/api/v1/projects/{id}/runs`, and one run at `/api/v1/projects/{id}/runs/{runId}` or `/api/v1/runs/{runId}`<br>List runs across automations; read one in full — status, output, trace, effects; `POST .../cancel` a live one and `DELETE` a finished one; read the question a waiting run asks at `GET .../ask` and answer it at `POST .../asks/{askId}`; use the project path for a project run. |
| Threads | `/api/v1/projects/{id}/threads/...` or `/api/v1/threads/...`<br>The key holder's project chats or chats with no project: list, create, read, archive or restore, delete, send messages, poll the turn and cancel it. |
| Models | `GET /api/v1/models`<br>Configured chat models available to the key holder in this organization — plus `harnesses`, the coding harnesses a project agent may run on — with `contextWindow`, `maxOutputTokens` (absent when the catalog declares no ceiling — then no cap check applies to a send), capabilities, optional `pricing` when the catalog publishes rates, and `default: true` on the organization's pick when one is configured and accessible. |
| Teams | `GET /api/v1/teams`<br>Every team of the organization — `id`, `name` and whether the key holder is a `member` — as a complete set: the ids a team audience takes (`teamIds` on a project or a Hub document, `teams` on a skill). Teams are created and staffed in the app (Settings > Teams) or by an identity provider; nothing on this surface writes one. |
| Agents | `/api/v1/projects/{id}/agents/...`<br>List, read, create, update (conditionally, with `expectedUpdatedAt`) and delete agents within the required project. A `PUT` that names the configuration already stored writes nothing and leaves `updatedAt` alone. |
| Skills | `/api/v1/skills/...`<br>List, read, create or update, and delete organization skill bundles; read any file of a bundle — a validated read (`ETag` and `Last-Modified` on the bytes; `If-None-Match` / `If-Modified-Since` answer **304**), so a mirror re-downloads only what changed. Every skill names its version (`etag`, `updatedAt`) and a save can be guarded with `If-Match`; a skill keeps no version history on this surface — the read answers the current bundle only. |
| Knowledge entries | `/api/v1/knowledge-entries/...`<br>Topic-keyed facts: list (`?topic=`, `?status=`), create, supersede, delete, and one topic's version history at `GET .../{id}/versions`. |
| Knowledge search | `POST /api/v1/projects/{id}/knowledge/search` or `POST /api/v1/knowledge/search`<br>Search one project's indexed files, or visible non-project Hub documents and websites. |
| Documents | `/api/v1/documents/...`<br>Knowledge-base documents: CRUD (a `PATCH` returns the updated document), `GET .../content` for the bytes, plus `POST .../retry-indexing`; every file-backed document carries its `indexing` state. Hub only — project files live under Projects. |
| Websites | `/api/v1/websites/...`<br>Crawled sources: CRUD (a `PATCH` returns the updated website) plus `.../pages` — each page with its `status` (`discovered` until a fetch stores it, `active` from then on), `failCount`, and, when its last attempt failed, `lastError`, `lastErrorKind` and `lastErrorAt`, so a page the fetch guard refused (a redirect into a private address) is told apart from one nobody has fetched yet; `?state=failed` or `?state=skipped` narrows the window to the pages in that state (`total`, `hasMore` and the cursor then count that state alone, and a cursor minted under one state is refused under another), and every window carries `counts`, the failed and the skipped pages' numbers — `.../sync` and `.../search`. Search returns `{results, total}` — each result its `url`, `title`, `content`, `chunkIndex` and `score` — a shape of its own, not the `{hits, diagnostics}` of the knowledge-search endpoints; its `limit` (1–100, default 10) is a body field, refused with **400**, `INVALID_BODY`, when out of range — never clamped. On the website, `crawledPageCount` counts the pages the crawler attempted, stored or not, and `failedPageCount` those whose last attempt failed; the three counts are stamped by the corpus → row sync, which runs after discovery, after every stored batch, at each link's end and at the scan's end (`metadata.lastStatusSyncAt` says when) and which `POST .../sync` forces, and `lastScannedAt` is when the last scan ended. Discovery honours `robots.txt` `Disallow` rules on every path a URL can enter by, listed URLs excepted, and a page a rule covers leaves the index on the next scan; `POST /api/v1/websites` refuses an `http://` domain (`WEBSITE_DOMAIN_INVALID` — the crawler dials https only) and drops a trailing dot, so `example.com.` is `example.com`; a page's `lastError` is one line naming the cause, never a framework call log. |
| Browser sessions | `/api/v1/browser-sessions/...`<br>Browser cookies for [video ingestion](https://docs.tale.dev/self-hosted/configuration/video-ingestion). Organization members can read the masked list. `POST .../import` and `DELETE .../{id}` require an allowlisted deployment editor; check `capabilities.deploymentEditor` in `/me`. Sessions last 14 days by default and at most 180 days. |
| Products | `/api/v1/products/...`<br>Product catalog entries: CRUD (a `PATCH` returns the updated product). |
| Contacts | `/api/v1/contacts/...`<br>Contact records: CRUD (a `PATCH` returns the updated contact) plus `POST /api/v1/contacts/bulk`. |
| Conversations | `/api/v1/conversations/...`<br>Mirror external conversations into Inbox as versioned snapshots, read a source's snapshot receipt, peek at a source's delivery queue, claim native replies, acknowledge or fail their delivery, re-drive a dead-lettered one, and queue a mirrored conversation to a team; exact schemas are in the running instance’s `/docs`. |
| Notifications | `GET /api/v1/notifications/sync`<br>Read-only export of one verified member’s personal or organization feed; Owners and Admins, or a member an Admin granted `tale:notifications.export`. Signed pagination, localized text, stable IDs and content/read-state hashes. |
| Projects | `/api/v1/projects/...`<br>The machine endpoint for external workers: list projects or look one up by external id, create, archive and restore, delete; prepare folders, upload, download and delete files, index a file now, delete folders. |
| Tasks | `/api/v1/projects/{id}/tasks/...`<br>Idempotent task creation from an external ref, state reads, workflow starts (answering the `runId` to poll), comments, and the task’s review — read at `GET .../review`, decided for a member at `POST .../review` — within the named project. |
| MCP | `POST /api/v1/mcp`<br>The [MCP endpoint](https://docs.tale.dev/develop/mcp-endpoint) — same key, JSON-RPC instead of REST. |
| Model endpoints | `/api/v1/openai/...` and `/api/v1/anthropic/...`<br>OpenAI- and Anthropic-compatible calls to the organization's models, off until an Admin turns them on; see [Compatible model endpoints](https://docs.tale.dev/develop/api-reference#model-endpoints). |
| Webhook trigger | `POST /api/projects/{id}/automations/webhook/{token}` or `POST /api/automations/webhook/{token}`<br>Start a deployed automation using its token; the [Webhooks page](https://docs.tale.dev/develop/webhooks) covers project and non-project URLs. |

### Avoid overwriting a concurrent edit

Use `expectedUpdatedAt` in a contact, product, or document `PATCH` when your change depends on the last row you read. A stale value returns `409 CONTACT_STALE`, `PRODUCT_STALE`, or `DOCUMENT_STALE`. Reload the resource, merge your intended change with the intervening edit, then submit the new precondition.

For Hub documents, `If-Match` offers a representation-level guard: send the strong `ETag` returned by the document’s `GET`. The comparison runs inside the document’s write transaction. A mismatch returns `412 PRECONDITION_FAILED`, includes the current tag in `data.etag`, and writes nothing. A tag list or `*` is accepted; a weak `W/` tag never matches. The tag covers the whole read, including `indexing`, so indexing progress can invalidate it even when the document row’s `updatedAt` has not changed.

A successful contact, product, document, or website `PATCH` returns `200` with the updated resource; a document `PATCH` also carries the new representation's `ETag`, the value the next `If-Match` sends. For contacts, products, documents, and projects, a patch that leaves all stored values unchanged performs no write and preserves `updatedAt`. Preconditions are checked first: a no-op body does not bypass a stale `expectedUpdatedAt` or `If-Match`.

### Edit contacts, products, and website identity

Contacts and products share one editing vocabulary. Strings are trimmed; a contact's `email` is stored lowercase, so duplicates match case-insensitively, and the part before `@` is at most 64 characters. A second contact with the same `email` or `externalId` returns **409**, `CONTACT_DUPLICATE_EMAIL` or `CONTACT_DUPLICATE_EXTERNAL_ID`; a second product with the same `name` — compared without regard to case — or `externalId` returns **409**, `DUPLICATE_PRODUCT_NAME` or `DUPLICATE_PRODUCT_EXTERNAL_ID`, on create and on a `PATCH` that renames onto either.

`null` clears any optional field, and on `PATCH` a blank string reads as `null` — a blank required field (a product's `name`) returns **400**, `INVALID_BODY`; on create and bulk import a blank string — or `null` — reads as the field left out, so a CSV-shaped row or a JSON export imports cleanly (the OpenAPI document declares the optional create fields nullable for that reason). A bulk import carries at least one row — an empty `contacts` array returns **400**, `INVALID_BODY`, never a **201** that created nothing. A contact is filed under at least one of `name`, `email` and `externalId`: a patch that would clear the last one returns **400**, `CONTACT_IDENTITY_REQUIRED`.

Read a contact bulk-import result row by row. `POST /api/v1/contacts/bulk` accepts an object containing only `contacts`, an array of 1–500 rows. It validates rows independently and returns `201` even when some fail:

| Response field | How to use it |
| --- | --- |
| `success`, `failed` | Counts of accepted and rejected rows |
| `created[]` | Each created contact’s `id` and original zero-based `index` |
| `errors[]` | Original `index` and `contact`, human-readable `error`, stable `errorCode`, and field `issues` for schema failures |

A malformed email, unknown row key, or missing identity produces an `INVALID_BODY` row error; duplicate identities have their own codes. Correct only the failed rows before resubmitting. Invalid batch structure, transport limits, or invalid JSON encoding still reject the whole request before row processing.

The contact list’s `source` filter accepts the same closed source enum as writes, including `manual_import`, `api_import`, `shopify`, `hubspot`, `webhook`, and `custom`. Use the full enum in the instance’s OpenAPI schema; an unknown value returns `400 INVALID_QUERY`.

`PATCH` merges `metadata` per RFC 7396 — contacts, products and documents alike: sent keys are set, omitted keys stay, a key sent as `null` is removed, and the whole field sent as `null` clears it — while `address` is replaced whole, an address being a unit. `address` and `metadata` (a document's `metadata` too) are bounded to 64 KiB of JSON, 8 levels of nesting and 500 keys in total; a larger value returns **400**, `INVALID_BODY`, naming the path.

A product’s `price` and `stock` are numbers within the safe-integer range, negative values included (a correction booked through the API); the app’s product form and file import refuse negatives and a non-integer stock. A product’s `currency` is an ISO 4217 code (`USD`, `EUR`), accepted in any case and stored uppercase. Its `imageUrl` must be an absolute HTTP or HTTPS URL with a public host. Relative paths, other schemes, private or loopback IP literals, single-label names, and cloud metadata hosts return `400 INVALID_BODY`. Validation examines the URL without a DNS lookup and does not fetch the image. The operator setting `TALE_ALLOW_PRIVATE_CRAWL_HOSTS=1` allows private-network targets but never metadata hosts.

An image uploaded through the product form is a separate case. The app accepts PNG, JPEG, WebP, GIF, or SVG files up to 5 MiB, checks their bytes, and returns a stable protected URL. REST product reads expose that address as an absolute URL. You may send it back in `imageUrl`, including on a private deployment, if it belongs to this organization and you uploaded it or a current product already uses it. An inaccessible or missing image returns `404 FILE_NOT_FOUND`; an altered managed URL returns `400 INVALID_BODY`. Viewing its bytes requires an authorized app session; the URL is not a public sharing link, and a REST API key does not grant access to this app route. Set `imageUrl` to `null` on PATCH to remove the product’s image. Uploading image bytes uses the app form, not a REST product upload endpoint.

A website's `domain` is immutable: `PATCH /api/v1/websites/{id}` accepts the stored value echoed back (a client may send the resource it read) and returns **400**, `WEBSITE_DOMAIN_IMMUTABLE`, for any other. `POST /api/v1/websites` stores the host as given — `www.` is kept — and the `www.` and apex spellings count as one site: a domain already registered under either spelling returns **409**, `WEBSITE_DUPLICATE_DOMAIN`, with `data.websiteId` and `data.domain` naming the existing row.

The one exception is a URL list posted onto a domain registered as a list under the same spelling, which extends it and returns **200** with the existing id; a list posted onto a whole-site crawl is the same **409** — the crawl keeps its kind and nothing is queued — so read `kind` before you post, or re-post under the spelling the 409 names.

A website’s `status` describes its scan lifecycle. Filter with `GET /api/v1/websites?status=` using `scanning` (a registered site starts here), `active`, `error`, or `deleting`; other values return `400 INVALID_QUERY`, and so does `?scanInterval=` outside its seven values. `active` means a finished scan has stored at least one page, not that every page was refreshed. `error` means the scan failed or no pages remain stored after attempted fetches; inspect `metadata.lastSyncError`. A failure of the embedding model opens with `The embedding model could not embed the pages [<class>]:`, where the class is one of `credential`, `credit`, `unresolved`, `dimension`, `throttled` or `upstream`, followed by the provider's own sentence.

Each page’s `lastErrorKind` helps distinguish a network or TLS failure (`network_error`, `tls_error`), a refused target (`private_ip`), an HTTP failure (`http_error`), extraction or rendering failures, content that cannot be turned into text (`unsupported_content`), and a `robots_noindex` refusal — the origin answered `X-Robots-Tag: noindex` or the page carries a `<meta name="robots" content="noindex">` tag. A failed refresh can retain previously indexed content, so inspect page failures alongside the site’s status.

`POST /api/v1/websites/{id}/search` performs keyword search over that site’s stored chunks. Its BM25 `score` is unbounded and comparable only within one response. Deployments without ParadeDB use substring matching and report `0` for every hit. For semantic similarity and `minSimilarity`, use `POST /api/v1/knowledge/search` with `corpus: "web"`; that searches the visible web corpus, not one selected site.

### Save and synchronize skill bundles

`PUT /api/v1/skills/{slug}` creates the skill when the slug is free — **201** — and updates it in place otherwise — **200** — so the status is the create-or-update signal, the same convention as materializing a task, and a sync that mirrors bundles from elsewhere needs no read first: `description` and `body` are required, an omitted `icon`, `labels`, `teams`, `visibility` or `disableModelInvocation` keeps its stored value, `null` clears `icon` or `labels`, and `disableModelInvocation: false` drops the flag.

The body is Markdown of at most 507,893 bytes of UTF-8 — bytes, not characters: the composed `SKILL.md`, frontmatter included, is capped at 512 KiB and this budget always fits inside it — and a body that does not end with a newline gets one appended, so a `GET` reads it back one byte longer. The save rewrites `SKILL.md` only — every other file of the bundle stays, and frontmatter keys the body does not carry (`license`, `recommended-packages`, community keys) are preserved; replacing a whole bundle is the app's zip upload.

Every skill names its version: `etag`, the quoted SHA-256 of its `SKILL.md`, and `updatedAt`, when that file was last written — the tag moves with every save of the document and with nothing else.

A save whose composed `SKILL.md` is byte-identical to the stored one writes nothing: it returns **200** with the stored `etag` and `updatedAt` and adds no history entry — the no-op documents and knowledge entries already follow — so a mirror that re-pushes an unchanged bundle leaves `updatedAt` a change signal; the preconditions are still evaluated first, so a stale `If-Match` on an identical body is still **412**.

`GET /api/v1/skills/{slug}` carries the tag as `ETag` and returns **304** to an `If-None-Match` that names it — the weak `W/"…"` and the edge's `"…-gzip"` forms included — with the same `Cache-Control: private, no-cache` as its **200**. `GET /api/v1/skills` also returns `failures` — bundles on disk that could not be read, each with `slug`, `path` and `message`; normally an empty array — so a listing never fails because one bundle is broken.

Guard an update or a delete with `If-Match`: the `etag` you last read — a skill whose document changed since returns **412**, `SKILL_STALE`, with the current tag in `data.etag`, and nothing is written, so reload and merge before saving again (a guarded `PUT` of a skill that is not there is the same **412** with `data.etag: null`, while a guarded `DELETE` of one answers the plain **404**, `SKILL_NOT_FOUND` — already gone is done); a weak tag (`W/"…"`) never matches, and the body is validated before the precondition is evaluated. Send `If-None-Match: *` to create only: a slug that already has a bundle then returns **412**, `SKILL_EXISTS`, and nothing is written.

`GET /api/v1/skills/{slug}/files/{path}` reads any file of the bundle — `SKILL.md` included — as raw bytes named by `Content-Disposition`, with `path` exactly as `files[].path` lists it (`/` raw or `%2F`); the read is validated — the `ETag` is the file's bytes, `Last-Modified` its modification time, and `If-None-Match` or `If-Modified-Since` answers **304** —; a path the list would never carry returns **404**, `SKILL_FILE_NOT_FOUND`, and a bundle the file layer refuses — a planted symlink, a file over the 4 MiB staging cap — **422**, `SKILL_MALFORMED`.

A raw dot-segment in the URL (`../`, or `%2e%2e/` — the dots encoded, the slash not) never reaches the route: the edge refuses it first with its own **404**, `NOT_FOUND`, an `X-Request-Id` of its own and no `X-Tale-Api-Version`; a spelling whose slashes are encoded too (`%2e%2e%2f…`) reaches the route and reads as `SKILL_FILE_NOT_FOUND`. Every skill carries `canEdit` — whether this key may edit the bundle; shipped skills are organization bundles an administrator may overwrite — so check it before a save that means to replace one. Skills support `org` and `team` visibility; `teams` must name teams in this organization.

Every skill also says who created it and who last edited it. `origin` is `release` for a skill a managed configuration release installed, `builtin` when no creator is recorded (the document skills an organization starts with), and `member` otherwise, with `owner` the creator's user ID. `ownerName` is the creator's display name while they are a member of the organization, and is absent once they have left. `updatedBy` and `updatedByName` name the member whose write through Tale produced the stored `SKILL.md`; they are absent when nobody has edited the skill since it was created, and when its file changed outside Tale since the last edit. A save that changes the skill is recorded in the organization's audit log as the key holder: `skill.created`, `skill.updated`, and `skill.sharing_changed` when `visibility` or `teams` changed (contract 3.4.0).

An organization can reserve organization-wide skills with its [skill sharing policy](https://docs.tale.dev/platform/admin/governance/policies-and-limits#skill-sharing): to Editors and above, or to Owners and Admins, plus members holding a live `tale:skills.publish` grant. A key holder outside that set gets **403**, `SKILL_PUBLISH_FORBIDDEN`, for a save that would create a `visibility: org` skill, widen one to `org`, or change an `org` skill in place; nothing is written, and the refusal is recorded in the audit log as `skill.publish_denied`. Saving with `visibility: team` and the holder's own `teams`, a byte-identical save, and `DELETE` stay open. `capabilities.skillPublish` in `GET /api/v1/me` answers the question before the first save (contract 3.5.0).

`private` skill visibility is retired: it cannot be set, and a bundle that already carries it keeps it only when the save omits `visibility`. A slug is at most 64 characters of lowercase letters, digits and single hyphens, and `anthropic` and `claude` are reserved; `PUT` refuses a malformed one with **400**, `INVALID_SKILL_SLUG`, naming the rule it breaks, while `GET` and `DELETE` answer it as absent with **404**, `SKILL_NOT_FOUND`.

### Mirror conversations and deliver replies

Create the contact with `POST /api/v1/contacts` first. A conversation snapshot links `externalContactId` to that contact's `externalId` in the organization. An unknown contact returns **404** `CONTACT_NOT_FOUND`; an ambiguous match returns **409** `CONTACT_AMBIGUOUS`. A snapshot cannot move an existing source conversation to another contact: changing its `externalContactId` returns **409** `CONVERSATION_CONTACT_CONFLICT`.

`POST /api/v1/conversations/sync` compares the integer `version` with the stored snapshot:

| Incoming snapshot | Result |
| --- | --- |
| Newer version | Apply it. |
| Older version | Ignore it. |
| Same version, different content | **409** `CONVERSATION_SNAPSHOT_CONFLICT`. |
| `deleted: true`, version equal to or newer than stored | Close the mirror. Repeating this after closure changes nothing. |

Closing preserves the conversation and messages in the Inbox. This API does not hard-delete them.

`GET /api/v1/conversations/sync` also reports the linked `externalContactId`, the bound row's `contactId`, and `contactStatus`: `active`, `trashed`, or `missing` — and `sourceDeleted` with the Inbox `status`, so an engine that resumes from the receipt knows a teardown landed: a content snapshot onto a torn-down mirror answers **409** `CONVERSATION_CLOSED` at any version (mirror the source conversation under a new `externalId` to start again). The binding keeps the original contact row. Deleting that contact moves it to trash and frees its email and external ID, but recreating those identifiers never transfers the old conversation’s history. A contact re-keyed in the CRM (a `PATCH` of its `externalId`) keeps its conversations: a snapshot naming the current id applies and the receipt follows it, while the id it no longer carries returns **409** `CONVERSATION_CONTACT_CONFLICT` naming the id the conversation is bound to. `GET /api/v1/conversations?source=` lists every conversation you mirrored under a source — `conversationId`, `externalId`, `externalContactId`, `contactId`, `contactStatus`, `version`, `sourceDeleted`, `status`, `subject` — newest first as a keyset page under `conversations` (the same `?cursor=` loop as every list), and `?contactStatus=trashed` finds the mirrors a deleted contact froze.

A newer content snapshot for a trashed contact returns `409 CONVERSATION_CONTACT_TRASHED`. Restore the contact — `POST /api/v1/contacts/{id}/restore`, which applies the create's own rule (a live contact that has since taken its email or `externalId` refuses the restore with the create's **409**), or the app's trash — before sending more content, or close the mirror with `deleted: true` at an equal or newer version; a closed mirror is not reopened by the restore, so a later content snapshot answers the same 409 while the contact stays in the trash. Older snapshots remain ignored, and same-version repeats still follow the version rules above; deleting the contact does not turn every replay into an error.

Claim replies written in the Tale Inbox through `POST /api/v1/conversations/deliveries/claim`. Before including one in a later source snapshot, acknowledge its delivery under its `externalId`, then set `taleMessageId` to the reply's `messageId`. An unacknowledged reply returns **409** `DELIVERY_UNACKNOWLEDGED`. Without `taleMessageId`, a message is treated as originating in the source system, regardless of `isCustomer`.

A claim must name a source you have mirrored. An unknown source returns **404** `CONVERSATION_SOURCE_NOT_FOUND`; one owned only by other service users returns **403** `INTEGRATION_NOT_OWNED`. A source typo therefore produces an error rather than an apparently healthy empty queue.

A claimed delivery includes `attempts`, `leaseExpiresAt`, `lastErrorCode`, and `firstClaimedAt`. Use `GET /api/v1/conversations/deliveries?source=` to inspect the queue without claiming replies. It returns status (`queued`, `leased`, `failed`, `delivered`), attempt counts, and timestamps, but no claim token or message body. Entries are ordered oldest-due first in `{deliveries, isDone, continueCursor}`; pass `?cursor=` for subsequent pages.

Filter with `?status=failed` to find dead-lettered deliveries. `POST /api/v1/conversations/deliveries/{id}/retry` retries one and records the same audit action as **Retry** in the Inbox. A delivery that is not dead-lettered returns **409** `DELIVERY_RETRY_UNAVAILABLE`.

Queue a mirrored conversation to a team with `POST /api/v1/conversations/assignment`: `{source, externalId, teamId}`, where `teamId` comes from `GET /api/v1/teams` and `null` clears it. The team's members can then open the conversation in the Inbox, and each of them is notified. As in the Inbox, only admin and owner keys may assign; an editor key returns **403** `ROLE_FORBIDDEN` and can route its source with a [conversation routing rule](https://docs.tale.dev/platform/admin/governance/policies-and-limits) instead. A team outside the organization returns **400** `TEAM_NOT_IN_ORG`, a mirror no snapshot created returns **404** `CONVERSATION_NOT_FOUND`, and one another service user owns returns **403** `INTEGRATION_NOT_OWNED`.

Stage attachments through `POST /api/v1/conversations/uploads` before referencing them in a snapshot. Invalid attachments prevent the snapshot from being applied:

| Problem | Response |
| --- | --- |
| Unstaged, expired, malformed, or cross-organization `storageId` | **400** `ATTACHMENT_NOT_STAGED`. |
| Attachment staged by another service user in the organization | **403** `ATTACHMENT_NOT_OWNED`. |
| Declared `size` differs from the uploaded bytes | **400** `ATTACHMENT_SIZE_MISMATCH`. |

`replyConstraints` limits message length, attachment count, attachment size, and file extensions for replies a person writes in the Inbox. These limits apply when composing a reply, not when accepting a source snapshot.

`GET .../deliveries/{id}/attachments/{index}` returns `DELIVERY_NOT_FOUND` if the claimed delivery does not exist. A missing attachment position, or an index outside the integers 0 through 9, returns `ATTACHMENT_NOT_FOUND`.

There is no staged-upload delete route. Unbound uploads become eligible for cleanup after their two-hour window plus a 24-hour grace period; cleanup runs on a later upload in the organization. Bound attachments follow their message's lifetime. All conversation request bodies are strict: unknown keys, including those inside messages and attachments, return **400** `INVALID_BODY` with the field name.

### Create searchable knowledge and Hub documents

`POST /api/v1/documents` can store text directly as `content`. This inline content remains readable but is not indexed. Knowledge search finds only file-backed documents, so `POST .../retry-indexing` returns `{"status": "skipped", "reason": "content-only"}` for an inline document.

Other skip reasons are `untracked-blob`, `unsupported` (terminal indexing failure; inspect `indexing.errorCode`), and `in-progress` (a fresh indexing job is already queued or running). For `in-progress`, poll the document. Retrying a file that previously opted out of indexing opts it back in and returns `indexing`.

A project file is not this endpoint's — it returns **404**, `DOCUMENT_NOT_FOUND`, like any id outside the Hub — but has the same retry at `POST /api/v1/projects/{id}/files/{documentId}/retry-indexing`, which lifts the bind-time `skipRagIndexing` opt-out (see **Verify what landed** below). Either retry runs through the same guards as the app's **Index now**, a budget of 10 per user per minute included (**429**, `RATE_LIMITED`). Its `fileId` alternative requires the key holder's own unbound Hub upload in the selected organization, created through the app; REST does not mint one.

Use `POST /api/v1/knowledge-entries` to create searchable text. It creates a file-backed Hub document with `sourceProvider: knowledge` and starts indexing. An entry allows at most 8,000 characters, with one active entry per topic. The **201** response `{id, documentId}` already contains the document ID: poll `GET /api/v1/documents/{documentId}` to follow indexing.

A `PATCH` supersedes the active entry and re-indexes under the same `documentId`. If `topic` and `content` are unchanged after trimming, it creates no version and returns the existing entry ID. A `PATCH` of a superseded row returns **409**, `KNOWLEDGE_ENTRY_SUPERSEDED`, naming the topic's active row in `data.activeId` (and its direct successor in `data.supersededBy`) — update that row, no chase down the chain. An entry created or superseded over this door reads `source: "api"` (the app's form writes `manual`, the assistant's capture `chat`), so the Knowledge entries table tells the three apart. Deleting the entry trashes its backing document.

The entry endpoints need the knowledge write grant — a read-only member returns **403**, `KNOWLEDGE_ENTRY_FORBIDDEN` — and an object store that does not accept the content within 30 seconds returns **503**, `KNOWLEDGE_ENTRY_STORE_TIMEOUT`, with nothing written. That document refuses a direct `DELETE /api/v1/documents/{id}`, or a `PATCH` of its title or content, with **409**, `DOCUMENT_HAS_KNOWLEDGE_ENTRY` and `data.entryId` — the entry is the way to change it. `GET /api/v1/knowledge-entries?topic=<topic>&status=superseded` lists one topic's replaced versions, each stamped with `supersededAt`, and `GET /api/v1/knowledge-entries/{id}/versions` returns the whole chain from any of its rows, newest first.

`GET /api/v1/documents` lists Hub documents newest first. Choose the folder scope explicitly when reproducing the app’s folder view:

| `folderId` query parameter | Documents returned |
| --- | --- |
| Omitted | All visible Hub documents, including those inside folders. |
| `root` | Only documents that are not in a folder. |
| A folder ID | Documents directly inside that folder. |

Read a document's bytes at `GET /api/v1/documents/{id}/content` — the same download choreography as a project file (`Content-Disposition`, `Range`, `HEAD`), and a content-only document returns its inline text there too, typed as its `mimeType`; `GET /api/v1/documents/{id}` carries `content` only for a content-only document, `null` for a file-backed one. Every document returns `contentHash` — the SHA-256 the platform computed for its bytes (a knowledge entry's content, a synced file), `null` otherwise — as a field of its own, never a key in your `metadata`.

A document `PATCH` that changes nothing — an empty body, or every field already at its value — writes nothing and leaves `updatedAt` alone, so a no-op retry never invalidates another client's `expectedUpdatedAt`; a controlled record's content, MIME type, extension or source provider is refused with **400**, `DOCUMENT_RECORD_FROZEN` (in review or approved) or `DOCUMENT_RECORD_REPLACEMENT_REQUIRED` (a draft — use the replacement flow), and a `teamIds` entry the key holder is not a member of with **403**, `TEAM_ACCESS_DENIED` (a team that is not the organization's is **400**, `TEAM_NOT_IN_ORG`; a repeated id collapses to one).

Every file-backed document carries `indexing` — `status` is `pending`, `queued`, `running`, `completed`, `failed`, `unsupported` or `skipped`, with `indexedAt`, `error` and `errorCode` when set — so poll the document after a create or a `retry-indexing` instead of sleeping. An upload already attached to any document, thread or conversation cannot be reused here. A missing upload, another user's upload or a bound upload returns **404**, `FILE_NOT_FOUND`. Project, chat and conversation uploads cannot become Hub documents through this route. Trashed or expired documents, including files deleted with their project, stay out of this Hub surface. Files you keep when deleting their project are detached and remain in the Hub.

Branch on `indexing.errorCode`, not the wording of `error`. The OpenAPI schema enumerates the closed set:

| Status and codes | Recovery |
| --- | --- |
| `unsupported`: `unsupported_type`, `image_no_vision`, `empty`, `not_text`, `malformed` | Replace or re-export the source in a supported format. For `not_text`, export actual UTF-8 text. `malformed` currently identifies an unreadable PDF; corrupt Office files can instead report `indexer_error`. The retry route skips terminal codes, including older rows still marked `failed`. |
| `failed`: `embedding_upstream`, `indexer_error`, `index_rebuilding` | The background job retries these failures. Poll before requesting another attempt. |
| `failed`: `embedding_not_configured`, `embedding_provider_refused`, `index_repair_failed` | Ask the operator to correct provider configuration, permissions, or index health, then retry. `embedding_provider_refused` also covers a model that answers vectors of another width than the settings state, and an embedding credential the platform cannot use (none configured, deleted, disabled, or unreadable); saving corrected embedding settings, or adding or repairing the credential the embedding model uses, re-queues every document that failed on the embedding model. |
| `failed`: `secret_detected`, `pii_blocked` | Correct the source or the organization’s approved content policy before retrying. |
| `failed` with no `errorCode` | The platform settled the failure without classifying it, usually because the indexing run stopped before it finished (a lost job or a stopped worker). Don't wait for an automatic retry: request `retry-indexing`. |

`POST` and `PATCH` bodies are strict: `projectId` is refused with **400**. Create project files through the project upload and file routes below.

## Mirror a member’s notifications

`GET /api/v1/notifications/sync`, added in API contract 1.8.0, exports the notifications a particular member can see. Use it for a one-way mirror in another application. The caller’s API key must belong to an Owner or Admin of the selected organization, or to a member an Admin granted the `tale:notifications.export` capability (API contract 1.14.0). Any other role alone, Developer included, is insufficient.

### Delegate the export without an Admin role

A mirror worker does not need an Admin account. The Admin role also manages members, administers single sign-on and SCIM, and can reset lower-ranked members’ passwords, so run the worker as an ordinary member and grant that member the one capability the export checks. The grant is an entry in the organization’s competence register: it applies only in that organization, is audited, can carry an expiry, and is revoked automatically when an Admin removes the member or SCIM deprovisions them.

An Owner or Admin grants it under **Settings > Governance > Competences** ([Competences](https://docs.tale.dev/platform/admin/governance/competences)), or over HTTP from an active session. `TALE_ORIGIN` is your Tale origin and `TALE_SESSION_COOKIE` that session’s cookie header; `TALE_ORG_ID` and `TALE_WORKER_USER_ID` are the `organization.id` and `user.id` that `GET /api/v1/me` returns for the worker’s key:

```bash
GRANT_BODY=$(jq -n --arg user "$TALE_WORKER_USER_ID" \
  '{userId:$user,competence:"tale:notifications.export",evidence:"Notification mirror worker"}')
curl -sS --compressed -X POST "$TALE_ORIGIN/api/app/governance/competences?orgId=$TALE_ORG_ID" \
  -H "Cookie: $TALE_SESSION_COOKIE" \
  -H "Origin: $TALE_ORIGIN" \
  -H "Content-Type: application/json" \
  -d "$GRANT_BODY"
```

The response is **201** with `{ "recordId": "…" }`. Add `expiresAt`, a future instant in whole epoch milliseconds no later than `8640000000000000`, to end the grant on its own; without it, the grant does not expire. A past instant returns **400** `COMPETENCE_EXPIRY_IN_PAST`, and a value that is not a whole number in that range **400** `invalid body`. While a grant is live, granting it again returns **409** `COMPETENCE_ALREADY_GRANTED`. Any other name under `tale:` returns **400** `COMPETENCE_CAPABILITY_UNKNOWN`, a user outside the organization **400** `COMPETENCE_USER_NOT_MEMBER`, and a session without the Owner or Admin role **403** `COMPETENCE_FORBIDDEN`. Before the first page, confirm with the worker’s key that `GET /api/v1/me` reports `capabilities.notificationExport: true`.

To withdraw the right, find the grant’s `id` in `GET /api/app/governance/competences?orgId=<orgId>&userId=<userId>` with the same session, then send `POST /api/app/governance/competences/<recordId>/revoke?orgId=<orgId>`. The worker’s next export request returns `403 ROLE_FORBIDDEN`. A revoked grant stays in the list as the audit trail; grant the capability again to restore the export.

### Select the recipient and stream

Set `TALE_RECIPIENT_EMAIL` to the intended member’s verified email address. The recipient must have exactly one matching, active membership in the selected organization. The endpoint checks membership and verification again on every page. Organization notifications use the recipient’s role for visibility: an administrator caller cannot export security notifications to a recipient who could not see them in Tale.

| Query parameter | Rule |
| --- | --- |
| `recipientEmail` | Required valid email, at most 320 characters; matching ignores case. |
| `stream` | Required: `personal` for the member’s personal feed, or `organization` for organization notifications visible to them. Read both separately for a complete mirror. |
| `locale` | Optional `en`, `de` or `fr`. Defaults to the organization’s language, with English message fallback. |
| `limit` | Default 100, maximum 100, minimum 1. Whole numbers outside the range are clamped. |
| `cursor` | Omit on the first request; pass the preceding `continueCursor` unchanged for the next page. There is no numeric `offset` parameter. |

```bash
curl --fail-with-body --silent --show-error --compressed --get \
  "$TALE_URL/api/v1/notifications/sync" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --data-urlencode "recipientEmail=$TALE_RECIPIENT_EMAIL" \
  --data-urlencode 'stream=personal' \
  --data-urlencode 'locale=en' \
  --data-urlencode 'limit=100'
```

A successful request returns `200` with `{recipientId, page, isDone, continueCursor}`. Missing, disabled, unverified or ambiguous recipients return `recipientId: null`, an empty `page`, `isDone: true` and an empty cursor. This is not an invitation or account-creation operation.

### Read rows and complete a scan

| Row field | Meaning |
| --- | --- |
| `id` | Stable source ID in the form `<organizationId>:<stream>:<notificationId>`. Use it for matching and upserts within that recipient’s mirror. Organization notification IDs can be shared by recipients; keep their mirrors separate. |
| `version` | A 64-character hexadecimal SHA-256 hash of the exported row before the hash is added. Content or read-state changes change it; localized title/body changes can also change it. This is a change marker, not an incrementing sequence. |
| `title`, `body` | Text rendered from Tale’s notification catalogs and parameters, limited to 500 and 8,000 UTF-16 code units respectively. Keep the chosen locale stable across scans. |
| `path` | The same organization-scoped `/dashboard/...` destination used by the notification bell, including encoded identifiers and query parameters. Resolve it against the Tale browser origin, not an internal API transport URL. The user still needs access and any required private network connection. |
| `createdAt` | Creation time in epoch milliseconds. |
| `read` | Whether the intended recipient has read the notification in Tale. |

Personal pages are ordered by descending notification sequence; organization pages by descending creation time and ID. Both expose signed keyset cursors. A cursor is scoped to the organization, recipient and stream; never reuse it for another recipient or swap streams with it.

To keep the mirror consistent:

1. Start each stream without a cursor and upsert rows by `id`, comparing `version` for changes.
2. While `isDone` is `false`, send the returned cursor. At `true`, stop; do not send the empty final cursor.
3. Finish both streams successfully before retracting destination rows absent from this scan. If any page fails, preserve the previous mirror and recover the failed scan.
4. Begin later scans from the first page to notice read-state or text changes in older notifications. A cursor is a pagination position, not a change-feed checkpoint.

Reading the export never marks a Tale notification read and never deletes it. The endpoint provides no acknowledgement or write-back operation. Changing the destination’s read state does not change Tale’s.

### Recover an export request

| Response | Action |
| --- | --- |
| `401 UNAUTHORIZED` | Replace the missing, invalid or expired API key. |
| `403 ROLE_FORBIDDEN` | Use an Owner or Admin key in the selected organization, or have an Admin grant the key’s user `tale:notifications.export`; `capabilities.notificationExport` in `GET /api/v1/me` confirms it. An expired or revoked grant no longer permits the export. Recipient membership does not grant the caller export permission. |
| `400 INVALID_QUERY` | Correct missing or invalid recipient/stream/locale fields, unknown or repeated parameters, or blank cursor/limit. Inspect `data.issues`. |
| `400 INVALID_LIMIT` | Supply an integer limit. |
| `400 INVALID_CURSOR` | Restart the affected stream without a cursor. A removed or changed recipient can invalidate a cursor because membership is checked again. |
| `200`, `recipientId: null` | Check the recipient’s current membership and verified email. An empty completed page is not proof that an account exists. |
| `429 RATE_LIMITED` | Respect `Retry-After` and the [shared API budget](https://docs.tale.dev/develop/rate-limits); retain the previous mirror while waiting. |

The normal organization-selection errors also apply. Never replace a failed export with an empty successful result in the destination.

## Manage a project's agents

Every agent belongs to a project. The project ID is required in the URL for every operation; responses include both `projectId` and the agent's `id`. These are the same agents managed in the project's **Agents** tab, with the same access rules.

| Operation               | Route                                           | Success        |
| ----------------------- | ----------------------------------------------- | -------------- |
| List the roster         | `GET /api/v1/projects/{id}/agents`              | `200 {agents}` |
| Create                  | `POST /api/v1/projects/{id}/agents`             | `201 {agent}`  |
| Read                    | `GET /api/v1/projects/{id}/agents/{agentId}`    | `200 {agent}`  |
| Save full configuration | `PUT /api/v1/projects/{id}/agents/{agentId}`    | `200 {agent}`  |
| Delete                  | `DELETE /api/v1/projects/{id}/agents/{agentId}` | `204`          |

Choose an existing project, a harness `GET /api/v1/models` lists under `harnesses` — the ones the platform runs with its own credentials — and a model available to it. This example creates a Claude Code agent and reads back its configuration; it does not start a task.

```bash
: "${BASE:?Set BASE to your Tale origin}"
: "${TALE_API_KEY:?Set TALE_API_KEY}"
: "${ORG_SLUG:?Set ORG_SLUG}"
: "${PROJECT_ID:?Set PROJECT_ID to an existing project ID}"
: "${MODEL_ID:?Set MODEL_ID to a model served by your harness}"
AGENT_URL="$BASE/api/v1/projects/$PROJECT_ID/agents"
AGENT_BODY=$(jq -n --arg model "$MODEL_ID" \
  '{name:"Reviewer",harness:"claude-code",model:$model,skills:[],connectors:[]}')
AGENT_ID=$(curl -fsS "$AGENT_URL" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $ORG_SLUG" \
  -H 'Content-Type: application/json' -d "$AGENT_BODY" | jq -er '.agent.id')
curl -fsS "$AGENT_URL/$AGENT_ID" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $ORG_SLUG" \
  | jq '.agent | {name, harness, skills, connectors}'
```

```json
{
  "name": "Reviewer",
  "harness": "claude-code",
  "skills": [],
  "connectors": []
}
```

### Save a full agent configuration

`POST` and `PUT` require `name`, `harness`, `model`, `skills` and `connectors`; a `harness` outside the eligible set returns **400**, `PROJECT_AGENT_HARNESS_INVALID`, with the set in `data.harnesses`. Optional fields are `modelProvider`, `tools`, `secrets` and `instructions`. A `PUT` saves the full configuration: omitted provider/instructions reset to `null`, and omitted tools/secrets reset to empty lists. It updates an existing agent; it does not create one at an unknown ID. Pass the `updatedAt` you last read as `expectedUpdatedAt` to make the save conditional: an agent that changed since returns **409**, `PROJECT_AGENT_STALE`, with the current `updatedAt` in `data`, and nothing is written — reload it and merge before saving again.

An agent whose `managed` is `true` is the organization's [standard agent](https://docs.tale.dev/platform/projects/project-agents#standard-agent): Tale set it up in a project without agents of its own and keeps its runtime, model and instructions in line with the organization's settings. A `PUT` of it returns **409**, `PROJECT_AGENT_MANAGED`, and writes nothing; `DELETE` removes it like any other agent (contract 3.9.0).

### Validate models, grants, and limits

A project holds at most 50 agents. Names are unique within the project without regard to case, up to 120 characters; each equipment list allows 25 entries and instructions allow 20,000 characters. An invalid configuration or an exceeded limit returns **400**; a name another agent of the project already carries returns **409**, `PROJECT_AGENT_NAME_TAKEN` — the class every other duplicate on this endpoint returns, so reuse the existing agent rather than retrying.

`model` must be a model the organization's catalog lists (name `modelProvider` when several providers serve it) and `tools` must name known tool grants — a wrong value returns **400** with `PROJECT_AGENT_MODEL_INVALID`, `PROJECT_AGENT_PROVIDER_UNKNOWN` or `PROJECT_AGENT_TOOL_UNKNOWN` naming what to fix, instead of an agent that fails at its first task. `task_start_agent` lets the agent put another agent of the same project to work on a task (contract 3.8.0). `secrets` contains organization secret names, never values; a name the organization has not stored is refused with **400**, `PROJECT_AGENT_SECRET_UNKNOWN`, naming it in `data.secrets` (the app's dialog prunes such names; the API does not, so a typo never yields an agent that runs without its credential).

`task_update_metadata` is an optional project-agent grant (contract 3.10.0) for changing an existing task’s priority and agent assignment without execution. Its request names `taskId`, `priority` and/or `agentId`, plus the current value of each touched field in `expected`; `null` clears a value and omitted fields stay untouched. Build `expected.assignee` as `{type, id}` from `task_get`’s `assigneeType` and `assigneeId`, or use `null` when unassigned; an absent priority is `null`. A stale value refuses the whole request. The [project-agent guide](https://docs.tale.dev/platform/projects/project-agents) explains the protected review and live-run states. `task_upsert_by_external_ref` still uses `priority` only when creating a task.

`task_review` adds an optional project-agent grant in contract 3.11.0. It decides only a pending native review assigned to the live reviewer agent, for a completed run by a different agent in the same project. Pass `taskId`, `expected: {approvalId, runId, evidenceRevision}` from the current `task_get.pendingReview`, `decision: "approve" | "request_changes"`, nonempty `feedback`, and `evidence: {checks, pullRequests}`. Each check names its outcome (`passed` or `failed`) and details; a supplied GitHub pull request names its URL, exact `headSha`, and check state. Approval requires every supplied check to have passed. GitHub evidence is the agent's attestation, not a remote verification by Tale.

The tool rechecks the current grant, live issuer authority, recorded reviewer, implementation run, and local evidence revision. A stale result requires another read; changing the current assignee does not establish independence. Approval moves the task to `done`; `request_changes` moves it to `todo` with feedback and no execution, even if the feedback contains a mention. Human competence requirements and workflow approval gates remain outside this tool. There is no public REST endpoint for an agent verdict.

Since contract 3.15.0, native `task_get.agentRuns` includes an explicit `retryPending` boolean. Only the newest failed run of an existing agent can have `true`, using the same armed-retry, retirement and retry-budget checks as the task card. Preserve that retry. `false` does not authorize a restart or supply a provider reset time; an absent field on an older platform is unknown. Reconcile the current task, assignee, runs and review before acting, and honor provider waits and admission `retryAfter`. This adds no public REST endpoint or raw error text.

Contract 3.13.0 adds guarded repair admission to the existing native `task_start_agent` grant: pass `{taskId, resumeFrom: {kind: "review_repair", approvalId, runId}, feedback?}` for a recorded native `request_changes` decision. The server derives the implementation agent, feedback and feedback comment ID. It atomically requires the same latest settled source, unchanged implementation assignment, `todo`, no newer review or intervening status/assignment/archive decision, and the existing admission limits. An explicit `agentId` must match that source; `moveToInProgress: false` is refused. Untagged `{approvalId, runId}` retains its separate pending-question meaning. `stale_repair` starts nothing; do not fall back to an unguarded start.

A successful repair returns `started`, `runId` and `repairReceipt` with `taskId`, `approvalId`, `sourceRunId`, `feedbackCommentId`, `implementationAgentId`, admitted `runId`, `managerAgentId`, original `issuerRunId` and `admittedAt`. The same manager agent may recover it from a later live authorized run with `replayed: true`; every call rechecks current delegation and project authority, and replay has no effects. `task_get.reviewDecision` exposes one latest validated native verdict receipt, or `null` behind a newer pending, human or workflow review or unavailable metadata. It is historical evidence, not current task state; `null` does not prove a verdict was uncommitted. These additions create no public REST repair endpoint and do not make a verdict dispatch work.

Contract 3.12.0 also extends the native task tools. `task_find` accepts `reviewerAgentId` and returns `pendingReview: null` or `{approvalId, runId, reviewer}` per task. The filter matches the captured pending agent reviewer and is part of the signed cursor’s query identity; keep it unchanged when paging. It does not filter by the implementation assignee.

For a captured agent review with a usable source, `task_get.reviewFiles` returns `{expected, files, page, maxStageBytes}`. It lists up to 50 attachments and outputs; pass `page.continueCursor` back as `reviewFileCursor` while `page.isDone` is false. The cursor is bound to the task, reviewer, approval, source run and evidence revision. Entries carry their stored metadata and `unavailableReason`, or an explicit invalid-metadata reason when no safe file identity exists. An absent stored `runId` is not inferred.

The same `task_review` grant accepts `{operation: "stage_file", taskId, expected: {approvalId, runId, evidenceRevision}, fileId}` to stage one listed, available file of at most 20 MiB. It accepts no caller path, storage reference or URL. The response names the server-selected local `path` and `bytes`; the agent must read that file before attesting to its contents. Current task membership, captured review, live issuer, grant and policy are checked before transfer and again before success. Protected document bindings keep their document access rules; unsupported or unavailable files are refused. A concurrent revocation or handoff can leave previously authorized bytes in the workspace while refusing success and any stale verdict. This is a native tool operation, not a new public REST file or verdict endpoint.

Only organization Owners and Admins may change secret grants, so an editor's full save must preserve existing grants.

Project readers can read the roster; writes require project edit access and an active project. An invisible or missing project, or an agent ID from another project, returns **404**. A multi-organization key must include `X-Organization-Slug` on reads and writes. [Project agents](https://docs.tale.dev/platform/projects/project-agents) explains how these agents work on tasks; direct chat keeps using the built-in assistant.

## Automation names in URLs

An automation's name is a `/`-separated path — `billing/dunning` — and a path cannot travel inside one URL segment. In every `.../automations/{name}/...` URL, write the name with `__` in place of each `/`:

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/automations/billing__dunning/versions" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG"
```

Responses always carry the real name (`"name": "billing/dunning"`); the `__` form exists only in URLs. Skill slugs are flat and need no encoding. Project agents use their project ID and agent ID.

### Read the version that will run

`GET /api/v1/automations` lists each automation with its `latestVersion`, `deployedVersion` and `projectIds` — the projects it is installed in, which the run routes below require — plus what a launcher needs without a second call: its `description`, the `inputs` schema a run must match (the deployed version's, else the newest saved one's) and its `trigger` — kind, switch and health: `lastFiredAt`, `lastSkippedAt` and `lastSkipReason`, the same stamps `GET .../triggers` reads, so one listing call finds every binding that is enabled and not firing — or `null` when none is bound.

`GET /api/v1/automations/{name}` returns the newest saved version by default (`?version=latest` spells the default out), which may be a draft; a live run executes the deployed one, so read the contract of the code that actually runs with `?version=deployed` (a number names any saved version). A version the automation does not have returns **404** `AUTOMATION_VERSION_UNKNOWN` — `?version=deployed` while nothing is deployed too — where an unknown automation returns `AUTOMATION_NOT_FOUND`.

`GET /api/v1/automations/{name}/versions` names the `deployedVersion` and marks each row `deployed`, and each row carries the version's test verdict: `testsPassed` is `null` until the tests were run (a document without tests stays `null`), else `true` or `false` for the last run — the save's, when the MCP `save_automation` saves a document with tests, or the deploy gate's, which persists a refusal — with `testsCheckedAt` saying when — `null` beside a verdict recorded before 0.5.24 kept the time, so branch on `testsPassed` for the verdict and on `testsCheckedAt` for its freshness only; the latest verdict wins.

`DELETE /api/v1/automations/{name}` removes the automation, its versions, triggers and project bindings included — its runs stay: they remain listed by `GET /api/v1/runs`, readable by id, and still answered by name at `GET /api/v1/automations/{name}/runs` (and its project twin) under the name they ran as, which `GET /api/v1/automations/{name}`, its versions and its triggers then return **404** for — and returns **409** `AUTOMATION_HAS_ACTIVE_RUNS` while a run is in flight; it needs the developer capability. Creating, saving and deploying an automation is not on this surface: that is the [MCP endpoint](https://docs.tale.dev/develop/mcp-endpoint)'s `save_automation` and `deploy_automation`, the app's canvas, or a `tale deploy` configuration release — REST lists, reads, runs, installs and wires triggers for automations built there.

## Triggers

A trigger starts an automation without a call from you: on a schedule, from a webhook URL, or when the platform raises an event. Bind one with `PUT /api/v1/automations/{name}/triggers` — one trigger per automation, and the `PUT` replaces whatever was bound:

```bash
curl -sS --compressed -X PUT "https://your-host.example.com/api/v1/automations/billing__dunning/triggers" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "event", "event": "contact.created" }'
# → 200 { "name": "billing/dunning", "deployed": true }
```

### Choose the trigger kind

`kind` is `schedule` (with a five-field `cron` and an optional IANA `timezone`), `webhook` (the response carries the URL's `token` once — the [Webhooks page](https://docs.tale.dev/develop/webhooks) covers that endpoint) or `event`. A trigger that could never fire is refused with **400** `AUTOMATION_TRIGGER_INVALID` and a sentence naming the fix: a cron that matches nothing (including a day no named month has, `0 0 30 2 *`), a time zone that is not an IANA zone, an event the platform does not raise.

Each kind takes its own keys — `cron` and `timezone` only with `schedule`, `event` only with `event`, `rotateToken` only with `webhook` — and a key that belongs to another kind is refused as an unknown key (**400** `INVALID_BODY`, naming it under `data.issues`), so a webhook trigger can never read back as one that also runs on a schedule. An event trigger binds one of the events the platform raises today, and the run's input is `{ "trigger": "event", "event": "<name>", "payload": <the event's data> }`:

| Event                                                   | Raised when                                                                                                             |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `contact.created`, `contact.updated`, `contact.deleted` | a contact is created, changed or deleted — through the API, the app or an import                                        |
| `conversation.created`                                  | a conversation opens in Inbox — an email arriving, or an external conversation mirrored in                              |
| `conversation.message_received`                         | a message lands on an existing conversation                                                                             |
| `project.created`                                       | a project is created                                                                                                    |
| `task.created`                                          | a task is created — on a board, through the API, or by an intake                                                        |
| `task.status_changed`                                   | a person moves a task to another status (an agent's own moves raise nothing, so an automation cannot re-trigger itself) |
| `comment.created`                                       | a comment lands on a task                                                                                               |
| `comment.mentioned`                                     | a task comment mentions someone with `@`                                                                                |

### Check trigger health and pause safely

`GET .../triggers` reads the binding back — as `triggers`, a list of at most one, the one plural in the family — with its health: `lastFiredAt` is the last time this binding **started a run** — `lastRunId` names it, and both stay `null` until it has — while `lastSkippedAt` and `lastSkipReason` record the last time it came due and started nothing: `not_deployed` (nothing is deployed — deploy a version), `unusable_cron` (the expression or zone could not be read; the scheduler leaves the binding alone until it is edited), `start_refused` (the deployed version's `inputs` schema refused the run's input) or `paused_after_failures` (a schedule that turned itself off after repeated failures — see below). A webhook delivery the deployed `inputs` schema refuses is a different case: it is answered **400** `AUTOMATION_INPUT_INVALID` to the sender and starts nothing, and it moves none of these stamps — the binding did not come due, so a webhook whose every delivery is refused reads the same as one that has never been called. Verify deliveries from the sender's side.

A binding is alive when `lastFiredAt` keeps pace with its cadence; one whose `lastSkippedAt` is the newer stamp is coming due and not running, and the reason says what to fix. A rebind to another kind starts every stamp afresh. `enabled: false` pauses a trigger without losing it; `DELETE .../triggers` removes it — and, for a webhook, revokes the URL. So does binding another kind over a live webhook: the `PUT` still returns **200**, with `"revoked": "webhook"` beside the name, and the old URL is gone for good — a later webhook bind mints a different token.

A schedule whose runs keep failing pauses itself. `consecutiveFailures` counts the runs this binding started that failed in a row with a `failureCode` the next occurrence would repeat — `node_error`, `connector_error`, `llm_output_invalid`, `auth_error`, `missing_api_key`, `credit_exhausted` or `model_not_found` — and `lastFailedAt`, `lastFailureCode` and `lastFailedRunId` name the last of them. A success sets the count back to `0`, and any other failure neither counts nor resets it. A schedule that has paused itself (`enabled: false` with `lastSkipReason: "paused_after_failures"`) is the exception: it keeps the count that paused it, even when a run still in flight at the pause succeeds afterwards, and only a `PUT` clears it. When a schedule's count reaches five, the platform sets `enabled: false` and `lastSkipReason: "paused_after_failures"`, writes an `automation.trigger.paused` audit row, and notifies the organization's Owners and Admins. Fix the automation, then `PUT` the trigger with `enabled: true`. Every `PUT` resets the count and clears that reason, and one that omits `enabled` turns the trigger back on, since `enabled` defaults to `true`. Webhook and event bindings keep the count but are never paused (contract 3.1.0).

The `PUT` also returns `deployed`: binding before deploying is accepted, and a trigger bound to an automation with no deployed version starts nothing — every occurrence is skipped as `not_deployed`, which the row's `trigger` on `GET /api/v1/automations` shows — until a version is deployed.

## Start a run, then poll it

A run is durable and may take minutes, so starting one returns **202** with the run's identity, not its result:

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/automations/billing__dunning/runs" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "customerId": "cus_123" } }'
# → 202 { "runId": "...", "version": 2, "name": "billing/dunning", "mode": "live" }
```

### Interpret running and waiting states

Poll `GET /api/v1/projects/{id}/runs/{runId}?fields=status,finishedAt` until `status` leaves `queued`/`running`/`waiting` — naming the keys keeps the poll to a line instead of the whole run, and sending the answer's `ETag` back as `If-None-Match` turns an unchanged poll into a bodiless **304** ([caching](https://docs.tale.dev/develop/api-reference#caching-compression-and-partial-reads)); then read the run in full: it carries `output`, the per-node `trace`, and the `effects` it produced.

`waiting` covers two families and only one needs you: while a run is parked, `waitingFor` says on what — `approval` (a person's decision on a gate) and `ask` (a question a person has to answer) need a human; `agent` (an agent turn still running), `room` (an agent turn whose start waits for sandbox room, since contract 3.14.0) and `repeat` (a node polling until its `repeatUntil` condition holds) do not, and a run can sit in any of them for minutes while healthy. "Runs that need a person" is `waitingFor` in (`approval`, `ask`) — never `status=waiting` alone, which fills with polling runs. `detail` names the park (`approval:<approvalId>`, `agent:<nodeId>`, `room:<nodeId>`, `repeat:<nodeId>`) and, once failed, the failure sentence.

Failed runs expose a stable `failureCode` alongside the human-readable `detail`. Non-failed runs return `null`; older failed records can also have no code. Run summaries omit an unset code.

A run a trigger started (`startedBy: "trigger:<id>"`) also carries `startedVia` — `schedule`, `webhook` or `event` — read off the run's own input, so a listing tells a scheduled run from a webhook delivery, and an old run keeps its kind after the binding changes. Runs a person or an API key started omit it (contract 2.1.0).

| Failure family | Examples and next action |
| --- | --- |
| Automation engine | `node_error`, `connector_error`, `llm_output_invalid`, `approval_rejected`, `execution_limit`, `automation_deleted`: inspect the failed node and its trace. Correct the input or definition; if a person rejected an operation, address their reason before requesting another run. |
| Model provider | Codes such as `credit_exhausted` or `rate_limited`: resolve the provider condition before another attempt. |
| Agent execution | Codes such as `harness_error`, `session_gone`, `deadline`, or `budget_exceeded`: inspect the agent’s detail and limits. The complete enum is in OpenAPI. |

A failure code identifies the cause; it does not make a whole-run retry safe. Earlier nodes may already have changed external systems. `startedAt` records when the start was accepted, before a worker claims it. There is no separate pickup timestamp, so `finishedAt - startedAt` includes queueing and other waits.

`POST /api/v1/projects/{id}/runs/{runId}/cancel` stops a run at its next node boundary; completed work is not undone. The response includes `cancelled` and the resulting `status`. A successful cancellation returns `cancelled: true`, `status: "cancelled"`, and clears the run’s `detail`. If the run already finished, `cancelled: false` accompanies its terminal status (`success`, `failed`, or `cancelled`).

### Retry a start without creating another run

A start is safe to retry when you name it: send `Idempotency-Key: <your key>` and a repeat within 24 hours — a retried timeout, a lost response — returns **202** with the run the first attempt started and `"duplicate": true`, so no second run exists; the same key with a different body returns **409** `IDEMPOTENCY_KEY_REUSED`. The key is scoped to the automation and the URL project, and a refused start remembers nothing, so the same key runs once the refusal is fixed.

An optional `Idempotency-Key` must contain 1–255 printable ASCII characters after surrounding whitespace is removed. A header that is present but blank, too long, or contains other characters returns `400 INVALID_HEADER` with the header named in `data.issues`; nothing starts. Reuse the same trimmed value and body for a retry. Omit the header only when you do not want replay protection.

### Choose live or mock execution

`mode` defaults to `live`; arbitrary live runs and run cancellation require `capabilities.developer` from `/me`. Project runs also require edit access to an active project, including `mode: "mock"`. Mock runs use deterministic mocks; a non-project mock run needs only membership. Starting a run needs no trigger. An automation with no deployed version returns **409** unless a saved version is explicitly selected for a mock run.

An unknown automation returns **404**. A live run can only use the deployed `version`; naming another saved version returns **409**. Use `mode: "mock"` to test another saved version. A missing body means `{}`, but malformed JSON returns **400** and starts nothing. When the automation declares an `inputs` schema, the input must match it before a run is created: a mismatch returns **400** `AUTOMATION_INPUT_INVALID` with every problem under `data.issues` (`path`, `message`), the way a refused body does. `input` defaults to `{}` only when it is absent — `null` is sent as null, for the schema to judge.

### Select scope and browse run history

The project in the URL is the context for the run's task and document tools. An automation with project bindings can run only in a bound project; one with no bindings runs in any project the caller can edit — installing it (`POST /api/v1/projects/{id}/automations/{name}`) lists it under that project and scopes it, it is not a gate a never-bound automation has to pass. `GET /api/v1/projects/{id}/automations/{name}/runs` lists that project's history for one automation, `GET /api/v1/projects/{id}/runs` for every automation.

Listings answer summaries — identity, scope, status and timing, each row naming the run as `id` and, under the name the start answered, `runId`, one value under both names — newest first as `{ "runs": [...], "isDone": ..., "continueCursor": ... }`: add `?status=failed` (one or more statuses, comma-separated) to narrow them, `?include=input,output` (also `trace`, `effects`, `checkpoints`) to inline the full-row fields a summary leaves out — an inlining page reads at most 25 rows, is bounded at 8 MiB of them, and ends early, `isDone: false`, when the next row would not fit — and pass `continueCursor` back as `?cursor=` until `isDone`.

`GET /api/v1/runs` is the cross-cutting view: every run the key holder can see, organization runs and the runs of visible projects alike, each row naming its `projectId`. For an automation with no bindings, `POST /api/v1/automations/{name}/runs` starts a non-project run; a bound automation returns **409** there. `GET /api/v1/automations/{name}/runs` and `/api/v1/runs/{runId}` expose only non-project runs. A project run requires its project URL for reading, cancellation and deletion. `DELETE /api/v1/projects/{id}/runs/{runId}` (or `/api/v1/runs/{runId}`) removes a finished run — stored input and output included — under the developer capability; a run still in flight returns **409** `RUN_ACTIVE`, so cancel it first.

## Act for a member: answer a run’s question, decide a task’s review

A run parked on `waitingFor: "ask"` waits on a person; a task in `in_review` can wait on a person or a designated agent. These two REST doors relay a person's gesture from another application and name that person as `actor`, so Tale records the person rather than the key. Both doors need API contract 1.16.0; contract 3.11.0 adds the explicit refusal of human approval while a task review belongs to an agent.

### Answer the question a run is waiting on

`GET /api/v1/projects/{id}/runs/{runId}/ask` answers the live question as `PendingAsk` — the sentence, an optional structured `questions` set, the node that asked and the `expiresAt` deadline — or `ask: null` when nothing waits on a person. Reading it takes the same access as reading the run.

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/projects/<projectId>/runs/<runId>/ask" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "ask": { "askId": "...", "question": "...", "expiresAt": 1758210000000, "taskId": "..." } }
```

Send the answer to `POST /api/v1/projects/{id}/runs/{runId}/asks/{askId}`. Tale records it, resumes the run in the same transaction, and puts the answer on the task timeline as the answerer’s own comment. For a `questions` set, send one line per question the way the app does: `<question> → <picked label>; <typed text> (in their own words)`.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/runs/<runId>/asks/<askId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "answer": "Book it in February.", "actor": { "email": "reviewer@example.com" } }'
# → 200 { "ok": true, "askId": "...", "runId": "...", "answeredBy": "<userId>", "actorUserId": "<userId>", "taskId": "..." }
```

A project run needs write access to an active project; an organization run needs membership. Without `actor`, the key answers as itself and `answeredBy` reads `api-key:<userId>`. A question that was already answered or closed returns **409** `HUMAN_ASK_NOT_PENDING`, one past its deadline **409** `HUMAN_ASK_EXPIRED` — the run then fails with `failureCode: "ask_expired"` — and a question this run did not ask **404** `HUMAN_ASK_NOT_FOUND`. A blank answer returns **400** `EMPTY_ANSWER`.

### Decide a task’s review

`GET /api/v1/projects/{id}/tasks/{taskId}/review` answers the task's status and its pending `TaskReview`, or `review: null`. Since contract 3.11.0, `reviewer` is `{kind: "user", userId}`, `{kind: "agent", agentId}`, or `null`; `implementationAgentId` identifies the actual source agent and `evidenceRevision` identifies the current local review evidence, both nullable. `requestedFor` remains the human compatibility field and is `null` for an agent; `agentSlug` is display text, never source identity. A `POST` on this path relays a human decision and requires `actor`:

Contract 3.12.0 adds `agentReviewBlockedReason`: `null`, `reviewer_unavailable`, `permission_missing`, `source_required`, `source_changed`, `self_review`, `human_policy`, or `policy_unavailable`. The same diagnosis appears in native `task_get.pendingReview`. It is derived from current authority and source, never a new review state or an automatic transfer. Source-less submissions and new reviews under a human independence or competence policy use the human chain; already captured agent reviews require explicit handoff.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/tasks/<taskId>/review" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "decision": "approve", "actor": { "email": "reviewer@example.com", "userId": "<userId>" } }'
# → 200 { "task": { "id": "...", "status": "done" }, "decision": "approve", "approvalId": "...", "actorUserId": "<userId>" }
```

`approve` is the board’s move to Done: the member’s own right to change the task (an Editor or higher, or the member who created it or is its person assignee) and the organization’s `review_policy` apply exactly as there (**403** `REVIEW_INDEPENDENT_REVIEWER_REQUIRED` or `REVIEW_COMPETENCE_REQUIRED` when the policy refuses them), the review is recorded as approved by the member, and the task becomes `done`; a task with open subtasks returns **409** `TASK_HAS_OPEN_SUBTASKS`. `request_changes` needs `comment` and `workflowSlug`: it withdraws the review, puts the comment on the timeline and starts the workflow again on the task, which reads the comment as feedback; the answer carries the `runId` to poll, with `started: false` when a live run was reused. A task that is not in review returns **409** `TASK_NOT_IN_REVIEW`. Every decision is audited as `task.review_relayed`, naming the member and the key that relayed for them.

Human `approve` also reads the current policy strictly. Invalid or unreadable `review_policy` configuration returns **409** `TASK_REVIEW_POLICY_UNAVAILABLE`, even after an explicit agent-to-person transfer; no approval or completion is recorded. Restore valid configuration and read the review again. A genuinely absent optional policy remains supported. This refusal does not add a policy-approval gate to `request_changes` or withdrawal.

Approving a review assigned to an agent returns **409**, `TASK_AGENT_REVIEW_REQUIRED`. An Editor must explicitly [transfer the pending review](https://docs.tale.dev/platform/projects/tasks#transfer-review) to an eligible person before this human approval endpoint can accept it. Do not impersonate the agent in `actor` or treat a missing human `requestedFor` as an unowned review.

### Name the member the gesture is for

`actor.email` names the member by e-mail. Tale resolves it against the organization with the same rule as the notification export: exactly one active membership whose address is verified. No such member returns **404** `ACTOR_NOT_FOUND`, two **409** `ACTOR_AMBIGUOUS`, an unverified address **403** `ACTOR_UNVERIFIED`, a disabled membership **403** `ACTOR_DISABLED`. Every answer returns the resolved `actorUserId`; pin it as `actor.userId` on later calls, and an address that has since moved to another account returns **409** `ACTOR_REBOUND` instead of acting as its new holder. A member who may not see the project — or, on the review door, not change its task — returns **403** `ACTOR_FORBIDDEN`; the key holder's own access is checked first, so this code always speaks of the actor.

Naming an actor is a right of its own. An Owner or Admin key has it by role; any other key holder needs the `tale:rest.act-as` capability, granted and revoked exactly like the export capability in [Delegate the export without an Admin role](https://docs.tale.dev/develop/api-reference#delegate-the-export-without-an-admin-role), with `"competence":"tale:rest.act-as"` in the grant body. `GET /api/v1/me` answers it as `capabilities.actAs`; an `actor` sent without it returns **403** `ROLE_FORBIDDEN` before any member is looked up. The member’s own permissions still decide what the relayed gesture may do.

## Send a message, then poll the turn

Project chat follows the same 202-then-poll shape. Use a project you can read, create a thread, post a message, poll the generation, then read the messages:

### Choose a callable model

List models before sending a message. Each entry carries what a client needs to choose — `contextWindow`, `maxOutputTokens`, `capabilities` (`tools`, `vision`, `reasoning`), `pricing` when the catalog publishes one, `tags` — and `default: true` marks the organization’s pick for this key holder; it appears only when the organization pins a default model, so do not wait for it. Use an entry’s `id` as `model`; add its `providerSlug` when the same id is listed under more than one provider.

`maxOutputTokens` is omitted when the catalog declares no ceiling; the send route then has no catalog ceiling to enforce. Do not require this field when reading the model list.

The list respects the organization’s model-access policy and includes only models callable directly through REST; an empty list means no chat model is available to this key holder.

`capabilities` and `tags` describe the model, not what this surface can send it: the REST send is text only (`content`), so a `vision` model reads an image here only when the thread was continued from the app with an image attachment — a data URI pasted into `content` reaches the model as text and is answered as text, and nothing on the wire marks it; image input over REST is not offered in this version.

The list is the organization’s configured catalog, not a promise from the provider’s account: an operator excludes a model the provider’s plan does not cover through the credential’s model allowlist in Settings. The pair is checked on send, at the endpoint: an id the list does not carry returns **400**, `CHAT_MODEL_UNKNOWN`; an id several providers serve, with none named, **400**, `CHAT_MODEL_AMBIGUOUS` with the candidates in `data.providers`; a `providerSlug` the list does not carry **400**, `CHAT_PROVIDER_UNKNOWN`, and one that does not serve the chosen `model` **400**, `CHAT_MODEL_NOT_ON_PROVIDER`.

The 202 names the provider the turn runs on, and the turn never falls back to another provider behind your back.

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/models" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# No available model → 200 { "models": [] }
```

```bash
# 1. A thread of your own
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/threads" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" -d '{}'
# → 201 { "id": "<threadId>" }

# 2. Send a message — on this API the model is always explicit, never auto-selected
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/threads/<threadId>/messages" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Summarise this quarter for me.", "model": "<model-id>", "providerSlug": "<provider-slug>" }'
# → 202 { "threadId": "...", "status": "accepted", "model": "...", "providerSlug": "...", "messageId": "<assistantMessageId>", "poll": "/api/v1/projects/<projectId>/threads/<threadId>/generation" }

# 3. Poll until idle, then read
curl -sS --compressed "https://your-host.example.com/api/v1/projects/<projectId>/threads/<threadId>/generation" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "status": "queued", "messageId": "..." } … then { "status": "streaming", "messageId": "...", "text": "The quarter…", "textOffset": 0, "textLength": 12, "reasoning": "", "reasoningOffset": 0, "reasoningLength": 0, "cancelRequested": false, "updatedAt": 1774... } … then { "status": "idle", "lastMessageId": "<assistantMessageId>", "lastStatus": "complete" }

# 4. Read the reply by the id the 202 named
curl -sS "https://your-host.example.com/api/v1/projects/<projectId>/threads/<threadId>/messages/<assistantMessageId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "id": "<assistantMessageId>", "role": "assistant", "status": "complete", "finishReason": "stop", "parts": [ … ], "usage": { … }, … }
```

### Poll your accepted message

Keep the `messageId` returned by the send's `202`: this is the assistant message that will contain your result. Poll generation every two to five seconds and inspect its state:

Accepted chat messages share one oldest-first queue across the deployment’s organizations and keys. The background worker processes batches of up to `WORKER_CONCURRENCY` turns (default 5), and the next batch waits for the current batch to settle. Acceptance is not immediate execution; a quiet thread can wait behind work from other clients. The API does not expose queue position or an estimated start time.

| Generation state | Meaning and next action |
| --- | --- |
| `queued` | Accepted and waiting for a worker; keep polling. Until a worker opens the turn this poll is its only view: `GET .../messages` does not list the turn yet (the page reads complete without it) and `.../messages/{messageId}` can answer **404** for the id the send named |
| `streaming` | The provider is producing output; `text` and `reasoning` contain the current partial result |
| `idle`, matching `lastMessageId` | Your turn has settled; `lastStatus` describes its outcome |
| `idle`, different `lastMessageId` | The summary refers to another message; read your saved message ID directly before drawing a conclusion |

Read the result at `GET /api/v1/projects/{id}/threads/{threadId}/messages/{messageId}`. To browse the transcript newest first, use `GET .../messages?order=desc`; a cursor stays bound to the direction in which it was issued. A later turn can change the latest-message summary, so a different ID is not evidence that your earlier turn never ran.

Set a timeout for each poll request and a separate overall deadline for your client; 30 seconds per ordinary poll is a reasonable starting point. The server has no fixed total turn deadline. It abandons a provider request after 180 seconds without activity, and each received byte, including reasoning output, resets that timer. High reasoning effort can therefore keep a turn active before any answer text appears. If you no longer need the turn, call `DELETE .../generation` rather than merely stopping your polling loop.

For incremental updates, send the previous `textLength` as `since` and `reasoningLength` as `reasoningSince`. The unit is UTF-16 code units — JavaScript `String.length`, an emoji counting two; not code points — so echo the lengths the poll answered rather than counting characters yourself. The response's `textOffset` and `reasoningOffset` locate the returned slices: the value you sent, one lower when that would have split a surrogate pair (the slice then re-sends the whole character), or 0 when a completed tool round reset that stream. Reassemble by one rule, `held = held.slice(0, textOffset) + text`, and none of the three cases needs its own handling.

If the send response was lost, read `.../generation` before sending again. `queued` or `streaming` identifies the active turn. When idle, inspect the latest assistant message or find your newest user message by its `content`; without a saved message ID, do not assume an unrelated latest result belongs to the lost request.

### Retry a send safely

A send is safe to retry when you name it: send `Idempotency-Key: <your key>` and a repeat within 24 hours — a retried timeout, a lost 202 — returns **202** with what the first attempt answered, the same `messageId` included, and `"duplicate": true`, so no second turn runs or bills; the same key with a different body returns **409**, `IDEMPOTENCY_KEY_REUSED`. The key is scoped to the thread and the URL project, and a refused send (a thread still mid-turn) remembers nothing, so the same key sends once the poll says idle.

An optional `Idempotency-Key` must contain 1–255 printable ASCII characters after surrounding whitespace is removed. A header that is present but blank, too long, or contains other characters returns `400 INVALID_HEADER` with the header named in `data.issues`; nothing starts. Reuse the same trimmed value and body for a retry. Omit the header only when you do not want replay protection.

### Understand assistant behavior and token limits

A turn is the complete handling of one accepted message, including model rounds and tool calls. REST chat uses the built-in workspace assistant with its instructions, safety rules, and three retrieval tools. These add roughly 3,000 prompt tokens per model round, included in `usage.inputTokens`. A tool-using turn can take up to five rounds, each billing its full prompt. Requests for deliverables such as documents or reports are directed to Tasks.

Project threads can retrieve that project's files and the organization's knowledge hub, but not another project's files. Threads without a project can retrieve the hub only. The assistant chooses whether to search based on the question; naming a file or explicitly asking it to search helps express your intent, but no request field forces a retrieval call.

| Field | Behavior |
| --- | --- |
| `reasoningEffort` | `low`, `medium`, `high`, `extra`, or `max`; ignored when the model lacks `capabilities.reasoning` |
| `maxOutputTokens` | Budget for the whole turn across model rounds; must not exceed the model's declared ceiling from `/models` |

An excessive output budget receives `400 INVALID_BODY` naming the ceiling. Each round receives only the remaining budget; a round with no budget left does not start. Reasoning tokens count toward this budget and `usage.outputTokens`, and are billed at the output-token price. They can consume the entire allowance, leaving a billed `complete` response with no answer text and `finishReason: "length"`. Increase the output allowance or lower reasoning effort when your task needs room for a visible answer.

Thinking-budget providers using Anthropic-style extended thinking have one exception: a budget below 2,048 is raised to 2,048, allowing at least 1,024 for thinking and as much for the answer. Effort-based reasoning models, including the GLM and DeepSeek families, have no such floor.

Read `finishReason`, not just `status: "complete"` or the token count. The values are `stop`, `length`, `tool-calls`, `content-filter`, `cancelled`, and `other`; it is absent when the provider supplies none. When a round ends at the length cap, every tool call from that round is withheld, even if one call’s arguments are complete. Each withheld `tool-result` has `status: "invalid_args"`; its message distinguishes complete from truncated arguments. Final text can still look complete, so inspect the stopping reason and tool results.

An empty answer, or cancellation before any text, has no text part. `parts` can be empty or contain only reasoning and tool parts. Check for actual text before showing or exporting an answer.

Threads, messages, and generation status are visible only to their owning key holder. Sharing project membership does not reveal another user's chats. Use `GET /api/v1/projects/{id}/threads` to list yours and `GET /api/v1/projects/{id}/threads/{threadId}` to read one.

### Read language, status, usage, and message parts

`content` is trimmed; a blank prompt — nothing but whitespace and invisible format characters such as zero-width spaces — receives `400` without starting a turn (markdown that renders as nothing, an empty code fence say, is still a prompt). Optional `locale` is a BCP 47 language tag such as `de` or `en-GB`. It asks the assistant to answer in that language through system and message instructions. Organization-mandated instructions take precedence. Without it, the assistant uses the prompt's language.

Language is an instruction to the model, not a validated output guarantee. A model can answer in another language, especially with a short prompt and reasoning enabled; the response has no language-mismatch flag. If a specific language is required, inspect the answer before accepting it.

| Message status | Meaning |
| --- | --- |
| `pending` | Assistant row exists with empty `parts` while the turn runs; generation names its `messageId` |
| `complete` | Turn finished; inspect `finishReason` for truncation or other stopping conditions |
| `cancelled` | Stopped, with any partial output already received |
| `failed` | Failed, with `error` and `errorCode` when available |

| Usage field | Interpretation |
| --- | --- |
| `inputTokens`, `outputTokens` | Reported input and output counts |
| `reasoningTokens` | Share of output spent reasoning; absent means unreported, while `0` is a reported zero |
| `cachedInputTokens` | Share of input served from the provider's cache |
| `costEstimateCents` | Catalog estimate in fractional US cents, rounded to a millionth of a cent; absent without catalog pricing |
| `estimated: true` | Platform-estimated counts, typically when provider counts were lost to a cancellation or a failure mid-stream |
| `stepLimitHit: true` | The tool loop used its full round budget |

The usage ledger books the same catalog estimate. Cached input is priced at the normal input rate, so the estimate is an upper bound for a cached turn. Estimated usage includes the whole prompt, including assistant tools. A failed turn still carries `usage` for what it consumed: its finished model rounds and, if the provider had already accepted the request, the round that failed, estimated where the provider reported no counts. A round the provider refused adds nothing, whether it answered an HTTP error status or reported a refusal such as a rate limit before any answer or positive reported usage, so a turn refused on its first round has no `usage`.

`parts` is an ordered list discriminated by `type`: `text`, `reasoning`, `attachment`, `tool-call`, `tool-result`, or `approval`. The OpenAPI schema types each variant as its own named schema (`TextPart`, `ReasoningPart`, `AttachmentPart`, `ToolCallPart`, `ToolResultPart`, `ApprovalPart`) behind a `type` discriminator with an explicit mapping, so a generated client gets a class per kind. Treat future unknown variants as opaque rather than failing the whole message.

A `reasoning` part is thinking, not the final answer. It may repeat instructions supplied to the model, including organization and project instructions and retrieval trust rules. Display it separately and only to an audience allowed to see those instructions.

### Respect thread scope and access

For a personal chat with no project, use `/api/v1/threads` and its corresponding detail, messages and generation paths. Those URLs cannot address project threads. A wrong project URL returns **404**. Both kinds use the built-in assistant; `projectId`, `agentSlug` and `agentId` in create or message bodies answer **400**. Project readers, including Members, may create and send; an archived project refuses these writes with **403**.

An archived thread refuses a message with **409**, `CHAT_THREAD_ARCHIVED`, a sandbox thread with **409**, `CHAT_THREAD_NOT_DIRECT`, and a thread whose turn is still running — or whose accepted send is still queued — with **409**, `CHAT_TURN_IN_PROGRESS`; nothing is queued and the running turn keeps its `messageId`. Retry the last one once the poll says idle, never the other two.

### Rename, archive, delete, or stop a thread

The lifecycle is yours through the same URLs. `PATCH .../threads/{threadId}` with `{ "archived": true }` archives a thread out of the way and `false` restores it (a thread whose turn is running, or whose send is still queued, refuses the archive with **409** `CHAT_TURN_IN_PROGRESS` as the delete does — cancel first; restoring and renaming stay open mid-turn), and `{ "title": "Q3 review" }` renames it (send at least one of the two; a title is trimmed and 1–120 characters, on create and on rename alike); a thread created without a title is named by the assistant after its first message, and the thread’s `title` carries the name either way.

Archiving stamps `archivedAt` on the thread and leaves `updatedAt` alone — `updatedAt` is the last message activity, so a sync that watches it must read `archived` and `archivedAt` to see an archive or a restore. `DELETE .../threads/{threadId}` moves it to the trash (**409**, `CHAT_TURN_IN_PROGRESS` while a turn runs or a send is still queued); `DELETE .../threads/{threadId}/generation` asks the running turn to stop — **202** `{ "status": "cancelling", "messageId": "..." }`, then poll until idle; the stopped reply settles as `status: "cancelled"` with whatever had streamed.

A send that is still queued (the poll says `queued`) is stopped the same way: **202** naming the reply the send's 202 promised, the model is never called, and that reply settles as `cancelled` with empty `parts`. **404**, `CHAT_TURN_NOT_RUNNING` when nothing runs and nothing is queued — its `data.lastMessageId` and `data.lastStatus` name the newest assistant message the way an idle poll does, so a stop that lost the race against a fast model reads as "the reply is already there" without a second call. An archived project refuses all three with **403**.

### Recover from model and access failures

A model failure can appear as an assistant message with readable `error` text and, when available, `errorCode`. The model list is the organization’s configured catalog, not a promise from the provider’s account, so two codes mean the account rather than the request: `credit_exhausted` (the balance is spent) and `model_not_entitled` (the provider’s plan excludes this model). `error` is the provider's own answer prefixed with its HTTP status — a provider **429** can classify as `model_not_entitled` when the plan, not the rate, refused the model — so branch on `errorCode`, never on the sentence.

Pick another model or fix the account — waiting changes nothing, and neither is a `rate_limited`. The worker rechecks the accepted thread and project access before opening the turn. If the thread moves projects or access is lost while the request waits, it does not run or append an error in the new scope.

## Compatible model endpoints {#model-endpoints}

Three routes answer the OpenAI and Anthropic interfaces for the organization's models, so an SDK or a coding tool that speaks either one can use Tale as its model provider (contract 3.7.0). They are a bare model door: the request goes to the model it names and the answer comes back as the model sent it, with no assistant, thread, or Tale tool in between. They are off until an Admin turns on **Model endpoints for API keys**. Owners, Admins, and Developers may then call them; any other member needs a live `tale:models.api` grant. [Use Tale from your editor or a script](https://docs.tale.dev/develop/use-tale-from-your-editor#model-endpoints) covers client setup.

| Route | Serves |
| --- | --- |
| `POST /api/v1/openai/chat/completions` | OpenAI Chat Completions, streamed as server-sent events or answered whole, with tools and `tool_calls`, images, and files. A stream ends with `data: [DONE]`; its closing usage chunk comes only when `stream_options.include_usage` asks for it. |
| `GET /api/v1/openai/models` | The model ids the key holder may call, as an OpenAI list: `owned_by` is the provider slug, and `created` is always `0`. |
| `POST /api/v1/anthropic/v1/messages` | Anthropic Messages, streamed or whole, with tools, images, and documents. `anthropic-version` and `anthropic-beta` are passed on. |

Authentication is the same as on every other operation: `Authorization: Bearer <key>` and, for a key holder with several memberships, `X-Organization-Slug`. The routes share the general rate budget and answer with `X-Request-Id` like any other. They ignore query parameters, an Anthropic SDK's `?beta=true` included, and take bodies up to 32 MiB. Tale reads the fields it governs and relays the rest of the body as sent, so the strict body and query rules of the other operations do not apply here.

`model` is `<providerSlug>/<modelId>` on both interfaces: the provider's slug, a slash, and the model's id in that provider's catalog, such as `openrouter/anthropic/claude-sonnet-4.6`. Because a catalog id can contain slashes, the provider is the part before the first slash. Answers name the id the request sent. The key holder may call the organization's chat models that a credential with an API key or an environment variable serves, narrowed by the credential's model allowlist and the holder's model access; models behind a subscription credential and providers with an endpoint per credential, such as Azure, are not served. `GET /api/v1/models` gives each of these models' context window, capabilities, and prices under the same `providerSlug` and `id`.

Every request is held to the key holder's model access, checked against every budget cap that binds the holder, their teams, the organization, and the key, and booked under the person and the key. The organization's input guardrails judge every text it carries before it is relayed; the answers are not filtered. A person, and each key, may have eight requests running at once.

### Read a refusal in the interface's shape

Every refusal on these routes, the authentication, organization, rate-limit, and body-size refusals included, comes in the error shape of the interface, so a vendor SDK reads it as its own. `code` carries Tale's stable code. On the OpenAI routes:

```json
{ "error": { "message": "The model endpoints are not enabled for this organization. An admin turns them on under Settings → Governance → Models → Model access.", "type": "permission_error", "param": null, "code": "MODEL_API_DISABLED" } }
```

On the Anthropic route, which also sets a `request-id` header:

```json
{ "type": "error", "error": { "type": "permission_error", "message": "The model endpoints are not enabled for this organization. An admin turns them on under Settings → Governance → Models → Model access.", "code": "MODEL_API_DISABLED" }, "request_id": "<X-Request-Id>" }
```

| Status | `code` | Meaning |
| --- | --- | --- |
| **403** | `MODEL_API_DISABLED` | The organization has not turned the endpoints on. |
| **403** | `MODEL_API_FORBIDDEN` | The key holder's role cannot call them, and the holder has no live `tale:models.api` grant. |
| **403** | `MODEL_API_MODEL_FORBIDDEN` | The organization's model access blocks the model for the key holder. |
| **404** | `MODEL_API_MODEL_UNKNOWN` | No model the key holder may call has this id; `GET /api/v1/openai/models` lists them. |
| **400** | `MODEL_API_VISION_UNSUPPORTED` | The request carries images, and the model does not read them. |
| **400** | `MODEL_API_TOOLS_UNSUPPORTED` | The request offers tools, and the model takes none. |
| **400** | `MODEL_API_VENDOR_TOOL_UNSUPPORTED` | The request asks the model vendor to run a tool: OpenAI `web_search_options` or a tool whose type is not `function` or `custom`; Anthropic web search, web fetch, code execution, an MCP toolset, `mcp_servers`, or `container`. |
| **400** | `MODEL_API_GUARDRAIL_BLOCKED` | An input guardrail blocked a text in the request; nothing was sent to the model. |
| **403** | `MODEL_API_GUARDRAIL_UNSUPPORTED` | The organization's PII protection tokenizes, which a relayed answer cannot honour. |
| **503** | `MODEL_API_GUARDRAIL_UNAVAILABLE` | A moderation step failed under a fail-closed policy, or a guardrail setting cannot be read. Retry later. |
| **413** | `MODEL_API_TEXT_TOO_LARGE` | A guardrail is on, and the request carries more than 2 MB of text. |
| **429** | `BUDGET_EXCEEDED` | A budget cap that binds the key holder or the key is reached, or the request's worst case, its prompt and output cap at the model's price, does not fit what is left; a lower `max_tokens` fits more. The message names the cap, `Retry-After` names the time until a reached cap resets, and `x-should-retry: false` tells the SDKs not to retry. |
| **429** | `MODEL_API_CONCURRENCY_EXCEEDED` | The key holder, or the key, already has eight requests running. `Retry-After` asks for a two-second wait. |
| **503** | `MODEL_API_UNAVAILABLE` | Tale cannot serve the request right now, for example because the model gateway cannot serve the model. Retry shortly. |
| **400**, **413**, **422**, **429**, **503**, **529**, or **502** | `MODEL_API_UPSTREAM_ERROR` | The model vendor refused the request. The first six keep the vendor's status; any other refusal is answered as **502**. |
| **400** | `INVALID_BODY` | The body is not a request the route can relay, such as audio input or output, a role it does not relay, an image URL that is neither `data:` nor `https:`, more than eight answers (`n`), a file stored in the vendor account (`file_id`, a `file` source), a `service_tier` other than the default, or `store: true`. The message names the field, and so does `param` on the OpenAI shape. |
| **413** | `BODY_TOO_LARGE` | The body is over 32 MiB. |

## Search a project's files

Use the project search URL when results must come from one project. It searches only that project's indexed files and requires read access, including for an archived project. Hub or team documents, other projects, websites and email attachments are outside this search. Omit `corpus` or set it to `"documents"`; any other corpus or a `projectId` body field returns **400**.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/knowledge/search" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "Q1 filing deadline", "limit": 10 }'
```

### Interpret search scores and failures

The body requires `query` (trimmed before it is checked) and also accepts `limit` (1–50, default 10) and `minSimilarity` (0–1). `limit` is the size of the page, not of the search: the platform fuses a wider candidate pool, checks every candidate against its live document, and only then cuts the page — so `limit: 1` returns the best readable passage (at equal `fusedScore` a passage the keyword leg ranked precedes one only the vector leg found, then the lower row identity — an exact term is stronger evidence than a nearest neighbour).

`minSimilarity` floors the dense (vector) leg only, before fusion; there is no default on this endpoint, so without it the nearest passages answer however weak, and the keyword leg is never floored (the built-in assistant's search applies the organization's configured floor instead — `minSimilarity` in its [`embedding.json`](https://docs.tale.dev/self-hosted/configuration/data-residency#the-organizations-embedding-model), 0.45 when unset). Hits come back in fused order, best first.

`fusedScore` is that order key and nothing more: Σ 1/(60+rank) over the legs that ranked the passage, divided by the best possible for that many legs — a rank, so the best candidate of a one-leg search scores 1.0 however weak the leg found it; comparable only within one response, never a confidence, and not stable across searches. Every candidate is checked against its live document before fusion, so a passage you cannot see never holds a rank.

What you can threshold on is `similarity` — the dense leg's cosine on the embedding model's own 0..1 scale, for the hits that leg ranked; a hit only the keyword leg found carries `similarity: null` and its `keywordScore` — keep those, an exact identifier or phrase match is stronger evidence than any cosine (in code: `hits.filter(h => h.similarity === null ? h.keywordScore !== null : h.similarity >= floor)`); a scale, not a calibrated confidence: a high similarity does not prove relevance, and an unfamiliar or misspelt token can score above a term that appears in the text, so a hit the keyword leg did not also match (`matchedLegs` without `documents:keyword`) deserves a second look before you trust it — beside `keywordScore` (the BM25 weight, unbounded, `null` when only the vector leg found it) and `matchedLegs` (`documents:keyword`, `documents:dense`, `web:keyword`, `web:dense` — which legs ranked it; `legs` is their count, 2 when the keyword and the vector leg agreed).

Each hit carries its passage, its leg `score` (the first matched leg's own number) and its `source`; `diagnostics.cached` and `diagnostics.reranked` are always `false` — Tale ships no semantic cache and no reranker, and both flags stay for compatibility; `diagnostics.legs` names every leg that ran with the admitted candidates it contributed, `0` when it ran and nothing survived (`documents:dense: 0` is a vector leg that found nothing in scope, never a missing one), and `diagnostics.dense` is `false` only when the corpus could not serve the vector leg at all, as `diagnostics.bm25` is for the keyword index; passages carry no control characters other than tab, line feed and carriage return; a passage repeated inside one document — an export of one line, a templated report — is indexed once, through its first occurrence, so a duplicate-heavy file neither crowds the vector leg nor ranks its copies one by one; a documents hit also carries `source.documentId` beside the blob `ref` the index keys it by: for a Hub hit (`source.projectId` null) it is the id `GET /api/v1/documents/{id}` takes, for a project hit the file id the project routes take (`GET /api/v1/projects/{projectId}/files/{documentId}/content`, `DELETE .../files/{documentId}`) — `/api/v1/documents/{id}` returns **404** for a project file.

A missing embedding model returns **409**, `EMBEDDING_NOT_CONFIGURED`; so does an embedding provider that refuses for account reasons — a spent balance, a spend limit, or a plan that excludes the model — as **409**, `EMBEDDING_CREDIT_EXHAUSTED`; a credential the provider rejects, or one it refuses the model, is **409**, `EMBEDDING_CREDENTIAL_REJECTED` — fix the provider settings. The same **409**, `EMBEDDING_CREDENTIAL_REJECTED`, answers when the platform has no usable credential to send at all: the provider has no default credential, or the one the embedding settings name was deleted, disabled or cannot be read; `error` names which. None of these is a rate limit: no wait lifts them, an admin has to act. Any other provider failure returns **503**, `EMBEDDING_UPSTREAM_ERROR`, with `Retry-After` — retry that one with backoff.

To search visible non-project Hub and team documents or registered websites instead, use `POST /api/v1/knowledge/search` with `corpus` set to `"documents"`, `"web"` or `"all"` (the default). That URL excludes project files and email attachments. Both URLs find file-backed documents only — a document created with inline `content` never indexes.

## Mirror an external system into a project

The Projects group is built for an unattended worker that mirrors an external system — a CRM, a practice-management tool — into Tale: find or create the client's project, prepare its folders, upload files, verify. Every call acts as the key holder: a project that user cannot see returns as if it did not exist, and writes need an editing role (Editor or above — Member is read-only here) plus edit access on the project.

These routes, and the Tasks routes below, refuse to guess the organization: a key whose user belongs to several organizations must send `X-Organization-Slug` on every call — a request without it returns **400**. Mint machine keys for a dedicated user with exactly one membership and the question never comes up; the examples keep the header anyway — it is always membership-checked, never ignored.

### Find or create the project

A project carries its audience in `teamIds` — the teams that may see it; empty means the whole organization. Read the ids from `GET /api/v1/teams` (every team, by name, with `member: true` on the ones the key holder belongs to — a key holder who is not an organization admin may only name those), send them on `POST /api/v1/projects` or replace the whole set with `PATCH /api/v1/projects/{id} { "teamIds": [...] }` (an admin verb). A repeated id collapses to one, re-asserting the audience the project already carries is a no-op that leaves `updatedAt` alone, and an archived project refuses the change like every other write (**403**, `PROJECT_ARCHIVED`) unless the same body restores it.

`externalItemId` is your key, not Tale's — an opaque string (your CRM's record id), unique per organization, never interpreted by the platform. It is stored and compared after NFC normalization and trimming, so a key handed over in NFD by a macOS filesystem finds the project a worker created in NFC from a CSV, and a trailing newline from a shell variable never makes a second project.

A legacy row whose key differed from another's only in normalization was released by the platform — its `externalItemId` is empty, the row that held the canonical spelling kept the key — so re-key it with `PATCH /api/v1/projects/{id}` when it is the one you meant. Look it up first; the lookup returns at most one project, and a match the key's user cannot see looks exactly like no match:

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/projects?externalItemId=crm-4711" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "projects": [] } — or [ { "id": "...", "name": "ACME Ltd", "externalItemId": "crm-4711" } ]
```

A match carries `archivedAt` when the project is archived — decide what your worker does with that case before it happens. Without `externalItemId`, the same route lists every project the key's user can see, newest first, keyset-paged like every other list — `{projects, isDone, continueCursor}`; pass `continueCursor` back as `?cursor=` until `isDone` (while more pages remain the answer also carries `cursor`, the same token under its pre-1.5 name — deprecated, read `continueCursor`; a lookup returns `isDone: true` with an empty `continueCursor`) — with archived projects left out unless you ask for them (`?archived=include`, or `?archived=only`).

Every row carries `createdAt` and `updatedAt`, so a worker can reconcile what it created:

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/projects?limit=50" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "projects": [ { "id": "...", "name": "ACME Ltd", "externalItemId": "crm-4711", "createdAt": 1774..., "updatedAt": 1774... } ], "isDone": true, "continueCursor": "" }
```

An empty lookup means create:

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ACME Ltd", "externalItemId": "crm-4711" }'
# → 201 { "project": { "id": "...", "name": "ACME Ltd", "key": "ACME", "externalItemId": "crm-4711" } }
```

`key` (the task-identifier prefix) and `description` are optional — the key derives from the name when omitted. A second create with the same `externalItemId` — the same after NFC normalization and trimming — returns **409**; the same string in another organization is fine, uniqueness is per organization. A key that is blank once trimmed returns **400**, `INVALID_BODY`.

An explicit project `key` contains 2–6 letters or digits, starting with a letter, and is normalized to uppercase; invalid keys answer **400**, without truncation. A name that yields no valid key creates a keyless project. A derived key that collides is re-derived until it is free; an explicit key that collides returns **409**, `PROJECT_KEY_TAKEN` — supply an unused one. The same `externalItemId` twice is **409**, `PROJECT_DUPLICATE_EXTERNAL_ID`.

### Create folders

Folder creation is get-or-create: the same name under the same parent — compared without regard to case, so `inbox` and `INBOX` are one folder — returns the existing folder with its stored name and `created: false` (**200**) instead of a duplicate, so a worker re-runs its setup step blindly after a crash; two workers creating the same folder at once get one folder.

A name is a name, never a path: a `/` or `\`, a control character, `.` or `..` returns **400**, `FOLDER_NAME_INVALID`, the sentence naming the rule broken and `data.issues` naming `name` — the same rule a file name follows, and like a file name the folder name is stored trimmed and NFC-normalized — and `parentId` is either a folder of this project or omitted for a root folder (a blank one returns **400**, `INVALID_BODY`). Folder names carry no platform-reserved meanings — the layout is yours:

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/folders" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "2026-Q1" }'
# → 201 { "folder": { "id": "<folderId>", "name": "2026-Q1" }, "created": true }
```

`parentId` (a folder of this project) nests deeper; omit it for a root folder. A name is at most 128 characters, trimmed, and never a path — `a/b`, `.` and `..` answer **400**, `FOLDER_NAME_INVALID` — and a folder 20 levels deep takes no child (**400**, `FOLDER_DEPTH_EXCEEDED`).

The tree reads back one level at a time: `GET .../folders` lists the root folders, `GET .../folders?parentId=<folderId>` the children of one folder, and every folder carries its `parentId` (`null` at the root); `GET .../folders/{folderId}` resolves a single folder — the `folderId` every file in `GET .../files` carries — so a worker that did not build the tree can still discover it, and a path is the parent chain walked upward. A `parentId` or `folderId` that is not a folder of this project returns **404**, `FOLDER_NOT_FOUND`.

### Upload a file in two steps

Two REST calls surround one direct object-store upload: prepare the handoff, transfer the bytes, then bind them to the project. The shell example requires `jq`, an existing project folder, and a local file whose extension and MIME type are allowed. Run each command only after the previous one succeeds.

```bash
: "${TALE_URL:?Set TALE_URL to your Tale origin}"
: "${TALE_API_KEY:?Set TALE_API_KEY}"
: "${TALE_ORG_SLUG:?Set TALE_ORG_SLUG}"
: "${TALE_PROJECT_ID:?Set TALE_PROJECT_ID}"
: "${TALE_FOLDER_ID:?Set TALE_FOLDER_ID to a folder in this project}"
: "${FILE_PATH:?Set FILE_PATH to an existing local file}"
: "${FILE_MIME:?Set FILE_MIME, for example application/pdf}"

FILE_NAME=$(basename "$FILE_PATH")
FILE_SIZE=$(wc -c < "$FILE_PATH" | tr -d ' ')
UPLOAD_BODY=$(jq -n --arg name "$FILE_NAME" --arg type "$FILE_MIME" \
  --argjson size "$FILE_SIZE" '{fileName:$name,contentType:$type,size:$size}')
UPLOAD_JSON=$(curl --fail-with-body --silent --show-error \
  "$TALE_URL/api/v1/projects/$TALE_PROJECT_ID/uploads" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --header 'Content-Type: application/json' --data "$UPLOAD_BODY")
UPLOAD_ID=$(printf '%s' "$UPLOAD_JSON" | jq -er '.uploadId')
UPLOAD_URL=$(printf '%s' "$UPLOAD_JSON" | jq -er '.url')
FILE_REF=$(printf '%s' "$UPLOAD_JSON" | jq -er '.s3Ref')
printf '%s' "$UPLOAD_JSON" | jq '{uploadId,method,expiresAt,maxBytes}'
```


#### Send the bytes before binding

The returned `url` is a presigned URL for a direct `PUT` to object storage. Send no `Authorization` header: the signature already authenticates the request, and adding a second authentication method is rejected. If preparation included `contentType`, the PUT's `Content-Type` must match it exactly. Omitting `contentType` during preparation leaves no required content-type header. Use the returned `s3Ref` as `fileId` when binding the upload.

Include `fileName` during preparation, for example `"fileName": "ledger-2026-q1.pdf"`, to check the format and organization policy before requesting a signed URL. A rejected file type or a name without an extension returns **400** with `UPLOAD_POLICY_REJECTED` or `UNSUPPORTED_FILE_TYPE`. Specifying a MIME type does not replace the required extension.

`maxBytes` reports the permitted size for the declared type: at most 100 MiB (104,857,600 bytes), or a stricter organization limit. Include the optional `size` to check the planned upload before transferring it. Exceeding the platform cap returns **400** `FILE_TOO_LARGE`; exceeding organization policy or volume quota returns **400** `UPLOAD_POLICY_REJECTED`. `data.limitBytes` identifies the limit.

This pre-check avoids transferring an oversized file. Binding still checks the actual stored byte count against the current limits. It does not compare that count with the declared `size`, so understating the declaration cannot bypass the upload limit.

Transfer the bytes to the returned URL. Do not send the Tale API key to this URL: the signature already authenticates the object-store request. Wait for a successful upload before binding.

```bash
curl --fail-with-body --silent --show-error --request PUT "$UPLOAD_URL" \
  --header "Content-Type: $FILE_MIME" \
  --upload-file "$FILE_PATH"
```

```bash
BIND_BODY=$(jq -n --arg upload "$UPLOAD_ID" --arg ref "$FILE_REF" \
  --arg folder "$TALE_FOLDER_ID" --arg name "$FILE_NAME" \
  '{uploadId:$upload,fileId:$ref,folderId:$folder,fileName:$name}')
curl --fail-with-body --silent --show-error \
  "$TALE_URL/api/v1/projects/$TALE_PROJECT_ID/files" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --header 'Content-Type: application/json' --data "$BIND_BODY"
```

The binding response is `201 {file}` and includes the new document ID. Keep `file.id` for later listing, download, indexing, or deletion; it is different from `uploadId` and `s3Ref`.

#### Handle expiry, format policy, and abandoned uploads

The stored `mimeType` is resolved from the file extension, and downloads use it as `Content-Type`. A multipart media type or upload hint does not override the extension-based policy.

`uploadId` is single-use. Both it and the signed URL expire after 30 minutes; `expiresAt` is their shared deadline. After an interrupted upload, prepare a new one if that deadline has passed.

`fileName` must be a plain filename. Tale trims it and applies NFC normalization; path separators or control characters return **400**. An allowed extension is required during preparation and binding: `CON` and `attachment-4711` return `UNSUPPORTED_FILE_TYPE`, even when `contentType` is supplied.

Binding rechecks the upload policy. Supported extensions are `pdf`, `doc`, `docx`, `odt`, `ppt`, `pptx`, `xls`, `xlsx`, `csv`, `txt`, `md`, `json`, `yaml`, `yml`, `py`, `jpg`, `jpeg`, `png`, `gif`, `webp`, and `ac2` (Banana accounting ledger), subject to the organization's narrower policy. The `UNSUPPORTED_FILE_TYPE` message includes the sorted format list. Unsupported formats and excessive sizes return **400** with the relevant reason code.

If the bytes have not reached object storage, binding returns **404** `BLOB_NOT_FOUND` and leaves the upload ID usable. Complete the PUT, then bind the same upload again.

Without configured object storage, both preparation and binding return **503** `OBJECT_STORE_UNCONFIGURED`. Unbound blobs are cleaned up automatically: they become eligible 24 hours after the 30-minute upload deadline, and a later upload-preparation request in the same organization removes a batch of expired upload records and blobs. This also covers rejected bindings and clients interrupted between transfer and binding.

Until cleanup, these bytes remain in the bucket but do not appear in file lists or count against a quota.

#### Choose whether to index the file

Files that enter through this endpoint are project working material, not organization knowledge: they skip knowledge indexing by default (`skipRagIndexing` defaults to `true` on the bind; pass `false` to opt in), and they never appear under `/api/v1/documents` — that family stays the knowledge hub's surface.

A skipped file is still listed by the project's chat and reads **Not indexed** on the project's Knowledge tab: a search never finds it until it is indexed (**Index now** on its row, `POST /api/v1/projects/{id}/files/{documentId}/retry-indexing` from REST — the same core and the same 10-per-user-per-minute budget as the Hub document's retry, answering `{"status": "indexing"}` and lifting the opt-out, or `skipped` with its `reason` — or a bind with `skipRagIndexing: false`), but the assistant reads a plain-text file of up to 4 MiB on request — `rag_fetch` on its id serves the bytes as text rather than answering that the file is unindexed.

### Verify what landed

Choose the file scope with `folderId`: omit it for all files in the project, use `folderId=root` for unfiled files at the project root, or pass a folder ID for that folder’s files. A folder outside the project returns **404**, `FOLDER_NOT_FOUND`.

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/projects/<projectId>/files?folderId=<folderId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "files": [ { "id": "...", "fileName": "ledger-2026-q1.pdf", "folderId": "<folderId>", "mimeType": "application/pdf", "size": 48213, "indexing": { "status": "skipped" }, "createdAt": 1774... } ], "isDone": true, "continueCursor": "" }
```

Each row carries the landed `size` and the file's `indexing` state in the vocabulary `GET /api/v1/documents` speaks: a file bound with the default `skipRagIndexing: true` reads `skipped`, and project search does not find it until it is indexed — `POST .../files/{documentId}/retry-indexing`, then poll the single-file read until indexing settles. The listing returns `{files, isDone, continueCursor}`: while `isDone` is `false`, pass `continueCursor` back as `?cursor=` unchanged (it is an opaque signed token) and cap the page with `?limit=` (max 100); while more pages remain the answer also carries `cursor`, the same token under its pre-1.5 name — deprecated, read `continueCursor`.

To monitor one file, read `GET /api/v1/projects/{id}/files/{documentId}`. It returns `{file}` with `id`, `fileName`, `folderId`, `mimeType`, `createdAt`, and `size` in bytes (`null` when unknown), plus indexing state when available. Send its `ETag` as `If-None-Match` for `304` while unchanged; after `POST .../retry-indexing`, poll this row until indexing settles. You do not need to rescan the file list. Missing, trashed, non-file, or out-of-project records return the opaque `404 FILE_NOT_FOUND`.

```bash
curl --fail-with-body --compressed "$TALE_URL/api/v1/projects/<projectId>/files/<documentId>" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG"
```

### Delete what you no longer need

Nothing this endpoint creates has to stay forever. A file goes with `DELETE .../files/{documentId}` — permanently: its document row, its search-corpus rows and its blob are purged through the same lane every hard delete uses, so the answer is **204** or a refusal, never a silent no-op:

```bash
curl -sS --compressed -X DELETE "https://your-host.example.com/api/v1/projects/<projectId>/files/<documentId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 204
```

A folder goes with `DELETE .../folders/{folderId}`, and everything beneath it goes too — every file in it and in its subfolders is purged first (their corpus rows released at once, so project search stops matching them), then the subtree. A protected controlled record or a legal hold anywhere beneath refuses the whole delete with **409** before anything is removed; a purge the object store could not finish returns **503**, `PURGE_INCOMPLETE`, with nothing removed — retry it. Both deletes need edit access to an active project; a file or folder of another project, or one already gone, returns **404** (`FILE_NOT_FOUND`, `FOLDER_NOT_FOUND`).

#### Archive, rename, or delete the project

The project itself has a lifecycle too, for organization admins (**403**, `ROLE_FORBIDDEN`, for anyone else). `PATCH /api/v1/projects/{id}` with `{ "archived": true }` archives it — it stays readable through this endpoint, refuses every write with **403**, `PROJECT_ARCHIVED`, keeps its `externalItemId` taken, and `{ "archived": false }` restores it.

The same `PATCH` carries the identity a mirror propagates when the source record changes: `name` (trimmed, never blank), `description` (`null` clears it) and `externalItemId` (stored NFC-normalized and trimmed; `null` releases the key, another project's key returns **409**, `PROJECT_DUPLICATE_EXTERNAL_ID`, with the key in `data`) — for editors with project edit access on an active project, every field optional and at least one required. A body that restores and renames applies the restore first, one that renames and archives applies the archive last; renaming an archived project the body does not restore returns **403**, `PROJECT_ARCHIVED`.

When "ACME Ltd" becomes "ACME Group" in the CRM, `{ "name": "ACME Group" }` is the whole move — nothing under the project is touched. `DELETE /api/v1/projects/{id}` removes it and frees the key: by default a cascade — every document expires into the retention pipeline, your own chats are trashed, every task is retired and its live runs cancelled — or, with the body `{ "mode": "detach" }`, the documents and chats are released into the organization instead. The project's run history goes with it either way, finished runs included — unlike an automation delete, which keeps its runs.

Agents and folders go with the project either way, and a cascade draws on the same per-user budget the app's delete does (5 per minute):

```bash
curl -sS --compressed -X DELETE "https://your-host.example.com/api/v1/projects/<projectId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 204
```

The delete is refused with **409**, before anything is written, while an automation is installed in the project — `PROJECT_HAS_BOUND_AUTOMATIONS`, with `data.automations` naming them; uninstall each via `DELETE /projects/{id}/automations/{name}` first — while a cascade would destroy a controlled record that is in review, approved or retains an approved version (`PROJECT_HAS_PROTECTED_RECORDS`, `data.documents` naming them), or while a legal hold covers one of its documents (`PROJECT_LEGAL_HOLD`).

## Materialize a task, then run it

The Tasks group turns an external item into a task on a project's board, starts a deployed workflow on it and reports back. A project-bound automation must be installed in this project first. Installing is idempotent: **201** on the first call, **200** when the binding exists. It requires the developer capability and edit access to an active project. Bind ahead of time if the worker's user lacks those permissions:

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/automations/vat-return" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{}'
# → 201 { "name": "vat-return", "added": true }
```

`GET /api/v1/projects/{id}/automations` lists the automations installed in that project. An automation without any project bindings can also run in an accessible project when the caller has the required edit permissions, but it is not part of that installed list. `DELETE /api/v1/projects/{id}/automations/{name}` uninstalls one again — **204**, or **404** `AUTOMATION_NOT_INSTALLED` when it was not installed there — under the same developer capability and edit access.

### Create or update the mirrored task

Task creation is idempotent per `(projectId, externalSystem, externalId)`: the first call creates (**201**, `created: true`) a task in `backlog` — the mirror's intake column, where the app's own Create task defaults to To do — and a repeat returns with the same task (**200**, `created: false`). Both keys are stored and compared after NFC normalization and trimming — the same rule as a project's `externalItemId` — so a padded or differently normalized repeat is still the same task, and a key that is blank once trimmed returns **400**. Take `projectId` from the URL; sending it in the body returns **400**. Every key holder who can read an active project may create a task, Members included (contract 3.6.0). A repeat changes the task it names, so it needs the right to change that task: an Editor or higher, or the member who created the task or is its person assignee. Anyone else gets **403**, `RBAC_FORBIDDEN`, and nothing is written.

For `externalSystem: "github"` or `"glitchtip"`, `externalState` never changes the Tale task's status. New tasks enter `backlog`; closing, resolving or reopening the upstream issue leaves local progress unchanged. The issue import automations display source status separately on the task.

For other source systems, `externalState` mirrors the source item's lifecycle: `closed` parks the task at `in_review` for a person to complete (only the workflow engine itself lands a close at `done`), and `open` reopens a task the mirror closed — one it parked at `in_review`, or a `done` one — back to `backlog`; a park a person or an agent made is theirs, `open` leaves it, and any move through the board ends the mirror's claim on a park it made. A cancelled task stays cancelled either way. A pending review owned by an agent keeps its status and reviewer. A custom-source sync records an upstream close or reopen separately, without approving or withdrawing that review.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/tasks" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "externalSystem": "crm", "externalId": "case-991", "title": "Prepare the Q1 filing" }'
# → 201 { "task": { "id": "<taskId>", "created": true } }
```

Repeating an active task’s external reference updates its title and description; omitting `description` clears it. Labels change only when supplied. An archived task stays unchanged. The task id stays the same, and `runWorkflowSlug` does not start another run on that repeat. Keep the repeated payload stable when retrying after a lost response.

### Bind a setup folder and choose automation ownership

`description`, `labels`, `externalUrl`, and `setupFolderName` are optional. `title` takes up to 200 UTF-16 code units (most emoji count as 2) and `description` up to 20,000; `labels` takes up to 50 names of up to 50 code units each. `externalUrl` must be an absolute `http(s)` URL. A value past its limit, or another scheme, returns **400** rather than a silently altered task. `setupFolderName` binds the task to one of the project's root folders by name — matched without regard to case — and stores that folder's id as the task's `externalUrl`: the Setup-folder binding a folder-driven automation reads off its task input, resolved again on every repeat.

A name no root folder of the project carries returns **400**, `SETUP_FOLDER_MISSING`, and nothing is created; sent beside `externalUrl`, it returns **400**, `INVALID_BODY`. Labels keep their spelling: a name is trimmed and NFC-normalized, matched against the project's catalog without regard to case, created with the spelling you sent when it is new, and read back as stored in the order you sent — so `["Bug", "P1"]` reads back as `["Bug", "P1"]`, while `["bug"]` on a project that already has `Bug` wears that existing label (two names differing only in case are one label, never two). Only an Editor or higher on the project creates labels this way; any other key holder names labels the catalog already has, and a new name returns **400**, `TASK_LABEL_UNKNOWN`, with nothing written.

Send `automationSlug` when the task belongs to an automation: it becomes the assignee, and the task modal's work panel — the Start button, run progress, and the operator questions a run asks — keys on that ownership (a later re-pick fills a missing attribution, but never overwrites an assignee). `runWorkflowSlug` starts a deployed workflow on a newly created task in the same call — the run starts inline, so the response carries its `runId` (the run id to poll; `executionId` repeats it and is deprecated), or `runId: null` if the slug has no deployed version or starting fails after the task is committed. A null run ID does not undo the saved task; inspect and correct the workflow, then use the explicit start route.

Start explicitly instead when you want to name the workflow in a separate call. The owning `automationSlug` must name an automation that exists — **404**, `AUTOMATION_NOT_FOUND`, otherwise — with a deployed version: one that is saved but not deployed returns **409**, `AUTOMATION_NOT_DEPLOYED`. A workflow bound to other projects returns **403**.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/tasks/<taskId>/start" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "workflowSlug": "vat-return" }'
# → 200 { "started": true, "runId": "<runId>", "executionId": "<runId>" }
```

### Check whether a task run started

Starting requires the right to change the task — an Editor or higher, or the member who created it or is its person assignee (**403**, `RBAC_FORBIDDEN`, otherwise) — in an active project, and an active task — an archived task returns **403**, `TASK_ARCHIVED` (the task read carries `archivedAt` while it is; `PATCH …/tasks/{taskId}` with `{ "archived": false }` restores it — see below). It wraps the task as `{task: ...}` and needs no additional developer capability; the run log attributes the start to your key. Poll `GET /api/v1/projects/{id}/runs/{runId}` with the `runId` (`executionId` carries the same value and is deprecated).

The answer is **200** whether or not a run started, so branch on `started`, never on the status alone: with `started: false`, `reason: "already_running"` carries the in-flight run's `runId` — a task holds at most one live run, whichever automation started it, so that run may belong to another automation (its `name` says which); poll that run. A workflow bound to other projects returns **403**, `AUTOMATION_PROJECT_FORBIDDEN`. The `workflowSlug` names the automation as `GET /api/v1/automations` lists it — the `/` form (`billing/dunning`), never the `__` spelling the URL path takes — and must name one that exists — **404**, `AUTOMATION_NOT_FOUND`, otherwise — with a deployed version: one that is saved but not deployed returns **409**, `AUTOMATION_NOT_DEPLOYED` — the same two refusals the intake gives an `automationSlug`, judged before the execute budget is charged; `reason: "not_started"` is left for the one residual case, a deployment withdrawn between that check and the start.

A task with an active project-agent run refuses a workflow start with **409** `TASK_HAS_LIVE_RUN`. Wait for the agent to finish or cancel its run before starting the workflow. The same rule prevents an agent from starting while a workflow holds the task.

New work also returns **403** `TASK_AUTOMATION_DISABLED` when an administrator has turned off task automation, or **409** `TASK_AUTOMATION_UNAVAILABLE` when its policy cannot be read. Ask an administrator to enable task automation or restore the policy. Existing runs can finish, and comments are still saved.

Concurrent starts for the same task share the one in-flight run, whichever automation they name, including requests that arrive together. This is not `Idempotency-Key` support for task starts: once that run finishes, another start can create another run. Save the returned `runId` and inspect it before retrying an uncertain start.

### Archive or restore a task

`PATCH /api/v1/projects/{id}/tasks/{taskId}` with `{ "archived": true }` archives the task — the board's own archive: it stays readable here and refuses comments and starts with **403**, `TASK_ARCHIVED` — and `{ "archived": false }` restores it. Both are idempotent, so a mirror that supersedes a task (a re-delivery that opened a new one, a source record that was cancelled) retires the old task without reading it first. It needs an **active** project and the right to change the task, as an Editor or higher or as the member who created it or is its person assignee (**403**, `PROJECT_ARCHIVED` or `RBAC_FORBIDDEN`); the task itself may be archived, which is what the restore is for. The body takes exactly `archived`; title, description and labels travel through the intake's repeat. The answer is the task as it now stands.

```bash
curl -sS --compressed -X PATCH "https://your-host.example.com/api/v1/projects/<projectId>/tasks/<taskId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'
# → 200 { "task": { "id": "<taskId>", "status": "in_progress", "archivedAt": 1789921403000, ... } }
```

### Comment and read task state

Report back and read state — the comment posts as the key holder, indistinguishable from the same person commenting in the app, @mentions included. Project readers, including Members, may comment on an active task in an active project; an archived task refuses the comment with **403**, `TASK_ARCHIVED`, the way an archived project does with `PROJECT_ARCHIVED`. Reading a task or its comments is also allowed after archival. Every task URL is judged left to right: a project that is missing or invisible returns **404**, `PROJECT_NOT_FOUND`, and only a task that is missing or belongs to another project returns `TASK_NOT_FOUND`.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/tasks/<taskId>/comments" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Filed. Confirmation 2026-8842." }'
# → 201 { "comment": { "id": "..." } }

curl -sS --compressed "https://your-host.example.com/api/v1/projects/<projectId>/tasks/<taskId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "task": { "id": "<taskId>", "title": "...", "status": "in_progress", "externalId": "case-991", "labels": [], "dueDate": 1790719200000, "repeat": null, ... } }
```

A task read also carries its schedule, which is read-only on this API. `startDate` and `dueDate` are epoch milliseconds and appear only when set. When you choose these dates in the app, it writes the midnight that starts the chosen calendar day in your browser’s time zone. `repeat` is always present: `null` when the task doesn't repeat, otherwise a `TaskRepeat` such as `{ "frequency": "weekly", "interval": 2, "weekdays": [2, 4], "timezone": "Europe/Zurich", "createOn": "dueDate" }`. `frequency` is `daily`, `weekly`, `monthly` or `yearly`, and `interval` runs from 1 to 99; `weekly` lists `weekdays` from 0 (Sunday) to 6 (Saturday), `monthly` takes a `monthDay`, and `yearly` a `month` and a `monthDay`. `createOn` appears, as `"dueDate"`, only when the next task is also created at the start of the due date; without it, the next task comes when this one is done or cancelled. When a repeating task closes, in the app or through an approved review here, or its due date begins under `createOn: "dueDate"`, its next task is created in `todo`, and `repeatNextTaskId` names it from then on. Deleting that next task removes `repeatNextTaskId`, but this task still never creates another one (contract 3.3.0).

### Read comments and download deliverables

A comment's canonical `body` is trimmed and takes 1 to 10,000 UTF-16 code units (most emoji count as 2). Comment writes also accept an optional `bodyByLocale`, which comment reads return when present. Supply equivalent nonblank translations for `en`, `de` and `fr`; additional language or language-region keys such as `nl`, `it` and `de-CH` are allowed. Each value is trimmed and held to the same limit, with at most 16 locales per comment. Render the reader's exact locale, then its base language, then `en`, then `body`. Attribution remains the key holder's. A plain-text edit in Tale clears the old translations so they cannot hide the edit.

Task and workflow agents receive instructions to preserve the language established by the task title and description, falling back to the organization's default agent language. Generated title-template words, quarter identifiers, source-document languages and the run starter's UI locale do not establish the task language. The same policy applies to operator questions, resumed turns and related task creation. This is model guidance; localized progress snapshots let clients select a translation independently of the canonical task language.

Read the run output and task comments to collect the automation's results. Whether it also creates files, and where it stores them, depends on the workflow; starting a task does not by itself put files in the example quarter folder.

Comments arrive in pages, newest page first and chronological within each page. `limit` defaults to 200 and allows at most 500. While `isDone` is `false`, pass `continueCursor` unchanged as `cursor` to read older comments. It is an opaque signed token, not a page number.

The content endpoint streams the bytes itself (**200**, no redirect to follow), named by an RFC 6266 `Content-Disposition`, so a plain `curl -o` lands the file and `--fail-with-body` turns a refusal into a non-zero exit instead of a file full of JSON.

`Range` is honoured: a single byte range (`bytes=0-1023`, `bytes=1024-`, `bytes=-512`) returns **206** with `Content-Range`; a range starting at or past the end of the file — what `curl -C -` sends once the local copy is complete — returns **416** with an empty body and `Content-Range: bytes */<size>` naming the size, so a resuming worker learns it is done; several ranges or a `Range` the server cannot read are ignored and the whole file returns **200**.

A `HEAD` returns the same headers a `GET` carries — `Content-Length`, `Content-Type`, `ETag`, `Last-Modified`, `Accept-Ranges` — without the bytes and ignores `Range`, so a poller checks for a new version with `curl -I` (not `curl -X HEAD`, which waits for a body) and sends the `ETag` back as `If-None-Match` to get **304** while nothing changed:

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/projects/<projectId>/tasks/<taskId>/comments?limit=100" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "comments": [ { "id": "...", "authorType": "agent", "body": "Return prepared — key figures…", ... } ], "isDone": false, "continueCursor": "<opaque token>" }

curl -sS --compressed --fail-with-body "https://your-host.example.com/api/v1/projects/<projectId>/files/<documentId>/content" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -o report.md
# → the file bytes (Content-Disposition carries the filename)
```

## Error model

API refusals normally use a flat JSON envelope. A conditional `304`, a `HEAD` response, or a refusal from an intermediary can have no JSON body:

```json
{ "error": "Automation not found", "code": "AUTOMATION_NOT_FOUND" }
```

The [compatible model endpoints](https://docs.tale.dev/develop/api-reference#model-endpoints) are the exception: under `/api/v1/openai` and `/api/v1/anthropic`, every refusal, the authentication and rate-limit ones included, takes the OpenAI or Anthropic error shape and carries the same `code` there.

`error` is a sentence for humans; `code` is the stable value to branch on — every refusal the API itself makes carries one, and the OpenAPI document lists the full set as the `Error.code` enum. The set is additive: a new code is a minor change, so treat a value you do not know as a generic refusal of the status you got. Some refusals add `data` — `issues` for a refused body, `retryAfterMs` for a rate limit, `providers` for an ambiguous model. Branch on the code where one is named below, on the status otherwise:

Read the exact error enum without a key:

```bash
curl --fail --silent --show-error "$TALE_URL/openapi.json" \
  | jq -r '.components.schemas.Error.properties.code.enum[]'
```

**400: correct the request before retrying.** Invalid bodies return `INVALID_BODY` with `data.issues`. Each issue has a field path, such as `price` or `contacts.2.email`, and a short message suitable for display: `is required`, `must be a string`, `must not be blank`, `must be at most 200 UTF-16 code units`, or `must be one of "a", "b"`. Unknown keys are reported under their own names. Branch on `code`, not this human-readable wording.

Body validation rejects missing required values, incorrect types, unknown keys, malformed JSON, invalid UTF-8, NUL characters, unpaired UTF-16 surrogates, integers beyond 2^53 − 1, and numbers outside the field's permitted range. A search `limit` in the JSON body is rejected when out of range; it is not clamped. The API reads JSON regardless of `Content-Type` and does not return 415 for these bodies.

| Other 400 code | Meaning and recovery |
| --- | --- |
| `INVALID_CURSOR` | The token did not come from this list. Restart pagination without it. |
| `INVALID_LIMIT` | A query `limit` is not an integer. Valid integers outside the range are clamped instead. |
| `INVALID_QUERY` | Another query parameter is invalid. Query failures name the parameter in `data.issues`; none silently restart at page one. |
| `AUTOMATION_INPUT_INVALID` | Correct the input against the automation's `inputs` schema using `data.issues`. |
| `AUTOMATION_TRIGGER_INVALID` | Correct a trigger that cannot fire, including an impossible date such as `0 0 30 2 *`. |
| `CONTACT_IDENTITY_REQUIRED` | Preserve at least one contact identity field. |
| `DOCUMENT_RECORD_FROZEN`, `DOCUMENT_RECORD_REPLACEMENT_REQUIRED` | Follow the controlled-record replacement workflow instead of editing protected content directly. |
| `ORG_SLUG_REQUIRED` | Supply the organization for a key holder with multiple memberships. |
| `INVALID_HEADER` | Use 1–255 printable ASCII characters after trimming for `Idempotency-Key`; `data.issues` names the header. |
| `INVALID_URL` | Remove NUL bytes (`%00`) from the path or query. This check runs before routing and authentication. |
| `BODY_CHUNK_MALFORMED` | Correct malformed HTTP/1.1 chunk framing in the client or intermediary. The edge supplies its own `requestId` and no contract version. |
| `BODY_LENGTH_MISMATCH` | Under HTTP/2, the body ended before its declared `Content-Length`. The edge response has a fresh `requestId` and no `X-Tale-Api-Version`. |

- **401** — missing or invalid API key (`UNAUTHORIZED`), with a `WWW-Authenticate: Bearer` challenge.
- **403** — the holder lacks the required role (`ROLE_FORBIDDEN`, `KNOWLEDGE_ENTRY_FORBIDDEN`) or project edit access, may not change another member's task (`RBAC_FORBIDDEN`), a document's or project's `teamIds` names a team the holder is not in (`TEAM_ACCESS_DENIED`), a skill save would share with the whole organization while the organization reserves that (`SKILL_PUBLISH_FORBIDDEN`), the project or task is archived for a requested mutation (`PROJECT_ARCHIVED`, `TASK_ARCHIVED` — a project's `teamIds` included), an automation cannot run in this project, or `X-Organization-Slug` names an organization the key holder is no member of (`ORG_FORBIDDEN`).
- **404** — the resource is absent, invisible to the holder, owned by another thread user, or belongs to a different project than the URL names; each family names its own code (`PROJECT_NOT_FOUND`, `DOCUMENT_NOT_FOUND`, `THREAD_NOT_FOUND`, …), an `X-Organization-Slug` that names no organization returns `ORG_SLUG_INVALID`, and an unknown route returns `NOT_FOUND` — once the key is checked: keyless, the endpoint's **401** comes first, so a path this endpoint never served (`/api/v1/openapi.json`, say) returns **401** without a key and **404** with one; the document itself lives at `/openapi.json`, outside the endpoint and keyless.
- **405** — the route exists, but not for that verb (`METHOD_NOT_ALLOWED`); `Allow` lists the verbs it serves.
- **409** — the state refuses the action: no deployed version, a bound automation called without a project URL, a run still in flight on delete (`RUN_ACTIVE`), an `Idempotency-Key` reused with a different body (`IDEMPOTENCY_KEY_REUSED`), an archived thread or a turn already running, a duplicate — a contact's `email` or `externalId` (`CONTACT_DUPLICATE_EMAIL`, `CONTACT_DUPLICATE_EXTERNAL_ID`), a product's `name` or `externalId` (`DUPLICATE_PRODUCT_NAME`, `DUPLICATE_PRODUCT_EXTERNAL_ID`), a knowledge entry's topic (`KNOWLEDGE_ENTRY_DUPLICATE`), a project's `externalItemId` (`PROJECT_DUPLICATE_EXTERNAL_ID`) —, a superseded knowledge entry (`KNOWLEDGE_ENTRY_SUPERSEDED`), a stale `expectedUpdatedAt` (`CONTACT_STALE`, `PRODUCT_STALE`, `DOCUMENT_STALE`), a document that backs an active knowledge entry (`DOCUMENT_HAS_KNOWLEDGE_ENTRY` — delete or update the entry instead), a delivery retry on one that is not dead-lettered (`DELIVERY_RETRY_UNAVAILABLE`), a newer conversation content snapshot bound to a trashed contact (`CONVERSATION_CONTACT_TRASHED`), or search without an embedding model.
- **412** — a precondition failed and nothing was written: `If-Match` on a skill whose `SKILL.md` changed since you read it, or with nothing stored (`SKILL_STALE` — `data.etag` names the current tag, `null` when nothing is stored); `If-None-Match: *` on a skill slug that already has a bundle (`SKILL_EXISTS`); a document `If-Match` that no longer matches its read representation (`PRECONDITION_FAILED`, with the current tag in `data.etag`).
- **413** — the body is too large (`BODY_TOO_LARGE`; the sentence names the cap): every JSON body at its cap (1 MiB unless the operation says otherwise — the caps are listed above), the webhook trigger at its 256 KiB (262,144 bytes) cap. An uploaded file that breaks the size or type policy is refused at the bind with **400** and a reason code instead.
- **422** — a skill bundle the file layer cannot read — a planted symlink, a file over the 4 MiB staging cap, a `SKILL.md` that does not parse (`SKILL_MALFORMED`): answered by the reads and, on `PUT`, only for the bundle already stored under the slug — the body you send is validated as **400** (`INVALID_BODY`, `INVALID_SKILL`), so a JSON body alone never provokes it.
- **429** — rate limit exceeded (`RATE_LIMITED`). `error` describes the wait; `requestId` identifies the request. Wait for `Retry-After` in whole seconds or `data.retryAfterMs` in milliseconds before retrying. See [Rate limits](https://docs.tale.dev/develop/rate-limits).

| Status | Meaning and recovery |
| --- | --- |
| **414** | the request URL (path and query) exceeds 32 KiB (`URI_TOO_LONG`); the envelope carries a `requestId`. |
| **408** | the request did not finish arriving within 15 minutes, headers and body together (`REQUEST_TIMEOUT`); the envelope carries a fresh `requestId` (the timed-out request never got one of its own) and the connection is closed — retry on a faster link or in smaller pieces. |
| **431** | the request headers as a whole exceed the edge's 64 KiB budget; answered without the envelope and with no `X-Request-Id` (the edge's parser writes it before any route runs) on HTTP/1.1 (which lets a few KiB of slack through first — a URL or header just past the budget still reaches the platform and is judged by its rules, a 66 KiB URL answering **414**), and on HTTP/2, where the budget is exact, by closing the connection. |
| **500** | internal error (`INTERNAL_ERROR`); the envelope carries a `requestId` to quote when you report it. |
| **503** | a dependency the request needed is down: the platform's database, while it restarts or cannot be reached (`DATABASE_UNAVAILABLE`, with `Retry-After` and a `requestId` — on any operation and the webhook trigger, the key check included, so a working key is never refused with **401** meanwhile), the embedding provider (`EMBEDDING_UPSTREAM_ERROR`, with `Retry-After`), the object store behind a file download (`OBJECT_STORE_UNAVAILABLE`, with `Retry-After`) or a deployment without one (`OBJECT_STORE_UNCONFIGURED`), a document purge that could not finish (`PURGE_INCOMPLETE`), or an object store that accepted a knowledge-entry write and never answered it within 30 seconds (`KNOWLEDGE_ENTRY_STORE_TIMEOUT` — nothing is written) — retry with backoff. |
| **502**, **503**, **504** | answered at the edge while the platform restarts or cannot be reached (`UPSTREAM_UNAVAILABLE`, with `Retry-After`, a fresh `requestId` and no `X-Tale-Api-Version`), on every machine endpoint — `/api/*`, `/events`, `/status.json`, `/openapi.json`, `/.well-known/*`; a browser navigation gets the maintenance page instead — retry with backoff. |

Unbinding a trigger from an existing automation (`DELETE .../triggers`) returns **204** whether or not a trigger was bound; an unknown automation returns **404**. Deleting a resource returns **404** when it is absent, including a contact already moved to trash, a product already deleted or a knowledge entry already deleted. A contact's `DELETE` is a move to the trash (`POST /api/v1/contacts/{id}/restore` brings it back); a product's `DELETE` is permanent — products have no trash and no restore, and the name and `externalId` are free for a new product at once, which is a new row with a new id. It takes the product's uploaded image with it (as does a `PATCH` that replaces or removes `imageUrl`) unless another product still shows the same upload; under an active legal hold — the organization's, or a custodian hold on the image's uploader — the delete is refused with **409**, `LEGAL_HOLD_ACTIVE`, and a patch keeps the superseded image. Deleting an active knowledge entry retires every version of its topic and moves the Hub document behind it to the trash — and drops that document's passages from the search corpus at once; deleting that document directly is refused.

Cancelling an unknown run also returns **404**; `{cancelled: false}` means the run exists but has already finished; the accompanying `status` identifies its terminal state.

## Versioning

Three numbers describe a running instance, and they mean different things. The build (`GET /api/health` returns it) is the deployment's release. The REST prefix, `/api/v1/`, is the compatibility line: a route under it is served until a `/api/v2/` exists and the retirement of `/api/v1/` has been announced in the release notes at least two minor releases ahead, with `Deprecation` and `Sunset` headers on the retiring routes in the meantime.

The contract's own version is `info.version` in the OpenAPI document at `/openapi.json` — semver for the wire: a minor bump for an additive change (a new operation, field, header or error code), a major one for a removal or a changed meaning — and every response names the version the instance implements in `X-Tale-Api-Version`, so a client that pins to a version can tell when the instance moved. The document describes the routes and request and response schemas served by the running instance, with `servers` set to that instance; `/docs` renders it.

Use it as the contract for your client, and read each release's notes under **API contract changes** — every wire change to this surface is listed there with the old and the new behaviour ([release notes format](https://docs.tale.dev/self-hosted/operate/release-notes/format)). Published notes are available on [GitHub Releases](https://github.com/tale-project/tale/releases).

A few endpoints live outside that document on purpose: `GET /api/health` is the unauthenticated liveness probe (`{"status":"ok","version":"<build>"}`), `GET /status` and `/status.json` the deployment's own [status page](https://docs.tale.dev/develop/status-page), `/openapi.json` and `/docs` the contract itself; the [WebDAV](https://docs.tale.dev/develop/webdav-api) and OpenID Connect surfaces (above) speak their own protocols.

## Where this fits

This page is the REST half of the outside surface. The [MCP endpoint](https://docs.tale.dev/develop/mcp-endpoint) exposes the same platform to MCP clients — automation authoring lives there, not in REST. The [Webhooks page](https://docs.tale.dev/develop/webhooks) covers the inbound trigger that starts runs without a key. If you are building inside the product — project agents, automations — the [Platform tab](https://docs.tale.dev/platform) is your day-to-day; this page is for outside. To bring Tale into opencode, Claude Code, or a shell script, as their model provider through the [compatible model endpoints](https://docs.tale.dev/develop/api-reference#model-endpoints) or as a source of knowledge and tools, read [Use Tale from your editor or a script](https://docs.tale.dev/develop/use-tale-from-your-editor).

# Contributor Compose files
Source: https://docs.tale.dev/develop/compose-files

Use the repository’s Compose files to develop or test Tale from source. For the usual local workflow, [run the app and backend natively with Docker dependencies](https://docs.tale.dev/develop/contributor-setup). Use the container workflow below when your change needs to exercise the development images.

Packaged self-hosted installations use the CLI-generated stack described in [Quickstart](https://docs.tale.dev/self-hosted/install/quickstart). The source-tree overlays have development ports and mounts; review them before exposing a host publicly.

Choose one workflow for the change you are testing. Starting native development and the container frontend on the same port produces a conflict, not a second isolated instance.

## Start the container development workflow

Run from the repository root with the pinned Bun version and Docker Compose available:

```bash
bun install
bun run docker:dev
bun run docker:dev:logs
```

The `docker:dev` wrapper prepares the sandbox runtime image and network, generates an environment overlay, and starts the base, development and docs files together. Prefer that entry point to copying only its final Compose command: the preparation is part of the workflow. The generated environment overlay forwards most host variables into the platform container, so review the environment you run it from.

Stop the live log stream with `Ctrl-C`. Use `bun run docker:dev:down` to stop this stack. Keep data volumes and the existing environment when you want to resume with the same instance. A second worktree needs its own ports, container identities and storage to run independently.

## Choose an overlay

| File | Purpose |
| --- | --- |
| `compose.yml` | Source-build base services and their dependencies. |
| `compose.dev.yml` | Source mounts and development commands. |
| `compose.docs.yml` | The documentation site and proxy routing. |
| `compose.web.yml` | The marketing site and proxy routing. |
| `compose.test.yml` | Platform container test configuration. |
| `compose.docs.test.yml` | Documentation container test configuration. |
| `compose.web.test.yml` | Marketing-site container test configuration. |
| `compose.test.mock.yml` | Mock-backed integration configuration. |

Read the script that invokes a test overlay before running it directly; the test harness may prepare images, ports and fixtures. [Docker contributions](https://docs.tale.dev/develop/contributing-docker) covers the relevant checks.

## Inspect what Compose will merge

Files apply from left to right. Later files override or extend earlier configuration according to Compose’s merge rules. Inspect service names without printing the resolved environment and its secrets:

```bash
docker compose -f compose.yml -f compose.dev.yml -f compose.docs.yml config --services
```

This inspects the static files. The `docker:dev` command also supplies its generated environment overlay. A complete `docker compose config` can print interpolated credentials; keep that output out of public logs and bug reports.

## Understand the main services

The source stack separates `backend-api` from `backend-worker`. The API handles application requests and authentication; the worker runs jobs, model turns and knowledge processing. `platform` serves the web app. `proxy` routes traffic, while `db`, `knowledge-db` and `object-store` hold application, knowledge and blob data.

`sandbox`, `sandbox-egress` and `sandbox-llm-gateway` provide isolated execution and its network/model paths. The source stack also includes the video-ingestion sidecar. Production topology can differ: the generated single-host stack combines the application and knowledge databases. Use [Container architecture](https://docs.tale.dev/self-hosted/operate/container-architecture) for service responsibilities and [Environment reference](https://docs.tale.dev/self-hosted/configuration/environment-reference) for their configuration.

## Diagnose the first failure

If preparation fails, read the wrapper’s first error before retrying Compose. Check Docker availability and image builds for an image error; network creation for an absent sandbox network; occupied ports or existing containers for a second-checkout conflict. Inspect `docker compose ps` and the failing service’s logs before changing configuration. Avoid removing volumes to solve a startup error: that discards the state needed to reproduce it.

# Connectors
Source: https://docs.tale.dev/develop/connectors

A connector gives Tale a reusable way to call a service. Its definition describes authentication, permitted destinations, and actions; each organization supplies its own credentials. Use this page to inspect that contract or contribute a new connector.

If your goal is to connect an account in the app, use [Connector credentials](https://docs.tale.dev/platform/admin/connectors). To choose an existing integration, browse the [connector catalog](https://docs.tale.dev/platform/connectors/overview).

## How a connector is declared

Definitions live in `configs/platform/system/connectors/<slug>/connector.yml`, alongside the connector's icon. The directory slug must match `name`. An automation calls an action using `<connector>.<action>`, for example `tavily.search`. Vendor connectors appear in Settings; internal connectors with platform authentication do not.

This is the identity and authentication excerpt from the shipped Tavily definition. It is not a complete connector: the file also needs its action definitions.

```yaml
name: tavily
displayName: Tavily
description: Real-time web search and page extraction for AI research.
tags:
  - Search
allowedHosts:
  - api.tavily.com
auth:
  - method: api-key
```

### Set the destination boundary

| Field | Meaning |
| --- | --- |
| `endpointMode: fixed` | Default. Live HTTP calls use fixed vendor URLs; `allowedHosts` contains exact hosts |
| `endpointMode: per-credential` | Each credential supplies an HTTPS `endpointUrl`; actions read its origin as `ctx.endpoint`, without a trailing slash |
| `allowedHosts` in per-credential mode | Host suffixes: `atlassian.net` allows its subdomains |
| `configFields` | Non-secret per-credential values such as server host, port, region, or API version |

Confluence, GlitchTip and Shopify use per-credential origins. Keep secrets out of `configFields`; use the encrypted credential payload. For JavaScript actions, `ctx.http` enforces the declared HTTP destination boundary. Native backends, such as mailbox protocols, implement their own transport checks; an HTTP allowlist alone does not describe their whole security boundary.

<Info>

Adding a connector is a source contribution. The runtime reads the platform catalog, with no organization-level connector upload. Start from [Contributor setup](https://docs.tale.dev/develop/contributor-setup), then inspect a shipped connector with the same authentication and transport before adding yours.

</Info>

## What an action declares

| Field | Contract for the author and caller |
| --- | --- |
| `name`, `description` | Stable snake_case action name and an explanation of when to use it |
| `input` | Object JSON Schema, validated before execution; describe fields and mark required ones |
| `output` | TypeScript-style signature describing the result; this is documentation, not a runtime output validator |
| `effects` | `read` or `write`; writes pass through approval policy |
| `mock` | Required deterministic JavaScript implementation; same input, same output, no network I/O |
| `backend` | Optional live implementation: `yaml-js` with `live`, or `native` with an `impl` identifier |
| `exampleInput` | Optional small, meaningful example for discovery and testing |

A connector with no live backend can run in mock mode but refuses live execution. Write actions do not run if the platform cannot obtain an approval decision. See the [approval-policy reference](https://docs.tale.dev/self-hosted/configuration/approvals) for rule precedence and pending decisions.

When inspecting a result contract, read the live implementation too. For example, Tavily's search input describes `max_results`, but the shipped action caps the returned results at five. The output signature alone does not explain that bound.

### Resolve the right account

Credentials are selected at call time: the one named by the caller, otherwise the connector's default. Changing a default can therefore change which account a later run uses. Name the credential explicitly when the account is part of your integration's contract.

Mailbox discovery has a deliberate exception: `conversation.sync_mailbox` and `conversation.list_mailbox_messages` enumerate every active credential for the connector. They cover all connected mailboxes instead of limiting themselves to the default.

## The authentication methods

A connector can support several methods; a stored credential uses exactly one.

| Method    | UI label            | What the credential holds                                                                        |
| --------- | ------------------- | ------------------------------------------------------------------------------------------------ |
| `api-key` | API key             | A single secret the action body places itself — a vendor header, a query param, or a body field. |
| `bearer`  | Token               | A token sent as the Authorization header, under the scheme the connector names.                  |
| `basic`   | Username & password | A username and password sent as HTTP Basic, which is also the shape a mailbox login takes.       |
| `oauth2`  | OAuth               | An authorization-code grant: access token, refresh token, expiry, and the granted scopes.        |

The internal `platform` method has no stored credential and cannot be combined with vendor methods. It is reserved for native platform capabilities such as task and document actions.

Credential secrets are encrypted at rest. Lists return a masked preview and metadata rather than plaintext; the authorized live runtime resolves the secret when it performs the action. A successful credential save proves storage, not that the vendor accepts the credential or grants the required scopes.

## Registering an OAuth app

The connector declares authorization/token URLs and requested scopes. Configure the vendor application separately, then connect an account using that application.

| Source | Precedence and configuration |
| --- | --- |
| Organization app | Takes precedence. An administrator supplies client ID and secret in **Settings > Connectors > OAuth apps** |
| Deployment app | Default when no organization app is configured: `CONNECTOR_OAUTH_<SLUG>_CLIENT_ID` and `CONNECTOR_OAUTH_<SLUG>_CLIENT_SECRET` |

In environment variable names, uppercase the slug and replace dashes with underscores. For a single-tenant Microsoft app, also configure its directory ID so authorization uses that tenant rather than `/common`. Organization app secrets are encrypted and not revealed again.

### Register the callback exactly

All organization OAuth connectors use this redirect URI:

```text
${SITE_URL}${BASE_PATH}/api/connectors/oauth2/callback
```

Match the scheme, host, path, and absence of a trailing slash exactly. Tale refuses to begin consent when `SITE_URL` is missing; it does not infer a public callback from the incoming request. A `redirect_uri` refusal on the vendor screen usually means the registered URI differs from the one Tale sent.

Personal OneDrive/Google Drive knowledge imports are a separate flow. Google Drive shares its OAuth application between connector and import, so register both redirect URIs on that Google client. Find the import callback in the [environment reference](https://docs.tale.dev/self-hosted/configuration/environment-reference).

### Configure Slack's event endpoint

Slack's app is deployment-only: `CONNECTOR_OAUTH_SLACK_*` and `CONNECTOR_SLACK_SIGNING_SECRET`. Its incoming event must be verified before Tale knows the organization, so an organization app cannot supply this secret.

Register `${SITE_URL}${BASE_PATH}/api/connectors/slack/events` as the Events Request URL. Without the signing secret, even the registration handshake returns `503`. With valid configuration, Tale verifies signatures and identifies the organization from the Slack workspace. The endpoint currently acknowledges events; it does not turn inbound Slack messages into conversations or automatically run an automation.

## Choosing a surface

| Need | Use |
| --- | --- |
| A supported vendor action | A shipped connector and an organization credential |
| A reusable action missing from the catalog | A source contribution with schema, deterministic mock, live backend, and tests |
| Project-specific calls to your own service | A project agent's **Secrets** and sandbox code, within that sandbox's network permissions |
| Custom logic inside an automation | A `transform` node, within the runner's available capabilities and network rules |

A secret provides authentication; it does not make an unreachable private service reachable. Confirm network access from the actual sandbox or runner before designing an integration around it.

External MCP-server registration is not available. Tale's [MCP endpoint](https://docs.tale.dev/develop/mcp-endpoint) lets an external client call Tale; it does not add an outbound connector to another MCP server.

## Where this fits

Test three things separately when contributing: schema validation, deterministic mock behavior, and the live vendor path. Check failure handling as well as success: missing credential, wrong scope, denied destination, invalid input, vendor refusal, and an approval wait for writes. The [contributor guide](https://docs.tale.dev/develop/contributor-setup) explains the local source environment; the [credential guide](https://docs.tale.dev/platform/admin/connectors) explains the administrator's setup.

# Build and maintain Tale images
Source: https://docs.tale.dev/develop/contributing-docker

Build an image when a change affects container dependencies, startup behavior or packaged application code. Start from a source checkout with the prerequisites in [Contributor setup](https://docs.tale.dev/develop/contributor-setup), a running Docker daemon and access to the base-image and package registries used by the Dockerfile.

A successful build proves that an image can be assembled. Run it in a separate development stack and exercise the changed behavior before using it in a deployment.

## What the images are

Dockerfiles use the repository root as their build context. Open the relevant Dockerfile for exact base-image versions and build arguments; the table describes each image’s purpose.

| Image | Dockerfile directory | Contents and role |
| --- | --- | --- |
| `tale-platform` | `services/platform/` | Debian-based application image with the built web app and native backend. Build stages use Bun and Node; API and worker roles reuse this image. |
| `tale-db` | `services/db/` | PostgreSQL with the supplied search/vector extensions, based on ParadeDB. Both application and knowledge database services use it. |
| `tale-proxy` | `services/proxy/` | Caddy configuration and proxy startup. |
| `tale-sandbox` | `services/sandbox/` | Sandbox orchestration, including Bun and the Docker CLI. |
| `tale-sandbox-runtime` | `services/sandbox-runtime/` | Python-based execution environment with coding harnesses, Node, Bun, browsers and document tools. |
| `tale-sandbox-egress` | `services/sandbox-egress/` | Alpine-based outbound proxy and DNS support. |
| `tale-sandbox-buildkitd` | `services/sandbox-buildkitd/` | BuildKit with the sandbox’s networking and startup configuration. |
| `tale-sandbox-llm-gateway` | `services/sandbox-llm-gateway/` | Model gateway built from Bifrost. |

Object storage and the video-ingestion sidecar use upstream images directly. They are not built from a Tale Dockerfile. Sandbox runtime and BuildKit images are launched on demand; do not assume that building only the services in a Compose file also builds them.

## Building locally

For an isolated proxy-image build, run this from the repository root:

```bash
docker build -f services/proxy/Dockerfile -t tale-proxy:docs-review .
```

The local `docs-review` tag makes the result distinguishable from a published release. The build must finish successfully before you test or tag it for distribution.

For services declared with `build:` in the repository Compose file, use:

```bash
docker compose build platform
```

`docker compose build` without a service selects all services that have a build definition. Build time depends on cached layers, network access, platform and the image; a browser or application image has different requirements from the proxy.

The repository Compose file defaults `PULL_POLICY` to `build`. Generated production Compose normally pulls release images. Use [Compose files](https://docs.tale.dev/develop/compose-files) for the supported development launcher, which also prepares services and images that a bare build does not start.

## The customisation seams

Choose the narrowest change that satisfies the requirement:

| Requirement | Where to start |
| --- | --- |
| Routing, TLS or public headers | `services/proxy/Caddyfile` and proxy configuration. Test callbacks and streaming after changes. |
| Application UI, backend or extraction behavior | Application source under `services/platform/`, followed by an application-image build and relevant tests. |
| A package or browser in agent sessions | `services/sandbox-runtime/Dockerfile`. Test in a newly created session using the changed image. |
| Sandbox outbound policy | Existing environment configuration first; proxy templates and startup code only when the configuration cannot express the change. |
| BuildKit behavior | `services/sandbox-buildkitd/`, including its network assumptions. |

Entrypoints, health checks and internal paths are implementation contracts. A fork must maintain and test changes to them across upgrades. A configuration-only change may not need a new image; see [Run Compose yourself](https://docs.tale.dev/self-hosted/install/own-compose).

## Tagging and pushing your own registry

After testing the image, set your registry namespace and an immutable tag. This example publishes only the proxy image built above; it is not a complete deployment image set. Registry authentication and permission to push are prerequisites.

```bash
export REGISTRY=registry.internal.example.com/tale
export IMAGE_TAG=reviewed-build-1
docker tag tale-proxy:docs-review "$REGISTRY/tale-proxy:$IMAGE_TAG"
docker push "$REGISTRY/tale-proxy:$IMAGE_TAG"
```

Record the resulting digest, source commit and build platform. Distribute all images required by the destination, including sandbox images and upstream dependencies. An offline environment also needs a plan for packages, browser downloads and model access; moving a single image does not make the system self-contained.

The CLI reads `GHCR_REGISTRY` for the Tale image namespace. Its selected version still determines the image tag, so publish the names and version tags the deployment expects. For independently pinned images and source commits, follow the [managed deployment reference](https://docs.tale.dev/self-hosted/install/cli-install#managed-deployments).

## Staying in sync with upstream

Keep the fork’s source changes under version control and review upstream changes before rebuilding. Record base-image versions or digests with the build. Review updates to those pins deliberately; rebuilding against an unchanged pin does not incorporate a newer upstream image automatically.

Before rollout, verify the startup role, health checks, public routes and the feature you changed. For sandbox changes, include a new session and its required network calls. Contribute generally useful fixes upstream when possible to reduce the code your fork must maintain.

## Diagnose a failed build or startup

| Symptom | Next check |
| --- | --- |
| A `COPY` source is missing | Run from the repository root with the expected build context; check `.dockerignore` and the source path. |
| Package or base-image download fails | Check registry access, authentication and the first failed build step. |
| The image builds but exits | Read that container’s startup logs and confirm its environment, mounts and role. |
| A sandbox still uses old packages | Confirm the configured runtime image and create a new session. An existing container is not replaced by retagging an image. |

Use [Container architecture](https://docs.tale.dev/self-hosted/operate/container-architecture) to trace service dependencies and [Upgrades](https://docs.tale.dev/self-hosted/operate/upgrades) for rollout and recovery.

# Run Tale from source
Source: https://docs.tale.dev/develop/contributor-setup

Run Tale from source when you want to change the product or test a contribution. You will run the web app and backend on your machine, with databases and sandbox services in Docker. For a packaged installation, follow the [self-hosted quickstart](https://docs.tale.dev/self-hosted/install/quickstart).

## Prepare your machine

Use a local checkout of the [Tale repository](https://github.com/tale-project/tale). Run the commands below from its root.

| Requirement | What it runs | Check |
| --- | --- | --- |
| Bun version pinned in the root `package.json` | Workspaces, dependency installation, Vite and development scripts | `bun --version` |
| Node.js 22.21.1 or newer in the 22.x line | The application backend; the container pins 22.21.1 | `node --version` |
| Docker with Compose | Application and knowledge databases, object storage and sandbox services | `docker info` and `docker compose version` |
| Free local ports | App on 3000 and backend on 3005 | `bun run setup:check` |

The repository pins its package-manager version. Match that version when reproducing a failure or contributing a lockfile change; the startup pre-flight checks only a minimum version.

The pre-flight command checks Bun and the two ports. Check Node and Docker separately; a green pre-flight result does not verify them. The first boot also needs network access to fetch dependencies and container images. A model provider is needed for real AI replies, but not for signing in and inspecting the app.

## Install and start

Install the workspace dependencies, check the local ports, then start the development stack:

```bash
bun install
bun run setup:check
bun run dev
```

The root development script creates missing secrets in the gitignored root `.env` and keeps existing values. Keep that file private and retain it between restarts: the backend and sandbox must share the same secrets.

The orchestrator starts Docker dependencies, starts the Node backend, waits for its API and authentication routes, then starts Vite. If the sandbox runtime image is missing, for example on a first run or after you removed local images, the orchestrator builds it from source before the backend starts. That single step can take several minutes, and agent sessions and code execution stay unavailable until it finishes. The backend applies database migrations during startup. Wait for the `READY` banner before opening `http://localhost:3000`; image downloads and first-time provisioning can make a cold boot slower.

<Check>

Open the app and sign in. Loading the dashboard verifies the browser-to-backend path; send a message with a configured provider to check an actual model turn.

</Check>

Stop the foreground processes with `Ctrl-C`. Docker data volumes persist; stopping development does not erase the instance.

## Sign in to the local workspace

The local development seeder creates `dev@tale.test` with password `TaleDev!Passw0rd` and a **Dev Workspace** organization. It leaves an existing account unchanged. The seed is restricted to loopback `SITE_URL` values.

Set `TALE_DEV_SEED_USER=0` to test first-time setup instead. To use a different local identity, supply `TALE_DEV_SEED_USER_EMAIL` and `TALE_DEV_SEED_USER_PASSWORD` through the environment. Changing these values does not reset an existing account’s password.

## Choose what to run

For normal product work, keep `bun run dev`. It starts the backend and app together and supplies the shared configuration they need.

If the backing services already run with the correct ports and credentials, skip only their Docker startup:

```bash
TALE_DEV_SKIP_DOCKER=1 bun run dev
```

This still starts a local backend. It does not make the app independent of Postgres, object storage or the sandbox. Use [Contributor compose files](https://docs.tale.dev/develop/compose-files) when your change needs the full container build.

For frontend-only work against an existing backend, run Vite directly from `services/platform` and point it at that backend:

```bash
cd services/platform
TALE_BACKEND_URL=http://localhost:3005 bunx --bun vite --host 127.0.0.1 --port 3000
```

This command does not start services, seed accounts or run migrations. The backend must already be configured for the browser origin you use.

## Resolve startup failures

| Symptom | Check next |
| --- | --- |
| `node` is missing or a Node flag is unknown | Install the Node version above and confirm that your shell resolves it. |
| Docker cannot connect | Start Docker and check `docker info` in the same shell. |
| Port 3000 or 3005 is busy | Identify the process before stopping it; it may belong to another checkout. |
| Backend fails before Vite starts | Read the first backend error and check database connectivity and credentials. |
| Sign-in works but model calls fail | Check the provider credential, selected model and sandbox services. |
| Changes appear in the wrong app | Check the URL and which checkout owns the listening process. |

On macOS or Linux, inspect the listener with:

```bash
lsof -nP -iTCP:3000 -sTCP:LISTEN
lsof -nP -iTCP:3005 -sTCP:LISTEN
```

Stop a known development process from its original terminal. Do not kill a process solely because it holds a port.

## Keep or reset local data deliberately

Databases and uploaded files persist outside the source checkout. A second Git worktree does not automatically isolate Docker service names, ports, volumes or `.env` credentials. Before running two instances, give each its own backing services and configuration.

A reset destroys development data and can affect another checkout using the same Compose project. Inspect the project's containers and volumes, back up anything you need, and stop the stack before removing state. Configuration trees under `TALE_CONFIG_DIR` have their own lifecycle; deleting a database does not reset those files.

## Use the design system

For interface changes, start with the [design-system guides](https://ui.tale.dev). They cover `@tale/ui` for app interfaces and `@tale/marketing-ui` for marketing pages, with interactive examples, tokens, and layout patterns. Reuse a package component before adding one. The guide content is in English.

## Verify a contribution

Read the repository's `AGENTS.md` and `.agents/repo.md` before changing code. Run the relevant checks while working, then the shared gate from the repository root:

```bash
bun run check
```

The gate includes formatting, lint, types and automated tests. Its Python formatting step also uses `uvx`; install that tooling before running the full gate. Browser behavior still needs a browser check, and database changes need the real-Postgres integration check required by the repository contract.

Update affected docs and every shipped locale with your change. For container work, continue with [Build Docker images](https://docs.tale.dev/develop/contributing-docker); for external integrations, start with [Call Tale from a script](https://docs.tale.dev/tutorials/developer/call-tale-from-a-script).

# MCP endpoint
Source: https://docs.tale.dev/develop/mcp-endpoint

Connect an MCP client when an agent needs to discover Tale's tools, retrieve knowledge, or build and run automations. The connection uses the same API key and organization scope as [REST](https://docs.tale.dev/develop/api-reference). Tale is the server in this connection: your external client calls Tale.

Start with `initialize`, inspect `tools/list`, then call `get_docs` before writing an automation. The deployment supplies its own supported grammar, so the client does not need to invent node types or configuration fields.

## Connect a client

### Prepare the connection

Create an [API key](https://docs.tale.dev/platform/admin/api-keys) and keep it in your client's secret configuration. The app's **Settings > API > MCP** page shows the endpoint, organization slug, and a copyable discovery request.

| Setting | Value |
| --- | --- |
| Endpoint | `https://your-host.example.com/api/v1/mcp` |
| Transport | HTTPS POST with JSON-RPC; plain JSON responses |
| Authorization | `Authorization: Bearer <api-key>` |
| Organization | `X-Organization-Slug: <slug>` |
| Protocol revisions | `2025-06-18`, or `2025-03-26` when proposed by the client |

Use a client that supports a remote HTTP endpoint with custom headers. There is no SSE event stream, session deletion, or OAuth authorization flow. OAuth discovery URLs return JSON `404`; a client requiring that flow needs a different authentication configuration. A client that only launches local stdio servers cannot use this URL directly. [Use Tale from your editor or a script](https://docs.tale.dev/develop/use-tale-from-your-editor) has ready configurations for opencode and Claude Code.

Always send the organization header in reusable integrations. It is optional only when the key holder has one organization. With several memberships, omitting it returns `400 ORG_SLUG_REQUIRED`; an unknown slug returns `404 ORG_SLUG_INVALID`, and a non-member organization returns `403 ORG_FORBIDDEN`. Each of these refusals lists the slugs you can send in `data.organizations`.

### Initialize and retrieve the authoring reference

The examples assume `TALE_URL`, `TALE_API_KEY`, and `TALE_ORG_SLUG` are already set in your environment. `TALE_URL` is the application origin, without `/api/v1`.

```bash
curl --fail-with-body "$TALE_URL/api/v1/mcp" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"docs-client","version":"1.0.0"}}}'
```

The response identifies the server as `tale-platform`. Read `result.protocolVersion` and send that negotiated value as `MCP-Protocol-Version` on later calls. The next example uses `2025-06-18`; replace it if your initialization negotiated the older revision. An unsupported header value returns `400`.

```bash
curl --fail-with-body "$TALE_URL/api/v1/mcp" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --header 'MCP-Protocol-Version: 2025-06-18' \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_docs","arguments":{}}}'
```

A successful `get_docs` result contains the automation reference as text and has no error flag set. To inspect tool schemas instead, send `method: "tools/list"`. The current inventory has 22 tools. Keep the JSON-RPC `id` so a client can match a result to its request.

### Transport and batches

| Request | Response behavior |
| --- | --- |
| One JSON-RPC message | One JSON-RPC result or error |
| Batch of up to 20 messages | An array of responses; notifications have no response entry |
| Notifications only | HTTP `202` |
| `OPTIONS` | HTTP `204`, `Allow: POST, OPTIONS`; no key required |
| Any other HTTP method | HTTP `405`, `Allow: POST, OPTIONS` |

Every additional tool call in a batch consumes the same request budget as a separate call. If a batch exhausts its budget, the refused entry is JSON-RPC `-32000` with `data.retryAfterMs`; the enclosing HTTP response remains `200` and has no `Retry-After`. A single request rejected at the HTTP boundary gets REST `429`. Handle both cases using the [rate-limit guidance](https://docs.tale.dev/develop/rate-limits).

The endpoint supplies no CORS headers for browser key use. Keep the API key on a trusted server or in the MCP client's credential store.

## The tools

`tools/list` is the source for each tool's input schema. Missing, mistyped, blank, or unexpected arguments receive JSON-RPC `-32602` before execution. The document passed to `validate_automation`, `run_automation`, `test_automation`, or `save_automation` is intentionally an open envelope: `get_docs` explains its grammar, and the engine validates its contents.

Tools also expose `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`. Hosts can use these annotations to explain a call, but they do not grant permission or guarantee safety. Reads are marked read-only; saving writes a version; deployment and trigger changes can replace existing state; live runs can contact real services.

### Authoring

| Tool                  | What it does                                               |
| --------------------- | ---------------------------------------------------------- |
| `get_docs`            | The automation authoring reference — grammar, node kinds, capability nodes and the method table in this endpoint's own `tools/call` dialect — as text. |
| `get_catalog`         | Every node type this deployment can execute; `kind` narrows to one node kind and `compact: true` drops the input schemas. |
| `search_catalog`      | Search the node-type catalog by keyword.                   |
| `validate_automation` | Validate an automation document without saving it.         |
| `run_automation`      | Run an automation document directly against the deterministic mocks. |
| `test_automation`     | Run an automation's own acceptance tests.                  |
| `save_automation`     | Save an automation document as a new immutable version.    |
| `get_automation`      | Read one saved version — the latest when unversioned, `version: "deployed"` for the live one (`AUTOMATION_VERSION_UNKNOWN` while nothing is deployed). |
| `list_automations`    | The organization's automations with their latest and deployed versions and the projects each is installed in (`projectIds`). |
| `deploy_automation`   | Promote one saved version to be the live version.          |

Use the authoring loop in this order: read the grammar and catalog, validate the document, run it against mocks, run its acceptance tests, save a version, then deploy that version. A successful mock run verifies the simulated path; it does not prove vendor credentials, network access, or real effects.

### Run & trigger management

| Tool             | What it does                                                                                                   |
| ---------------- | -------------------------------------------------------------------------------------------------------------- |
| `run_deployed`   | Run the deployed version live and WAIT for the finished result — output, trace and effects in one answer; a run that outlives the wait answers with its `runId` to poll. Takes the same optional `idempotencyKey` as `start_run`, on the same ledger the REST endpoint keeps: a repeat answers the first run with `duplicate: true` and starts nothing, whichever door started it. |
| `start_run`      | Start the deployed version in the background and return a run handle immediately; poll get_run for the result. Takes an optional `idempotencyKey` — the REST endpoint's `Idempotency-Key`, the same ledger: the same key with the same arguments answers the first run's handle with `duplicate: true` and starts nothing, the same key with different arguments is refused (`IDEMPOTENCY_KEY_REUSED`). The `Idempotency-Key` HTTP header is refused on this endpoint (**400**, `INVALID_HEADER`) — a batch carries up to 20 calls, so the key rides in the tool arguments. |
| `list_runs`      | Recent runs the key may read, newest first — of one automation or across the organization's projects; each names its `projectId`. |
| `get_run`        | One run in full: status, output, trace, effects and `projectId` — a project run's id is the one `GET /api/v1/projects/{id}/runs/{runId}` takes. |
| `cancel_run`     | Stop a run at its next node boundary.                                                                          |
| `list_versions`  | One automation's immutable version history; each row says whether it is the `deployed` one, and `deployedVersion` names it beside the list (`null` while nothing is deployed). |
| `list_triggers`  | What starts the automations (never the webhook secret).                                                        |
| `delete_trigger` | Unbind an automation's trigger; its versions and run history stay.                                             |
| `set_trigger`    | Bind what starts the automation (schedule/webhook/event). A webhook's `token` is answered once, here, and never again — store it; `deployed` says whether deliveries will run: a trigger bound to an automation with no deployed version is stored and fires nothing until one is deployed. |

| Choose | When |
| --- | --- |
| `run_automation` | Try an unsaved document against deterministic mocks; `mode: "live"` is refused |
| `run_deployed` | Run the saved deployment live and wait up to 30 seconds; poll the returned `runId` if it continues |
| `start_run` | Start the saved deployment in the background and poll `get_run`; pass `idempotencyKey` to make a retry safe |

Both deployed-run tools use the durable runner with the same authorization and execution records. `start_run` accepts an optional `projectId`. A project-bound automation must run in a project where it is installed; a sole binding can be selected automatically. With no bindings, omission means organization scope. Read `projectIds` from `list_automations` and the actual `projectId` from the returned handle rather than guessing a REST polling URL.

### Capabilities & knowledge

| Tool                  | What it does                                                                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `search_capabilities` | Search everything this organization can do — its deployed automations, by name and description.                     |
| `invoke_capability`   | Invoke one capability by id. An action the organization gates returns a pending-approval result instead of running. |
| `get_knowledge`       | Retrieve passages from the organization's knowledge — its documents and its crawled web pages. `corpus` is `private` (documents), `public-web` (crawled pages) or `all`; the REST spellings `documents` and `web` are taken too. `query` is capped at 2000 characters. Each passage carries `text`, `source` (a title), `ref`, `corpus`, `chunkIndex`, `score`, `similarity` when the dense leg ranked it, `url` for a web page, and — for a document — the `documentId` that `GET /api/v1/documents/{id}` takes (a project file's id for a project hit) and its `projectId`, the same citation the REST search answers. |

The capability registry currently contains deployed automations. It does not include builtin tools, connector actions, skills, or external MCP servers. Invoking a deployed automation is the same live operation as `run_deployed`. If approval is needed, a `pending` result lets the client explain that a person must decide before execution continues.

## What the key may do

| Operation | Required access |
| --- | --- |
| Reads, validation, mock runs and acceptance tests, capability search, knowledge retrieval | Organization membership, plus the resource's normal access rules |
| Save, deploy, set/delete a trigger, cancel a run, or execute live | Developer capability, plus the resource's normal access rules |

The key identifies its holder; it does not expand that person's role or project access. Live `invoke_capability` calls also pass through the execution checks.

Read `GET /api/v1/me` before configuring privileged tools: `capabilities.developer` reports the current role gate, while `deploymentEditor` is a separate operator allowlist and does not authorize MCP authoring. The MCP tool-error envelope below still applies; a REST capability check does not change JSON-RPC error handling.

### Distinguish a transport error from a refused tool

| Result | How to handle it |
| --- | --- |
| JSON-RPC `-32601` | Correct the unknown method |
| JSON-RPC `-32602` | Correct the tool name or arguments using `tools/list`; a value outside an enumerated set is refused with the set named |
| Tool result with `isError: true` | Read its text payload's stable `code`, explanatory `error`, and actionable `hint`; `data` may contain field problems |
| `validate_automation` with `valid: false` | Normal validation result; inspect `errors`, even though `isError` remains false |
| Capability result `pending` | Normal approval outcome; do not treat it as completion or retry it as a failure |
| Capability result `refused` | Error result; correct the stated cause |

Tool refusal codes include `AUTOMATION_NOT_FOUND`, `AUTOMATION_VERSION_UNKNOWN`, `AUTOMATION_NOT_DEPLOYED`, `RUN_NOT_FOUND`, `AUTOMATION_INVALID`, `AUTOMATION_TESTS_FAILING`, `LIVE_MODE_UNAVAILABLE`, and `NOT_SUPPORTED`. The latter means the host does not support that run/version/trigger operation. `start_run` refuses a reused `idempotencyKey` with different arguments as `IDEMPOTENCY_KEY_REUSED`; `invoke_capability` refuses an id the registry does not hold — a saved-only automation is not in it — as `CAPABILITY_NOT_FOUND` and input its schema rejects as `CAPABILITY_INPUT_INVALID`; `get_knowledge` lifts the knowledge endpoint's own codes through (`KNOWLEDGE_UNAVAILABLE` when the search itself failed). Platform errors retain their own code, hint, and optional data; for example, missing developer access returns `FORBIDDEN_DEVELOPER_SETTINGS`.

An unknown automation name is an error even for `list_versions`, `list_runs`, and `list_triggers`; an empty list means an existing automation has no matching items. The one exception is run history: a deleted automation keeps its runs, so `list_runs {name}` answers them for as long as they exist, and only a name that never ran is `AUTOMATION_NOT_FOUND`. `get_catalog` narrowed to a core node kind (`transform`, `llm`, `agent`, `subautomation`) answers an empty list with a `hint` pointing at `get_docs`, as `search_catalog` does. Invalid documents passed to tools that need a valid one, search failures, and missing deployments set `isError: true`. Only the validation tool reports an invalid document as its ordinary verdict.

## Where this fits

REST and MCP share keys, organization scoping, and durable run objects. Use REST when you want explicit HTTP routes; use MCP when your client understands tool discovery and calls. Tale does not register or call external MCP servers through this endpoint.

# Build with Tale
Source: https://docs.tale.dev/develop/overview

Use these guides when writing a client, connecting an external system, or changing Tale itself. Start with the smallest working request, then add the authentication, scope, and recovery handling your integration needs.

## Choose a development task

| What you want to build | Start here |
| --- | --- |
| A script that sends a message and reads the reply | [Call Tale from a script](https://docs.tale.dev/tutorials/developer/call-tale-from-a-script) |
| A client for projects, tasks, files, or other resources | [API reference](https://docs.tale.dev/develop/api-reference) |
| A connection from an MCP client | [MCP endpoint](https://docs.tale.dev/develop/mcp-endpoint) |
| AI help in your editor, with Tale's knowledge or models | [Use Tale from your editor or a script](https://docs.tale.dev/develop/use-tale-from-your-editor) |
| An automation triggered by another system | [Webhooks](https://docs.tale.dev/develop/webhooks) |
| A filesystem client for documents | [WebDAV API](https://docs.tale.dev/develop/webdav-api) |
| A new connector | [Connector development](https://docs.tale.dev/develop/connectors) |
| A change to Tale's application code | [Contributor setup](https://docs.tale.dev/develop/contributor-setup) |

## Make the first request reliable

Choose the credential with the surface: REST, MCP, and the model endpoints use API keys, WebDAV uses an app password, and a webhook uses a secret trigger URL. These credentials are not interchangeable.

Create a separate API key for each integration, send it only to the intended instance, and keep it out of source control. [Make your first API request](https://docs.tale.dev/get-started/developers) explains instance URLs and organization scope. For a long-running operation, distinguish the accepted request from its eventual result: poll the resource or run and handle a failed outcome.

Read the [rate limits](https://docs.tale.dev/develop/rate-limits) before adding retries. Check [instance availability](https://docs.tale.dev/develop/status-page) when troubleshooting a connection. The API reference describes the error envelope and the generated specification for the current checkout.

## Build inside the platform

For agents, projects, and the automation editor, use the [Developer guide](https://docs.tale.dev/platform/developer/overview). [AI-assisted development](https://docs.tale.dev/develop/ai-assisted-development) explains how to combine authoring tools with validation and review.

<Video src="https://docs.tale.dev/videos/en/tutorials/ep10-developers/ep10-developers.en.mp4" poster="https://docs.tale.dev/videos/en/tutorials/ep10-developers/ep10-developers.en.webp" captions="https://docs.tale.dev/videos/en/tutorials/ep10-developers/ep10-developers.en.vtt" lang="en" title="Bonus — Tale for developers" caption="Bonus — Tale for developers (2:08)">

</Video>

# Handle rate limits
Source: https://docs.tale.dev/develop/rate-limits

Tale limits API traffic by the key holder. All API keys belonging to the same person share that person’s budget. Account for every integration and polling worker using that identity, rather than budgeting each key independently.

The limits below describe the current backend. An operator’s proxy or a downstream provider may impose additional limits.

## The buckets

A token bucket refills continuously up to its burst capacity. A short batch can use that capacity, but sustained traffic must stay within the refill rate.

| Traffic | Sustained rate | Burst | Budget owner |
| --- | --- | --- | --- |
| General `/api/v1` traffic, including MCP and the model endpoints | 120/minute | 200 | Key holder |
| Run starts, model-message sends and task starts | 20/minute | 40 | Key holder |
| Project upload handoff and file binding | 240/minute | 300 | Key holder |
| Failed API-key authentication | 20/minute | 40 | Source IP |
| Webhook deliveries before token validation | 120/minute | 240 | Sender address |
| Deliveries to a verified webhook trigger | 20/minute | 40 | Trigger |

REST execution and upload requests also consume the general budget. For example, a project file needs an upload-handoff request and a file-bind request; each counts against both the general and upload budgets. The larger upload bucket does not allow a user to bypass the general limit.

Execution includes project and non-project automation starts, thread-message sends and explicit task starts. Task intake also consumes the execution budget when `runWorkflowSlug` is supplied. A starting-work request is charged once its body and headers have passed the endpoint's own checks — a `400 INVALID_BODY` or `INVALID_HEADER` spends nothing — and before anything is looked up, so a `404` for a thread, task or automation you cannot see costs a token, as does a `409` the state answers. Some mutations, such as task comments and folder changes, have additional domain budgets shared with the app.

MCP batches have their own accounting: additional tool calls consume additional request budget. See [MCP endpoint](https://docs.tale.dev/develop/mcp-endpoint) for the difference between an HTTP `429` and a refused message inside a batch. Webhook budgets are separate from API-key traffic; both sender and trigger limits must allow a delivery.

Calls to the [model endpoints](https://docs.tale.dev/develop/api-reference#model-endpoints) under `/api/v1/openai` and `/api/v1/anthropic` count against the general budget only, one request each, streamed or not; what a call may spend is capped separately by budget rules. A person, and each API key, may also have eight of these calls running at once: a ninth answers `429` with `code` `MODEL_API_CONCURRENCY_EXCEEDED` and `Retry-After: 2`.

The execution bucket limits how quickly messages are accepted, not how many turns run at once. Accepted chat messages share a deployment-wide queue across organizations and keys. Each worker batch runs up to `WORKER_CONCURRENCY` turns, 5 by default; the next batch waits for the current one to settle. A successful send can therefore wait behind other clients’ work. Queue position and estimated start time are not exposed.

## The 429

An HTTP limit refusal includes `Retry-After` in whole seconds. The JSON body provides the same wait in milliseconds. This illustrative response means wait at least two seconds:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json

{
  "error": "Too many requests — retry after 1500 ms",
  "code": "RATE_LIMITED",
  "requestId": "example-request-id",
  "data": {"retryAfterMs": 1500}
}
```

Branch on `code`; `error` is a sentence describing the wait, and `requestId` identifies the request for investigation. This is the REST response format. The app’s `/api/app` and webhook limit responses keep the machine code in `error`, so do not parse that text across surfaces. Tale does not expose remaining-budget counters: track your traffic and honor the server’s wait instruction.

1. Stop the worker’s immediate retry loop.
2. Wait at least `Retry-After`. If multiple workers share the identity, coordinate their pause.
3. Retry with a bounded exponential delay and jitter when refusals continue. For example, grow a delay from one second up to sixty seconds, always honoring a longer server-provided wait.
4. Preserve the original idempotency key for operations that support one. A timeout after a run start may mean the run was already accepted.

A spending cap answers `429` too, with `code` `BUDGET_EXCEEDED`: a budget rule that applies to the key holder — their own, a team’s, the organization’s, or the API key’s — has been reached. A short wait does not help. `Retry-After` names the time until the cap’s period resets, and `data` names the cap: `scope`, `period`, `limitCode`, `used`, `limit`, and `resetsAt` in epoch milliseconds. Nothing is queued; pause the work until `resetsAt`, or ask an administrator to raise the limit under [Policies & Limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits). On the model endpoints, both 429s come in the OpenAI or Anthropic error shape with the same `code` and `Retry-After`. A spent budget names its cap in the message there instead of in `data`, and carries `x-should-retry: false` so the vendors' SDKs do not retry it on their own.

Other `4xx` responses usually need a corrected request, credential or permission. Do not treat every failure as a rate limit; use the [error model](https://docs.tale.dev/develop/api-reference#error-model).

## Plan polling and retries

An `ETag` response of `304` still costs a request. It saves response bytes, not budget. Polling one run every five seconds consumes twelve reads per minute before any retries or other work. Leave capacity for those other calls instead of filling the entire budget with polls.

Request only the fields you need, such as `?fields=status,finishedAt` on a run. Slow down when a run is waiting for a human, and stop polling terminal runs. Follow [Start a run, then poll it](https://docs.tale.dev/develop/api-reference#start-a-run-then-poll-it) for states and idempotent starts.

For larger imports, use supported batch operations such as `POST /api/v1/contacts/bulk`, and spread batches over time. Creating more keys for the same user does not increase the budget. If a workflow needs its own service identity, provision that identity through your normal account and permission process; do not use key rotation as a retry strategy.

# Check instance availability
Source: https://docs.tale.dev/develop/status-page

Open `/status` on your Tale host to check availability without signing in. Monitors can read the same summary from `/status.json`. The summary covers the backend and deployment stores; it does not prove that every model or organization-specific connection works.

## Poll the status document

Set `TALE_BASE_URL` to the instance URL and request its status:

```bash
curl --fail-with-body --silent --show-error \
  "$TALE_BASE_URL/status.json"
```

Inspect the JSON body, not only the HTTP status. During local verification with an unavailable object store, the endpoint returned HTTP `200` and this degraded result:

```json
{
  "status": "degraded",
  "checkedAt": "2026-09-14T04:31:20.847Z",
  "components": [
    { "id": "backend", "status": "operational" },
    { "id": "database", "status": "operational" },
    { "id": "object-store", "status": "outage" }
  ]
}
```

In this case the app can answer requests and reach its database, while file operations need investigation. A monitor that treats every HTTP `200` as healthy would miss that failure.

## Interpret the components

| Field or component | Meaning |
| --- | --- |
| `status: operational` | All reported components are available. |
| `status: degraded` | Some components are unavailable. |
| `status: outage` | All reported components are unavailable. |
| `checkedAt` | Time of the status check, in UTC. |
| `backend` | Application backend reachability. |
| `database` | Application and deployment knowledge database health, combined. |
| `object-store` | Deployment file-store health. |

Component entries report `operational` or `outage`. If the backend cannot answer, the dependent store rows cannot be established and show as unavailable too. Accept new component IDs without breaking your parser.

## Configure a monitor

For an automated health check, install `jq` and make the verdict affect the command’s exit status. This example fails on a network error, invalid JSON, or any overall state other than `operational`:

```bash
set -o pipefail
curl --fail-with-body --silent --show-error --max-time 10 \
  "$TALE_BASE_URL/status.json" | jq -e '.status == "operational"'
```


The JSON endpoint requires no API key and does not consume an API-key budget. Its result is cached for five seconds; backend store probes refresh separately, so it is a recent summary rather than a fresh storage transaction per poll. Set a request timeout and alert on repeated failures or a non-operational body according to your service needs.

`/status.json` allows cross-origin reads with `Access-Control-Allow-Origin: *`. `HEAD` returns headers without the body and `OPTIONS` advertises `GET, HEAD, OPTIONS`. Use `GET` when your monitor must inspect the component verdict.

## Distinguish liveness from readiness

The production web server’s `/api/health` endpoint is a lightweight process check. It is useful for container liveness, but does not replace the status document’s dependency checks. A development Vite server can proxy that path differently and return `404`; use `/status.json` to inspect the running development app.

On a production deployment, `/health` is the edge proxy’s own liveness response: it returns `OK` even while the application restarts. An unrecognized route such as `/healthz` can return the app shell with HTTP `200`. Neither is a readiness check. Use the documented `/status.json` or `/api/health` endpoint according to what your monitor needs to establish.

A green status does not check an external model’s credit, entitlement or availability. It also does not exercise a full upload, knowledge query, chat turn or automation. Add a controlled end-to-end check for the operation your integration depends on.

## Investigate a failure

For a degraded component, use [Troubleshooting](https://docs.tale.dev/self-hosted/operate/observability/troubleshooting) to find the corresponding logs. For a failed API call with healthy instance status, inspect the [API error code](https://docs.tale.dev/develop/api-reference#error-model); `429` is a [rate-limit response](https://docs.tale.dev/develop/rate-limits), not an instance-outage verdict.

Cloud instances expose the same status paths on their own host. Service incident communication and assurance materials are described in [Trust and compliance](https://docs.tale.dev/cloud/trust-and-compliance).

# Use Tale from your editor or a script
Source: https://docs.tale.dev/develop/use-tale-from-your-editor

Tale reaches your development work in four ways. They differ in which language model runs and in how much of the work Tale governs:

| You want | Use | Model | What Tale governs |
| --- | --- | --- | --- |
| Your organization's models as the model provider of opencode, Claude Code, or an SDK script | [The model endpoints](https://docs.tale.dev/develop/use-tale-from-your-editor#model-endpoints) | An organization model you name by its id in each request | Each model call: model access, input guardrails, budgets, usage under your name and key; not the answers |
| Ask the workspace assistant from a script | [The REST chat API](https://docs.tale.dev/develop/use-tale-from-your-editor#script-the-rest-chat-api) | An organization model you name in each request | The whole turn: model access, budgets, usage under your name |
| Tale's knowledge and automation tools inside opencode or Claude Code | [The MCP endpoint](https://docs.tale.dev/develop/use-tale-from-your-editor#connect-opencode-or-claude-code) | The model configured in your editor | Only the tool calls; the editor's model calls stay outside Tale |
| Have a script edited on your organization's models | [A project agent on a task](https://docs.tale.dev/develop/use-tale-from-your-editor#let-a-project-agent-edit-scripts) | An organization model the agent is configured with | The whole run: sandbox, budgets, usage, review |

An editor can use two of them with the same key: the model endpoints as its model provider and the MCP endpoint for Tale's knowledge. [The last section](https://docs.tale.dev/develop/use-tale-from-your-editor#where-the-openai-compatible-endpoint-went) explains how the model endpoints differ from the OpenAI-compatible layer of Tale 0.3.

## Create an API key

Every path from outside the app starts with a personal API key. Owners, Admins, and Developers create one under **Settings > API > REST** with **Create API key**, choosing a name and an expiration, and so can a member an Admin granted a competence that is used with a key, such as **Call models over the API**. The secret is shown once; copy it into your secret store or a private shell environment before closing the dialog. [API keys](https://docs.tale.dev/platform/admin/api-keys) covers creation, rotation, and revocation.

A key acts as you. It carries your current role and project access, and the usage it causes is booked under your name. Chat turns, model calls, and automation runs you start with the key also record the key, so API-key limits apply to them as well; a project-agent run is booked to you alone. An Admin can cap what you spend with a personal, team, or role budget under [Policies and limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits); a request over a cap is refused with `429 BUDGET_EXCEEDED`.

The examples on this page read three environment variables. `TALE_URL` is your instance's origin without `/api/v1`. `TALE_ORG_SLUG` is the organization slug, shown under **Settings > API > MCP**, under **Settings > API > Models** once the model endpoints are on, and returned by `GET /api/v1/me`. Export all three in your shell, and keep `TALE_API_KEY` out of files you commit.

## Use your organization's models from your tools {#model-endpoints}

The model endpoints let opencode, Claude Code, and scripts built on the OpenAI or Anthropic SDKs use your organization's approved models as their model provider. Tale speaks the OpenAI Chat Completions and Anthropic Messages interfaces these tools already use, so you change a base URL, a key, and a model name rather than your code. Each request is a bare model call: no workspace assistant, thread, or Tale tool is involved, and the answer comes back as the model sent it.

### Before you start

The endpoints are off until an Admin turns on **Model endpoints for API keys** under **Settings > Governance > Models**; [Models](https://docs.tale.dev/platform/admin/governance/content-models#model-endpoints) describes the switch. Owners, Admins, and Developers may then call them through their role; any other member needs the competence **Call models over the API**, which an Admin grants under [Competences](https://docs.tale.dev/platform/admin/governance/competences). `GET /api/v1/me` answers `capabilities.modelApi: true` once your key may call them.

**Settings > API > Models** collects what your tools need: both base URLs, the organization slug, the models you can call with a copy button for each id, and configuration to copy for opencode, Claude Code, and the OpenAI SDK for Python. While your organization has not turned the endpoints on, the tab reads **Model endpoints are not enabled for your organization**, and Owners and Admins find **Open model access** there.

<Frame caption="Settings > API > Models — the base URLs, the organization slug, and the models you can call.">

![The Models tab under Settings > API showing the OpenAI- and Anthropic-compatible base URLs, the Authorization header for an API key, the organization slug northlight-labs, and five model ids, each with a copy button.](https://docs.tale.dev/images/develop/settings-api-models.webp)

</Frame>

### Connection settings

| Setting | Value |
| --- | --- |
| OpenAI-compatible base URL | `https://<host>/api/v1/openai`; the OpenAI SDKs and opencode append `/chat/completions` |
| Anthropic-compatible base URL | `https://<host>/api/v1/anthropic`; the Anthropic SDKs and Claude Code append `/v1/messages` |
| Key | Your personal API key as `Authorization: Bearer <key>`. Tale refuses the `x-api-key` header with `401`, so an Anthropic client must send the key as an auth token |
| Organization | `X-Organization-Slug: <slug>`, required when you belong to several organizations |
| Model | `<providerSlug>/<modelId>`: the provider's slug, a slash, and the model's id in that provider's catalog, such as `openrouter/anthropic/claude-sonnet-4.6` or `deepseek/deepseek-v4-flash` |

The same id works on both endpoints. Check the key and list the ids you may call, with your own host and slug in place of `tale.example.com` and `acme`:

```bash
curl https://tale.example.com/api/v1/openai/models \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: acme"
```

The answer is an OpenAI model list: `owned_by` is the provider slug, and `created` is always `0`. It looks like this, with the ids your organization offers you:

```json
{
  "object": "list",
  "data": [
    { "id": "openrouter/anthropic/claude-sonnet-4.6", "object": "model", "created": 0, "owned_by": "openrouter" },
    { "id": "deepseek/deepseek-v4-flash", "object": "model", "created": 0, "owned_by": "deepseek" }
  ]
}
```

The list holds your organization's chat models that a provider credential of type **API key** or **Environment variable** serves, narrowed by each credential's model allowlist and by your model access. Models served through a subscription credential are not listed, and neither are models of a provider whose endpoint is set per credential, such as Azure, or models whose tool calls work only through OpenAI's Responses API, such as GPT-6.1 Sol, which these endpoints do not relay. `GET /api/v1/models` gives each of these models' context window, capabilities, and prices under the same `providerSlug` and `id`.

### Point opencode at Tale

Add Tale as a provider in your global `opencode.json` or the project's. opencode reaches it through its OpenAI-compatible package and reads the key from `TALE_API_KEY`. List every model you want to choose under `models`, keyed by its id; `model` sets the default as `tale/` followed by that id.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "tale": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Tale",
      "options": {
        "baseURL": "https://tale.example.com/api/v1/openai",
        "apiKey": "{env:TALE_API_KEY}",
        "headers": { "X-Organization-Slug": "acme" }
      },
      "models": {
        "openrouter/anthropic/claude-sonnet-4.6": { "name": "Claude Sonnet 4.6" }
      }
    }
  },
  "model": "tale/openrouter/anthropic/claude-sonnet-4.6"
}
```

The `provider` block can sit beside the `mcp` block from [the MCP configuration](https://docs.tale.dev/develop/use-tale-from-your-editor#opencode) in the same file. Start opencode from a shell where `TALE_API_KEY` is set.

### Point Claude Code at Tale

Claude Code reads its model provider from environment variables. Set them in the shell you start it from:

```bash
export ANTHROPIC_BASE_URL="https://tale.example.com/api/v1/anthropic"
export ANTHROPIC_AUTH_TOKEN="$TALE_API_KEY"
export ANTHROPIC_CUSTOM_HEADERS="X-Organization-Slug: acme"
export ANTHROPIC_MODEL="openrouter/anthropic/claude-sonnet-4.6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="openrouter/anthropic/claude-haiku-4.5"
unset ANTHROPIC_API_KEY
claude
```

`ANTHROPIC_AUTH_TOKEN` sends the key as a bearer token. Leave `ANTHROPIC_API_KEY` unset: Claude Code would send it as `x-api-key`, which Tale refuses. `ANTHROPIC_DEFAULT_HAIKU_MODEL` is the model Claude Code uses for background tasks; both model variables must name ids from your list. Claude Code's WebSearch tool asks the model vendor to run the search, so Tale refuses those requests; the tools Claude Code runs on your machine work as usual.

### Call the models from a script

The OpenAI SDK for Python needs a different base URL and the organization header. This example reads the key from `TALE_API_KEY`, asks once for a whole answer, then streams a second one:

```python
import os

from openai import OpenAI

client = OpenAI(
    base_url="https://tale.example.com/api/v1/openai",
    api_key=os.environ["TALE_API_KEY"],
    default_headers={"X-Organization-Slug": "acme"},
)
MODEL = "openrouter/anthropic/claude-sonnet-4.6"

reply = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "What does the cron expression 0 3 * * 1 mean?"}],
)
print(reply.choices[0].message.content)

stream = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "Write a commit message for a typo fix."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
print()
```

Tools, `tool_calls`, and images work as they do with OpenAI, and the answer's `model` is the id you sent. A stream ends with `data: [DONE]`; its closing usage chunk arrives only when you pass `stream_options={"include_usage": True}`.

The Anthropic SDK for Python takes the key as an auth token. Run it with `ANTHROPIC_API_KEY` unset, because the SDK would send that variable's value as `x-api-key`, which Tale refuses:

```python
import os

import anthropic

client = anthropic.Anthropic(
    base_url="https://tale.example.com/api/v1/anthropic",
    auth_token=os.environ["TALE_API_KEY"],
    default_headers={"X-Organization-Slug": "acme"},
)

message = client.messages.create(
    model="openrouter/anthropic/claude-sonnet-4.6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain the error ECONNRESET in one paragraph."}],
)
print(message.content[0].text)
```

### What Tale checks on every call

Each call is governed like a chat request, for the person whose key sent it:

- **The switch and your right.** The organization has turned the endpoints on, and your role or competence lets you call them.
- **The model.** It must be on your list, and the organization's model access must allow it for you at the moment of the call. The model allowlist of the provider credential applies as well.
- **What the model can read.** Images need a model with vision, and tools a model that takes them. Images travel as OpenAI `image_url` parts with a `data:` or `https:` URL, or as Anthropic `image` blocks in base64 or with an `https:` URL, also inside tool results. Documents travel as OpenAI `file` parts or Anthropic `document` blocks.
- **The input guardrails.** The organization's content safety, personal-data protection, and moderation provider read every text the request carries before it is sent on: system and developer instructions, your turns and the assistant's, tool calls, tool results and tool definitions, and documents given as text. A block refuses the request, and a mask sends the model the masked text. The model's answers, and images and documents that are not text, are not filtered. [Guardrails](https://docs.tale.dev/platform/admin/governance/guardrails#model-endpoints) has the details.
- **The budgets.** Before the call, Tale works out its worst case, the estimated prompt plus the most output it may produce at the model's catalog price. It refuses the call with `429 BUDGET_EXCEEDED` when that worst case does not fit what is left under a budget cap that applies to you, your teams, the organization, or the key, and holds it against those caps while the call runs; a lower `max_tokens` fits more. Afterwards it books the cost the model gateway measured and the reported tokens under your name and the key. A call you break off while Tale is still checking it is never sent on and is not booked. Breaking it off once it has been sent cancels its request to the provider as well, and the call is still booked: at least for its prompt and the output that had reached you, at the model's catalog price. Each call counts as one request and appears as **Direct API** in usage analytics.
- **Eight calls at a time.** You, and each of your keys, may have eight calls running at once. A ninth is refused with `429 MODEL_API_CONCURRENCY_EXCEEDED` and a `Retry-After` of two seconds.

Your tools never see a provider key. Tale relays each call through its model gateway with a key minted for that one request and that one model. Revoking your API key under **Settings > API > REST** ends its access with the next request; an answer that is already streaming finishes.

### What the endpoints do not serve

- **Tools the model vendor runs.** OpenAI's `web_search_options` and any tool whose type is not `function` or `custom`, and Anthropic's web search, web fetch, code execution, and MCP toolsets, with the `mcp_servers` and `container` fields, are refused with `400 MODEL_API_VENDOR_TOOL_UNSUPPORTED`: Tale could neither meter nor audit them. Your own tools are relayed and come back as `tool_calls` or `tool_use`, including Anthropic's client tools `bash`, `text_editor`, `computer`, and `memory`.
- **Audio input.** Requests with `input_audio` parts are refused.
- **Requests Tale cannot bill or keep in your organization.** More than eight answers per request (`n`), files stored in the vendor account (an OpenAI `file_id`, an Anthropic `file` source), a `service_tier` other than `auto` or `default` (`auto` or `standard_only` on Anthropic), audio output, and `store: true` are refused with `400 INVALID_BODY`.
- **Other routes.** Anthropic's `count_tokens` and every other Anthropic route are not served, and neither are OpenAI routes beyond chat completions and the model list, such as embeddings, Responses, or image generation.
- **Tale's own assistant and tools.** For those, use [the REST chat API](https://docs.tale.dev/develop/use-tale-from-your-editor#script-the-rest-chat-api) or [the MCP endpoint](https://docs.tale.dev/develop/use-tale-from-your-editor#connect-opencode-or-claude-code).

### Troubleshoot a refused call

Every refusal comes in the error shape of the interface you called, so your SDK reports it as an OpenAI or Anthropic error. Its `code` field carries Tale's stable code; the [API reference](https://docs.tale.dev/develop/api-reference#model-endpoints) lists them all.

| Status and code | What to do |
| --- | --- |
| `401 UNAUTHORIZED` | Send the key as `Authorization: Bearer`, never as `x-api-key`. For Claude Code, set `ANTHROPIC_AUTH_TOKEN` and unset `ANTHROPIC_API_KEY`; for the Anthropic SDKs, pass the key as `auth_token` or `authToken`. A revoked or expired key answers `401` too. |
| `400 ORG_SLUG_REQUIRED` | You belong to several organizations. Send `X-Organization-Slug`. |
| `403 MODEL_API_DISABLED` | The organization has not turned the endpoints on. Ask an Admin. |
| `403 MODEL_API_FORBIDDEN` | Your role cannot call them. Ask an Admin to grant **Call models over the API**. |
| `404 MODEL_API_MODEL_UNKNOWN` | The id is not on your list. Copy one from `GET /api/v1/openai/models` or the **Models** tab, provider slug included. |
| `403 MODEL_API_MODEL_FORBIDDEN` | Model access blocks this model for you. Choose another model or ask an Admin. |
| `400 MODEL_API_VISION_UNSUPPORTED`, `400 MODEL_API_TOOLS_UNSUPPORTED` | Choose a model that reads images or takes tools, or send the request without them. |
| `400 MODEL_API_VENDOR_TOOL_UNSUPPORTED` | Remove the tool the vendor would run, such as a web search. In Claude Code, the WebSearch tool causes it. |
| `400 MODEL_API_GUARDRAIL_BLOCKED` | A guardrail refused the system prompt or a message, and nothing reached the model. Rephrase, or ask an Admin about the rule. |
| `403 MODEL_API_GUARDRAIL_UNSUPPORTED` | The organization's personal-data protection tokenizes, which the model endpoints cannot honour. An Admin can switch it to mask or block. |
| `429 RATE_LIMITED` | You sent more than your API keys' shared request budget allows. Wait for `Retry-After`; see [Rate limits](https://docs.tale.dev/develop/rate-limits). |
| `429 BUDGET_EXCEEDED` | A budget cap is reached. `Retry-After` names the time until it resets, and the answer carries `x-should-retry: false` so the SDKs do not retry. Wait, or ask an Admin to raise the cap. |
| `503 MODEL_API_UNAVAILABLE`, `503 MODEL_API_GUARDRAIL_UNAVAILABLE` | A service the call needs is unavailable, such as the model gateway or the moderation provider. Retry later; if it persists, ask an Admin to check the provider credential or the moderation provider. |
| `MODEL_API_UPSTREAM_ERROR` | The model vendor refused the call, and the message is the vendor's. `400`, `413`, `422`, `429`, `503`, and `529` keep their status; any other refusal arrives as `502`. |

## Script the REST chat API

The REST chat API gives a script the same assistant members use in the app's chat. It is not a bare model call: every turn runs the built-in workspace assistant, which searches your organization's knowledge when the question calls for it and redirects requests for documents or other deliverables to Tasks. The API is asynchronous. A send answers `202` with the ID of the reply, and you poll until the turn settles.

The examples share one helper, which sends the key and the organization header on every request. Save it as `tale-api.sh`:

```bash
# tale-api.sh: source it from your shell or from a script
: "${TALE_URL:?Set TALE_URL to your Tale origin, without /api/v1}"
: "${TALE_API_KEY:?Set TALE_API_KEY}"
: "${TALE_ORG_SLUG:?Set TALE_ORG_SLUG}"
tale_api() {
  curl --fail-with-body -sS \
    -H "Authorization: Bearer $TALE_API_KEY" \
    -H "X-Organization-Slug: $TALE_ORG_SLUG" \
    -H 'Content-Type: application/json' "$@"
}
```

Load it in your shell, check the key, and list the models you can call. The examples need curl and `jq`.

```bash
source ./tale-api.sh

# Who the key acts as, and in which organization
tale_api "$TALE_URL/api/v1/me" | jq '{email: .user.email, organization: .organization.slug, role: .organization.role}'

# The models you can name: id and providerSlug
tale_api "$TALE_URL/api/v1/models" | jq -r '.models[] | "\(.id)\t\(.providerSlug)"'
```

Export `MODEL_ID` and `PROVIDER` from one line of that list. The conversation is a script, `ask-tale.sh`, saved next to the helper and run with `bash ask-tale.sh`. It creates a personal thread, sends one question, waits for the turn to settle, and prints the reply's text. `set -euo pipefail` stops it at the first failed request, so it never goes on with an empty ID.

```bash
#!/usr/bin/env bash
set -euo pipefail
source "$(dirname "$0")/tale-api.sh"
: "${MODEL_ID:?Set MODEL_ID to an id from /models}"
: "${PROVIDER:?Set PROVIDER to the providerSlug listed with it}"

THREAD_ID=$(tale_api -X POST "$TALE_URL/api/v1/threads" -d '{"title":"Script help"}' | jq -er '.id')

BODY=$(jq -n --arg model "$MODEL_ID" --arg provider "$PROVIDER" \
  '{content: "What does our runbook say about rotating database passwords?", model: $model, providerSlug: $provider}')
MESSAGE_ID=$(tale_api -X POST "$TALE_URL/api/v1/threads/$THREAD_ID/messages" -d "$BODY" | jq -er '.messageId')

# Poll every three seconds, for up to ten minutes, until the turn settles
STATUS=queued
for _ in $(seq 200); do
  STATUS=$(tale_api "$TALE_URL/api/v1/threads/$THREAD_ID/generation" | jq -r '.status')
  [ "$STATUS" = idle ] && break
  sleep 3
done
if [ "$STATUS" != idle ]; then
  echo "No reply within ten minutes; stopping the turn." >&2
  tale_api -X DELETE "$TALE_URL/api/v1/threads/$THREAD_ID/generation" > /dev/null
  exit 1
fi

# Read the reply the send named, then check how it ended
REPLY=$(tale_api "$TALE_URL/api/v1/threads/$THREAD_ID/messages/$MESSAGE_ID")
if [ "$(jq -r '.status' <<< "$REPLY")" != complete ]; then
  jq -r '"Turn \(.status): \(.errorCode // "") \(.error // "")"' <<< "$REPLY" >&2
  exit 1
fi
if [ "$(jq -r '.finishReason // ""' <<< "$REPLY")" = length ]; then
  echo "The reply reached its output limit and may be cut off." >&2
fi
jq -r '[.parts[] | select(.type == "text") | .text] | join("")' <<< "$REPLY"
```

While the send waits for a worker, `GET .../messages/$MESSAGE_ID` can still answer `404 MESSAGE_NOT_FOUND`, so the script reads the reply only once the thread is idle. A turn that has not settled after ten minutes is stopped with `DELETE .../generation`. Send follow-up questions to the same `THREAD_ID` to keep the conversation's context. The send is text only, and it is refused with `409 CHAT_TURN_IN_PROGRESS` while the thread's previous turn is still running.

When a script needs the matching passages rather than an answer, `POST /api/v1/knowledge/search` returns them without the assistant; see [Search a project's files](https://docs.tale.dev/develop/api-reference#search-a-projects-files). [Call Tale from a script](https://docs.tale.dev/tutorials/developer/call-tale-from-a-script) builds the same conversation in Python with error handling, and [Send a message, then poll the turn](https://docs.tale.dev/develop/api-reference#send-a-message-then-poll-the-turn) covers retries, token limits, and failures.

## Bring Tale's tools into opencode or Claude Code {#connect-opencode-or-claude-code}

Tale's [MCP endpoint](https://docs.tale.dev/develop/mcp-endpoint), `/api/v1/mcp`, gives an editor agent Tale's tools. The most useful for script work is `get_knowledge`, which retrieves passages from your organization's documents and crawled web pages. The endpoint also exposes the automation tools: validate, test, save, deploy, and run automations, and read their runs. Saving, deploying, setting or deleting a trigger, cancelling a run, and live runs require the Developer capability. The endpoint has no chat tool and no skills tool; to copy your organization's skills into a local skills folder, read them with `GET /api/v1/skills` as described in [Save and synchronize skill bundles](https://docs.tale.dev/develop/api-reference#save-and-synchronize-skill-bundles).

The language model on this path is the one configured in your editor. Tale authenticates the tool calls and applies your permissions to them, but the prompts, your code, and every passage a Tale tool returns travel to that editor's model provider. When that provider is another service, Tale's budgets, usage records, and model-access rules do not apply to its model calls; check that your organization allows its knowledge to reach that provider before you connect. When the editor uses [the model endpoints](https://docs.tale.dev/develop/use-tale-from-your-editor#model-endpoints) as its provider, the passages go only to models your organization approved, and each model call is governed as described there.

The endpoint authenticates with the API key in a header and has no OAuth sign-in. Turn off a client's OAuth detection where it offers the switch.

### opencode

Add a remote server to your global opencode configuration, `~/.config/opencode/opencode.json`, or to an `opencode.json` in the project. `{env:TALE_API_KEY}` makes opencode read the key from your environment, so the file never holds the secret. Replace the host and the slug with your own.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tale": {
      "type": "remote",
      "url": "https://your-host.example.com/api/v1/mcp",
      "oauth": false,
      "timeout": 60000,
      "headers": {
        "Authorization": "Bearer {env:TALE_API_KEY}",
        "X-Organization-Slug": "your-org-slug"
      }
    }
  }
}
```

`timeout` raises opencode's five-second default for MCP requests, which a knowledge search under load or a `run_deployed` call that waits up to 30 seconds can exceed. Start opencode from a shell where `TALE_API_KEY` is set. `opencode mcp list` shows whether the server is configured; opencode prefixes the tools with the server name, as in `tale_get_knowledge`.

### Claude Code

Register the endpoint as an HTTP server. The command below stores the expanded key in your private Claude Code configuration for the current project:

```bash
claude mcp add --transport http tale "$TALE_URL/api/v1/mcp" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG"
```

To share the server with a team through a committed `.mcp.json`, reference the key as an environment variable so each person supplies their own:

```json
{
  "mcpServers": {
    "tale": {
      "type": "http",
      "url": "https://your-host.example.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${TALE_API_KEY}",
        "X-Organization-Slug": "your-org-slug"
      }
    }
  }
}
```

`claude mcp list` reports whether Claude Code can reach the server.

## Let a project agent edit scripts

To have the edit made inside Tale, in a sandbox and with a person's review, hand the script to a [project agent](https://docs.tale.dev/platform/projects/project-agents). Tale runs a coding harness such as OpenCode in a sandbox, on the model the agent is configured with. The run counts against the budgets of the member who started it and is recorded under that person; a run you start over REST is booked to you, not to the API key. The edited files come back as the task's deliverables, and the task waits in review for a person. [Choose an agent runtime](https://docs.tale.dev/platform/agents/harnesses) compares the harnesses; OpenCode runs only through Tale's model gateway, so it never receives a provider key.

Creating the agent needs edit access to the project, which starts at the Editor role; any member who can open the project can then create the task and start the agent on it. The organization needs a model the harness can use and available sandbox capacity. In the app, open the project's **Agents** tab, select **New agent**, choose OpenCode as the agent type and a model, then create a task with the script attached, assign it to the agent, and start the agent.

The same loop works from a terminal over REST, reusing `tale-api.sh` from the chat example. First check that this deployment runs OpenCode for project agents:

```bash
tale_api "$TALE_URL/api/v1/models" | jq -r '.harnesses[] | "\(.harness)\t\(.label)"'
```

Then save the script below as `hand-to-agent.sh` next to the helper and run it with `bash hand-to-agent.sh`. It reuses the project's agent named Script editor or creates it on the first run, because agent names are unique in a project regardless of case. It then files the script as a task and puts the agent to work with a comment that mentions it.

```bash
#!/usr/bin/env bash
set -euo pipefail
source "$(dirname "$0")/tale-api.sh"
: "${PROJECT_ID:?Set PROJECT_ID to a project you can edit}"
: "${MODEL_ID:?Set MODEL_ID to a model the harness can use}"
: "${PROVIDER:?Set PROVIDER to the providerSlug listed with it}"
AGENT_NAME="Script editor"

AGENT_ID=$(tale_api "$TALE_URL/api/v1/projects/$PROJECT_ID/agents" \
  | jq -r --arg name "$AGENT_NAME" 'first(.agents[] | select((.name | ascii_downcase) == ($name | ascii_downcase)) | .id) // ""')
if [ -z "$AGENT_ID" ]; then
  AGENT_ID=$(tale_api -X POST "$TALE_URL/api/v1/projects/$PROJECT_ID/agents" \
    -d "$(jq -n --arg name "$AGENT_NAME" --arg model "$MODEL_ID" --arg provider "$PROVIDER" '{name: $name, harness: "opencode", model: $model, modelProvider: $provider, skills: [], connectors: [], instructions: "Edit the script from the task description. Return the changed script as a file and list every change in your report."}')" \
    | jq -er '.agent.id')
fi

TASK_ID=$(tale_api -X POST "$TALE_URL/api/v1/projects/$PROJECT_ID/tasks" \
  -d "$(jq -n --rawfile script backup.ps1 '{externalSystem: "terminal", externalId: "backup-ps1-hardening", title: "Harden backup.ps1", description: ("Add error handling and a dry-run switch to this PowerShell script:\n\n" + $script)}')" \
  | jq -er '.task.id')

tale_api -X POST "$TALE_URL/api/v1/projects/$PROJECT_ID/tasks/$TASK_ID/comments" \
  -d "$(jq -n --arg agent "$AGENT_ID" '{body: ("@" + $agent + " please take this task.")}')" > /dev/null
echo "TASK_ID=$TASK_ID"
```

`externalSystem` and `externalId` make the task idempotent: sending the same pair again returns the existing task. A description holds up to 20,000 characters; for a longer script, upload it to the project as described in [Upload a file in two steps](https://docs.tale.dev/develop/api-reference#upload-a-file-in-two-steps). An agent answers to its ID and to its name in lower case with spaces replaced by dots or removed, so `@script.editor` also works.

The mention assigns the task to the agent and starts a run, and the task moves to `in_progress`. A mention that cannot start a run is saved as an ordinary comment without an error, for example when the task is not yours to change, task automation is turned off, or another run already holds the task. Set `TASK_ID` to the value the script printed, check the task, and read the agent's report once the task reaches `in_review`:

```bash
tale_api "$TALE_URL/api/v1/projects/$PROJECT_ID/tasks/$TASK_ID" | jq -r '.task.status'
tale_api "$TALE_URL/api/v1/projects/$PROJECT_ID/tasks/$TASK_ID/comments?limit=20" \
  | jq -r '.comments[] | select(.authorType == "agent") | .body'
```

Review the edited files under the task's deliverables in the app before you approve the task. To send the agent back with changes, post another comment that mentions it.

## What changed since Tale 0.3 {#where-the-openai-compatible-endpoint-went}

From 0.2.10 through 0.3, Tale served an OpenAI-compatible layer: `POST /api/v1/chat/completions`, `POST /api/v1/images/generations`, and an OpenAI-shaped `GET /api/v1/models`, whose `model` field could name an agent. Tale 0.4 rebuilt the platform without it. The [model endpoints](https://docs.tale.dev/develop/use-tale-from-your-editor#model-endpoints) take its place for model calls, with differences a client written for 0.3 has to follow:

- The base URL is `/api/v1/openai`, or `/api/v1/anthropic` for an Anthropic client, not `/api/v1`. An OpenAI SDK pointed at `/api/v1` still receives `404 NOT_FOUND` for chat completions, and `GET /api/v1/models` is Tale's own listing of models and agent harnesses, not the OpenAI shape.
- `model` names a model as `<providerSlug>/<modelId>`, never an agent. For the workspace assistant, use the REST chat API; to put an agent to work, use a project agent.
- Image generation is not served.
- The endpoints are off until an Admin turns them on, and every call passes model access, the input guardrails, and the budgets.

[Upgrade and recover a deployment](https://docs.tale.dev/self-hosted/operate/upgrades#03-04-the-openai-compatible-api-was-removed) lists the removal for operators moving from 0.3.

# WebDAV API
Source: https://docs.tale.dev/develop/webdav-api

Use WebDAV when a file client needs folders, downloads, uploads, and edit locks over HTTP. This endpoint exposes the organization's Document Hub; project files are outside its tree. For Finder, File Explorer, or another existing client, start with [Connect with WebDAV](https://docs.tale.dev/platform/connectors/webdav).

This reference is for client implementers. First verify one authenticated listing, then a small upload. A successful `207` listing proves access; a successful upload followed by the same downloaded bytes proves the complete storage path.

## URL scheme

| Path | Access | Contents |
| --- | --- | --- |
| `/dav/<orgSlug>/documents/<path>` | Read and write | Active Document Hub documents and folders |
| `/dav/<orgSlug>/.trash/<path>` | Read only | Trashed documents |
| `/dav/<orgSlug>/` | Read only | The two collections above |

Encode each path segment separately. The parser normalizes Unicode to NFC and trims leading and trailing whitespace. It rejects empty names, `.` and `..`, `/`, `\`, control characters, and names longer than 255 UTF-16 code units. This is a character-length check, not a 255-byte limit. Organization slugs match `[a-zA-Z0-9_-]{1,64}`. A `.` or `..` segment in the request line, raw or percent-encoded (`%2e%2e`, `.%2e`), is refused with `404` before routing and is never resolved against the parent folder. A raw backslash counts as a segment separator for that check (`a\..\x` reads like `a/../x`); an encoded one (`%5C`) is an ordinary, refused, name character.

Use a trailing slash for folders and none for files. Listings return canonical URLs. Follow the returned `href` when addressing an existing item; do not reconstruct it from its display name, particularly when sibling documents share a title.

## Authentication

Generate an app password in **Settings > API > WebDAV** using an account with access to developer settings. The complete password appears once. Give each client its own label so you can revoke its access independently.

| Credential field | Value |
| --- | --- |
| HTTP scheme | Basic |
| Username | Your account email; the server accepts any non-empty username |
| Password | The generated WebDAV app password |
| Organization | The slug in the URL, checked against current membership |

The app password identifies the user. Neither an account password nor a REST API key is accepted. A valid password does not bypass organization membership: losing membership causes `403`. `OPTIONS` alone is available without authentication.

### Verify a listing

Set your deployment URL and email below. Each `curl --user` command prompts for the app password, keeping it out of the command itself and shell history.

```bash
export TALE_DAV_URL="https://your-host.example.com/dav/acme/documents"
export TALE_DAV_USER="you@example.com"

curl --user "$TALE_DAV_USER" --request PROPFIND \
  --header 'Depth: 1' "$TALE_DAV_URL/"
```

Expect `207 Multi-Status` with XML containing the collection and its immediate children. An empty folder still has a response for the collection itself. Do not parse the XML as JSON or treat every status inside a `207` as success.

### Verify a write and download

Choose a new folder name to avoid overwriting existing work. These commands create one folder, upload a small text file, and download it:

```bash
curl --user "$TALE_DAV_USER" --request MKCOL "$TALE_DAV_URL/Client%20test/"
printf 'Hello from WebDAV.\n' > webdav-test.txt
curl --user "$TALE_DAV_USER" --upload-file webdav-test.txt \
  --header 'Content-Type: text/plain' "$TALE_DAV_URL/Client%20test/webdav-test.txt"
curl --user "$TALE_DAV_USER" "$TALE_DAV_URL/Client%20test/webdav-test.txt"
```

Expect `201` for the new folder, `201` for the new file, and the text `Hello from WebDAV.` on download. Uploading to an existing file returns `204` and replaces its content. The file also appears in the Document Hub without a separate synchronization operation.

## Methods

All methods except `OPTIONS` require the app password.

| Method | Purpose | Successful response |
| --- | --- | --- |
| `OPTIONS` | Discover capabilities and the target's allowed methods | `200`, `DAV: 1, 2`, `Allow` |
| `PROPFIND` | Read properties; use `Depth: 0` for the target or `Depth: 1` for its immediate children | `207` XML |
| `PROPPATCH` | Submit property changes; see persistence limitations below | `207`, with a status per property |
| `GET`, `HEAD` | Download a file or read its headers | `200`; conditional and range requests can change the status |
| `PUT` | Create or replace a file | `201` new, `204` replacement |
| `DELETE` | Move documents to trash; recursively trash folder contents and remove folder rows | `204` |
| `MKCOL` | Create a folder whose parent already exists | `201` |
| `MOVE` | Rename or relocate a document or folder | `201` new destination, `204` replacement |
| `COPY` | Copy a document or folder tree on the server; file copies share stored bytes | `201` new destination, `204` replacement |
| `LOCK` | Acquire or refresh a write lock | `200`, with a lock token |
| `UNLOCK` | Release a lock owned by the requesting user | `204` |

`GET` on a folder is `405`; use `PROPFIND`. An omitted `Depth` defaults to `1`; `Depth: infinity` is `403`. `MKCOL` takes an empty body. `PUT` requires `Content-Length`: use a known-size file rather than chunked transfer.

`MOVE` and `COPY` use `Destination` and honor `Overwrite: T/F` and `If`. Keep the destination on the same host and in the same organization. A missing destination parent is `409`; `Overwrite: F` onto an existing item is `412`. Moving a document is atomic; moving a folder changes its parent. Destructive operations also respect legal holds and document record restrictions.

The `Allow` header describes the target: the documents tree advertises the methods above, a trash file advertises `OPTIONS, GET, HEAD, PROPFIND`, and the trash collection and organization root advertise `OPTIONS, PROPFIND`. Capability probes on a path that cannot yet be parsed still advertise the full method set. Windows discovery also receives `MS-Author-Via: DAV` and `Microsoft-Server-WebDAV-Extensions: 1`.

## Properties

| DAV property | Meaning |
| --- | --- |
| `resourcetype` | `<collection/>` for folders; empty for files |
| `displayname` | Folder name or document title |
| `getlastmodified` | RFC 1123 timestamp; source modification time, falling back to creation time |
| `creationdate` | Creation time in ISO 8601 |
| `getcontenttype` | File MIME type |
| `getcontentlength` | File size in bytes |
| `getetag` | The same validator returned by `GET` and `HEAD` |
| `supportedlock` | Exclusive write-lock support |
| `lockdiscovery` | Active lock information when available |

File-only properties do not apply to collections. An ETag is a quoted content hash when one exists, otherwise a weak validator based on size and modification time, such as `W/"42-1789373842855"`. Preserve the quotes and `W/` marker; do not substitute the document ID or infer byte equality from a weak validator. `GET` supports conditional requests and byte ranges.

<Warning>

Custom properties are not persisted. A `PROPPATCH` containing only dead properties reports per-property `200` for client compatibility, but a later read does not return those values. A protected live property gets `403`; dead properties in that same request get `424 Failed Dependency`. Do not use these properties to store business metadata.

</Warning>

## Lock semantics

Use an exclusive write lock and retain its `opaquelocktoken:<uuid>` token. The advertised lock support is exclusive; although the parser accepts a shared scope, the backing store permits only one live lock at a resource. Do not build a shared-editing workflow around shared locks.

| Client action | Required behavior |
| --- | --- |
| Acquire | Send `LOCK` with an XML write-lock body and `Timeout: Second-N` |
| Write while locked | Include `If: (<opaquelocktoken:...>)` |
| Refresh | Send an empty `LOCK` body with the same `If` token |
| Release | Send `UNLOCK` with `Lock-Token: <opaquelocktoken:...>` as the owning user |

Timeouts are clamped to 1–3600 seconds. Refresh before expiry if an edit takes longer. A missing token on a protected write gives `423`; a mismatched token or an unknown refresh token gives `412`. Locks can cover descendant paths, so a parent lock can block a write below it.

Locks are stored in Postgres and expire lazily. Expired rows do not protect a resource even before cleanup removes them. Revoking an app password deletes its locks immediately. This is also a recovery path for a client that disappeared while holding a lock; it disconnects every mount using that password.

## Status codes

| Status | Meaning and next action |
| --- | --- |
| `200`, `201`, `204` | Successful read, creation, or update; see the method table |
| `207` | Inspect each resource/property result in the XML envelope |
| `400` | Correct a malformed `Destination`, `If`, `Lock-Token`, or `Timeout` header |
| `401` | Supply a valid, unrevoked app password using Basic authentication |
| `403` | Check membership, read-only namespace, legal hold/record rules, depth, ownership, and destination scope |
| `404` | Check the returned `href`, organization slug, and resource existence |
| `405` | Check the target's `Allow`; folders cannot be downloaded or overwritten as files |
| `409` | Create the destination parent first |
| `411` | Send `Content-Length` for `PUT` |
| `412` | Re-read the resource or lock state; check `If`, `If-Match`, `If-None-Match`, and `Overwrite` |
| `413` | Reduce the file or XML body size, or review the operator's upload limit |
| `415` | Send an empty `MKCOL` body; extended MKCOL is unsupported |
| `423` | Obtain the matching lock token or wait for/release the lock |
| `502` | Check cross-host destinations and object-store connectivity |
| `503` | Release unused locks for this password and honor `Retry-After` |
| `507` | Split a folder-tree operation into smaller operations |

Do not retry every refusal automatically. A missing parent or an invalid credential needs a correction; a lock conflict needs coordination with the other editor.

## Compliance

The endpoint advertises `DAV: 1, 2`. Treat the methods and limitations on this page as the implementation contract; the advertisement is not a promise that every optional WebDAV feature works. In particular, dead properties do not persist and shared editing locks are not available. Calendar, contact, search, and ACL extensions are not provided.

For wire syntax, consult [RFC 4918](https://www.rfc-editor.org/rfc/rfc4918). DAV compliance class 3 is a revision-compliance category, not a name for calendar or contact extensions.

## Limits

| Boundary | Limit or behavior |
| --- | --- |
| Recursive listing | `Depth: infinity` refused; walk one level at a time |
| Lock duration | 1–3600 seconds |
| Active locks | 200 per app password |
| Upload size | 5 GB by default; `WEBDAV_MAX_PUT_BYTES` sets the byte cap |
| XML bodies | 64 KiB for `PROPFIND`, `PROPPATCH`, `MKCOL`, and `LOCK` |
| Password creation | Up to 50 active app passwords per user in an organization |
| Usage timestamp | Updated at most once per minute per password |

Uploads stream to the object store with backpressure. The server needs the length before it can create the upload request; chunked uploads receive `411`. Folder operations have bounded traversal budgets and can return `507`; splitting a large tree is preferable to repeatedly submitting the same oversized operation.

## Network requirements

The backend serves `/dav/*`; the platform proxy exposes it on the same public host as Tale. In local development, Vite forwards `/dav` from port 3000 to the backend, so clients can use the normal local application origin. There is no separate WebDAV service to deploy.

A listing can succeed while a download or upload fails: listings require the database, whereas file bytes also require a working object store. Test both paths after changing proxy or storage configuration. Keep the proxy's body cap consistent with `WEBDAV_MAX_PUT_BYTES`.

## Security

Use HTTPS for remote mounts. Basic authentication sends the app password on every request; Base64 is encoding, not encryption. Plain HTTP is suitable only for a controlled localhost test. Store credentials in the client's password prompt or operating-system keychain, never in a URL such as `https://user:password@host/`.

The backend stores HMAC-SHA256 hashes and a four-character lookup prefix, then verifies the hash in constant time. `WEBDAV_APP_PASSWORD_HMAC_KEY` is derived from `INSTANCE_SECRET` by the platform startup configuration unless explicitly set. Keep these deployment secrets stable and backed up; changing the HMAC key invalidates existing passwords.

The password list exposes its label, prefix, creation time, and last-use time. Use those to identify and revoke a lost device's credential. Last use is throttled metadata, not a complete per-request audit trail.

## Where this fits

Use [REST](https://docs.tale.dev/develop/api-reference) for project-scoped imports, explicit IDs, and search. Use WebDAV for Document Hub file clients that expect paths and locks. Both work with Tale documents, but WebDAV does not expose the project's file tree or every REST operation.

# Webhooks
Source: https://docs.tale.dev/develop/webhooks

A webhook lets an external system start a deployed automation by posting to a secret URL. It suits services that can send an order event, form submission, or other notification to a fixed destination. A `202` response confirms acceptance and gives you a run ID; it does not confirm the automation has finished.

For a guided first setup, follow [Trigger an automation via webhook](https://docs.tale.dev/tutorials/developer/trigger-automation-via-webhook). This reference covers the delivery contract, scope, token lifecycle, and retry behavior.

## A worked trigger

### Prepare a deployed automation

Save and deploy an automation whose tests pass. Bind a webhook in the editor, or send `PUT /api/v1/automations/{name}/triggers` with `{"kind":"webhook"}` using an authorized API key. Copy the newly issued token immediately; it is returned once.

Choose the URL from the automation's scope:

| Work to start | URL | Requirement |
| --- | --- | --- |
| Project run | `/api/projects/{id}/automations/webhook/{token}` | Active project in the token's organization, with this automation installed |
| Organization run | `/api/automations/webhook/{token}` | Automation with no project bindings |

A project-bound automation refuses the global URL with `409 AUTOMATION_PROJECT_SCOPE_REQUIRED`. Do not add a `projectId` query parameter: both URLs reject it with `400 INVALID_QUERY`. A field inside the vendor body is input data, not a way to choose the project.

### Send one delivery

Store the complete secret URL in `TALE_WEBHOOK_URL` using your sender's secret configuration. The following request uses a stable ID for one logical event:

```bash
curl --fail-with-body --request POST "$TALE_WEBHOOK_URL" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-12345-paid' \
  --data '{"orderId":"12345","status":"paid"}'
```

The accepted response has the shape `{"runId":"..."}` with HTTP `202`. Save that ID alongside the sender's delivery ID. Tale passes the body to the automation inside this wrapper:

```json
{
  "trigger": "webhook",
  "payload": { "orderId": "12345", "status": "paid" }
}
```

Read the order as `input.payload.orderId`. If the automation declares an `inputs` schema, it must describe this wrapper. A body that is not JSON becomes text in `payload`. The body limit is 256 KiB (262,144 bytes), measured as bytes arrive; larger requests receive `413`.

### Follow the result

| Delivery scope | Authenticated polling route |
| --- | --- |
| Project | `GET /api/v1/projects/{id}/runs/{runId}` |
| Organization | `GET /api/v1/runs/{runId}` |

Poll with an API key whose holder can read that scope, or open the run in Tale. The webhook token starts deliveries; it is not a credential for reading REST results. Wait for a terminal run status before reporting that the work succeeded.

### Interpret delivery responses

| Status | Code/result | Recovery |
| --- | --- | --- |
| `202` | `runId` | Accepted; follow the run |
| `202` | `runId`, `duplicate: true` | Already accepted; follow the original run, no new run was created |
| `400` | `INVALID_QUERY` | Remove `projectId` from the query string |
| `400` | `AUTOMATION_INPUT_INVALID` | Correct the wrapper/schema mismatch using `data.issues` |
| `403` | `AUTOMATION_PROJECT_FORBIDDEN` | Check that the project is active, in the right organization, and has the automation installed |
| `404` | Unknown, disabled, or mistyped token; also any non-POST method | Check the saved URL and trigger state |
| `409` | `AUTOMATION_NOT_DEPLOYED` | Deploy a version whose tests pass |
| `409` | `AUTOMATION_PROJECT_SCOPE_REQUIRED` | Use the installed project's URL |
| `409` | `AUTOMATION_DELIVERY_SCOPE_MISMATCH` | Check the scope used for the original delivery ID |
| `413` | Body too large | Reduce the payload below 256 KiB |
| `429` | Sender or trigger budget exhausted | Wait at least `Retry-After` |

A refused input creates no run. Project refusals deliberately do not distinguish a missing project, archived project, or missing installation, and do not reveal the automation's name. `GET`, `HEAD`, and `OPTIONS` all receive the same `404` as an invalid token, without an `Allow` header.

## The token is the credential

The secret in the URL authorizes delivery. This endpoint does not verify a vendor HMAC signature or use an `Authorization` header. Keep the URL out of public issue reports, shared logs, and screenshots. Tale stores its hash and uses a constant-time comparison; plaintext is disclosed only when minted.

| Change | Token effect |
| --- | --- |
| `PUT` webhook with `rotateToken: true` | New token returned once; old URL stops working immediately |
| Delete/unbind the trigger | Token revoked; saved versions and run history remain |
| Replace webhook with schedule/event | Token revoked; response includes `revoked: "webhook"` |
| Bind webhook again after replacement | New token; the original does not return |
| Set `enabled: false` | URL suspended with `404`, but token retained |
| Re-enable, including a later `PUT` that omits `enabled` | The same suspended URL becomes active again |

<Warning>

After a leak, rotate or unbind the trigger. Disabling it is temporary suspension, not permanent revocation. Coordinate a token rotation with the sender and replace its stored URL before resuming deliveries.

</Warning>

Read `revoked` in scripted trigger changes so replacing a trigger type does not silently disconnect a partner that still uses the old URL.

## Idempotency and retries

Deduplication applies to the trigger and the project in its URL. The same delivery ID can start one run in each installed project. Current project activity and installation are checked before Tale returns a cached duplicate.

| Identity | Duplicate window | What must stay the same |
| --- | --- | --- |
| Delivery-ID header | 24 hours | ID value and scope; the body may differ and still counts as the same delivery |
| No delivery-ID header | 2 minutes | Byte-identical body and URL |

For header-based identity, the first present header in this priority order wins:

```text
Idempotency-Key
X-Idempotency-Key
webhook-id
X-GitHub-Delivery
X-Gitlab-Event-UUID
X-Shopify-Webhook-Id
Linear-Delivery
X-Atlassian-Webhook-Identifier
X-Request-UUID
I-Twilio-Idempotency-Token
X-Webhook-Id
```

Header names are alternatives, not separate namespaces. Forwarding a vendor's ID as `Idempotency-Key` preserves its identity. With no ID, JSON formatting changes the body bytes and may produce a new delivery. Prefer an explicit, stable event ID whenever your sender supports one.

Repeating the example request within 24 hours returns the original `runId` with `duplicate: true`. It does not rerun a failed automation. Decide separately how to recover a failed run instead of changing delivery IDs blindly.

Retry network failures and temporary `5xx` responses with bounded exponential backoff. For `429`, honor `Retry-After`. Keep the ID unchanged if a response may have been lost. Correct other `4xx` causes before retrying. Deduplication prevents extra runs within its window; it does not guarantee exactly-once effects in an external service.

## Budgets

| Budget | Refill | Burst | Charged when |
| --- | --- | --- | --- |
| Sender IP, as reported by trusted proxies | 120/minute | 240 | Before token verification |
| Verified trigger | 20/minute | 40 | For delivery admission |

Either budget can cause `429` with `Retry-After` in whole seconds and the normal error envelope. A token authenticates access to the trigger, but there is no separate sender-account identity to budget. Use the [rate-limit guidance](https://docs.tale.dev/develop/rate-limits) and keep the delivery ID stable while backing off.

## Choose webhook or API key

Use a webhook when the sender supports a fixed event URL. Use an API key when your client must also discover automations, choose projects, or read results. [Triggers](https://docs.tale.dev/platform/automations/triggers) explains setup in the app; the [API reference](https://docs.tale.dev/develop/api-reference) describes authenticated starts and polling.

# Set up a workspace for your team
Source: https://docs.tale.dev/get-started/admins

A usable workspace needs an organization, a working model provider, and accounts with the right access. Follow this sequence to get the team started, then configure the controls that match the work you plan to do.

## Before you begin

Use an Owner or Admin account on the correct instance. The first-run setup creates the initial account and organization. If you already see your organization in the dashboard, continue with its settings rather than creating another one.

Have the provider credential ready in your password manager. The provider must support the model and tasks you intend to use. [AI providers](https://docs.tale.dev/platform/admin/providers) explains credentials, catalogs, and agent runtimes.

## Connect a provider and test chat

<Steps>

<Step title="Add the credential">

Open **Settings > AI providers**, select **Add credential**, and choose the provider. Complete the fields for its supported authentication method and save. Use a descriptive credential name so another administrator can identify its purpose.

<Frame caption="Connected credentials make the provider’s models available to the workspace.">

![The AI providers settings page lists connected provider credentials.](https://docs.tale.dev/images/get-started/settings-providers.webp)

</Frame>

</Step>

<Step title="Check the model in a new chat">

Open **Home**, choose **New chat**, and select an available model. Send a self-contained prompt such as “Write a three-item meeting checklist.” Wait for the answer to finish. A saved credential alone does not prove that its account has access to the selected model.

If the model list is empty or the provider rejects the request, use the recovery steps in [AI providers](https://docs.tale.dev/platform/admin/providers).

</Step>

</Steps>

## Add people with the access they need

Open **Settings > Members** and select **Add member**. For a new account, the form sets an initial password; an existing account keeps its credentials. This flow does not send an invitation email. Follow [members and roles](https://docs.tale.dev/platform/admin/members-and-roles) for the fields and secure handover of the initial credentials.

<Frame caption="Review each member’s role before handing over access.">

![The Members page shows the people in the organization and the role assigned to each person.](https://docs.tale.dev/images/get-started/settings-organization-members.webp)

</Frame>

Choose the role for the job: Members use the workspace, Editors maintain shared content, Developers work on integrations and automations, and Admins manage the organization. Use the detailed permission table when the task crosses those boundaries. Teams and project sharing further determine which project work a person can access.

## Verify the team’s first workflow

Ask a teammate to sign in with their own account, send a message, and open the project they need. Check any shared source with that account too. Testing only as Owner can hide missing permissions or access that is broader than intended.

<Tip>

Start with one representative project and a small set of source documents. Confirm that people can find the work and that the intended accounts can access its files before importing a large library.

</Tip>

## Set the operating rules

Review [policies and limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits), [audit logs](https://docs.tale.dev/platform/admin/governance/audit-logs), and [SSO](https://docs.tale.dev/platform/admin/enterprise-sso) as needed. Assign responsibility for provider credentials, access reviews, and responding to failed jobs. Self-hosted operators also need a tested [backup and restore process](https://docs.tale.dev/self-hosted/operate/backups-and-restore).

# Make your first API request
Source: https://docs.tale.dev/get-started/developers

Start an integration by proving three things: the key authenticates, it targets the right organization and that organization has the resources you need. This guide gets you through those checks with curl. You need a running Tale instance and permission to create API keys, normally the Developer, Admin or Owner role.

## Create a key for the integration

Open **Settings > API > REST** and select **Create API key**. Name the key for its purpose, choose an expiration and select **Create key**. Copy the value immediately; Tale displays the secret once.

<Frame caption="Use one recognizable key per integration so you can replace or revoke it independently.">

![The Create API key dialog asks for a descriptive name and an expiry before a key is generated.](https://docs.tale.dev/images/get-started/settings-api-keys.webp)

</Frame>

Load the secret into `TALE_API_KEY` from a secret manager or private shell environment. Set `TALE_BASE_URL` to your instance, for example `https://your-host.example.com`. Do not include a trailing `/api/v1`; the commands below add that path.

## Identify the account and organization

Call `/me` without an organization header. With one membership, it returns the key’s identity and organization. With several memberships, it returns `400 ORG_SLUG_REQUIRED` and lists your choices in `data.organizations`:

```bash
curl --fail-with-body --silent --show-error "$TALE_BASE_URL/api/v1/me" \
  -H "Authorization: Bearer $TALE_API_KEY"
```

Set `TALE_ORG_SLUG` to your chosen slug, then repeat `/me` with that scope. The dashboard URL contains an organization ID; do not use it as the slug. A `400` in the first request makes curl exit with code 22 while still printing the JSON body.

```bash
curl --fail-with-body --silent --show-error "$TALE_BASE_URL/api/v1/me" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG"
```

Check the successful response’s account, organization, capabilities and `key.expiresAt` before proceeding.

The key acts with its holder’s current membership and permissions. Creating several keys for one account does not create several independent roles or rate-limit budgets. Plan key replacement before expiration; `/api/v1` does not manage API keys for you.

## Find an available model

Send the organization explicitly when listing models:

```bash
curl --fail-with-body --silent --show-error "$TALE_BASE_URL/api/v1/models" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG"
```

<Check>

A `200` response with a `models` array confirms this authenticated, organization-scoped request. The array may be empty; that confirms access to the endpoint, not readiness to generate a reply.

</Check>

Use a model’s `id` in chat requests and its `providerSlug` when that ID is available from several providers. A model can be listed yet unavailable to the provider account because of credit or plan restrictions. Ask an admin to check provider credentials and model access if the list is empty.

## Resolve the first error

| Response | What to do |
| --- | --- |
| `401` | Check the bearer key, expiration and revocation state. |
| `400` with `ORG_SLUG_REQUIRED` | Choose a slug from `data.organizations` in this error and send `X-Organization-Slug`. |
| `404` with `ORG_SLUG_INVALID` | The header names no organization at all — a typo, or the dashboard URL's organization ID pasted as the slug. Send the slug from `data.organizations`. |
| `403` with `ORG_FORBIDDEN` | The organization exists, but the key holder is not a member of it. Pick a slug from `data.organizations`. |
| `403` | Check the permission needed for the operation. |
| `429` | Wait as directed by `Retry-After`; read [Rate limits](https://docs.tale.dev/develop/rate-limits). |

If curl reports a TLS or network error before receiving JSON, check the host and certificate. Avoid disabling certificate verification in production scripts.

## Choose the next task

| You want to… | Continue with |
| --- | --- |
| Print a completed assistant reply | [Call Tale from a script](https://docs.tale.dev/tutorials/developer/call-tale-from-a-script). |
| Start an automation from another system | [Trigger an automation via webhook](https://docs.tale.dev/tutorials/developer/trigger-automation-via-webhook). |
| Connect an MCP client | [MCP endpoint](https://docs.tale.dev/develop/mcp-endpoint). |
| Use Tale from opencode, Claude Code or a shell script | [Use Tale from your editor or a script](https://docs.tale.dev/develop/use-tale-from-your-editor). |
| Work with project files, tasks or runs | [API reference](https://docs.tale.dev/develop/api-reference). |

Use project routes under `/api/v1/projects/{id}/...` for project-scoped work. The project ID belongs in that path; the organization slug belongs in the header. Keep both explicit in your integration configuration.

# Create and test a project agent
Source: https://docs.tale.dev/get-started/editors

Create a project agent for a repeatable job, such as reviewing documents or preparing an operational report. You choose its instructions, runtime, model, and tools, then give it a task with a result you can inspect. This guide uses a launch-brief review to show that path. Until a project has an agent of its own, its tasks can go to the organization's [standard agent](https://docs.tale.dev/platform/projects/project-agents#standard-agent).

## Before you begin

You need edit access to a project, a suitable model provider, and an available agent runtime with its required infrastructure. A successful ordinary chat verifies the provider’s chat path; it does not prove that an agent runtime or sandbox is ready. Ask an administrator to check [agent runtimes](https://docs.tale.dev/platform/agents/harnesses) if none is available.

Create or open a project first. For the project’s sharing and knowledge setup, follow [use projects](https://docs.tale.dev/tutorials/member/use-projects).

## Give the agent a focused job

<Steps>

<Step title="Create an agent in the project">

Open the project’s **Agents** tab and select **New agent**. Name it for the job, such as “Launch reviewer”. Choose an **Agent type** and **Model** supported by your workspace. When a model has multiple provider entries, choose the intended provider too.

<Frame caption="Project agents combine a named job with a runtime and model.">

![The project Agents tab lists agents with their configured runtime and model.](https://docs.tale.dev/images/platform/project-agents-models.webp)

</Frame>

</Step>

<Step title="Write instructions that you can evaluate">

In **Instructions**, describe the job, the source material, the expected output, and the limits. For example:

> Review the launch brief attached to the task. List missing decisions, unclear owners, and contradictions. Quote the relevant passage for each finding. Do not change files or contact external services. If the brief is missing, ask for it.

Grant only the **Skills, connectors & tools** and **Secrets** needed for that task. Select **Create agent** to save. You can edit the brief after reviewing a result.

</Step>

<Step title="Assign a concrete task and start it">

Create a task with a clear description and the required input files. Assign the agent, then select **Start agent**. Assignment and starting are separate actions. Watch the task’s status and activity while it runs.

If it cannot start, inspect the displayed reason before retrying. A missing provider, unavailable runtime, policy restriction, or absent input needs a different correction.

</Step>

</Steps>

## Review the work

Read the agent’s task comment and any output files. Compare the result with the brief: did it inspect the right source, support each finding, and stay within scope? A completed run means execution finished, not that the result is correct.

Keep review and completion explicit. Use the project’s task controls to record feedback, request another pass when needed, and mark accepted work as done. [Project tasks](https://docs.tale.dev/platform/projects/tasks) explains the statuses and reviewer field.

<Tip>

Test a missing-input case as well as a normal task. An agent that asks for a missing brief is more useful than one that invents what the brief might say.

</Tip>

## Refine one thing at a time

Improve the instruction that caused a poor result, then try a comparable task. Add tools only when the job needs them, and review the [approval behavior](https://docs.tale.dev/platform/approvals/concepts) before enabling external writes. For a longer worked example, follow [your first agent end to end](https://docs.tale.dev/tutorials/editor/first-agent-end-to-end).

Once you have a task you can evaluate reliably, use the same agent for similar work. If the process needs scheduled runs, defined stages, or connector approvals, build an [automation](https://docs.tale.dev/platform/automations/concepts) around those requirements.

# Use Tale with your team
Source: https://docs.tale.dev/get-started/members

Your everyday work in Tale starts with a conversation or a project. This guide helps you find the right place for a question, a document, and work you want to share with your team.

## Know what you can access

Start with a signed-in account and a working [first chat](https://docs.tale.dev/get-started/quickstart). Your role and project access determine what you can read or change. Members can chat and work in accessible projects. Editing organization-wide knowledge requires Editor or higher; project work follows the project’s access rules. Check [members and roles](https://docs.tale.dev/platform/admin/members-and-roles) when a control is missing.

## Ask a question with enough context

Open **Home** and select **New chat**. Describe the task, provide the information needed, and say what the result should look like. For example, paste meeting notes and ask for decisions, owners, and open questions.

Read the result before using it. When the answer cites a source, open it and check that it supports the claim. A fluent answer is not evidence that the model used the correct document. [Chat effectively](https://docs.tale.dev/tutorials/member/chat-effectively) shows how to improve an answer with follow-up questions.

## Put information in the right place

| You want to… | Use… |
| --- | --- |
| Discuss a file in this conversation | A [chat attachment](https://docs.tale.dev/platform/chat/attachments) |
| Keep source material with a project | The project’s [Knowledge tab](https://docs.tale.dev/platform/projects/manage-files) |
| Make approved material available as organization knowledge | [Knowledge documents](https://docs.tale.dev/platform/knowledge/documents) |
| Maintain a short reusable article | A [knowledge entry](https://docs.tale.dev/platform/knowledge/knowledge-entries) |

Choose the intended audience before uploading. Organization knowledge and a project’s files have different access boundaries. Uploading a file and making it searchable are separate stages; wait for indexing before testing retrieval.

<Frame caption="The Documents list shows uploaded files and their indexing state. This view filters files to indexed uploads.">

![The Documents table lists source files with their indexing status.](https://docs.tale.dev/images/get-started/documents-list.webp)

</Frame>

If you cannot add a shared source, ask someone with edit access. Include the intended audience and where the file should live.

## Work in a project

In Home, choose a project you can access under **Projects**. Use **Tasks** to see the work, **Knowledge** for project files, and **Chats** for conversations. Project chats remain personal until shared with the project.

<Frame caption="A board groups work by status; each card opens the task details.">

![A project task board groups task cards into Backlog, To do, In progress, In review, Done, and Cancelled.](https://docs.tale.dev/images/platform/projects-task-board.webp)

</Frame>

Open a task to read its description, assignee, and discussion. You can create tasks in any project you can open and change the ones you created or that are assigned to you, for example to hand the work to one of the project's agents, or, in a project without agents of its own, to the organization's [standard agent](https://docs.tale.dev/platform/projects/project-agents#standard-agent). Follow [manage project tasks](https://docs.tale.dev/platform/projects/tasks) for ordinary task work and [use projects](https://docs.tale.dev/tutorials/member/use-projects) for a complete example.

## Return to your work

Every section opens on its own first page, whatever you did there last. On a computer, **Home** is the exception: it reopens the chat you last read, and choosing it again starts a new chat. The [navigation guide](https://docs.tale.dev/platform#navigation) explains the desktop and phone controls.

Home lists your chats together with the open tasks assigned to you or waiting for your review; choose **Chats** or **Tasks** above the list to see one kind only. If the Home panel is hidden, **Show sidebar** at the start of the header brings it back. Use a new chat for a new subject and share a project conversation deliberately when teammates need it.

Your language and theme are available from **Manage account**. The [preferences guide](https://docs.tale.dev/platform/member/preferences) explains the other account settings and which features use them.

# Send your first message
Source: https://docs.tale.dev/get-started/quickstart

Start here when you have access to a Tale workspace and want to get your first answer. You will send a short prompt, read the response, and find the conversation again.

## Before you begin

You need your instance address, an account, and a workspace with an AI provider connected. Ask the person who manages your workspace for access. To install your own instance, follow the [self-hosted quickstart](https://docs.tale.dev/self-hosted/install/quickstart); for a managed instance, follow [Cloud onboarding](https://docs.tale.dev/cloud/onboarding).

An account lets you sign in. Your organization is the workspace that holds your team’s members, projects, and configuration. Your role controls which actions you can take there.

## Start a conversation

<Steps>

<Step title="Sign in and start a chat">

Open your instance and sign in with the method your administrator provided. If you belong to several organizations, choose the one where you want to work. Open **Home**, then choose **New chat**, the pencil at the top of the Home list.

</Step>

<Step title="Check the model and write a prompt">

Use the model control below the message field to inspect the available models. It may show **Auto**; you can choose a specific model when you want to control which one answers. The available choices depend on your workspace’s connected providers and access rules.

<Frame caption="The message field and model control are in the same composer.">

![The chat composer contains the message field, the model selector, attachment controls, and the send button.](https://docs.tale.dev/images/platform/chat-composer.webp)

</Frame>

For a first test, use a self-contained request: “Write a three-item checklist for preparing a team meeting. Keep each item to one sentence.” This does not depend on uploaded documents or connected tools.

</Step>

<Step title="Send and read the answer">

Select **Send message** or press Enter. Your message appears in the conversation, followed by the assistant’s response. A thinking indicator may appear before the answer. Wait for the response to finish before evaluating it.

Check whether it followed the requested length and format. Ask a follow-up such as “Add who should prepare each item.” The same conversation retains the context of your earlier messages.

</Step>

</Steps>

## Find the chat again

Home lists the conversation under **Today**; choose it to reopen it. A new chat starts a separate conversation; it is useful when you change subjects. For names, history, and response controls, read [Chat basics](https://docs.tale.dev/platform/chat/basics).

<Tip>

Give the model the goal, the information it should use, and the format you need. “Summarize these notes as decisions and open questions” gives it a clearer task than “Help with this.”

</Tip>

## If you cannot get an answer

| What you see | What to do |
| --- | --- |
| You cannot sign in | Check the instance address and sign-in method with your administrator. |
| No models are available | Ask an administrator to check [AI providers](https://docs.tale.dev/platform/admin/providers) and your model access. |
| A provider or model error | Try another available model and report the displayed error to the administrator. |
| A usage limit message | Ask the administrator to review the relevant [policy](https://docs.tale.dev/platform/admin/governance/policies-and-limits). |
| An answer without your documents | This first prompt did not supply a source. Follow [chat attachments](https://docs.tale.dev/platform/chat/attachments) or [knowledge](https://docs.tale.dev/platform/knowledge/overview) to add one. |

Continue with [using Tale with your team](https://docs.tale.dev/get-started/members) or [writing effective prompts](https://docs.tale.dev/tutorials/member/chat-effectively).

<Video src="https://docs.tale.dev/videos/en/tutorials/ep1-welcome/ep1-welcome.en.mp4" poster="https://docs.tale.dev/videos/en/tutorials/ep1-welcome/ep1-welcome.en.webp" captions="https://docs.tale.dev/videos/en/tutorials/ep1-welcome/ep1-welcome.en.vtt" lang="en" title="Episode 1 — Welcome to Tale" caption="Episode 1 — Welcome to Tale (2:48)">

</Video>

# Tale documentation
Source: https://docs.tale.dev/

Find your way around Tale, give an agent its first task, or build on the platform. Start with [your first message](https://docs.tale.dev/get-started/quickstart) if you already have an account, or [install your own workspace](https://docs.tale.dev/self-hosted/install/quickstart).

## From a task to a result

1. [Describe the work](https://docs.tale.dev/platform/projects/tasks). Give the task its goal, source files, and a clear outcome.
2. [Give an agent the task](https://docs.tale.dev/get-started/editors). Choose its instructions and tools, then start the work.
3. [Review what comes back](https://docs.tale.dev/platform/projects/task-automation). Inspect the report and files, then approve or request changes.

Each guide explains the access and setup it needs. A working chat does not prove that an agent runtime or sandbox is ready.

## What would you like to do?

<CardGroup cols="2">

<Card title="Create and test a project agent" icon="bot" href="https://docs.tale.dev/get-started/editors">

Configure a focused agent, give it a project task, and inspect its first result.

</Card>

<Card title="Work with your team" icon="users" href="https://docs.tale.dev/get-started/members">

Find your conversations, work with sources, and join a project.

</Card>

<Card title="Set up a workspace" icon="shield" href="https://docs.tale.dev/get-started/admins">

Connect a provider, invite people, and choose their access.

</Card>

<Card title="Connect another system" icon="code" href="https://docs.tale.dev/get-started/developers">

Make your first API request and check the response.

</Card>

</CardGroup>

## Learn by doing

Follow a complete task with example inputs and checkpoints. Check the prerequisites before starting, or [browse all tutorials](https://docs.tale.dev/tutorials/overview).

<CardGroup cols="3">

<Card title="Organize work in a project" icon="folder" href="https://docs.tale.dev/tutorials/member/use-projects">

Bring a task, source files, and project instructions together.

</Card>

<Card title="Run your first agent" icon="bot" href="https://docs.tale.dev/tutorials/editor/first-agent-end-to-end">

Start a delegated task and review the report and delivered files.

</Card>

<Card title="Build a workflow with approvals" icon="check-check" href="https://docs.tale.dev/tutorials/editor/workflow-with-approvals">

Review an action before the workflow carries it out.

</Card>

</CardGroup>

## Find the reference you need

- [Platform guides](https://docs.tale.dev/platform) explain controls, permissions, expected behavior, and troubleshooting.
- [API reference](https://docs.tale.dev/develop/api-reference) describes the contract for integrating another system.
- [Self-hosting](https://docs.tale.dev/self-hosted) covers installation, configuration, backups, and upgrades.
- [Tale Cloud](https://docs.tale.dev/cloud) explains managed hosting and operational responsibilities.

The same product guides apply to Cloud and self-hosted instances. Screenshots show the English interface; German and French pages use the labels from their respective interfaces.

# Govern project agents
Source: https://docs.tale.dev/platform/admin/agents

Govern an agent through its project and the organization resources it uses. There is no separate organization-wide agent roster to configure: open the project from **Projects** in Home, then **Agents** to inspect or edit its workers.

## Establish who can change the agent

Anyone who can read the project can see its agents. People with project edit access may create, update or delete agents while the project is active. Archived projects remain readable. Review [members’ roles](https://docs.tale.dev/platform/admin/members-and-roles) and [team access](https://docs.tale.dev/platform/admin/teams) when the wrong person can or cannot manage a roster.

An agent belongs to one project. Neither its ID nor access to a second project lets an integration use it as that second project’s agent. Projects allow up to 50 agents, with names unique inside each project.

## Review the resources before work starts

Open the agent’s edit dialog and review the combination, rather than checking the model alone:

| Check | Why it matters | Where to resolve a problem |
| --- | --- | --- |
| Harness, model and provider | The credential must support that execution path. | [AI providers](https://docs.tale.dev/platform/admin/providers). |
| Skills and their sharing | The project’s team scope determines which bundles can be equipped. | [Skill library](https://docs.tale.dev/platform/workspace/skills) and project access. |
| Connectors and platform tools | They grant access to services and supported data operations. | [Connector credentials](https://docs.tale.dev/platform/admin/connectors) and the agent’s equipment. |
| Secrets | The running session can read the granted values. | The agent’s **Secrets** controls, available to Owners and Admins. |
| Sandbox capacity and spending | Work needs an available environment and an allowed budget. | [Sandboxes](https://docs.tale.dev/platform/admin/sandboxes) and [Policies and limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits). |

For a review agent, repository read access and reporting tools may be enough. Granting a write tool authorizes its operations within its access rules; a standing instruction to ask first is not a substitute for removing an unnecessary grant.

## Handle secret changes deliberately

Only an Owner or Admin can change secret grants. An editor can update other fields while preserving the existing grants. Secret values are encrypted in organization storage and are not returned with the agent configuration, but a running agent receives the values it is granted.

Use narrowly scoped, replaceable credentials. A secret name may be shared by several agents or automation nodes, so rotating or deleting its organization value affects every future run that refers to it. Review those uses before changing it.

## Apply the same review to API clients

The public API reads and writes the same project roster and applies the key holder’s project permissions. Every operation includes a project ID. An update provides the full configuration, including secret grants to retain; omitting them requests their removal and therefore requires administrative permission.

Use the [project-agent API example](https://docs.tale.dev/develop/api-reference#manage-a-projects-agents) for integration details. After a configuration change, reopen the agent to check the saved model, equipment and grants, then give it a small task with an outcome a person can review. [Project agents](https://docs.tale.dev/platform/projects/project-agents) covers that workflow.

# API keys
Source: https://docs.tale.dev/platform/admin/api-keys

Create an API key when a script or service needs to call Tale's REST API. A key belongs to the person who created it, not to the organization whose settings page created it: it acts as that person, follows their current permissions, and works in every organization they are a member of. A REST call names the organization it addresses with the `X-Organization-Slug` header; a key whose holder belongs to one organization may omit it. Owners, Admins, and Developers manage their keys under **Settings > API > REST**, and so does a member an Admin granted a competence that is used with a key: **Call models over the API**, **Export notifications**, or **Act for another member**. Tale refuses anyone else a new key with `403 API_KEY_CREATE_FORBIDDEN`.

<Frame caption="Settings > API > REST — where keys are created, rotated, and revoked.">

![The Create API key dialog asks for a descriptive name and an expiry before a key is generated.](https://docs.tale.dev/images/get-started/settings-api-keys.webp)

</Frame>

## Create a key

1. Select **Create API key**.
2. Enter a **Key name** that identifies the caller, such as `Billing sync` or `Document import`.
3. Choose **Expiration**: 7, 30, or 90 days, one year, or never. The form starts at 30 days.
4. Create the key and copy its secret into the caller's approved secret store before closing the confirmation.

The complete secret is shown once. The table later shows only a masked fragment, the creation date, and when the key was last used. It lists your keys, not your teammates' keys.

<Warning>

Anyone holding a key can act with its owner's permissions. Keep it out of source code, chat messages, screenshots, and logs. Use an account with only the access the integration needs.

</Warning>

## Verify the caller

Follow the authenticated request in the [API quickstart](https://docs.tale.dev/get-started/developers). Confirm the returned identity and organization before starting a write or import. After an authenticated request, check **Last used** in the key table.

A successful authentication does not guarantee permission for every resource. Project access and the key owner's current role still apply. If a request fails, use the API's error response to distinguish an expired or revoked key from missing resource permissions.

## Rotate without an outage

1. Create a replacement key before the old one expires.
2. Update the caller's secret store and restart or reload it as its configuration requires.
3. Run an authenticated request with the replacement and check that it works.
4. Revoke the old key only after every dependent caller has moved.

Tale does not automatically rotate keys. Key creation and revocation happen in this UI, not through `/api/v1`. A caller can inspect its key's name and expiry through `GET /api/v1/me` and alert the responsible person before expiration.

## Revoke a key

Open its row menu, select **Revoke key**, and confirm. Future requests with the key can no longer authenticate, calls to the model endpoints included; an answer that is already streaming finishes. Revocation cannot be undone; create a new key if you revoke the wrong one. Creating and revoking a key each leave a row in the audit log under **Settings > Governance > Logs**, in every organization you belong to.

Do not use an old **Last used** date as the only reason to revoke a key. A monthly job or a recovery process may legitimately be idle. Check the caller identified by the name first.

## Understand permissions and limits

Role changes take effect for existing keys on subsequent requests. Disabling the owner's membership removes their access; a key does not preserve the role it had when created. Losing the role or competence that let you create keys leaves the ones you hold in place: **Settings > API > REST** keeps listing them for you to revoke, but offers no new one.

Give an integration the narrowest access that works. A notification mirror, for example, does not need an Admin account: an Admin can grant an ordinary member the `tale:notifications.export` capability, which permits that export and none of the other rights of the Admin role. The grant applies only in that organization, can expire, and ends when the member is removed. Grant it under [Competences](https://docs.tale.dev/platform/admin/governance/competences), where an integration that relays people's answers and review decisions gets `tale:rest.act-as` the same way; [Delegate the export without an Admin role](https://docs.tale.dev/develop/api-reference#delegate-the-export-without-an-admin-role) covers the API side.

REST rate limits apply to the authenticated key holder. Several keys owned by the same person do not provide separate rate-limit allowances. See [Rate limits](https://docs.tale.dev/develop/rate-limits). A [budget rule](https://docs.tale.dev/platform/admin/governance/policies-and-limits) can additionally cap what requests authenticated with one key may spend: their usage counts toward the key, and a send or a model call over the cap is refused with `429 BUDGET_EXCEEDED`. Automation runs started with the key count toward it as well, alongside the personal limits of the member the key acts for. [How usage is counted](https://docs.tale.dev/platform/admin/governance/usage-attribution) has the full rule.

A key can also call the organization's models from tools such as opencode or Claude Code, through the [model endpoints](https://docs.tale.dev/develop/use-tale-from-your-editor#model-endpoints), once an Admin turns them on under [Models](https://docs.tale.dev/platform/admin/governance/content-models#model-endpoints). Its holder must be an Owner, Admin, or Developer, or hold **Call models over the API**. Those calls count toward the key's budget rules like its chat messages, and they appear as **Direct API** in usage analytics under the person and the key.

API keys authenticate software calling Tale. [Connector credentials](https://docs.tale.dev/platform/admin/connectors) serve the other direction: they let Tale call an external service. [Use Tale from your editor or a script](https://docs.tale.dev/develop/use-tale-from-your-editor) shows where a key goes in opencode, Claude Code, and a shell script.

# Branding
Source: https://docs.tale.dev/platform/admin/branding

Give an organization its own logo, browser-tab icons, and accent color under **Settings > Branding**. Owners and Admins can edit these settings. They apply to the organization you have open, so check the organization name before changing shared branding.

<Frame caption="Settings > Branding — the logo, favicon, and colour controls beside a live preview of the sidebar.">

![The Branding settings page with logo and favicon uploads, an accent colour field, and a live preview pane on the right.](https://docs.tale.dev/images/platform/settings-branding.webp)

</Frame>

## Choose the assets

| Setting | What to prepare |
| --- | --- |
| **Logo** | A mark that stays readable at sidebar size and works on light and dark backgrounds. SVG is preferred; raster images should be at least 64 × 64 pixels. |
| **Favicon** | A small, recognizable tab icon. You can provide separate light and dark variants. |
| **Accent color** | Your brand's hex color, then a visual check in both themes. Tale derives the displayed palette for the current theme. |

The organization name supplies the text wordmark when there is no logo. Change that name under **Settings > Organization**; there is no separate application-name field on Branding.

## Upload a logo or favicon

Use the corresponding upload field and select the image. Uploading or removing an image takes effect immediately; it is not held until you select Save. The preview and organization branding refresh after the operation succeeds.

When no explicit favicon is configured, Tale can derive one from the uploaded logo. Provide an explicit icon when the full logo becomes hard to recognize at tab size. Check the tab icon and sidebar after uploading, including in the other theme.

<Note>

The header's Discard action applies to pending form edits. It does not undo an image that has already been uploaded or removed.

</Note>

## Change the accent color

Edit **Accent color** and inspect the preview. Select **Save** in the settings header to persist the change, or **Discard** to return to the saved value. The color field reflects the current theme, so a derived dark-theme color may differ from the stored light-theme value. The preview shows the color as it will look once saved, so in the dark theme it can differ from the value in the field. Saving a change, uploading an image or removing one each leave a row in the audit log under **Settings > Governance > Logs**.

Buttons keep your color as closely as legibility allows. Other marks drawn in the accent use your color only where it reads as text on the page. Where it does not, Tale uses a deeper shade of it, or a lighter one in the dark theme. These marks include a link, a mention, a source reference, the selected navigation item, an unread dot, the keyboard focus ring, a switch that is on, and a progress bar. A mid-tone color can therefore look slightly different on a link or a switch than on a button.

After saving, reload the page and check a selected navigation item, a button, and keyboard focus. A color that looks good as a large swatch may be hard to recognize in a small control.

## Check where branding appears

Organization branding applies inside that workspace. Switching organizations loads the destination organization's branding. Sign-in screens appear before an organization is selected and use the platform's default branding.

If you still see an old browser icon, reload the page and check the explicit favicon fields. An explicit favicon takes precedence over one derived from the logo. Use **Reset** only when you intend to remove the organization's configured branding, and read the confirmation first. Confirming takes effect immediately: the images are deleted and the cleared accent color is saved, so no further **Save** is needed and nothing is left unsaved.

# What’s new
Source: https://docs.tale.dev/platform/admin/changelog

Open **What's new** to read release notes for the Tale platform. Every signed-in member can view them; you do not need an administrator role.

## Open the release notes

Use **What's new** in the user menu, or select **View** on an upgrade notification. Opening the notes acknowledges the update and clears its unread indicator. The page shows the relevant releases, or tells you when you are up to date.

Expand a release to read its version, date, title, and notes. Focus on changes to the tasks your team uses, then open the linked product guide when you need the current instructions.

## Find older or unavailable notes

Use the link to older releases on GitHub when the change you need is outside the displayed range. The viewer obtains public release information from GitHub and caches it; a deployment with no network access may be unable to load uncached notes.

A version that has not yet been published can have no matching release entry. Check the linked release history rather than assuming that an empty view proves nothing changed.

## Distinguish releases from organization activity

Release notes describe changes to Tale itself. They do not show who changed an organization's settings or content; use [audit logs](https://docs.tale.dev/platform/admin/governance/audit-logs) for that investigation.

If you operate a deployment, follow [the upgrade guide](https://docs.tale.dev/self-hosted/operate/upgrades) for the upgrade procedure, then review the release notes for changes your team needs to know.

# Connector credentials
Source: https://docs.tale.dev/platform/admin/connectors

Add connector credentials so Tale can use services such as a mailbox, file store, or issue tracker. Owners, Admins, and Developers manage them under **Settings > Connectors**. Choose the service and account your work needs; the [connector catalog](https://docs.tale.dev/platform/connectors/overview) explains each service's available actions.

## Add an account

1. Select **Add credential**, then the connector. Already configured connectors appear first and can hold additional credentials.
2. Check the **Name**. It starts as the connector's name, with a number added when another credential for that connector already uses it: `GitHub`, then `GitHub 2`. A name such as `Support inbox` or `EU store` is easier for an automation author to recognize. An OAuth connection has no name field: Tale names it the same way when consent completes (a second Slack workspace takes the workspace's name), and **Edit credential** renames it.
3. Complete the authentication method offered by that connector. For OAuth, select **Connect** and complete the vendor's consent flow. Each **Connect** adds a new credential for the account you authorize and never replaces an existing one, so sign in to the vendor as the account you want to add.
4. Complete the form and check the resulting row, including its connector, account or instance, and status.

Slack connects one credential per workspace. Authorizing a workspace that is already connected renews that workspace's credential instead of adding a second one.

The connector determines which fields appear. Use the account's actual credentials, not a Tale API key.

| Method | Required information |
| --- | --- |
| API key | The key issued by the service, such as Tavily or Shopify. Jev decisions takes an OpenRouter API key. |
| Token | A service token, such as a GitHub personal access token, a Discord bot token, or a GlitchTip API token with `project:read` and `event:read`. |
| Username and password | The service's expected pair. This can be a login and app password, or a vendor-specific ID and token. |
| OAuth | Authorization in the vendor's browser flow; Tale stores the returned authorization. |

Some connectors also require an instance address. For Confluence, use the Atlassian site origin. For GlitchTip, use the instance origin, such as `https://app.glitchtip.com`; a self-hosted instance must also be allowed by the deployment's connector host policy. For Shopify, use the store's `myshopify.com` origin, not the customer-facing storefront domain.

## Choose the default

The table contains one row per credential and updates while it is open: a credential another admin adds, changes or deletes appears there without a reload. The **Default** badge marks the credential used when an action does not explicitly name one. Select **Make default** in a row's menu to change it; one default is allowed per connector.

A connector with several credentials and no default can still serve callers that name a credential. Callers that omit the name need a default. Name accounts clearly before wiring automations so a future administrator can identify the intended account.

Mailbox synchronization and inbox triage can inspect every active credential for a mailbox connector. A second mailbox does not have to become the default before these operations can find it. When you compose a new email, the **Inbox** field lists each mailbox by its name, and the email leaves from the one you choose. Replies in that conversation, including a retry of a failed send, leave from the same mailbox.

## Rotate a secret or pause access

Use the row's replacement action for its method, such as **Replace API key** or **Replace token**. The new secret replaces the stored one while preserving the credential's name, default choice, and references. Test an appropriate service action after replacement.

**Disable** pauses a credential while retaining its configuration; **Enable** restores it. **Edit credential** handles other editable details, including its name or instance address where supported.

<Warning>

Deleting credentials removes access for automations and agents that depend on them. Move callers first. Deleting a connector's default makes its oldest remaining active credential the default, and the confirmation names that credential before you delete. A disabled credential or one that needs Reconnect never takes over, so with no active credential left the connector has no default until you choose one. Deletion cannot be undone by reopening the same row.

</Warning>

## Prepare an OAuth app

Owners and Admins use **OAuth apps** at the bottom of the page to configure the vendor app registrations used during consent. An organization app overrides the deployment-wide app. If neither exists, the connector cannot start authorization and the page shows that it is not configured.

Select **Configure**, enter the vendor's client ID and secret, and register the exact redirect URIs shown in the dialog with the vendor. Microsoft apps may also require a directory/tenant ID. On a later edit, leave a stored secret blank to keep it.

The Google Drive app also supports Knowledge import. The OneDrive/SharePoint import entry is for Knowledge rather than a separate connector. Slack's app is configured by the deployment operator. Read the relevant [connector guide](https://docs.tale.dev/platform/connectors/overview) before assigning vendor permissions.

For OneDrive/SharePoint, **Use Entra ID SSO app** can copy an existing SSO registration into the import configuration. This is a one-time copy: after rotating the SSO secret, copy it again and review the redirect URI and delegated permissions listed by the confirmation.

## Reconnect or diagnose a failure

**Reconnect needed** means stored OAuth authorization can no longer refresh. Choose **Reconnect** in that row's menu and authorize the same account again. Tale renews exactly that credential: its name, default choice and references stay, and no other credential changes. Reconnect does not re-enable a deliberately disabled credential; **Enable** returns it to service.

If the credential is removed before consent completes, or your role no longer allows you to manage credentials, Tale saves nothing and shows the reason. For Slack, authorize the workspace the credential already connects. Tale refuses a different workspace; connect that one with **Add credential**.

If the connection cannot start, check whether the OAuth app is configured. If the vendor rejects the return to Tale, compare the registered redirect URI with the exact URI shown by Tale. If an action fails after connecting, check the account's permissions and the required scope for that action.

For systems without a built-in connector, see [MCP and custom integrations](https://docs.tale.dev/platform/connectors/mcp-servers). Registering an arbitrary outbound MCP server is not part of this credential page.

# Enterprise SSO and provisioning
Source: https://docs.tale.dev/platform/admin/enterprise-sso

Enterprise SSO lets members sign in through your identity provider (IdP). SCIM lets that provider create, update, and deactivate members without waiting for them to sign in. An organization has one connection; you can enable sign-in, provisioning, or both in **Settings > Enterprise SSO** as an Admin or Owner.

## Before you start

You need permission to register an application with your IdP, its client credentials or SAML metadata, and the public Tale address members will use. Keep a working administrator session open while testing so you can correct the connection if a test sign-in fails.

Choose a **Display name** members will recognize. When more than one organization on the deployment has SSO enabled, it appears in the organization picker on the public sign-in page, so avoid internal or confidential information.

<Frame caption="Choose the protocol first. Tale shows the relevant fields and the callback address to register with your identity provider.">

![Enterprise SSO settings with Microsoft Entra ID selected, a redirect URL, and issuer and client credential fields.](https://docs.tale.dev/images/platform/settings-enterprise-sso.webp)

</Frame>

## Choose the protocol

| Protocol | Use it when | Information to prepare |
| --- | --- | --- |
| **Microsoft Entra ID** | Your organization uses Entra; optional team sync uses Microsoft Graph. | Tenant issuer URL, client ID, client secret. |
| **Generic OIDC** | Your provider supports OpenID Connect discovery. | Issuer URL, client ID, client secret. |
| **OAuth2** | Your provider has no OIDC discovery document. | Client credentials and authorization, token, and userinfo endpoint URLs. |
| **SAML 2.0** | Your IdP uses SAML assertions. | IdP metadata or its entity ID, sign-on URL, and signing certificate. |

## Connect an OIDC or OAuth2 provider

1. Select the protocol in Tale and open **Setup guide** to find the callback URL.
2. Register a web application with your IdP. Copy the callback URL exactly, including scheme, host, and path. Register each additional callback URL Tale shows if members use several deployment domains.
3. Enter the client ID and secret in Tale. For OIDC, enter the issuer URL; Tale discovers the endpoints. For OAuth2, enter the three endpoint URLs yourself.
4. Review **Scopes** and **Advanced**. Request the identity claims your provisioning rules need. Map nonstandard claim names where necessary; claim paths can use dots, such as `realm_access.roles`.
5. Select **Test connection**, resolve any error, then **Save** in the header. Continue with a real sign-in test below.

For Entra, use a tenant-specific issuer such as `https://login.microsoftonline.com/{tenant-id}/v2.0`, register the callback as a Web redirect URI, and copy the client secret's value rather than its ID. Microsoft's [application registration guide](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) explains the provider-side setup. Group-to-team sync requires the Microsoft Graph `GroupMember.Read.All` permission and admin consent. App roles you define in the app registration and assign to users or groups in the enterprise application arrive in the sign-in token, so an **App role** rule matches the role's **Value** (for example `Administrator`) and needs no Graph permission.

For Google, choose **Generic OIDC** with issuer `https://accounts.google.com`; see Google's [OpenID Connect setup](https://developers.google.com/identity/openid-connect/openid-connect). Standard Google OIDC does not provide group memberships, so signing in with Google alone does not enable group-to-team sync.

<Note>
Microsoft 365 file import has a separate consent flow under Knowledge. Do not add `Files.Read` or `Sites.Read.All` to SSO scopes just to let members sign in. Configure import access through [connector OAuth apps](/platform/admin/connectors).
</Note>

## Connect a SAML provider

1. Choose **SAML 2.0**. Copy the **SP metadata URL** and **ACS (reply) URL** into your IdP's SAML application. Use the service-provider metadata for its entity ID/audience and set the Name ID format to email address.
2. Under **Import IdP metadata**, import the IdP's metadata URL or select **Upload XML**. Review the entity ID, sign-on URL, and signing certificate filled in by the import. You can also enter them manually.
3. Under **Advanced**, map email, name, and groups if the IdP uses different attribute names. Keep **Require signed assertions** enabled.
4. Save the connection, then test a sign-in through the IdP.

If your IdP encrypts assertions, add a matching **SP certificate (PEM)** and **SP private key (PEM)** under **Advanced**. The certificate is published in SP metadata; the private key is stored as a secret and is not shown again. Configure the IdP to encrypt before enabling **Require encrypted assertions**. Tale refuses that setting without a decryption key and rejects unencrypted assertions when it is enabled.

Both IdP-initiated and Tale-initiated SAML are supported. For a sign-in started in Tale, finish in the same browser so the callback can validate the cookie created at the start.

## Assign roles and teams at sign-in

| Setting | What it controls |
| --- | --- |
| **Default role** | Role for newly provisioned members when no role rule matches; initially Member. |
| **Auto-assign roles from the IdP** | Maps groups, app roles, job titles, or claims to Tale roles. Review who could match an Admin rule before enabling it. |
| **Sync IdP groups to teams** | Creates or joins teams from group membership at sign-in. |
| **Exclude groups** | Comma-separated group names to leave out of team sync. |

Role rules are checked from top to bottom, and the first rule that matches decides the role. A person who matches several rules — for example, someone with both an `Administrator` and an `Employee` app role — gets the role of the rule higher in the list, not automatically the most privileged one. Put the most privileged rules first: drag a rule by its handle or use its **Move up** and **Move down** arrows, then save.

Team sync removes memberships it previously granted when groups disappear and deletes teams it created once empty. It preserves memberships created manually or through SCIM, and leaves excluded groups alone. See [teams](https://docs.tale.dev/platform/admin/teams) for manual membership management.

## Provision members through SCIM

1. In **SCIM provisioning**, select **Generate token** and copy it immediately; it is shown once.
2. Enter the token as a bearer credential and the displayed **SCIM base URL** in your IdP's provisioning configuration.
3. Provision a test user and group. Confirm the member and team appear in Tale, then test updates and deactivation before enabling a wider rollout.

SCIM Users map to members and Groups to teams. Deactivation (`active: false`) disables the member's access; reactivation restores their previous role. Deleting a SCIM user removes their organization membership but preserves their account. Provisioning them again starts with the connection's default role.

The organization owner cannot be deactivated or removed through SCIM. Groups can contain only members of this organization. A username change is refused if the new email is in use or the account belongs to multiple organizations, protecting its shared sign-in identity.

## Sign members in through an authenticating proxy

An application that already authenticates its users can hand them into this organization through its reverse proxy, so members never see Tale's sign-in form. The **Trusted headers** card on the same page holds the switch, the role ceiling and the keys the proxy presents.

1. Turn on **Accept sign-ins from a trusted proxy** and choose the **Highest role a proxy may assert**. The role header is capped at this role; Owner is never assertable. On every sign-in the member's seat follows the asserted role; an Owner seat never changes.
2. Select **Create key**, name it after the proxy that will hold it, and copy the key immediately; it is shown once. An organization holds at most 10 live keys.
3. Configure the proxy to send its sign-ins to the **Hand-off URL** with the key in the key header and the identity headers listed under **Header names**. A member who arrives through the proxy is signed in on the app's first request and never sees a sign-in page; the app offers them no sign-out, since the proxy owns that session. Pointing the proxy's `/log-in` at the same address remains supported.

To show the pages inside the application's own page, turn on **Allow embedding in a frame** under **Embedding** and list the page's origin under **Allowed origins**; Tale then admits that origin as a frame ancestor. A frame carries the signed-in session only when the surrounding page is on the same site as Tale.

The key decides the organization: a member signs in, an address Tale has never seen becomes a new member with the asserted role, and an existing account from another organization is refused. Turning the switch off refuses every key without revoking one. **Revoke** stamps a key so the proxy can no longer sign anyone in; sessions it already started stay signed in. The operator's [authentication configuration](https://docs.tale.dev/self-hosted/configuration/authentication) covers header names and proxy requirements.

## Verify and troubleshoot

Open a separate browser session and choose **Continue with SSO**. The organization picker appears only when more than one organization on the deployment has SSO enabled; select the organization by its display name there. Otherwise the button opens the one enabled organization's identity provider directly, and an address typed into the e-mail field is passed along only as a login hint — Tale does not route by e-mail domain. Complete sign-in, then check the expected role and team memberships. **Test connection** checks connection details; it does not prove that a real user receives the right access.

| Symptom | What to check |
| --- | --- |
| Redirect mismatch, including `AADSTS50011` | Compare the registered callback with Tale's exact URL; check domain, scheme, path, and trailing slash. |
| Connection test fails | Check issuer/endpoints, client ID, secret value and expiry, and required provider consent. |
| Browser-binding error | Start sign-in again in the same browser and allow the cookies needed across redirects. |
| Wrong role or missing team | Inspect the IdP's actual claims, role rules and their order, exclusions, and group permissions. An **App role** rule matches the app role's Value, not its display name or ID. |
| SCIM cannot connect | Check the base URL, bearer token, and whether provisioning is enabled. |
| Proxy sign-in is refused | Check that the card is on, the key is not revoked, and the proxy sends the email header and the key on the hand-off request. |
| Missing redirect URL or server-configuration warning | Ask the deployment operator to check [authentication configuration](https://docs.tale.dev/self-hosted/configuration/authentication). |

**Disable sign-in** stops new SSO sign-ins while keeping active sessions. **Remove** deletes the connection configuration and credentials. Arrange another working sign-in method before using either action.

# Audit logs
Source: https://docs.tale.dev/platform/admin/governance/audit-logs

Open **Settings > Governance > Logs** as an Admin or Owner to investigate recorded actions in your organization. Start with the event and time you need, then inspect its actor, target, result, and available change details.

## Find a change

1. Select **Audit logs** and open **Filter**.
2. Choose a category relevant to the action, such as member changes, security, or data.
3. Find the event by timestamp, action, and target. Open its row to inspect the details.
4. Check the status before interpreting the event: an attempted action marked denied or failed does not establish that the change succeeded.

The active tab and category are reflected in the URL, so you can bookmark the view. Access still depends on your organization permissions.

<Frame caption="Governance > Logs: the Audit logs tab narrowed to the Member category. Clear all removes the filter.">

![The Logs page with the Audit logs tab filtered to the Member category, listing eleven events in which Alex Rivera added members, created three teams, and added a member to each team, every row showing its resource, target, category, and a Success status.](https://docs.tale.dev/images/platform/governance-audit-logs.webp)

</Frame>

## Read an event

| Field | What to look for |
| --- | --- |
| Timestamp | When Tale recorded the action. |
| Action | The operation that was attempted or completed. Some newer actions appear by their technical name. |
| User | The person or system actor responsible for the action. |
| Resource and target | The kind of item and the particular record affected. |
| Category | The grouping used by the filter. |
| Status | Success, failure, or denied. |
| Detail view | Available previous/new state, changed fields, metadata, and error information. Not every event has every field. |

Treat the log as evidence of the events it records. It is not a complete copy of every conversation, provider response, or external service's activity.

## Choose the right tab

**Audit logs** contains individual events; the table loads more as you scroll, and its footer states how many events are loaded so far, so a count is never the whole history until the footer says so. **Sign-in blocks** helps investigate authentication lockouts. **Activity logs** summarizes activity and outcomes over a period: the period chosen in its **Filter** (7, 30, or 90 days) is named above the totals, and every number on the tab covers that period only. **Error logs** focuses on failures; its category filter helps narrow the investigation.

When a member cannot sign in, begin with the sign-in blocks and the [account security guidance](https://docs.tale.dev/platform/admin/two-factor-authentication). When a configuration changed unexpectedly, use the audit event and its detail view.

## Export results

Set the category filter, then open **Export** and choose CSV or JSON. CSV provides flat columns for spreadsheets, including UTC timestamps, actor identifiers, resource identifiers, status, and errors. JSON preserves the fuller event objects, including available change payloads and integrity hashes.

Exports honor the category filter and contain at most 10,000 rows, newest first. They are generated on the server and downloaded through a temporary link. A filtered or capped export is a selection of evidence; it is not necessarily the entire audit history or a complete hash chain.

## Retention and integrity

Use **Verify now** in **Chain integrity** to check the stored audit chain. The panel shows its status and the latest automated check. If a check reports a break, preserve the reported details and investigate with the deployment operator before relying on that segment of history.

A successful check covers the retained records it examined; it does not establish an independently signed origin for the history. The [operator integrity guide](https://docs.tale.dev/self-hosted/operate/security/audit-log-integrity) explains the checks and their limits.

Hash chaining helps detect changes to stored records; it does not prove that every possible action was logged. Audit retention is configurable under [Policies and limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits). Check the active policy and deployment bounds instead of assuming a fixed retention period. Recoverable audit records can appear in [Trash](https://docs.tale.dev/platform/admin/governance/trash); permanent cleanup limits the history available here.

Scheduled retention cleanup records each of its runs here as system events in the **Data** category: when the run started, how many records each category deleted, and whether the run completed or failed.

# Competences
Source: https://docs.tale.dev/platform/admin/governance/competences

Use **Settings > Governance > Competences** as an Admin or Owner to keep the organization's competence register. A competence is one of two things:

- A **platform capability** lets a member do one narrow thing that otherwise needs a higher role. Grant it to the account behind an integration instead of making that account an Admin, which would also let it manage members, single sign-on and passwords.
- A **qualification** is a name your organization's review policy can require of the person who approves a review.

A grant applies in this organization only. Tale records every grant and revocation in the audit log, and removing a member from the organization revokes their grants.

## Platform capabilities

| Capability                                             | What it allows                                                                                                                                            |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Export notifications** (`tale:notifications.export`) | Read the notifications another member can see through the REST API, so another application can mirror them.                                               |
| **Act for another member** (`tale:rest.act-as`)        | Name the member an API call answers a question or decides a review for. The task timeline and the audit log then show that person instead of the API key. |
| **Publish skills to the organization** (`tale:skills.publish`) | Share a skill with the whole organization even when the [skill sharing policy](https://docs.tale.dev/platform/admin/governance/policies-and-limits#skill-sharing) reserves that for Editors or admins. |
| **Call models over the API** (`tale:models.api`) | Call the organization's models from one's own tools with a personal API key, through the [model endpoints](https://docs.tale.dev/develop/use-tale-from-your-editor#model-endpoints), once the organization turns them on. It also opens **Settings > API** with its **REST** and **Models** tabs, to create the key and read the setup. |

Owners and Admins have all four through their role, and Developers also have **Call models over the API** through theirs. Any other member needs the capability granted here, for example a Developer account whose API key an integration uses for an export. Without it, the REST API answers an export or an `actor` with `403 ROLE_FORBIDDEN`, and the model endpoints answer `403 MODEL_API_FORBIDDEN`. The [API reference](https://docs.tale.dev/develop/api-reference#name-the-member-the-gesture-is-for) describes the export and `actor` requests.

**Export notifications**, **Act for another member**, and **Call models over the API** are used with a personal API key, so each also lets its holder create one under **Settings > API > REST**. The key acts with the holder's own role; the competence adds only its own right.

**Publish skills to the organization** matters only while the skill sharing policy reserves organization-wide skills. Under **Editors and above**, Editors and Developers already have it through their role. Without it, a member can share skills with their own teams only, and the skill editor, uploads, and the REST API refuse an organization-wide skill with `403 SKILL_PUBLISH_FORBIDDEN`.

**Call models over the API** takes effect only once the organization turns on the model endpoints under [Models](https://docs.tale.dev/platform/admin/governance/content-models#model-endpoints). A member who holds it can open **Settings > API** with its **REST** and **Models** tabs to create a personal key and copy the setup; the **MCP** and **WebDAV** tabs stay with Owners, Admins, and Developers. Once the grant is revoked, Tale refuses the member's next model call.

## Grant a competence

1. Select **Grant competence**.
2. Choose the **Member**.
3. Choose the **Competence**: a platform capability, or **Qualification**, then type the **Qualification name** your review policy uses. Names that start with `tale:` are reserved for platform capabilities.
4. Choose when it **Expires**: **Never**, **In 30 days**, **In 90 days** or **In 1 year**.
5. Optionally note the **Evidence**: why the member holds it, such as a certificate, a ticket or the system it serves. It stays in the register.
6. Select **Grant**.

The grant applies to the member's next request, so an integration does not need a restart. A member holds each competence once at a time: to change its expiry or evidence, revoke the grant and grant it again. If the member already holds it, the dialog says so and grants nothing.

## Revoke a competence

Select **Revoke** on the row and confirm with **Revoke**. The member loses the competence right away. The grant stays in the register as history with the status **Revoked** and the revocation date; point at the date to see who revoked it.

## Read the register

The list opens on **Active** grants. Use **Filter > Status** to include **Expired** and **Revoked** grants, or select **Clear all** to see every grant.

| Status      | Meaning                                                                                                                   |
| ----------- | ------------------------------------------------------------------------------------------------------------------------- |
| **Active**  | The member holds the competence. The line below shows its expiry date, or **No expiry**.                                  |
| **Expired** | The expiry date has passed, shown below the status. Grant it again if the member still needs it.                          |
| **Revoked** | An Admin or Owner revoked it, or a new grant replaced it after it expired. The revocation date is shown below the status. |

Removing a member revokes every active grant they hold — capabilities and qualifications alike — so a re-added member starts without them. A revoked grant whose holder has left the organization names them **Former member**. The register lists every active and expired grant, and the 1,000 most recent revoked ones as history.

<Tip>

An integration can check its own key with `GET /api/v1/me`: `capabilities.actAs`, `capabilities.notificationExport`, `capabilities.skillPublish`, and `capabilities.modelApi` say whether the key may use each capability, through its role or a grant; `capabilities.modelApi` also needs the model endpoints turned on.

</Tip>

# Models
Source: https://docs.tale.dev/platform/admin/governance/content-models

Use **Settings > Governance > Models** as an Admin or Owner to choose the models members start with and the models they may use. Defaults guide a choice; access rules enforce a restriction. Configure [provider credentials](https://docs.tale.dev/platform/admin/providers) first so the intended models are available.

## Set a default model

1. Under **Default models**, select **Add rule**.
2. Choose **Default** for the baseline, **Role** for a role, or **Team** for a team. Select the target when needed.
3. Choose a provider and model, then **Confirm**. Save the page's pending changes in the header.
4. Start a chat as a member of the target group with its model on **Auto**, and check the resolved model.

The default is used when there is no explicit model choice. A team rule takes precedence over a role rule, followed by the baseline default; when someone belongs to several teams with a rule, the first matching team rule in the table wins (see [How rules combine](https://docs.tale.dev/platform/admin/governance/policies-and-limits#how-rules-combine)). A default does not prevent someone from selecting another permitted model.

## Restrict model access

Under **Model access**, choose the mode and add rules for the users, teams, roles, or default scope you want to cover.

| Mode | Effect for a matching rule |
| --- | --- |
| **Allowlist** | Only listed allowed models may be used; a blocked model remains denied. |
| **Blocklist** | Models are permitted unless listed as blocked. |

Access resolves user rules before team rules, then role rules, then the default. Multiple matching team rules combine their lists; an explicit block still wins for that model. If no rule matches, the policy does not restrict that user. Add a baseline rule when you intend to cover everyone.

For chat, access is checked when a model is used, including an explicitly selected or pinned model. A configured default must also pass the check. If it is denied, automatic selection can fall back to an allowed model. The editor warns about a default that conflicts with access rules; resolve that warning so the intended default is actually used.

<Tip>
Test both cases after changing access: an allowed model should work and a denied model should be refused for the affected member. Testing only as the admin does not prove a role-specific rule.
</Tip>

### Let API keys call the organization's models {#model-endpoints}

**Model endpoints for API keys** lets people use the models this policy allows from their own tools, such as opencode, Claude Code, or scripts built on the OpenAI or Anthropic SDKs, with a personal API key over OpenAI- and Anthropic-compatible endpoints. It is off by default. Turn on the **Model endpoints for API keys** switch; the change saves at once.

- **Who may call.** Owners, Admins, and Developers through their role. Any other member only with the competence **Call models over the API**, granted under [Competences](https://docs.tale.dev/platform/admin/governance/competences).
- **Which models.** The chat models your provider credentials serve with an API key or an environment variable, narrowed by each credential's model allowlist. The access rules above apply to every call, for the person whose key sent it. The switch works independently of **Enable model access policy**: with that policy off, only the credentials' allowlists narrow the list.
- **What each call passes.** The budgets under [Policies and limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits) and the input guardrails under [Guardrails](https://docs.tale.dev/platform/admin/governance/guardrails#model-endpoints). The models' answers are not filtered.
- **Where it shows.** Each call is booked under the person and the key, as **Direct API** in [Usage analytics](https://docs.tale.dev/platform/admin/governance/usage-analytics).

<Frame caption="Governance > Models — Model endpoints for API keys, switched on.">

![The Model endpoints for API keys section on the Models page with its switch on, explaining that Owners, Admins, Developers, and members granted Call models over the API may use the organization's models from their own tools.](https://docs.tale.dev/images/platform/governance-model-endpoints.webp)

</Frame>

Turning the switch off refuses the next call with `403 MODEL_API_DISABLED`. [Use Tale from your editor or a script](https://docs.tale.dev/develop/use-tale-from-your-editor#model-endpoints) shows members how to connect their tools.

## Choose the image-reading model

A text-only agent needs help reading an image, such as a screenshot or scanned page. **Vision model** selects the model that describes it for the agent. An agent whose own model reads images reads them itself; the vision model still serves the image tools that scripts and coding agents call inside their sandbox, such as batch transcription of scanned pages, so every managed agent gets one when a reachable model exists.

Leave **Model that reads images** on **Automatic** to follow the available provider catalog. Tale prefers a recommended vision model and otherwise selects a reachable low-cost option. The text below the picker identifies the current choice and reason.

Pin a model if you need a stable choice. The picker offers models that can read images. If a pin later becomes unavailable, restore its provider access or explicitly choose **Automatic** and save. Tale does not silently switch a pinned model. Review the current choice after rotating credentials or changing model availability.

## Let agents generate images

**Image generation** lets [project agents](https://docs.tale.dev/platform/projects/project-agents) working on tasks and agent nodes in [automations](https://docs.tale.dev/platform/automations/concepts) create images, such as a cover for a report or a visual for a campaign. It is off until you turn it on. Chat never creates images: a member who needs one assigns a task to a project agent.

1. Turn on **Let agents generate images**. The switch saves at once.
2. Leave **Image model** on **Automatic**, or select a model and save the page's pending changes in the header.
3. Check the line below the picker. It names the model agents use.

<Frame caption="Governance > Models — image generation on, with a pinned image model.">

![The Image generation section with its switch on, the Image model picker set to OpenRouter · google/gemini-2.5-flash-image, and the line below it naming the model agents currently use.](https://docs.tale.dev/images/platform/governance-image-generation.webp)

</Frame>

**Automatic** uses the first model of a short recommended list that your provider credentials reach: Gemini 2.5 Flash Image, GPT Image 1 Mini, GPT Image 1, then FLUX.2 Pro. It considers OpenRouter and OpenAI credentials. The picker lists every image model your credentials can serve, including those of other compatible providers. A selected model stays fixed until you change it; if it becomes unavailable, Tale reports it and does not switch to another model. Turning image generation off keeps the selected model for the next time you turn it on.

While image generation is on and a model is available, every agent turn that starts on a runtime with Tale's MCP channel gets an image tool. Agents on other runtimes, and every agent while image generation is off, do not see the tool at all; [Choose an agent runtime](https://docs.tale.dev/platform/agents/harnesses) shows which runtimes have the channel. Turning image generation off also stops a running agent's next image request. An agent saves its images among its files, so a task's images appear with its deliverables and an automation step's images with the step's output.

Images come in three shapes: square, landscape at 3:2, and portrait at 2:3. An agent that asks for another shape, such as a 16:9 banner, gets the one with the same orientation. The image model decides the exact size in pixels, and the image tool tells the agent the size of each image it saved.

Each image is billed to your organization and counts against the person who started the run, like the rest of the run. One agent turn creates at most 16 images, one request at a time, and its images draw on the same allowance as the turn's model use: each image's cost comes out of what the model may still spend, and once the turn has used the allowance up, Tale refuses the next image. A budget limit that applies to that person refuses the image before the image model is called. Set cost or request limits for images under [Policies and limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits); [How usage is counted](https://docs.tale.dev/platform/admin/governance/usage-attribution) explains who each image counts against. For the policy file and custom image endpoints, see the [self-hosted provider reference](https://docs.tale.dev/self-hosted/configuration/providers#configure-image-generation).

## Provide a standard agent {#standard-agent}

Only Editors and higher roles can add agents to a project. So that a project without agents can still take on agent work, Tale offers the organization's **standard agent** there: anyone who can open the project can give it a task, Members included. It is on by default.

<Frame caption="Governance > Models — the standard agent, on, with its agent type and model chosen automatically.">

![The Standard agent section with its switch on, Agent type and Model both set to Automatic, an empty Instructions field showing Built-in instructions, and the line For you, it runs on Claude Code with Claude Haiku 4.5.](https://docs.tale.dev/images/platform/governance-standard-agent.webp)

</Frame>

- **Where it appears.** In a project without agents, **Assignee** offers **Standard agent**, and [Create task from chat](https://docs.tale.dev/platform/chat/basics#create-task-from-chat) assigns it for you. Tale sets it up in a project the first time someone chooses it there or hands a chat's task to that project; the project's **Agents** tab then lists it with the **Standard** badge, and [The standard agent](https://docs.tale.dev/platform/projects/project-agents#standard-agent) explains how it behaves there.
- **What it runs on.** With **Agent type** and **Model** on **Automatic**, Tale picks a recommended model the person starting the task may use under your [model access](https://docs.tale.dev/platform/admin/governance/content-models#restrict-model-access) rules, and runs it on Claude Code, or on the agent type a subscription model is bound to. The line at the end of the section names what it runs on for you. Choose an agent type or a model to use it for everyone, then save the page's pending changes in the header.
- **What it knows.** Its built-in instructions tell it to do what the task asks with the task's files and comments, deliver a requested document, presentation, spreadsheet or PDF as a task output, write in the task's language, and ask in a comment when the task is unclear. Text under **Instructions** replaces them.
- **What it may use.** The document skills `docx`, `pptx`, `xlsx` and `pdf` that are available to the project, and none of the connectors, platform tools or secrets an Editor can grant to other agents.

Every run starts with the settings in force at that moment; a running agent keeps the ones it started with. A chosen model stays in effect even when it becomes unavailable, and so does one that a person's model access denies: the standard agent then doesn't start for them and says why, and Tale doesn't switch to another model. Choose another model or **Automatic** and save. When no model a person may use can run it, it doesn't start for them either: add a credential under [AI providers](https://docs.tale.dev/platform/admin/providers), or check their model access.

Turn off **Provide a standard agent** to stop offering it; the change saves at once and keeps your choices. Projects without agents then offer no agent, and tasks already given to a standard agent can't start until you turn it back on. For the policy file, see the [self-hosted provider reference](https://docs.tale.dev/self-hosted/configuration/providers#configure-the-standard-agent).

## Choose the audio transcription model

**Audio transcription model** controls server transcription for audio and video attachments, the audio fallback for video links, and dictation in browsers without built-in speech recognition. Browser speech recognition uses its own service and keeps priority when supported.

<Frame caption="Audio transcription has its own organization-wide automatic or fixed model selection.">

![The Audio transcription model section shows Automatic and identifies the current server transcription model.](https://docs.tale.dev/images/platform/governance-content-models.webp)

</Frame>

An active default credential for OpenRouter also makes its dedicated speech-to-text models available here. Tale discovers them from the OpenRouter catalog. Check that the credential’s allowed models include your intended transcription model, then use **Automatic** or select that model explicitly.

1. Under **Model that transcribes audio**, leave **Automatic** selected to let Tale choose an available compatible model, or select a specific provider and model.
2. Save the page's pending changes in the header. Until you save, the selection is a draft; discard it to keep the saved setting.
3. Check the current model shown below the picker. Test a short recording before relying on the setup for a longer upload.

A model change applies to new transcription work; completed attachments keep their existing transcript. Uploading the same bytes again reuses completed work for the same transcription target, but transcribes them again when the target provider or model differs.

An explicit selection stays fixed. If that model becomes unavailable, Tale reports it and does not switch to another model. Choose another available model or **Automatic**, then save. If no compatible model is available, configure an active credential in [AI providers](https://docs.tale.dev/platform/admin/providers) and check the credential’s allowed models. A temporary failure to check the configuration calls for a retry, not a new model selection.

If unavailable server transcription prevents a member’s attempt to dictate or attach audio or video, a dismissible dialog explains the problem. Settings actions appear according to their access; otherwise, they are asked to contact an admin. A temporarily failed availability check can be retried. For deployment-managed selection and custom audio endpoints, see the [self-hosted provider reference](https://docs.tale.dev/self-hosted/configuration/providers#configure-audio-transcription).

## Diagnose an unexpected choice

Check the member's roles and teams, the explicit chat selection, the matching default, the access rule, and the provider credential's model list. A model appearing in a catalog does not establish that the organization has usable credentials for it. Spending and token caps still apply through [Policies and limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits).

# Data subject requests
Source: https://docs.tale.dev/platform/admin/governance/data-subject-requests

Use **Settings > Governance > Data subject requests** as an Admin or Owner to process a person's erasure request. Tale tracks the request, its approval and waiting period, and the result of the deletion process. Confirm the person's identity and the appropriate scope through your organization's process before filing.

<Frame caption="Governance > Data subject requests — the DSAR governance policy (cooling-off window, dual approval, daily limit) above the request receipts list with File request.">

![The Data subject requests governance page showing the cooling-off window, dual-approval toggle, and daily-limit fields above an erasure-requests table with one pending request — subject Jordan Blake, reason code consent withdrawn, 24 hours until execution and 29 days left on its SLA — beside a File request button.](https://docs.tale.dev/images/platform/governance-data-subject-requests.webp)

</Frame>

## File a request

1. Select **File request** and choose the **Subject** by name or email. Check that you selected the intended account.
2. Select the **Lawful ground** and write a **Reason narrative** that explains the request and references your internal case.
3. Type `ERASE` exactly, then select **File request**.
4. Open the receipt and check its status, deadline, and next required action.

Erasure permanently removes covered data; it is not a move to Trash. The receipt records the affected categories and counts, including chats, documents and uploads, preferences, feedback, notifications, usage, and audit-identifier scrubbing. The erasure also deletes the separate sandbox workspaces of the [agent runs the person started](https://docs.tale.dev/platform/projects/tasks#agent-runs-a-member-starts), even while work still runs in them, and the receipt counts them under **Sandbox workspaces**. A workspace counts only once the sandbox service has deleted its files, which can take a while for a large one. Until then, or while deleting them keeps failing, the receipt reads **Partial** with `sandboxWorkspaces` among its failed passes; choose **Retry** later, and the erasure completes once the files are gone. On Kubernetes, a workspace counts once its volume is handed to the cluster's storage provisioner; with a StorageClass whose `reclaimPolicy` is `Retain`, the volume's files stay until an operator removes the volume, although the receipt counts the workspace. A sandbox service or device that is not yet updated to this version cannot confirm the deletion, so the receipt stays **Partial** until it is updated.

Tasks that name the person as **Reviewer** lose that designation. A task review still waiting on them moves to the first eligible human fallback, the task creator or project creator, and that person is notified. On an archived task the review moves without a notification. Review decisions the person already made stay on record without their name.

## Check the policy before filing

| Setting | Effect |
| --- | --- |
| **Cooling-off window (hours)** | A waiting period of 0–72 hours before execution. Admins can cancel while waiting. Zero allows immediate execution once other requirements are met. |
| **Require dual approval** | A different admin must approve before the cooling-off window begins. The filer cannot approve their own request. |
| **Daily limit per admin** | Limits each admin to 1–50 filings per day. |

Only the Owner can change this policy. Stronger safeguards apply immediately; weaker safeguards are staged for 24 hours so any admin can cancel the change. Review the effective settings and any pending-change banner before relying on a new value.

## Follow the receipt

| State | What to do |
| --- | --- |
| Pending / awaiting approval | Check whether another admin must approve or the cooling-off window must finish. Cancel or reject if the request should not run. |
| Running | Wait for the category results; do not file a duplicate request. |
| Completed | Review the recorded counts and retain the receipt with your case. |
| Partial | Inspect the skipped categories and errors. Resolve the cause before retrying. |
| Blocked | Inspect the [legal hold](https://docs.tale.dev/platform/admin/governance/legal-hold). Covered data remains protected. The receipt names the hold that still applies; once the hold is released it says so, and the erasure continues only when you choose **Retry**. |
| Failed | Read the failure details. Use **Retry** when available; a watchdog timeout may require a new request. |
| Cancelled | No further execution is scheduled by this receipt. File a new request if the case must resume. |

An open receipt for a subject can prevent a duplicate filing. Work from that receipt rather than creating repeated requests. A retry blocked at initial filing must satisfy the current approval and waiting-period policy again. A receipt awaiting approval keeps the approval requirement captured when it was filed: turning dual approval off later does not release it.

## Manage the deadline

The list shows the tracked deadline and whether it is overdue. Use **Extend deadline** for a justified extension while it is still available: the application permits one extension before the original deadline expires and records the reason and admin.

The deadline is a tracking aid. Your organization remains responsible for assessing the request and communicating with the person. Completing a Tale receipt does not by itself confirm deletion from unrelated external systems or backups.

## Verify the outcome

Open the receipt's category counters, errors, and audit timeline. A completed action, a held category, and a failed pass have different outcomes; record those distinctions in your case. Review [audit logs](https://docs.tale.dev/platform/admin/governance/audit-logs) for the associated administrative events.

# Feedback analytics
Source: https://docs.tale.dev/platform/admin/governance/feedback-analytics

Use **Settings > Metrics > Feedback** as an Admin or Owner to review the feedback members submit in chat. Ratings tell you what people judged useful; their comments help explain why.

## Find the feedback you need

Choose a period, then narrow by feedback type, assistant, or model. The available windows are 1, 7, 30, and 90 days, plus all time; the initial view uses 7 days. Selecting an assistant or model in a breakdown filters the view. Clear the filter chips to broaden it again. Tale attributes each rating from the rated reply itself: the model and provider that answered, and the assistant the conversation runs under. The assistant is the one the conversation runs under when the rating is given, not necessarily the one that wrote the reply: after a conversation switches assistants, a rating on an earlier reply counts for the new assistant. A reply in a plain chat, outside any assistant, is listed as **Unattributed**.

Use **Comments only** to focus on written explanations. If no feedback appears, check the period and filters before concluding that nobody has rated a reply. Feedback is voluntary; an unrated answer is neither a positive nor a negative vote.

## Keep the signals separate

| Signal | What it tells you |
| --- | --- |
| Thumbs up/down | Whether a member found a particular reply helpful. An optional comment provides context. |
| Arena verdict | Which answer a member preferred in a specific pair, or whether the pair tied or both were bad. A verdict cast on two copies of the same model is counted under **Same model**, apart from the verdicts and the matchup table. |

Members can change or withdraw a rating. The dashboard reflects the current state, not a permanent count of every click. [Arena mode](https://docs.tale.dev/platform/chat/arena-mode) explains how members compare two answers.

## Compare results fairly

Read the number of ratings alongside the helpful ratio. One positive vote is weaker evidence than repeated feedback across the tasks a model actually handles. Compare similar periods and tasks before attributing a change to a model or an assistant configuration.

Use the assistant and model tables to locate the change, the trend to find its timing, and **Recent feedback** to read comments. For arena results, compare the same model pairing; a win against one model does not establish superiority over every model.

<Tip>
Pair this review with [usage analytics](/platform/admin/governance/usage-analytics). A model can cost less per request while requiring more retries to produce a useful answer.
</Tip>

## Understand partial results

Large windows can reach the aggregation limit of 50,000 entries. If Tale shows a partial-results notice, narrow the period before drawing conclusions. Retention and deletion also affect which ratings and comments remain available; this view is not a permanent archive of member feedback.

# Guardrails
Source: https://docs.tale.dev/platform/admin/governance/guardrails

Use **Settings > Governance > Guardrails** as an Admin or Owner to control how chat text is checked before and after a model call. Enabled layers run in order: content safety, personal-data detection, then external moderation. Start with one clear rule and verify its effect before broadening the policy.

<Frame caption="Governance > Guardrails — the three filter-layer status cards (content safety, PII detection, moderation provider) above the recent-events log.">

![The Guardrails governance page showing three status cards — Content safety on with two categories for input and output, PII detection on in mask mode, and the Moderation provider not configured — above a recent-events feed reporting no events yet and the organization's custom instructions.](https://docs.tale.dev/images/platform/governance-guardrails.webp)

</Frame>

## Add a content rule

1. Under **Content safety**, choose whether to check **User input**, **Model output**, or both.
2. Select **Add category**, give it a recognizable **Label**, and choose its **Mode**.
3. Add the words or phrases to detect, one per line. You can import a text list; review it before applying it.
4. Save the category, enable the intended category and layer, then save the page's pending changes.
5. Test with synthetic text containing a match and with ordinary text that should pass. Check **Recent events** and the visible chat outcome.

| Mode | What happens on a match |
| --- | --- |
| **Flag** | Records the detection and allows the message. Useful while tuning a rule. |
| **Mask** | Replaces matched text with the configured placeholder. |
| **Block** | Refuses the message. |

When several categories match, block takes precedence over mask, then flag. Word matching ignores case. Check variants and false positives that matter for your languages; one successful test does not establish complete coverage.

## Protect personal data

**PII protection** detects configured patterns such as email addresses, phone numbers, and identifiers. Select the relevant built-in types and any custom patterns, then choose the intended behavior.

Masking removes matched values from the text sent onward. In a chat, the masked text is also what Tale stores and shows as the message; the original wording is not kept. Blocking refuses a match. Tokenization replaces detected values with indexed tokens for the model and restores them in its reply. Tokenization is therefore useful for processing with reduced exposure, but it is not a promise that the final reply will contain no personal data.

A built-in identifier that is digits only, such as a Swedish passport number or a Ukrainian tax ID, is recognized only next to a word that names it, for example `passnummer` or `ІПН`. Order numbers, compact dates, and build numbers pass through. Each detection in **Recent events** names the pattern that fired, such as `se-passport`.

Test the formats you actually use with synthetic values. Pattern detection can miss unusual formats and can flag ordinary text. Check input and output separately.

## Add external moderation

The moderation layer sends text to a configured classifier, such as OpenAI, Azure, Perspective, or a custom endpoint. Configure its credentials, categories, and actions, and choose the directions it should inspect.

Decide what should happen if the provider is unavailable: fail-open allows the message, while fail-closed refuses it. Review provider errors and circuit-open events when unexpected refusals or unfiltered messages occur. Enabling this layer introduces another service that processes the text; use the provider and endpoint approved for your organization.

## Set organization instructions

**Custom instructions** adds organization instructions ahead of the chat assistant's instructions and ahead of every agent's own: project agents working tasks and agent nodes in automations. Members cannot edit this organization policy. Use it for shared behavior and terminology; use access rules and filters for restrictions that must be enforced independently of a model following prose instructions.

## Guardrails on the model endpoints {#model-endpoints}

When your organization turns on [model endpoints for API keys](https://docs.tale.dev/platform/admin/governance/content-models#model-endpoints), the input side of these guardrails also judges every request sent to them. Content safety, PII protection, and the moderation provider read every text the request carries before Tale passes it to the model: system and developer instructions, the person's and the assistant's turns, tool calls, tool results and tool definitions, and documents given as text. The caller writes every one of them, so none is trusted more than another:

- A block refuses the request with `400 MODEL_API_GUARDRAIL_BLOCKED`, and nothing reaches the model.
- A mask replaces the match, and the model receives the masked text.
- Tokenization cannot be honoured, because Tale relays the model's answer unchanged and cannot restore the values into it. While PII protection is on in **Tokenize** mode, every request is refused with `403 MODEL_API_GUARDRAIL_UNSUPPORTED`; choose **Mask** or **Block** if members use the model endpoints.
- A moderation provider that fails under fail-closed refuses the request with `503 MODEL_API_GUARDRAIL_UNAVAILABLE`, and so does a guardrail setting Tale cannot read.
- While a guardrail is on, a request with more than 2 MB of text is refused with `413 MODEL_API_TEXT_TOO_LARGE`.

Output is not filtered there: rules that check **Model output** do not apply, and the model's answers, streamed or not, pass unchecked, as do images and documents that are not text. Custom instructions are not added either; the model receives the request as the caller's tool sent it. Detections appear under **Recent events** like chat detections, each recorded under `model-api:` followed by Tale's own ID for the request, with the `X-Request-Id` the caller received kept beside it. Because tools resend the whole conversation with every request, Tale reuses its verdict on a text it judged within the last few minutes and records a detection once rather than on every resend.

## Review and tune

**Recent events** shows the latest 50 detections, blocks, and provider errors. Filter by layer or outcome and inspect category, direction, and time. Raw matched text is not stored in these events, so a row explains the detection without reproducing the sensitive match.

If a rule is too broad, adjust its category or patterns and repeat the synthetic tests. If a detection is absent, check that the layer, category, and intended direction are enabled. How long events stay depends on the **Chat filter events** category of the [retention policy](https://docs.tale.dev/platform/admin/governance/policies-and-limits). The category is off by default, and events are kept until an admin enables it. While it is enabled, scheduled cleanup deletes events older than its period plus the deletion grace period, up to 50,000 per night; a larger backlog, such as months of events when the category is first enabled, is cleared over several nights. Recent events and the guardrail figures under **Settings > Metrics > Chat health** only show the events still kept: if the period plus the grace period is shorter than 30 days, the older part of a 30-day view stays empty.

A [legal hold](https://docs.tale.dev/platform/admin/governance/legal-hold) protects events from cleanup: an organization hold keeps every event, and a member hold keeps the events raised in that member's chats. An event whose chat was permanently deleted before the hold has no owner left to protect it and is not kept.

# Legal hold
Source: https://docs.tale.dev/platform/admin/governance/legal-hold

A legal hold preserves covered data while a matter is open. Admins and Owners manage holds under **Settings > Governance > Legal hold**. Place the hold while the data still exists: it cannot recover records that were already permanently deleted.

<Frame caption="Governance > Legal hold — the active-holds table with the Place legal hold action above the dual-control release-requests queue.">

![The Legal hold governance page showing one active hold — a User hold on marta.vogel, placed by Alex Rivera under the Northstar contract matter — beside a Place legal hold button, above the Pending approval and Approved release-request queues, both reading No release requests.](https://docs.tale.dev/images/platform/governance-legal-hold.webp)

</Frame>

## Place a hold

1. Select **Place legal hold**.
2. Choose the target: a user as custodian, or the whole organization. For a user hold, select the intended member.
3. Enter a reason that lets another admin understand what must be preserved. Link the hold to a matter if you are tracking a case.
4. Confirm, then check the target and reason in **Active holds**.

A placed hold takes effect immediately. Covered data is protected from retention and erasure; attempts to delete held content are refused. Use your organization's preservation process to decide the correct scope.

## Organize holds by matter

Use **Create matter** to group related holds under a case name and number. The matter's linked-hold count helps you check that the intended custodians are covered.

Closing a matter requests the release of its linked holds. It does not release them immediately: each request still needs the separate review below.

## Release a hold

1. On the active hold, choose **Request release** and record why preservation is no longer needed.
2. A different admin reviews the request and chooses **Approve** or **Reject**. The requesting admin cannot approve their own release.
3. After approval, check the cooldown shown in **Release requests**. The hold remains effective while the request awaits that cooldown.
4. Check **Release history** for the completed outcome and **Active holds** to confirm which holds remain.

Placing a hold takes one admin; releasing it uses two-person review and a delay. Approval is therefore not the same as completed release.

## Understand blocked deletion

A hold can block a person's erasure request, deletion of their covered chats or documents, and deletion of a folder that contains held files. Any active organization or member hold also prevents deletion of the organization itself.

If a deletion fails, inspect the relevant hold instead of repeatedly trying the action. Releasing one hold does not remove another overlapping hold, and release allows the applicable retention or erasure process to continue. An erasure receipt the hold blocked does not resume on its own: open it under Data subject requests and choose **Retry**.

## Review related requests

Use [Data subject requests](https://docs.tale.dev/platform/admin/governance/data-subject-requests) to inspect an erasure receipt blocked by a hold, and [audit logs](https://docs.tale.dev/platform/admin/governance/audit-logs) to investigate recorded hold actions. The [retention policy](https://docs.tale.dev/platform/admin/governance/policies-and-limits) determines normal cleanup after preservation no longer applies.

# Operations metrics
Source: https://docs.tale.dev/platform/admin/governance/operations-metrics

Beside [Usage](https://docs.tale.dev/platform/admin/governance/usage-analytics) and [Feedback](https://docs.tale.dev/platform/admin/governance/feedback-analytics), **Settings > Metrics** holds four dashboards for Owners and Admins. **Chat health** shows whether assistant replies fail or are blocked, **Harness turns** whether agents working in the sandbox finish their turns, **Automations** how live automation runs end, and **Projects** how one project's tasks move. Each dashboard recomputes its figures from the records Tale still keeps for the period you choose.

<Frame caption="Settings > Metrics > Chat health: the turn counts and rates, the daily outcome chart, and the breakdown by agent and model.">

![The Chat health dashboard for the last seven days, reporting seven assistant turns with a 0% error rate, a 0% blocked rate and no guardrail events, a bar of seven successful turns on the current day, and a breakdown that attributes every turn to plain chats and splits them between two models.](https://docs.tale.dev/images/platform/metrics-chat-health.webp)

</Frame>

## Check chat health

Open **Chat health** when members report failed or refused replies. Choose 1, 7, or 30 days under **Filter**; the page opens on 7 days.

The cards count **Assistant turns**, the replies the assistant produced in the period. **Error rate** is the share of those turns that ended in an error, and **Blocked rate** the share Tale refused to answer, for example because a guardrail blocked the message. **Guardrail events** counts the detections in the period and how many of them blocked a message.

**Turns over time** splits each day's turns into **Successful**, **Errors**, and **Blocked**, so you can see when a problem started. **Breakdown** gives each agent's and each model's share of the turns; a reply in a plain chat, outside any agent, counts as **Unattributed**.

Under **Errors**, **By error type** groups the failures, for example **Rate limited**, **Model not found**, **Credit exhausted**, or **Usage limit reached**, and **Recent errors** lists the latest ones with their model and agent. The type points to the next check: a provider credential or its quota under [AI providers](https://docs.tale.dev/platform/admin/providers), a model's availability under [Models](https://docs.tale.dev/platform/admin/governance/content-models), or a budget rule under [Policies and limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits).

**Guardrails** breaks the guardrail events down by kind and by filter and charts detections, blocks, and filter errors per day. Those events come from the filters on [Guardrails](https://docs.tale.dev/platform/admin/governance/guardrails) and cover only the events retention still keeps.

## Watch harness turns

A harness turn is one piece of work an agent harness, such as Claude Code or Codex, carries out in the sandbox: a [project agent](https://docs.tale.dev/platform/projects/project-agents) working on a task, or an agent step in an automation. **Harness turns** shows whether those turns finish. Choose 7, 30, or 90 days; the page opens on 30 days.

The cards report **Total turns**, the **Success rate**, the **Timeout rate**, the **p95 duration**, which 95% of the turns finished within, and the turns **Stopped by user**. **By harness** repeats the turns, success rate, and timeouts for each harness, so a rising timeout rate points to the harness it comes from. [Harnesses](https://docs.tale.dev/platform/agents/harnesses) explains how each one runs, and [Sandboxes](https://docs.tale.dev/platform/admin/sandboxes) where their capacity is set.

## Follow automation runs

**Automations** counts live runs of your organization's automations; test runs appear on each automation's **Runs** tab but not here. Choose 7, 30, or 90 days; the page opens on 30 days. Each card compares its figure with the period of the same length before it.

**Success rate** is the share of finished runs that succeeded: runs that failed or were stopped count against it, while queued, running, and waiting runs do not count yet. **Avg duration** averages the finished runs, and **Failed runs** counts the failures. **Runs over time** shows the daily volume, **Status breakdown** the outcome of every run in the period, and **Top automations** the ten automations with the most runs, with their success rate, average duration, failures, and last run. Open a failing automation's **Runs** tab to find the node that failed; [Read automation runs](https://docs.tale.dev/platform/automations/execution-logs) walks through it.

## Review a project's delivery

**Projects** shows one project at a time: choose it under **Select a project**. If the organization has a single project, it is selected for you. Choose 7, 30, or 90 days; the page opens on 30 days.

| Figure | What it measures |
| --- | --- |
| **Completed** | Tasks that reached Done in the period, split by current assignee into tasks assigned to an agent and all other tasks. |
| **Avg cycle time** | The average time from a task's first move to In progress until it reached Done. A task that skipped In progress has no cycle time. |
| **Intervention rate** | Changes requested in review plus escalations (questions that agent steps in automations asked people), per agent run started in the period. |
| **Spend** | The cost of the project's agent runs, with how many started and how many failed. |

The charts below show the open tasks by status at the end of each day, the tasks created and completed each day, the cycle-time trend, each day's completions split into **Agents** and **Humans**, and the daily spend. That split, like the one under **Completed**, goes by each task's assignee as it is now, not by who completed the task. A task assigned to an agent counts for agents, although a person moved it to Done; a task assigned to a person, an automation, or no one counts for humans. Past days change too: when a task is later assigned to an agent or loses its agent, for example because the agent was deleted, its completion moves to the other side. A task created directly in Done or Cancelled gets a completion timestamp at creation, but daily completion throughput counts status-change events only, so that creation is not counted as a completion event.

A rising intervention rate with a steady number of runs means people are sending more work back or agents are asking more questions. Escalations come from agent steps in automations working on the project, and each one counts on the day it is raised, whether or not anyone answers. For work sent back, read the tasks in review before changing an agent's instructions under [Project agents](https://docs.tale.dev/platform/projects/project-agents); for questions, read the runs of the automation that asked them, as [Read automation runs](https://docs.tale.dev/platform/automations/execution-logs) explains.

## Read the figures correctly

- Every dashboard works from the records Tale keeps. Retention settings and deletions shorten the history, so an empty period can mean the records are gone rather than that nothing happened.
- A busy period can exceed what one pass reads: Chat health, Harness turns, Automations, and Projects each count at most the 5,000 most recent records of a kind in the period. When Tale shows a notice about recent activity, narrow the period before drawing conclusions.
- Cost figures are recorded application usage, not a provider's invoice; [Usage analytics](https://docs.tale.dev/platform/admin/governance/usage-analytics) explains the difference.

# Policies and limits
Source: https://docs.tale.dev/platform/admin/governance/policies-and-limits

Use **Settings > Governance > Policies & Limits** as an Admin or Owner to control resource use and data handling. Choose the section that matches the problem: spending, uploads, retention, feature availability, the notice members see in chat, who may share skills with the whole organization, or who receives inbound conversations.

<Frame caption="Governance > Policies & Limits — the budget-rules table above the upload policy and retention controls.">

![The Policies and Limits governance page showing three monthly budget rules — one for the entire organization, one default for all users, and one for the developer role, each capping tokens, cost, and requests — above the upload-policy fields for allowed file types, sizes, and volume.](https://docs.tale.dev/images/platform/governance-policies-limits.webp)

</Frame>

## Add a spending budget

1. Under **Budget rules**, select **Add rule**.
2. Choose the scope and its target. Use a role for a group such as Editors, a team for a shared workload, a user for an individual, an API key for one credential, or the organization for a shared ceiling. The API key list offers every active key held by a member of the organization, named with its owner, so you can cap one person's script or coding tool.
3. Select a daily, weekly, or monthly period. Enter at least one positive token, cost, or request limit. Cost is entered in USD; an empty field leaves that dimension uncapped by this rule.
4. Optionally set **Warning threshold (%)** between 0 and 100 to warn before the cap is reached.
5. Select **Confirm**, save the pending page changes, and check the saved rule's scope, target, period, and limits.

For example, a monthly role rule can give Editors a USD 50 personal spending limit, while an organization rule caps everyone's combined spend at USD 500. These are example amounts, not recommended defaults.

A rule stays in the table after its API key stops working. **Target** still names the key and its owner, with a status: **Expired** while the expired key is still stored, **Disabled**, **Revoked** when this organization recorded its revocation, or **Former member** when the owner has left the organization. **Unavailable** means the key is known but no longer stored, without a recorded cause; expiry cleanup can produce this state. **Unknown key** marks a key this organization has no record of. Remove such a rule, or edit it and choose an active key.

Budgets apply to new billable work, including chat, voice output, managed agent runs, the images agents generate, and calls to the model endpoints. Tale checks every chat request before it runs — a sent message, a regenerated or edited reply, both sides of a model comparison, a message waiting for an attachment, and a send through the REST API — and refuses it once a cap that applies is reached, naming the cap and when it resets. Replies still being written hold what they may spend, so requests sent at the same moment cannot pass a nearly reached cap together. An agent's image request is checked the same way before the image model is called: while its images are being made it holds an estimated cost, and the check also counts what the agent's own run may still spend on its model. Each image counts as one request. Image generation needs cost or request limits because its usage is not measured as text tokens. A token limit counts input and output tokens, and input includes the part of a prompt that a provider read from or wrote to its cache. That part is priced differently from other input, so an agent that reuses a long prompt can reach a token limit while its cost stays low. Investigate warnings in [Usage analytics](https://docs.tale.dev/platform/admin/governance/usage-analytics).

## Understand which caps apply

Personal limits resolve each dimension from the most specific rule that defines it: user, then team, role, and default. When someone belongs to several teams with a rule, the strictest of those caps applies to them personally. Organization limits apply in addition. A team budget also caps the combined usage of the team's current members, even when a member has a more specific personal rule: a new member's usage in the current period counts at once, and someone who leaves no longer counts. API-key limits independently cap requests authenticated with that key, and those requests' usage counts toward the key; they do not cap unrelated in-app work.

Managed agent runs count against the person who started them. A run you start from a task, a comment, the REST API, or the MCP endpoint uses your personal and team caps, and a run started with an API key also counts toward that key. Runs that a schedule, a webhook, or an event started have no person behind them: only the organization's limits apply to them, and [Usage analytics](https://docs.tale.dev/platform/admin/governance/usage-analytics) lists them under **Automations (triggers)**. [How usage is counted](https://docs.tale.dev/platform/admin/governance/usage-attribution) explains the rule for every kind of work.

A call to the [model endpoints](https://docs.tale.dev/develop/use-tale-from-your-editor#model-endpoints) is checked like a chat request. Before it runs, Tale works out its worst case, the estimated prompt plus the most output it may produce at the model's catalog price, and refuses it with `429 BUDGET_EXCEEDED` when that worst case does not fit what is left under a cap that applies to the key holder or to the key. While the call runs, its worst case is held against those caps. Afterwards, the cost the model gateway measured is booked under the person and the key, and each call counts as one request.

If a request is refused unexpectedly, check all applicable caps and their periods. Increasing one personal limit does not remove an organization, shared-team, or API-key ceiling.

Members can check their own standing under [Settings > Usage](https://docs.tale.dev/platform/member/preferences#usage-limits). It lists each personal, team, and organization cap that applies to them with its current usage and next reset, without showing the rules themselves.

### How rules combine {#how-rules-combine}

Every policy here and under [Content & models](https://docs.tale.dev/platform/admin/governance/content-models) reads its rules the same way. The most specific scope wins: a user rule before a team rule, a team rule before a role rule, and a role rule before the default. When a person belongs to several teams that carry a rule, the team rules combine by what they are:

- A limit, such as a budget cap or a context-window cap, combines to the strictest value. Joining a lenient team never raises anyone's cap.
- A permission list, such as model access, combines as the union of the allowed models; a block in any of the rules still wins for that model.
- A single choice, such as the default model, follows the order of the rules in the table: the first matching team rule wins.

## Control uploads

**Upload policy** sets allowed and blocked extensions, allowed MIME types, maximum file size in MB, and total volume per user in GB. Use the types your workflows need and test an allowed file and a rejected file after saving.

A filename extension, content type, and size are separate checks. If an upload fails, compare all three with the policy. Check existing per-user storage when individual files fit but further uploads are refused.

## Set retention and recovery time

Under **Retention policy**, select **Edit** and configure the categories your organization needs. The summary shows effective values, including disabled categories and temporary-file cleanup. Disabling a category's scheduled retention does not prevent an explicit deletion or erasure request.

Check the deployment's minimum and maximum bounds before changing a period. Changes that require review or a delay appear as proposals or pending changes; read their effective time instead of assuming they apply immediately.

The deletion grace period is the recovery window for supported soft-deleted records. A positive value leaves time to restore them in [Trash](https://docs.tale.dev/platform/admin/governance/trash); zero permits immediate permanent cleanup. Not every category has a restore path. A [legal hold](https://docs.tale.dev/platform/admin/governance/legal-hold) protects covered data from cleanup.

For self-hosted deployments, [Retention configuration](https://docs.tale.dev/self-hosted/configuration/retention) explains the operator controls and category-specific behavior. Do not infer an archive guarantee from a disabled policy or a displayed period alone.

## Review feature controls

Feature controls include scoped context-window limits and the organization-wide voice-output switch. A context limit controls how much context can reach an AI reply; it is different from a spending budget. A limit below 200,000 tokens also applies to Claude Code agent runs, as set for the person who started the run: the agent compacts its conversation into a summary before it outgrows the limit, and Claude Code treats any limit below 100,000 tokens as 100,000. Turning off voice output prevents members from enabling it through their own defaults or conversation choices.

The custom-instructions default switch stores the organization default for members’ personal instructions: while it is on, every member’s custom instructions apply to their chat replies unless they turned the feature off themselves under **Settings > Preferences**. Organization-wide mandatory instructions are a separate setting under [Guardrails](https://docs.tale.dev/platform/admin/governance/guardrails).

## Show a confidentiality notice in chat

**Confidentiality notice** adds a short line under the chat message field for every member of your organization, such as a reminder not to share sensitive data. It stays off until you turn it on.

1. Turn on the **Confidentiality notice** switch. Members see the notice in chat right away, in their language; open chats update without reloading.
2. Optionally enter your own text in the language tabs **English**, **Deutsch**, and **Français**, up to 280 characters per language. Save the pending page changes.

<Frame caption="Governance > Policies & Limits — the confidentiality notice switched on, with English text, a German translation, and French still untranslated.">

![The Confidentiality notice section with its switch on and the English tab selected, asking members not to paste client names, contract values, or unreleased project codenames into chat; the Français tab is marked untranslated.](https://docs.tale.dev/images/platform/governance-confidentiality-notice.webp)

</Frame>

Members see the text for their language. A tab marked **untranslated** has no text of its own: members reading that language see your English text, or the default notice when English is empty too, and the empty field previews that text. A red dot marks a language whose text is too long, and saving stays unavailable until you shorten it. Turning the notice off keeps your texts for when you turn it on again.

The notice is a reminder only. It does not check, block, or change what members send. To act on sensitive content, configure [Guardrails](https://docs.tale.dev/platform/admin/governance/guardrails).

## Decide who shares skills with everyone {#skill-sharing}

By default, every member can share a skill with the whole organization. Use **Skill sharing** to reserve that for fewer people: choose who may **Share skills with the organization**, then save the pending page changes.

- **Every member** keeps the default.
- **Editors and above** admits Editors, Developers, Admins, and Owners: the roles that equip agents.
- **Owners and admins only** admits Owners and Admins.

<Frame caption="Governance > Policies & Limits — Skill sharing decides who may share a skill with the whole organization.">

![The Skill sharing section with Share skills with the organization set to Every member, and the hint that Owners and Admins always may and one more member can be granted Publish skills to the organization under Competences.](https://docs.tale.dev/images/platform/governance-skill-sharing.webp)

</Frame>

Owners and Admins can always share with everyone. To let one more person do it without a higher role, grant them **Publish skills to the organization** under [Competences](https://docs.tale.dev/platform/admin/governance/competences).

Everyone else can still create skills and share them with their own teams. They cannot create a skill for the whole organization, widen one of theirs to **Organization**, or change an organization-wide skill in place. They can narrow a skill of theirs to their teams, with other changes in the same save, or delete it. The rule applies in the skill editor, to zip and folder uploads, to automation packages that carry skills, and to the REST API. Each refusal appears in the [audit logs](https://docs.tale.dev/platform/admin/governance/audit-logs) as **Skill publishing refused**.

A stricter setting does not narrow skills that are already shared with the organization. To review them, open **Settings > Skills**, choose **Filter > Visibility > Organization**, and check the **Created by** column. Narrow or delete the ones that should not stay shared with everyone.

<Note>

A managed configuration release installs its skills as the member who deploys it. Before you choose a stricter setting, make sure that member can still share with everyone, through their role or the competence; otherwise the next release that carries an organization-wide skill is refused.

</Note>

## Conversation routing

Use **Conversation routing** to assign new conversations by where they arrive. Add a rule, set its fields, then save it:

- **Arrives on**: **Any mailbox**, one mailbox by its name, or an API app. An API app is listed once it has synced a conversation.
- **Sent to**: the address the conversation was sent to. It is required for **Any mailbox**, optional for one mailbox, and absent for an API app. Address matching ignores case.
- **Route to**: a team, a person, or both.

A rule for `support@example.com` also catches plus-addressed mail such as `support+billing@example.com`, and a rule for the tagged address wins for that address. When several rules match, the most specific one applies: a mailbox with its exact address, then a mailbox with the base address, then an address on any mailbox, then a mailbox alone.

A team assignment makes the conversation visible to that team's members; a person assignment makes it visible to that person. When both are set, either membership grants visibility. Unassigned conversations are for Admin and Owner triage.

Rules apply when a new conversation arrives. They do not reassign an existing conversation when a reply joins it. If a rule points to a deleted person, team, or mailbox, the conversation still arrives without that routing assignment. Test with a new message and verify the resulting assignee.

## Configure sign-in limits separately

Password requirements, sign-in attempt limits, session idle timeout, and [two-factor policy](https://docs.tale.dev/platform/admin/two-factor-authentication) live under **Settings > Governance > Security**. An organization idle timeout can tighten the deployment's limit. For trusted-header authentication, coordinate session expiry with the proxy or identity provider, which can authenticate the member again.

# Trash
Source: https://docs.tale.dev/platform/admin/governance/trash

Use **Settings > Governance > Trash** as an Admin or Owner to recover records that are still stored after soft deletion. Permanent deletion cannot be undone here, and not every deletion in Tale goes through Trash.

## Restore a record

1. Open Trash and use **Filter > Category** to narrow the list, or leave it unfiltered to see all supported types.
2. Check the record's name, owner, type, and deletion time. These help distinguish records with similar names. A chat is listed under its title; the answer discarded in an [Arena](https://docs.tale.dev/platform/chat/arena-mode) comparison keeps the title of its conversation.
3. Select **Restore** on the row and review the confirmation.
4. For a retention-expired record, type `restore` exactly. Confirm the action, then look for the record in its original location: for example, its chat list or Knowledge.

The restored row disappears from Trash. Tale records the restoration in the audit log. If the row is no longer available, refresh the list: cleanup may already have permanently removed it.

## Understand the status

| Status | Meaning |
| --- | --- |
| **Trashed** | The record was soft-deleted and is still available for restoration. |
| **Expired** | Retention policy expired the record. Restoring it overrides that policy, so confirmation requires the word `restore`. |

**Expired** does not mean the recovery window has already ended. Retention marks records expired when their grace window starts; permanent cleanup follows once that window elapses.

The category filter lists the record types that pass through Trash: chats, documents, temporary files, message feedback, contacts, and external conversations. A chat's earlier versions travel with it: they are trashed and restored together with the chat and never appear as rows of their own. Other data, such as automation runs, usage records, audit records, and chat-filter events, is deleted directly or as part of a parent record's cleanup and has no restore action here.

## Check the recovery window

The organization's retention policy sets the grace period. With a positive grace period, supported expired records remain recoverable until cleanup removes them. A grace of zero allows immediate permanent cleanup. Check the active policy under [Policies and limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits) instead of relying on an assumed number of days.

An empty Trash means there are no recoverable records in the current view. It does not prove that nothing has ever been deleted. Clear category filters before concluding a record is absent.

Trash never shows a failed read as empty. If the list cannot be loaded, an alert takes the table's place and offers **Try again**, instead of the empty state. If records are listed but the next ones or a refresh cannot be loaded, a notice above the list says so and offers **Try again**, and the count under the list no longer claims to show all records.

## Account for legal holds

A [legal hold](https://docs.tale.dev/platform/admin/governance/legal-hold) prevents covered data from being deleted by retention or erasure. It preserves data that still exists; it cannot recover data already permanently deleted. Check the hold and retention history when investigating why an expected record did or did not enter Trash.

# Usage analytics
Source: https://docs.tale.dev/platform/admin/governance/usage-analytics

Open **Settings > Metrics > Usage** as an Admin or Owner to understand which workloads consume AI resources. Start with the reporting period, then use the breakdowns to investigate a change in cost or volume.

<Frame caption="Settings > Metrics > Usage: the totals, the token chart, and the top assistants for the last 30 days.">

![The Usage metrics page for the last 30 days, reporting 14 requests, 448 tokens, a recorded cost of $0.00, and one active user, with a token chart whose only bar is the current day split into input and output, above a Top assistants table that lists the assistant and chat-title generation.](https://docs.tale.dev/images/platform/metrics-usage.webp)

</Frame>

## Investigate a usage increase

1. Open **Filter** and choose a **Period** of 7, 30, or 90 days. The initial view covers 30 days.
2. Compare total requests, total tokens, total cost, and active users. More requests and larger replies have different causes.
3. Choose the chart's metric and granularity in the filter menu to see when the change happened.
4. Inspect **Top assistants**, **Top models**, and **Per-user usage**. Select an assistant or model breakdown to narrow the view; remove its filter chip to return to the wider view.

Assistant names can include supporting work such as chat-title generation. A request count therefore does not always equal the number of messages members sent. Voice synthesis has its own **Top voice models** table.

**Per-user usage** attributes every request to a person: the member who sent the chat message or started the agent run, including runs started through the REST API or the MCP endpoint. Runs that a schedule, a webhook, or an event started have no person behind them. Their usage appears as one row named **Automations (triggers)**, which does not count as an active user. In **Top assistants**, a project agent and an automation each appear under their name. [How usage is counted](https://docs.tale.dev/platform/admin/governance/usage-attribution) explains the rule for every kind of work.

## Read cost alongside tokens

The dashboard uses recorded usage and metering information. Input and output tokens are separate, and services such as voice output or image generation may have different billing units. A token total alone cannot explain every cost. Input tokens include the part of a prompt that a provider read from or wrote to its cache. That part is priced differently from other input, so a run that reuses a long prompt can show many input tokens for a small cost.

An image an agent generated appears under its image model in **Top models** and under the agent or automation in **Top assistants**, as one request per image and without tokens. Its cost is the charge OpenRouter reported, or for OpenAI the list price of the image tokens OpenAI reported. A request the provider billed without returning a usable image counts the same way.

Treat the displayed cost as recorded application usage, not an invoice from your provider. Provider pricing, subscriptions, credits, and unmetered calls can affect how it compares with the bill. A displayed zero does not prove that a provider charged nothing.

## Respond to a budget warning

Use the same period and affected workload when investigating a budget notice. Find the user, assistant, or model behind the increase, then decide whether to change the workflow, choose another model, or adjust a cap under [Policies and limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits).

Compare [feedback analytics](https://docs.tale.dev/platform/admin/governance/feedback-analytics) before making a model change solely for cost: lower spend is useful only if the results still meet the task.

## Understand missing history

Charts reflect the usage records Tale still retains. The organization and deployment retention settings determine the available history; there is no universal 365-day guarantee. Check the selected period, filters, and usage-ledger retention if expected activity is missing.

If the metrics cannot be loaded, the page says so and offers **Try again** instead of showing zeros or empty tables. The period and filters you chose stay as they are. If a refresh fails, the figures already shown stay, with a note that they may be out of date. If **Try again** keeps failing, ask the deployment operator to check that Tale's services are running.

# How usage is counted
Source: https://docs.tale.dev/platform/admin/governance/usage-attribution

Every AI request Tale makes for your organization is recorded once, against one person, and measured against the [budget rules](https://docs.tale.dev/platform/admin/governance/policies-and-limits) that apply to that person. This page explains who that person is for each kind of work, which limits the work counts against, and where you find it in [Usage analytics](https://docs.tale.dev/platform/admin/governance/usage-analytics). Members see their own share under [Settings > Usage](https://docs.tale.dev/platform/member/preferences#usage-limits).

## What counts as usage

Tale records a request whenever a model or a metered service runs for your organization: a chat reply, including a regenerated or edited one and both sides of a model comparison; the short model call that names a new chat; a turn of a managed agent working on a task or inside an automation; an image such an agent generates; voice output; the transcription of an uploaded recording; a metered connector call; and a call to the model endpoints with an API key. Each record carries the tokens or units used and the cost estimated from the provider's list price at that moment; for a model endpoint call, it is the cost the model gateway measured.

## Who a request counts against

The rule is the same everywhere: a request counts against the person who asked for the work. The door the request came through, such as the app, the REST API, the MCP endpoint, or the model endpoints, changes nothing about who that is.

| Work | Counts against | Also counts toward | Appears in Usage analytics as |
| --- | --- | --- | --- |
| A chat reply, or the title of a new chat | The member who sent the message | The API key, when the message was sent through the REST API | The assistant used; a title under `thread-title` |
| An agent run on a task | The member who started the run from the task, or with a comment or a task description that mentions the agent; for a run another agent or an automation step started, the member that agent's or automation's run counts against | — | The agent's name under **Top assistants** |
| An automation run someone started | The member who started it from the run list, the builder, a chat, a task, the REST API, or the MCP endpoint | The API key, when the run was started with one | The automation's name under **Top assistants** |
| An automation run a trigger started | Nobody: a schedule, a webhook, or an event has no person behind it | — | The **Automations (triggers)** row under **Per-user usage** |
| A project agent's run a schedule began, or one another agent started for such a run | Nobody, as for the schedule's own run | — | The **Automations (triggers)** row under **Per-user usage**, and the agent's name under **Top assistants** |
| An image an agent generates | The person the agent's run counts against: its starter, or nobody for a run a trigger started | The API key, when the run was started with one | The agent's or automation's name under **Top assistants**, and the image model under **Top models** |
| Voice output or a transcription | The member who requested it | — | **Voice output** or **Transcription** under **Top assistants**; voice output also under **Top voice models** |
| A metered connector call | The member whose request made the call | — | The assistant that made it, or **Connector** |
| A call to the [model endpoints](https://docs.tale.dev/develop/use-tale-from-your-editor#model-endpoints) | The member whose API key sent it | The API key | **Direct API** under **Top assistants** |

A retry of an agent run continues the run its starter kicked off, so its usage stays with that person. When an integration uses an API key to act for another member, the run counts against the member acted for, and the key's own limit counts it too.

## Which limits apply

- **Personal, team, and role limits** bind the person a request counts against. A run a schedule, a webhook, or an event started has no such person and is not measured against any of them.
- **Organization limits** bind every request, including trigger-started runs.
- **API-key limits** bind the requests authenticated with that key: the chat messages it sent, its model endpoint calls, and the runs it started.

When a limit is reached, Tale refuses the next request before it runs and names the limit. A managed agent turn is refused at its start; a turn already running keeps the allowance it was given. An image the agent asks for during its turn is checked on its own before the image model is called, so a reached limit refuses the image while the turn continues. The image also draws on the allowance of the turn that asked for it. [How rules combine](https://docs.tale.dev/platform/admin/governance/policies-and-limits#how-rules-combine) covers the case of several rules applying to one person.

## Three situations worth knowing

**A teammate mentions your agent in a task comment or a task description.** Posting the comment or saving the description starts a run, and that run counts against the teammate who wrote it, not against you as the agent's creator.

**A scheduled automation spends every night.** Its runs appear on the **Automations (triggers)** row. They never raise anyone's personal usage or the active-user count, and only the organization's limits can stop them. Set an organization cost or request limit when you need a ceiling for them.

**An integration uses an API key on behalf of a member.** The member's personal and team limits see the run, and so does the key's limit. Two ceilings apply, and the stricter one refuses first.

## What members see

**Settings > Usage** lists every limit that applies to the signed-in member with its current usage: the chats they sent, the voice output they requested, the model endpoint calls they made, and the agent runs they started, whichever way they started them. Shared team and organization limits appear there too, because they can be reached before a personal one.

# Members and roles
Source: https://docs.tale.dev/platform/admin/members-and-roles

Add people under **Settings > Members**, then choose the role that matches their work. Roles determine permitted actions; project access, teams, and conversation assignments determine which resources a person can reach.

<Video src="https://docs.tale.dev/videos/en/tutorials/ep8-people/ep8-people.en.mp4" poster="https://docs.tale.dev/videos/en/tutorials/ep8-people/ep8-people.en.webp" captions="https://docs.tale.dev/videos/en/tutorials/ep8-people/ep8-people.en.vtt" lang="en" title="Episode 8 — People, roles & teams" caption="Episode 8 — People, roles & teams (2:15)">

</Video>

<Frame caption="Settings > Members — every account and the role that bounds it.">

![The Members settings page listing the workspace owner and four more people, each with a role badge, beside an Add member button.](https://docs.tale.dev/images/get-started/settings-organization-members.webp)

</Frame>

## Add a person

You need an Owner or Admin account to manage members.

1. Open **Settings > Members** and select **Add member**.
2. Enter the person's **Email** and, optionally, **Name**.
3. Choose a **Role**. Start with Member for everyday use; the comparison below explains when to grant more access.
4. For a new Tale account, enter a **Password** that meets the displayed policy. If the email already belongs to an account, Tale reuses its credentials and hides the password field.
5. Select **Add member**. For a new account, save the credentials shown in the confirmation before closing it, then share them through your organization's approved channel.

The person appears in the member list. Tale does not send an invitation or password-reset email for this flow: adding someone is your confirmation of their address, so the account works everywhere at once — including applications people sign in to with their Tale account. If the address is already a member of this organization, the form reports that instead of adding a duplicate.

<Tip>

After adding a person, assign the teams they need. A role alone does not put them into a team's project access or conversation queue.

</Tip>

## Choose a role

| Role | Typical work | Organization administration |
| --- | --- | --- |
| **Owner** | All product and administration work | Includes transferring ownership and deleting the organization, which also deletes its sandboxes and their files; deleting asks you to type the organization's name before the button enables. |
| **Admin** | Manage people, services, policies, and the team's work | Full organization settings; cannot transfer ownership. |
| **Developer** | Build agents, automations, and integrations | Technical settings such as providers, connectors, and API access; no member administration. |
| **Editor** | Maintain content and operate day-to-day work | Content editing; no access to **Automations**; connector resources are read-only. |
| **Member** | Use chat, read resources shared with them, and create project tasks, working their own tasks with project agents | No organization administration; can submit message feedback. |
| **Disabled** | No active access | Retains the membership record without granting permissions. |

Only Owners, Admins, and Developers see **Automations**, in the navigation and in projects; anyone else who follows a link to an automation sees **Access denied**.

People who are not Owners or Admins cannot open **Settings > Members**; they see their own role under [**Settings > Account > Your role**](https://docs.tale.dev/platform/member/preferences#role).

Project tasks follow a rule of their own: every member who can open a project creates tasks in it and changes the tasks they created or that are assigned to them, while Editors and higher roles change every task. The project's settings, agents, and files stay with Editors. [Manage tasks on a project board](https://docs.tale.dev/platform/projects/tasks#who-can-create-and-change-tasks) lists what a Member can do with their own tasks.

These are role capabilities, not a promise that every record is visible. Conversation reads follow assignment: a person sees work assigned to them or their teams; unassigned conversations remain with Owners and Admins for triage. See [conversation routing](https://docs.tale.dev/platform/admin/governance/policies-and-limits#conversation-routing).

Audit-log viewing is restricted to Owners and Admins. Actions by other roles can still produce audit entries; producing an entry does not grant access to the log.

## Change a role or reset a password

Open the person's row menu, choose **Edit**, and change **Role**. Select **Save**, then check the role badge in the list. To restore a disabled member's access, explicitly select the role they should receive.

The edit dialog also changes the display name. Email is read-only. To set a replacement password, enable **Update password**, enter a password that meets the displayed requirements, and save. Use your organization's identity-checking process before resetting an account.

You cannot edit your own role through this menu, assign Owner through the role picker, or demote the last administrator. Existing Owners and the organization creator also have protected roles. If a change is refused, check the relevant account before trying a different role.

## Transfer ownership

An Owner can choose **Transfer ownership** from another member's row menu. Read the confirmation carefully: the selected person becomes Owner and the transferring Owner becomes Admin. Use this action for an ownership handover, not an ordinary role promotion.

## Remove or recover access

Use **Disabled** when access should stop while the membership remains. Use the row's **Delete** action to remove the membership from this organization. Removing it also deletes the separate sandbox workspaces of the [agent runs the person started](https://docs.tale.dev/platform/projects/tasks#agent-runs-a-member-starts), with their files; **Disabled** keeps them. Review shared work and team responsibilities first; removing membership is different from a [data subject erasure request](https://docs.tale.dev/platform/admin/governance/data-subject-requests).

If a member loses an authenticator or passkey, open **Edit** and use the relevant security controls. [Two-factor authentication](https://docs.tale.dev/platform/admin/two-factor-authentication) explains reset, recovery, and session consequences.

# Admin
Source: https://docs.tale.dev/platform/admin/overview

Use organization settings to give people access, connect the services they need, and control how Tale handles work and data. Start with the task you need to complete; you do not have to configure every area before your team can begin.

<Video src="https://docs.tale.dev/videos/en/tutorials/ep9-governance/ep9-governance.en.mp4" poster="https://docs.tale.dev/videos/en/tutorials/ep9-governance/ep9-governance.en.webp" captions="https://docs.tale.dev/videos/en/tutorials/ep9-governance/ep9-governance.en.vtt" lang="en" title="Episode 9 — Governance, cost & trust" caption="Episode 9 — Governance, cost & trust (3:01)">

</Video>

## Set up a working organization

1. [Add members and choose their roles](https://docs.tale.dev/platform/admin/members-and-roles). Give each person the access their work requires.
2. [Create teams](https://docs.tale.dev/platform/admin/teams) when several people need the same project or conversation access.
3. [Connect an AI provider](https://docs.tale.dev/platform/admin/providers) so chats and agents have models available.
4. [Add connector credentials](https://docs.tale.dev/platform/admin/connectors) for the external services your workflows use.

Owners and Admins manage organization settings. Developers can reach the technical settings needed for integrations, but cannot manage members or open the full governance area. Personal account settings remain separate.

## Choose the right control

| You need to… | Open… |
| --- | --- |
| Choose default models or restrict model choices | [Models](https://docs.tale.dev/platform/admin/governance/content-models) |
| Limit usage, uploads, or retention | [Policies and limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits) |
| Filter messages and set organization instructions | [Guardrails](https://docs.tale.dev/platform/admin/governance/guardrails) |
| Investigate actions or spending | [Audit logs](https://docs.tale.dev/platform/admin/governance/audit-logs) or [usage metrics](https://docs.tale.dev/platform/admin/governance/usage-analytics) |
| Find failing chat replies, agent turns, or automation runs | [Operations metrics](https://docs.tale.dev/platform/admin/governance/operations-metrics) |
| Recover retained data or preserve it against deletion | [Trash](https://docs.tale.dev/platform/admin/governance/trash) or [legal hold](https://docs.tale.dev/platform/admin/governance/legal-hold) |
| Review an erasure request | [Data subject requests](https://docs.tale.dev/platform/admin/governance/data-subject-requests) |

## Sign-in, integrations, and appearance

Configure [enterprise SSO](https://docs.tale.dev/platform/admin/enterprise-sso) for your identity provider and [two-factor authentication](https://docs.tale.dev/platform/admin/two-factor-authentication) for account protection. Use [API keys](https://docs.tale.dev/platform/admin/api-keys) when software needs to call Tale.

[Branding](https://docs.tale.dev/platform/admin/branding) changes the organization's logo and colors. [Sandboxes](https://docs.tale.dev/platform/admin/sandboxes) shows execution capacity and workload limits; with [sandbox devices](https://docs.tale.dev/platform/admin/sandbox-devices), your organization's sandboxes run on machines of your own. For a project agent's access to these resources, read [Agents (admin view)](https://docs.tale.dev/platform/admin/agents).

After an upgrade, [What's new](https://docs.tale.dev/platform/admin/changelog) helps you check which platform changes affect your team.

# AI providers
Source: https://docs.tale.dev/platform/admin/providers

Connect an AI provider before asking Tale to run chats or agents. Under **Settings > AI providers**, Owners, Admins, and Developers manage the credentials their organization uses. The provider defines the connection and supported authentication; a credential supplies your organization's access to it.

<Frame caption="Each row is one credential. The Default badge identifies the credential used when a caller does not name one.">

![The AI providers settings page shows a credential with its provider, authentication method, and Default badge.](https://docs.tale.dev/images/get-started/settings-providers.webp)

</Frame>

## Add your first credential

1. Select **Add credential** and choose the provider. The catalog shows configured providers first; choosing one again adds another credential.
2. Choose an **Authentication method** if the provider offers more than one.
3. Check the **Name**. It starts as the provider's name, with a number added when another credential for that provider already uses it: `OpenRouter`, then `OpenRouter 2`. A name that identifies the purpose, such as `Production key` or `Finance team`, makes several credentials for one provider easier to tell apart. Fill in that method's required fields.
4. Review **Model allowlist**. For a provider with a catalog, leaving it empty allows the credential to use that catalog. Providers without a catalog need explicit model IDs.
5. Select **Add credential**. Check the new row and make it the default for that provider when ordinary requests should use it.

For **API key** or **Environment variable** credentials, open a chat and send a short test message with the intended model. A model must be available through an enabled credential and permitted by the organization's model-access rules. Verify subscription credentials with a task or automation agent, as described below. Saving a credential alone does not prove the provider will accept requests.

## Choose an authentication method

| Method | What you provide | When to use it |
| --- | --- | --- |
| **API key** | The provider's secret key | Standard metered API access. The stored secret is encrypted and later shown only as a masked fragment. |
| **Environment variable** | The name of a deployment variable | An operator manages the secret outside the UI. The name must start with `TALE_PROVIDER_KEY_`. |
| **Subscription key** | A supported vendor subscription secret | Runs through the vendor's supported agent runtime in tasks and automations, never in chat. |
| **Subscription broker** | A broker endpoint and token-response configuration | The deployment obtains usable subscription tokens from a broker for the vendor's agent runtime in tasks and automations, never in chat. |

Only methods supported by the selected provider appear. An environment reference does not create the variable: ask the operator to provision it using the [provider configuration guide](https://docs.tale.dev/self-hosted/configuration/providers).

## Use subscriptions in tasks, not in chat

A **Subscription key** or **Subscription broker** credential works only inside the agent runtime it is bound to: Claude Code for an Anthropic subscription and for the Moonshot and Z.ai coding plans, Codex for a ChatGPT subscription, Gemini CLI for Gemini, and Hermes for Nous Portal. Vendors do not permit subscription tokens in other applications, and Anthropic refuses them from any client other than Claude Code. Chat calls the provider's API from Tale itself, so it cannot use a subscription credential.

Tale therefore runs a subscription in tasks and automations, where its runtime works in a sandbox. Chat offers only models that an **API key** or **Environment variable** credential serves. The app says so in three places: the add form shows **Tasks and automations only** when you choose a subscription method, every subscription row in the credentials table carries the same note, and the chat model list names the subscriptions it leaves out.

To chat with a model you reach through a subscription, add an API key or environment-variable credential for the same provider, or connect a provider such as OpenRouter that serves the model.

## Connect a subscription broker

Subscription brokers support Anthropic subscriptions through Claude Code and OpenAI ChatGPT subscriptions through Codex. These credentials serve task and automation agents; chats require direct API credentials, for the [reasons above](https://docs.tale.dev/platform/admin/providers#use-subscriptions-in-tasks-not-in-chat).

| Provider and runtime | Target variable |
| --- | --- |
| Anthropic · Claude Code | `CLAUDE_CODE_OAUTH_TOKEN` |
| OpenAI · Codex | `TALE_SUBSCRIPTION_TOKEN` |

When adding the credential, choose **Subscription broker** and obtain the endpoint and authentication details from your operator. Use an endpoint that serves only the selected provider. For Tale AI gateway, that is `/api/tokens/anthropic` or `/api/tokens/openai`.

Set **Token array path** to `$.tokens`, **Token field** to `access_token`, and **Target environment variable** to the value above. Under **Advanced**, use `status` for **Status field**, `active` for **Active status value**, and `expires_at` for **Expiry field**, and leave **Expiry safety margin (ms)** at its default. The gateway itself holds back an account whose token is about to be refreshed while another account can take the work; Tale still uses it when no other available account can take the turn, for example while the others cool down after a rate limit. Other brokers may use different paths. OpenAI pools must also supply the vendor's `account_id` for every usable token; the broker's own `id` is a separate account identifier.

For OpenAI, restrict **Model allowlist** to model IDs your ChatGPT plan supports. The OpenAI API catalog can include models that the subscription cannot use.

To run a GPT-6 model on the ChatGPT subscription, save the OpenAI broker credential, then configure a [project agent](https://docs.tale.dev/platform/projects/project-agents) with **Agent type** set to **Codex**. Under **Model**, search for the model ID, such as `gpt-6.1-sol`, and select the entry marked **OpenAI · Subscription**. [Run the GPT-6 models](https://docs.tale.dev/platform/admin/providers#run-the-gpt-6-models) explains where else each model runs.

Choose **Token selection** according to how you want to distribute new agent turns:

- **Random**, the initial choice, picks uniformly from the usable accounts for each selection.
- **First usable** always takes the first usable account in the broker's order. Use it for an ordered preference, not to spread work.
- **Round-robin** picks the usable account that was selected least recently. All backend processes share the selection history for this organization and credential, including concurrent requests. Reordered responses and backend restarts preserve that history; stable broker account IDs also preserve it across token refreshes. This distributes selections; it does not promise equal token usage or equal numbers of running agents.

Save the credential, then run a short task or automation with the matching provider and agent runtime. Check that the agent completes a reply. If no account is usable, ask the operator to check account authorization, token expiry and planned refreshes, and reported quota. The [broker configuration reference](https://docs.tale.dev/self-hosted/configuration/providers#connect-a-subscription-broker) explains the optional account metadata, defaults and recovery.

## Run the GPT-6 models

The OpenAI catalog includes GPT-6 Astra (`gpt-6-astra`), GPT-6 Sol (`gpt-6-sol`), GPT-6 Luna (`gpt-6-luna`) and GPT-6.1 Sol (`gpt-6.1-sol`).

- **Chat** offers all four through an OpenAI **API key** or **Environment variable** credential, automatic model selection included. Astra and GPT-6.1 Sol make tool calls only through OpenAI's Responses API, so Tale calls them through it. GPT-6 Sol and Luna accept the chat's tools only with reasoning switched off, so the picker offers no effort levels for them.
- **Project agents and automations** run Astra and GPT-6.1 Sol only on **Codex**, the runtime that speaks the Responses API, on an API-key, environment-variable or ChatGPT-subscription credential. The model picker offers them for no other runtime.

## Configure Azure or another custom endpoint

Azure OpenAI requires **Endpoint URL**, typically `https://<resource>.openai.azure.com/openai/v1`. Each credential belongs to that resource. Azure model IDs are the deployment names configured in the Azure resource, so enter those names in **Model allowlist**; an empty list provides no models when there is no catalog to inherit.

Use the provider's documented endpoint and model identifiers. A display name from a marketing page is not necessarily the identifier accepted by its API.

## Define a custom provider

An organization can connect an endpoint the shipped catalog does not list: a self-hosted model server such as vLLM or Ollama, or an internal gateway that speaks the OpenAI or Anthropic API. Select **Add credential** and choose **Custom provider**, the entry pinned under the catalog:

1. Enter a **Provider name**. It names the provider and this credential, and the provider's identifier is derived from it.
2. Choose the **API format** the endpoint speaks and enter its **Base URL**, the API root the platform appends its paths to. A public host needs `https`.
3. Under **Models**, keep **Discover from the endpoint** to read the server's `/models` listing with this key, or choose **Enter model IDs** and list the exact IDs in the **Model allowlist** for an endpoint that cannot list them.
4. Fill in the **API key** (or the environment variable) and select **Add credential**.

The credential row now shows the provider with a **Custom** badge, and the provider appears in the **Add credential** catalog with the same badge; choosing it there adds another credential for it. A private or loopback address also needs the deployment's private-host opt-in, which an operator sets; saving the credential does not grant it. Ask your operator to prepare endpoint access and deployment policy, then follow [Connect a local model server](https://docs.tale.dev/tutorials/admin/connect-local-provider). If coding agents will use the provider, test an agent session too: their model traffic passes through a separate gateway, which also needs network access and certificate trust.

From the row's menu, **Check models** reads the endpoint's model list again with this key, **Edit credential** changes the base URL, API format and model source beside the credential's name, and **Delete** removes the credential. In the edit, **Save** changes the provider and the credential together: a duplicate name or a stale version is refused before either changes. If someone saved the provider or this credential after you opened the dialog, your save is refused instead of overwriting their change; reopen the dialog to load the current settings. Deleting a provider's last credential removes the provider itself, and the dialog says so beforehand. Every saved version of the definition stays in the organization's configuration history. Facts the form does not cover, such as a coding-agent endpoint, are set in the definition file the [provider configuration guide](https://docs.tale.dev/self-hosted/configuration/providers) describes.

If the connection drops during **Save**, the outcome may be unknown. Reload the page and check both the provider settings and the credential before retrying; a connection error does not prove that the save was rolled back.

## Select a default and restrict model access

Choose **Make default** from a credential's row menu. There is one default per provider; selecting another moves the badge. Disabled credentials cannot become the default. If no default exists, a caller must explicitly name a credential.

A credential's **Model allowlist** limits only that credential. [Models](https://docs.tale.dev/platform/admin/governance/content-models) sets default models and access rules for people, teams, and roles across providers. Both restrictions apply; widening one list cannot bypass the other.

The **Agent runtimes** section below the credentials is read-only. It shows available models and subscriptions for each runtime; change the credentials above to change that configuration.

## Recover a missing or failing model

- If a provider has no default, select the intended active credential and make it the default.
- If the catalog failed to load, use **Refresh catalogs** and inspect the provider's result. Live catalogs are cached; built-in catalogs change with the platform.
- If a model is missing, check both the credential's allowlist and organization model-access rules. For a catalog-free provider, check the exact model IDs.
- If a request is rejected, verify the credential's enable state, provider account access, endpoint, and provider-side quota before changing model rules.

## Rotate or retire credentials

Use the row's replacement action to rotate a secret while keeping its name and references. **Disable** pauses a credential without removing its configuration; **Enable** restores it. Confirm a replacement works with the intended model.

<Warning>

Deleting a credential removes access for callers that depend on it. Move those callers first. If you delete the default, select a replacement default so unnamed requests can resolve a credential. A credential the knowledge embedding model resolves — the one named under **Settings > Data residency > Embedding model**, or that provider's last active default — cannot be deleted: the delete dialog names the dependency and Tale refuses the delete. Choose another credential for the embedding model first.

</Warning>

# Run sandboxes on your own devices
Source: https://docs.tale.dev/platform/admin/sandbox-devices

A device is a machine you connect to your organization so its sandboxes run there instead of on the Tale server: a spare workstation, a build server or a Mac with capacity to share. Owners and Admins add and remove devices under **Settings > Sandboxes**. Developers can see the list.

## Check what the machine needs

- Linux on x86_64 or arm64, or macOS on Apple silicon or Intel.
- Docker: Docker Engine on Linux; Docker Desktop, OrbStack or Colima on macOS. If Docker is missing, the Tale CLI offers to install it.
- Outbound HTTPS to your Tale site. The device connects out to Tale; nothing has to reach the machine, so it works behind a router or firewall.
- Disk space for the sandbox images, several gigabytes, and for the workspaces it will hold.

By default a device runs one sandbox for every two CPUs and every 4 GiB of memory that Docker can use, up to 16 at a time, because each agent sandbox gets 2 CPUs and 4 GiB. You can choose another number when you connect the machine.

This number is a ceiling. The device also checks available host memory and workspace disk space before admitting work, so a free slot alone does not guarantee capacity for another sandbox.

<Warning>

A device runs your organization's work. Agent workspaces, the files they process and the short-lived credentials a task uses pass through the machine, and anyone with administrator access to it can read them. Connect only machines you control and trust as much as the Tale server. In turn, the Tale site decides what runs on the device, including the updates it installs by itself, so connect a machine only to a Tale site you trust with it.

</Warning>

## Add a device

<Steps>

<Step title="Copy the command">

Open **Settings > Sandboxes** and select **Add device** in the **Devices** section. Under **Install and connect**, select **Copy command**.

The command works once, within an hour. It carries a single-use token that the machine trades for a credential of its own.

<Frame caption="Add a device: the install-and-connect command, and the shorter one for a machine that already has the CLI. The token shown here is a placeholder.">

![The Add a device dialog with the Install and connect command, which installs the Tale CLI and runs tale sandbox connect with the deployment's address and a single-use token, a Copy command button, the requirements, the note that the command works once within an hour, the shorter command for a machine that already has the CLI, and the status Waiting for the device to connect.](https://docs.tale.dev/images/platform/sandbox-add-device.webp)

</Frame>

</Step>

<Step title="Run it on the machine">

Paste the command into a terminal on the machine and run it. It installs the Tale CLI and connects the machine:

```text
Connecting this machine to https://your-org.tale.dev as "studio-mac"…
Starting the sandbox device (Tale 0.5.60). The first start downloads the sandbox images, which can take a few minutes…
```

If the machine already has the Tale CLI, run the shorter command under **Already have the Tale CLI? Run this instead**.

</Step>

<Step title="Confirm it is online">

As soon as the machine reaches Tale, the dialog shows **studio-mac is connected.** and the device appears in the **Devices** list as **Online**. Select **Done**.

</Step>

</Steps>

The device keeps running after the machine restarts, as long as Docker starts with it. When Tale is updated, the device updates itself to the same release.

## Understand where sandboxes run

New agent and automation workspaces start on a connected device that has room. When none has, they start on the Tale server. A workspace stays with its files on the machine where it started, so an agent that already has a workspace on the server keeps using it. Pages rendered for website crawling always stay on the server.

When several devices have room, Tale considers both free slots and observed memory headroom. If a device refuses a create because it is full, another device or the server can take it. If the response is lost or the device returns a server error, retries stay on that device: it may already have created the workspace.

Once your organization has a device, the **Workspaces** list shows where each workspace runs: **On the server** or on a device by name. While a device is offline, work that needs one of its workspaces fails with a message that the device is not connected. Start the work again once the device is back online; workspaces never move to another machine by themselves.

Sandboxes on a device reach the internet through the machine's own connection, through the same egress proxy as on the server. The proxy blocks private network addresses, so sandboxes cannot reach other machines on your local network.

Connected devices also raise the ceiling for your organization's [workload limits](https://docs.tale.dev/platform/admin/sandboxes#change-a-workload-limit): their total may use the deployment capacity plus the sandboxes your devices run.

## Read the device list

| Column | What it shows |
| --- | --- |
| **Device** | The name the machine connected with, and its operating system. |
| **Status** | **Online**, **Updating**, **Update needed**, **Update failed** or **Offline**. |
| **Sandboxes** | Sandboxes running now, and how many the device runs at once. |
| **Machine** | CPUs and memory that Docker can use on the machine. |
| **Version** | The Tale release the device runs. |
| **Last seen** | **Now** while connected, otherwise when the device was last in contact. |

A device on another release than the server takes no new sandboxes until it updates. **Update needed** means the device does not update itself; **Update failed** means its last automatic update did not succeed. In both cases, run `tale sandbox update` on the machine.

## Look after a device from the machine

Run these commands on the device itself:

| Command | What it does |
| --- | --- |
| `tale sandbox status` | Shows the connection, the organization, the release and the sandboxes running now. |
| `tale sandbox logs --follow` | Follows the device's log. |
| `tale sandbox update` | Moves the device to the server's release now, with the server's current addresses for its sandboxes. |
| `tale sandbox disconnect` | Removes the device from its organization, stops its sandboxes and deletes their workspaces from the machine. Add `--keep-data` to keep the workspaces. |

## Remove a device

In the **Devices** list, open the device's row menu, select **Remove** and confirm. The device stops running sandboxes for your organization right away. Its workspaces stay on the machine but can no longer be reached from Tale, so their agents start with fresh workspaces the next time they run.

To clean up the machine as well, run `tale sandbox disconnect` on it.

## Fix a device that does not connect

- **The command has expired or was already used.** Select **Add device** again to get a new command.
- **The device started but has not reached the server yet.** Run `tale sandbox logs --follow` on the machine and check that it can open HTTPS connections to your Tale site, including through any proxy between them.
- **The connection fails with a certificate error.** The machine must trust your Tale site's TLS certificate. A deployment that uses a self-signed certificate cannot take devices.
- **Add device is unavailable, and the section says the sandbox service doesn't accept devices.** The deployment runs without its device hub. On a self-hosted deployment, the operator turns it on as described under [Sandbox devices](https://docs.tale.dev/self-hosted/configuration/environment-reference#sandbox-devices).

# Manage sandbox capacity
Source: https://docs.tale.dev/platform/admin/sandboxes

Open **Settings > Sandboxes** when agent work or crawling cannot obtain an execution environment. The page separates your organization’s workload limits from the deployment’s actual infrastructure. Owners and Admins can change limits and decide when unused workspaces are deleted; Developers can read limits and aggregate capacity, without the private workspace list.

## Identify the limit that matters

| Workload | Default | What uses a slot |
| --- | --- | --- |
| **Project agent sessions** | 2 | An agent workspace starting or doing work. The agent reuses its workspace across tasks. |
| **Workflow sessions** | 2 | A workflow run’s sandbox, shared by its sandbox work. Concurrent runs use separate slots. |
| **Render sessions** | 2 | A temporary sandbox rendering pages during website crawling. |

These are concurrency limits, not a count of tasks or a spending budget. An agent can work on several tasks in its one workspace. Limits do not reserve infrastructure for the organization; all organizations share the deployment capacity.

<Frame caption="The three workload limits add up automatically. Their total must fit within the deployment capacity.">

![The Organization limits section shows three editable session limits and their calculated total against the deployment capacity.](https://docs.tale.dev/images/platform/settings-sandboxes.webp)

</Frame>

## Change a workload limit

1. Check the workload’s **Allocated** count and the infrastructure measurements below it.
2. Enter a whole number from 1 to 500 for the relevant limit. **Total organization sessions** recalculates the sum of all three fields.
3. Keep that total within deployment capacity, then select **Save** in the header. **Discard** restores the saved values.
4. Reopen the page to confirm the saved limits and inspect whether new work can obtain an allocation.

For example, the defaults total 6. If deployment capacity is 8, a total of 8 is valid and 9 is refused. The server rechecks capacity when saving, so another observation may differ from the one you first saw. Your organization's connected [devices](https://docs.tale.dev/platform/admin/sandbox-devices) add the sandboxes they run to the ceiling: with one device that runs 4, the total may reach 12.

Lowering a limit affects future admissions; it does not interrupt active work. If infrastructure data is unavailable, reductions remain possible but increases need a fresh capacity observation. If the operator lowered capacity below your existing total, reduce your limits before saving again. If organization allocation data itself cannot load, the fields remain unavailable instead of showing editable defaults.

## Read the infrastructure measurements

<Frame caption="Deployment sandboxes shows the shared count and capacity. Your organization's sandboxes shows its current count, including idle environments kept for reuse.">

![The Infrastructure capacity section shows deployment sandboxes as a current count and capacity, the organization's sandbox count, and measured host CPU and memory.](https://docs.tale.dev/images/platform/sandbox-infrastructure-capacity.webp)

</Frame>

| Measurement | What it means |
| --- | --- |
| **Deployment sandboxes** | Running and starting environments across all organizations, compared with shared capacity. Kubernetes reports the namespace boundary. |
| **Your organization's sandboxes** | This organization’s running and starting environments, including idle ones kept for reuse. This is a count, not another organization limit. |
| **Host CPU usage** | Recently used and total CPU cores for the host, including its other services. |
| **Host memory usage** | Used and total host memory, including other services and allowing for reclaimable cache. |

Measurements refresh every 15 seconds; **Refresh** requests a new observation. Check its timestamp before interpreting it. CPU usage is the change between two samples; a first observation after a long gap takes about a second longer. Remote hosts may expose totals without usage. Kubernetes namespace access does not expose host measurements. **Unavailable** means unknown, not zero.

## Explain an allocated or idle workspace

Owners and Admins can inspect **Workspaces**. A row identifies its agent or workflow run, runtime state, allocation state and running tasks. These states answer different questions: a container may remain running for reuse after it has released its organization slot. A project agent’s workspace stays listed while the agent is idle, as **Stopped** with **Quota released**, until you destroy it or Tale deletes it: when nobody has used it for [the number of days your organization sets](https://docs.tale.dev/platform/admin/sandboxes#delete-unused-workspaces-automatically), or when [its agent, project or member is removed](https://docs.tale.dev/platform/admin/sandboxes#explain-why-a-workspace-disappeared). Once the agent itself is deleted, the row reads **Deleted agent** until Tale has deleted the workspace. A workflow run’s workspace is reclaimed shortly after the run ends.

**Spend** adds the metered cost of finished turns. A turn still running is included when it ends. Temporary crawler environments appear in capacity counts even without a standing workspace row.

When deployment capacity is full, Tale may reclaim an unpinned idle environment whose allocation is released and which confirms it has no ongoing work. Its persistent workspace files remain for the next start. Busy, pinned or unresponsive environments are not candidates. If there is no safe candidate, new work must wait for capacity. An environment whose task or run has finished stops after a few idle minutes, so its room frees soon after the work ends. An agent environment that runs Docker inside keeps its full idle time, so the next turn does not have to pull its images again.

## Manage an existing workspace

Owners and Admins can use a workspace’s row menu:

| Action | Effect |
| --- | --- |
| **Stop task** | Cancels all currently running operations in that workspace. Check the listed tasks first; one agent may have several. |
| **Pin** / **Unpin** | Keeps the workspace exempt from automatic idle and expiry cleanup and from deletion for being unused, or restores normal cleanup. A pinned allocation can continue holding capacity. If a pinned workspace’s environment disappears, for example after a host restart, Tale starts it again with its workspace files, and the workspace stays pinned. |
| **Destroy** | Asks for confirmation, then removes the sandbox and its workspace files in the background: it unpins the workspace first and cancels running work. Until the workspace is gone, its row reads **Destroying** and you can go on using the page. If Tale still cannot remove it after several attempts, the workspace remains listed, unpinned, and reads **Destroy failed**; choose **Destroy** again to finish removing it. While the row reads **Destroying**, nothing new starts in that workspace: an agent's run waits and reads **Waiting for a sandbox slot**, and a workflow run's step that needs the workspace fails at once with the reason, without waiting or trying again, because the files its earlier steps left are being deleted. Once the row is gone, the next start creates a fresh environment; if it reads **Destroy failed** instead, the waiting work continues in the old files. |

A pin change is saved durably and retried if its runtime acknowledgement fails, including after a worker restart or device outage. Retries apply the latest desired value to the same session incarnation; repeated unpin delivery does not extend its expiry.

Use stop when the current work should end but its files should remain. Before destruction, preserve outputs you still need and read the confirmation. Idle capacity reclamation preserves workspace files; explicit destruction and automatic deletion do not.

## Delete unused workspaces automatically

A project agent keeps its files between runs in workspaces: the one it reuses across tasks, and a separate one for each Member who [starts its runs](https://docs.tale.dev/platform/projects/tasks#agent-runs-a-member-starts). Tale deletes a workspace that nobody has used for the number of days your organization sets; **Destroy** still deletes one at once. Owners and Admins set this rule under **Workspace cleanup**, above **Workspaces**. Developers don't see that section.

<Frame caption="With Delete unused workspaces on, a workspace nobody has used for the set number of days is deleted. Pinned workspaces are kept.">

![The Workspace cleanup section shows the Delete unused workspaces switch turned on and Days without use set to 30, each with an explanation of what it does.](https://docs.tale.dev/images/platform/sandbox-workspace-cleanup.webp)

</Frame>

1. Keep **Delete unused workspaces** switched on, as it is by default. While it is off, Tale deletes no workspace for being unused.
2. Enter **Days without use**, a whole number from 1 to 3650; the default is 30. The days count from the last time the agent worked in the workspace, or from when it was unpinned.
3. Select **Save** in the header. **Discard** restores the saved values.

A change never makes a workspace go early. After you switch deletion on or shorten the period, no workspace is deleted for being unused until the full number of days has passed since the change. The same wait follows the update that introduced the setting. Lengthening the period doesn't restart the wait; switching deletion off and on again does.

In **Workspaces**, a stopped agent workspace shows the day it will be deleted under its status: **Deleted on … unless used again**. A new run in the workspace starts the count again. A pinned workspace, or one a [legal hold](https://docs.tale.dev/platform/admin/governance/legal-hold) keeps, shows no date and is never deleted for being unused.

## Explain why a workspace disappeared

Besides deleting unused workspaces, Tale deletes a workspace when what it belongs to is removed, whatever the cleanup setting says:

- Deleting a project agent deletes all its workspaces, including each Member's. Deleting a project does the same for every agent in it.
- [Removing a member](https://docs.tale.dev/platform/admin/members-and-roles#remove-or-recover-access) from the organization deletes their own workspaces with every agent. Setting the member to **Disabled** instead keeps them.
- [Erasing a person's data](https://docs.tale.dev/platform/admin/governance/data-subject-requests) deletes their own workspaces without waiting for work running in them.
- Deleting the organization deletes all its sandboxes and their files, revokes the gateway keys issued to them, disconnects its [devices](https://docs.tale.dev/platform/admin/sandbox-devices) and removes the build and package caches kept for it.

This happens within about a minute, or after the task ends if one is still running in the workspace. A pinned workspace goes too, but a [legal hold](https://docs.tale.dev/platform/admin/governance/legal-hold) keeps every workspace it covers: a hold on the organization keeps all of them, and a hold on a person keeps that person's own workspaces. An hourly cleanup also deletes leftovers that nothing owns any more, such as a workflow run's workspace that was never reclaimed.

Every workspace Tale deletes on its own, for one of these reasons or for being unused, appears in the [audit log](https://docs.tale.dev/platform/admin/governance/audit-logs) under **Settings > Governance > Logs** as **Sandbox workspace deleted**. It is a system event in the **Data** category, and its metadata names the reason: `agent_deleted`, `member_removed`, `member_erased`, `unused` or `orphaned`. The event is recorded once Tale has confirmed that the workspace's files are deleted, which can take a while for a large workspace. On Kubernetes, it is recorded once the workspace's volume is handed to the cluster's storage provisioner, which deletes it according to its StorageClass's `reclaimPolicy`; the metadata says which happened (`deletion`: `done` or `handed_off`). If deleting the files fails, the event appears with the status **Failure**, and the deletion is tried again until the files are gone. A sandbox service or device that is not yet updated to this version cannot confirm a deletion, so Tale records no event for its workspaces and keeps trying until it is updated. A leftover that nothing owns any more can end without an event: if its files are still being deleted when the hourly cleanup moves on, the sandbox service finishes deleting them, but Tale does not check on them again.

## Resolve a blocked start

A start that finds no room waits. When your organization's limits are in use, or the deployment is full or short of memory, the work starts on its own once room frees, and needs nothing from you. Disk space is different: stopping idle work frees none, because a stopped workspace keeps its files. Tale removes build caches that no session uses, if there are any; when that frees too little, the start waits until workspaces are deleted, for example ones you destroy because you no longer need them, or until the operator frees disk space. When the deployment itself is full, its room goes to the work that has waited longest, whichever organization it belongs to, and each waiting start is told when its turn comes:

- A task run waits in the queue. It is tried again as soon as a session ends, in your organization or in another one on the same deployment. When the deployment is full, it is also tried when its turn comes. Every two minutes, Tale also tries a few of each organization's waiting runs, the longest-waiting first.
- An automation's agent step tries again without using up its retries: when its turn comes if the deployment is full, otherwise after a pause that grows while the step keeps waiting, up to about two minutes. The run shows **Waiting for a sandbox slot** meanwhile. After two hours without room, the run fails with that reason. A workspace an administrator is destroying is no lack of room: the step fails at once instead, as described for **Destroy** above.
- Crawling waits for its turn, then continues with its next batch.

Raise a workload limit only when its allocations are full and the new total fits shared capacity. If the deployment itself is full, increasing an organization limit cannot create infrastructure. To add capacity of your own, [connect a device](https://docs.tale.dev/platform/admin/sandbox-devices): new workspaces start on it. Otherwise, ask the operator to inspect capacity and host resources; a free container slot alone does not guarantee enough CPU, memory or disk space.

For a credential or model refusal, use [AI providers](https://docs.tale.dev/platform/admin/providers). For a spending refusal, use [Policies and limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits). Self-hosted operators can inspect the deployment setting in the [environment reference](https://docs.tale.dev/self-hosted/configuration/environment-reference#sandbox-infrastructure).

# Teams
Source: https://docs.tale.dev/platform/admin/teams

A team is a label on work, not a place you switch into. A document, folder, or project carries the teams that may see it, and a conversation can wait in a team's queue. A person's role controls what they may do; their teams decide which restricted work they can reach. Owners and Admins manage teams under **Settings > Teams**.

<Frame caption="Settings > Teams — every team the org has, with its member count, beside the Create team action.">

![The Teams settings page listing three teams (Customer success, Growth, and Platform engineering), each with one member and the date it was added, beside a Create team button.](https://docs.tale.dev/images/platform/settings-teams.webp)

</Frame>

## Create a team

1. Select **Create team** and enter a **Team name**, such as `Customer support`.
2. Select the organization's members who should join. If you select nobody, Tale adds you to the team.
3. Select **Create team**. Check the new row and its member count in the list.

Choose a name that people will recognize wherever teams are shown: the audience of a document or project, a queue in the inbox, a list filter. The form accepts up to 80 characters. A name is unique within the organization: one that another team already uses — in any letter case or spacing — is refused. Creating the team does not put existing work under it; choose the team on the documents, projects, and conversations it should cover.

## Change membership or the name

Open a team's row to inspect its members. The row menu offers **View**, **Edit**, and **Delete**. Use **Edit** to change the name or membership, then save your changes and check the member count.

A team keeps at least one member. To remove the last one, delete the team instead.

A person can belong to more than one team. Their access can come from several teams or from a direct assignment, so removing them from one team does not necessarily remove all access to a resource. Review those other routes when withdrawing access.

Notifications follow the same rule. Someone who can no longer open a project gets no new notifications or emails about its tasks, not even about the tasks they watch. What they were already told stays in their notifications. If they regain access, the tasks they watch notify them again.

A team your identity provider provisions shows **Synced** in the list. The provider owns its name and members: the edit dialog shows them read-only, because a local change would be undone by the next synchronization. You can still delete such a team locally; the provider may recreate it.

<Tip>

Rename an existing team when its purpose changes but the same people should retain access. Deleting and recreating it creates a different team and changes existing resource assignments.

</Tip>

## What a team decides

Every team-scoped resource follows one rule. A resource with no team is visible to everyone in the organization. A resource with teams is visible to the members of any of those teams. Owners and Admins see everything either way, so a team is never a way to hide work from administrators.

| Resource | How teams matter |
| --- | --- |
| Projects | **Audience** on **General** lists the teams that can open the project; empty means the whole organization. |
| Documents and folders | A document or folder carries the teams that can read it. Anything filed into a team folder takes the folder's teams and cannot name a team outside them. |
| Skills | Team visibility makes a skill available to the selected teams. |
| Conversations | Assignment to a team places the conversation in that team's queue. |

When you restrict work to teams, you can only choose teams you belong to; Owners and Admins can choose any team of the organization. Team membership does not grant actions that a role forbids: an Editor and a Member in the same team can have different editing rights.

Members see their own teams under **Settings > Account > Your teams** and in the **Teams** row of the profile menu. To narrow a list to certain work, each list offers a **Teams** filter with **Organization-wide**, **My teams**, and every team by name; the inbox uses an **Assignee** filter instead, which covers people as well as teams. See [Manage your account](https://docs.tale.dev/platform/member/preferences#teams).

For inbound conversations, [routing rules](https://docs.tale.dev/platform/admin/governance/policies-and-limits#conversation-routing) can select the team when the conversation arrives. Without a person or team assignment, the conversation stays in administrator triage.

## Retire a team carefully

Choose **Delete** from the row menu. The confirmation counts the team's members, the projects, folders, and documents it is on, and the conversations in its queue. It also says how many of those items have no other team and will become visible to everyone in the organization. Reassign work that must remain restricted before you confirm.

<Warning>

Deleting a team cannot be undone. Every project, folder, and document drops the team and keeps its other teams. An item whose only team it was becomes organization-wide, which can make it visible to more people.

</Warning>

The team, its memberships, its place on every resource, and any identity-provider link go in one step, so a half-deleted team cannot remain. A conversation loses its team assignment; if no person is assigned either, it returns to administrator triage. Imported-file configurations also lose that team scope. Deleting a team does not delete its members' accounts.

Teams synchronized through [enterprise SSO or SCIM](https://docs.tale.dev/platform/admin/enterprise-sso) also depend on the identity provider's provisioning rules. Check that source before making a local change you expect to persist.

# Two-factor authentication
Source: https://docs.tale.dev/platform/admin/two-factor-authentication

Protect your account with an authenticator app or a passkey. Members set up their own sign-in methods in **Settings > Account**; admins can require a second factor and help a member recover access.

## Choose a sign-in method

| Method | What you need | How you use it |
| --- | --- | --- |
| Authenticator app | A Tale password and an app that supports time-based codes (TOTP) | Enter your password, then the app's six-digit code. |
| Passkey | A compatible device or security key | Approve the browser's sign-in prompt with your device or key. You can also use it after a password sign-in. |
| Backup code | A saved code from authenticator setup | Use it once in place of an authenticator code when you cannot access the app. |

A passkey satisfies Tale's two-factor policy even if you have never set up an authenticator. Accounts that sign in only through SSO do not show authenticator setup because it requires a Tale password; your organization's SSO exemption determines whether you need a Tale passkey.

<Frame caption="Settings > Account shows your password, two-factor authentication, and passkeys: start the authenticator setup or register another passkey from here.">

![The Account settings page with the Password, Two-factor authentication, and Passkeys sections; the Passkeys section lists one passkey named Work laptop.](https://docs.tale.dev/images/platform/settings-account-security.webp)

</Frame>

## Set up an authenticator

1. Open **Settings > Account**, find **Two-factor authentication**, and select **Enable two-factor**.
2. Enter your current Tale password and select **Confirm**. A wrong password counts toward the same temporary lock as a failed sign-in.
3. Scan the QR code with your authenticator app. If scanning is unavailable, enter the displayed setup secret manually in the app.
4. Enter its current six-digit code in **Verification code**, then select **Verify and enable**.
5. Download or copy the backup codes before selecting **Done**. Tale does not display them again.

The account page now confirms that two-factor authentication is active. At your next password sign-in, enter a code from the same authenticator entry.

<Tip>
Keep recovery codes somewhere you can reach without the device you use to sign in, such as a password manager available on another trusted device.
</Tip>

## Add a passkey

1. Open **Settings > Account**, find **Passkeys**, and select **Add a passkey**.
2. If you signed in more than a day ago, Tale first asks for your password. Enter it in **Password** and select **Confirm**. A wrong password counts toward the same temporary lock as a failed sign-in.
3. Give **Passkey name** a recognizable name, such as `Work laptop`.
4. Leave **Authenticator type** on **Any (recommended)** to see the browser's available options, or choose the built-in device authenticator or a security key/phone.
5. Select **Add a passkey** and complete the browser prompt.

The passkey appears in your account's list. On the sign-in page, choose **Sign in with a passkey**. After a password sign-in, **Use a passkey instead** is also available on the verification screen.

To stop using a passkey, select its **Remove** button and confirm. If it was your only second factor and the organization requires one, you must set up another.

## Recover access and replace codes

On the verification screen, select **Use a backup code instead** and enter one saved code. Each code works once. After signing in, open **Settings > Account** and select **Regenerate backup codes** if you need a fresh set; confirm your password and save the new codes. This invalidates every previous code, including unused ones.

If a code is rejected, check that you selected the authenticator entry for this Tale account, use the current code, and check the device's clock. Repeated failures can temporarily block verification; follow the message shown instead of repeatedly submitting.

If you have no usable authenticator, passkey, or backup code, contact an organization admin. Do not send them your password, setup secret, or remaining codes.

## Require a second factor for the organization

Admins configure the policy in **Settings > Governance > Security**. Arrange a recovery contact and give members time to set up a method before enabling it.

<Frame caption="The Security settings page contains password, sign-in, and two-factor policies. Scroll to Two-factor authentication for the enrollment policy.">

![Security settings showing sign-in limits and password requirements above the two-factor policy.](https://docs.tale.dev/images/platform/governance-security-monitoring.webp)

</Frame>

| Setting | Effect |
| --- | --- |
| **Require two-factor authentication** | Enables the requirement after confirmation. A registered passkey or authenticator satisfies it. |
| **Grace period (days)** | Time to enroll, counted from the member's first sign-in under the policy. Zero requires enrollment immediately. |
| **Exempt SSO-only users** | Lets members without a Tale password rely on their identity provider's authentication. |

During the grace period, members see a reminder. After it expires, Tale blocks organization access until they enroll: the enrollment page asks for their password to set up an authenticator, or offers **Register a passkey instead**. A member who has been signed in for more than a day confirms their password before the passkey prompt; one who signs in only through SSO selects **Sign in again** first. Disabling your personal authenticator does not exempt you from this policy.

## Help a locked-out member

Verify the person's identity through your organization's recovery process first. Then open **Settings > Members**, edit the member, and select **Reset two-factor**. Confirming clears their authenticator setup and ends all active sessions. They can sign in again and set up a new authenticator; an enforced policy requires enrollment before they continue.

For a lost passkey, remove that credential in the member dialog's **Passkeys** section instead. Admin removal also ends all of that member's sessions. Review recovery actions in [audit logs](https://docs.tale.dev/platform/admin/governance/audit-logs).

# Understand project agents
Source: https://docs.tale.dev/platform/agents/concepts

A project agent is a named worker for tasks in one project. You configure how it runs and what it may use, then give it a task with a reviewable outcome. It can work on files and commands in a sandbox. The [configured reviewer](https://docs.tale.dev/platform/projects/tasks#review-default), a person or an independent project agent, checks the result before completing the task. New reviews that require human independence or competence records go to the human review chain; a captured agent review needs explicit transfer to an eligible person.

## Choose the right working mode

| Use | Suitable work | What you configure |
| --- | --- | --- |
| Chat | Ask a question, retrieve knowledge or draft text in a conversation. | The message, model and optional project context. |
| Project agent | Review a repository, prepare files or carry out a task over several turns. | A reusable worker in the project. |
| Automation | Run defined steps, react to events or wait for an approval between actions. | A versioned workflow and its inputs. |

A project chat still uses the built-in chat assistant. Adding a project to a chat does not select one of the project’s agents. An automation’s agent node has its own configuration.

## Give the agent a clear responsibility

Start with a responsibility you can evaluate, such as “Review changes for regressions and report evidence.” Keep that in the agent’s standing instructions. Put the particular repository, files, acceptance criteria and deadline in each task.

An agent belongs to exactly one project. People who can read the project can see its agents; people with project edit access can manage them while the project is active. Names must be unique within the project, and a project can contain up to 50 agents. Another project needs its own configuration even if it uses the same name and instructions. A project without agents of its own isn't left without one: unless an admin has turned it off, the organization's [standard agent](https://docs.tale.dev/platform/projects/project-agents#standard-agent) takes its tasks, with settings an admin chooses for the whole organization.

## Understand the configuration

| Part | What it controls | Example decision |
| --- | --- | --- |
| Harness | The coding program that runs the session in a sandbox. | Choose a runtime supported by the available credential. |
| Model and provider | The model called and the provider serving it. | Select the provider/model pair approved for the work. |
| Instructions | The agent’s reusable responsibility and working rules, up to 20,000 characters. | Require evidence and a report of checks performed. |
| Skills | Instruction bundles and supporting files. | Add the team’s review checklist. |
| Connectors and tools | Connected services and allowed platform operations. | Grant repository access and only the task tools needed. |
| Secrets | Named organization credentials supplied to the running session. | Use a narrowly scoped token for a service without a connector. |

The skills, connectors, tools and secret-name lists each allow up to 25 entries. A grant to a write tool authorizes its supported writes within its access rules; an instruction asking the agent to be careful does not remove that permission. Only an Owner or Admin may change secret grants.

```mermaid
flowchart LR
    P[Project task and acceptance criteria] --> A[Configured agent]
    H[Harness and model] --> A
    I[Standing instructions] --> A
    E[Skills, connectors, tools and secrets] --> A
    A --> R[Report and files for review]
```

## Check readiness before assigning work

The provider credential must support the selected harness and model, and sandbox capacity must be available. Success in ordinary Chat proves neither condition. A task should explain what success looks like and include the material the agent needs to inspect.

[Create a project agent](https://docs.tale.dev/platform/projects/project-agents) once those choices are clear. [Task automation](https://docs.tale.dev/platform/projects/task-automation) explains starting, steering and reviewing its work.

# Choose an agent runtime
Source: https://docs.tale.dev/platform/agents/harnesses

A harness is the coding program that runs an agent’s session in a sandbox. It asks the model what to do, reads and writes files, runs commands, and returns a report. Choose it for project-agent tasks or an automation’s `agent` node; the ordinary Chat model picker does not select a harness.

## Select the runtime and check access

In a project’s **Agents** tab, open an agent and choose **Agent type**. An automation’s agent node calls the field **Harness**. Then choose the model and provider. Under **Settings > AI providers**, **Agent runtimes** shows which execution paths the organization can currently serve.

A runtime needs both compatible credentials and [sandbox capacity](https://docs.tale.dev/platform/admin/sandboxes). A working chat model is not enough. If a runtime is missing or has no models, inspect its status and provider credential before changing the task prompt. A model whose tool calls need OpenAI’s Responses API, such as GPT-6 Astra or GPT-6.1 Sol, runs only on Codex, so the model picker offers it for no other runtime.

## Compare supported runtimes

“Managed” means the runtime calls through Tale’s model gateway. “Direct” means the session receives a credential for the provider’s own tooling. The built-in definitions support these combinations; your deployment and credentials determine what is available.

| Harness | Credential path | Receives new instructions in the running process | Tale’s MCP channel |
| --- | --- | --- | --- |
| Claude Code | Managed or direct | Yes | Yes |
| Codex | Managed or direct | No | Yes |
| Cursor | Direct only | No | No |
| Gemini CLI | Managed or direct | No | Yes |
| Hermes | Managed or direct | No | No |
| OpenClaw | Managed or direct | No | Yes |
| OpenCode | Managed only | No | Yes |
| Pi | Managed or direct | No | No |
| Qwen Code | Managed or direct | No | Yes |

**Claude Code (compact prompt)** is an optional choice for focused workflows that already supply complete task instructions. It shortens the runtime’s built-in instructions and some tool descriptions while retaining tools, hooks, MCP and Tale’s added guidance. Check task results and elapsed time with your model before adopting it; a smaller prompt does not guarantee a faster run. Choose ordinary **Claude Code** to restore its full prompt on the next fresh run. A provider subscription restricted to Claude Code does not automatically support the compact choice.

To guide project work, comment on the task and mention its agent. Claude Code receives that guidance at a tool boundary. For the other runtimes, Tale stops the current process and continues the conversation in a new process with the comment. This is why a running task may restart its process after you give it direction.

Gemini CLI is the exception: Tale never continues one of its conversations. A later comment, an automatic retry, or an answer to a question it asked starts a fresh conversation over the same workspace, with the task brief and the earlier rounds restated, because the runtime cannot resume a conversation in which it ran a tool. Its files and output are preserved; only the conversation starts over.

## Understand credential exposure and cost

With a stored API key or deployment-environment credential, Tale supplies a session-scoped gateway key. The original model-provider key stays at the platform. Calls through this gateway are metered and subject to the applicable spending rules, including allowance already assigned to other running turns.

Vendor subscriptions use their supported harness and receive the subscription credential in the session environment. They cannot be used as ordinary chat credentials or with an incompatible harness, because the vendors permit subscription tokens only in their own runtime; [AI providers](https://docs.tale.dev/platform/admin/providers#use-subscriptions-in-tasks-not-in-chat) explains this. Their direct provider calls bypass Tale’s gateway metering and spending caps; review usage with the subscription provider.

These model-credential rules do not mean the sandbox contains no secrets. Explicitly granted **Secrets**, and the token supplied for an equipped GitHub connection, can be available inside it. Grant only the access the task needs.

## Understand files and connected tools

A project agent reuses a persistent workspace across its tasks. Task attachments are available read-only under `/agent/inputs/<task>/attachments/`. Files written to `/agent/output/<task>/` are collected as task **Deliverables** when the turn ends. Automation agent output is collected from `/agent/output/`.

Equipped skill bundles are staged as files and named in the run’s instructions. Review their instructions and scripts before granting them; [Skills on agents](https://docs.tale.dev/platform/agents/skills) explains staging and visibility.

Every runtime also finds Tale’s built-in `visual-aspect-analyzer` skill among its own skills, without equipping it. It drives a real browser over a finished UI change and reports layout shifts, flicker and other visual regressions. A skill of the same name in the workspace repository’s `.claude/skills` and `.agents/skills` folders takes its place in every runtime that reads a repository’s skills.

Tale’s connector broker keeps ordinary connector credentials at the platform and returns action results. It exposes read actions to agents, and refuses writes through that broker. Use an automation connector node for a governed connector write. GitHub tooling and explicitly granted secrets have their own access paths, so the broker’s read-only rule is not a general ban on all shell writes.

Agents with Tale’s MCP channel can also look up which Tale release the platform reports. Along with the platform tools granted to the agent, `workspace_status` returns `platform.version`, the release number that the answering backend’s build is labelled with: for example `0.5.64` for the release whose tag is `v0.5.64`. The backend reads nothing from the request for this value. A build without a release number, such as a development build, returns `null` with a short note instead. Treat the value as a label rather than proof, because any build can carry a release number. It also describes that backend only and does not show whether the rest of the deployment is healthy; the deployment’s [status page](https://docs.tale.dev/develop/status-page) reports on its services.

Outbound access normally permits package installation and repository cloning while blocking private addresses and cloud metadata targets. Operators can restrict permitted hosts further. If a command cannot reach a site, check the network policy instead of assuming the credential is wrong.

Tale’s built-in document skills `docx`, `pptx`, `xlsx` and `pdf` find the libraries they call already installed in the sandbox, so an agent equipped with them creates and reads Word, PowerPoint, Excel and PDF files even where package installation is blocked. Their instructions still include install commands such as `npm install -g docx`; where the registry is blocked, that step fails while the preinstalled library stays available. Text recognition (OCR) for scanned PDFs is not included.

## Check the result

The runtime determines when its turn is finished; Tale collects the report and output. Read both before marking the task complete. Confirm which checks actually ran and which depend on services unavailable in the sandbox. [Task automation](https://docs.tale.dev/platform/projects/task-automation) explains the review loop; [execution logs](https://docs.tale.dev/platform/automations/execution-logs) explains an automation’s agent-step result.

If the runtime cannot start at all — a configuration it refuses, a state directory it cannot find — the run fails at once and its reason quotes the last lines the runtime wrote, so the cause is named rather than a bare exit code. Such a run is not retried automatically; fix the cause, then retry.

# Equip agents with skills
Source: https://docs.tale.dev/platform/agents/skills

Equip an agent with a skill when it needs a reusable procedure or reference material from the organization's [skill library](https://docs.tale.dev/platform/workspace/skills). The library stores the bundle; the agent's equipment determines which bundles are available to its runs.

## Choose a skill for the task

A useful skill explains when to use it, how to perform the work, and what a good result looks like. For example, equip a release-note skill with the agent that prepares releases, then give it a small set of changes and check its output against your expected format.

The bundle contains `SKILL.md` and may include references, assets, or scripts. Importing it does not execute those files. Once equipped, its instructions can guide a coding agent that has a shell or other tools, including running a bundled script. Review the whole bundle before use; a skill does not add a separate permission boundary.

## Equip a project agent

Open the [project agent](https://docs.tale.dev/platform/projects/project-agents) and select the needed skills in its equipment. The available list follows the project's access, even if you personally can read more skills:

| Project scope | Available skills |
| --- | --- |
| Organization-wide project | Organization skills |
| Project shared with teams | Organization skills and team skills shared with at least one of the project's teams |

Legacy private skills cannot be equipped on a project agent. The same access rule is checked when a task runs; selecting a skill does not grant the project permanent access to it.

A new project agent starts with the document skills `docx`, `pptx`, `xlsx` and `pdf` ticked when the project can access them. Untick those the job does not need.

Each skill in the list names who created it: a member, **Built-in** for the skills your organization starts with, or **Configuration release** with the member whose upload installed it. Check where an unfamiliar skill comes from before you equip it.

## Use skills in an automation

An automation's agent nodes declare the skills they need. A run bound to a project uses that project's scope. An organization-level run can use organization skills only. Your personal membership in additional teams does not expand either scope.

During sandbox setup, Tale stages the equipped bundles as files and lists each skill with a description excerpt of up to 300 characters and the path to its `SKILL.md` instructions. The excerpt helps the agent choose a skill for a plain-language task; it is a selection hint, not an instruction to execute. Supporting files are available alongside the instructions.

For a skill marked `disable-model-invocation`, the list tells the agent to wait until the task asks for that skill by name. This is guidance, not an access control. Keep the equipment focused and name the procedure when it matters; availability alone does not prove that the result followed it.

## Resolve missing or changed skills

Deleting a skill unequips it from every agent that carried it, and the audit log records which ones. If a required skill is no longer shared with the run's scope, staging fails and names the unavailable skill; the run is not retried automatically, because nothing about a retry changes that. In the agent's dialog the skill is listed as unavailable so you can untick it — every other setting of the agent still saves. Restore the intended access or remove the obsolete equipment before retrying.

Changes to a shared bundle affect later staging for its users. Review replacements and test an agent with a known input after a substantial change. Do not assume a repository's similarly named skill overrides the equipped bundle.

## Choose skills or agent instructions

| Put it in a skill when… | Put it in agent instructions when… |
| --- | --- |
| Several agents share the procedure. | It defines this agent's role or voice. |
| The procedure needs reference files or scripts. | It is a short, stable rule for this agent. |
| Maintainers should update the procedure in one place. | It describes how this agent should use its equipped skills. |

Use the [skill library guide](https://docs.tale.dev/platform/workspace/skills) to create, import, edit, and share a bundle.

# Understand operation approvals
Source: https://docs.tale.dev/platform/approvals/concepts

An operation approval lets a person review a proposed connector write before it happens. For example, an automation can prepare an email, then wait for you to check its recipient and body before sending it.

## When a write waits

A live automation pauses when it reaches a connector write that the organization's policy requires someone to approve. By default, writes to external systems need approval; writes through internal, platform-authenticated connectors do not. The organization can change that rule for a connector or a specific action. See [Configure approvals](https://docs.tale.dev/platform/approvals/configure).

Reads do not request operation approval. **Test run** uses mock connectors, so it does not perform the external write or show its live approval card. Passing a test does not prove that the proposed live action is appropriate.

## Review the proposed operation

Open the automation's [run list](https://docs.tale.dev/platform/automations/execution-logs) and select the run marked **Waiting**. Its approval card names the operation, such as `imap-smtp.send`, and the node requesting it. **The step would call with** shows the exact input.

Check the destination, recipients, content, and identifiers against the intended task. Review sensitive details in the input before choosing:

- **Approve** allows this operation to execute when the run resumes.
- **Reject** prevents this operation and causes the step and run to fail.

The card does not edit the operation. If an input is wrong, reject it, correct the workflow or its input, and start a new run.

<Note>

Organization members can decide connector operation approvals. These cards do not route to a named reviewer or approver group; the decision is made on the run detail, which only Owners, Admins, and Developers open. When the run works a task, its card also appears on the task, where anyone who can open the task decides it. Other kinds of review can have stricter permissions.

</Note>

## Check what happened next

Approval permits execution; it does not guarantee that the connector succeeds. Check the resumed run's status, node result, and effects. A rejected run shows the rejection as its failure reason. The [audit log](https://docs.tale.dev/platform/admin/governance/audit-logs) records the decision and actor.

An existing pending approval stays pending if the policy is relaxed. The same operation in the same run keeps its recorded decision; starting a new run creates a new execution that is evaluated again. A finished or cancelled run cannot use an outstanding approval to perform its write.

## Distinguish approval from a question

An agent node may also pause because it needs information from a person. Answering that question supplies input; it is not approval of a connector write. [Approvals in workflows](https://docs.tale.dev/platform/automations/approvals-in-workflows) explains both interactions. Task reviews, controlled document reviews, and erasure requests have their own [review rules](https://docs.tale.dev/platform/approvals/configure#distinguish-the-other-human-decisions).

# Decide which actions need approval
Source: https://docs.tale.dev/platform/approvals/configure

An approval policy decides which connector writes must wait for a person during a live automation run. Review the workflow’s outbound actions before deploying it, especially when it sends messages or changes another system. [Approval concepts](https://docs.tale.dev/platform/approvals/concepts) explains the decision card itself.

## Start with the default behavior

Reads do not require operation approval. By default, writes to external systems, such as sending mail, posting to Slack, creating a GitHub issue, or writing to WebDAV, pause for approval. Internal operations, such as updating a task or saving a document in Tale, do not ask by default.

An allowed operation still runs under the relevant access rules. A missing approval card is not evidence that an operation is read-only: it may be an internal write or one that your organization explicitly auto-approves.

## Request a policy change

There is no per-action approval switch in the connector settings page. The organization’s approval policy can require or bypass approval for a connector or an individual action. A rule for one action takes precedence over a rule for its connector.

Ask the person managing your deployment to apply the [approval policy configuration](https://docs.tale.dev/self-hosted/configuration/approvals). Name the exact operation, why it should ask or proceed automatically, and which workflow uses it. Cloud administrators should coordinate the change with whoever manages their deployment.

An operation already waiting for approval keeps its pending decision after a policy change. Approve or reject that card explicitly; loosening the policy does not release it.

## Check a workflow before it goes live

1. Inspect each connector node and identify whether it reads or writes.
2. Confirm which writes the organization’s effective policy auto-approves.
3. Run **Test run** to check inputs and output against mocks.
4. During a controlled live run, inspect the operation and exact input on any pending card before deciding.

A mock test does not prove that a live approval will appear. Mock connectors do not change external systems and do not request approval.

## Distinguish the other human decisions

| Decision | Where to read the rules |
| --- | --- |
| Accept an agent’s task result | [Task automation](https://docs.tale.dev/platform/projects/task-automation). A person moves the result from In review to Done. |
| Approve a controlled document version | [Documents](https://docs.tale.dev/platform/knowledge/documents). The named reviewer decides on the frozen version. |
| Authorize an erasure request | [Data subject requests](https://docs.tale.dev/platform/admin/governance/data-subject-requests). A second Admin provides the required approval. |
| Answer an agent node’s question | [Approvals in workflows](https://docs.tale.dev/platform/automations/approvals-in-workflows). The run needs information to continue. |

These decisions have their own rules; the connector approval policy does not disable them. Chat has read-only retrieval tools and does not create operation approval cards.

# Respond to a waiting workflow
Source: https://docs.tale.dev/platform/automations/approvals-in-workflows

A run can wait for a decision before writing through a connector, or for information an agent needs to continue. Open the run detail to see which response is required. A waiting run has not finished, even if earlier nodes succeeded.

## Find the waiting run

Open the automation and its [execution logs](https://docs.tale.dev/platform/automations/execution-logs), then select the run marked **Waiting**. Check the version and run input so you know which execution you are reviewing.

An operation approval names a connector action and shows its proposed input. An agent question instead asks for an answer, with choices or a text field. These are separate interactions: answering a question does not approve a later write.

## Approve or reject a write

Read the operation and **The step would call with** carefully. Check the recipient or destination, the content, and any identifier that selects what will change.

Choose **Approve** to allow the operation. The run resumes and attempts the write; check the node result and effects afterwards. Choose **Reject** if the request is wrong or should not happen. Rejection prevents that operation and fails the run.

The card keeps telling you where the run stands when something goes wrong. If the approval cannot be loaded, the card says so and offers **Try again**; the run keeps waiting until someone decides. If your choice was not recorded, the card says so and keeps **Approve** and **Reject** available, so you can choose again. If someone else decided first, the card shows the decision on record.

A live run checks that the connector has a usable credential before it asks for approval: when none is configured, the node fails with that reason instead of waiting for a decision.

You cannot revise parameters on the approval card. Reject an incorrect request, fix the workflow or run input, and test the correction before starting a new live run. Changes to the approval policy do not release an already pending card. See [Approval concepts](https://docs.tale.dev/platform/approvals/concepts) for the decision lifecycle and [approval policy configuration](https://docs.tale.dev/self-hosted/configuration/approvals) for operator rules.

## Answer an agent’s question

When an agent node uses `ask_human`, the run detail displays **The agent needs your answer to continue**. If choices are offered, answer the questions on the card. For an open question, enter text under **Your answer**, then choose **Send answer & resume**.

Give the missing information directly. If the agent asks which document to use, name the document or provide its identifier rather than a general instruction to continue. The waiting node resumes with your answer, and the run may later need another answer or an operation approval. Owners, Admins, and Developers answer on the run detail. When the run works a task, the question also appears on the task, where anyone who can open the task answers it.

## Correct and test the workflow

Changing a workflow definition is separate from responding to its current run. Save a corrected version in the [workflow editor](https://docs.tale.dev/platform/automations/editor), test it against mocks, then deploy it when it is ready for live use. Saving a version does not revise a call already waiting for approval.

<Frame caption="Edit the workflow on the canvas; review a waiting execution on its run detail page.">

![The workflow editor shows the automation graph and a panel for configuring a selected node.](https://docs.tale.dev/images/platform/automation-editor-canvas.webp)

</Frame>

A mock test does not perform external connector writes or request their live approvals. For a practical walkthrough, follow [Build a workflow with approvals](https://docs.tale.dev/tutorials/editor/workflow-with-approvals). After a live decision, inspect both the run outcome and the [audit log](https://docs.tale.dev/platform/admin/governance/audit-logs); permission to proceed and successful execution are different results.

# Choose how to author an automation
Source: https://docs.tale.dev/platform/automations/assistant

Edit an automation directly on its canvas, or connect an external assistant through MCP to author it with Tale’s tools. Both routes save versions of the same workflow and use the same validation and deployment rules. You need Developer-level permission to author and deploy automations.

## Make a change in the visual editor

Open **Automations** and select the workflow. Select a node to inspect its input, model, code, or other configuration. Save the change with a version message, run a test, and deploy the intended version when its checks pass.

<Frame caption="Selecting a node opens its configuration beside the workflow graph.">

![The automation editor shows a workflow graph and the selected node’s input fields in a side panel.](https://docs.tale.dev/images/platform/automation-editor-canvas.webp)

</Frame>

[The workflow editor](https://docs.tale.dev/platform/automations/editor) covers these steps in detail, including inspecting a run and returning to an earlier version. The canvas does not include a conversational assistant panel.

## Use an external assistant through MCP

Configure your client with the endpoint under **Settings > API > MCP** and an appropriate organization API key. Give it the desired inputs, output, and the systems the workflow may change. Ask it to inspect existing automations and available capabilities before creating another one.

The [MCP endpoint](https://docs.tale.dev/develop/mcp-endpoint) provides documentation, validation, save, test, and deploy tools. Review the resulting workflow and its test output before deployment. A successful save creates a version; it does not make that version live.

## Keep runtime decisions separate

An agent node inside an automation performs work during a run. It is separate from the client you use to write the workflow. Similarly, an [approval](https://docs.tale.dev/platform/approvals/concepts) authorizes one pending operation during execution; it does not approve a proposed edit to the workflow definition.

Choose [the editor](https://docs.tale.dev/platform/automations/editor) for a change you want to make directly, or [MCP](https://docs.tale.dev/develop/mcp-endpoint) for authoring from your own client. Start from [an existing automation](https://docs.tale.dev/platform/automations/catalog) when a suitable one is already available.

# Built-in automations
Source: https://docs.tale.dev/platform/automations/builtin

Tale includes ten automation packages: three mailbox syncs, three inbox digests, two GitHub review workflows, and GitHub and GlitchTip issue imports. Each starts as version 1 and **Not deployed**. The issue importers run manually; the other packages include schedules. Inspect their inputs, model, connections, and writes before an Owner, Admin, or Developer deploys a version.

<Frame caption="The Automations catalog shows package names, version counts, and deployment status.">

![The Automations catalog lists GitHub and mail packages with one version and Not deployed status.](https://docs.tale.dev/images/platform/automations-catalog.webp)

</Frame>

## Start with one package

Open **Automations**, select a package, and inspect its nodes in the [workflow editor](https://docs.tale.dev/platform/automations/editor). Check that the required connector is connected and that the model used by any `llm` node is one your organization serves — the packages name a model your providers may not offer, and validation warns about it when you save; pick a served model in the node’s **Model** field before a live run. A test run uses mock responses; it validates the flow without proving access to your real mailbox or repository.

The packages are added when an organization is created. Existing versions are preserved when the shipped package changes; only its shipped name and description refresh. A deleted package stays deleted. Your edits create new versions, which you deploy separately.

## Sync mail into the Inbox

These workflows pull new messages into conversations every five minutes. Each declares the **Inbox** view: deploying one adds that view to [Home](https://docs.tale.dev/platform#home) and offers its connected mailbox in the compose form. Before deployment, Home has no **Inbox** view. A link to the inbox shows a setup notice instead: for Owners, Admins, and Developers it points to **Automations**; everyone else is told that one of those roles must deploy an email automation.

| Automation | Required connector | Schedule |
| --- | --- | --- |
| Sync Gmail emails | Gmail | Every 5 minutes |
| Sync Outlook emails | Outlook | Every 5 minutes |
| Sync emails via SMTP/IMAP | IMAP/SMTP | Every 5 minutes |

A pass reads the mailbox's Inbox folder only. It tells the mailbox's own replies from a customer's by the mailbox address, which the first pass learns from the connected account and keeps on the connection as its From address; IMAP takes it from the login.

Connect the matching mailbox first. After the first live run, inspect its [execution log](https://docs.tale.dev/platform/automations/execution-logs) and check that the expected messages appear in the **Inbox** view in Home.

Attachments are stored with their message, so you open and download them from the conversation. Gmail hands over each attachment only up to 3.5 MB: a larger one is still listed with its name and size, but you open it in Gmail.

## Triage the Inbox

These workflows work on the **Inbox** that the sync automations fill, every six hours. Each one reads the open conversations of its mail connector whose newest message is the customer's and that no earlier pass has judged since that message arrived — 25 per run, or the `limit` you set, up to 100. The model decides for each thread whether a person has to reply, and how urgent it is.

What a run changes:

- The verdict is recorded on each thread, with its reason, so the next run looks at the thread again only when the customer writes again.
- The thread's **priority** is set to the model's verdict — but only when nobody has set one. A priority a person chose stays as it is.
- Where a reply is due, a second model call drafts one and leaves it on the thread as a **Suggested reply**: a card above the composer, apart from anything a person typed. **Put in editor** hands the text to the composer to edit and send; **Discard** drops it, and the thread is not proposed on again until the customer writes again. Nothing is sent by the automation. A thread that already carries a suggestion keeps it.

The run's output lists what was read, the model's summary, the threads that need a reply with their Inbox links, and the drafts it left. A run with nothing waiting makes no model call. Deploy the matching sync automation first; without synchronized conversations there is nothing to triage.

| Automation | Required connector | Schedule |
| --- | --- | --- |
| Triage the Gmail inbox | Gmail | Every 6 hours |
| Triage the Outlook inbox | Outlook | Every 6 hours |
| Triage the IMAP inbox | IMAP/SMTP | Every 6 hours |

## Import and synchronize issues

**Import GitHub issues** and **Import GlitchTip issues** use the same form to turn source issues into tasks. They start without a schedule. These imports read the source and write Tale tasks; they never comment on, close, or change the upstream issue and do not start an agent.

1. Connect the source under **Settings > Connectors** and choose its default credential. GitHub needs repository access with read permission for issues. GlitchTip needs its instance URL and a token with `project:read` and `event:read`; a project-provisioning token alone cannot read issues. Self-hosted instances must be allowed by the deployment's connector host policy.
2. Open the importer and choose **Test run**. Select the **Tale project**, then enter the GitHub owner and repository or the GlitchTip organization and project slugs. Optional labels or a GlitchTip search narrow new issue discovery. **Maximum issues** accepts 1–500, defaulting to 100.
3. Inspect the test result, deploy the version, and choose **Run live** with the same destination and filters. A test run uses fixtures and creates no tasks; only a live run verifies the real connection.
4. Open **Runs** and select the run. **Imported tasks** links to the corresponding Tale tasks. If another batch remains, **Continue import** carries the same source, destination, and continuation position into the next run. To import every issue on a schedule instead, an automation keeps that position between its occurrences: see [Import every issue on a schedule](https://docs.tale.dev/platform/automations/triggers#import-every-issue-on-a-schedule).

Each synchronization discovers new issues and refreshes up to 500 linked issues, prioritizing the oldest checks. Linked issues are refreshed even when they no longer match the discovery filter. Run again to keep large collections current. GitHub pull requests are excluded. Repeating or retrying an import reuses the same source identity within a Tale project; repository and project renames update the canonical source link instead of creating a second task. Issues moved to another repository or source project remain linked and continue to refresh through earlier imports, provided the connection can read their new location.

A task's source card shows the latest source title, description and status separately. When it imports an issue, Tale cuts a title over 200 UTF-16 code units or a description over 20,000 (most emoji count as 2) to that length on the task, ending it in "…"; the source card and the linked issue keep the full text. Closing or resolving a source issue leaves the Tale task's status, title, description, assignee and priority unchanged. A source issue that becomes unavailable retains its last known snapshot; authentication and rate-limit errors fail the run rather than declaring the issue deleted. Review and complete work in Tale as usual.

## Review GitHub work

**Triage GitHub issues** reads open issues, scores whether they are actionable and their priority, and returns a ranked shortlist with reasons. It does not write to GitHub or create project tasks. Its default limit is 50 issues per run.

**Review GitHub pull requests** reads open pull-request diffs and posts findings as review comments. Its default limit is 10 pull requests per run. It does not approve or merge a pull request. Review the target repository before running it live, because a repeat run can add another comment.

| Automation | Required connector | Shipped schedule | Writes |
| --- | --- | --- | --- |
| Triage GitHub issues | GitHub | Daily at 07:00 UTC | None; read the run output |
| Review GitHub pull requests | GitHub | Every 30 minutes | A review comment per processed pull request |

Both workflows require `owner` and `repo`. In **Test run**, supply **Run input (JSON)** using your repository’s values:

```json
{
  "owner": "your-organization",
  "repo": "your-repository",
  "limit": 5
}
```

<Note>

The shipped GitHub schedules do not supply `owner` and `repo`; deploying alone does not make those scheduled runs valid. A schedule sends only `trigger` and `firedAt`, so the required repository input is missing and the start is refused. Run manually with the required input, or adapt the workflow’s schema and repository configuration before enabling scheduled execution. A refused scheduled start appears as `start_refused` on the [trigger](https://docs.tale.dev/platform/automations/triggers).

</Note>

Before deploying, read the resolved input and output of the test run. For a live run, also check connector permissions and any approval requirements. [Execution logs](https://docs.tale.dev/platform/automations/execution-logs) explains waiting, failure, and the recorded writes.

# Create or import an automation
Source: https://docs.tale.dev/platform/automations/catalog

Open **Automations** to find the workflows available in your organization. Only the Owner, Admin and Developer roles see this section and manage its automations. Start with a [built-in automation](https://docs.tale.dev/platform/automations/builtin) when it matches your task, or create a draft you can test before making it live.

Search by name or slug. For example, enter `Triage` to compare the shipped triage workflows.

<Frame caption="The list filtered by Triage shows four shipped examples with their version counts and deployment states.">

![Four filtered triage automations for GitHub, Gmail, IMAP and Outlook, with their versions, deployment states and the Create automation button.](https://docs.tale.dev/images/platform/automations-catalog.webp)

</Frame>

## Choose a starting point

Each row shows the automation’s name, project bindings, version count and deployed version, or **Not deployed**. Open it on the **Editor** tab to inspect the workflow. **General** holds its trigger and its projects: **Projects** controls which boards can use it; without project bindings, it serves the organization. **Projects** offers only the projects you can open, and saving keeps any binding to a project you cannot see. An automation bound only to such projects does not appear in your list. The **Version** selector beside the tabs shows its saved history; **Runs** shows recent executions.

The **Create automation** menu offers two routes:

| Choice | Use it when | What happens next |
| --- | --- | --- |
| **Blank (trigger + agent)** | You want to configure the workflow yourself. | Set the name, model, instructions and equipment, then choose when it runs. Creation opens the editor for further changes. |
| **Upload package** | You already have a workflow file or a reusable pack. | Tale validates the files and saves a draft version. |

Shipped automations are already installed when the organization is created. They still need configuration and a deployed version before automatic use. Follow [the workflow editor](https://docs.tale.dev/platform/automations/editor) to test inputs, inspect results and deploy deliberately.

## Import a package

A pack contains the required `workflow.yml`, an optional `automation.yml` manifest and, optionally, skill bundles:

```text
review-invoices/
├── workflow.yml
├── automation.yml
└── skills/
    └── invoice-rules/
        ├── SKILL.md
        └── references/
            └── checklist-rules.md
```

<Steps>

<Step title="Select the files">

Choose **Create automation > Upload package**. Upload the workflow and optional manifest as individual files, or select one `.zip` containing the pack. Use a zip when carrying skills; upload that archive on its own. Markdown notes outside `skills/`, dotfiles and build leftovers such as `node_modules/` and `__pycache__/` are ignored.

</Step>

<Step title="Choose the destination">

Under **Install into**, choose **Organization** or an existing project. A manifest declaring `scope: project` requires a project. Installing an existing automation into another project adds that binding; it does not remove previous ones. You can adjust the full set later under **Projects** on the automation's **General** tab.

<Frame caption="Upload package — the files or one zip, and where the automation installs.">

![The upload package dialog with its file drop zone and the Install into picker set to Organization.](https://docs.tale.dev/images/platform/automations-upload-dialog.webp)

</Frame>

</Step>

<Step title="Validate and save">

Choose **Upload package** and resolve any reported document, manifest or skill issues. Validation completes before the upload writes the automation and carried skills. A successful upload creates a draft; uploading the same automation again appends a version and preserves its history.

</Step>

<Step title="Review before deployment">

Choose **Later** to inspect and test the draft in the editor. The success dialog also offers deployment of the numbered version. Uploading alone does not change the live version. Configure required credentials and check the supplied skills before deploying.

</Step>

</Steps>

Keep a zip within 20 MiB compressed and 20 MiB expanded, with at most 500 files, 2 MiB per file and 20 skill bundles. If rejected for size, remove generated artifacts and split unrelated material into separate skills rather than increasing compression alone.

## Resolve skill conflicts

The manifest’s `skills` list must match the folders carried under `skills/`: undeclared folders and declared-but-missing bundles are rejected. Each bundle needs valid `SKILL.md` frontmatter with a `name` matching its folder. Carried skills follow the skill library's rules: a new skill belongs to the person uploading the package, and a replacement keeps its owner or belongs to the uploader if it had none. New or changed team lists may name only teams the uploader may share with; existing lists can stay unchanged. Tale checks every carried skill's audience before installing any of them.

```yaml
# automation.yml
name: Review invoices
skills:
  - invoice-rules
```

New bundles are installed into the organization’s [skill library](https://docs.tale.dev/platform/workspace/skills), and identical bundles remain unchanged. Different content pauses the upload and lists the affected slugs. Confirm replacement only after reviewing them: the package replaces those shared bundles, and the previous `SKILL.md` remains in each skill’s history. No automation or skill is written before that confirmation.

A workflow may also refer to library skills it does not carry. If one is missing, the upload reports a warning; install an accessible bundle before running the agent that needs it. A saved draft does not prove all its dependencies are ready.

## Configure a project through package forms

A manifest can declare forms that appear when someone selects the automation’s task template. Values belong to the project, so two projects can use the same automation with different policies.

```yaml
# automation.yml
settings:
  folder: Setup
  forms:
    - file: validation-policy.yaml
      title: Validation policy
      required: true
      fields:
        - key: method
          label: Validation profile
          type: select
          default: strict_rules
          options:
            - value: strict_rules
              label: Strict checklist
```

A required form appears before the task’s own fields if that project has not been configured. **Save and continue** writes the forms and proceeds to task creation. Later, **Settings** reopens them as tabs; a dot marks unsaved changes, and **Save** writes every changed form. Closing with unsaved edits asks for confirmation.

Saving replaces the form’s flat YAML file, such as `Setup/validation-policy.yaml`. Existing values prefill the form, including values uploaded by hand. Supported field types are `text`, `number`, `boolean` and `select`; stored values are strings. Text fields can specify a `pattern`, and per-entry `i18n` blocks localize titles, labels, help and options. Keep nested structures and lists in separate files the workflow reads.

## Supply reference files through an upload form

An upload form manages files directly instead of producing YAML:

```yaml
settings:
  folder: Setup
  forms:
    - kind: uploads
      title: Reference documents
      subdir: reference
      accept: ['.pdf', '.json']
      match: '\.(pdf|json)$'
      requireFolder: true
```

`subdir` chooses a subfolder of the settings folder. `accept` limits extensions offered by the picker; `match` filters listed names case-insensitively and rejects uploads that would not appear. With `requireFolder: true`, select or create a subfolder before uploading, for example one per reporting period.

Uploads apply immediately and have no **Save** action. They never block task creation. Runs read the folder’s current contents, so finish preparing the reference set before starting work that depends on it.

## Define what the reviewer should receive

The manifest can name deliverables in the task’s **Outcome** area. Declared files stay in the specified order; other attachments and working files remain under **Files**.

```yaml
subjects:
  task:
    outcome:
      files:
        - return.xml
        - report.md
        - name: audit-summary.md
          optional: true
```

A required file appears as **Not ready yet** until a run files it. An optional file appears only once it exists. Patterns support `*` and `?`, such as `return-*.xml`. Without declarations, the outcome shows all files filed by runs, newest first. Use a short explicit list when the reviewer needs to distinguish the final report from supporting work.

## Ask before an approval that decides more

**Approve** closes the task in one click. When approving means more than closing the task, declare that consequence, for example when an integration reports the approval to a client as a filing. **Approve** then asks first and shows your sentence:

```yaml
subjects:
  task:
    review:
      requestChanges: true
      approve:
        confirm: Approving tells the client this return has been filed with the tax authority. Approve only after you have filed it.
        i18n:
          de:
            confirm: Mit der Freigabe erfährt der Kunde, dass diese Abrechnung bei der Steuerverwaltung eingereicht ist. Gib sie erst frei, wenn du sie eingereicht hast.
```

Without `approve`, **Approve** stays a one-click close. Translate the sentence under `i18n`; a locale without its own sentence uses its base language, then the English one.

# Automation concepts
Source: https://docs.tale.dev/platform/automations/concepts

Use an automation for work that follows a repeatable process. Its workflow describes the steps; saved versions preserve each revision, deployment chooses the version used for live runs, and a trigger can start it on a schedule or event. You can inspect each run to see its input, results, and operations.

Prefer to watch first? Episode 5 opens the triage automation end to end and decides an approval card on camera, captions included — recorded on the earlier version, where the card sat in chat; in this version it sits on the run's detail page.

<Video src="https://docs.tale.dev/videos/en/tutorials/ep5-automations/ep5-automations.en.mp4" poster="https://docs.tale.dev/videos/en/tutorials/ep5-automations/ep5-automations.en.webp" captions="https://docs.tale.dev/videos/en/tutorials/ep5-automations/ep5-automations.en.vtt" lang="en" title="Episode 5 — Automations & approvals" caption="Episode 5 — Automations & approvals (2:42)">

</Video>

## The workflow document

An automation’s `name` identifies it. Use lowercase slug segments separated by dashes; `/` groups related automations into folders, as in `billing/dunning-reminder`. The first segment must not be a reserved page name: `asks`, `builder`, `catalog`, `listing`, `metrics`, `runs`, `serving-preview`, or `upload`.

The document also contains a `description`, an `inputs` JSON Schema for the data a run receives, `nodes` for the steps, and an `output` expression for the result. Its `tests` describe examples and expected outcomes that are checked before deployment.

```yaml
name: billing/dunning-reminder
description: Remind a customer about an overdue invoice.
inputs:
  type: object
  properties:
    invoiceId: { type: string }
  required: [invoiceId]
nodes:
  - id: invoice
    type: transform
    input:
      id: '{{ input.invoiceId }}'
    code: 'return { id: input.id, daysLate: 14 };'
  - id: message
    type: llm
    model: openai/gpt-4o-mini
    prompt: 'Write a polite reminder for invoice {{ nodes.invoice.output.id }}.'
output:
  text: '{{ nodes.message.output.text }}'
tests:
  - name: builds a reminder
    input: { invoiceId: 'inv-1' }
```

The `ui` block stores canvas positions. Moving a node changes the layout, without changing its execution.

### Edges are derived, not declared

There is no edge list. One node reads another by referencing it — `{{ nodes.invoice.output.id }}` — and that reference _is_ the edge the canvas draws. Execution order is a topological sort over those derived edges, which is why deleting a reference also removes an arrow, and why two nodes that read each other are refused as a cycle.

Templates use a single `{{ }}` JavaScript-expression grammar over `input`, `nodes.<id>.output`, and, inside an iterating node, `item` and `index`.

### Control flow rides on the node

Branching and looping are fields on a node rather than separate step types, so the canvas shows them as badges on the box they affect.

| Field                        | What it does                                                             |
| ---------------------------- | ------------------------------------------------------------------------ |
| `when`                       | Run the node only when the expression is truthy; dependents skip with it |
| `elseOf`                     | Run exactly when the named node was skipped by its own `when`            |
| `forEach`                    | Run once per item of a collection, with `item` and `index` in scope      |
| `repeatUntil` / `maxRepeats` | Re-run until the expression is truthy, capped (default 5, maximum 20)    |
| `onError`                    | `fail` halts the run; `continue` records the error and skips dependents  |

### Node types

Four types are built in, and every connector action and platform native — knowledge search, document operations — joins the same table alongside them.

**`transform`** runs pure JavaScript to reshape data. It has no network and no imports: the body reads the node's resolved `input` and must return a value.

**`llm`** calls a language model with a templated prompt. `model` is required and always explicit — an automation never picks one on your behalf (the chat composer's Auto is a chat-only affordance). The output is `{text}`, or the schema-shaped object when the node declares an `outputSchema`.

**`agent`** runs one turn of a coding agent (Claude Code, Codex, and the other harnesses) in the sandbox. It reads staged `files`, uses `skills`, brokered `connectors`, granted platform `tools`, and injected `secrets`, and returns `{text, files, status}`; `model` is required. When an admin has turned on [image generation](https://docs.tale.dev/platform/admin/governance/content-models#let-agents-generate-images), it can also create images, which come back among its `files`. Reach for `llm` when a one-shot completion is enough, and for `agent` only when the step needs tools, files, or several turns — a live agent node runs as an asynchronous turn, so it sits at the top level rather than inside a `subautomation` and does not iterate with `forEach`.

**`subautomation`** runs another saved automation as a single node, its `automation` field naming `"name"` or `"name@version"`. Without a version it uses the deployed one, and nesting is capped at three levels.

### Structured and unstructured output

A **structured** output has named fields that you can reference with `nodes.<id>.output.<field>`. An **unstructured** output is free text. Reference it through `nodes.<id>.output.text` in a string expression; do not treat it as an object with additional fields.

A tool without an output schema is unstructured. To turn its text into structured data for later steps, use an `llm` node with an `outputSchema`. Validation errors identify the invalid reference and the fields or context that are allowed. Correct that reference before saving again.

## Versions never change

Saving creates a new version instead of overwriting the previous one. Versions are numbered from 1 for each automation and carry the author’s change message. An existing version’s workflow stays unchanged.

A running automation keeps the version it started with, so later edits do not alter its steps. When inspecting an older run, open its recorded version to compare the input and workflow. This immutability is distinct from retention: deleting an automation or its history can remove the records.

## Deploying is a separate act

One version per automation is the deployed one, and that is the version triggers run. Promoting a version, or rolling back to an earlier one, is a single act that overwrites no history — the version list stays exactly as it was and only the pointer moves. An automation may also have no deployment at all and live purely as drafts.

A version with a failing test cannot be deployed; a version whose tests pass, or that carries no tests at all, can. Tests are stored with the document: each has a name, an input, and expectations about the output and about the effects the run should produce. Whether a version's tests passed is recorded when it is saved, so promoting reads that recorded fact instead of re-running the suite.

<Note>

A live run needs a deployed version. You can still test a saved draft with **Test run** before deployment.

</Note>

## What starts a run

Start a saved version manually in test mode, or run the deployed version live. For automatic starts, configure one of three trigger kinds: a schedule with a cron expression and IANA timezone, a webhook URL protected by a token, or a named platform event.

The trigger belongs to the automation’s name. Deploying another version keeps its trigger configuration and webhook URL while changing the version used by subsequent starts. Disable the trigger when you need to pause automatic runs. [Workflow triggers](https://docs.tale.dev/platform/automations/triggers) explains timing, authentication, and the input each kind supplies.

## What a run records

A run records its status (`queued`, `running`, `waiting`, `success`, `failed`, or `cancelled`), mode, starting event, input, output, and a checkpoint for each completed node. Its trace explains the steps the engine attempted.

If processing yields before the workflow finishes, the same run resumes from its checkpoints without repeating completed nodes. The effects list records connector writes; it is not a complete inventory of changes made through a sandbox or other direct tools. Run history remains subject to deletion and retention settings.

**Mock** mode simulates external operations for authoring feedback. **Live** mode can perform them and requires developer-level permissions to start. Use [Execution logs](https://docs.tale.dev/platform/automations/execution-logs) to inspect the saved version, resolved inputs, errors, and recorded effects.

## Where a human decides

An approval pauses the run in `waiting` before a protected write. Approving permits the engine to attempt that write; it does not guarantee success. Rejecting blocks it and fails the run. A question also pauses the run, but asks for information rather than permission.

A `waiting` status can also mean that an agent is still working, that an agent step waits for a sandbox slot to start, or that a node is polling a condition. Check `waitingFor`: `approval` and `ask` require a person, while `agent`, `room` and `repeat` normally resume automatically. [Approvals in workflows](https://docs.tale.dev/platform/automations/approvals-in-workflows) explains how to inspect and answer each human request.

## Choose a chat, task, or automation

| Need | Use |
| --- | --- |
| Ask a question and discuss the answer | Chat |
| Produce a reviewed result with an owner | A project task, optionally assigned to an agent |
| Run several dependent steps or react to a schedule, webhook, or event | An automation |

Check the [built-in automations](https://docs.tale.dev/platform/automations/builtin) before building. A webhook starts an automation; it is not a separate kind of project agent.

## Putting the model to work

The workflow, versions, deployment, and trigger are separate parts of one automation. Follow [The workflow editor](https://docs.tale.dev/platform/automations/editor) to test and deploy a change; use [Execution logs](https://docs.tale.dev/platform/automations/execution-logs) to inspect what happened.

# The workflow editor
Source: https://docs.tale.dev/platform/automations/editor

Use the workflow editor to change what an automation does and decide which saved version runs live. You need Developer, Admin, or Owner permissions to make changes. Saving, testing, and deployment are separate steps: editing a draft leaves the deployed version in place.

Open **Automations**, then select an automation. It opens on **Editor**. To create one first, use [Create or import an automation](https://docs.tale.dev/platform/automations/catalog).

| Tab | Use it to |
| --- | --- |
| **Editor** | Change the workflow, test a saved version and choose what runs live. |
| **General** | Choose what starts the automation and which projects can use it. |
| **Runs** | Inspect recent executions and open a run’s full record. |

The **Version** selector stays at the right of the Editor, General and Runs tabs on desktop and mobile. Open it to read version messages, dates, test results and the live marker, then select a row to open that version. On desktop, run actions sit beside the tabs together with **Save** and **Discard**; on **General**, only **Save** and **Discard** sit there. A dot on a tab marks its unsaved changes. Leaving the tab or switching versions asks you to resolve those changes first.

On a phone, opening an automation starts with compact navigation. The editor canvas fills the available height, and its run and deploy controls sit inside the canvas beside the zoom controls. Selecting a node opens its fields — and Save and Discard — in a panel at the bottom of the screen.

<Frame caption="On a wide screen, select a node to inspect its fields beside the canvas.">

![The workflow editor shows connected nodes and the selected node’s fields beside the canvas.](https://docs.tale.dev/images/platform/automation-editor-canvas.webp)

</Frame>

To switch without returning to the list, click the current automation's name in the breadcrumb trail. The menu includes every automation in the organization, even after switching to another project, except one bound only to projects you cannot open. Automations with no project assignments appear first, followed by those assigned to projects, with a horizontal divider between the two groups. Search by name or slug and select an entry. The switch keeps the current tab; from a run’s detail, it opens the other automation’s **Runs** list. A selected version number does not carry over: **Editor** opens the other automation’s latest saved version.

## Read the canvas

Each box is a node. Its label identifies the step and type; **Reads** lists the nodes whose outputs it uses. Arrows come from references such as `{{ nodes.draft.output.text }}`. Edit the reference to change the dependency. The canvas does not create dependencies by drawing an arrow.

Badges show conditions and loops: `when`, `else of`, `for each`, `repeat until`, and `continue on error`. A cycle warning means two or more nodes depend on one another; remove the circular reference before saving a runnable version.

## Edit a node

Select a box to open its fields. On a wide screen, the panel opens beside the canvas; until you select a node, the canvas takes the full width. On narrower screens, the fields open in a dialog over the canvas. A `transform` has **Code**; an `llm` has prompt, model, and output-schema fields; an `agent` also has harness and equipment. The **Model** picker of an `llm` or `agent` node lists the models your organization’s connected providers serve; a model that is not listed can still be typed, but validation warns that a live run would fail at that node until its provider is connected. **Input** contains JSON values and references passed to the node. Incomplete JSON is reported and does not update the node.

Open **Control flow** for conditions and iteration; it is already open on a node that has one. Use **Close** to return to the canvas. On a wide screen, clicking the empty canvas or pressing Escape outside a text field also closes the panel. The automation's trigger and project settings are on the **General** tab. [Automation concepts](https://docs.tale.dev/platform/automations/concepts) explains the node types and expression rules.

## Save and test a version

1. Edit the required fields and click **Save**.
2. Enter a **Version message** that explains the change, then **Save version**. This appends a version and preserves earlier ones. If someone saved another version while you were editing, Tale refuses the save and asks: **Discard my changes and reload** shows the newer version, **Save anyway** appends your version on top of it — the newer one stays in the version history, but the latest version is then yours.
3. Click **Test run**. If the workflow declares an input schema, fill **Run input (JSON)** in the dialog. Expand **Input schema** to inspect required fields and types. Invalid JSON or a schema mismatch prevents the start.
4. Start the test, switch to the **Runs** tab and inspect its row. Open it to compare the resolved input, output, and proposed operations with your expected result.

For a workflow requiring `owner` and `repo`, an input might be:

```json
{
  "owner": "your-organization",
  "repo": "your-repository"
}
```

Use the workflow's actual schema. A field typed as a number must receive a JSON number, not a quoted string. Where a project selector is offered, check the scope before starting.

**Test run** uses the selected saved version with deterministic mocks. It does not send mail or change external records. A draft can be tested before it is deployed; a successful mock does not verify live credentials or outside services.

<Frame caption="For an input-driven workflow, supply JSON and inspect its schema before starting the test.">

![The Test run dialog shows owner and repo JSON values and the expanded input schema.](https://docs.tale.dev/images/platform/automation-run-input.webp)

</Frame>

## Deploy and run live

Choose the tested version under **Version** and click the deploy button beside it, which names that version, such as **Deploy v3**. The **Live** badge marks the deployed version. A version whose saved tests failed cannot be deployed; correct the cause and save a new version.

**Run live** starts the deployed version, even if you are viewing another one. Its confirmation shows the scope and, when required, **Run input (JSON)** for that deployed version. Check both before confirming. Live runs may act on connected systems and may wait for an [approval](https://docs.tale.dev/platform/approvals/concepts).

A trigger also runs the deployed version. Set it up only when you are ready for repeated or externally initiated execution; see [Automation triggers](https://docs.tale.dev/platform/automations/triggers).

## Diagnose a result

**Show last run** overlays run states on the canvas. Select a node to see **In this run**, its **Resolved input**, **Output**, and effects. This is often enough to find a wrong reference: compare the input received by the failed node with the output of the node it reads.

Switch to **Runs** and open a row for the full record. The tabs remain visible with **Runs** active; **Editor** returns to the workflow. Check whether it was a test or live run and inspect already completed operations before starting another run. [Execution logs](https://docs.tale.dev/platform/automations/execution-logs) explains waiting, failures, automatic retries, and stopping.

## Roll back or delete

To roll back, open **Version** at the right of the tab strip, read the version messages and select an earlier version. Its row opens **Editor** at that version; click its deploy button there, such as **Deploy v2**. Future starts use it; version history remains intact. A version message such as “Restore the previous recipient mapping” makes that choice easier to review.

To delete the automation, return to the list, open its row menu, and select **Delete**. Read the named confirmation. All versions, deployment, trigger, and project bindings are removed. An unfinished run blocks deletion; stop it or let it finish first. Past runs remain subject to retention. Deleting an automation does not undo the actions its runs already performed.

# Read automation runs and recover from failures
Source: https://docs.tale.dev/platform/automations/execution-logs

Open an automation, switch to its **Runs** tab and select a row to understand what happened. Start with its status, version and mode, then inspect the relevant node. A successful test run proves the workflow’s mocked execution; it does not prove that a real external account will accept the same action.

<Frame caption="A finished test run: its status, mode, version, starter, and times above the workflow, with each node's result.">

![The run page of a test run of Triage GitHub issues, marked Succeeded, Test, and v1 and started by you, with its start and finish times above the workflow graph, where the issues, open issues, score, and report nodes each show Ran; the run's effects list begins below the graph.](https://docs.tale.dev/images/platform/automation-run-detail.webp)

</Frame>

## Read the run’s state

The **Runs** tab lists the latest 50 runs you can see, newest first. Owners, Admins, and Developers see the organization’s own runs; a run in a project, and any question it waits on, appears only to those of them who can open that project. Each row identifies its version, time, mode and starter, or gives a failure or waiting reason. The detail shows the workflow with node results and run timing; an unfinished run has no completion time. The tabs stay visible while you inspect a run. Choose **Runs** to return to the list or **Editor** to change the workflow.

| Status | Meaning | What to do |
| --- | --- | --- |
| **Queued** | Accepted, waiting for execution. | Wait and inspect capacity if it does not progress. |
| **Running** | The engine is processing the workflow. | Follow node progress. |
| **Waiting** | A decision, reply, agent turn or polling condition is outstanding. | Read what it is waiting for. |
| **Succeeded** | Reached nodes completed and the workflow produced its output. | Review output and effects. |
| **Failed** | Execution ended with an unhandled failure. | Open the failed node and read its error. |
| **Stopped** | The run was cancelled. | Inspect work already performed before restarting. |

A waiting approval or question requires a person; a running agent or polling node may continue without you. A decision or answer can also be refused or expire. Use the displayed reason, not **Waiting** alone, to decide whether action is needed. [Approvals in workflows](https://docs.tale.dev/platform/automations/approvals-in-workflows) explains the decision controls.

## Inspect the node that matters

Select a node on the run’s canvas. **Resolved input** shows the actual values after template evaluation; **Output** shows what the step returned. These fields distinguish a bad reference from a service failure.

Node states include **Ran**, **Skipped**, **Failed**, **Never reached**, **Not reached yet** and, on a stopped run, **Stopped here** for the node the run was on when it was stopped. A skipped node may have a false condition, an unmet dependency, an alternate branch or a failure rule that permits continuation. Do not assume every skipped node is an error.

For example, a reminder node may receive a customer name but an empty invoice ID. Inspect its upstream output: if the record now uses another field, correct the reference there rather than replacing the mail credential. Verify the corrected resolved input in a new test run.

Applications reading the [run API](https://docs.tale.dev/develop/api-reference) also receive `failureCode` when a failed run has a classified cause. For example, `approval_rejected` means a person refused the operation, while `llm_output_invalid` means a model response did not match the required structure. Historical failures can lack a code. Use it to route an investigation; it does not establish that retrying is safe or will succeed.

## Check what the run changed

The effects list records connector writes, with the node, connector and input. A test uses deterministic stand-ins; live actions can change external systems. The run explicitly reports when it has no recorded effects.

Read effects before retrying. A failure later in the graph does not undo an earlier message or update. For delivery-sensitive work, confirm the result with the receiving service as well. Effects are retained with the run until deletion or retention removes that record; they are not a permanent independent archive. Deleting the automation keeps its runs: a run page still opens, marked with the deletion date and drawn from the run’s own trace, until retention removes it.

## Understand continuation and automatic retries

The engine checkpoints completed nodes and resumes after those checkpoints when execution continues. An unfinished run whose continuation was lost can be picked up after a grace period. A separate run starts with separate checkpoints and can repeat writes, so “run again” is different from resuming the existing run.

An eligible agent-step failure can receive up to three automatic retries after the original attempt. Upstream checkpoints remain intact, and the header reports **Auto-retry 1 of 3** and subsequent attempts. An attempt that performs at least fifteen minutes of execution refreshes that retry budget. Subscription pools can choose another account for a new attempt. When a subscription broker refreshed the account while the step worked and the provider rejected the old token, the retry continues on a fresh token without using one of the three retries; a third such interruption in a row counts like any other failure. When the step could not start because every account of the pool was cooling down after a rate limit, the retry starts once the first account is available again, at most a minute later, and continues the conversation the refused attempt was to resume. That wait uses one of the three retries unless the refused attempt was itself retrying a rate-limit failure. When the failed turn had announced its conversation handle, the retry resumes that conversation over the preserved workspace — the agent continues where the cut landed instead of reasoning from the start; a turn that died before announcing one, or whose sandbox session is gone, starts fresh. A Gemini CLI step always starts fresh, because that runtime cannot resume a conversation in which it ran a tool; [Choose an agent runtime](https://docs.tale.dev/platform/agents/harnesses) explains the exception.

An agent step also fails when its model returns nothing at all: no text, no tool call and no generated tokens. A model server can answer this way when it breaks down mid-answer. The run then reports “The model returned an empty answer, so the agent did nothing this turn.” This failure receives those retries too. A step whose model only used tools, or reported generated tokens but no visible text (reasoning, for example), has answered and does not fail this way.

An exhausted budget, full execution-window timeout, or expired question does not receive those retries. Each attempt consumes its own resources; retrying does not erase earlier charges. If repeated attempts cannot fix the cause, stop the run and correct the dependency before starting another.

## Stop or repair the workflow

Select **Stop the run** for an unfinished run you want to cancel, and confirm. Cancellation stops further work at the engine’s execution boundaries; it does not roll back completed effects. If the run finishes before the cancellation reaches it, its completed outcome is retained.

To repair a document problem, return to the editor, change the relevant input or node, and save a version with a useful message. Run a test with representative input and inspect the values and output, not only the success badge. Deploy that version when the result is ready. Scheduled and webhook starts then use the deployed version; an older failed run remains a record of the old version.

If the run never started, inspect its [trigger](https://docs.tale.dev/platform/automations/triggers). A disabled trigger, missing deployment or rejected input can explain the absence of a run altogether.

# Start automations automatically
Source: https://docs.tale.dev/platform/automations/triggers

Use the **Trigger** section on the automation’s **General** tab when work should start on a schedule or in response to an event. Every trigger starts the deployed version in live mode. Before enabling one, test the workflow with the input shape it will receive and check that its external actions are ready.

<Frame caption="The General tab of a shipped package: its schedule trigger is enabled, but it starts nothing until a version is deployed.">

![The General tab of Triage the Gmail inbox with a Schedule trigger switched on, the cron expression 0 */6 * * * described as every six hours and not starting until a version is deployed, the UTC timezone, and an empty Projects selector below.](https://docs.tale.dev/images/platform/automation-general-trigger.webp)

</Frame>

## Choose how the automation starts

| Trigger type | Use it for | Input passed to the run |
| --- | --- | --- |
| **Schedule** | Periodic work at a local time or regular interval. | `{ trigger: "schedule", firedAt: <epoch ms> }` |
| **Webhook** | A delivery from another system. | `{ trigger: "webhook", payload: … }` |
| **Platform event** | A named event inside the organization. | `{ trigger: "event", event: "…", payload: … }` |

An automation has one configured trigger at a time. Changing its type replaces the previous binding. Replacing a webhook revokes its URL immediately; configuring another webhook later does not recover that credential.

An API or MCP client can also start work without a configured trigger. Its API key and project permissions authorize the request, and it sends the workflow’s input directly. See the [API reference](https://docs.tale.dev/develop/api-reference).

## Set a schedule

<Steps>

<Step title="Open the trigger settings">

Open the automation, then its **General** tab. Without a binding, the **Trigger** section says that the automation runs only when started by hand or through the API; choose **Add trigger**, then **Schedule** under **Trigger type**. A new trigger starts with **Enabled** off — keep it off while preparing a workflow that should not start yet.

</Step>

<Step title="Enter the timing">

Fill **Cron** and choose **Timezone**. A cron expression has five fields: minute, hour, day of month, month and day of week. Use an IANA timezone such as `Europe/Zurich` when local business hours matter; an unspecified timezone means UTC.

</Step>

<Step title="Check and save">

Review the next occurrence shown for a valid expression: it is the minute the schedule will actually start, daylight-saving changes included. Then click **Save** beside the tabs. Confirm that the workflow’s deployed version accepts the schedule input above. When ready, turn on **Enabled** and save again. Check the next started run under **Runs**.

</Step>

</Steps>

```text
*/15 * * * *     every fifteen minutes
0 9 * * 1-5      09:00 on weekdays
0 6 1 * *        06:00 on the first of the month
30 8 1 * 1       08:30 on the 1st and on every Monday
```

Fields support `*`, numbers, ranges, steps and comma-separated lists. Both 0 and 7 mean Sunday. If both day-of-month and weekday are restricted, either match is enough; the last example runs on Mondays as well as the first day of each month.

Local time follows the timezone’s daylight-saving rules. A 09:00 Zurich schedule stays at 09:00 locally. Timing has one-minute resolution. Missed occurrences during an outage are not replayed; work resumes at the next occurrence. Impossible calendar dates are rejected when saving.

## Receive a webhook

Choose **Webhook**, then save to generate the credential. Copy the full URL when it appears: the token is shown once and only its hash is stored. The section supplies an organization URL and a project URL pattern. Use the project URL for an active project in which the automation is installed; an automation with project bindings cannot run through the organization-only URL.

Post a small payload to the URL. JSON becomes `payload` inside the input wrapper, not the workflow’s top-level input. Other request bodies pass through as text. The limit is 256 KiB; upload large documents separately. An accepted request returns a run ID without waiting for completion.

For example, a posted `{ "invoiceId": "inv-1" }` reaches the workflow as:

```json
{
  "trigger": "webhook",
  "payload": { "invoiceId": "inv-1" }
}
```

Use a delivery ID, such as `Idempotency-Key` or the sender’s supported delivery header. Repeating that ID within 24 hours returns the original run. Without an ID, an identical body on the same URL within two minutes is treated as a duplicate. Send distinct IDs if identical payloads represent separate work. [Webhooks](https://docs.tale.dev/develop/webhooks) lists supported headers, project routes, errors and response formats.

<Warning>

The URL authorizes a run. Store it as a credential and share it only with the sending system. **Rotate token** generates a replacement and invalidates the old URL; removing or replacing the trigger also revokes it. Update the sender after a rotation.

</Warning>

## React to a platform event

Choose **Platform event**, select **Event name**, then save and enable when ready. Match the workflow’s schema to the `trigger`, `event` and `payload` wrapper in the table. Events raised by automation runs do not fire triggers, preventing a workflow from repeatedly starting itself through its own changes.

A workflow expecting required top-level fields such as `owner` and `repo` cannot accept schedule metadata or a wrapped webhook unchanged. Adapt its input schema and references, or use an API-started run that supplies those fields. The trigger settings do not provide arbitrary saved input fields.

## Start a project agent on a schedule

A schedule can put one of a project's existing agents to work: a standing task the agent reports on at every occurrence, or recurring work you would otherwise start by hand. Install the automation in the task's project, add a `task.start_agent` step that names the task, and give the automation a schedule. Each occurrence starts the task's agent assignee, or first assigns the task to the agent `agentId` names, which must belong to the same project. `feedback` is the message the run addresses first, such as the occurrence it serves:

```yaml
nodes:
  - id: start
    type: task.start_agent
    input:
      taskId: <the task's ID>
      moveToInProgress: false
      feedback: 'Scheduled occurrence {{ input.firedAt }}.'
```

The step answers the run it started, and the task's timeline lists that run as **automation** with a link to the automation run. When it starts nothing, the step still succeeds and says why, so the occurrence is recorded rather than queued:

| Answer | Meaning |
| --- | --- |
| `started: true` | The agent's run started; `runId` names it. |
| `already_running` | The task's previous run is still working and carries the work. Nothing new starts, and the occurrence does not wait behind it. |
| `in_review` | With `moveToInProgress: false`, the card waits for its captured reviewer, a person or an agent. Nothing is assigned or started, and the review keeps that recipient. |
| `closed` | With `moveToInProgress: false`, the card is **Done** or **Cancelled** (`taskStatus`). Nothing is assigned or started. |
| `agent_busy` | The agent is working another task (`busyTaskId`). An agent works one task at a time in its workspace. |
| `blocked` | A task this one depends on is still open (`blockedBy`). |
| `paused` | The task took three starts by automations and agents within the last hour, ordinary automatic retries included. One broker cooldown immediately after the same agent’s HTTP 429 adds no start; consecutive cooldowns still count. `retryAfter` says when the hourly count permits another start; other admission checks still apply. |

A run a schedule starts answers to no person. It works with the agent's configured instructions, secrets and tools, and its spend counts as automation spend against the organization's limits. Connector actions it asks the platform to run act for nobody, so they are refused. It keeps that authority only while the schedule may act in the project: turning the schedule off, removing it, or uninstalling the automation from the project stops the next start, fails a run that has not launched yet, and ends the workspace tools of a run in progress. A run a person starts from the automation answers to that person instead, as long as they can edit the project. A run a webhook or a platform event started cannot start agents, and an automation that is not installed in the task's project cannot reach its agents.

`moveToInProgress` decides what happens to the card. By default the card moves to **In progress** and the result waits at **In review** for its [configured reviewer](https://docs.tale.dev/platform/projects/tasks#review-default), as after **Start agent**; a review still pending on the earlier work is withdrawn, never approved. With `false` the card stays where it is and the run asks for no review, which suits a standing task in **To do**. The run keeps that choice to its end: when it completes, its report and files arrive as usual, and the card is neither moved nor sent for review, even if someone moved it to **In progress** meanwhile. That start only runs under open work (**Backlog**, **To do** or **In progress**): a card waiting at **In review** answers `in_review` and a closed one `closed`, so the card never presents earlier work for judgment, or as finished, while new work runs under it.

A retryable failure can be retried automatically while the task keeps its original status and assignee, with no later status, assignment, archive or review decision. Changing a value and then changing it back still ends that retry; comments do not. The attempt limits, schedule permissions and workspace checks still apply. A later scheduled occurrence can start fresh work when eligible.

### Import every issue on a schedule

An issue import reads at most one batch per run, up to 500 issues, and answers where the next batch starts. A person continues it with **Continue import**; a schedule keeps the position between its occurrences instead, so each occurrence imports one batch from where the last one stopped until every open issue has been read, and the occurrence after that starts the next pass. Read the position with `task.get_import_cursor`, pass it to the importer, and save the importer's `nextCursor` with `task.save_import_cursor`:

```yaml
nodes:
  - id: position
    type: task.get_import_cursor
    onError: continue
    input: { projectId: <the project's ID>, externalSystem: github, source: owner/repo }
  - id: issues
    type: subautomation
    automation: github-import-issues
    onError: continue
    input:
      projectId: <the project's ID>
      owner: owner
      repo: repo
      limit: 500
      cursor: '{{ nodes.position.output.cursor }}'
  - id: progress
    type: task.save_import_cursor
    onError: continue
    input:
      projectId: <the project's ID>
      externalSystem: github
      source: owner/repo
      revision: '{{ nodes.position.output.revision }}'
      next: '{{ nodes.issues.output.nextCursor ?? "" }}'
```

`source` is your name for the listing; automations that name the same source share one pass. The read also answers `revision`, the position's compare token, and the save hands it back: the position advances only while it is still at that revision. Every saved batch, every drain and every restart moves the revision on, and a revision never repeats, even when the cursor text does. An import that fails saves nothing, so the next occurrence retries the same batch. A save from any earlier revision is refused (`conflict`) and writes nothing, whether it comes from an overlapping run, from a run delayed past the end of its pass, or from a run that still holds a position from before a restart. After three reads of one position without a save, the next read starts the pass over (`restarted`) instead of retrying a position the source keeps refusing, for example after the repository was renamed. The save answers `batch` and `drained`, which a receipt can report. Each run also refreshes up to 500 issues imported earlier, the longest-unchecked first, so a large collection is refreshed over several occurrences.

## Diagnose a missing start

First check **Enabled**, the deployed version and the last-fired information. Then inspect any recorded skip reason:

| Reason or symptom | What to check |
| --- | --- |
| `not_deployed` | Deploy a tested version. A saved draft is insufficient. |
| `start_refused` | Compare the deployed input schema with the trigger’s actual wrapper and resolve the reported validation or start error. |
| `unusable_cron` | Correct the expression or timezone and save it again. Other schedules continue while this one is skipped. |
| `paused_after_failures` | The schedule turned itself off after repeated failures. See [When a schedule pauses itself](https://docs.tale.dev/platform/automations/triggers#when-a-schedule-pauses-itself). |
| Webhook credential refused | Check the current URL and enabled state. Unknown and disabled tokens intentionally receive the same refusal. |
| Run exists but did not finish | Open [execution logs](https://docs.tale.dev/platform/automations/execution-logs); the start succeeded and the issue is inside the run. |

The last-fired timestamp advances when a run actually starts. A due trigger that cannot start work records a skip instead. This separates a broken schedule from a workflow that started and later failed.

## When a schedule pauses itself

A schedule whose runs fail the same way at every occurrence would otherwise keep failing indefinitely. Tale counts the runs a trigger starts that fail with an error a retry won't fix: the automation's own code (`node_error`), a connector (`connector_error`), a model reply that does not match its schema (`llm_output_invalid`), or the organization's model provider (`auth_error`, `missing_api_key`, `credit_exhausted`, `model_not_found`). A successful run resets the count, and other failures, such as a rate limit or an unreachable provider, neither count nor reset it. A schedule that has already paused itself is the exception: it keeps the count that paused it, even when a run that was still in progress succeeds afterwards, and only saving the trigger clears it.

After five such failures in a row, the schedule turns **Enabled** off and records `paused_after_failures`. The **Trigger** section then shows the pause, the last failure's code and time, and **View run**, which opens that run. While runs are failing but the schedule is still on, the section shows how many failed in a row. Owners and Admins get a bell notification, which also reaches them by email when the organization has a connected mailbox, and the audit log records the pause. They can switch these notices off with **Automation alerts** under **Settings > Notifications**.

Open the failed run to read the error, and fix the automation or its connection. Then turn on **Enabled** and save. Saving the trigger starts a new count, whether it turns the schedule back on or leaves it off, and marks the notices read.

Webhook and platform-event triggers count failures the same way but are never paused. Their runs carry a delivery or an event, which a paused trigger would drop.

## Pause or replace the trigger

Turn off **Enabled** and save to pause starts while retaining the configuration and run history. Re-enable it to resume. **Remove trigger** deletes the binding; for a webhook, its URL becomes unusable.

Triggers belong to the automation’s name, not a version. Deploying or rolling back keeps the same schedule or URL and changes which version future starts execute. Editing a trigger does not create a workflow version, so review trigger settings alongside any deployment that changes expected inputs.

# Compare models in Arena
Source: https://docs.tale.dev/platform/chat/arena-mode

Use **Arena Mode** to compare two models on the same prompt. Both sides use the chat assistant and the same starting context. Choose a question you can evaluate: preference alone cannot establish that an answer is correct.

## Start a comparison

Open a private chat, open the composer’s **+** menu and select **Arena Mode**. Shared chats cannot enter Arena. Choose the models under **Model A** and **Model B**, then send your prompt. You may choose the same model twice to compare variation, or two different models to compare their behavior.

For a useful first comparison, give both sides a short source and a precise request, such as “List the three decisions in these meeting notes and cite the sentence supporting each.” Keep the source, instructions and requested format the same.

<Frame caption="The same prompt answered by two models, with the verdict row beneath.">

![Arena Mode with one launch-checklist prompt answered in two columns — Claude Haiku 4.5 on the left returning a numbered five-step list, Claude Sonnet 4.6 on the right grouping the same work under headings and adding the risks worth flagging — above the A is better, B is better, Tie, and Both bad verdict buttons.](https://docs.tale.dev/images/platform/chat-arena-split.webp)

</Frame>

Each reply appears in its own column. The prompt is admitted for both columns together: a usage limit that would stop it stops it for both sides, never for one column alone. Wait until both have finished before selecting a verdict; the controls stay unavailable while either side is answering. A slow reply is still part of the comparison. If a side fails, its column shows the error and the round cannot be judged: the four verdict buttons stay unavailable until both columns hold a finished reply, while **Exit without verdict** remains available. Inspect the error before treating the result as a quality judgment.

## Judge the replies

Check factual accuracy against the source, whether the reply followed the instructions, whether essential details are missing, and how much editing you would need before using it. A longer or more confident response is not necessarily better.

| Verdict | Use it when | Conversation continues with |
| --- | --- | --- |
| **A is better** | A is more useful or accurate. | Column A. |
| **B is better** | B is more useful or accurate. | Column B, and the composer switches to Model B. |
| **Tie** | Both meet the request equally well. | Column A. |
| **Both bad** | Neither is acceptable. | Column A. |
| **Exit without verdict** | You do not want to record a comparison. | Column A, without a verdict. |

Every choice ends the two-column comparison. The next message goes to the remaining conversation. To compare again, enable Arena again; a tie does not keep both columns active.

The other column's answer is discarded and goes to the organization's [Trash](https://docs.tale.dev/platform/admin/governance/trash), where an administrator can restore it as a chat of its own until the retention grace window ends. It no longer appears in your chat list or in search, and a link to it reports that the chat is not available.

## Find the recorded feedback

When both models have produced replies, a verdict contributes to the organization’s [Feedback analytics](https://docs.tale.dev/platform/admin/governance/feedback-analytics). Administrators can inspect **Arena verdicts** and model matchups there. A round in which only one column answered is never recorded: the verdict is refused, so the analytics only contain comparisons of two finished replies. Exiting without a verdict does not add a rating.

Use several representative questions before drawing a conclusion about a model. A result for a short summary may not predict its performance on code or long documents, and organization-wide preferences include other people’s tasks.

## Resolve a blocked comparison

If a model is absent, check its provider and access rules through the [model catalog](https://docs.tale.dev/platform/models). If the verdict buttons remain disabled, wait for both generations to end, or check that both columns show a finished reply: a side that failed or never answered leaves nothing to compare, so exit without a verdict, fix the cause and send the prompt again. A failed request may reflect credentials, availability or policy rather than answer quality; use its displayed reason to decide what to fix before retrying.

# Ask about files and images
Source: https://docs.tale.dev/platform/chat/attachments

Attach a file when it is needed for the current conversation. The assistant receives images, retrieves text from supported documents, and reads transcripts of recordings. For files that several chats should reuse, upload them to a [project](https://docs.tale.dev/platform/projects/manage-files) or the [Knowledge library](https://docs.tale.dev/platform/knowledge/documents) instead.

## Add an attachment

Open the `+` menu beside the message field and choose **Add photos & files**. You can also drag files onto the composer or paste a screenshot into the message field. A message can carry up to ten files.

Images appear as thumbnails; other files appear as named chips with their processing status. Check the filenames before sending. Use a staged attachment’s remove control to leave it out of the message.

After sending, **Edit message** changes the text in a new version of the conversation and keeps the original attachments. You do not need to upload them again.

<Frame caption="A staged document shows its name, then its size once it has been processed and is ready to send with your question.">

![The chat composer shows an attached document above the message field, with its file size and a control to remove it.](https://docs.tale.dev/images/platform/chat-document-attachment.webp)

</Frame>

Write a question that tells the assistant what to look for, such as “Read the meeting note and list the decisions, their owners, and any missing deadlines.” Attaching a file without a question leaves the intended task unclear.

When you try to attach audio or video, Tale checks whether the organization has an available transcription model. If the check prevents the upload, a dialog explains the problem and offers the recovery actions you can use. Those files are refused before transfer; other supported files in the same selection can still upload. Close the dialog to keep composing, follow the settings action if you have access, or ask an admin to check [Models](https://docs.tale.dev/platform/admin/governance/content-models).

## Understand what the assistant receives

| Attachment | What the model uses | What to check |
| --- | --- | --- |
| Image or pasted screenshot | The image itself, when the selected model supports vision. | Confirm the picker offers an image-capable model and the text is legible. |
| PDF, modern Office document, or supported text file | Text made available through the assistant’s retrieval tools. | Wait for processing and check for a reading step in the reply. |
| Audio or video file | A text transcript. | An admin must configure transcription; check names, numbers, and specialist terms against the recording. |
| Legacy Office file without a text extractor | The filename, without searchable document text. | Save it as `.docx`, `.xlsx`, or `.pptx` and attach that copy. |

File upload support and text extraction are separate. A file that appears in the chat is not necessarily a file whose contents the assistant can read.

## Send while processing continues

If documents or recordings are still processing when you send, Tale queues the message and sends it after they are ready. The queued message appears above the composer. Cancel it there if you need to change the question; its text returns to the field.

Paste a supported video link into the message field to start creating an attachment. A URL entered by typing stays ordinary message text. Tale retrieves captions first and uses audio transcription when captions are unavailable, then supplies the transcript to the assistant. When the captions show two people speaking at the same moment, the transcript keeps the words of both. Pasting a link remains available without a transcription model because usable captions do not need one. Pasting a link again in an existing chat before sending reuses the attachment that chat already has for it, even if you pasted the link in another chat in between; each chat keeps its own. A failed or removed attachment, or one added more than a day earlier, is not reused. If that link fails, retry it or remove it before sending. If Tale cannot remove a link, its chip comes back and a message says why; the link stays attached until a removal succeeds.

A model change applies to new transcription work; completed attachments keep their existing transcript. Uploading the same bytes again reuses completed work for the same transcription target, but transcribes them again when the target provider or model differs.

## Keep the file in the right place

Chat attachments belong to that conversation. They do not automatically enter the organization’s Knowledge library or become available in another chat. Switching conversations clears staged attachments, so check the chips again after changing chats.

A regenerated reply uses the original message’s stored attachments. If you need to ask about a different version of a file, send the new file and identify which version the assistant should use.

<Tip>

For recurring questions about a brief or policy, put the file in the appropriate project once. Start later chats inside that project instead of uploading a separate copy each time.

</Tip>

## Resolve attachment problems

| Symptom | Action |
| --- | --- |
| The image cannot be read by the selected model | Choose a vision-capable model. On Auto, Tale considers compatible image models; if none are available, ask an admin to configure one. |
| Processing fails | Retry the file. If a small supported file also fails, ask an admin to check storage, indexing, or transcription as indicated by the error. |
| The assistant knows the name but not the contents | Check the format and processing status. Convert legacy files to a supported modern format. |
| The answer invents detail from a recording | Check the transcript against the recording and supply the corrected passage before continuing. |
| A queued message has not sent | Inspect every attachment’s status, including video links. Remove or retry failed items. |
| A removed video link comes back | Tale could not remove it, and the message that appears says why. The link is still attached. Remove it again once the cause is resolved, for example when your connection is back or after you sign in again. |

Return to [Chat basics](https://docs.tale.dev/platform/chat/basics) to check sources and continue the conversation.

# Ask questions in chat
Source: https://docs.tale.dev/platform/chat/basics

Use chat to ask questions, understand a document, or investigate information in Tale. The assistant can search accessible knowledge and read public pages. Start with a specific question, then use follow-up messages to narrow the answer.

<Frame caption="The conversation keeps your question, the assistant’s steps, and its reply together.">

![A chat about onboarding feedback shows the question and an assistant reply with three themes in a table.](https://docs.tale.dev/images/platform/chat-thread-reply.webp)

</Frame>

## Send your first message

Open **Home**. On a computer, it reopens the chat you last read, if there is one. To begin a new subject, choose **New chat** at the top of the Home list or, on a computer, choose **Home** again while it is active. Type in the message field. Press **Enter** to send or **Shift+Enter** for a new line. A starter prompt fills the same role as your own first question; edit your request to include the source, subject, and kind of answer you need.

For example: “Find the onboarding feedback and summarize the three most common problems. Cite the documents and separate reported problems from your suggestions.”

If your organization turned on a confidentiality notice, it appears under the message field as a reminder of what not to share in chat.

While the reply streams, the send control becomes a stop control. Stopping keeps the text already received, which may end mid-sentence. Use a follow-up message to clarify the question or ask for missing detail.

## Choose a model when the choice matters

The model picker starts on **Auto** when several usable models are available. Auto selects a model for each message from your organization’s available models; organization rules can set a default or restrict the choices. The details under a reply identify the model that actually answered.

Pick a named model when you need consistent comparisons or know which model the work requires. Your choice stays selected until you change it, including which provider serves the model when two providers offer the same one. If that model supports adjustable reasoning, the picker also offers an effort setting. More reasoning can take longer; it is not a substitute for checking the answer.

<Frame caption="The model picker sits beside the attachment menu and voice controls.">

![The chat composer contains the plus menu, an Auto model picker, a microphone, and the send button.](https://docs.tale.dev/images/platform/chat-composer.webp)

</Frame>

If no models are available, ask an admin to check active provider credentials and model access. Chat offers only models that an API key or environment-variable credential serves: a subscription runs only in tasks and automations, and the model list names any it leaves out. [Models](https://docs.tale.dev/platform/models) explains how the catalog is built.

## Give the assistant the right sources

Choose the conversation’s location before asking about files:

| Where you ask | Files the assistant can retrieve |
| --- | --- |
| The organization’s chat | Knowledge-library documents you can access and this chat’s own attachments. |
| A chat inside a project | That project’s files, Knowledge-library documents you can access, and the chat’s own attachments. |
| A shared chat link | A read-only snapshot; viewers cannot ask follow-up questions there. |

Project chat also receives the project’s standing instructions. File access is enforced by Tale, so asking a project chat to read a different project does not grant access. Trashed or expired files are not searchable.

Use [attachments](https://docs.tale.dev/platform/chat/attachments) for material needed in this conversation, [project files](https://docs.tale.dev/platform/projects/manage-files) for recurring project work, and [Knowledge](https://docs.tale.dev/platform/knowledge/overview) for shared reference material. The assistant retrieves content when it needs it; uploading a document does not mean every answer has read it.

Questions about Tale itself need no upload: the assistant looks up the public documentation at docs.tale.dev before explaining how a screen or setting works. If the server cannot reach docs.tale.dev, for example on a self-hosted installation without internet access, the timeline shows a failed reading step and the answer is not grounded in the documentation. The documentation describes the latest release, so the assistant points out when your workspace may differ.

## Check what the assistant used

Above the reply, the timeline shows search and reading steps. A failed step explains what could not be read; it is useful evidence when an answer is incomplete. Expand the thinking section when one is available, but judge factual claims against sources rather than the fluency of that explanation.

**Sources** below the answer lists documents and pages the assistant loaded. Open a source and check that it supports the relevant claim. A citation establishes which material was used, not that every conclusion is correct. A reply without a retrieval step may rely on the model’s prior knowledge.

The assistant can search workspace information such as documents, knowledge entries, websites, contacts, products, accessible tasks, and the Inbox conversations you can see, including the text of the emails they received and of their attachments. A task can be named by its key, such as `DOCS-12`, as the board shows it. It can fetch the details behind a result and read a public web page. Chat does not run code, change connected systems, create images, produce file deliverables, or use [skills](https://docs.tale.dev/platform/workspace/skills); assign that work to a [project task](https://docs.tale.dev/platform/projects/tasks). Any member can create one in a project they can open and hand it to one of the project's agents; [Turn a chat into a task](https://docs.tale.dev/platform/chat/basics#create-task-from-chat) shows how to start it from the conversation. A project agent working on the task can create images when an admin has turned on [image generation](https://docs.tale.dev/platform/admin/governance/content-models#let-agents-generate-images).

## Turn a chat into a task {#create-task-from-chat}

When a conversation ends in work that needs a file, such as a presentation, a report, or a spreadsheet, hand it to a project agent. Select **Create task** in the conversation's header; on a narrow screen, choose **Create task from chat** in the **⋯** menu. A chat filed in a project creates the task there. Otherwise, choose the project first: **With an agent** lists the projects you can open that have agents, with how many. A project without agents of its own appears there with **Standard agent**: its task goes to the organization's [standard agent](https://docs.tale.dev/platform/projects/project-agents#standard-agent). When the standard agent can't run for you, for example because an admin has turned it off, such projects are listed under **No agent yet** instead, each saying who can add one.

The task dialog opens with your last request as the description, a link back to the chat, and the files you attached in the conversation. When the project has a single agent, or uses the standard agent, it's already the **Assignee**; otherwise, choose one. Edit anything you like, then select **Create and start agent**: the task is created, and the agent starts on it at once. **Create only** creates it without starting the agent; **Start agent** on the task starts it later.

<Frame caption="Create task opens the task dialog with the request, a link back to the chat, and the agent to start.">

![The Create task dialog holds the title and description "Plan the quarterly business review agenda for Friday", a link labelled From the chat below the request, Content editor as the assignee, and the buttons Create only and Create and start agent.](https://docs.tale.dev/images/platform/chat-create-task.webp)

</Frame>

The task then shows above the chat's message box with what it's doing: **The agent is working**, **Waiting for a sandbox slot**, **Trying again…**, **Ready for review** with the number of files it delivered, or **The agent couldn't finish**. **Open** takes you to the task. You're also notified when it's ready for review and when the agent can't finish; [When the agent can't finish](https://docs.tale.dev/platform/projects/task-automation#when-the-agent-cant-finish) explains what to do next.

<Frame caption="The task a chat handed over shows its progress above the message box.">

![Above the message box, a row names the task "Plan the quarterly business review agenda for Friday" with Ready for review · Website relaunch and an Open link.](https://docs.tale.dev/images/platform/chat-task-tray.webp)

</Frame>

Ask the assistant for such a file, and it answers what fits in a reply, then walks you through these steps for your own projects, naming the buttons as you see them.

No project you can open offers an agent? Then the standard agent can't run for you: an admin may have turned it off under [Governance > Models](https://docs.tale.dev/platform/admin/governance/content-models#standard-agent), or no model you may use can run it. Ask an Admin about it, or ask an Editor or Admin to add an agent on the project's **Agents** tab. As an Editor, you can also add one from the task: under **Assignee**, choose **Create an agent…**.

Files come along only from your own conversation. A task takes only its creator's uploads, so a task created from a chat someone shared into a project starts without them.

## Continue, copy, or keep the conversation

Use the reply toolbar to copy an answer, give feedback, inspect its details, or fork a conversation at that point. A fork lets you try another direction while preserving the earlier exchange.

Find earlier chats in [Home](https://docs.tale.dev/platform#home); **Chats** above the list hides your tasks and inbox conversations. Pin frequently used chats, give a chat a recognizable title, or move it into a project when the topic becomes ongoing work: drag it onto the project or choose **Move to project…** in its menu. [Shared chats](https://docs.tale.dev/platform/chat/shared-threads) explains how to publish a read-only snapshot for colleagues.

Very long conversations may exceed the model’s context window. Tale displays a notice when older messages are omitted. Restate an important requirement or start a new chat with the relevant sources instead of assuming the assistant still sees the entire history.

## Improve an incomplete answer

| Problem | Try this |
| --- | --- |
| The answer is too broad | Ask one question, name the audience, and specify the desired length or format. |
| A file was not used | Check the chat’s project, the file’s indexing status, and the retrieval steps. Name the file explicitly. |
| Search reports an unavailable source | Ask an admin to check the named service or embedding configuration; an empty result is not proof the information does not exist. |
| A reply stops with an error | Read its error, check the selected model, and retry after the cause is resolved. Tale does not silently switch providers. |
| A reply ends without an answer | The note in its place says why: the model returned nothing, used up its output token limit before writing, or the provider’s content filter withheld the reply. Select **Try again**, or first lower the reasoning effort, shorten the request, or choose another model. |

For a guided example with source checking, follow [Chat effectively](https://docs.tale.dev/tutorials/member/chat-effectively).

# Chat
Source: https://docs.tale.dev/platform/chat/overview

Chat is the quickest place to ask about a document, understand a topic, or refine an answer through follow-up questions. The assistant can search accessible knowledge and fetch public pages when the question needs them. Check its sources before relying on a factual answer, especially when the information may have changed.

<Frame caption="A conversation keeps the question and answer together so you can refine the request without starting over.">

![A chat shows a question about onboarding feedback and an answer arranged as a table of themes.](https://docs.tale.dev/images/platform/chat-thread-reply.webp)

</Frame>

## Start with a useful question

Open **Home**, choose **New chat**, type in the composer, and send. A starter prompt can help if you are unsure where to begin. Include the outcome you need and the relevant source: “Using the onboarding guide, list the steps a new customer needs to complete. Cite the guide.”

When several usable models are available, the model picker can start on **Auto**. Select a named model when you want control over which available model answers, and adjust reasoning effort where supported. You can attach a file for a question about its contents or open a project chat for recurring reference material.

<Frame caption="Starter prompts offer a first question; the composer also accepts your own.">

![A new chat shows the welcome heading, four starter prompts, and the message composer.](https://docs.tale.dev/images/platform/chat-starters-empty.webp)

</Frame>

## Choose the surface for the work

| You want to | Start in |
| --- | --- |
| Ask, compare information, or clarify an answer | A **chat** |
| Reuse the same files and instructions across conversations | A **project chat** |
| Produce a deliverable with an owner and a review | A project **task** |
| Run a repeatable process on a schedule or incoming event | An **automation** |

Chat focuses on conversation and retrieval. For a substantial deliverable, the assistant may direct you to a task so an agent can work in a sandbox and a person can review the result. See [Tasks](https://docs.tale.dev/platform/projects/tasks) and [Automations](https://docs.tale.dev/platform/automations/concepts).

## Use the conversation well

<CardGroup cols="2">

<Card title="Chat basics" icon="message-circle" href="https://docs.tale.dev/platform/chat/basics">
Send, choose a model, read sources, and resume a conversation later.
</Card>

<Card title="Attach files" icon="paperclip" href="https://docs.tale.dev/platform/chat/attachments">
Add a document or image and understand upload and indexing states.
</Card>

<Card title="Compare models in Arena" icon="swords" href="https://docs.tale.dev/platform/chat/arena-mode">
Compare two answers to the same question and keep the one that works better.
</Card>

<Card title="Use your voice" icon="mic" href="https://docs.tale.dev/platform/chat/voice-mode">
Dictate a message or listen to a response, with the required provider setup.
</Card>

<Card title="Share a chat" icon="share-2" href="https://docs.tale.dev/platform/chat/shared-threads">
Publish a read-only snapshot for your organization and stop sharing later.
</Card>

<Card title="Practice with a real source" icon="book-open" href="https://docs.tale.dev/tutorials/member/chat-effectively">
Work through a focused question, a source check, and a useful follow-up.
</Card>

</CardGroup>

# Share a chat with your organization
Source: https://docs.tale.dev/platform/chat/shared-threads

Share a chat when a colleague needs to read the question and answer without continuing your conversation. The link publishes a snapshot for signed-in members of your organization. It is not a public link, and it does not update automatically as you keep chatting.

## Create the snapshot

1. Open the chat’s header menu and choose **Share**.
2. Select **Share with organization** in the **Share chat** dialog.
3. Click **Create share link**.
4. Use **Preview** to check the snapshot, then **Copy link** when it is ready to share.

The snapshot is the branch you are viewing. If you used **Edit message** or **Try again**, the link publishes the version of each edited or regenerated turn that is on screen. Switch to the version you want colleagues to read with **Previous branch** and **Next branch** before you create the link.

Read the transcript before distributing the link. A reply can contain details copied or summarized from a restricted source; sharing that reply makes its text readable to the organization members who have the link.

<Frame caption="Recipients read the snapshot with its sharing byline; there is no message composer.">

![A read-only shared chat shows its transcript and a byline identifying the person who shared it and the date.](https://docs.tale.dev/images/platform/chat-shared-view.webp)

</Frame>

## Include a later answer

New messages stay outside the published snapshot. Open **Share** again and choose **Include newer messages** when you want the same link to show the newer exchange. The snapshot is taken again from the branch you are viewing, so switch to the version you want to publish first. Preview it again before treating that version as the one colleagues should read.

A recipient who wants to continue the topic starts their own chat. A snapshot does not create a collaborative conversation, and it does not grant access to every source mentioned in it.

## Stop sharing

Choose **Keep private** in the share dialog or **Stop sharing** in the chat's menu in the Home list. The link becomes unavailable. Deleting the original chat also makes its share unavailable.

If the dialog can't load the sharing status, it selects neither option and says that the chat may still be shared. Choose **Try again**; once the status appears, you can choose **Keep private**. An existing link keeps working until then.

Stopping a share prevents future viewing through that link. It cannot retract text someone already copied, which is why reviewing the snapshot before sharing matters.

## Share with a project instead

For ongoing collaboration, use **Share with project** on a chat in a [project](https://docs.tale.dev/platform/projects/concepts). The project’s **Chats** tab separates personal chats from those shared with the project. Project membership alone does not share your personal chats automatically.

Arena comparisons cannot be shared while they remain Arena chats. Finish the comparison before sharing the conversation you keep; see [Arena Mode](https://docs.tale.dev/platform/chat/arena-mode).

# Voice mode
Source: https://docs.tale.dev/platform/chat/voice-mode

Dictation lets you speak a message instead of typing it. Voice output reads an assistant reply aloud. You can use either on its own: dictating does not require spoken replies, and listening does not require microphone access.

## Dictate and check a message

1. Click **Start dictation** on the composer's microphone control.
2. Allow microphone access in the browser if asked, then speak clearly.
3. Click **Stop dictation**. Where server transcription is used, wait for it to finish.
4. Read and correct the text in the message field, especially names, numbers, and dates. Send when it is ready.

Dictation adds text to the composer; it does not automatically send the message. Sending stops an active dictation. The chat model receives the text you submit.

Tale first uses the browser's speech-recognition capability when available. Otherwise, it can record and transcribe through your organization's configured transcription model. Browser speech recognition may use a browser-vendor service; do not assume dictation works offline.

The server fallback needs browser recording support through MediaRecorder, microphone permission, and an available organization transcription model. An admin chooses **Audio transcription model** under [Settings > Governance > Models](https://docs.tale.dev/platform/admin/governance/content-models). This setting also serves audio and video attachments. It does not change the browser's own recognition service: supported browser dictation remains usable when the organization's server model is unavailable.

If you try to start server dictation and its transcription model is unavailable, a dialog explains the problem. Follow the recovery action offered: open settings, retry a temporarily failed availability check, or ask an admin for help. You can close the dialog and continue typing.

## Listen to a reply

Enable **Voice mode** in the composer to hear replies in the current chat. A text-to-speech model prepares audio from the answer. Use the reply's playback control to stop or play it again; the written response remains available for checking details.

An organization policy can hide voice output. A disabled control can also mean there is no usable speech model. An administrator checks the configured [AI providers](https://docs.tale.dev/platform/admin/providers); changing the chat model alone does not supply a speech provider.

The voice setting on an existing chat applies to that chat. Setting it on a new chat also establishes the default for later chats. There is no separate voice configuration on each project agent.

## Recover a voice problem

| Symptom | What to check |
| --- | --- |
| The microphone will not start | Browser microphone permission, the selected input device, and whether another app is using it. |
| A message says dictation is unavailable | The browser's speech service could not be reached: check the connection, a proxy or a content blocker, then try again. |
| Words are missing or wrong | Reduce background noise and correct the transcript before sending. |
| Server transcription failed | Use the retry control while the failed recording remains available, or discard it and type. |
| A reply is ready but silent | Check device volume and browser playback permission, then use the reply's play control. |
| Voice reports a configuration error | Ask an administrator to check the speech model and credential. |

A failed server-transcription recording is held in the current page's memory for retry. Leaving or reloading the page can lose that recording. It is not a saved audio attachment; use [attachments](https://docs.tale.dev/platform/chat/attachments) when you want to upload an existing recording.

## Understand the audio path

Browser dictation follows the browser's speech service. The server fallback sends the recording to Tale for transcription with the organization's configured provider; this dictation path does not store it as a document. Once sent, the transcript becomes part of chat history.

Voice output sends answer text to the configured speech provider and streams audio for playback. If the answer contains information from a restricted source, that text is included in the speech request. Administrators should choose speech services consistent with the organization's [data-residency requirements](https://docs.tale.dev/cloud/data-residency).

# Connect an external client with MCP
Source: https://docs.tale.dev/platform/connectors/mcp-servers

Tale exposes an MCP endpoint that lets an external coding assistant or other MCP client work with your organization. Use it to discover capabilities, author automations, and inspect runs through the client’s tools. Access follows the organization API key and its holder’s permissions.

## Find your endpoint

Open **Settings > API > MCP**. The page shows the deployment’s endpoint URL, the organization slug, available tool groups, and a request you can copy to check connectivity. Create a suitable key under **Settings > API** if you do not already have one.

<Frame caption="The MCP settings page provides the endpoint, organization context, and available tools.">

![The MCP settings page shows an endpoint URL ending in /api/v1/mcp, an organization slug, tool groups, and a sample connectivity request.](https://docs.tale.dev/images/platform/settings-mcp-endpoint.webp)

</Frame>

Follow [MCP endpoint](https://docs.tale.dev/develop/mcp-endpoint) for client configuration, authentication, and permission requirements. Store the key in the client’s credential settings; do not put it in a prompt or a shared document.

## Choose the direction of the connection

Tale’s MCP endpoint accepts connections from external clients. Tale does not provide a settings form for registering an external MCP server as equipment for its own project agents.

For an agent inside Tale that needs another service, check the [connector catalog](https://docs.tale.dev/platform/connectors/overview). When there is no suitable connector, a [project agent](https://docs.tale.dev/platform/projects/project-agents) can use an appropriately scoped secret to call a service from its sandbox. That grants the running agent access to the secret, so choose the scope for the specific job.

## Verify access before authoring

Start with the connectivity request on the MCP page and confirm that the client can list the tools. Then read the tool’s required permission before trying a write. Saving an automation and deploying it are separate operations; connecting a client does not bypass the deploy gate or approval rules.

Use [API keys](https://docs.tale.dev/platform/admin/api-keys) for key rotation and revocation, and [Automation concepts](https://docs.tale.dev/platform/automations/concepts) for the save, test, and deploy lifecycle.

# Connect Tale to external services
Source: https://docs.tale.dev/platform/connectors/overview

Use a connector when Tale needs to read or change data in an external service. The connector defines supported actions; a credential authorizes the account those actions use. A Developer, Admin or Owner manages credentials under **Settings > Connectors**.

<Video src="https://docs.tale.dev/videos/en/tutorials/ep7-connectors/ep7-connectors.en.mp4" poster="https://docs.tale.dev/videos/en/tutorials/ep7-connectors/ep7-connectors.en.webp" captions="https://docs.tale.dev/videos/en/tutorials/ep7-connectors/ep7-connectors.en.vtt" lang="en" title="Episode 7 — Connectors & the outside world" caption="Episode 7 — Connectors & the outside world (2:30)">

</Video>

## Choose the connection for the task

| Connector | Typical use | Authentication |
| --- | --- | --- |
| Confluence | Import Confluence Cloud pages into knowledge. | Username and password/token pair. |
| Discord | Work with messages and channels. | Token. |
| GitHub | Read or manage repositories, issues and pull requests. | Token. |
| GlitchTip | Read a project's issues so the GlitchTip importer can turn them into tasks. | Token and an Instance URL. |
| Gmail | Read, send and organize mail. | OAuth. |
| Google Drive | Import files into knowledge. | OAuth. |
| IMAP / SMTP Mailbox | Read or send mail through a private mail service. | Username and password. |
| Jev decisions | Answer typed questions about a workflow's data with calibrated probabilities, to decide whether to act. | API key (an OpenRouter key). |
| Microsoft Outlook | Work with mail, calendars and contacts. | OAuth. |
| Shopify | Work with products, customers and orders. | API key. |
| Slack | Work with messages and channels. | OAuth. |
| Tavily | Search the web and extract pages. | API key. |
| Microsoft Teams | Work with messages and channels. | OAuth. |
| Twilio | Send SMS and make voice calls. | Username and password/token pair. |
| WebDAV Files | Read, write and list the organization’s WebDAV files. | Username and password. |

The deployed catalog’s cards show the current actions and authentication methods. These definitions arrive with the platform; adding an account does not install arbitrary new connector code.

Knowledge imports use the [document indexing pipeline](https://docs.tale.dev/platform/knowledge/documents). OneDrive and SharePoint use the import flow in **Knowledge > Documents**, with per-user consent, rather than a separate organization connector. Mounting Tale’s documents on your own device is the other direction; use [WebDAV](https://docs.tale.dev/platform/connectors/webdav).

## Add the intended account

Select **Add credential**, search for the service and choose its card. Connectors with existing credentials appear first, but you can add another account for the same service. The form asks for the authentication that connector supports.

<Frame caption="Add credential opens on the catalog — the shipped connectors, with the ones you already hold a credential for listed first.">

![The Add credential dialog over the Settings > Connectors table, listing the shipped connectors as cards with their category tags and action counts, a search field at the top, and the already-configured Tavily connector at the head of the list.](https://docs.tale.dev/images/platform/connectors-add-credential.webp)

</Frame>

The **Name** field starts with the connector’s name. When you add several accounts for the same service, change it to one that identifies the purpose, such as `Support inbox` or `Release bot`. Use the external service’s credentials, not a Tale API key. For OAuth, sign in to the provider as the account you want to add and complete its consent. Each connection adds a new credential named after the connector and numbered (`Gmail`, then `Gmail 2`); Slack keeps one per workspace. Rename a new credential so the accounts stay distinguishable. If consent cannot start, an administrator may need to configure its OAuth app first.

Confluence, GlitchTip and Shopify require an **Instance URL** per credential. Use the Atlassian site origin, the GlitchTip instance origin such as `https://app.glitchtip.com`, or the store’s `myshopify.com` origin, rather than an unrelated page or customer-facing domain. A self-hosted GlitchTip instance must also be allowed by the deployment's connector host policy. [Connector credentials](https://docs.tale.dev/platform/admin/connectors) covers setup fields, reconnection and rotation.

## Choose which account an action uses

An action uses the credential it explicitly names, or the connector’s default when no name is supplied. Only one credential per connector is the default. With no default, an unnamed call fails even if other credentials exist. Deleting the default makes the oldest remaining active credential of that connector the default; the delete confirmation names it first.

For example, two support mailboxes are two credential rows. Choose names that distinguish them and inspect a workflow’s resolved input before running it live. A default is a fallback for selection, not proof that every job should use that account. Mailbox operations designed to inspect all active accounts are a separate case.

Disabling a credential retains its configuration but stops use through it. Replacing its secret updates the account connection used by existing references. Check dependent workflows before disabling, deleting or changing the default.

## Understand reads and writes

Automations use connector actions as workflow nodes. Each action declares an input schema, output and read or write effect. GlitchTip and Jev decisions only read: the GlitchTip importer writes Tale tasks and never changes the upstream issue, and a Jev decision answers each question with its probabilities and writes nothing. Each decision is billed to the OpenRouter account whose key the credential holds. In a test run, connector responses are mocked. In a live run, a write can send a message or change external data and is subject to the organization’s approval policy.

Equipped project agents receive supported read actions through Tale’s connector broker. It keeps those connector credentials outside the sandbox and returns results. The broker refuses connector writes. Direct GitHub tooling or explicit agent secrets use separate paths and must be reviewed separately.

Adding a credential does not add arbitrary tools to the ordinary Chat assistant. Use [automations](https://docs.tale.dev/platform/automations/editor) for a defined connector workflow and [project agents](https://docs.tale.dev/platform/projects/project-agents) for sandbox work.

## When the service is missing

An equipped agent can use a narrowly scoped secret to call a service from its sandbox. A `transform` node only reshapes data and cannot make an external API request. Review the permissions and expected effects before choosing a direct integration.

If the external application needs to call Tale, use the [REST API](https://docs.tale.dev/develop/api-reference) or [MCP endpoint](https://docs.tale.dev/develop/mcp-endpoint). [MCP and custom integrations](https://docs.tale.dev/platform/connectors/mcp-servers) explains that distinction.

# Open Tale documents through WebDAV
Source: https://docs.tale.dev/platform/connectors/webdav

WebDAV lets a compatible file client read and edit Tale’s organization documents as a remote folder. Changes use the same document store as **Knowledge > Documents**. Project-specific Knowledge files are not included in this mount.

## Get the connection details

Open **Settings > API > WebDAV**. Owners, Admins and Developers can generate their own device credentials. Copy the displayed URL, including the organization slug and `/documents/` path; do not construct it from an organization ID or use another organization’s address.

<Frame caption="Settings > API > WebDAV — the pre-filled connection details on top, the app-password generator below.">

![The WebDAV settings page shows the connection URL and username above three app-password rows. Retired design workstation is revoked; Design workstation and MacBook Pro remain active with Revoke actions.](https://docs.tale.dev/images/platform/settings-webdav.webp)

</Frame>

Use your Tale account email as the username and an app-password as the password. Your normal account password does not authenticate WebDAV. On a deployed service, connect over HTTPS; avoid credentials embedded in URLs or saved in command history.

## Generate one password per device

1. Select **Generate** and enter a **Label** such as `Design laptop`.
2. Generate the password and copy it before closing the result. The full value appears only once.
3. Store it in the device client’s credential manager, then select **I have saved it**.

The list keeps the label, prefix and usage dates, not the recoverable password. If you lose it, generate a replacement and revoke the old one once you have updated the client. Separate passwords let you disconnect one device without changing every other connection.

## Configure your client

<Tabs>

<Tab title="macOS Finder">

In Finder, press **⌘K** to open **Connect to Server**. Paste Tale’s WebDAV URL and connect with your email and app-password. Open the mounted folder and inspect a known document before copying files into it. Save the credential only on a device you trust.

</Tab>

<Tab title="Windows">

Use File Explorer’s network-drive connection with the HTTPS WebDAV address and your generated credentials. The Windows WebClient service must be available. If connection or large transfers fail, check Microsoft’s [WebDAV client requirements and limits](https://learn.microsoft.com/en-us/iis/publish/using-webdav/using-the-webdav-redirector) with IT, or use a dedicated WebDAV client. Keep HTTPS authentication enabled.

</Tab>

<Tab title="Linux">

A desktop file manager with WebDAV support can use the displayed host and path. GNOME Files uses `davs://` for secure WebDAV; KDE Dolphin uses `webdavs://`. If the dialog separates server and folder, enter the host in the server field and `/dav/<orgSlug>/documents/` as the folder, with HTTPS and the correct port.

</Tab>

<Tab title="iPhone and iPad">

Choose a client that explicitly supports WebDAV and give the device its own app-password. Tale’s browser-based Documents page also works for occasional access. Do not assume the Files app’s generic server dialog supports this protocol. Direct WebDAV upload from Pages, Numbers and Keynote is [no longer supported](https://support.apple.com/en-us/101948).

</Tab>

<Tab title="rclone">

Run `rclone config` and create a WebDAV remote with Tale’s URL, your email and app-password. Choose vendor `other`. Enter the password through the interactive prompt. Follow [rclone’s WebDAV guide](https://rclone.org/webdav/) to list files and copy a small test directory before a larger transfer.

</Tab>

</Tabs>

## Verify a small transfer

Open or download a document you can already read in Tale. If your role permits writes, upload a small uniquely named text file in a test folder. Confirm its name and content in **Knowledge > Documents**, then check its indexing status before expecting it in search.

A WebDAV upload follows document permissions and indexing rules; the source is recorded as `webdav`. A successful file transfer does not mean indexing has finished. If a project file seems missing from the mount, open that project’s Knowledge tab instead.

## Handle locks and deleted files

A compatible editor can lock a file while editing. A conflicting write receives **423 Locked**; finish or close the other editing session rather than repeatedly overwriting. Revoking an app-password also releases locks held by that credential.

The `.trash/` area lists soft-deleted documents read-only. Download a retained file if you need to inspect it; use Tale’s UI to restore it. You cannot use this area to retrieve a file that has already been permanently removed. A file you upload, overwrite, copy or delete over WebDAV leaves a row in the audit log under **Settings > Governance > Logs** in your name; a deletion shows as a document moved to trash.

## Revoke or repair a connection

Use **Revoke** on the password’s row and confirm. Subsequent requests with it are rejected, while other app-passwords remain usable. Revocation cannot be undone; update the client with a new password if needed. Generating and revoking an app-password each leave a row in the audit log under **Settings > Governance > Logs**.

Repeated sign-in prompts usually warrant checking the exact URL, organization membership and whether the password was revoked. A permission refusal after authentication is different from a wrong password. Use the [WebDAV API reference](https://docs.tale.dev/develop/webdav-api) for status codes and protocol diagnostics, or [API keys](https://docs.tale.dev/platform/admin/api-keys) for software that needs the REST API instead.

# Developer
Source: https://docs.tale.dev/platform/developer/overview

As a Developer, configure the technical connections and automations that support your team’s work. You have content-editing capabilities as well as access to technical settings such as providers, connectors, and API credentials. Member administration remains with Owners and Admins.

## Choose a connection or workflow

<CardGroup cols="2">

<Card title="Create an API key" icon="key" href="https://docs.tale.dev/platform/admin/api-keys">

Authorize a script or service to call Tale and plan for rotation and revocation.

</Card>

<Card title="Connect an MCP client" icon="network" href="https://docs.tale.dev/develop/mcp-endpoint">

Let an external client discover and use Tale’s exposed tools.

</Card>

<Card title="Connect an external service" icon="plug" href="https://docs.tale.dev/platform/admin/connectors">

Add a credential, choose its default, and recover expired authorization.

</Card>

<Card title="Build an automation" icon="workflow" href="https://docs.tale.dev/platform/automations/catalog">

Start from a blank workflow or import a package, then test and deploy a version.

</Card>

</CardGroup>

## Work from a concrete boundary

For incoming requests, start with the [API reference](https://docs.tale.dev/develop/api-reference) or [webhooks](https://docs.tale.dev/develop/webhooks). For an agent calling another system, prefer a supported connector; direct credentials in a sandbox require careful scoping. [Project agents](https://docs.tale.dev/platform/projects/project-agents) explains equipment. Deployment files and environment variables belong in the [self-hosted configuration guide](https://docs.tale.dev/self-hosted/configuration/environment-reference).

# Editor
Source: https://docs.tale.dev/platform/editor/overview

As an Editor, keep shared information useful: upload documents, correct knowledge entries, and maintain records. You can work on projects where you have edit access. Begin with one source and a question it should answer, then expand the collection as the team’s needs become clear.

## Choose a content task

<CardGroup cols="2">

<Card title="Maintain knowledge" icon="library" href="https://docs.tale.dev/platform/knowledge/overview">

Choose files, short facts, websites, or structured records for the information.

</Card>

<Card title="Set up a project" icon="folder-open" href="https://docs.tale.dev/tutorials/member/use-projects">

Bring files and instructions together and ask a question in project chat.

</Card>

<Card title="Track work as tasks" icon="list-checks" href="https://docs.tale.dev/platform/projects/tasks">

Record acceptance criteria, ownership, progress, and review.

</Card>

<Card title="Maintain reusable instructions" icon="list-plus" href="https://docs.tale.dev/platform/workspace/skills">

Create and share skills for the agents that need a repeatable method.

</Card>

</CardGroup>

## Know when to involve a Developer

The Editor role does not grant workflow authoring or connector administration; those resources are read-only. A Developer, Admin, or Owner handles automation changes and technical credentials. Project-agent management also requires project edit access and working provider and sandbox setup. Check [Members and roles](https://docs.tale.dev/platform/admin/members-and-roles) before starting a guide that needs additional permissions.

# Platform
Source: https://docs.tale.dev/platform

Use these guides to work in Tale, whether your organization uses Cloud or runs its own deployment. Start with a question in a chat, keep recurring work in a project, or follow a specific feature guide when you need to change a setting.

## Move between sections {#navigation}

On a computer, the rail along the left edge shows the sections as icons: **Home**, **Knowledge**, and **Automations**, with **Settings**, your notifications, and your profile menu at its foot. Point to an icon to see its name. On a phone, the tab bar at the bottom offers **Home**, **Knowledge**, **Automations**, and **Settings**. **Automations** shows only for Owners, Admins, and Developers, who build automations; Members and Editors don't see it.

On a phone, navigation sits in a rounded capsule floating above the page. Content scrolls behind it, while message fields and page actions stay above it. The capsule hides when the on-screen keyboard opens and returns when you close the keyboard.

As you scroll down, the navigation becomes smaller and moves slightly lower, showing just the icons. Scroll up to bring back the full bar and labels. Every destination stays available in both sizes.

A section always opens on its own first page, whatever you did there last, so the same choice leads to the same place every time. For example, open an automation's **Runs** tab, switch to **Home**, then choose **Automations**: the automation list opens, not the tab you left. On a computer, Home is the one section that picks up where you were: it reopens the chat you last read, or a new chat if you have none, and choosing **Home** again while you are there starts a new chat. The shortcut **⌥⌘N** on a Mac, or **Alt+Ctrl+N** on Windows or Linux, also starts a new chat.

**Settings** lists its pages in a panel beside the page, and the page header names the page you opened; on a phone, Settings starts from a list of its pages. **Knowledge** shows its pages as tabs under its header.

| You want to… | Do this |
| --- | --- |
| Open another section | Choose that section in the rail or, on a phone, in the tab bar. |
| Start a new chat | On a computer, choose **New chat** in Home, or choose **Home** while you are already there. On a phone, open **Home**, choose **Chats**, then **New chat**. |
| Open a project | On a computer, choose the project under **Projects** in Home. On a phone, choose the project, or choose **Open project** from its menu. |
| Return to the project list | Choose **All projects** in Home, or use the **Projects** breadcrumb above the project. |
| Return to the Documents list | Choose **Knowledge**. |

Bookmarks and shared links to a particular project, task, or document still open that destination.

### Find your work in Home {#home}

Home keeps your chats, tasks, projects, and customer conversations together. On a computer, the Home panel stays beside every chat, task, project, and inbox page. On a phone, **Home** opens the same list as a screen of its own. A chat, task, or conversation you open from it has a single header: a back arrow that returns to the list, its title, and its actions. Your profile menu stays at the top of the Home screen and of Settings.

On desktop, drag the Home panel’s right edge to adjust its width. You can also focus the divider with Tab and press Left or Right. The width is remembered for this organization in your browser.

At the top of the panel, **All**, **Chats**, **Tasks**, and **Inbox** switch what the list shows, and **New chat**, the pencil beside them, starts a chat; its tooltip shows the shortcut. **Inbox** appears only when your organization has an inbox: a deployed mail-sync automation, or an API app that has synced a conversation.

**Projects** lists every project you can open. Choose a project to open its page with the task board, **General**, **Chats**, **Knowledge**, and **Agents**. The two icons beside the **Projects** heading are **All projects**, which opens the full project list, and **New project**. Drag a chat onto a project to file it there. A project's menu offers **New chat** and **Pin project**.

Below the projects, one list groups your work under **Pinned**, **Today**, **Yesterday**, **Previous 7 days**, and **Earlier**:

- Your chats.
- The open tasks assigned to you or waiting for your review, from every project you can read.
- In **All**, the open inbox conversations you can see.

An empty **Tasks** view offers **All projects**, which opens the project list. On a computer, an empty **All** or **Chats** view also offers **New chat**. If your chats, tasks, or conversations cannot be loaded, the list keeps what did load and says what is missing, instead of showing an empty view. **Try again** asks for it again.

On a phone, the same list differs in three ways:

- **New chat** is at the top of the **Chats** view, not in the header. Home has no **New project** button, and a project's menu offers **Open project** and **Pin project**.
- Choosing a project under **Projects** narrows **All**, **Chats** and **Tasks** to that project's chats or open tasks, highlighting the selected project row. The narrowing stays on when you switch between these views. Tapping the project row again removes the filter. **Inbox** is never narrowed by project.
- **All projects** is a labelled link beside the **Projects** heading, not an icon.

Each row starts with a chat bubble, a colored circle for the task's status, or the customer's initials. The title follows with how long ago the item last changed, and one line of context below: the chat's project, the task's key and status such as `WEB-2` **In review** or **Waiting for your review**, or the customer and their latest message. A dot in the accent color marks an unread chat or conversation and a task waiting for your review. **Draft** with a pencil at the start of the context line marks a chat, task, or conversation holding text you typed but have not sent, except the one you have open. Drafts stay in the browser you typed them in. A chat's menu offers **Pin chat**, **Mark as read** or **Mark as unread**, **Rename**, **Move to project…**, **Share**, **Stop sharing** for a shared chat, **Archive**, and **Delete**. Archived chats move to **Archived** at the bottom of the Chats view.

The **Inbox** view lists the conversations of one status: choose **Open**, **Closed**, **Spam**, or **Archived** in its status menu. It also offers **New email**, a search field, and a **Filter** button for **Assignee**, **Read status**, and **Channel**. To act on several conversations at once, point to a conversation's initials and tick the checkbox that appears. The bar above the list then offers **Send messages**, **Close**, and **Mark as spam** for open conversations, or **Reopen** for closed and spam ones, together with **Archive** or **Unarchive** and **Clear selection**.

The checkbox at the start of the bar ticks the whole list. While only some conversations are ticked it shows a dash, and ticking it then selects every conversation the list shows, apart from those a search or filter hides. A selection of more than 200 conversations goes out in parts, and the Inbox counts them off as they go. The message that follows says how many conversations changed and how many failed, with the reason for the first failure when there is one. Those that failed stay ticked, so you can try again. If the list cannot be loaded, it reads **Couldn't load conversations** with **Try again**, rather than showing an empty status.

<Frame caption="Home's Inbox view beside an open conversation: the status menu, New email, search, and Filter above the conversations, each with its customer's initials and latest message.">

![Home in its Inbox view lists three open conversations: Copy of the August invoice from Léa Martin, Annual discount on the team plan from Hannah Weber, and Seat pricing for read-only members from Daniel Okafor. Beside the list, the conversation with Hannah Weber is open, showing her two messages, the team's reply between them, and the message field.](https://docs.tale.dev/images/platform/home-inbox.webp)

</Frame>

A chat, task, or conversation opens under a header with its icon, its title, one line of context, and its actions. **Hide sidebar** at the start of that header folds the Home panel away for more room, and **Show sidebar** brings it back; the button's tooltip shows the shortcut. A project's page offers the same button at the start of its header. In a conversation, the first action, **Copy link**, copies a link that opens the same conversation for a teammate. Owners and Admins assign the conversation from its header, to a person, a team, or one of each. Choosing the current person or team again clears it, as do **Unassign** and **Remove team** at the end of the list; the other assignment stays as it is.

Images in an email appear inside the message. Tale fetches the pictures hosted on the sender's servers for you, so the sender sees neither your IP address nor when you read the message. A picture larger than 10 MB, or one in SVG format, does not appear.

### Keyboard shortcuts {#shortcuts}

On a computer, you can also move through Home and open search from the keyboard:

| Mac | Windows or Linux | What it does |
| --- | --- | --- |
| **⌥⌘N** | **Alt+Ctrl+N** | Starts a new chat from any page. |
| **⌘K** | **Ctrl+K** | Opens search from any page, as the magnifying glass in the rail does. |
| **⌘\\** | **Ctrl+\\** | Hides or shows the Home panel on a chat, a task, or an open conversation. |
| **⌥↑** or **⌥↓** | **Alt+↑** or **Alt+↓** | Opens the previous or next chat, task, or conversation in the current view, even while the panel is hidden. |
| **↑** or **↓** | **↑** or **↓** | Moves to the row above or below once a row in the Home panel has keyboard focus. |

When nothing from the list is open, **⌥↓** (**Alt+↓**) opens its first item and **⌥↑** (**Alt+↑**) its last. In a text field, these keys keep their usual meaning. Once a row has keyboard focus, the **Home** and **End** keys jump to the first and last row of its list, and **Enter** opens the focused row.

## Choose a feature

<CardGroup cols="2">

<Card title="Chat" icon="message-circle" href="https://docs.tale.dev/platform/chat/overview">

Ask questions, attach files, check sources, compare models, and share a conversation.

</Card>

<Card title="Projects" icon="folder-open" href="https://docs.tale.dev/platform/projects/overview">

Keep files, instructions, personal and shared chats, and tasks together.

</Card>

<Card title="Agents" icon="bot" href="https://docs.tale.dev/platform/agents/concepts">

Configure agents to work on project tasks with a chosen harness, model, and equipment.

</Card>

<Card title="Automations" icon="workflow" href="https://docs.tale.dev/platform/automations/concepts">

Build a repeatable process, test it, deploy a version, and inspect its runs.

</Card>

<Card title="Knowledge" icon="library" href="https://docs.tale.dev/platform/knowledge/overview">

Maintain documents, short facts, public websites, contacts, and products.

</Card>

<Card title="Approvals" icon="check-check" href="https://docs.tale.dev/platform/approvals/concepts">

Review an automation’s proposed operation before allowing it to proceed.

</Card>

<Card title="Skill library" icon="list-plus" href="https://docs.tale.dev/platform/workspace/skills">

Create reusable instructions and share them with teams or the organization.

</Card>

<Card title="Models" icon="cpu" href="https://docs.tale.dev/platform/models">

Understand model capabilities, availability, and selection.

</Card>

<Card title="Connectors" icon="plug" href="https://docs.tale.dev/platform/connectors/overview">

Connect external services and understand which actions agents and automations can use.

</Card>

</CardGroup>

## Find your starting point

Your role controls which actions are available. Teams and project access decide which resources you can reach. Follow the route closest to your work; an administrator can explain a missing action.

<CardGroup cols="2">

<Card title="Member" icon="user" href="https://docs.tale.dev/platform/member/overview">

Ask, read shared knowledge, and organize your personal settings.

</Card>

<Card title="Editor" icon="pencil-ruler" href="https://docs.tale.dev/platform/editor/overview">

Maintain shared content and work with the projects you can edit.

</Card>

<Card title="Developer" icon="terminal" href="https://docs.tale.dev/platform/developer/overview">

Build automations and connect code, clients, and external services.

</Card>

<Card title="Admin" icon="shield" href="https://docs.tale.dev/platform/admin/overview">

Set up people, providers, infrastructure, and organization policies.

</Card>

</CardGroup>

# Add websites to knowledge
Source: https://docs.tale.dev/platform/knowledge/crawling

Add a website when your team needs to ask about public content that changes over time. Tale fetches the selected pages and indexes their readable text for knowledge search. You need Editor permissions or higher to manage website sources. Pages behind a login need another import route, such as [Documents](https://docs.tale.dev/platform/knowledge/documents).

## Add a website or selected pages

Open **Knowledge > Websites** and click **Add website**. Choose the source type before entering the address:

| Source type | Use it when | What to enter |
| --- | --- | --- |
| **Whole website** | You want content discovered across a domain | A **Domain**, such as `example.com` |
| **URL list** | You need a selected set of pages or public documents | One address per line under **URLs** |

Whole-website mode accepts a URL but uses its hostname; pasting a path does not restrict the crawl to that path. Choose URL list for that purpose. An `http://` address is refused, because the crawler fetches over HTTPS only, and a trailing dot is dropped. The `www` and non-`www` spellings count as the same website, so adding both produces a duplicate warning.

Choose **Scan interval** and **Save**. The default interval is six hours; the available choices range from one hour to thirty days. A newly saved source is picked up by the scheduler. Saving does not mean all pages have already been fetched or indexed.

<Frame caption="Whole website mode asks for a domain and a scan interval. Choose URL list when the page selection matters.">

![The Add website dialog shows Domain and Scan interval with a six-hour default.](https://docs.tale.dev/images/platform/websites-add-dialog.webp)

</Frame>

## Make the pages searchable in chat

Crawling stores a page's text. Chat and knowledge search reach it only once your organization has a working embedding model, because every search first turns the question into a vector. Without one, a source can read **Active** with all its pages indexed while the assistant answers that web-page search is not set up.

**Knowledge > Websites** then shows the notice **Chat can't search these websites yet**; an administrator may see the banner **Knowledge search is off** in its place, above every page. An administrator sets the model under **Settings > Data residency**; operators find the setup details in [Data residency](https://docs.tale.dev/self-hosted/configuration/data-residency). Saving a model starts a scan of every source that was crawled without one and of every source whose last scan failed, so you do not add them again.

## Keep a URL list focused

A URL list fetches only the addresses you provide and follows no additional links. It can contain pages from several websites; Tale groups them into one source per website. A listed `http://` address is accepted and fetched as `https://`, unlike a whole-website `http://` domain, which is refused; a page that serves plaintext only stays out of reach either way. Adding another list for an existing URL-list source adds addresses without dropping the existing ones and updates its scan interval.

Use complete public URLs. Linked PDF and modern Office documents can be indexed when they contain readable text. A download served under a generic or legacy type (`application/octet-stream`, `application/vnd.ms-excel` on an `.xlsx` export) is recognised by its filename and its bytes. Images and scans without extractable text do not become searchable content.

## Understand discovery and refresh

For a whole website, the crawler uses the homepage and published sitemaps, including sitemap indexes and sitemaps declared in `robots.txt`. If usable sitemaps are missing, it follows links within the domain from the homepage. A page absent from both sitemaps and reachable links may be missed; use a URL list when specific coverage matters.

Scans are incremental. Unchanged content is skipped, changed content is indexed again, new pages are added, and removed pages leave the index — and so do pages `robots.txt` has come to disallow. A page that redirects to another address of the same site is indexed once, under the address it lands on. The row's page counts follow the scan as pages land, after discovery and after every stored batch, so the table moves while a scan runs. A URL list follows the same refresh schedule with its fixed selection. There is no separate publish step after successful indexing.

The crawler visits as an anonymous reader. Content that depends on a private session is not made accessible by adding its URL. It identifies itself on every request as `TaleBot/<version> (+https://docs.tale.dev/platform/knowledge/crawling)`, so a `robots.txt` group can address it by name — `User-agent: TaleBot` — to allow, throttle or refuse it alone.

The crawler applies `robots.txt` `Disallow` rules for the `*` agent on every path a URL can enter by — the sitemaps, the link walk and the links a rendered JavaScript page reveals — and again before every fetch: a page a rule covers is never fetched, and a page a rule added later covers leaves the index on the next scan. The rules do not filter an explicit URL list: a listed address is your instruction. On each content fetch, an HTTP `X-Robots-Tag: noindex` or `none`, or an HTML `<meta name="robots" content="noindex">` tag, prevents indexing, including for listed URLs, and drops whatever an earlier scan stored of that page. These rules are courtesy, not access control: do not rely on Tale's crawler as an access-control mechanism.

Use HTTPS on the standard port, and register a hostname: addresses with a non-default port, such as `:8001`, and bare IP addresses are rejected — the crawler dials by host name and verifies the certificate against it. Private addresses and redirects into private networks are blocked unless the operator has configured an allowed private-network deployment.

## Work within crawl limits

| Limit | Effect on coverage |
| --- | --- |
| 10,000 tracked URLs per website | A larger site can have undiscovered pages. Use a focused URL list for the material you need. |
| Three minutes for discovery, at most 50 sitemap fetches | Large or slow sitemap collections can be incomplete. |
| 100 MiB (`KNOWLEDGE_CRAWL_DOCUMENT_MAX_BYTES`) and 30 seconds per content fetch | Oversized downloads and slow responses fail (`timeout` for the download and the 20-second browser-render budgets); so does a page behind more than five redirects (`redirect_limit_exceeded`). |
| Five-minute processing budget per batch, up to 200 continuations | Long scans continue in batches. Work already being fetched or rendered can outlast a batch's budget; this is not a guaranteed total scan duration. |
| Five consecutive failures for an automatically discovered URL | The crawler stops scheduling that URL for seven days, then probes it once more. A failure of the render sandbox itself is not counted: when its egress proxy refuses the connection or its browser stops answering, the scan ends with that reason on the source and the next scan retries every page. Listed URLs remain eligible on each scan, and a listed page the site answers 404 for stays in the list with that answer on it. |

There is no configurable page cap, include/exclude path filter, or stop-scan button. A URL list narrows what you request; it does not remove these limits.

## Check what was indexed

The table shows **Status**, the **Indexed** page count, **Scanned**, and **Interval**. Open the source row to inspect its page list, word and chunk counts, and last-crawled times. Expand a page to read its stored text chunks. A failed fetch shows its reason and number of consecutive failures. A page the crawler skipped on purpose — the source asked not to be indexed, the content type has no readable text, or a redirect left the site — reads **Skipped** with its reason and does not count as failed.

| Status | Meaning |
| --- | --- |
| **Scanning** | A scan is in progress; a site you just added starts here. |
| **Active** | A scan completed successfully. Check page-level results for coverage. |
| **Error** | The scan failed, or attempted pages left the source with no stored content. Open the source for its reason. |
| **Deleting** | The source is being removed. |

A scan that was under way when Tale restarted, was updated or stopped without warning continues on its own within a few minutes, with the pages it had not reached yet. Pages that need the browser can follow up to a quarter of an hour later. The source reads **Scanning** throughout.

To scan outside the interval, open the source's row menu or its details and choose **Scan now**. Use it after the site changed, or after a failed scan, which otherwise retries on its own within two hours. The action is offered while the source is neither scanning nor being deleted.

The page view also offers search over indexed content. Try a distinctive phrase from a page before relying on it in chat, then ask a specific question and inspect the citation.

## Resolve a missing page

First check the address, source type, and latest scan time. Then open the source, narrow its page list to **Failed** or **Skipped**, and read the affected page's error.

| Reported issue | What to check or change |
| --- | --- |
| Certificate not trusted | The website operator must fix an expired, self-signed, mismatched, or otherwise untrusted TLS certificate. Repeated scans do not repair it. |
| Private address, refused redirect, or invalid URL | Use the intended public HTTPS address. Ask your operator about approved internal sources if needed. |
| HTTP error, network failure, or timeout | Open the original page and check availability. A later scan can recover after the source service is repaired. |
| Response too large | Publish a smaller document or split the source; the fetch limit is 100 MiB unless your operator set `KNOWLEDGE_CRAWL_DOCUMENT_MAX_BYTES`. |
| Source requests no indexing | The response sends `X-Robots-Tag: noindex` or `none`, or the page carries `<meta name="robots" content="noindex">`. The source owner must change that directive before Tale can index it. |
| Unsupported content or no readable text | JSON/XML endpoints, binary downloads, images, or scans may provide no supported page text. Supply an HTML page or a supported document with extractable text. |
| Rendering or document extraction failed | Check that the public page loads and the original document opens. Repair or re-export the source if it is damaged. |
| The assistant says web-page search is not set up | The organization has no working embedding model. An administrator sets one under **Settings > Data residency**; Tale then scans the affected sources again. |
| **Error** with "The embedding model couldn't process the pages." | The embedding provider refused or failed the request: a rejected credential, an exhausted balance, a rate limit that held through every retry, or an outage. The source's details say which, with the provider's own reply beneath. An administrator repairs the model under **Settings > Data residency** or its credential under **Settings > AI providers**; saving either one scans the affected sources again. After an outage on the provider's side, choose **Scan now** once it is back. |
| **Error** with "Scanning didn't run." | The crawler's browser could not start, so no page was rendered; its report is under **Technical details** in the source's details. The address is not the cause: ask your operator to check the sandbox service, then choose **Scan now**. |

A successful later fetch clears the previous error. A failed refresh can leave an earlier indexed copy available: **Active** and an indexed count do not prove every page is up to date. Compare the stored chunks and last-crawled information with the original before relying on a recent change.

If the source shows **Paused**, repeated failures to reach the knowledge database stopped scans. Ask an administrator to repair the connection under **Settings > Data residency**, then use **Resume scanning**.

# Documents
Source: https://docs.tale.dev/platform/knowledge/documents

Use **Knowledge > Documents** for files that belong in the shared library: policies, guides, reports, and supporting evidence. Members read documents within their access; Editors and higher roles can upload and manage them. For material that belongs to one project, use that project's [Knowledge tab](https://docs.tale.dev/platform/projects/manage-files).

<Frame caption="The document list brings together the original file, its source, indexing status, and team access. This view filters files to indexed uploads.">

![The Documents tab displays shared files with size, source, RAG status, and team columns.](https://docs.tale.dev/images/get-started/documents-list.webp)

</Frame>

## Upload from your device

1. Open **Knowledge > Documents** and the folder where the files should go. Use **New folder** if you need one.
2. Choose **Upload documents > From your device** and select the files.
3. Wait for the upload to finish, then find each row in the table.
4. Open a document to check its preview and details. Check the **RAG status** before asking the assistant about its content.

Use a descriptive filename and include a date or revision when it helps distinguish sources. Uploading another file with the same name creates a separate document; it does not replace the existing one.

## Understand upload and search support

A stored file and a searchable file are different states. Tale needs to extract text before it can index a document for knowledge search.

| Format | What to expect |
| --- | --- |
| PDF with embedded text, `.docx`, `.xlsx`, `.pptx`, `.odt`, CSV, plain text | Supported for text extraction and indexing. Check the result for the particular file. |
| Legacy Office `.doc`, `.xls`, `.ppt` | Can be stored and downloaded; convert to a modern format for indexing. |
| Images such as JPG, PNG, GIF, WEBP | Can be stored and downloaded; the knowledge index does not extract text from them. |
| Microsoft Loop files (`.loop`) imported from Microsoft 365 | Can be imported and downloaded; Tale cannot extract their text, so their status is **Not supported**. |
| Scanned PDF without readable text | Supply an OCR-processed or text version if search needs its content. |

Unsupported formats are not made searchable by repeatedly reindexing. For a question about an image, see [Chat attachments](https://docs.tale.dev/platform/chat/attachments), where an available vision model may read it directly.

## Read the indexing status

| Status | What it means and what to do |
| --- | --- |
| **Queued** | Waiting for an indexing slot. A busy library processes files in batches. |
| **Indexing** | Text is being prepared for search. Wait before testing the source. |
| **Indexed** | Indexing completed. Test a specific question and open its citation. |
| **Needs reindex** | The index is stale. Use **Retry indexing** beside the status. |
| **Failed** | Inspect the error, resolve its cause, then retry. |
| **Not supported** | These file contents cannot be indexed: the format may be unsupported, the text empty or unreadable, or the PDF damaged. Open the badge for the cause. |
| **Not indexed** | No completed index is available. Check the file and start indexing where offered. |

Interrupted jobs recover in the background or report a failure with a retry option. If a status does not progress, give an administrator the document name and error. They can check indexing services and the embedding configuration. Failed and unsupported files still use storage until removed.

## Recover from an indexing problem

Click **Failed** or **Not supported** to read the explanation. The next action depends on the cause, not just the filename extension.

| Cause | Next action |
| --- | --- |
| Unsupported format or image | Convert to a supported document with readable text. Uploading an image alone does not run OCR for knowledge search. |
| Empty text or scanned PDF without a text layer | Add the missing content or supply an OCR-processed version. Whitespace alone is also empty. |
| Binary contents behind a text extension | Export readable text, preferably UTF-8. Renaming a binary file to `.txt` does not convert it. |
| PDF cannot be parsed | Check that the original opens, remove password protection where permitted, or export a new PDF. A corrupt Office file may instead report a general indexing failure; check the original before repeatedly retrying. |
| A secret or personal-data policy blocks indexing | Remove the credential from the source, or ask an administrator to review the reported policy restriction. Then upload the corrected material or retry after the configuration is repaired. |
| Embedding model missing or provider account refused | An administrator must configure the model under **Settings > Data residency**, or repair the provider key, model access, plan, or balance. Then retry. |
| Embedding credential missing or unusable | The credential the embedding model uses was deleted or disabled, its provider has no default credential left (**Settings > Data residency** shows **Credential missing**), or its secret cannot be read: it was stored under an earlier encryption key, or it names an environment variable the server does not set. An administrator adds or repairs the credential under **Settings > AI providers**, or chooses another one for the embedding model. Either save puts the affected documents back in the queue. After a fix on the server itself, such as setting the environment variable, use **Retry indexing**. |
| Temporary provider or indexing-service failure | Background jobs retry transient failures. If the error persists, give an administrator the document name and error; after repair, use **Retry indexing**. |
| Search index rebuilding or repair failed | Rebuilding can recover automatically. A failed repair needs the operator to repair or restore the knowledge database before retrying. |

**Not supported** has no retry action: another attempt with the same bytes cannot fix the cause. Failed files can also require a source or configuration change before a retry helps. Applications can distinguish these cases using `indexing.errorCode`; the [API reference](https://docs.tale.dev/develop/api-reference) lists the stable codes.

<Frame caption="The status dialog explains that this document has no text to index. Supply readable content before uploading again.">

![The Document cannot be indexed dialog reports an empty document or scan without a text layer and recommends uploading readable text.](https://docs.tale.dev/images/platform/document-indexing-unsupported.webp)

</Frame>

## If the documents don't load

Documents lists folders and documents from two separate reads. When the documents cannot be loaded, Tale doesn't pass the folders off as everything there is:

- The folders stay listed, and you can still open them. A notice above the table says the documents couldn't be loaded and offers **Try again**, which repeats the read without reloading the page.
- The count below the table says it shows only the first items and that the rest couldn't be loaded. A search covers only what is listed.
- If documents were already listed when a refresh failed, they stay, and the notice says the list may be incomplete or out of date.
- While you retry, the rows stay on screen, and your search, filters and any open dialog are kept.
- If nothing at all can be loaded, the table shows the error and **Try again** instead of the empty state.

A folder that really holds no documents lists its subfolders without a notice. If **Try again** keeps failing, ask an administrator to check that Tale's services are running.

## Choose who can read it

Library documents default to **Organization-wide**. Use **Assign team** in the row menu to restrict a document to the chosen teams: members of any of those teams can read it, and Owners and Admins always can. Unless you are an Owner or Admin, you can only choose teams you belong to. A document inside a team folder takes the folder's teams and cannot name a team outside them, and moving a document into such a folder applies the folder's teams. These restrictions also apply to knowledge retrieval; an agent cannot make an inaccessible document visible through search.

The library root shows folders and documents that have not been filed in a folder. Open a folder to see its contents; a document inside it does not also appear as a file row at the root.

Folders organize the library; to rename one, use **Rename** in its row menu. A synced folder, the folders inside it and the folders that contain it keep their names, because each sync rebuilds that path. Check the **Teams** cell for access and the **Source** column for where a file came from. The **Teams** filter narrows the list to **Organization-wide** items, **My teams** (anything one of your teams can see), or a team by name; the selection is part of the page address, so a filtered list can be bookmarked. Project files are a separate scope and do not appear in this library. See [Knowledge](https://docs.tale.dev/platform/knowledge/overview) when deciding where to keep a source.

## Import from Microsoft 365 or Google Drive

Choose **From Microsoft 365** or **From Google Drive** under **Upload documents**. On first use, connect your account and authorize the import. If Tale reports that import is not configured, an administrator must set up the service under [Connectors](https://docs.tale.dev/platform/admin/connectors) before you can continue.

Select files or folders, then choose the import mode:

| Mode | Result |
| --- | --- |
| **One-time import** | Copies the selection once and preserves its folder structure. Later source changes do not update the copy. |
| **Sync import** | Keeps the supported selection current. New files arrive on a later sync; changed files reindex; deleted source files are removed from the mirror. |

In the library, the **Source** column shows where each file came from. An imported file carries the OneDrive, SharePoint, or Google Drive logo. Circling arrows beside the logo mean a sync import keeps the file current, and they appear on the synced folder itself too; the same arrows struck through mean a one-time import. Uploads, files an agent or automation wrote, knowledge entries, and API imports each show their own icon. Point to an icon to read the source in words.

Starting a folder sync can also reorganize an earlier import. If the same source file is already in Tale, the sync adopts that document and moves it into the matching sync folder, even when its content has not changed. This is a match to the source file, not merely to its name. A sync without a destination folder keeps the existing placement.

For Microsoft 365, choose **My OneDrive** or **SharePoint Sites**. Sync is available for personal OneDrive folders; SharePoint selections import once. For Google Drive, select from My Drive. Native Google Docs, Sheets, and Slides are skipped: export them to PDF or Office formats first.

If a folder is too large to list completely, Tale refuses that import. Select smaller subfolders or use sync where supported. If the selected source folder or file is deleted, its mirror is removed and the sync ends.

When an import ends, a notice reports the result. **Import completed** counts the files this import brought in together with those an earlier import had already brought in unchanged. If some files could not be imported, a warning such as **Imported 3 of 4 files** appears instead. When the first file that failed has a reason to show, such as a file larger than the upload limit, the warning names that file and the reason. If no file could be imported, the notice reads **Import failed**. If the picker is still open, import again to retry the files that failed. Files already imported are skipped.

If access to your Microsoft 365 or Google Drive account ends during an import, for example because the connection was removed or expired, Tale opens **Reconnect Microsoft 365** or **Reconnect Google Drive** instead of a notice while the import picker is still open. The dialog says how many files were imported before access ended; those files are kept. Reconnect your account, then import the same files or folders again to bring in the rest. Files already imported are not imported twice.

Closing the picker does not cancel an import already running. Its result appears in a notice without closing a picker you opened later or changing your new selection. If access ended, open the import again to reconnect your account.

A sync runs about every 15 minutes, under the account of the member who set it up. A file added at the source shows up in its folder within that window and then indexes like an upload. When a run cannot reach the source, the folder row's **Source** cell replaces the circling arrows with a red warning sign whose tooltip reads **Sync failed**, or with a red unplugged plug reading **Reconnect needed** when that member's Microsoft 365 or Google Drive connection has expired. Select the icon to see the cause, when the failures began, and whose account the sync uses; the files synced so far stay in place. That member is also notified in the bell and by email: at once for an expired connection, otherwise once the sync has been failing for an hour. Reconnecting the account, which the dialog offers to that member, resumes the sync on its next run. Any member who can import documents can instead start a new sync import of the same item to run it under their own account. The notice clears with the next successful run.

To keep the imported files without further updates, use **Stop syncing** on the file or folder row. Deleting the imported item also stops its sync. These actions leave the originals in OneDrive or Google Drive untouched. **Disconnect Google Drive** in the import dialog revokes that connection; reconnect when you need to import again.

## Revising a controlled document

Use a controlled document when approval must stay tied to the exact file that a reviewer saw. Replacing its draft updates the existing record; uploading another file with the same name still creates a separate document.

<Steps>

<Step title="Choose the controlled record">

For a regular upload, open the row menu and click **Mark as controlled**. It becomes `v1 · Draft`. An approved record offers both **Replace file** and **New revision**: use **New revision** only when you need the next draft without replacing its file.

</Step>

<Step title="Replace the current file">

Open the draft or approved record's row menu and click **Replace file**, then choose one file in the same format. A draft keeps its current revision. For an approved record, the dialog preserves approved vN and opens draft vN+1 only after the replacement succeeds; cancelling or a failed upload leaves vN approved. A legal hold blocks either path.

<Frame caption="The replacement dialog accepts one file in the record's existing format.">

![The Replace file dialog for a controlled text document, with a same-format file picker and a note that approved versions remain in history.](https://docs.tale.dev/images/platform/controlled-document-replace-file.webp)

</Frame>

</Step>

<Step title="Check and submit the revision">

Open the document preview and confirm that it shows the replacement. Then open the row menu and click **Submit for review**. The picker offers only members who can actually open the document — a project file needs project edit access — and never yourself: only the reviewer you name can approve or request changes, so every review is a second pair of eyes.

The draft freezes while the reviewer decides on that exact file; the reviewer is notified in the bell and by email, and the decision comes back to you the same way — a request for changes carries the reviewer's feedback, which the submit dialog also shows before your next attempt.

If the reviewer can no longer decide — they left the organization, were disabled, or lost access to the document — open the row menu and click **Change reviewer**: the pending request moves to the member you name, and the record stays frozen on the same file.

</Step>

</Steps>

## Delete with the contents in mind

**Delete** removes the document and its indexed content. The confirmation explains the impact; keep a copy if you will need the file later. Re-uploading creates a new document.

<Warning>

Deleting a folder permanently deletes its files and subfolders. For a synced folder, it also removes the sync configuration and history. The originals in Microsoft 365 or Google Drive remain untouched.

</Warning>

A controlled document with an approved version is protected from deletion, including while a later draft is being prepared. Its menu shows **Protected controlled record**. A folder containing such a record cannot be deleted either. Legal holds can also block changes or deletion; ask an administrator to check the specific restriction rather than uploading duplicates to work around it.

# Knowledge entries
Source: https://docs.tale.dev/platform/knowledge/knowledge-entries

Use a knowledge entry for a short fact that colleagues should be able to find again: support hours, a return window, or the owner of a process. Each entry has a topic and a body. Choose a [document](https://docs.tale.dev/platform/knowledge/documents) when the source is a whole policy or report, and [structured data](https://docs.tale.dev/platform/knowledge/structured-data) when named fields and exact values matter.

Members can read entries. Creating, editing, and deleting them requires the Editor role or higher. Entries belong to the organization's shared knowledge; do not use one for a personal note or a fact intended only for a particular project.

## Add a fact

<Steps>

<Step title="Open the entry form">

Go to **Knowledge > Knowledge entries** and click **Add entry**. If the action is missing, ask an administrator to check your role.

</Step>

<Step title="Give the fact a stable topic">

Enter a **Topic** such as `Support response target`. Use a name you would keep even if the answer changes. The topic can contain up to 120 characters and must be unique; edit the existing entry when Tale reports a duplicate.

</Step>

<Step title="Write enough context to use the answer">

In **Content**, state the fact, its scope, and any conditions. Markdown is supported, up to 8,000 characters. For example:

```markdown
Support aims to send a first response within 45 minutes during business
hours: Monday–Friday, 09:00–17:00 CET. This is a response target, not a
resolution deadline. Owner: Support Operations.
```

Avoid relative dates such as “next Friday” or references such as “the policy above.” An entry needs to make sense when retrieved on its own.

</Step>

<Step title="Save and check indexing">

Click **Save**. The entry appears in the table with its topic, content, source (**Manual** for the form, **Chat** for a fact the assistant captured, **API** for one an integration wrote over REST), indexing status, and update time. Open it to read the full content. Indexing happens in the background; saving the row does not mean search is already using it.

</Step>

</Steps>

<Frame caption="The table lets you check the fact and its indexing status before relying on it in an answer.">

![The Knowledge entries table lists manual facts with topic, content, source, indexing status, and update time.](https://docs.tale.dev/images/platform/knowledge-entries-list.webp)

</Frame>

## Correct an existing fact

Open the entry's row menu, choose **Edit**, change the content, and **Save**. Editing creates a new current version and queues its updated text for indexing. There is one current entry per topic, so correcting the existing fact avoids competing answers.

Open the entry's details to inspect **Version history** after a correction. Previous versions record what changed and when they were replaced; they are not additional current facts. An entry that was never edited says it has no earlier versions yet. The **Version ID** shown in the details belongs to the current version and changes with every edit; the topic identifies the entry across versions. An application can also create or update entries through the [REST API](https://docs.tale.dev/develop/api-reference).

<Tip>

When a chat uncovers a useful fact, verify it against the source, then add or edit an entry yourself. Chat does not automatically save facts to the organization's knowledge base.

</Tip>

## Remove an obsolete entry

Use **Delete** in its row menu and read the confirmation. Deletion removes the entry and its version chain from this view and makes its backing document unavailable to knowledge retrieval. Keep a copy before deleting if you still need the text; use **Edit** for a correction instead.

## If the fact is missing from an answer

Check the current entry before changing the prompt. Has it been saved, is its indexing complete, and does the question use a clear topic? If indexing failed, use the retry control after resolving the reported cause. Repeated failures need an administrator to check the organization's embedding configuration and indexing services.

Ask the assistant to cite the source, then open that source and compare it with the entry. A plausible answer alone does not establish that the latest fact was used. [Documents](https://docs.tale.dev/platform/knowledge/documents) explains the shared indexing states in more detail.

## If the list or the history doesn't load

When a read fails, Tale says so where the content belongs. It never shows the failure as an empty library or as an entry without history. **Try again** repeats the read without reloading the page:

- If no entries can be loaded, the table shows the error and **Try again** instead of the empty state.
- If entries are already on screen, they stay, and a notice above the table says the list may be incomplete or out of date. Your search and selected rows are kept while you retry. When further entries could not be loaded, the count below the table says so, and a search covers only the entries that loaded.
- In an entry's details, if **Version history** cannot be loaded, the section says so and offers **Try again**. The current content stays readable.

If **Try again** keeps failing, ask an administrator to check that Tale's services are running.

# Knowledge
Source: https://docs.tale.dev/platform/knowledge/overview

Knowledge is your organization's shared library. Add documents, short facts, public websites, contacts, and products so people and agents can work from the same sources. Start with the information you need to answer a real question; a small, current collection is easier to trust than an unreviewed archive.

<Video src="https://docs.tale.dev/videos/en/tutorials/ep3-knowledge/ep3-knowledge.en.mp4" poster="https://docs.tale.dev/videos/en/tutorials/ep3-knowledge/ep3-knowledge.en.webp" captions="https://docs.tale.dev/videos/en/tutorials/ep3-knowledge/ep3-knowledge.en.vtt" lang="en" title="Episode 3 — Knowledge" caption="Episode 3 — Knowledge (3:03)">

</Video>

<Frame caption="Start in Documents for files, or open the page that matches your source. This view filters files to indexed uploads.">

![The Knowledge area shows its Documents, Knowledge entries, Websites, Products, and Contacts tabs above a table of shared files.](https://docs.tale.dev/images/get-started/documents-list.webp)

</Frame>

## Choose the right place

| You have | Use | Why |
| --- | --- | --- |
| A policy, guide, spreadsheet, or report | **Documents** | Keep the original file and retrieve passages from supported formats. |
| A short fact such as support hours | **Knowledge entries** | Give it a stable topic and update one current answer. |
| Public pages that change over time | **Websites** | Crawl a whole website or a chosen URL list on a schedule. |
| People, organizations, and their contact details | **Contacts** | Keep names and other fields as structured records. |
| Items with product details | **Products** | Look up the record's fields instead of searching a paragraph. |
| Reference files for one piece of work | A project's **Knowledge** tab | Keep them within that project's access and chat context. |

Members can read content within their access. Editors and higher roles curate the shared library. Open a row, or choose **View** in its row menu, to see its details. If you can change a source, the same menu offers the actions that change it, such as **Delete**; contacts, products, websites, and knowledge entries also offer **Edit** there and in their details. The [structured-data guide](https://docs.tale.dev/platform/knowledge/structured-data) helps when a spreadsheet could be either a source document or a set of records.

## Make a source useful for answers

Uploading or saving is the first step. Documents, entries, and website pages also need to be **indexed**: Tale extracts their text and prepares it for search. Check the status before asking about newly added content. A file can remain downloadable even when its format cannot be indexed.

Use a clear title, include dates and scope in the content, and remove or correct outdated guidance. If two sources disagree, tell the assistant which one is authoritative and verify its citation. Adding more files does not resolve a contradiction between them.

<Tip>

Test a new source with a question whose answer you already know: “What are our support hours? Cite the source.” Open the cited source and compare the answer. This checks usefulness more directly than asking for a general summary of everything in the library.

</Tip>

## Understand access and search

Organization chat can search the shared library within your permissions. Project chat can also search that project's files and uses its saved instructions; it does not search another project's files. Project agents need the corresponding platform tools in their equipment.

Team restrictions continue to apply during retrieval. A file you can see in one workspace may therefore be absent from a different project's context. Use [project files](https://docs.tale.dev/platform/projects/manage-files) for project-specific material and document team access for shared library files.

If all searches fail, ask an administrator to check the embedding model and knowledge connection in **Settings > Data residency**. Operators can find setup details in [Data residency](https://docs.tale.dev/self-hosted/configuration/data-residency).

## Maintain each source

<CardGroup cols="2">

<Card title="Documents" icon="file-text" href="https://docs.tale.dev/platform/knowledge/documents">
Upload, import, check indexing, and maintain approved document revisions.
</Card>

<Card title="Knowledge entries" icon="book-open" href="https://docs.tale.dev/platform/knowledge/knowledge-entries">
Add a concise fact, correct it, and read its version history.
</Card>

<Card title="Websites" icon="globe" href="https://docs.tale.dev/platform/knowledge/crawling">
Choose pages to crawl, set the interval, and investigate missing pages.
</Card>

<Card title="Structured data" icon="table" href="https://docs.tale.dev/platform/knowledge/structured-data">
Choose records for exact fields and documents for supporting explanations.
</Card>

</CardGroup>

# Choose documents or structured records
Source: https://docs.tale.dev/platform/knowledge/structured-data

Use documents for information that needs paragraphs to explain, such as a contract or a meeting note. Use structured records for information that belongs in named fields, such as a contact’s email address or a product’s identifier. Most teams need both: the record identifies the thing, and the documents explain its history or context.

## Choose a home for the information

| Information | Put it in | Why |
| --- | --- | --- |
| A policy, contract, manual, or meeting note | **Documents** | Tale searches the text and retrieves relevant passages. |
| A short fact that needs its own update history | **Knowledge entries** | One topic has one current version, with earlier versions retained. |
| A person or organization you work with | **Contacts** | Named fields keep details together in a record you can update. |
| A product and its attributes | **Products** | Product details stay in fields instead of being buried in a file. |
| Pages on a public website | **Websites** | Tale crawls the pages and updates their searchable content on a schedule. |
| Reference files for one project | The project’s **Knowledge** tab | Access follows the project, and project chats can retrieve the files. |

The way information is stored affects how it is retrieved. Finding a passage in a document does not establish that the whole file was reviewed. Reading a record’s fields gives Tale those values; it does not guarantee that the source is current or that an answer based on it is correct.

## Combine records with supporting documents

Suppose you need to prepare for a call with Acme. Keep its contact details in **Contacts** and its contract and meeting notes in **Documents**, or in the relevant project’s **Knowledge** tab.

Ask the chat assistant to find Acme’s contact record and summarize the open questions from the latest notes. Check the record for the email address and the cited notes for the decisions. If the files belong to a project, start the chat inside that project so it can reach them.

<Tip>

Use the same recognizable company or product name in record titles and supporting files. Add dates to meeting notes and revision identifiers to policies so you can distinguish a current source from an old one.

</Tip>

## Create a contact

You need an Editor role or higher to maintain organization records. Open **Knowledge > Contacts**, choose **Add contact**, then **Manual entry**.

1. Enter the contact’s **Email**. Add a **Name** and **Phone** if useful.
2. Check **Locale**, which starts as `en`, and set the language appropriate to the contact.
3. Choose **Save**. The new row appears in Contacts with its details and added date.

The form holds each field to what Tale stores before it saves: a **Name** of up to 300 characters, a **Phone** of up to 50, a **Locale** of up to 20, and an **Email** with at most 64 characters before the `@`. A value past a limit is named under its field, and nothing is saved until you fix it.

To see only the contacts in one language, choose **Filter** above the Contacts list and pick the language under **Locale**. A language includes its regional variants: **FR** lists contacts whose locale is `fr`, `fr-CH`, or `fr_CA`. A contact without a locale appears only while no language is picked.

You can also add a contact while writing to them. In the **Inbox** view in Home, choose **New email** and type an address into **To**: if no contact carries it, the list offers **Add “…” as a contact**, which opens this same form with the **Email** already filled. Saving makes that contact the recipient, so you never leave the message you are writing.

If the email address already exists, find the existing contact and update it through the row menu instead of creating a duplicate; from **New email**, Tale selects the existing contact for you. Saving a contact creates a record; it does not send that person an email.

You can edit or delete the contacts your team entered or imported here, one at a time from the row menu. To delete several at once, tick their rows and choose **Delete selected**. Contacts that came from an integration, the API or a conversation belong to their source, which would overwrite a change made here: their row menu offers no **Edit** or **Delete**, and their rows have no checkbox.

## Create a product

<Frame caption="Knowledge > Products: each product is a record with named fields for stock, price, category, and status.">

![The Products tab of Knowledge lists three products: Team training workshop with 12 in stock at $950.00 in Services, marked Draft; Onboarding accelerator at $1,900.00 in Services; and Analytics Pro — annual license at $1,188.00 in Licenses, both Active.](https://docs.tale.dev/images/platform/knowledge-products-list.webp)

</Frame>

Open **Knowledge > Products**, choose **Add product**, then **Manual entry**. The form has three stages.

1. Under **Basics**, enter a **Product name**. Add a description and image if they help someone identify the product, then choose **Next**.
2. Under **Pricing & inventory**, set **Price** and **Currency** together. For example, enter `12.50` and select `CHF`; changing the currency does not convert the amount. Add stock and category when relevant, and check **Status**. A new product starts as **Draft**.
3. Under **Review**, check the details and choose **Create**. The product appears in the table with its price, status, and updated date.

Use the row menu to edit a saved product. Keep product names distinct so teammates can identify the right record, and review the price and currency before changing its status.

To add a product image, choose **Upload image** or drop a PNG, JPEG, WebP, GIF, or SVG file into the image area. The limit is 5 MiB. Wait for the preview before moving on. Tale checks the uploaded bytes; if it refuses the file, the message under the image field says why — an unsupported format, a file over the limit, or an SVG that carries scripts or event handlers — so you know whether another file is needed.

The uploaded image stays available after you save and reload the product. Other organization members with product access can view it once the product is saved; the image address requires a signed-in session and is not a public sharing link. To remove it, edit the product, choose **Remove image**, then save. Removing or replacing the image, or deleting the product, removes the upload itself as well, unless another product still shows it.

If you choose **Or paste a URL**, enter a complete public HTTPS address, starting with `https://`. The form names an incomplete address under the field before you can continue. Tale refuses unsafe or disallowed hosts; ask an administrator if you need an internal image source. Images loaded from external addresses follow that source’s access rules.

## Keep access and freshness in view

A record or document is useful only to people who can access it. Check its team scope when a teammate cannot find it. Project files follow project access rather than the document library’s team tags; see [Project files](https://docs.tale.dev/platform/projects/manage-files).

Update the authoritative record when a detail changes. For a revised document, wait until indexing finishes before testing a question against its new text. Website content follows its configured scan interval, so it may lag behind the live page.

## Work with the available record types

The Knowledge area provides Contacts, Products, and Websites. **Settings > Governance > Models** controls AI model access and defaults; it does not create custom record types or database fields.

If the available fields do not fit your material, keep the detail in a document and link the surrounding process to the appropriate record. For programmatic imports and the fields each resource accepts, use the [API reference](https://docs.tale.dev/develop/api-reference).

Read [Documents](https://docs.tale.dev/platform/knowledge/documents) to upload and verify a file, [Knowledge entries](https://docs.tale.dev/platform/knowledge/knowledge-entries) to maintain one fact, or [Crawling](https://docs.tale.dev/platform/knowledge/crawling) to keep public pages searchable.

# Install Tale as an app
Source: https://docs.tale.dev/platform/member/install-as-app

Install Tale if you want a launcher icon and a separate app window. Use the same Tale address and account as in your browser. Installation does not create another organization or copy your chats into a new account.

## Install on a computer or Android

Open your Tale instance in a supported browser. Open the account menu from your name or avatar and choose **Get app**, then accept the browser’s installation prompt. Tale shows this action when the browser makes installation available.

If the action is missing, check the browser’s own menu. Chrome provides **Cast, save, and share > Install page as app** on desktop; wording varies by browser and device. [Chrome’s app guide](https://support.google.com/chrome/answer/9658361?hl=en) covers installation and management.

Open the new icon and confirm that you reach the intended Tale instance. Sign in if asked, then check the organization in the account menu. A browser profile or an installed app may have a different sign-in state.

## Install on iPhone or iPad

In Tale’s account menu, **Get app** opens manual installation instructions on iOS. The browser performs the installation.

In Safari, open Tale, choose **Share > Add to Home Screen**, and confirm **Add**. If **Open as Web App** is shown, leave it enabled for a standalone window. Apple documents the current controls in its [iPhone app installation guide](https://support.apple.com/guide/iphone/open-as-web-app-iphea86e5236/ios).

Other iOS browsers can also offer **Add to Home Screen**. If your browser does not expose it, open the same address in Safari. The installed app’s cookies can become separate from the browser’s after installation, so signing out in one window does not necessarily sign out the other. [WebKit’s web-app behavior](https://webkit.org/blog/14787/webkit-features-in-safari-17-2/) explains this separation.

## Understand what changes

Your organization, permissions and saved content stay on the Tale instance. Installation changes how you launch and display it. It does not install a local model or make server-dependent work available without a connection.

Notifications still depend on browser and operating-system support, permission, and your Tale preferences. Installing the app alone does not grant notification permission. If you change device or reinstall, check those permissions again.

## Remove the installed app

Use the browser or operating system’s **Uninstall** or **Delete App** action. Removing an icon from the macOS Dock only removes that shortcut. In Chrome, use the installed app’s menu or `chrome://apps`; deleting its browser data may also sign you out.

Uninstalling the app does not delete your Tale account, organization or server-side documents. Use [Profile and account](https://docs.tale.dev/platform/member/preferences) for account changes. On a shared device, sign out of both the app and any browser session you used.

## If installation is unavailable

| What you see | What to try |
| --- | --- |
| No **Get app** action | Check the browser’s installation menu and whether the app is already installed. |
| No install option in a private or managed browser | Try a regular window, or ask the device administrator about installation policy. |
| The icon opens the wrong instance | Check the address in the original browser, then install the intended instance. |
| App opens but cannot load content | Check network access and whether the Tale instance is running. |

# Member
Source: https://docs.tale.dev/platform/member/overview

As a Member, use Chat to ask questions and read the knowledge and project content shared with you. Your organization’s setup and team memberships determine the resources you see. You can also create project tasks and put project agents to work on them, maintain your account preferences, and create reusable skills.

## Start your day

<CardGroup cols="2">

<Card title="Ask a useful question" icon="message-circle" href="https://docs.tale.dev/tutorials/member/chat-effectively">

Practice with a source, check the facts, and ask a follow-up.

</Card>

<Card title="Read shared knowledge" icon="library" href="https://docs.tale.dev/platform/knowledge/overview">

Find documents, facts, and records, and understand why a source may be unavailable.

</Card>

<Card title="Understand projects" icon="folder-open" href="https://docs.tale.dev/platform/projects/concepts">

Learn which files and conversations belong to a project and which chats remain personal.

</Card>

<Card title="Manage your account" icon="user" href="https://docs.tale.dev/platform/member/preferences">

Edit your profile, check your usage limits, and understand saved preferences and chat management.

</Card>

</CardGroup>

Move between your daily work with the [main navigation](https://docs.tale.dev/platform#navigation). Each section opens on its own first page; on a computer, **Home** reopens the chat you last read instead, and choosing it again starts a new chat. [Home](https://docs.tale.dev/platform#home) also lists your projects, the open tasks assigned to you or waiting for your review, and the inbox when your organization has one.

## Hand work to a project agent

When you need a deliverable, such as a summary of several contracts or a translated document, open a project you can access and create a task on its **Tasks** tab. Describe the result and how you will check it, attach the files it depends on, and assign one of the project's agents. **Start agent** puts it to work: the agent reports in the task's comments and moves the task to **In review**. Read the report and open the deliverables, then move the task to **Done** when you accept the result.

You can change the tasks you created and the tasks assigned to you. On other people's tasks you read and comment. Setting up the agents themselves, and the project's settings and files, stays with Editors. [Manage tasks on a project board](https://docs.tale.dev/platform/projects/tasks#who-can-create-and-change-tasks) and [Delegate a task to an agent](https://docs.tale.dev/platform/projects/task-automation) go into the details.

## Follow a notification

A notification link opens the related task, document or conversation. If you need to sign in first, Tale keeps the destination and opens it after sign-in. Your account still needs access to the organization and the linked content. For a private deployment, connect to its required network before opening the link.

## If an action is missing

Members read the shared library; Editors and higher roles maintain its content. In a project, you change the tasks you created or that are assigned to you; its settings, agents, and files stay with Editors. Automations and technical setup require Developer or administrator permissions, so Members and Editors don't see **Automations** at all. Ask for the access needed for your task rather than assuming every visible resource is editable. [Members and roles](https://docs.tale.dev/platform/admin/members-and-roles) explains the differences.

# Manage your account and preferences
Source: https://docs.tale.dev/platform/member/preferences

Your account settings control how teammates recognize you and how you sign in. Your profile menu also lets you switch organization and language and shows the teams you belong to. These controls are available without an administrator role.

## Update the name your teammates see

Open **Settings > Account**. Under **Profile**, edit **Name** and click **Save** in the page header. **Discard** restores the saved value. Your email address is shown as read-only because it identifies the account used to sign in and receive notifications.

The name is visible to teammates and can be at most 100 characters long. It is not a private instruction to the assistant.

## Protect your sign-in

The **Password** section offers **Change password**, or **Set password** for an account that does not yet have one. Follow the password requirements shown in the dialog. They come from your organization's password policy. If you belong to several organizations, your password must meet the requirements of every one of them. Changing the password signs out your sessions, so keep the new password available before confirming. A wrong current password counts toward the same temporary lock as a failed sign-in.

Set up an authenticator under **Two-factor authentication** or add a passkey under **Passkeys**. Store backup codes somewhere you can reach without signing in to Tale. [Two-factor authentication](https://docs.tale.dev/platform/admin/two-factor-authentication) covers setup, recovery, and organization requirements.

## Switch language or workspace

Open the profile menu from your avatar. **Language** changes the interface language. When you belong to several organizations, **Organization** switches the workspace. The **Teams** row names the teams you are in and opens the account page; it switches nothing, because a team is not a workspace.

Check the organization name before changing settings or adding content.

## See your role {#role}

**Settings > Account > Your role** shows your role in this organization, such as Editor or Member. Your role decides what you can do; your teams decide which team work you can see. Admins assign roles under [Members and roles](https://docs.tale.dev/platform/admin/members-and-roles). With single sign-on, your identity provider can also set your role each time you sign in. Owners and Admins see a **Manage members** button beside the section's title.

## See your teams {#teams}

**Settings > Account > Your teams** lists the teams you belong to. Teams decide which team documents, projects, and inbox queues you can see; work shared with the whole organization is visible to you regardless. When you are in no team, the section says so. If your teams can't be loaded, the section says that instead of claiming you are in no team. Choose **Try again** to load them. When a refresh fails, the teams already shown stay, with a note that they may be out of date.

To narrow a list to certain work, use its **Teams** filter: **Organization-wide** shows only items without a team, **My teams** shows items any of your teams can see, and each team is listed by name. The inbox offers an **Assignee** filter behind its search box, listing people and teams together. A filter changes the current view; it does not grant access to another team’s data.

Owners and Admins manage membership under [Teams](https://docs.tale.dev/platform/admin/teams); the section's **Manage teams** button takes them there.

## Set custom instructions for the chat assistant

Open **Settings > Preferences**. **Custom instructions** are standing instructions the chat assistant follows in every reply to you, such as a preferred tone, a default programming language, or how much detail you want. The switch can follow the organization default or store your own choice; the hint under it says which applies. The text field appears while the feature is on. Type your instructions and click **Save** in the page header.

<Frame caption="Preferences holds your custom instructions and the switch that turns them on.">

![The Preferences page shows the Custom instructions switch and its text field.](https://docs.tale.dev/images/platform/settings-preferences.webp)

</Frame>

<Note>

Your instructions never override the organization’s mandatory instructions or a project’s **General > Instructions**; where they conflict, those take precedence. Turning the switch off keeps the text for later without applying it.

</Note>

## Check your usage limits {#usage-limits}

Open **Settings > Usage** to see how much you have used of each limit your organization applies to you. The page says so when no limit covers you.

<Frame caption="Settings > Usage lists each limit that applies to you with its usage and next reset.">

![The Usage page lists personal monthly token, cost, and request limits and the organization's shared monthly limits, each with a usage bar and its reset date, above the storage used against the per-user limit. An administrator also sees a Manage limits button.](https://docs.tale.dev/images/platform/settings-usage.webp)

</Frame>

- **Your limits** count your own chats, voice output, and agent runs, whichever way you started them; [How usage is counted](https://docs.tale.dev/platform/admin/governance/usage-attribution) explains who a run counts against. When one is reached, you can't start more of that work until it resets: a message you send then is refused with a notice that names the limit, and it stays in the composer.
- **Shared limits** count the usage of everyone they cover, such as a team you belong to or the entire organization, so they can be reached before your own limits.
- **Storage** compares the files you have uploaded with your storage limit. New document uploads are refused once it is reached.

Each usage limit shows the amount used, the limit, and when it resets in your local time. Periods follow UTC: daily limits reset at midnight, weekly limits on Monday, and monthly limits on the first of the month. If an administrator set a warning threshold, the bar turns amber once your usage reaches it. When a banner above the composer warns about a limit, **View usage** opens this page. Administrators also see **Manage limits**, which opens **Governance > Policies & Limits**.

## Archive old chats or sign out

**Settings > Account > Your chats** offers **Archive all chats** and **Delete all chats** for your own chats in the current organization, including project chats. Archiving affects unarchived chats; deleting also includes archived chats and moves them to Trash, where they can be restored during the retention grace period. Chats under legal hold remain unchanged, and chats with a running reply cannot be deleted.

Read the confirmation before proceeding. The result reports how many chats changed and how many could not be changed. Use an individual chat's menu in Home when you only want to organize that conversation. Archived chats stay under **Archived** at the bottom of the Home list, where **Unarchive** in a chat's menu brings it back.

**Log out** in the profile menu ends the current session and returns you to sign-in. Sign out on a shared device when you finish using Tale. For a dedicated app window on your own device, see [Install as app](https://docs.tale.dev/platform/member/install-as-app).

If your session ends while Tale is open, for example because you logged out in another tab, a refused request shows **Your session has ended. Sign in again.**, and a document upload fails with the same sentence and no retry. A project's **Environment** tab you open afterwards shows **Admin access required** instead. One that was already open, or that you open again less than five minutes after it last loaded, still shows its variables, and saving there shows the same sentence. **Settings > Data residency** says **You're not allowed to manage this organization's data residency.** On your organization's pages, whose addresses start with `/dashboard`, Tale checks the session and asks before opening sign-in. Signing in leaves the page, so unsaved changes may be lost. Choose **Stay here** to keep the page and copy any work you need. Further refusals do not reopen the confirmation. On other pages, Tale doesn't ask: reload the page to sign in again.

When you are ready, close any open dialog and choose **Sign in** in the notice that stays at the top of the page, above its header, then confirm. Tale checks again before leaving; if another tab has already restored your session, your page stays open. Otherwise, the sign-in page shows the same session notice. After signing in, you return to the page you were on; copied work can be re-entered, but unsaved drafts are not restored automatically.

# Choose an available model
Source: https://docs.tale.dev/platform/models

The model picker shows what your organization can currently use, not every model a vendor sells. A usable provider credential, its model allowlist and the organization’s access rules all affect the result. An administrator manages these under **Settings > AI providers** and [Content & models](https://docs.tale.dev/platform/admin/governance/content-models).

## Choose automatic or explicit selection

In Chat, **Auto** selects a model for each message using the message’s characteristics, such as length, code and attached documents. It uses a lightweight heuristic, not a second AI request. Inspect a reply’s details to see which model actually answered.

Choose a specific model in the composer when you need to compare results, control the choice or use a model suited to a known task. That selection remains until you change it or return to Auto. [Arena](https://docs.tale.dev/platform/chat/arena-mode) lets you compare two available models with the same prompt.

Project agents and workflow model steps use their configured model. An agent’s picker distinguishes entries from different providers, even when the model ID is the same. Selecting an entry pins that provider/model pair. A model failure is reported rather than silently answered by a different model.

## Understand where the list comes from

Open **Settings > AI providers** to inspect the provider and its offered models. The catalog count describes the provider’s available definitions; it does not establish that your organization has permission or credentials to call all of them.

| Source | How models enter the catalog | When it changes |
| --- | --- | --- |
| Built-in catalog | Model definitions ship with Tale. | With a platform/catalog update. |
| OpenRouter catalog | Tale fetches OpenRouter’s list. | After a fetch or explicit refresh. |
| Provider models endpoint | Tale fetches the provider’s own model list. | After a fetch or explicit refresh. |
| No catalog | Model IDs come from the credential’s allowlist. | When an administrator edits that list. |

Azure OpenAI and Nous Portal use credential-defined model IDs. For Azure, enter your resource’s deployment names, which may differ from public model names. An empty allowlist on a provider with no catalog makes no models available.

## Refresh a fetched catalog

Owners, Admins and Developers can select **Refresh catalogs** in the settings header. Read the result for each provider: it reports the model count or the error that prevented refresh. A failed refresh is not evidence that the provider offers zero models.

Remote catalogs are cached for 24 hours and refreshed on demand when the cache is stale. The button forces a fresh attempt. A failed automatic fetch can continue serving a previous catalog or shipped defaults; a forced refresh reports the failure. A newly published model also needs to pass credential and policy checks. Built-in-only deployments have no remote catalogs to fetch.

## Find why a model is missing

Check these boundaries in order, or give the details to an administrator if you cannot edit settings:

1. Confirm the provider has an enabled, usable credential. A catalog entry by itself is not an account connection.
2. Inspect that credential’s **Model allowlist**. For a catalog provider it restricts the list; for a provider without a catalog it defines the list.
3. Check the model-access rules for the relevant organization, team or user under [Content & models](https://docs.tale.dev/platform/admin/governance/content-models).
4. For a project agent, check that the credential supports its selected [harness](https://docs.tale.dev/platform/agents/harnesses). A subscription may work only with its required runtime, and a model whose tool calls need OpenAI’s Responses API, such as GPT-6.1 Sol, is offered only for Codex.
5. In Chat, a model that only a subscription credential serves is not offered: a subscription runs only in tasks and automations, and the chat model list names the subscriptions it leaves out. Add an API key or environment-variable credential to chat with that model; [AI providers](https://docs.tale.dev/platform/admin/providers#use-subscriptions-in-tasks-not-in-chat) explains why.

If the model is visible but a call fails, read the displayed reason. Expired credentials, provider failure, budget limits and lack of sandbox capacity are different problems. Refreshing a catalog cannot repair all of them. [AI providers](https://docs.tale.dev/platform/admin/providers) covers credentials; [Policies and limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits) covers spending refusals.

# Triage the project backlog
Source: https://docs.tale.dev/platform/projects/backlog

Use **Backlog** for proposed work the team has not committed to yet. It is a normal task status, shown first in the board and list. A proposal can already have an assignee; assignment alone does not make it active work. A proposal assigned to you still appears among your tasks in [Home](https://docs.tale.dev/platform#home), marked **Backlog**.

## Capture a proposal

Open the project’s **Tasks** and create a task. Choose **Backlog** in the status picker; new tasks otherwise default to **To do**. Give the proposal a title describing the outcome and enough context for someone to decide whether to pursue it.

For example, “Check the mobile checkout error” is easier to triage with the affected page, a reproducible symptom and a screenshot than with a title alone. Leave implementation detail open until the problem is understood.

A project agent with the task-creation tool can also create a proposal. That tool allows initial **Backlog** or **To do** status, not a working or finished status. The same boundary applies when an automation uses the project’s task tools.

## Decide what happens next

| Decision | Action |
| --- | --- |
| More information is needed | Keep **Backlog** and explain the missing information in the description or a comment. |
| The team accepts the work | Set **To do** and choose an assignee. |
| Work has started | Move to **In progress**. |
| The proposal will not be pursued | Set **Cancelled**, preserving the task’s discussion. |

Change status in the task detail or drag the card between board columns. These are the same controls used for other tasks; Backlog has no separate accept or reject workflow.

## Hand the task to an agent

Choose an agent from the same project and make the expected result explicit before clicking **Start agent**. Assigning it does not replace that start action. Use [Task automation](https://docs.tale.dev/platform/projects/task-automation) for prerequisites, progress and review.

## Understand where proposals come from

The shipped **Triage GitHub issues** automation returns a ranked report. It does not create project tasks or fill Backlog automatically. A person or an appropriately equipped agent must turn a selected issue into a task. This keeps the decision to accept work separate from the report that recommends it.

[Manage project tasks](https://docs.tale.dev/platform/projects/tasks) covers task details, comments, dependencies and the rest of the board.

# Project concepts
Source: https://docs.tale.dev/platform/projects/concepts

Use a project when several questions or tasks depend on the same reference material. A project brings together files, instructions, chats, a task board, and task agents. A one-off question can stay in an ordinary chat; a launch, customer handover, or ongoing investigation usually benefits from a project.

## What the project keeps together

| Area | What belongs here |
| --- | --- |
| **General** | Name, description, standing instructions, sharing, and the default task reviewer. |
| **Chats** | Your project conversations and the conversations explicitly shared with the project. |
| **Knowledge** | Reference files organized into folders and scoped to this project. |
| **Tasks** | Work with an owner, status, comments, and a result to review. |
| **Agents** | Named agents configured to work on tasks. |

Project chat starts with the saved project instructions. It can search this project's files together with the organization's accessible knowledge. This gives later conversations a common starting point without copying a brief into every message. Other projects' files are outside that search scope.

<Frame caption="General holds the project instructions and sharing controls. Save after changing the fields.">

![The General page of Website relaunch shows the name, description, Instructions editor, Sharing section, and Save and Discard controls.](https://docs.tale.dev/images/platform/project-general-tab.webp)

</Frame>

## Create an identity people can recognize

**Create project** asks for a name and a **Project key**, with an optional description, icon, and color. The key becomes the prefix of task IDs such as `WR-1` and cannot change after creation. Choose a short, durable abbreviation.

You can revise the name, description, icon, color, and instructions on **General** later. Use **Save** to apply field edits or **Discard** to abandon them. For a complete walkthrough, follow [Use projects](https://docs.tale.dev/tutorials/member/use-projects).

Write instructions for recurring context: what this work covers, which sources take precedence, and how to handle missing information. Put a one-time request in a chat or task description. Project instructions should not become a log of every past decision.

## Check who can open it

New projects default to **Org-wide** access. Choose teams under **Who can see it** when you create a project, or under **Audience** on **General** later. An empty audience means everyone in the organization; otherwise members of any listed team can open the project, and organization administrators always can. Unless you are an Owner or Admin, you can only pick teams you belong to. Removing a team later hides the project from members outside the remaining teams, and the page asks you to confirm that. Sharing is based on teams rather than individual invitations; the project list shows each project's teams in its **Sharing** column and offers a **Teams** filter.

Project files follow project access. They do not appear as ordinary library documents, and a team tag on a library file does not make that file a project attachment. [Manage files](https://docs.tale.dev/platform/projects/manage-files) explains moving documents and how removing a file from a project can widen its audience.

## Keep personal and shared chats distinct

A chat inside a project starts as your own conversation. Other project members do not see it simply because they can open the project. **Chats** separates **Your chats** from **Shared with project**; use **Share with project** when the conversation is ready for colleagues.

Colleagues open a shared chat read-only: they cannot reply, edit a message, or rate an answer. Where you edited a message or retried an answer, they read the version you have selected, not the one it replaced.

Read the messages before sharing, including any sensitive information the answer quotes. Moving a shared chat to a different project, or out of the project, ends its project share. Share it again deliberately if the new audience should read it.

Use **Move to project…** in a chat's actions, or drag the chat onto the project in Home, when an existing conversation belongs with this work. Organization-wide snapshot links are a separate option, described in [Share a chat](https://docs.tale.dev/platform/chat/shared-threads).

## Turn discussion into work

Create a [task](https://docs.tale.dev/platform/projects/tasks) when a decision needs an owner or a result. A teammate can complete it manually, or a configured [project agent](https://docs.tale.dev/platform/projects/project-agents) can work on it. Keep the acceptance criteria in the description so the reviewer can judge the result.

Archive a finished project when you want it out of the active list. An archived project is read-only for everyone — its settings, tasks, files, and agents can be read but not changed — until a project administrator restores it from **General**. Before deleting, read the choice about its contents: detaching leaves files in the library and chats as personal conversations; deleting the contents removes them too. Detaching files can widen access, so choose according to what should remain available.

# Manage project files
Source: https://docs.tale.dev/platform/projects/manage-files

The project’s **Knowledge** tab holds files that its chats can retrieve. Upload a reference once and use it across conversations in that project. You need project edit access to add, organize, or remove files.

<Frame caption="Files belong to the project, and their indexing badges show whether chat can search their text.">

![The Knowledge tab of Website relaunch contains two indexed files, a New folder button, and file and folder upload controls.](https://docs.tale.dev/images/platform/project-knowledge-files.webp)

</Frame>

## Upload into the right folder

1. Open the project and select **Knowledge**.
2. Select a folder, or leave the root selected.
3. Click **Add file** or drop files onto the upload area.
4. Check that each file appears in the intended folder and finishes indexing.

**New folder** creates a folder at the root. A folder’s **New folder inside** action creates a subfolder. **Upload folder** imports a folder from your device and recreates its structure under the selected location. A folder upload is limited to 200 files and 200 MB; split larger folders and check the report for skipped files.

## Check whether chat can read a file

| Status | Meaning and action |
| --- | --- |
| **Queued** | The file is waiting to be processed. |
| **Indexing…** | Tale is preparing its text for search. |
| **Indexed** | The text is searchable; verify a question against the original file. |
| **Failed** | Open the failure detail when available and use **Retry indexing**. Ask an admin if the failure returns. |
| **Not supported** | These contents cannot be indexed. Supply readable text or a supported format; retrying the same file cannot help. |
| **Not indexed** | The file is stored but not searchable. Use **Index now** when offered, or convert a format without a text extractor. |

An integration can upload a file without indexing it. Such a file is still visible in the tree; a supported plain-text file can be read directly when named, but it will not appear in text search until indexed.

When not every file arrives, the upload report lists the rest with a reason: **Skipped** files failed the type or size check before uploading, and **Not added** files were refused by Tale, which says why. Per-file and storage limits may be restricted further by organization policy. When an upload fails, first try a small supported file. An admin can check [Policies and limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits), storage, and the embedding model.

## If files or folders don't load

When the tab cannot load the project's files or folders, a notice above the tree says what failed and offers **Try again**. Tale never shows the project as empty because a read failed:

- If only the folders fail to load, every file that loaded stays listed. Files at the root stay in place, and files inside folders appear under **Files inside folders** until the folders load.
- If only the files fail to load, the folders stay visible and the notice says the files are missing.
- If a refresh fails after the tree has loaded, the tree keeps what it showed, and the notice says it may be out of date.

**Try again** repeats only the read that failed, and the tree keeps its expanded and selected folders. If it keeps failing, ask an administrator to check that Tale's services are running.

## Ask about the files from a project chat

Open **Chats** in this project, start a chat, and ask about the file by name or topic. The assistant can retrieve this project’s files and the organization’s Knowledge documents that you can access. It cannot retrieve another project’s files from here.

The organization’s general chat does not search project files. Files also stay out of the organization’s document list and WebDAV library while they belong to the project. Project access determines who can read them; project files do not have separate team tags.

## Replace a controlled file without losing its review history

Uploading another file with the same name creates a separate document; a matching filename is not a revision link. For a file whose approval must remain tied to exact bytes, use the row menu’s **Mark as controlled** action.

A controlled record starts as a draft. **Replace file** updates a draft or opens the next draft from an approved version while preserving that approved version. **Submit for review** freezes the draft for the named reviewer. See [Controlled documents](https://docs.tale.dev/platform/knowledge/documents#revising-a-controlled-document) for the complete lifecycle and reviewer rules.

## Move to Knowledge or delete

**Remove from project** moves the file to the organization’s Knowledge library. It does not delete the file.

<Warning>

Removing a file from the project makes it visible to everyone in the organization. Use this only when you intend to publish it to that wider audience. Read the confirmation before proceeding.

</Warning>

To remove a file entirely, use **Delete** in its row menu and read the deletion confirmation. Folder deletion removes its contained files and subfolders as well as their search entries. These actions cannot be undone through the file tree. Legal holds and protected controlled records can block deletion.

**Delete** is offered for files uploaded here and for files an agent wrote into the project, such as readings or generated reports. A file synced from a connector offers no Delete in the project, because the next sync would restore it; remove it at its source instead.

If a file serves several unrelated projects, consider keeping an appropriately scoped copy in the [Knowledge library](https://docs.tale.dev/platform/knowledge/documents). Avoid maintaining several conflicting copies of the same policy.

# Projects
Source: https://docs.tale.dev/platform/projects/overview

A project keeps the files, instructions, conversations, and tasks for one piece of work together. Use one when context needs to last beyond a single chat or when a result needs an owner and a review. Start with [Use projects](https://docs.tale.dev/tutorials/member/use-projects) to create a project and ask a question about its reference file.

<Video src="https://docs.tale.dev/videos/en/tutorials/ep6-projects/ep6-projects.en.mp4" poster="https://docs.tale.dev/videos/en/tutorials/ep6-projects/ep6-projects.en.webp" captions="https://docs.tale.dev/videos/en/tutorials/ep6-projects/ep6-projects.en.vtt" lang="en" title="Episode 6 — Projects with AI" caption="Episode 6 — Projects with AI (2:21)">

</Video>

<Frame caption="The task board makes proposed work, work in progress, and results awaiting review visible together.">

![Website relaunch shows task cards across Backlog, To do, In progress, In review, Done, and Cancelled.](https://docs.tale.dev/images/platform/projects-task-board.webp)

</Frame>

## Find the next step

<CardGroup cols="2">

<Card title="Understand project access" icon="compass" href="https://docs.tale.dev/platform/projects/concepts">
Learn what the project shares, which chats stay personal, and how teams control access.
</Card>

<Card title="Manage reference files" icon="folder-open" href="https://docs.tale.dev/platform/projects/manage-files">
Upload and organize files, check indexing, and manage controlled revisions.
</Card>

<Card title="Create and track tasks" icon="list-checks" href="https://docs.tale.dev/platform/projects/tasks">
Set an owner, reviewer, dates, and acceptance criteria; follow progress on the board.
</Card>

<Card title="Configure a project agent" icon="bot" href="https://docs.tale.dev/platform/projects/project-agents">
Choose a harness, model, tools, and instructions for an agent that can take tasks.
</Card>

<Card title="Run and review agent work" icon="workflow" href="https://docs.tale.dev/platform/projects/task-automation">
Start a task, review the result, request rework, and recover a failed run.
</Card>

<Card title="Triage proposed work" icon="gauge" href="https://docs.tale.dev/platform/projects/backlog">
Use Backlog to review ideas before committing them to the team's work.
</Card>

</CardGroup>

Every project you can open is listed under **Projects** in [Home](https://docs.tale.dev/platform#home), where **All projects** opens the full list. A project opens on its task board; **General**, **Chats**, **Knowledge**, and **Agents** sit beside the task views. For Owners, Admins, and Developers, a bound automation adds an **Automations** surface; project administrators can configure **Environment**. Installed apps may add further tabs; you do not need them to start with files, chats, and tasks.

# Create and manage project agents
Source: https://docs.tale.dev/platform/projects/project-agents

Create a project agent when you want a reusable worker for that project’s tasks. It combines a coding runtime, a model, instructions and allowed equipment. You need project edit access; the project must be active. Members see the project's agents on its **Agents** tab, which tells them to ask an Editor or Admin for a new one. Until a project has agents of its own, its tasks can go to the organization's [standard agent](https://docs.tale.dev/platform/projects/project-agents#standard-agent). Only Owners and Admins can change secret grants.

## Prepare the first task

Choose a small outcome, such as reviewing a launch brief for missing approvals. The agent needs compatible [provider credentials](https://docs.tale.dev/platform/admin/providers) and an available [sandbox](https://docs.tale.dev/platform/admin/sandboxes). It can be configured without proving that a sandbox run will succeed.

Separate reusable instructions from the task. “Identify missing evidence and report the checks you performed” belongs on the agent. The document, review date and acceptance criteria belong on the task.

<Frame caption="The Agents tab — the project's own agents, each row naming its harness, serving provider, and model.">

![The Agents tab of the Website relaunch project listing two named agents — Content editor on Claude Code and Redirect auditor on Codex — each row naming the serving provider and model id, beside a New agent button.](https://docs.tale.dev/images/platform/project-agents-models.webp)

</Frame>

## Configure the agent

<Steps>

<Step title="Name it and choose the runtime">

Open the project’s **Agents** tab and select **New agent**. Give it a recognizable **Name**, then choose **Agent type**, the coding [harness](https://docs.tale.dev/platform/agents/harnesses). Names are unique within the project; a project supports up to 50 agents.

You can also start from a task: while the project has no agent, **Create an agent…** under **Assignee** opens **New agent** over the task and assigns the agent you create to it.

</Step>

<Step title="Choose the model and provider">

Search **Model** by name or API ID. The same model can appear once per provider; read the provider on the entry before selecting it. Selecting an entry pins that pair for future runs. Subscription entries appear only for a compatible runtime, and a model whose tool calls need OpenAI’s Responses API, such as GPT-6.1 Sol, appears only for Codex.

An older configuration may name a model without a pinned provider. The dialog reports which provider currently resolves it, or why none can serve it. Select an entry if you want to pin that choice.

</Step>

<Step title="Grant equipment and write instructions">

Under **Skills, connectors & tools**, add the bundles, services and platform operations the work needs. A new agent preselects the document skills `docx`, `pptx`, `xlsx` and `pdf` that are available to the project. They provide instructions for working with Word, PowerPoint, Excel and PDF files. Untick any the agent does not need; editing an existing agent keeps its saved equipment. Skill availability follows the project’s team access, not merely what you personally can see. A missing skill may therefore require a sharing change.

<Frame caption="A new agent's Skills menu with the document skills already switched on; each skill names who created it.">

![The New agent dialog with its Skills menu open: docx, pdf, pptx, and xlsx are switched on and marked Built-in, while brief-summary and release-notes by Alex Rivera and visual-aspect-analyzer stay off.](https://docs.tale.dev/images/platform/project-agent-document-skills.webp)

</Frame>

Read the **Writes data** label before granting a platform write tool: it authorizes real operations within that tool’s access rules. Connector broker actions available to agents are read-only; direct GitHub tooling or explicit secrets use separate access paths.

**Change task priority and agent assignment** lets a project agent prioritize existing tasks, assign them to an agent of the same project or leave them unassigned, without starting work. It is off until you grant it and is unavailable to automation agent nodes. The agent must read each task first and submit the current values with its changes; if someone changed those values meanwhile, the whole request is refused and the agent must read again. Ownership changes require an open task with no live run, pending review, or open question. A priority change alone preserves those handoffs. The tool never changes the status or reviewer, answers a human question, or starts a run. Only a live run with project-wide authority can use it; a run a Member started cannot.

**Review other agents’ task results** lets a designated reviewer decide a completed result from a different project agent. It is off until you grant it and is unavailable to automation agent nodes. Selecting an agent as reviewer does not enable this tool or start a run. The reviewer works from its own task, with current project-wide authority and the review permission still enabled. A decision records feedback and evidence; approval completes the reviewed task, while a request for changes returns it to **To do** without starting more work. Required human competences and workflow approvals remain protected. [Set up an independent reviewer](https://docs.tale.dev/platform/projects/task-automation#agent-review) explains the full flow.

**Start other agents on tasks** lets the agent put another agent of this project to work, for example a manager agent that hands out ready work and resumes an agent whose question it answered. It names a task, optionally the agent to assign it to, and a message the started run addresses first. The started run answers to whoever the manager's run answers to and names the manager as the agent that started it. An agent started this way cannot start further agents, a run a Member started cannot start any, and an agent already working another task, or a task an open task blocks, is not started. Grant this tool only to an agent whose instructions say which work it may hand out; [Task automation](https://docs.tale.dev/platform/projects/task-automation#work-an-automation-or-another-agent-starts) describes what such a run may do.

A run’s connector calls act for the member who started it, whether with **Start agent**, **Retry**, a move to **In progress** or an @mention of the agent. They use the organization’s [connector credentials](https://docs.tale.dev/platform/admin/connectors) and are recorded under that member. If that member leaves the organization or is disabled, the calls are refused: use **Cancel run** (or let the run finish), then start it again so it acts for you. When a comment restarts the run to guide it, as every runtime except Claude Code does, the calls act for the comment's author from then on.

Write **Instructions** that define responsibility, evidence and boundaries. For the launch reviewer: “Read the supplied brief. Report missing approvals and conflicting dates with the source passage. Do not mark the task complete.”

</Step>

<Step title="Review and save">

If the work needs **Secrets**, an Owner or Admin grants named organization credentials. The running agent can read their values, so use narrowly scoped, replaceable tokens. Shared names affect other agents and workflow nodes when their underlying value changes. A run a Member starts gets none of these secrets, nor the token of an equipped GitHub connection: an Editor or higher has to start work that needs them.

Select **Create agent**. Check the new row’s runtime, provider and model, then reopen it if you need to inspect the saved equipment or instructions.

</Step>

</Steps>

## Assign and start work

Open a task in the same project, choose the agent as assignee and select **Start agent**. Assignment and execution are separate actions. Provide the files and acceptance criteria before starting. You don't need project edit access for this: a Member can put an agent to work on a task they created or that is assigned to them, and an Editor or higher on any task in the project. A run a Member starts keeps to that task, without the agent's secrets and in a workspace of its own; [Agent runs a Member starts](https://docs.tale.dev/platform/projects/tasks#agent-runs-a-member-starts) lists what changes.

The agent's report appears in task comments and collected files appear as deliverables. When an admin has turned on [image generation](https://docs.tale.dev/platform/admin/governance/content-models#let-agents-generate-images), the agent can also create images for the task; they appear among the deliverables and count against the member who started the run. Successful agent work moves to **In review** for its designated human or independent agent reviewer. Mention the agent in a comment to guide a running task or continue the conversation; the chosen harness determines whether guidance enters the existing process or starts a continuation.

[Task automation](https://docs.tale.dev/platform/projects/task-automation) explains progress, stopping and review. The ordinary Chat assistant remains separate, even when a chat has project context.

## The standard agent {#standard-agent}

A project without agents of its own can still take on agent work. Unless an admin has turned it off under [Governance > Models](https://docs.tale.dev/platform/admin/governance/content-models#standard-agent), **Assignee** offers **Standard agent** there, to everyone who can assign the task, Members included. The first time someone chooses it, Tale sets the agent up in the project and assigns it the task. You then start it like any other agent, or mention it in a comment. When it can't start for you, the comment box says so, and your comment is saved as a plain mention.

<Frame caption="The Agents tab of a project whose tasks go to the standard agent.">

![The Agents tab of the Customer onboarding portal project with one row, Standard agent, marked Standard, reading Claude Code · OpenRouter · anthropic/claude-haiku-4.5 · 4 equipped and Set up by Tale for this project. Its agent type, model and instructions follow the organization's settings under Governance. The row has a delete button and no edit button.](https://docs.tale.dev/images/platform/project-agents-standard.webp)

</Frame>

The **Agents** tab lists it with the **Standard** badge. Nobody edits it: its agent type, model and instructions follow the organization's settings, read again whenever a run starts, and its equipment is whichever of the document skills `docx`, `pptx`, `xlsx` and `pdf` the project can use when a run starts, so a skill an admin turns off drops out instead of stopping the agent. On **Automatic**, each run uses a model that the person who starts it may use, so it can run on different models for different people.

To give the project an agent of its own, select **New agent**. From then on, the project isn't offered the standard agent any more; the one already set up stays assignable until you delete it. Deleting it keeps the history of its tasks, and while the project has no agents, the next task given to the standard agent sets it up again.

## Update or remove an agent

Use the agent’s row actions to edit or delete it. The standard agent has only **Delete agent**. Changes apply to later runs; an active run keeps its starting configuration. Deleting the agent clears task assignment references while preserving task history. It also deletes the agent's [sandbox workspaces](https://docs.tale.dev/platform/admin/sandboxes#explain-why-a-workspace-disappeared) and their files, including each Member's. Review current work and preserve outputs you still need before removing the worker it belongs to.

If creation fails, use the displayed reason to distinguish a duplicate name, missing project access, an unavailable provider/model or a skill visibility issue. A run that fails for good says at the top of its task what went wrong and who can fix it; [When the agent can't finish](https://docs.tale.dev/platform/projects/task-automation#when-the-agent-cant-finish) lists the cases. Changing instructions does not fix those dependencies.

# Delegate a task to an agent
Source: https://docs.tale.dev/platform/projects/task-automation

A project agent works on a task and returns a result for review. Choose its assignment, start the work, and keep feedback on the task so the agent and reviewer have the same context. You need to be able to change the task: an Editor or higher can on every task in the project, and a Member on the tasks they created or that are assigned to them. The organization also needs a working provider, compatible harness, and available sandbox capacity.

<Frame caption="Agent work uses the same board as human work: start at In progress and review the result at In review.">

![The project task board shows work distributed across Backlog, To do, In progress, In review, Done, and Cancelled.](https://docs.tale.dev/images/platform/projects-task-board.webp)

</Frame>

## Prepare and start the task

1. Create a [task](https://docs.tale.dev/platform/projects/tasks) with the desired result, completion criteria, and input files.
2. Choose a [project agent](https://docs.tale.dev/platform/projects/project-agents) under **Assignee**.
3. If you can edit the project, choose a person or independent agent under **Reviewer**, or keep **Project default**. The initial project default routes reviews to an eligible task creator or project creator. [Choose an owner and a reviewer](https://docs.tale.dev/platform/projects/tasks#choose-an-owner-and-a-reviewer) explains the default, permissions, and pending handoffs.
4. Click **Start agent**, or move the task to **In progress**. When you assign the agent while creating the task, **Create and start agent** in **Create task** does this in the same step.

Assignment alone does not start execution. A task may remain assigned in **Backlog** while the team decides whether to proceed; until someone starts it, whoever can start the agent sees **Start agent** on the task with the note **The agent waits until you start it.** When started, the agent uses the task description, comments, and input files in its sandbox. Its run card shows whether it is queued or working. A run a Member starts keeps to its task and goes without the agent's secrets; [Agent runs a Member starts](https://docs.tale.dev/platform/projects/tasks#agent-runs-a-member-starts) lists what changes.

Agents are instructed to keep task updates, reports, related tasks and questions in the language of the task's title and description. If those do not establish a language, they use the organization's default agent language. An identifier, quarter or generated title template does not choose a language. Changing your interface language does not change the task's language; an explicit request to the agent can.

Workflow progress comments can carry translations for each supported interface language. The same saved comment then follows the reader's language selection. Comments without translations retain their original text.

## Read and accept the result

The agent posts its report as a task comment and adds produced files as deliverables. It then moves the task to **In review**. A human reviewer receives a notification and, when email delivery is configured, an email. An agent reviewer reads the pending review from its own task; routing a review to it does not start it automatically.

Tale lists delivered or skipped files in a separate system comment that follows your interface language. A missing or shortened report is noted there too, so the report keeps the task's language.

For a human review, read the report, open the deliverables, and compare them with the completion criteria. Move the task to **Done** only when you accept the work. Tale records the decision; the implementation agent cannot approve its own result.

For a review assigned to a person, **Reviewer** routes the notification and review queue without reserving the decision to that person. Other people who can change the task may accept it, subject to the organization's independent-review and competence rules. A pending review assigned to an agent must be explicitly transferred to an eligible person before a human can approve it. Changing the reviewer does not reassign the implementation work; [Choose an owner and a reviewer](https://docs.tale.dev/platform/projects/tasks#choose-an-owner-and-a-reviewer) has the details.

Changing **Reviewer** while the task waits in **In review** transfers the recorded request. The previous human reviewer's notification clears; a new human reviewer receives the request, while an agent-owned review waits for that agent. **Project default** uses the current project choice. A concurrent change to the review or result refuses the handoff, so read the refreshed state before trying again.

## Set up an independent reviewer {#agent-review}

1. Create a separate [project agent](https://docs.tale.dev/platform/projects/project-agents) for review. Under **Skills, connectors & tools**, grant **Find tasks**, **Read a task**, and **Review other agents’ task results**. The review grant is off initially and is not available to automation agent nodes.
2. Select that agent as the project's [default reviewer](https://docs.tale.dev/platform/projects/tasks#review-default), or explicitly under **Reviewer** on a task. For a review already waiting, use the task's reviewer control to transfer it; changing the project default alone does not.
3. Give the reviewer its own task and instructions to inspect only reviews assigned to it. Start that task directly or through an existing [schedule](https://docs.tale.dev/platform/automations/triggers#start-a-project-agent-on-a-schedule). Do not start a new implementation run on the task being judged.
4. Require the reviewer to read the current review, examine the actual report and deliverables, and record concrete check results and feedback. It must decide against the same completed run and evidence it read; a changed result requires another read and review.

For a captured agent review, `task_get.reviewFiles` lists attachments and outputs in pages of 50. Continue with `reviewFiles.page.continueCursor` as `reviewFileCursor`. The reviewer can use `task_review` with `operation: "stage_file"`, the current `expected: {approvalId, runId, evidenceRevision}`, and one listed `fileId` to copy an available file of at most 20 MiB into its workspace. It must then open and inspect the returned path: staging alone is not evidence that the contents were reviewed.

An `unavailableReason` explains why a file cannot be staged, including unsupported storage, missing or ambiguous metadata, a larger file, or a protected document binding. Document access rules still apply. A changed source or reviewer requires a fresh read. If authority changes during transfer, the operation refuses success; bytes already authorized for that workspace can remain there, but they do not authorize an outdated verdict.

Approval moves the reviewed task to **Done**. A request for changes records the feedback and moves it to **To do**, preserving its assignment. Neither verdict starts another run. Even an agent mention inside review feedback does not dispatch work: an authorized person, manager, or schedule must start the next attempt separately. The activity identifies the reviewer agent and its decision.

For one recorded request for changes, the manager calls `task_start_agent` with `taskId` and `resumeFrom: {kind: "review_repair", approvalId, runId}`. These IDs name the rejected review and the implementation it judged. The server selects that implementation agent and includes the reviewer’s saved feedback and `feedbackCommentId` in the repair brief. Any additional `feedback` must fit with that text and its identity prefix within the existing limit of 10,000 UTF-16 code units.

The repair starts only while the task is still **To do**, assigned to that same agent, with the same latest completed implementation and no newer review or intervening status, assignment or archive decision. Changing a value and then changing it back still invalidates the old intent. A `stale_repair` answer changes nothing: the manager reads the current task and retires the outdated intent. It never retries without the tagged guard. The repair uses the ordinary lifecycle and submits a new review when it finishes; `moveToInProgress: false` is refused.

If the response is lost, the same manager agent can repeat the guarded call from a currently authorized live run, including a later occurrence. `replayed: true` returns the original `runId` and `repairReceipt`, preserving the first issuing run and creating no further work. It reports a previous admission, not that the run is still active. Current delegation permission and project authority are checked again on every call. The existing single-live-run, busy-agent and three-automated-starts-per-task-per-hour limits still apply to new admissions. Repeated unchanged failures need a separate investigation task rather than an unbounded retry instruction.

To reconcile a lost verdict response across reviewer occurrences, read `task_get.reviewDecision`. It contains the latest validated native decision receipt, or `null` behind a newer pending, human or workflow review or when the receipt is unavailable. Compare its approval and run IDs with the recorded intent, and read the task’s current state separately. A historical receipt does not describe the current column, and `null` does not prove that a verdict failed to commit. An immediate identical `task_review` replay still requires the same live issuer.

The reviewer must be different from the agent that actually produced the result, for either verdict. It needs a live run with project-wide authority and the review grant still enabled; a run started by a Member cannot decide reviews. An independent-human-review policy or required human competence records routes new reviews to the human chain; a captured agent review requires explicit transfer to an eligible person. Workflow approvals and questions addressed to a person keep their own human gates. Read `pendingReview.agentReviewBlockedReason` for a current source, grant, identity or policy problem before attempting a verdict. If GitHub work is involved, the reviewer must check the referenced commit and checks itself: Tale records its evidence but does not independently verify GitHub's current state or merge a pull request as part of the verdict.

## Ask for changes

Add a task comment that names what needs to change and **@mention the assigned agent**. The mention is an instruction: an active agent can receive it during its run, and an idle agent starts a rework run that continues the previous conversation. The result returns to **In review**.

If you started a run, your mentions keep guiding it even after the task has passed to the agent, for example because your mention handed it a task that was assigned to you. When the agent's runtime restarts to take in a comment, which every runtime except Claude Code does, the rest of the run belongs to the comment's author: it counts against their limits, and its connector calls act for them.

A plain comment keeps a note without starting that agent action. The mention picker indicates when an agent cannot respond, for example because task automation is disabled or paused, or because you can comment on the task but not change it.

For an automation-owned task, mention the owning automation to request another run. Mentioning a different automation does not transfer ownership or start it. See [Automations](https://docs.tale.dev/platform/automations/concepts) for workflows that coordinate several steps.

A task can have only one queued, running, or waiting run at a time, whichever automation started it. Repeating a start request while one is active returns the existing run, even when it names another automation. Once it finishes, another start can create a new run and repeat the work. Check the current run and its effects before requesting another attempt.

## Let a manager agent keep the queue moving

A manager agent is a project agent whose instructions are to read the whole board, hand out ready work and answer the routine questions other agents leave, so that people see only what needs them. It reads with **Find tasks** and **Read a task**; neither tool changes anything.

### Read the whole queue in passes

**Find tasks** answers at most 50 tasks at a time. While a page says `isDone: false`, its `continueCursor`, passed back as `cursor` with the same arguments, returns the next page; the last page says `isDone: true`. A cursor that comes back with other filters, another order or from another project's run is refused, and so is a damaged one: it is never read as the first page. A total appears only when one page holds every matching task.

To walk a whole queue, use `order: "created"`. Tasks come oldest first and keep their place, so a pass lists each task at most once, as it stands when its page is read. The default order groups tasks by status and keeps each column's order within it, so a task that moves while the manager pages can be missed or listed twice.

Each listed task carries `pendingReview: null` or the captured `approvalId`, source `runId`, and typed `reviewer`. A reviewer finds its own queue with `status: "in_review"` and `reviewerAgentId` set to its agent ID; this matches the recorded review owner, not the implementation assignee or today’s project default. Keep that filter on every cursor request. The manager also scans all `in_review` tasks to find reviews whose agent has been deleted, then uses `task_get.pendingReview.agentReviewBlockedReason` to identify the recovery needed. Agent reviews stay in this task queue; a person’s Home review queue is for human requests.

A pass can outlast one run. Before its run ends, the manager saves a checkpoint comment on its own task: the pass, its order and filters, the next `continueCursor` and the last task it examined. Its next run finds that checkpoint with **Read a task** and continues from it. When a pass ends, or its cursor is refused, the next pass starts at the first page. A read that fails is not an empty queue: the manager reports it and stops.

### Tell running, finished and waiting work apart

**Read a task** names subtasks, blockers and comments by their IDs and pages back through older comments with `commentCursor`. It also lists the task's project-agent runs, newest first, each with the first 500 characters of the message its start carried, along with the task's automation run and any pending review:

- A run with `live: true` is queued or running, and nothing else starts on the task until it ends.
- A run that has settled, failed or been cancelled is finished; `settledAt` says when.
- `retryPending: true` means the newest failed run still has an armed automatic retry with budget remaining. Leave that retry to Tale. `false` means no retry is pending for that run; a missing field on an older platform means unknown. It supplies no provider reset time or permission to restart: first read the current task, assignee, runs and review, then honor any provider wait and admission `retryAfter`.
- A `workflowRun` waiting for an `ask` or an `approval` waits on a person. A `pendingReview` records its human or agent reviewer; a manager leaves the decision to that reviewer unless it is itself the assigned independent reviewer with the review grant.

The answer leaves out transcripts, error texts and results, and anything from another project.

### Answer a routine question

A routine question is one the manager can answer from what the project already records. Write the same protocol into the instructions of the working agents and of the manager:

1. The working agent posts the question as a task comment with a stable question key, its evidence and the question. It names the comment's ID and its own run ID in its result (**Read a task** on its task shows that run as the live one) and finishes the run instead of waiting inside it. Mentioning the manager in that comment starts nothing: a comment by an agent never starts an agent.
2. On its next pass, the manager answers only while the task still waits on that question: the run that asked is the task's newest run and has finished, nothing is live on the task, and the task waits in review of that run (`pendingReview.runId`). It keeps that run's ID and `pendingReview.approvalId` from this read. If someone has since moved the task on, by accepting or cancelling it or asking for changes, the question is no longer the manager's to answer, and it reports the question instead.
3. It posts its answer as a comment that names the question's comment ID; the answer stays on the task whatever happens next. It then resumes the agent with **Start other agents on tasks**, passing `resumeFrom: {runId, approvalId}` with the two IDs it kept, and a message that opens with the question's key, the run's ID and the answer's comment ID: a later **Read a task** shows only the first 500 characters of a start's message. The start checks, as it happens, that this is still the task's open question. Only then does it withdraw the pending review, without approving it, and resume the agent.
4. If the start answers `stale_question`, the question was overtaken between the manager's read and the start: a decision was made, a newer run or review exists, or the assignee changed. Nothing was changed. The manager reads the task again and drops the outdated question. It does not start again, and never without `resumeFrom`.
5. If the start's response is lost, the manager reads the task again before trying anything else: a newer run whose message opens with that question's key, run ID and answer comment ID means the start went through. If the same start is sent again, it answers `stale_question` and changes nothing.

A question from a standing task, one a schedule starts with `moveToInProgress: false`, waits for no review. The manager only posts its answer there, and the run at the schedule's next occurrence reads it. Neither the manager nor anyone else starts the task early to deliver the answer.

Answering an automation's question and deciding a workflow approval stay with people. A manager may decide a project-agent task review only through the independent-review flow above, when that review is assigned to it; reading or resuming a task does not approve it.

## Handle waiting and failed runs

| State or symptom | What to do |
| --- | --- |
| Waiting for a sandbox slot | Available capacity may be exhausted for the organization or shared infrastructure. Wait for a slot, or ask an admin to inspect [Sandboxes](https://docs.tale.dev/platform/admin/sandboxes). |
| Automatic retry is shown | Tale is retrying a recoverable failure. Read the attempt count and avoid starting another run. |
| **The agent couldn't finish this task** | No automatic retry follows. The notice says what went wrong and who can fix it, and **Details** beside the run shows what the run itself reported; [When the agent can't finish](https://docs.tale.dev/platform/projects/task-automation#when-the-agent-cant-finish) lists the cases. Resolve the cause, then use **Retry** to continue the conversation. |
| Reassignment is refused | Cancel the live run before choosing another assignee. |
| Agents or automations keep restarting one task | A task takes at most three starts of its agent by automations and other agents in any hour, ordinary automatic retries included; the cooldown exception below applies. The next start is refused, a retry past the limit is not started, and the timeline says **Run refused: agent runs are paused on this task**. Starts by people, and their retries, are never counted. Automation runs have no such cap: between two automations that keep mentioning each other, the one-engine rule is what stops a loop. Cancel the live run, then read the timeline before letting either start again. |
| **Run refused: agent is working on another task** | An automatic retry waited two hours for its agent, which is still working on another task. Nothing waits behind the refusal: start the task again once the agent is free, or leave it to the manager agent or automation that hands out the work. |
| The task cannot close | Finish its open subtasks first. |

Recoverable failures get up to three automatic retries, which start right away except in the cases below. A run that makes sustained progress for at least fifteen minutes receives a fresh retry allowance. This helps long work recover from interruptions; it does not prove the resulting work is correct.

An automatic retry continues the work of the person who started the run, so it starts only where that person could start the run now: the project must still be active, and they must still be allowed to change the task. If an admin archives the project, or that person leaves the organization or loses the right to change the task, no further retry starts and the run stays failed. The same applies to a mention that reaches the agent only after its run has ended. Once the project is restored, anyone who can change the task can use **Retry**.

An agent served by a subscription broker can lose its token while it works, when the broker refreshes the account. The retry then continues the conversation on a fresh token, and the attempt count does not advance: the retry shows the same count as the run it replaces, or **Resumed after a token refresh** when that run showed none or had worked for at least fifteen minutes, which earned it a fresh retry allowance. After two such interruptions in a row, a further one counts like any other failure.

A run can also fail to start because every account of its subscription broker is cooling down after a rate limit. Its retry is queued at once but starts only when the first account is available again, at most a minute later. The wait uses no attempt when the refused run immediately follows the same agent’s HTTP 429 failure. That single wait also adds no start to the task’s hourly automated-start count: the rate-limit failure already counted. A consecutive cooldown refusal, or one following any other failure, counts toward both limits.

### When the agent can't finish

When a run fails and nothing retries it, because its automatic retries are used up or a retry can't change the cause, the task says so at the top: **The agent couldn't finish this task**, with what went wrong and who can fix it. **Retry** there starts the agent again for whoever can change the task.

| The notice says | Who acts |
| --- | --- |
| A usage limit stopped the run | An Admin raises the limit; then start the agent again. |
| Something the agent needs is missing: its model, one of its skills, or the agent itself | An Editor or Admin fixes the agent on the project's **Agents** tab. |
| An attachment on this task is no longer in storage | Whoever can change the task removes the attachment or uploads it again; **Details** beside the run names the file. Then start the agent again. |
| The run reached its time limit | Start the agent again, or split the task into smaller ones. |
| The run waited too long for a free sandbox | Start the agent again when fewer agents are busy. |
| The AI model failed, or the run couldn't start or was interrupted | Start the agent again. If it fails again, show an Admin what the run reported under **Details**. |

Tale also tells the person who started the run and everyone watching the task: with the notification **Agent run failed** and, when the organization has a connected mailbox, by email. Only people who can still open the project are told. Starting a new run on the task marks the unread notification as read. Switch these notices off with **Agent escalations** under **Settings > Notifications**.

## Work an automation or another agent starts

A project agent can also be put to work without anyone pressing **Start agent**: by a [scheduled automation](https://docs.tale.dev/platform/automations/triggers#start-a-project-agent-on-a-schedule), or by another agent of the project that holds the **Start other agents on tasks** tool, such as a manager agent that hands out ready work and answers questions. The timeline lists such a run as **automation**, with a link to the automation run for Owners, Admins, and Developers, or as **delegated**, started by the agent that asked. The agent is told who started it, and a message that automation or agent passed reads as theirs, never as a person's review: where it contradicts the description or a person's comment, those win.

The run answers to whoever the requesting run answers to: the person who started it, or nobody for a schedule's chain, whose spend counts as automation spend. That person, or the schedule, has to be able to act in the project when the run starts; a lost Editor role, a paused schedule, or an automation removed from the project stops the next start. An agent another agent started cannot start further agents, and a run a Member started cannot start any. Such a start also checks what a person might forget: a task an open task blocks does not start, and an agent already working another task is not started twice. An automatic retry of such a run keeps to that rule: while its agent works on another task in the same workspace, the retry waits, checks again every five minutes and starts once the agent is free, without using an attempt. Each check reads the task afresh, so a move out of **In progress**, a reassignment, an archived task or project, or a lost role ends the wait. If the agent is still busy two hours after the failure, the retry does not start, and the timeline says **Run refused: agent is working on another task**.

A delegated run parks its result at **In review** for its recorded reviewer. Resuming a task that waits there withdraws its pending review without approving it. A start that leaves the card where it is (`moveToInProgress: false`) is refused under a card waiting for review, or a **Done** or **Cancelled** one, so earlier work is never presented for judgment while new work runs under it. A manager that answers an agent's question resumes it naming the run that asked and the review it waits at. The resumption happens only while that is still the task's open question. If a decision was made in the meantime (Done, Cancelled or another move), a newer run or review exists, or the assignee changed, the agent answers `stale_question` and nothing is assigned, withdrawn, moved or started. When your organization requires an independent human reviewer, the person the run answers to cannot accept its result.

## Cancel or pause work

Use **Cancel run** to stop the active agent. Anyone who can change the task can cancel its run, and so can the person who started the run, even after the task has passed to the agent. Moving a running agent-owned task out of **In progress** can also cancel the run; read the confirmation before proceeding. A task cannot have two active agent runs at once.

For a task an automation owns, the move stops the run and puts the task where you moved it in one step. If that move is refused, for example because you moved a parent task to **Done** while its subtasks are still open, the run keeps working and the task stays in **In progress**. **Cancel run** in the automation's panel on the task moves it to **Cancelled**, so the same open subtasks refuse it; to stop the run and keep the task open, move it to **To do** instead.

An admin can disable task automation for the organization. That blocks new starts while existing work finishes. Organization limits and budget policies still apply to each run; see [Policies and limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits).

## Choose the right assignee

Assign a person when the task needs human judgment or work outside an agent’s permitted access. Assign a project agent for a bounded job using its configured files and tools. Use an automation when the work follows a defined process with stages, triggers, or connector approvals. A Member can choose only an automation built for tasks, one of those listed under **Automations** in **Assignee**.

For a first run, follow [Build your first agent](https://docs.tale.dev/tutorials/editor/first-agent-end-to-end). Keep the task small enough that you can inspect its result yourself.

# Manage tasks on a project board
Source: https://docs.tale.dev/platform/projects/tasks

A task keeps a piece of work together: its purpose, owner, status, files, and the conversation about the result. Use the project board for work a person will do as well as work you delegate to an agent. Every member who can open the project can create tasks in it; [who can change a task](https://docs.tale.dev/platform/projects/tasks#who-can-create-and-change-tasks) depends on your role and on whether the task is yours. The project must be active: an archived project is read-only until an administrator restores it.

<Frame caption="The board groups the same tasks by status. Switch to List when you prefer rows.">

![The Website relaunch project’s task board shows cards in Backlog, To do, In progress, In review, Done, and Cancelled.](https://docs.tale.dev/images/platform/projects-task-board.webp)

</Frame>

## Create a task with a clear result

1. Open the project’s **Tasks** tab and click **Create task**.
2. Write a **Title** that names the result, such as “Review the launch brief”.
3. Use **Description** to explain what is needed and how the result will be checked. Add supporting files under **Attachments** when the work depends on them.
4. Choose **Status**, **Priority**, and an **Assignee** as needed. New tasks default to **To do**; use **Backlog** for a proposal the team has not committed to.
5. Click **Create task**. Open the new card to continue adding details. When an agent is the **Assignee**, **Create and start agent** creates the task and starts the agent in one step.

A title can have up to 200 characters and a description up to 20,000; most emoji count as 2. A longer description, pasted in or left on a task by an earlier import, is not cut: the field names the limit and counts the length, and **Create task** or **Save** stays unavailable until you shorten it.

Tale gives the task an identifier built from the project key, such as `WEB-1`. Use that identifier when referring to the work so similarly named tasks remain distinguishable.

A conversation can start a task too: **Create task** in the chat's header opens the same dialog with your request, the chat's files, and a link back to it, and the chat then follows the task above its message box. See [Turn a chat into a task](https://docs.tale.dev/platform/chat/basics#create-task-from-chat).

An automation built for tasks can also offer a template in **Create task**: its name then appears beside **Blank task** above the form. Choose it, enter the name the automation asks for, such as a quarter, and click **Create task**; the automation becomes the task's assignee. If a task already exists for that name, Tale opens it instead of creating a second one and says **A task for this subject already exists.** A Member can read and comment on it there, but change it only if it's theirs. Templates that set up folders or settings files in the project are offered to Editors and higher roles only.

<Tip>

A useful description states the input, the requested output, and a check for completion. For example: “Compare the review date in the attached brief with the meeting notes. Comment with any mismatch and cite both files.”

</Tip>

<Frame caption="The task details keep the description, attachments, subtasks, and comments beside ownership and status.">

![The task Sign off the launch checklist shows its description area, attachments, subtasks, comments, status, assignee, reviewer, dates, repeat, labels, and dependencies.](https://docs.tale.dev/images/platform/project-task-detail.webp)

</Frame>

## Who can create and change tasks

Every member who can open a project can create tasks in it. Editors and higher roles can change every task in the project. On tasks they created or that are assigned to them, a Member can:

- Edit the title, description, attachments, subtasks, dates, priority, labels, and repeat.
- Assign the task to themselves, to another member of the project, to one of its agents, or to an automation built for tasks.
- Start, guide, or stop the agent, including with an @mention in a comment.
- Move the status, including accepting a result by moving the task to **Done**.
- Archive the task, or restore it.

The same goes for the subtasks under such a task, whoever added them, for example an agent that split up the work, so they never keep the Member from closing their task. Changing **Reviewer** requires project edit access, including on a task you created or own.

On other people's tasks, a Member reads and comments; mentioning an agent there leaves an ordinary mention that starts nothing. Everyone can edit and delete their own comments on any task they can read, and Owners and Admins can also delete other people's comments.

An archived task can be read but not changed. Until someone restores it, nobody can comment on it, edit or delete its comments, or change its dependencies; a task it blocks can still remove it under **Blocked by**. An agent run that was already working on the task still posts its result there.

Handing a task that was assigned to you to someone else, a person or an agent, also hands over the right to change it, unless you created the task. A run you started still answers to you, though: when your @mention hands the task to an agent, you can guide that run with further mentions and stop it with **Cancel run** until it ends.

A dependency belongs to the task it blocks, so a Member records dependencies for their own tasks only: under **Blocked by** on a task of theirs, or under **Blocks** on any task they can open, picking one of their tasks as the blocked one. The project's settings, agents, files, and label catalog stay with Editors and higher roles; a Member picks from the labels the project already has. Only Owners and Admins can delete a task; everyone else who can change it archives it instead.

Automations follow a narrower rule, because an automation acts as itself, with the organization's connector credentials, not as the person who starts it. A Member can hand a task only to an automation built for tasks, the ones listed under **Automations** in **Assignee**, or to the automation that already owns the task, and those are also the only ones they can start or ask for changes. Every other automation stays with Editors and higher roles.

### Agent runs a Member starts

A run started by someone who can't edit the project, such as a Member, keeps to its task:

- Its platform tools change only that task and the subtasks under it: the agent creates new tasks only as subtasks of that task, uses only labels the project already has, and can't sync items from other systems into the project.
- It can't save documents to the project. The files it produces still arrive on the task under **Deliverables**.
- The run gets neither the agent's **Secrets** nor the token of an equipped GitHub connection. The agent learns which credentials were held back and is asked to say so in its report when the work needs them; an Editor or higher then has to start it. Connectors equipped on the agent keep working and act for the person who started the run.
- It works in a workspace of its own, kept for that person's runs with this agent: files from runs that Editors started aren't there, and what this run leaves behind never reaches those runs. The same person's later runs with the agent find it again, until Tale deletes it: when the person leaves the organization or the agent is deleted, or once no run has used it for the number of days the organization sets under [**Days without use**](https://docs.tale.dev/platform/admin/sandboxes#delete-unused-workspaces-automatically).

The run can still read the project's tasks and knowledge, and it keeps these limits when an Editor guides it later. A run that an Editor or higher starts has the agent's full equipment, on any task. A Member's comment can change that: when the agent's runtime restarts to take in the comment, as [every runtime except Claude Code](https://docs.tale.dev/platform/agents/harnesses) does, the rest of the run counts as the Member's, with the same limits on its tools and credentials.

## Choose an owner and a reviewer

**Assignee** identifies who does the work: a person, a project agent, or an automation available to the project. **Reviewer** chooses a person, a project agent, or the **Project default** for checking the result. Changing that choice requires project edit access. A human reviewer also needs project edit access; an agent reviewer belongs to this project and must be different from the agent that produced the result.

Assigning an agent and starting its run are separate choices. After assigning it, click **Start agent**, or move the task to **In progress**. Read [Task automation](https://docs.tale.dev/platform/projects/task-automation) before starting work that can use connected services or produce files.

If the project has no agent of its own, **Assignee** offers **Standard agent**, the organization's agent for such projects. Choosing it sets the agent up in the project and assigns it the task; [The standard agent](https://docs.tale.dev/platform/projects/project-agents#standard-agent) explains how it works. Editors and higher roles can choose **Create an agent…** instead: **New agent** opens over the task, and the agent you create is assigned to it. When the standard agent can't run for them, for example because an admin has turned it off, Members are told to ask an Editor or Admin to add an agent on the project's **Agents** tab.

<Frame caption="Assignee in a project without agents of its own offers the organization's standard agent.">

![The Assignee list scrolled to its Agents section: Standard agent, described as The organization's agent for projects without their own, then Create an agent…, above the footer Until this project has agents of its own, the organization's standard agent takes its tasks.](https://docs.tale.dev/images/platform/project-task-standard-agent.webp)

</Frame>

For a review assigned to a person, the named reviewer receives the request without being the only person allowed to accept it. Anyone else who can change the task can also accept the result: an Editor or higher, or the Member the task belongs to. When your organization requires an independent reviewer, the person who started the agent run under review cannot accept its result; when no agent run produced the result, the task's creator cannot. Required human competences still apply. A review assigned to an agent needs that agent's decision, or an explicit transfer to an eligible person before a human can approve it.

If the organization’s review policy cannot be read or is invalid, human approval is refused, including after a review is transferred from an agent to a person. An organization administrator must restore valid policy configuration before approval can succeed. Asking for changes or withdrawing a review keeps its existing behavior.

### Set a project review default {#review-default}

On the project's **General** tab, open **Task reviews** and choose **Default reviewer**, then save the project changes. The initial **Person** choice uses the task creator, then the project creator, if they can edit the project. Choose an independent project agent to route new reviews to it. This setting neither starts the agent nor grants its review permission; [Set up an independent reviewer](https://docs.tale.dev/platform/projects/task-automation#agent-review) covers those steps.

Tasks with **Project default** follow this choice when a new review starts. A task with an explicitly named person or agent keeps that choice. Reviews already waiting retain their recorded reviewer even if the project default changes. If someone changes the default while you are editing, discard the stale draft and choose again.

An agent default applies only when a native project-agent run produced the result and the organization does not require human independence or competence records. A person or automation submitting work without such a run uses the human review chain. Saving an agent choice requires its task review permission; a task cannot select its own implementation agent. A captured review never changes owner automatically after a grant, assignment or policy changes.

### Transfer a pending review {#transfer-review}

Open the task and read **Current review** below **Reviewer**: it names who owns the waiting review, which can differ from the current project default. Choosing another reviewer also transfers that pending review, without changing the assignee or starting a run. Choose **Project default** to hand it to the project's current default. If the reviewer or result changed since the task was read, the transfer is refused; check the refreshed review before choosing again.

An agent can review only a completed project-agent result from a different implementation agent. Assigning the task to someone else keeps the original result's producer but blocks the pending agent decision. To keep the new assignment and review that result, explicitly transfer the review to an eligible person; the organization's review policy still applies.

A live run or open question can prevent a transfer to an agent. For work without a supported completed agent run, or a review requiring human independence or competence records, choose an eligible person. If an agent is unavailable or lacks the review permission, the task shows that reason; it does not silently send the review to you.

The current review also explains self-review, changed implementation ownership, and unavailable policy. Restore the indicated condition or transfer it explicitly; settlement still records the result. A repeated task retains an explicit agent reviewer even if that agent was deleted or lost its grant, so repair that choice instead of silently inheriting a different reviewer.

## Use statuses to communicate progress

Change **Status** in the task details, or drag a card to another column on **Board**. The status picker is the keyboard-accessible alternative to dragging.

| Status | Meaning |
| --- | --- |
| **Backlog** | Proposed work that has not been committed to. |
| **To do** | Work ready to be picked up. |
| **In progress** | Work is underway. Moving an agent-owned task here starts its run. |
| **In review** | A result is waiting for its human or agent reviewer. |
| **Done** | The completed work has been accepted. |
| **Cancelled** | The work is no longer going ahead. |

For an agent-owned task, changing status can start or cancel execution. Read the action hint before moving it. An agent reports back at **In review**; it cannot mark its own work **Done**.

## Keep decisions with the work

Open the task to add a description, attachments, dates, labels, subtasks, or comments. Use comments for questions, decisions, and feedback that future reviewers need to understand.

Typing `@` in a comment opens the mention picker. A mention of an assigned agent is an instruction: it can steer a running agent or start another run when the agent is idle. A plain comment records the discussion without requesting that agent action.

Mentions in the task description work the same way when you save the task: the people you name are notified, and a named agent is steered or starts a run as described above. A run it starts moves the task to **In progress**, whichever column you created it in. When you edit the description later, only the mentions you add take effect. Rewording the text around an existing mention notifies no one again. The agent reads the description as it is when its run starts, so an edit you make while the run is still waiting is the version it works from.

Use **Subtasks** to split work that has separately checkable results. A subtask names its parent at the top of its details (**Part of …**); click it to go back up. While any of its subtasks is still open, a parent task cannot move to **Done** or **Cancelled**; every other status stays available, **To do** included. **Dependencies** shows which tasks block this task and which it blocks; circular dependencies are refused.

When you change a field, the task's **Activity** shows its value before and after. A field you clear shows what is left, such as **No due date** or **Unassigned**, rather than its old value alone. Titles, descriptions, labels, and file names appear exactly as they were written, even when the text is a status name such as `done`. Statuses, priorities, dates, and the words for an empty field appear in your language.

## Repeat a task

Give a task a repeat when the same work comes back on a schedule, such as a weekly status report. Each time the task closes, the next one appears in **To do**, due on the next day the repeat names.

Click **Repeat** below **Due date**, in the task's details or in **Create task**, and choose how the task repeats. A choice is saved as soon as you click it:

- **Never**
- **Daily**
- **Every weekday**, Monday to Friday
- **Weekly on …**, **Monthly on day …**, or **Yearly on …**, which take their day from the due date; a task without one uses its start date if that is still ahead, or else today

<Frame caption="Choose a repeat in the task's details; the preview lists its next due dates.">

![The Repeat menu of the task Sign off the launch checklist lists Never, Daily, Every weekday, weekly, monthly and yearly options named after the due date, with the weekly one checked, and Custom, above the next due dates and the option to create the next task on the due date.](https://docs.tale.dev/images/platform/project-task-repeat.webp)

</Frame>

**Next due dates** shows when the next three tasks will be due. A task without a due date gets one when you choose a repeat: the first matching day from today, or from its start date when that is later. A monthly repeat on the 31st falls on the last day of shorter months. If you clear the due date of a task that already repeats, the repeat stays: the next task then comes when this one closes, due on the first matching day after that, and **Repeat** says so when you open it. Any change to the repeat gives the task a due date again.

If the dates exceed the supported calendar range, the preview explains this. Choose an earlier start or due date before setting the repeat.

### Set a custom repeat

For any other schedule, choose **Custom** in the same list. Pick **Day**, **Week**, **Month**, or **Year**, set how often the task comes back, and choose the weekdays, the day of the month, or the date, such as every 2 weeks on Tuesday and Thursday. **Next due dates** follows each change. Click **Save** to keep the repeat. **Cancel**, **Escape**, or a click outside the list discards your changes; the back arrow returns to the list and keeps them.

### Create the next task on the due date

Normally, the next task appears when you move this one to **Done** or **Cancelled**. When the work has to come back on time even if the last round isn't finished, open **Repeat** on a repeating task, select **Create the next task on the due date** below the dates, and click **Save**. The next task then appears at the start of the due date, midnight in the time zone of whoever set up the repeat, even while this task is still open. If the task is already due, the next one appears within a few minutes, and closing the task before its due date creates the next one at once. **System** appears as its creator in the task's activity. **Repeat** shows a calendar icon, and the tooltip of the repeat icon on **Board** and **List** ends in **next task on the due date**.

Open tasks no longer hold such a series back, so they can pile up when nobody closes them. A series never has more than 10 open tasks: the next one waits until someone closes one of them. Changing the repeat, or choosing **Never** and then a repeat again, still counts the tasks that remain open in the series.

### What the next task brings back

The next task has its own identifier and starts in **To do**. It keeps the title, description, priority, labels, attachments, assignee, reviewer, the people watching the task, and the repeat. Its subtasks come back with it, each in **To do** with its dates moved by the same step, along with the dependencies between them. Comments, dependencies on other tasks, archived subtasks, and the files an agent produced stay with the earlier task. People carry over only while they still have access: the assignee while they can still be assigned, the reviewer while they can still edit the project, and watchers while they can still see it. Whoever stopped watching the task doesn't watch the next one either, even if they created it.

The next task is due on the first day the repeat names after the earlier task's due date, and a start date keeps the same number of days before it. That due date is never in the past: close a task late, and the next one is due today or on the next matching day, so missed dates don't pile up as overdue tasks.

Under **Repeat**, the earlier task links to the next one, such as **Next task: WEB-13**; reopening the earlier task and closing it again creates no second one. On **Board** and **List**, a repeat icon marks the task that currently carries the series, and its tooltip names the repeat.

### Stop a series

When you close a repeating task, the message **Next task created** tells you when the next one is due and offers **Stop repeating**. The same button stays under **Repeat** on the task that created the next one, beside **Next task**, while the next task still repeats. If nobody has touched the next task yet (it is still in **To do**, unchanged, with no comments or agent runs), it is removed together with its subtasks. Otherwise it stays and no longer repeats. Either way, the series ends: on the task you stopped it from, **Repeat** reads **Never**, and its tooltip says **This series has stopped.** If you used the button under **Repeat**, the focus then moves to **Repeat**. You can also set **Repeat** to **Never** on the latest task of the series.

**Stop repeating** reaches only tasks you can change: the one you use it on, and the later tasks of the series that you can change too. Earlier tasks keep showing their repeat. If a later task belongs to someone else by now, for example after it was reassigned, it keeps its repeat and the series goes on from it; no next task is removed then.

Deleting the latest task of a series ends the series. The task before it doesn't create another one, even if you reopen it and close it again: it shows no repeat icon, and its **Repeat** stays locked, with the tooltip **Its next task was deleted. This task cannot repeat again.** Deleting an earlier task leaves the series going on from the latest one.

### When the repeat can't be changed

Point at **Repeat**, or move the keyboard focus to it, to read why it is locked:

- A task that already created its next task has handed the series on and doesn't repeat again, even if you reopen it. While the series goes on, change the repeat on the next task, which the **Next task** link opens. Once the series has stopped or its next task was deleted, **Repeat** says so.
- Any other task in **Done** or **Cancelled** keeps the repeat it closed with. Reopen it to change the repeat.
- A subtask has no repeat of its own. While its parent repeats, **Repeat** reads **With WEB-3**, for example, and each next task of the parent brings a fresh copy of the subtask. An archived subtask has no **Repeat**: it doesn't come back. Work that follows its own schedule needs a task of its own.
- A task an automation owns doesn't repeat, and assigning a repeating task to an automation ends its series.
- In **Create task**, **Repeat** reads **Never** while **Status** is **Done** or **Cancelled**, or while an automation is the assignee.

## Review the result before closing

For a human-owned task, compare the work with the description’s completion check. For agent work, read the report in the task’s comments and inspect any produced files. A finished run records that the agent has stopped working. Check the recorded review decision to see whether the result was accepted.

Move the task to **Done** when the result meets the requirement. If an agent needs to revise it, add specific feedback and mention that agent. [Task automation](https://docs.tale.dev/platform/projects/task-automation) explains retries, rework, and cancellation.

## Open your tasks from Home

[Home](https://docs.tale.dev/platform#home) lists the open tasks assigned to you and those waiting for your review, from every project you can read; **Tasks** above the list shows only them. A task you open there appears as a page of its own beside the Home panel, not in the board's dialog:

- The brief comes first as a card: the description, attachments, and subtasks.
- The discussion follows like a conversation, oldest first under day labels. It combines the comments with the task's history, such as status changes, assignments, and agent runs.
- The comment box sits at the bottom. Send with **⌘+Enter** or **Ctrl+Enter**, or with the round send button; **Enter** alone starts a new line. Type `@` to mention an agent or a person, with the same effect as in the board's dialog. Text you have not sent stays in the box for that task, here and in the board's dialog, and the task's row in Home shows **Draft** while you work elsewhere.
- **Details** beside the discussion holds the status, priority, assignee, reviewer, dates, repeat, labels, and dependencies, together with **Watch** and **Archive**. Organization owners and admins also find **Delete** there: it removes the task with its subtasks, their comments, and their files for good, and stops their running agent runs. **Hide details** at the end of the header folds it away, and **Show details** brings it back. In a window too narrow to keep both side by side, **Show details** opens it as a sheet over the discussion instead — from the side, or from the bottom on a phone.

**Board** in the header opens the project's task board. A task you open from the board still appears in its dialog; both views edit the same task. **Copy link**, the link icon beside **Board**, copies a link to this task page. To copy the task's identifier, such as `WEB-2`, click it in the line under the title; a message confirms each copy.

## Find work that needs attention

Use **Filter** to narrow the board, or switch to **List** to scan rows. Keep proposals in [Backlog](https://docs.tale.dev/platform/projects/backlog) until they are ready to start; use labels for distinctions that do not need another status.

**Search tasks** narrows the board together with **Filter**, and every task that matches both appears, however many there are. A search finds tasks whose title, description, or identifier, such as `WEB-12`, contains each word you type, and tasks with a comment that contains them all. The board holds up to 2,000 tasks. In a larger project, a note says that only the first 2,000 are shown; search to reach the others.

If the tasks can't be loaded, the board says so instead of showing empty columns, and your search and filters stay as they are. Choose **Try again** to load them. When a refresh fails, the tasks already on screen stay, with a note that they are shown as they were last loaded. A note also tells you when dependencies or agent and review activity can't be loaded, because blocked tasks, running agents, open questions, and pending reviews may then not be marked. **Try again** in a note reloads only what failed.

With the keyboard, press **Enter** on **Filter**: the panel opens on its first filter, **Assignee**. Press **Enter** to expand it and **Tab** to reach its options. The arrow keys choose one, and the board follows at once. **Space** chooses the option the focus is on, and clears it when it is already chosen. **Tab** moves on to the next filter, and **Escape** closes the panel.

In **Board** and **List**, press **Tab** until the task title is focused, then press **Enter** to open the task.

If you can edit the task, press **Space** on its title to pick it up, move it with the arrow keys, and press **Space** again to drop it. **Escape** cancels the move and leaves the task where it was. A screen reader names the task when you pick it up and announces its status and position as you move it.

If a change is refused, check the task’s current state before trying again: a live agent run blocks reassignment, open subtasks block closure, and your role and whether the task is yours determine whether you can change it at all.

# Skill library
Source: https://docs.tale.dev/platform/workspace/skills

A skill packages a repeatable way of working: writing release notes, checking a brief, or preparing a document in your house style. It contains a `SKILL.md` instruction file and, optionally, supporting files. Use **Settings > Skills** to maintain it once, then [equip the agents](https://docs.tale.dev/platform/agents/skills) that need it.

Skills take effect where an agent does the work: a [project agent](https://docs.tale.dev/platform/projects/project-agents) working a [task](https://docs.tale.dev/platform/projects/tasks), or an agent node in an [automation](https://docs.tale.dev/platform/automations/concepts). Chat answers questions and searches your knowledge; it does not use skills, run code, or produce files. To get a document made with a skill, assign a task to an agent equipped with it. Any member can create that task in a project they can open; equipping an agent with the skill needs the Editor role or higher.

Every member can create a skill. You can edit your own; editing or deleting another person's shared skill requires an organization administrator. Your organization can reserve sharing with everyone for some roles; see [Who can share with everyone](https://docs.tale.dev/platform/workspace/skills#who-can-share-with-everyone).

## Create a small skill

<Steps>

<Step title="Name the skill and explain when to use it">

Open **Settings > Skills**, then **Add skill > Blank skill**. Enter a **Name** such as `brief-summary` and a **Description**:

```text
Summarize a project brief into its review date, owner, and open questions.
Use when someone asks for a handover or a quick check of a brief.
```

The name is a unique slug: lowercase letters, digits, and single hyphens, up to 64 characters. The description tells the model when the skill is relevant. Under **Visibility**, choose who sees the skill: **Organization**, or **Teams** with at least one team. Click **Create** to add it and open its editor.

</Step>

<Step title="Write the instructions">

Under **Instructions (body)**, give a short procedure and a recognizable result. For example:

```markdown
Read the supplied brief. Return a table with three rows: review date,
owner, and open questions. Quote the sentence supporting each answer.
Write "Not stated" where the brief supplies no answer. Do not infer a
launch date from a review date.
```

Add reference files only when they help perform the procedure. Keep detailed examples in those files and tell the agent when to open them.

</Step>

<Step title="Choose the audience and save">

**Organization** is preselected when you create a skill, unless your organization reserves it. If the content belongs to a different audience, change it under **Visibility**: **Teams** needs at least one team. Add an icon or labels if they will help people find the skill, then click **Save**.

Creating a skill does not equip an agent automatically. Open the intended project's agent and select the skill in its equipment. Run a small task with a known input and check the result against the instructions.

</Step>

</Steps>

<Frame caption="The skill editor names who created the skill and puts bundle files, description, labels, and visibility together, with Instructions below.">

![The docx skill editor shows its bundle file tree beside Created by Built-in, the description, icon, labels, Organization visibility, and the Instructions heading.](https://docs.tale.dev/images/platform/skill-library-detail.webp)

</Frame>

## Import an existing bundle

Use **Add skill > Upload zip** or **Upload folder**. The bundle must contain `SKILL.md` at its root. References, assets, and scripts can accompany it:

```text
brief-summary/
├── SKILL.md
└── references/
    └── example-brief.md
```

The preview shows metadata, sharing, license, and the file list before **Upload bundle** writes anything. Check the contents and audience. Missing `visibility` means organization-wide sharing. If your organization reserves that and you may not publish, the preview says so and **Upload bundle** stays unavailable; add `visibility: team` and your team IDs to `SKILL.md`. When you create a team skill or change its teams, you may name only your organization's teams, and only your own unless you are an administrator. Keeping an existing team list is allowed even if a team has since been deleted. An `owner` in the file is ignored: a new skill is yours, and a replacement keeps its current owner or becomes yours if it had none. If the name already exists, Tale asks whether to replace that skill; replacement affects the agents that use it.

<Warning>

Importing a skill does not start a task or execute its files. Once equipped, however, its instructions guide a coding agent that may have tools, credentials, and a shell. Review unfamiliar instructions and scripts before equipping the bundle. A skill is not an additional permission boundary.

</Warning>

## Understand sharing

| Visibility | Who can read it | Which project agents can equip it |
| --- | --- | --- |
| **Organization** | Every organization member | Agents in any project |
| **Teams** | Members of the selected teams | Agents in projects with a matching team |

The project's access decides its equipment, even if you personally can read more skills. An organization-wide project can equip organization skills. Legacy private skills remain visible to their owner, but cannot be equipped; new private skills are not accepted.

Narrowing visibility asks for confirmation because some agents may lose access. Deleting a skill has the same practical consequence: runs that require the missing bundle cannot stage it. Check where a shared skill is used before restricting or retiring it.

### Who can share with everyone {#who-can-share-with-everyone}

By default, every member can share a skill with the whole organization. An administrator can reserve this for Editors and above, or for Owners and Admins, under [Skill sharing](https://docs.tale.dev/platform/admin/governance/policies-and-limits#skill-sharing), and can let individual members publish with the **Publish skills to the organization** competence. When your organization reserves it and you may not publish:

- **Organization** is unavailable under **Visibility**, and a new skill starts with **Teams**. You can share with your own teams.
- An organization-wide skill you created cannot be changed in place. Narrow it to your teams, with any other change in the same save, or delete it.
- The upload preview flags a bundle that would be shared with the whole organization, one without `visibility` included, and **Upload bundle** stays unavailable.

Skills that were already shared with the organization stay shared.

## See who created and changed a skill

The **Created by** column names the member who created each skill. Search the library for a name to find everything that person shared. The column shows **Built-in** for a skill without a recorded creator, such as the document skills your organization starts with, and **Configuration release** with the member whose upload installed it for a skill a managed configuration release installed. Once the creator leaves the organization, it shows **Former member**.

<Frame caption="Settings > Skills — the Created by column names the member who wrote each skill and marks the document skills as Built-in.">

![The skill library lists seven skills: brief-summary and release-notes created by Alex Rivera, and docx, pdf, pptx, visual-aspect-analyzer, and xlsx marked Built-in, each shared with the Organization.](https://docs.tale.dev/images/platform/skill-library-list.webp)

</Frame>

Open a skill to see **Created by** and **Last edited by**: the member whose save or upload in Tale produced the current version. **Last edited by** is left out when nobody has edited the skill since it was created, or when its file changed outside Tale since the last edit. The skill list in an [agent's equipment](https://docs.tale.dev/platform/agents/skills) names the creator under each skill as well.

Tale records creating, editing, uploading and deleting a skill, and every change to its visibility or teams, in the audit log. Administrators and owners find these entries under **Settings > Governance > Logs** in the **Skill** category.

## File reference

A minimal `SKILL.md` looks like this:

```markdown
---
name: brief-summary
description: Summarize a project brief. Use for brief handovers and checks.
visibility: org
---

Read the supplied brief. Report its review date, owner, and open questions.
Quote supporting text and mark missing information as "Not stated".
```

| Field | Meaning |
| --- | --- |
| `name` | Matches the bundle's folder name. `anthropic` and `claude` are reserved. |
| `description` | When and why the model should read the skill; maximum 1,024 characters. |
| `visibility` / `teams` | `org`, or `team` with the team IDs. The UI fills these in for you. |
| `owner` | The user ID of the member who created the skill. Tale sets it; a value in an uploaded file is ignored. |
| `license` | The terms supplied by the author. |
| `recommended-packages` | Suggested dependencies; importing does not install them. |
| `disable-model-invocation` | Requests explicit use of the skill. Treat this metadata as an instruction, not an access restriction. |
| `icon` / `labels` | Library presentation; up to eight labels of up to 40 characters each. |

Tale preserves unrecognized frontmatter keys. The frontmatter limit is 16 KB and the complete `SKILL.md` limit is 512 KB. Keep frequently read instructions much smaller than these ceilings.

## Update and troubleshoot

Open a row to edit its description, instructions, labels, and visibility. The **Bundle** tree lets you inspect supporting files. Changes are not pinned per agent: later staging uses the current bundle, so test shared changes with a representative task.

**Labels** takes up to eight comma-separated labels of up to 40 characters each. When the list is longer, or a label is too long, the field says what to remove or shorten and **Save** stays unavailable; nothing you typed is dropped. The **Bundle** tree remembers the folders you collapse, per skill, in your browser.

If Tale cannot load a skill or one of its files, the dialog says so and offers **Try again**. When a refresh fails, the version already on screen stays, unsaved changes included. A removed file is reported as no longer in the bundle, and an empty file as empty.

If an agent cannot find the skill, check that it is equipped and visible to the project. Tale shows the agent a description excerpt of up to 300 characters to help it choose a relevant skill, so start the description with when the skill applies. If it ignores an equipped skill, name the skill in the task and check the result against its instructions. Read [Skills on agents](https://docs.tale.dev/platform/agents/skills) for how the equipped bundle is staged and presented to the agent.

For an import error, check that `SKILL.md` is at the root, its frontmatter is valid, and its name is a valid slug. The error names rejected paths or size limits. To retire a bundle, open it and choose **Delete skill** after checking the affected agents.

# Set automation approval rules
Source: https://docs.tale.dev/self-hosted/configuration/approvals

Automation approval rules decide whether a live connector write runs immediately or waits for a person. The default requires approval for writes to external systems; writes through platform-authenticated internal connectors are allowed. Override that behavior for one organization when its review process needs a different boundary.

## Define the organization’s policy

Store rules in `TALE_CONFIG_DIR/<orgSlug>/governance/approval-policy.yml`. Each rule names exactly one `connector` or one qualified `action`, followed by `decision`.

This example requires review for writes through the internal `task` connector and allows `imap-smtp.send` without a separate approval:

```yaml
rules:
  - connector: task
    decision: require_approval
  - action: imap-smtp.send
    decision: auto_approve
```

<Warning>

`auto_approve` permits the matching write without a human review at this gate. Check the exact action, credentials and intended recipients before allowing an external action such as sending email.

</Warning>

Use connector and action identifiers from the shipped catalog, not translated display names. The action form is `<connector>.<action>`; the allowed decisions are `auto_approve` and `require_approval`.

## Resolve overlapping rules

An action rule wins over a connector rule regardless of their order. Among equally specific matching rules, the last one wins. If no rule matches, Tale uses the internal-versus-external default above. Keep each target once where possible so readers can predict the result without tracing overrides.

The policy affects new gate evaluations. A pending approval is retained when you relax the rule; it does not silently become approved. This file also does not remove independent review gates such as publishing an automation or completing a task that needs review.

## Verify the effect

Test with an isolated automation and harmless data before enabling a rule for production work. Confirm one matching operation and one operation that should keep its default behavior. Inspect the pending approval and run trace through the [approval workflow](https://docs.tale.dev/platform/approvals/configure).

New write decisions read the current policy and organization slug without the short display cache. If the policy is invalid or its configuration root is unavailable, the operation stops before the write; repair the configuration before retrying. Only an absent policy file in an available configuration tree uses the default rules. A malformed `.yml` file never falls back to a sibling `.json`. Existing approval records keep their recorded decision, including pending approvals and previously granted operations.

# Choose an authentication setup
Source: https://docs.tale.dev/self-hosted/configuration/authentication

Tale supports local email-and-password accounts, organization-specific enterprise sign-in and identity supplied by a trusted reverse proxy. Choose based on where your team’s identities are managed and who owns account provisioning. Sign-in and provisioning are separate decisions: SSO authenticates a person, while invitations, sign-in provisioning or SCIM control membership.

## Choose the right integration

| Your environment | Configure | Main prerequisite |
| --- | --- | --- |
| Local accounts managed in Tale | Local sign-in and invitations | Stable deployment secrets and a reachable instance URL. |
| An existing corporate identity provider | Enterprise SSO: Microsoft Entra ID, generic OIDC, OAuth2 or SAML 2.0 | An IdP application configured with Tale’s exact callback or metadata URLs. |
| An application or proxy already authenticates its users | Trusted headers, per organization | A key from **Settings > Enterprise SSO** and a proxy that injects it with the identity headers. |

Enterprise SSO and trusted headers are both configured per organization. Plan and test changes to identity mapping before moving existing accounts to another mechanism.

## Establish the public URL first

Set `SITE_URL` and any supported base-path configuration to the URL people will actually open. Complete [TLS and domain setup](https://docs.tale.dev/self-hosted/configuration/tls-and-domains) before registering redirect URLs with an identity provider.

Keep `BETTER_AUTH_SECRET` stable across the backend processes that serve the instance. Use the generated secret from your deployment tooling or inject it from your secret manager. A mismatch can interrupt authentication even when the identity provider accepts the user.

## Use local accounts

Local sign-in stores password hashes in the application database. The [first-admin setup](https://docs.tale.dev/self-hosted/install/first-admin) creates the initial Owner; later members join by invitation. Configure mail delivery if your onboarding and password-recovery process relies on email.

Verify the complete flow with a test account: invitation, sign-in, sign-out and recovery. A working owner session does not prove that a new member can join.

Tale sends no verification mail, so an address is confirmed by whoever provisioned it: the setup wizard’s first Owner, an admin adding a person under **Settings > Members**, and the operator’s deployment all count as that assertion, and the account is usable straight away. Connected applications read this as the `email_verified` claim on the identity Tale issues, so a colleague an admin just added can sign in to them immediately. An account that comes from enterprise SSO, SCIM or trusted headers keeps whatever its directory reports instead.

## Connect enterprise sign-in

Configure the organization under **Settings > Enterprise SSO**. Microsoft Entra ID and generic OIDC use issuer discovery; OAuth2 takes explicit authorization, token and userinfo endpoints; SAML uses metadata, an assertion-consumer URL and signing certificates.

<Frame caption="Copy the URLs from the running instance so its domain and deployment path are included.">

![The Enterprise SSO settings page shows protocol selection and the connection fields for Microsoft Entra ID.](https://docs.tale.dev/images/platform/settings-enterprise-sso.webp)

</Frame>

Use the callback and metadata URLs shown there rather than reconstructing them. Current native OIDC callbacks use `/api/sso/callback`; the compatibility route `/http_api/api/sso/callback` is also supported for existing registrations. The IdP registration must match the URL used by the flow.

Follow [Enterprise SSO and provisioning](https://docs.tale.dev/platform/admin/enterprise-sso) for protocol-specific setup, claim mapping, default roles, team synchronization and SCIM. Test sign-in in a separate browser session before ending the administrator session used to configure it. Discovery passing does not prove claims, group permissions or a complete sign-in.

## Trust an authentication proxy

An application that already signs its users in can hand them into one organization through its reverse proxy. An Admin turns the feature on under **Settings > Enterprise SSO**, in the **Trusted headers** card: choose the highest role the proxy may assert, then create a key and copy it, because it is shown once. Point the proxy's sign-in at `/api/trusted-headers/authenticate` with that key in the `Remote-Internal-Secret` header and the identity headers `Remote-Email`, `Remote-Name`, `Remote-Role` and `Remote-Teams`. The [environment reference](https://docs.tale.dev/self-hosted/configuration/environment-reference) lists the `TRUSTED_*_HEADER` variables for renaming those headers.

The key decides the organization. A member of that organization signs in; an address the deployment has never seen becomes a new member with the asserted role; an existing account from another organization is refused. Owner is never assertable, and a role above the organization's ceiling is lowered to it. On every sign-in the member's seat follows the asserted role, so **Settings > Members** shows what the proxy asserted; an Owner seat never changes. Turning the card off refuses every key without revoking one; revoking a key does not end the sessions it started.

<Warning>

The proxy must remove client-supplied identity headers, set its own authenticated values and add the key only on the hand-off request. Anyone holding the key can sign in as any member the proxy names within that organization. Treat it like a password and rotate it from the card.

</Warning>

`Remote-Teams` lists team names separated by commas, for example `Finance,Operations`; an `id:name` entry such as `t-fin:Finance` is accepted too, and teams are matched and created by name. An omitted header leaves team management alone; a present empty header removes memberships previously granted by this synchronization. Invalid entries can therefore remove synchronized memberships. Manually granted memberships are preserved.

A proxied visitor is signed in on the app's first own request: when that request carries the key and the identity header but no session cookie, the backend mints the session right there and the app opens signed in — no sign-in page, no redirect. Should the app still land on its sign-in page (a stale cookie, for example), the page hands the browser to the hand-off address by itself, and a refusal comes back to that page with its reason. Routing the proxy's `/log-in` straight to the hand-off address remains supported; the address answers a success with a redirect to the app and a refusal as a page with its status. Because the proxy owns the session, the app offers no sign-out to a proxied member; after an inactivity sign-out the automatic sign-in pauses until the member continues from the notice.

To show Tale inside the application's own page rather than in a tab, an Admin lists that page's origin under **Embedding** on the same settings page. Tale's pages then answer with a `frame-ancestors` policy naming `'self'` and the listed origins instead of refusing every frame, and the `X-Frame-Options` header is left off. The list belongs to one organization, but the sign-in shell is one document for the whole deployment, so an origin any organization admits may load it. The browser sends the session cookie into a frame only when the surrounding page is on the same site as Tale, for example a subdomain of the host or Tale served under the host's own domain; a cross-site frame shows the sign-in page instead.

## Diagnose sign-in failures

| Symptom | Check first |
| --- | --- |
| IdP rejects a redirect | Compare its registered URL with the URL shown by Tale, including scheme, host and path. |
| Redirect returns but sign-in fails | Check callback reachability, cookies and the configured claim names. |
| Member receives the wrong role | Check default role and mapping rules with that person’s actual claims. |
| Synchronized teams disappear | Inspect the groups claim or `Remote-Teams` value; distinguish absent from empty. |
| Trusted-header sign-in is refused | Check that the card is on for that organization, that the key is not revoked, and the proxy's header names. |

Use a staging organization for mapping changes and keep a tested administrative recovery path. Authentication changes can affect every member whose identity depends on the connection.

# Release client configurations
Source: https://docs.tale.dev/self-hosted/configuration/config-releases

A configuration release installs a reviewed workflow and its owned skills into an existing organization and project. Its identity is the full source commit. Use this procedure when the application runtime stays in place; use [managed deployments](https://docs.tale.dev/self-hosted/install/cli-install#managed-deployments) for a new instance or runtime change.

## Know what each command produces

| Command | Result to check before continuing |
| --- | --- |
| `config build` | A manifest and compiled archives from a committed source revision. |
| `config verify --rebuild` | Independent reconstruction agrees with the reviewed artifacts. |
| `config stage` | A transferable directory containing only the deployment files and their hashed inventory. |
| `config deploy` | The workflow and owned skills are installed, read back, and recorded in a persistent receipt. |
| `config verify-native` | A read-only comparison with the currently installed content. |

A **native** ID or session in these commands belongs to the target Tale instance. A **receipt** records a deployment result; it does not replace checking the current server. Format and byte verification do not prove the automation's business result, so keep domain tests in the client repository.

## Before you begin

Install the [Tale CLI](https://docs.tale.dev/self-hosted/install/cli-install) and pin a revision that supports the target server's pack format and APIs. Configuration commands take explicit source and target options; they need no local `tale.json`, Docker context or adjacent Tale source checkout. The bundled parser and validator check supported fields, without adding newer server capabilities to an older instance.

You need a committed client descriptor and pack, an existing organization and project, and an authorized native operator session. If the pack owns skills, use that user's native ID as the build owner. The ID is distinct from a project, organization or external identity ID.

For a new instance without native IDs, use managed deployment with an explicit fresh identity, symbolic project and `skillOwner: "operator"`. It carries verified source and compiles only after proving the native operator; these standalone release commands still require resolved IDs. Keep business configuration in its client-owned source tree. External model settings belong to the deployment declaration.

The examples use the synthetic `example-team` client and `document-review` automation. Inject the full operator session cookie through `TALE_CONFIG_COOKIE` from your secret manager. Keep it out of arguments, source, archives, receipts and logs.

## Commit the descriptor and pack

Store the descriptor at `tale/client.json`, packs beneath `tale/packs/`, and domain tests beside them. Keep any retained historical release catalogue there too. Descriptor paths resolve relative to its own directory.

Ignore `.tale/` if it is not already in the client's `.gitignore`. Default builds keep local coordination state there; explicit output operations coordinate beside their output. Maintained configuration uses `tale/` without the dot.

```json
{
  "schemaVersion": 1,
  "clientId": "example-team",
  "sourceRepository": "https://github.com/example-team/client-app",
  "automations": [
    {
      "name": "document-review",
      "displayName": "Document review",
      "packPath": "packs/document-review",
      "releasesPath": "releases/document-review",
      "logicalSkillSlugs": ["record-check"],
      "requiredExternalSkills": []
    }
  ]
}
```

`logicalSkillSlugs` lists the skill directories carried by this pack. `requiredExternalSkills` lists dependencies already installed in Tale: the CLI checks their presence, but this release does not pin their bytes. Keep credentials, target hostnames and project IDs in deployment configuration. Commit the descriptor and pack; the compiler reads Git objects rather than uncommitted edits.

## Build and verify the source commit

Set `CONFIG_REPO` to the checkout, `CONFIG_SOURCE_COMMIT` to its full 40-character source commit, and `TALE_NATIVE_USER_ID` to the native operator ID. Choose a new absolute `CONFIG_BUILD` output directory outside the checkout. These commands build the release and independently reconstruct its bytes.

```bash
tale --json config build \
  --repo "$CONFIG_REPO" \
  --descriptor tale/client.json \
  --automation document-review \
  --source-commit "$CONFIG_SOURCE_COMMIT" \
  --skill-owner "$TALE_NATIVE_USER_ID" \
  --output "$CONFIG_BUILD"

tale --json config verify \
  --repo "$CONFIG_REPO" \
  --descriptor tale/client.json \
  --automation document-review \
  --manifest "$CONFIG_BUILD/$CONFIG_SOURCE_COMMIT.json" \
  --rebuild
```

The default manifest uses schema 4/compiler 3 and records `releaseRef` equal to `sourceCommit`, plus the pack tree, descriptor hash and complete compiled inventory. The output contains a canonical ZIP, one ZIP per owned skill and a workflow-only installation ZIP. Owned skill slugs carry the full source SHA, with compiler metadata preserving their logical identity. The complete skill bytes include the declared owner; changing that owner requires a new source commit and release.

Require identical bytes on rebuild and run the client's correctness tests against the extracted canonical ZIP. Preserve the reviewed artifacts and record `artifactSha256` as `CONFIG_ARTIFACT_SHA256`. Native format validation proves that the pack can be interpreted, not that its business results are correct. New source-based deployments do not need an extra commit containing generated release files.

## Prepare the transfer directory

Use a checkout whose `HEAD` matches `CONFIG_SOURCE_COMMIT`. Set `CONFIG_STAGE` to a new absolute output directory outside that checkout. The optional `DEPLOYMENT_COMMIT` records the full commit of your deployment declaration; omit `--deployment-ref` if you do not track one.

```bash
tale --json config stage \
  --repo "$CONFIG_REPO" \
  --descriptor tale/client.json \
  --automation document-review \
  --config-ref "$CONFIG_SOURCE_COMMIT" \
  --skill-owner "$TALE_NATIVE_USER_ID" \
  --client example-team \
  --deployment-ref "$DEPLOYMENT_COMMIT" \
  --output "$CONFIG_STAGE"
```

The stage builds the committed descriptor and pack, independently verifies the archives and prepares only allowlisted deployment files with a hashed inventory. Dirty source edits do not enter it. Check that its artifact hash matches the reviewed build. Preserve the stage as one unit during transfer; the native destination needs neither the client checkout nor its Git credential.

Pin the client repository URL and full source SHA, Tale CLI revision and optional deployment revision. Source provenance also depends on your trusted checkout: a URL in a descriptor does not establish which remote supplied a local Git object.

## Deploy and read the result back

Set `TALE_CONFIG_URL`, `TALE_CONFIG_ORIGIN`, `TALE_ORG_ID` and `TALE_PROJECT_ID` to the approved native target. Keep `CONFIG_RECEIPT` on persistent storage. After reviewing the stage, supply `--yes` for an authorized unattended deployment, then run a separate read-only verification. Use the same optional deployment reference as the stage.

```bash
tale --json --yes config deploy \
  --stage "$CONFIG_STAGE" \
  --url "$TALE_CONFIG_URL" \
  --origin "$TALE_CONFIG_ORIGIN" \
  --org "$TALE_ORG_ID" \
  --project "$TALE_PROJECT_ID" \
  --receipt "$CONFIG_RECEIPT" \
  --config-ref "$CONFIG_SOURCE_COMMIT" \
  --source-repository https://github.com/example-team/client-app \
  --artifact-sha256 "$CONFIG_ARTIFACT_SHA256" \
  --deployment-ref "$DEPLOYMENT_COMMIT"

tale --json config verify-native \
  --stage "$CONFIG_STAGE" \
  --url "$TALE_CONFIG_URL" \
  --origin "$TALE_CONFIG_ORIGIN" \
  --org "$TALE_ORG_ID" \
  --project "$TALE_PROJECT_ID" \
  --config-ref "$CONFIG_SOURCE_COMMIT" \
  --source-repository https://github.com/example-team/client-app \
  --artifact-sha256 "$CONFIG_ARTIFACT_SHA256" \
  --deployment-ref "$DEPLOYMENT_COMMIT"
```

The target URL is where the API is reachable; the origin is the canonical browser origin, including when the API URL is loopback behind a proxy. The authenticated native user must match the declared skill owner.

Deployment creates missing owned skills through native create-only upload and verifies every installed byte. Existing exact bytes can be reused; differing bytes at the release slug cause a refusal. Workflow-only import cannot write skills. Before reporting success, the CLI checks the deployed workflow, settings, presentation, task contract and project binding.

Run `verify-native` after deployment and operational tests. It imports nothing and creates no version or receipt. A repeat deployment also reads current native content before reporting an unchanged release; a stored receipt alone does not prove current bytes.

## Recover a stopped deployment

Keep the exact stage and receipt while investigating. Choose the next action from the state the CLI reports:

| State | Safe next step |
| --- | --- |
| A trusted receipt records partial progress | Retry with the same stage, target, and receipt. Exact skills can be reused. |
| A matching version is already deployed | Read it back with `verify-native`; a repeated deploy also verifies before reporting no change. |
| An upload response was lost and only an unpublished version is visible | Stop and investigate. The native API cannot read its complete task contract before deployment, so the CLI cannot prove that version safe to reuse. |
| A release skill slug exists with different bytes | Preserve the evidence and identify the conflicting release or edit. Do not overwrite it to make verification pass. |
| A receipt is unreadable or names another target | Restore the correct record or resolve the mismatch before retrying. Never manufacture a successful receipt. |

Coordinate deployments that share a destination. Local locking does not prevent another host or an administrator from changing native content. After recovery, rerun the client's operational checks and the independent native verification.

## Reconstruct a historical release

Existing semantic releases remain a compatibility path: `build --config-version` selects schema 3/compiler 2; `stage --config-version` uses the committed catalogue and its explicit catalogue/ops pins. Keep original manifests and archives unchanged. A descriptor can register checksummed historical source snapshots for offline reconstruction; only that format's supported fields can be verified. Legacy shared skills may be reused only when explicitly allowed and already byte-identical. Restore different historical content through a new release.

Historical reconstruction needs additional tools. Schema 1 uses Git's `archive --mtime` capability; check your selected Git supports it. Schema 2/compiler 1 uses Python 3's standard library. Schema 3/compiler 2, schema 4/compiler 3 and native deployment do not need Python.

Retain the source, client tests, reviewed archives, CLI revision, deployment pins, and receipt together. Keep session cookies and credentials in your secret manager, outside those artifacts. [Upgrades](https://docs.tale.dev/self-hosted/operate/upgrades) and [Backups and restore](https://docs.tale.dev/self-hosted/operate/backups-and-restore) cover recovery of the surrounding runtime and data.

# Choose and move data stores
Source: https://docs.tale.dev/self-hosted/configuration/data-residency

Choose storage for three kinds of data: application records, searchable knowledge, and original files. Moving one does not move the others. Storage placement also does not determine where a model provider or connector processes a request; include those destinations in your residency assessment.

## Choose the scope of the change

| Store | Deployment-wide setting | Organization-specific setting |
| --- | --- | --- |
| Application database: users, chats, runs, and audit data | `DATABASE_URL` | No separate application database setting on this page. |
| Knowledge database: extracted text, embeddings, search indexes, and crawled content | `KNOWLEDGE_DATABASE_URL` | **Settings > Data residency > Knowledge database** |
| Original files: documents, attachments, audio, and generated media | `OBJECT_STORE_*` | **Settings > Data residency > Object storage** |

The packaged stack puts `tale_app` and `tale_knowledge` in one Postgres service, while keeping them separate databases. Other layouts can use separate services. The environment values generated by the deployment select the defaults; a bare application process does not invent working object-store credentials.

Organization settings require Admin or Owner permissions. Without an organization-specific connection, Tale uses the deployment default and keeps organization data scoped. An invalid configured knowledge connection fails rather than silently using a different database.

## Prepare an external database

Provision the database and credentials before changing Tale. The application database needs a role with permission to apply its schema migrations. The knowledge database needs `vector` installed; `pg_search` enables the BM25 part of hybrid search. A target with only pgvector provides vector search without that keyword leg. Tale prepares knowledge schemas and tables but does not install extensions on a database you own.

Use a direct or session-compatible Postgres connection. Transaction-mode pooling is incompatible with session locks, `LISTEN`, and prepared statements used by the stack. For `sslmode=verify-ca` or `verify-full`, supply the required PEM roots through `POSTGRES_CA_FILE` and mount the file in the backend roles. Check connectivity and permissions from the deployment network.

Before a cutover, choose how existing application or knowledge data will reach the destination, and take coordinated backups. Saving a database connection only changes where subsequent operations go; it does not copy old rows or reindex old documents automatically.

## Change deployment defaults

Update `.env`, then deploy or recreate the affected backend services. `docker compose restart` keeps the old environment. If you are moving both databases out of the bundled service, preserve its old volume until the new stores and recovery plan are accepted.

For the default object store, the backend reconciles `default/object-storage/connection.json` and its secret sidecar from the environment at startup. The boot result distinguishes `seeded`, `reconciled`, `skipped` when credentials are absent, and `ignored` for an operator-managed file. `"managedBy": "operator"` makes you responsible for that file instead of environment reconciliation.

Changing the default bucket or endpoint does not copy existing blobs. Copy them with storage tooling, retaining keys and required metadata, and coordinate the switch before removing the old store. An external database or bucket is outside the CLI volume snapshot's data coverage; update [Backups and restore](https://docs.tale.dev/self-hosted/operate/backups-and-restore) procedures as part of the change.

## Connect an organization's knowledge database

1. Open **Settings > Data residency** in the target organization and configure **Knowledge database** with host, port, database, user, SSL mode, and password.
2. Use **Test connection**. It first checks the fields the way **Save** does and names a missing host, database, or user under its field instead of running. Check both connectivity and extension availability; a successful connection does not prove the old corpus has migrated.
3. Save only when the destination and existing-data plan are ready. Subsequent requests use the selected connection without a container restart.
4. Index a controlled document, search for a known phrase, and verify that pre-existing content required by your users remains available.

The files live under `$TALE_CONFIG_DIR/<orgSlug>/knowledge/`: `connection.json`, `connection.secrets.json`, and `embedding.json`. Secrets use SOPS when an age key is configured. Removing the connection returns routing to the deployment default; it leaves data in the external database and makes that data inaccessible through the removed connection.

### Match the embedding model to the corpus {#the-organizations-embedding-model}

In **Embedding model**, choose the provider and stored credential, then the model. **Model** lists the embedding models the provider's catalog carries and fills the vector width the catalog states. A provider that offers no embedding model at all, such as Anthropic, cannot be chosen: the row reads **Cannot embed**, and you pick another provider. Where Tale knows no vector width for the provider, type the model tag (for Azure OpenAI, your deployment name) and the vector width that model produces. That applies to a shipped provider whose catalog lists no embedding model, to a provider your organization defined itself whose model listing carries none, and to Azure OpenAI, whose deployments carry your own names. The provider's [`embedding` declaration](https://docs.tale.dev/self-hosted/configuration/providers#what-a-connector-declares) decides between the two, and saving refuses a provider declared unable to embed however the request arrives. If Tale cannot check the declarations, the section says so and offers **Try again**; until the check answers, no model can be chosen. An optional base URL selects an OpenAI-compatible endpoint. Without a configured embedding model, knowledge indexing and search cannot operate normally.

Vector width is pinned per database on first use. Organizations sharing a database must use that width; a different width needs a separate compatible database. Changing the model can also make existing vectors incompatible even when the width stays the same. Plan reindexing with the chosen model instead of mixing embeddings blindly.

`embedding.json` can set `minSimilarity`, the assistant search's vector-leg floor; its default is `0.45`. The settings form preserves this file value but does not expose a field for it. Tune it against representative queries. REST knowledge search applies a floor only when its request supplies one; this is not a universal score threshold for all searches.

### Pace requests to a self-hosted embedding server {#embedding-server-capacity}

Two more optional `embedding.json` settings describe how much work the embedding server can take. Set them when you run the server yourself, for example a model server on your own hardware that computes one request at a time and queues the rest. Like `minSimilarity`, they exist only in the file: the settings form keeps them when you save, and the CLI declares them in the `knowledge-embedding` resource.

- `maxConcurrentRequests` (1 to 64, default 3) is how many embedding requests to this model Tale keeps in flight at once for the organization. Document indexing, the indexing of incoming email, website scans and searches share this limit. Further requests wait in arrival order, except that a search query goes ahead of waiting indexing batches. Each Tale process counts separately, so the API and every worker replica can each reach the limit. A lower value takes effect at once; a higher one once the requests started under the old value have finished. On a server that computes one request at a time, a higher value adds no load; each request only waits longer.
- `minTokensPerSecond` (any positive number) is the slowest rate at which the server computes embeddings for this model under its usual load. Measure it while other work runs on the same hardware, such as a chat model, but leave out the time a request waits behind other requests. Tale adds that waiting time itself.
- `maxTokensPerMinute` and `maxRequestsPerMinute` (whole numbers) pace what Tale sends this model within any one minute, for the organization in each Tale process. Set them to a hosted provider's per-minute limits, which are counted per provider account across every deployment that shares the key: an indexing batch that would cross a limit waits until enough of the last minute has aged out, so a crawl of hundreds of pages is paced instead of refused with `429`. Tale estimates tokens from characters, on the high side, keeps a sixtieth of each limit within any one second as well — a provider enforces its per-minute figure per second too — and sizes each request to fit that second. A `429` the provider still answers pauses every request of the organization to that model and is retried on a minute scale; a search query is not held back by either. Alibaba Cloud Model Studio, for example, allows text-embedding-v4 1,800 requests and 1,000,000 tokens per minute.

```json
{
  "providerSlug": "local-embedding",
  "model": "example-embedding",
  "dimensions": 1024,
  "baseUrl": "https://embeddings.example.internal/v1",
  "maxConcurrentRequests": 2,
  "minTokensPerSecond": 800,
  "maxTokensPerMinute": 1000000,
  "maxRequestsPerMinute": 1800
}
```

Each embedding request has a ceiling: 15 minutes for indexing, and 5 minutes for a search query, which a chat answer waits on. Without `minTokensPerSecond`, Tale cannot tell how long the server's queue may take, so a request may use its whole ceiling. With it, Tale gives each request time for the work that can be ahead of it or beside it on the server, plus its own. That work is the request's own tokens, estimated generously from its characters, plus the other requests this Tale process may have in flight and `maxConcurrentRequests` more from other clients. Tale counts each of those requests as at least a full batch of 64 texts with 1,024 tokens each, divides the total by `minTokensPerSecond`, and adds 50%, but never allows less than 60 seconds or more than the ceiling. With the example above, a full batch of ordinary text gets about eight minutes, and a search query gets its five-minute ceiling. A search query also ends after five minutes in total, including any wait for a free slot. If more clients share the server than one more Tale process with the same limit, state a lower rate.

A request that runs out of time is not sent again at once: the server had it the whole time, and a repeat would only lengthen its queue. A refused connection, a rate limit or a server error is retried after a pause that grows with each attempt, or after the pause a busy server asks for with `Retry-After`, up to one minute. A server that asks for a longer pause is left alone. When one batch of a request made of several batches fails, for example on a long web page, Tale cancels the other batches, whether they are running or still waiting, so the server stops working on them.

Indexing a document gets at most 15 minutes per attempt. When a large document or a long queue needs more, the attempt stops at that limit and cancels its open request; a request that runs out of time ends the attempt too. The next attempt starts after a pause that grows with each attempt and continues after the chunks already stored. If a document is still unfinished after six attempts, it shows as failed; **Retry indexing** continues from the stored chunks.

## Connect an organization's bucket

1. Provision an S3-compatible bucket and the required object permissions. Configure CORS for the actual browser origins and the needed `GET`, `PUT`, and `HEAD` methods.
2. In **Object storage**, enter region, endpoint when needed, bucket, optional key prefix, and credentials. Use path-style addressing when your store requires it.
3. Run **Test connection**, then save. A missing region or bucket, or a value past a field's length limit, is named under its field before anything is sent. The server test writes, reads, and deletes a test object; it does not test browser CORS.
4. Upload and download a controlled file in the browser before relying on the new connection.

New uploads use the organization's bucket. Earlier default-store files can remain readable through mixed references, so connecting the bucket does not by itself meet a requirement to relocate history. Configuration lives under `$TALE_CONFIG_DIR/<orgSlug>/object-storage/connection.json` and `connection.secrets.json`.

Removing this connection sends new uploads to the default store. Existing objects remain in the organization's bucket but require the connection to be restored before Tale can read them again.

### Move existing files deliberately

With the organization bucket saved, use **Move existing files** in the same section. Review any preview, confirm the move, and follow its progress. Keep the connection stable until it finishes.

The backfill walks that organization's referenced documents and history, uploaded files, synthesized audio, and video transcripts. It copies each blob with its content type, checks the destination size, then deletes the source copy. It preserves object keys and can resume a previously verified copy without duplicating the move. This is a move, not an additional backup or a cryptographic content audit.

The destination must differ from the default store. If the run fails, inspect its last error and progress before starting another; preserve both stores until the final result and representative old-file downloads are verified. See [Secrets with SOPS](https://docs.tale.dev/self-hosted/configuration/secrets-with-sops) for protecting the connection sidecars.

# Environment reference
Source: https://docs.tale.dev/self-hosted/configuration/environment-reference

Use this reference to find a deployment variable, its default and the process that needs it. The project `.env` is one way to supply values; container environment settings and secret-manager injection are also deployment inputs. The [example environment file](https://github.com/tale-project/tale/blob/main/.env.example) carries the corresponding source configuration.

After changing an environment value, recreate the consuming services through your deployment workflow. `docker compose restart` retains the container’s existing environment. File-based organization configuration has a separate lifecycle.

## How to read this page

Tables list names, defaults, and purpose. Required values must reach the consuming service; deployment tooling may generate some of them. Optional values can remain unset. A documented default can come from the shipped Compose configuration rather than the process itself.

Use the example file alongside this reference and inspect your effective service environment before diagnosing a missing value.

## Domain identity (required at first boot)

| Name        | Default             | Description                                                                                                               |
| ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `HOST`      | `localhost`         | **Required.** Hostname without protocol. Used for Docker networking and outbound email.                                   |
| `SITE_URL`  | `https://localhost` | **Required.** Full canonical URL including scheme and any non-standard port. Auth callbacks and external links use this.  |
| `ADDITIONAL_SITE_URLS` | unset      | **Optional.** Other origins the same deployment answers on, comma- or whitespace-separated (e.g. `https://a.example,https://b.example`). Each is a full entry point. See [TLS and domains](https://docs.tale.dev/self-hosted/configuration/tls-and-domains#several-domains-at-once). |
| `TOTP_ENVIRONMENT` | unset | Authenticator environment label for `backend-api` and the `all` role: 1–32 letters, digits, underscores or hyphens, trimmed and uppercased. `pr` or unset keeps `Tale`; `te` names newly generated entries `Tale <TE>`. Invalid labels prevent backend startup. |
| `BASE_PATH` | unset               | **Optional.** Path prefix for subpath deployments behind a reverse proxy (e.g. `/app`). Leave unset for root deployments. |
| `DOCS_URL` | `https://docs.<HOST>` | Public origin for the proxy’s separate documentation host. The deployment must also include the docs service. |

`SITE_URL` identifies the canonical public origin. Keep scheme, hostname, and port consistent with the browser address and registered callbacks; `BASE_PATH` supplies a deployment path prefix. A trailing slash is normalized by the proxy. Additional addresses belong in `ADDITIONAL_SITE_URLS` as bare origins. Invalid additional origins stop backend startup.

The prose documentation uses its own origin. On the platform origin, `/docs` opens the interactive API reference and `/openapi.json` serves its schema. `DOCS_URL` changes the proxy’s docs host; it does not install the docs service or rewrite links in existing client bundles. The SEO tooling’s `TALE_DOCS_URL` and the docs service’s build/runtime path prefix `DOCS_BASE_URL` are separate settings.

Changing `TOTP_ENVIRONMENT` affects newly generated QR codes and setup URIs, including when an existing secret is displayed again. It does not rotate secrets or rename entries already saved on a device; rename those in your authenticator app if needed.

## TLS

| Name        | Default      | Description                                                                                                                       |
| ----------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `TLS_MODE`  | `selfsigned` | One of `selfsigned`, `letsencrypt`, `external`. See [TLS and domains](https://docs.tale.dev/self-hosted/configuration/tls-and-domains) for trade-offs. |
| `TLS_EMAIL` | unset        | Contact email for Let's Encrypt notifications. Optional but recommended in production.                                            |
| `TRUSTED_PROXIES` | `private_ranges` | With `TLS_MODE=external`, the addresses whose forwarded headers the proxy accepts: CIDR ranges separated by spaces, or `private_ranges`. The other modes ignore it. See [TLS and domains](https://docs.tale.dev/self-hosted/configuration/tls-and-domains). |

`selfsigned` runs Caddy with a generated cert — the browser warns, fine for development. `letsencrypt` requires a real domain and ports 80/443 reachable from the public Internet. `external` makes Caddy serve plain HTTP; an upstream reverse proxy terminates TLS.

## Security secrets (required)

| Name                    | Default                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BETTER_AUTH_SECRET` | example value in shipped file | Authentication secret shared by backend replicas. Generate a high-entropy value, for example with `openssl rand -base64 32`. Keep it stable; changing it can invalidate sessions and active sign-in flows. |
| `ENCRYPTION_SECRET_HEX` | example value in shipped file | 32-byte hex encryption root for stored secrets; generate with `openssl rand -hex 32`. Preserve the value matching existing encrypted data. Replacing it does not migrate ciphertext: restore the matching key or re-enter affected secrets through their supported flow. |
| `INSTANCE_SECRET`       | example value in shipped file | **Required.** The instance's root secret: 64 hex chars, generated by `tale init` (`openssl rand -hex 32` by hand). At boot the WebDAV app-password HMAC key (`WEBDAV_APP_PASSWORD_HMAC_KEY`) is derived from it unless you set that key yourself, and the short-lived tokens sandbox sessions use to fetch blobs are signed with a subkey of the same derivation. Keep it stable across deploys: rotating it re-derives that key and invalidates every WebDAV app-password. |
| `SANDBOX_TOKEN`         | example value in shipped file | **Required.** Shared HMAC secret between the backend and the sandbox spawner: the backend signs every spawner call with it, and the spawner rejects unsigned ones. The spawner refuses to start without it — it holds the host docker socket, so there is no unsigned mode. `tale init` and `bun run dev` mint it; a stack you compose yourself sets it (`openssl rand -hex 32`) before the first boot. Rotating it means restarting the backend and the spawner together — they must agree. |
| `SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD` | unset | **Required for sandbox harness turns.** Gateway management credential used by the backend to provision session keys. Give the gateway the same value: a gateway without an admin account creates one only for a caller that presents it, which is how the backend claims the gateway on first use. The gateway image always uses this value as its setup token (`BIFROST_SETUP_TOKEN`) and replaces one set on the container. The gateway then retains a password hash in `llm-gateway-data`. Keep the matching secret or use the gateway’s supported credential recovery/rotation procedure. Do not wipe its state as routine recovery. The username defaults to `admin` (`SANDBOX_LLM_GATEWAY_ADMIN_USERNAME`). |

Replace the values that ship in `.env.example` before exposing the instance — they are intentionally insecure placeholders.

## Database

Tale keeps two databases: the operational store (`tale_app` — agents, runs, the audit log) and the knowledge corpus (`tale_knowledge` — document chunks, embeddings, crawled pages). A production stack folds both into one ParadeDB service (`db`, port 5432, aliased `knowledge-db`). Both share `DB_PASSWORD`, and the corpus can be pointed at external infrastructure on its own.

| Name                                      | Default                                                             | Description                                                                                                                                                                                                                                                                               |
| ----------------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DB_PASSWORD` | `tale_password_change_me` | **Required for bundled Postgres.** Password shared by the application and knowledge databases in the packaged layout. Replace the example value before production. |
| `DATABASE_URL`                            | constructed from `DB_PASSWORD`                                      | **Optional.** Connection URL for the operational database. Set it to point the backend at a Postgres of your own; it needs no extensions and no superuser, only a database and a role that may create schemas. Read on every start.                                                       |
| `DATABASE_POOL_MAX` | `10` | **Optional.** Maximum connections in each operational database pool. Each `backend-api` or `backend-worker` replica normally needs up to twice this value (app pool plus job queue). Sandbox lifecycle operations can temporarily add one connection per occupied app-pool slot, for a peak of three times this value per replica. Count that peak against the database’s `max_connections`. |
| `POSTGRES_CA_FILE`                        | unset                                                               | **Optional.** Path to a PEM bundle trusted for **every** Postgres connection: the operational database, the knowledge corpus, and the databases organizations bring themselves. Needed whenever a URL asks for `sslmode=verify-ca` or `verify-full` against a provider whose root is not one Node ships (Amazon RDS is the common one). Concatenate several roots into one file if your databases use different providers. |
| `KNOWLEDGE_DATABASE_URL` | `postgresql://tale:${DB_PASSWORD}@knowledge-db:5432/tale_knowledge` | Connection URL for the default knowledge corpus. Pointing it elsewhere selects another database; it does not migrate existing chunks or vectors. |
| `KNOWLEDGE_DB_POOL_MAX` | `10` | **Optional.** Connections one backend process opens to the knowledge corpus. Every indexing job holds one while it commits a slice of chunks, so a worker allowed more concurrent jobs than this (`WORKER_CONCURRENCY`) queues on the pool — raise the two together. Like `DATABASE_POOL_MAX`, it counts per replica against the corpus database's `max_connections`. |
| `KNOWLEDGE_DB_NAME` | `tale_knowledge` | Name of the knowledge database created by the bundled database initialization. |
| `KNOWLEDGE_INDEX_REPAIR_INLINE_MAX_BYTES` | `1073741824`                                                        | **Optional.** Largest BM25 search index (in bytes) the backend rebuilds synchronously at boot when it finds it corrupted; a larger one is rebuilt by a background job while writes to that corpus are refused. See [Container architecture](https://docs.tale.dev/self-hosted/operate/container-architecture). |
| `KNOWLEDGE_INDEX_REPAIR_DISABLED` | unset | `1` or `true` disables automatic boot-time BM25 verification and repair. It does not fix corruption; failed queries or writes need investigation and a controlled repair. |
| `KNOWLEDGE_CRAWL_DOCUMENT_MAX_BYTES` | `104857600` | **Optional.** Largest document (PDF, DOCX, XLSX, PPTX, ODT — in bytes) the website crawler downloads and extracts; a larger one is recorded on its page as too large to fetch. HTML pages have their own 2 MiB budget. Every fetch is held in memory while its text is extracted, and up to five sites scan at once, so size the backend's memory with it. A value below 1 MiB, or not a whole number, falls back to the default. |

The auto-constructed operational form is `postgresql://tale:${DB_PASSWORD}@db:5432/tale_app` (override the database name with `APP_DB_NAME`). The knowledge corpus lives in `tale_knowledge` with the `private_knowledge` and `public_web` schemas. These variables set the deployment defaults every organization shares; an organization can additionally point its own corpus and its own bucket at infrastructure of its own under **Settings > Data residency** (per-organization files, applied live, no restart), covered in [Data residency](https://docs.tale.dev/self-hosted/configuration/data-residency).

Two things to know before pointing either database at infrastructure of your own:

- **The knowledge corpus needs `pgvector` installed.** Tale creates its schemas and tables on a database that starts empty, but it never installs extensions — the chunk table has a `vector` column, so `CREATE EXTENSION vector;` has to have been run on the target database first. ParadeDB's `pg_search` is optional: without it, search degrades to vector-only rather than failing. The operational database needs no extensions at all.
- **Use a direct or session-compatible Postgres connection.** Job notifications, migration locks, and prepared statements need session semantics. Validate any managed connection proxy against those requirements.

## Object store

Files and media use S3-compatible storage. These variables configure the deployment default. An organization’s explicit connection takes precedence; an unavailable default does not imply that every organization’s own bucket is unavailable.

| Name                             | Default                        | Description                                                                                                                                                             |
| -------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OBJECT_STORE_ACCESS_KEY` | unset | Access key for the deployment’s default S3 connection. For bundled MinIO, configure the same value as `MINIO_ROOT_USER`. Missing credentials do not create a default connection; an organization can still have its own valid connection. |
| `OBJECT_STORE_SECRET_KEY` | auto-generated by `tale init` | Secret key for the default store. For bundled MinIO, it must match `MINIO_ROOT_PASSWORD`. Rotate the store and backend credentials together and verify reads and writes; changing a password does not migrate or inherently orphan blobs. |
| `OBJECT_STORE_BUCKET`            | `tale-blobs`                   | Bucket blobs are stored in. Created if it is absent and the key is allowed to; an existing bucket is used as it is.                                                     |
| `OBJECT_STORE_ENDPOINT` | `http://object-store:9000` in the shipped compose | Backend endpoint for the store. AWS S3 uses no custom endpoint; remove or explicitly clear the bundled endpoint in your effective Compose environment. Set a custom URL for MinIO, R2, or another compatible service. |
| `OBJECT_STORE_REGION`            | `us-east-1`                    | Signing region. Meaningful for AWS; arbitrary but required by the signer for a self-hosted store.                                                                       |
| `OBJECT_STORE_FORCE_PATH_STYLE`  | `true` with an endpoint, `false` without | Address the bucket as `endpoint/bucket/key` rather than `bucket.endpoint/key`. The default follows the endpoint, which is right for both the self-hosted case and AWS; set it only for a store that disagrees with its own shape. |
| `OBJECT_STORE_PREFIX`            | unset                          | Key prefix inside the bucket, so Tale's blobs can share a bucket with other data. Empty means the bucket root.                                                          |
| `OBJECT_STORE_PUBLIC_ENDPOINT`   | `${SITE_URL}` (set by the CLI) | Where the **browser** reaches the store. The proxy publishes the bundled store at `/<bucket>/*` and forwards presigned URLs verbatim, so uploads and downloads run browser↔store directly. When this endpoint is one of the deployment's origins, a link for a browser on another configured origin is signed for that origin. Leave it unset for a bucket the browser can already reach. |

The packaged proxy exposes the bundled store’s object route to browsers without publishing the store’s administration port. An external store can be reached directly through its configured public endpoint.

### How these variables reach the running deployment

At startup, the backend reconciles `default/object-storage/connection.json` with its environment. Apply changed values by recreating `backend-api` and `backend-worker`. The startup messages identify these outcomes:

| Line | Meaning |
| --- | --- |
| `object store (seeded)` | there was no connection; one was written from the environment |
| `object store (reconciled)` | the environment changed; the connection was updated to match |
| `object store (adopted)` | a connection written by an older release was recognised and is now kept in step |
| `object store (ignored)` | the connection is marked `"managedBy": "operator"`, so these variables do nothing |
| `object store (skipped)` | No credential pair was supplied to create a deployment default. Check whether a usable existing or organization connection remains. |
| *(nothing)* | already in step — the steady state |

To manage the store by hand instead, set `"managedBy": "operator"` in `connection.json`; the backend then never touches that file. A file with no `managedBy` at all — written before this behaviour existed — is taken over only if it still names the same bucket at the same endpoint the environment does; if you had repointed it by hand, that edit is kept.

Bucket permissions: the backend checks the bucket exists (`HeadBucket`) and creates it only if it does not. A key that may read, write and delete objects but not create buckets is therefore fine, as long as you create the bucket yourself. Presigned uploads and downloads run in the browser, so an external bucket also needs a CORS policy allowing your deployment's origin with `GET`, `PUT` and `HEAD` — see [Data residency](https://docs.tale.dev/self-hosted/configuration/data-residency).

## Audit log privacy

A pepper pseudonymizes personal data recorded after failed sign-ins. Earlier releases also generated `TALE_AUDIT_SIGNING_KEY` and `TALE_AUDIT_SIGNING_KEY_PREVIOUS`. Nothing reads either, so you can keep or delete an existing value.

| Name                              | Default                       | Description                                                                                                                                                                                                                                                                                                                                                                  |
| --------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TALE_AUDIT_PEPPER` | auto-generated by `tale init` | At least 16 characters for failed-sign-in pseudonymization: HMAC-SHA256 of email and truncated IP address. Without it, these audit fields retain plaintext values and the backend warns. Rotation breaks correlation with earlier identifiers; retention follows each organization’s applied policy. |

See [Audit log integrity](https://docs.tale.dev/self-hosted/operate/security/audit-log-integrity) for the verification model.

## Observability

| Name                        | Default | Description                                                                                                                            |
| --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `SENTRY_DSN`                | unset   | Sentry DSN for error tracking. Leave unset to disable. Compatible with self-hosted GlitchTip and Bugsink.                              |
| `SENTRY_ENVIRONMENT` | unset | Shared reporting label for browser, backend and sandbox events. Managed deployments default to their retained `name`; an explicit environment reference can select a canonical label without renaming the deployment. |
| `SENTRY_TRACES_SAMPLE_RATE` | unset | Optional sample rate for browser performance traces (`0.0`–`1.0`); independent of backend sampling. |
| `BACKEND_SENTRY_TRACES_SAMPLE_RATE` | `0` | Backend HTTP and worker span sample rate (`0.0`–`1.0`). Requires `SENTRY_DSN` and a destination accepting Sentry transactions; `0` disables spans. |
| `METRICS_BEARER_TOKEN` | unset | Bearer token for the proxy’s `/metrics/*` routes. Without a configured token they return 401. Internal process endpoints remain a separate network-access concern. |
| `UMAMI_URL` | unset | HTTPS origin of the authenticated collector gateway. HTTP is accepted only for local testing on `localhost`, `127.0.0.1` or `[::1]`. Requires a valid website ID and proxy token; no path, query or credentials in this URL. |
| `UMAMI_WEBSITE_ID` | unset | Umami website UUID. Unset or invalid disables aggregate analytics; use a separate ID for each deployment. |
| `UMAMI_PROXY_TOKEN` | unset | Server-only bearer token for the collector gateway: 16–256 ASCII letters, digits or characters from `._~-`. Never inject it into browser configuration. |

Setting `METRICS_BEARER_TOKEN` exposes the metrics endpoints behind the token: `/metrics/platform`, `/metrics/backend` (the application backend's metrics), and `/metrics/sla-rules`. See [Observability config](https://docs.tale.dev/self-hosted/configuration/observability-config) for the scrape config.

## Provider secrets encryption

SOPS protects supported configuration secret sidecars. Current provider credentials in the database use `ENCRYPTION_SECRET_HEX`, listed with the security secrets above.

| Name | Default | Description |
| --- | --- | --- |
| `SOPS_AGE_KEY` | unset | One inline private age key. Takes precedence over the key-file setting. |
| `SOPS_AGE_KEY_FILE` | unset | Path visible to the consuming process, containing one or more private age keys, one per line. Mount the file into each container that needs it. |

Without an age key, the SOPS helper writes supported sidecars as plaintext at mode `0600`; existing encrypted files still require their key. Read [Secrets with SOPS](https://docs.tale.dev/self-hosted/configuration/secrets-with-sops) before changing either variable.

Provider credentials may instead reference a variable under `TALE_PROVIDER_KEY_` (maximum name length 40). Subscription-broker credentials use the separate `TALE_TOKEN_SOURCE_` prefix (maximum 60). These fields store variable names, not secret values. Inject values into the backend processes and recreate the consumers when values change. [Providers](https://docs.tale.dev/self-hosted/configuration/providers) describes this setup.

## Connector OAuth apps

OAuth connectors (Gmail, Google Drive, Outlook, Teams, Slack, …) resolve their vendor app per organization first: an app configured under **Settings > Connectors > OAuth apps** wins for that org. The environment supplies the deployment-wide default underneath (and is the only source for Slack, whose inbound event verification runs before any org is known). For each connector slug:

| Name                                   | Default | Description                                                                                             |
| -------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------- |
| `CONNECTOR_OAUTH_<SLUG>_CLIENT_ID`     | unset   | OAuth client ID for that connector. Slug is upper-cased with dashes as underscores (`gmail` → `GMAIL`). |
| `CONNECTOR_OAUTH_<SLUG>_CLIENT_SECRET` | unset   | Matching client secret.                                                                                 |
| `CONNECTOR_SLACK_SIGNING_SECRET`       | unset   | The Slack app's signing secret. The inbound Events endpoint verifies every delivery with it and answers 503 while it is unset. |

Register `${SITE_URL}${BASE_PATH}/api/connectors/oauth2/callback` on the vendor app, and for Slack also `${SITE_URL}${BASE_PATH}/api/connectors/slack/events` as the Events Request URL. Details: [Connectors (develop)](https://docs.tale.dev/develop/connectors).

## Knowledge cloud import (Documents)

Per-user OneDrive / Google Drive authorizations for **Knowledge → Documents** are separate from org connectors and from login. An org-level app configured under **Settings > Connectors > OAuth apps** takes precedence here too — the **google-drive** entry is shared with the connector lane, and **OneDrive / SharePoint (Knowledge import)** has its own entry. The chains below resolve wherever the org has not configured one. Register this redirect URI on the Microsoft (or Google) app:

`${SITE_URL}${BASE_PATH}/api/cloud-import/oauth2/callback`

Credential resolution for OneDrive (first match wins):

| Name                                           | Description                                 |
| ---------------------------------------------- | ------------------------------------------- |
| `CLOUD_IMPORT_MICROSOFT_CLIENT_ID` / `_SECRET` | Dedicated Knowledge import app (preferred). |
| `CLOUD_IMPORT_MICROSOFT_TENANT_ID`             | Directory (tenant) ID for that app.         |
| `AUTH_MICROSOFT_ENTRA_ID_ID` / `_SECRET`       | Login Microsoft app.                        |
| `AUTH_MICROSOFT_ENTRA_ID_TENANT_ID`            | Directory (tenant) ID for the login app.    |

Single-tenant Entra app registrations must use a tenant-specific authorize URL — `/common` fails with AADSTS50194. Set the tenant ID (or `organizations` / `common` for a multi-tenant app). When unset, Tale falls back to the org's Entra SSO issuer tenant if configured.

The Microsoft consent screen requests Graph **Files.Read** and **Sites.Read.All** (list/download OneDrive and SharePoint), **User.Read** (account label), and **offline_access** (refresh token for sync). That grant is intentional and per user — it is not attached by signing in to Tale.

Google Drive uses a dedicated app only (no login-app fallback):

| Name                                              | Description                        |
| ------------------------------------------------- | ---------------------------------- |
| `CLOUD_IMPORT_GOOGLE_DRIVE_CLIENT_ID` / `_SECRET` | Knowledge Google Drive import app. |

Register the same cloud-import callback URI on the Google OAuth client. Consent requests **drive.readonly** and **userinfo.email**.

## Feature flags

These variables configure backend authentication, file events, and operator permissions. Recreate the consuming backend roles when their environment changes; changing only the web container is insufficient.

| Name                              | Default                  | Description                                                                                                                                                                                                           |
| --------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TRUSTED_SECRET_HEADER` | `Remote-Internal-Secret` | Name of the request header that carries the organization's trusted-header key on the hand-off request. |
| `TRUSTED_EMAIL_HEADER`            | `Remote-Email`           | Name of the request header carrying the user's email — the identity the session is minted for.                                                                                                                        |
| `TRUSTED_NAME_HEADER`             | `Remote-Name`            | Name of the request header carrying the display name. Falls back to the local part of the email.                                                                                                                      |
| `TRUSTED_ROLE_HEADER` | `Remote-Role` | Name of the request header carrying the organization role the session acts with, capped at the organization's ceiling (`member` when the header is absent). |
| `TRUSTED_TEAMS_HEADER`            | `Remote-Teams`           | Name of the request header carrying team memberships as comma-separated team names (`id:name` entries are accepted too). Absent = teams untouched; present = the proxy's list is authoritative for the memberships it granted (empty revokes them). |
| `TALE_FILE_EVENTS`                | `false`                  | Streams config-file changes under `TALE_CONFIG_DIR` to open browser tabs (`/events/file`), so an agent, skill, or branding file edited on disk shows up without a reload. On in the dev compose, off in production.   |
| `TALE_DEPLOYMENT_CONFIG_ADMINS`   | unset                    | Comma-separated email allowlist of operators allowed to write the deployment config file (`deployment.yml`, today the sandbox runtime section) through the API. Empty/unset = read-only for all admins. Data residency is configured per organization and is not gated by this list. |
| `TALE_ALLOW_PRIVATE_PROVIDER_HOSTS` | unset | Set to `1` in the backend environment to admit private model-provider destinations, including their sandbox gateway configuration. Cloud-metadata targets remain blocked. See [Providers](https://docs.tale.dev/self-hosted/configuration/providers). |
| `TALE_ALLOW_PRIVATE_CRAWL_HOSTS` | unset | Set to `1` to admit intranet crawl targets and private product `imageUrl` hosts. Cloud-metadata targets remain blocked. |
| `TALE_ALLOW_OPEN_SIGN_UP` | unset | Set to exactly `true` to keep `POST /api/auth/sign-up/email` open after the deployment's first account. For throwaway test stacks only — the local dev orchestrator and the dev compose overlay set it themselves. A real deployment leaves it unset, so an administrator creates every account after the first. |
| `TALE_ORGANIZATION_CREATORS` | unset | Comma-separated email allowlist of the accounts that may create an organization, matched case-insensitively. Unset, every signed-in user may create one. Set, every other user is refused with `403 ORGANIZATION_CREATION_FORBIDDEN` once the deployment holds an organization — the first one is always allowed — and the app hides **Create organization** from them. A set but empty value closes creation to everyone. A managed deployment writes it from `organizations.creators` in its specification; see [Install the tale CLI](https://docs.tale.dev/self-hosted/install/cli-install#managed-organization-creators). |

The private-crawl opt-in affects two boundaries: website registration and crawler requests, and validation of a product’s `imageUrl`. Without it, a private website target returns `400 WEBSITE_DOMAIN_NOT_CRAWLABLE`; a private product image URL returns `400 INVALID_BODY`. Product validation checks the hostname string without fetching the image or resolving DNS. Website registration and crawling also check resolved addresses. Enable the flag only for a deployment that needs these private destinations; it is separate from the private-provider flag.

## Deployment topology

These values shape the application roles of a workspace deployment: the replica counts, which `tale deploy` reads from the project environment and clamps to the supported range with a warning, and how much work one worker replica takes on at once.

| Name                           | Default | Description                                                                                              |
| ------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------- |
| `TALE_PLATFORM_REPLICAS`       | `1`     | Replicas of the web tier that serves the app shell. Range `1`–`16`.                                       |
| `TALE_BACKEND_API_REPLICAS`    | `1`     | Replicas of the API — every application door, auth, and the hint stream. Range `1`–`16`.                  |
| `TALE_BACKEND_WORKER_REPLICAS` | `1`     | Replicas of the job runner: ingestion, crawls, automations, agent turns. Range `1`–`16`.                  |
| `WORKER_CONCURRENCY`           | `5`     | Jobs one `backend-worker` replica runs at once on each job queue — ingestion, crawls, automations and agent turns each get this many. Agent turn starts get at least 8 and the drive windows of live agent turns at least 16 per queue, since each one mostly waits on its sandbox (`AGENT_START_SLOTS`, `AGENT_DRIVE_SLOTS`). Read by the worker process itself; range `1`–`64`. The lever to pull before adding worker replicas when a backlog lags. Every running indexing job commits through the knowledge pool, so raise `KNOWLEDGE_DB_POOL_MAX` with it. |
| `AGENT_START_SLOTS` | `WORKER_CONCURRENCY`, at least `8` | Agent turn starts one `backend-worker` replica runs at once, for task runs and for automation steps each. A start holds its slot through the sandbox create and the turn's first 90-second window. Range `1`–`256`. |
| `AGENT_DRIVE_SLOTS` | `WORKER_CONCURRENCY`, at least `16` | Drive windows of live agent turns one `backend-worker` replica runs at once, per lane. A replica keeps about 2.5 times this many live turns per lane drained; past that, windows wait long enough for recovery to step in, so raise it (or add replicas) for more turns at once. Range `1`–`256`. |
| `TALE_BACKEND_URL` | `http://backend-api:3005` | Where the web tier reaches the application backend: the public `/status` page probes it and the web server asks it for the answers only a database can give. The shipped compose and the container entrypoint default it to the in-compose alias; set it only when your backend service has another name. Read by the `platform` service only. |

A workspace rollout temporarily runs both colors. Plan capacity for that overlap. Increase the role whose measured workload is the bottleneck; more replicas also increase database connections and memory use. See [Upgrades](https://docs.tale.dev/self-hosted/operate/upgrades).

## Sessions

| Name                           | Default | Description                                                                                                                                                                                              |
| ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SESSION_IDLE_TIMEOUT_MINUTES` | unset   | **Optional.** Sign a session out after this many minutes of inactivity (`1`–`1440`). The window slides on activity and is enforced server-side across email/password, SSO, and trusted-headers sessions. |

Leave it unset to keep the default session lifetime. When set, an idle session expires server-side once the window elapses, while an active one keeps sliding forward on each request. Org admins can tighten the effective window per organisation — never loosen it past this cap — via the [session idle timeout governance policy](https://docs.tale.dev/platform/admin/governance/policies-and-limits); idle sessions under that policy are revoked by a sweep that runs about every five minutes.

## Support link

| Name                       | Default                    | Description |
| -------------------------- | -------------------------- | ----------- |
| `TALE_CONTACT_SUPPORT_URL` | `https://tale.dev/contact` | **Optional, read by the `platform` service.** Where the **contact support** link on the app's error screens points. An absolute `http://` or `https://` URL. |

Set it to your own help desk so people who hit an error reach the team that runs your deployment. Where the error screen knows the organization, the link adds `organizationId=<id>` to the query string, after any query the URL already carries, and replaces an `organizationId` the URL already has. Any other value, such as `mailto:` or a URL without a scheme, is ignored with a warning in the `platform` service's log, and the link keeps the default.

## Sandbox infrastructure

The sandbox spawner reads the settings below. Pass them into its environment and recreate that service after a change. `SANDBOX_MAX_SESSIONS` sets the capacity shared by all organizations; an organization's three workload limits add up automatically and cannot be saved above that capacity. Manage those limits in [Sandboxes](https://docs.tale.dev/platform/admin/sandboxes), where actual runtime counts and host measurements appear separately from workload allocations.

| Name | Default | Description |
| --- | --- | --- |
| `SANDBOX_MAX_SESSIONS` | sized from host memory on a local Docker host (at least `8`, at most `256`); `8` elsewhere | Maximum running and starting sessions across all organizations on the Docker host or in the Kubernetes namespace, including idle containers kept for reuse. This capacity does not reserve CPU or memory. Unset on a Docker host whose memory the spawner can read, it is sized from that memory: one session per 768 MiB left after `SANDBOX_MIN_FREE_MEMORY`, or per 1.5 GiB where agent sessions run Docker inside the sandbox. If the memory cannot be read at start, the capacity stays `8` until it can. An explicit value fixes it. Concurrent Kubernetes replicas enforce it on a best-effort basis; use ResourceQuota for hard namespace resource bounds. |
| `SANDBOX_MIN_FREE_MEMORY` | a tenth of host memory, at least `1g` | Memory a new session or a released warm session resuming work must leave free on a local Docker host, beside what the sessions still starting or just started are about to use. A create that would leave less first stops a released idle session; if memory is still short, the spawner answers busy and the work waits until running sessions free some. Accepts sizes such as `2g` or `1536m`. Has no effect on Kubernetes or with a remote Docker daemon. |
| `SANDBOX_MIN_FREE_DISK` | a twentieth of each disk, at least `2g`, at most `20g` | Free space required for new and reactivated sessions on the workspace filesystem and the verified Docker data filesystem. Below the floor work waits; stopped unused build caches are reclaimed first. Accepts `10g` or `4096m`; `0` disables the check. Kubernetes relies on its storage class and volume provisioning. |
| `SANDBOX_DOCKER_WORKLOADS` | `project,workflow` | Workloads allowed to use inner Docker when it is enabled for the deployment. Set `project` to allow Docker only for project agents, `workflow` only for workflow agents, or `none` to disable both. Applies to newly created sessions; existing sessions keep their capabilities. A session request can opt out with `docker: false`, but cannot enable Docker beyond this allowlist or the deployment setting. |
| `SANDBOX_AGENT_CPUS` | `2` | CPU limit per agent session. Account for overlapping builds and other host workloads when choosing the session count. |
| `SANDBOX_AGENT_MEMORY` | `4g`; `8g` with Docker inside the sandbox | Memory limit per agent session, shared with its inner Docker daemon and nested containers. An explicit value overrides either default and applies to newly created sessions. |
| `SANDBOX_AGENT_PROFILE` | `agent` | Read by the backend API and worker. Profile for new agent and workflow workspaces: `agent` supports inner Docker; `agent-light` keeps coding tools and the persistent workspace without starting Docker or build-cache helpers. Existing workspaces retain their recorded profile. |
| `TALE_SANDBOX_CLAUDE_EFFORT` | unset (inherits the harness default) | Read by the backend API and worker. Claude Code reasoning effort: `low`, `medium`, `high` or `max`. Lower settings omit the automatic Ultrathink instruction and set the per-exec effort, while keeping adaptive thinking enabled. Other harnesses and foreign models are unaffected. Compare representative tasks before lowering it; shorter runs are not guaranteed. |
| `SANDBOX_SESSION_CREATE_TIMEOUT_MS` | `180000` | Total session startup budget, including optional build-cache setup, container or Pod startup, daemon readiness and environment delivery. A cancelled request aborts its session startup work; cleanup stops compute while preserving the workspace. Shared cache provisioning has its own bounded lifetime. |
| `SANDBOX_DOCKER_DATA_ROOT` | unset | Optional host path matching Docker's `DockerRootDir`. The CLI adds a read-only bind mount to the sandbox service when configured. Raw Compose requires the mount shown below. |
| `SANDBOX_DOCKER_DATA_PATH` | `/var/lib/tale-sandbox/docker-data` when the root is configured | Location of that read-only mount inside the spawner. Admission checks this filesystem as well as the workspace filesystem. A configured mount that cannot be verified or read blocks admission. |
| `SANDBOX_BUILDKITD_CPUS` | `SANDBOX_AGENT_CPUS` | CPU limit of an organization's build-cache helper, which runs the image builds of all its agent sessions when Docker runs inside the sandbox. A running helper takes a new value at once. The number of concurrent BuildKit solver steps is this CPU limit rounded down, with a minimum of one; this bound takes effect when an idle helper is recreated. |
| `SANDBOX_BUILDKITD_MEMORY` | twice `SANDBOX_AGENT_MEMORY` | Memory limit of an organization's build-cache helper, shared by the builds its agent sessions run at the same time. Accepts sizes such as `16g` or `12288m`. A running helper takes a new value when it is recreated, once no build is running. |
| `SANDBOX_BUILDKITD_IDLE_CACHE` | `5g` | Build cache an organization's build-cache helper keeps when it stops for want of agent sessions. Right before that stop, the spawner prunes the cache down to this size, least recently used first: the cache's own garbage collection runs only while the helper runs. Accepts sizes such as `5g` or `2048m`; `0` keeps nothing. |
| `SANDBOX_BUILDKITD_PROVISION_TIMEOUT_MS` | `5000` | Total time in milliseconds for optional shared build-cache setup during session creation, including queued Docker calls and registry mirrors. Range `100`–`60000`. When the shared setup budget expires, queued helper work is cancelled and cannot launch later; the session falls back to its local builder. |
| `SANDBOX_BUILDKITD_CACHE_RETENTION` | `14d` | How long an organization's stopped build-cache helpers keep their caches. Once the builder has been stopped longer than this and no session of the organization may use it, the spawner removes its helpers, network and cache volumes, as an organization's deletion does; its next build starts cold. Accepts whole days or hours such as `14d` or `336h`; `off` (or `0`) keeps the caches until the organization is deleted. |
| `SANDBOX_SESSION_MAX_IDLE_MS` | `1800000` (30 min) | Idle window for stopping unpinned sessions. Organization build-cache helpers also stop after this window with no potentially active organization session; their networks and cache volumes are retained. |
| `SANDBOX_SESSION_RELEASED_IDLE_MS` | `300000` (5 min) | Idle window for a released session: one whose task or run has finished and that no other work holds. An unpinned released session idle this long is stopped instead of waiting out `SANDBOX_SESSION_MAX_IDLE_MS`; the next turn resumes it on its preserved workspace. Agent sessions with Docker inside the sandbox keep the full idle window, because each resume starts their inner Docker daemon with an empty image store. |
| `SANDBOX_RUNTIME_IMAGE`          | `tale-sandbox-runtime:latest` | **Optional, read by the spawner.** The image every session container is created from. The default is the tag the development stack builds locally, so a host that pulls its images sets the registry one: `ghcr.io/tale-project/tale/tale-sandbox-runtime:<version>`, matching the rest of the stack. `tale deploy` sets it for you. |
| `SANDBOX_DIND_INNER_POOL` | unset (automatic) | Optional inner Docker address pool for agent sessions on Docker or Kubernetes. Use a canonical RFC1918 IPv4 `/16` outside your Pod, Service and VPC networks. The runtime rejects overlaps with networks and addresses it discovers. |
| `SANDBOX_EGRESS_MAX_CLIENTS` | `2000` | **Read by the `sandbox-egress` service**, not the spawner: recreate that service after a change. Connections the egress proxy serves at once for all sessions together; with transparent egress, every outbound connection of a session, its builds and its package installs goes through it. Past the limit the proxy refuses new connections, and installs and page loads fail with connection resets. Each connection takes a thread and two open files, so the shipped compose files size the proxy's process and open-file limits for the default; a higher value needs them raised too, and the proxy warns at start when its open-file limit is too low. At start the proxy raises its open-file limit to what the connections need, as far as the container's hard limit allows. On Kubernetes, set it on the egress Deployment; a Pod spec sets no process limit, so the node's `podPidsLimit` must leave room for one thread per connection. |

The backend settings above must reach both API and worker services. Recreate them after a change. The spawner checks memory and disk headroom when a released session is acquired again, so a warm workspace can wait for capacity too.

Connected devices apply the same local-host memory and disk admission checks while keeping their configured session ceiling.

An intentionally stopped Docker daemon remains ready for its next command; health checks do not start it. A failed health probe immediately refuses new work but does not by itself stop the session. Probe-based recovery needs at least three completed failures spanning five seconds; a healthy result or a new engine clears that failure history. A confirmed startup failure or unexpected engine exit can trigger recovery immediately. The spawner can then stop an idle, unpinned session after an atomic activity check, keeping the workspace for the next start. On Docker, stopping the whole session removes its inner Docker store; stopping only the idle inner engine preserves it. Busy or pinned sessions stay in place and refuse new starts until Docker recovers or an operator resolves the fault.

During a rolling upgrade, keep old spawners pinned to their existing runtime image until they are replaced. Do not move a runtime tag still used by an old spawner: it does not distinguish transient probe failures from confirmed failures. A new spawner with an older runtime refuses unhealthy new work and keeps the normal idle and lifetime cleanup limits.

A containerized spawner automatically checks Docker’s data filesystem when it can verify its existing `/etc/hostname` mount against the daemon. If discovery is unavailable, workspace admission remains active and `/health` reports Docker disk monitoring as `unavailable`. An explicit read-only data-root mount takes priority; if it cannot be verified or read, admission waits until it is available. To configure one, inspect `docker info --format '{{.DockerRootDir}}'` and use that actual host path. Docker Desktop and remote daemons may need a different setup. For raw Compose, add the following override and pass both variables into the sandbox service:

```yaml
services:
  sandbox:
    environment:
      SANDBOX_DOCKER_DATA_ROOT: ${SANDBOX_DOCKER_DATA_ROOT}
      SANDBOX_DOCKER_DATA_PATH: /var/lib/tale-sandbox/docker-data
    volumes:
      - ${SANDBOX_DOCKER_DATA_ROOT}:/var/lib/tale-sandbox/docker-data:ro
```

A disk floor is admission control, not a per-session storage quota. Docker named volumes have no portable size limit, and a Kubernetes PVC size request depends on its storage backend for enforcement. For hard quotas, use a quota-capable filesystem or storage class. Separately mounted containerd stores, volume directories and external volume drivers need their own monitoring, alongside workspaces, image layers and build caches.

Kubernetes sessions use `/readyz` for startup and `/livez` for daemon liveness. Startup accepts an intentionally stopped inner Docker engine as ready; an engine that is running must respond to its health probe. Liveness checks only the sandbox daemon, so dependency failures do not restart busy sessions. A wedged daemon can restart even when its session is pinned. Docker and egress diagnostics appear in `/healthz`.

An already active generation is not charged again. A workflow without inner Docker keeps its agent identity and tools, but starts no Docker daemon and does not keep build-cache helpers alive. Without an explicit `SANDBOX_AGENT_MEMORY`, each session defaults to `4g` without inner Docker or `8g` with it, even when other sessions in the deployment use Docker. An explicit value applies to both modes. These limits are ceilings, not reserved RAM.

At full capacity, the spawner can stop a released, unpinned idle session before the idle timeout to admit new work, starting with the one idle longest. The daemon must confirm that no work is in progress; busy sessions and sessions with unknown state are protected. Stopping compute preserves the persistent workspace directory or volume. If no safe session can be reclaimed, admission remains blocked by the deployment capacity. The same applies when the host's free memory would drop below `SANDBOX_MIN_FREE_MEMORY`. While the disk that holds the session workspaces is below `SANDBOX_MIN_FREE_DISK`, new work waits without stopping idle sessions: a stopped session keeps its workspace.

Harness protocol records, including unfinished lines, are limited to 8 MiB. Oversized or incomplete output fails explicitly; a bounded progress preview is never treated as a complete structured result. Complete final answers are retained separately from that preview.

Reacquiring a released warm session checks the same memory reserve and reserves its expected working set before resuming work. Concurrent resumes share that accounting. A busy response is retryable; it does not destroy the workspace or interrupt a session that already holds work. These reservations do not cap the later growth of active tools or organization builders.

When Docker is enabled inside agent sandboxes, the engine starts automatically on the first Docker command. Agents do not choose a mode. After five minutes without connected clients, it stops only if no container is running, restarting or paused and every container has its restart policy disabled; an unknown state keeps it running. The next command restarts it with the same images, volumes and workspace. Existing container metadata at session-container boot starts the engine immediately so restart policies still work. This does not change the deployment's runtime isolation, privileges or memory limits.

### Size session capacity

On a Docker host with `SANDBOX_MAX_SESSIONS` unset, the spawner sizes the capacity from the host's memory (a 16 GiB host gets 19 sessions, a 64 GiB host 76; 9 and 38 where agent sessions run their own Docker daemon) and admits a new session only while the host keeps `SANDBOX_MIN_FREE_MEMORY` free, counting what the sessions still starting or just started are about to use. A burst of new sessions that would overcommit the host therefore waits instead of starting; the check does not stop sessions already running from growing. Set the capacity yourself on Kubernetes, with a remote Docker daemon, or when the host also runs other heavy workloads: test the tasks your deployment will run together. Browser rendering and Docker builds have different peaks; include agents, workflows and crawling across all organizations. A free session slot does not guarantee enough resources.

On Docker, sample resource use while representative tasks overlap. Repeat this command during the run; an idle snapshot does not show task peaks:

```bash
docker stats --no-stream --format 'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}'
```

Subtract the operating system, platform services, databases, build-cache helpers and a safety margin from host memory. Divide the remaining memory by the measured peak per active session and round down. For example, a 32 GiB host with 8 GiB set aside and a measured peak of 3 GiB per session gives `(32 - 8) / 3 = 8` sessions. This is a sizing example, not a benchmark. For mixed workloads, budget their simultaneous peaks together and check CPU saturation and task duration before raising the limit.

An agent's 4 GiB or 8 GiB memory limit is a ceiling, not memory reserved at startup. Eight agents running Docker builds can therefore require much more memory than eight mostly idle sessions. Measure under representative load and keep headroom; increase capacity to 16 or higher only when the host can sustain it. Before lowering capacity, reduce any organization totals that exceed the new value. The default organization limits total 6, so a smaller deployment capacity also needs smaller organization limits.

### Apply a capacity change

Add or update this line in the deployment's `.env`, keeping its other entries. Explicit values remain in effect across upgrades; without one, a Docker host sizes the capacity from its memory as described above, and Kubernetes uses 8.

```dotenv .env
SANDBOX_MAX_SESSIONS=8
```

For a Compose stack you manage yourself, recreate only the sandbox service using its existing local image:

```bash
docker compose up -d --no-deps --no-build --pull never sandbox
```

Use the same project, `-f` files and environment-file options as the running stack. A restart alone does not load an edited `.env`. For CLI-managed installations, apply the change through the deployment workflow in [Upgrades](https://docs.tale.dev/self-hosted/operate/upgrades). On Kubernetes, set the variable on the sandbox spawner Deployment and roll out that Deployment.

Confirm the new deployment capacity in [Sandboxes](https://docs.tale.dev/platform/admin/sandboxes). With organization limits at 2/2/2 and deployment capacity at 8, the total reads **6 / 8**. Existing organization settings are preserved; saving still requires their total to fit the current capacity. Changing the capacity does not increase any container's CPU or memory limit.

### After an upgrade

The default capacity used to be 16, and organizations created before this release were seeded with limits of 2/4/4, a total of 10. A deployment that never set `SANDBOX_MAX_SESSIONS` therefore starts the new version with a capacity of 8 and organizations whose saved total exceeds it. Running work is not affected, and each organization keeps admitting work under its saved limits; only saving the Sandboxes page is blocked until its total fits, and lowering limits still saves. Either set `SANDBOX_MAX_SESSIONS=16` explicitly to keep the previous capacity, or ask each affected organization to lower one limit.

From this release, a Docker deployment that never set `SANDBOX_MAX_SESSIONS` gets a capacity sized from its host's memory instead of 8, never less than 8. It can admit more sessions at once than before, and only while the host has memory to spare. Set an explicit value to keep a fixed capacity.

### Docker build caches

Shared build-cache preparation uses `SANDBOX_BUILDKITD_PROVISION_TIMEOUT_MS` (5 seconds by default). Each session waits at most that long or one quarter of its total startup budget, whichever is shorter, then uses its local builder. Shared preparation has its own bounded lifetime; cancelling one session’s wait does not cancel setup for other sessions, and a late result does not attach to a session that already fell back. Registry mirrors are prepared concurrently. The shared builder’s parallel steps follow its configured CPU limit, rounded down with a minimum of one; its memory limit still applies. Preparation time counts against the remaining session startup budget.

Docker build caches are isolated by organization. Each organization uses one privileged builder and three unprivileged registry mirrors. Once no session may still use them, the helpers stop after the session idle window; the next build restarts them with their cache volumes intact. Right before the builder stops, the spawner prunes its cache to `SANDBOX_BUILDKITD_IDLE_CACHE`, because its garbage collection runs only while it runs. A stopped organization's cache is not pruned further; after `SANDBOX_BUILDKITD_CACHE_RETENTION` (14 days) with no build, its helpers and caches are removed, and otherwise they go with the organization. While the session disk is below `SANDBOX_MIN_FREE_DISK`, stopped organizations' caches go sooner, the longest-stopped first. Networks and volumes remain available for reuse. Kubernetes sessions use their own inner Docker builder; Kubernetes reconciliation does not invoke the Docker CLI for these helpers.

The spawner packs organization bridges into the first available Docker address pool before moving to the next. Its default `/23` gives each bridge 512 addresses; an otherwise unused `/16` holds 128 such organization networks. Smaller subnets configured in Docker’s pools remain smaller. It excludes existing Docker networks, routes and DNS server addresses on the Docker daemon’s host, and `172.31.0.0/16` for older runtime images, then validates the created network.

To observe the daemon’s host even with remote Docker, the spawner briefly runs the configured BuildKit image in the host network namespace with a read-only filesystem, all capabilities dropped and no mounts. If that observation fails or no safe subnet remains, sessions build locally without the shared cache. An unused owned network left with an invalid subnet is rebuilt; in-use and foreign networks are preserved.

Upgrades create cold organization caches and retain the old global cache data. Old helper containers stop automatically after no running session depends on them. Drain or stop old pinned sessions to complete that transition; until then the old shared cache service remains reachable. Browser automation uses headless Chromium; live browser viewing and manual browser takeover are retired.

### Inner Docker networks

On Docker and Kubernetes, automatic selection checks IPv4 routes and gateways from all routing tables, interface addresses and prefixes, DNS servers, and the resolved addresses of proxy and gateway hosts configured in the container environment at startup. Hosts supplied later during an agent turn are outside that initial observation. It also accounts for a Docker organization bridge that will attach later. The runtime prefers a free `172.31.0.0/16`, then tries other private `/16` ranges. The first `/24` serves `docker0`; inner Compose networks use `/24` blocks from that same pool. In automatic mode, failed observations or exhausted private space prevent session startup.

A Pod cannot discover the cluster’s complete Pod, Service and VPC CIDRs from its own network namespace. Set `SANDBOX_DIND_INNER_POOL` to a private `/16` you have checked against all those networks when deploying DinD on Kubernetes. An explicit pool still fails on every discovered overlap or invalid value. If some observations are unavailable, the runtime names them in a warning and can continue with the explicit pool; responsibility for the unseen address space remains with the operator.

After changing this pool, restart the spawner and recreate existing sessions to apply it. Restarting a runner container inside the same Kubernetes Pod retains that Pod’s environment and inner Docker store.

The egress proxy allows upstream DNS queries to the validated nameserver IPs in its `/etc/resolv.conf`, including private cluster DNS. Each exception covers only that exact IP and UDP/TCP destination port 53. Other private destinations and forwarding between attached networks stay blocked.

### IPv6 forwarding protection

Keep `sandbox`, `sandbox-egress` and `SANDBOX_RUNTIME_IMAGE` on the same release when upgrading. Before attaching an organization’s Docker build network, the spawner verifies the session’s forwarding protection. Compose and generated Docker session containers disable IPv6 with `net.ipv6.conf.all.disable_ipv6=1` and `net.ipv6.conf.default.disable_ipv6=1`; preserve both in custom Docker definitions.

Kubernetes Pods do not receive unsafe sysctls automatically. The egress proxy needs working IPv6 firewall support or IPv6 disabled in its network namespace. If the IPv6 firewall is unavailable, the entrypoint attempts that local disable and verifies the default and every interface. A read-only `/proc/sys` or denied write can prevent it; enabled IPv6 without protection still stops startup. Configure the egress Pod according to the cluster’s permitted networking settings before deployment.

## Sandbox devices

Organizations can run their sandboxes on their own machines, which they connect under [Settings > Sandboxes](https://docs.tale.dev/platform/admin/sandbox-devices). A device connects out over HTTPS to `<SITE_URL><BASE_PATH>/sandbox/tunnel` and keeps one WebSocket open. The bundled proxy forwards that path, and only that path, to the spawner's device hub; the spawner's signed API stays on the internal network. Devices need the Docker backend: the hub is off with Kubernetes.

| Name | Default | Description |
| --- | --- | --- |
| `SANDBOX_HUB_PORT` | `8004` | **Read by the spawner.** Port of the device hub, which answers only a ticket-authenticated WebSocket upgrade and a health check. `0` turns devices off: **Add device** is then unavailable. If you change the port, point `SANDBOX_HUB_UPSTREAM` at it too. |
| `SANDBOX_DEVICE_TUNNEL_URL` | `<SITE_URL><BASE_PATH>/sandbox/tunnel` as `wss://` | **Optional, read by the backend.** Where devices connect, when a proxy in front of Tale publishes the hub under another host or path. An `https://` address is used as `wss://`. |
| `SANDBOX_DEVICE_IMAGE_REGISTRY` | `GHCR_REGISTRY`, else `ghcr.io/tale-project/tale` | **Optional, read by the backend.** Where devices pull the sandbox images of the server's release. |
| `SANDBOX_HUB_UPSTREAM` | `sandbox:8004` | **Optional, read by the proxy.** Where the proxy forwards `/sandbox/tunnel`, when the spawner is not the `sandbox` service. |

A device always runs the server's release. It learns the release each time it renews its connection and replaces its own containers when the server moves on, unless it was connected with `--no-auto-update`. It keeps no data on the server: its workspaces stay on the machine. Sandboxes on a device call the backend's sandbox endpoints and the model gateway through the device's connection, along the same paths sessions use on the server; the gateway's management API is never reachable that way. A device keeps the backend and gateway addresses it received when it joined: after changing `SANDBOX_HTTP_API_BASE_URL` or `EXTERNAL_AGENT_GATEWAY_URL`, run `tale sandbox update` on each device.

A device must trust the site's TLS certificate. A deployment with `TLS_MODE=selfsigned` cannot take devices.

With a proxy of your own instead of the bundled one, forward `/sandbox/tunnel` to port `SANDBOX_HUB_PORT` of the spawner, keep WebSocket upgrades and the `Authorization` header intact, and allow connections that stay open for hours.

## Sandbox agent turns

| Name                             | Default              | Description                                                                                                                                                                                                                                                                                       |
| -------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TALE_EXTERNAL_TURN_DEADLINE_MS` | `1800000` (30 min)   | **Optional.** How long an in-sandbox coding-agent turn (Claude Code, OpenCode, Codex) may sit with nobody draining its output before the sandbox daemon reaps it. A sliding window, re-armed every time the platform re-attaches to the output — not an absolute cap on the turn. Milliseconds. |
| `SANDBOX_LLM_GATEWAY_STREAM_IDLE_TIMEOUT_SECONDS` | `600` (10 min) | **Optional.** How long the sandbox model gateway waits for the next byte from a silent upstream model before it aborts the stream, including while a slow local model is still processing a long prompt. The backend reads it and configures the gateway. Claude Code and Codex turns wait at least as long before they give up on a silent stream and send the request again, so you can raise it for a slow local model without either of them sending a turn twice. A stalled upstream model then also holds a turn longer before the gateway aborts it. A value above 600 also raises the gateway's per-request timeout to match: it bounds a whole non-streaming answer, which an agent falls back to when a stream breaks, and how long an upstream may take to begin a streamed answer. Seconds. |

Investigate why output consumption stopped before increasing this deadline. It limits orphaned output streams, not total task duration. Recreate the consuming backend roles after changing the environment.

## Video-link ingestion (yt-dlp)

The worker uses these values for video transcript retrieval. Its image includes yt-dlp and a PO-token plugin. Use [Video ingestion](https://docs.tale.dev/self-hosted/configuration/video-ingestion) to distinguish source restrictions, egress problems, and authorized session handling. Recreate the worker after changing deployment environment values; rereading a variable inside a process does not reload `.env`.

| Name                             | Default                               | Description                                                                                                                                                                                                                                                                                             |
| -------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VIDEO_INGEST_PROXY_URL` | unset | Proxy for yt-dlp requests. Supported schemes: `http`, `https`, `socks4`, `socks4a`, `socks5`, `socks5h`; the last resolves destination DNS at the proxy. Use an approved egress service. |
| `VIDEO_INGEST_POT_PROVIDER_URL` | `http://bgutil-provider:4416` (baked) | PO-token provider URL. Defaults to the bundled sidecar when the image plugin is present. Tokens can help retrieval but do not grant access to private content or guarantee success. |
| `VIDEO_INGEST_FETCH_POT` | `always` when a provider is wired | When to request provider tokens: `never`, `auto`, or `always`. The bundled provider path defaults to `always`. Use `never` only when deliberately disabling that token path. |
| `VIDEO_INGEST_YTDLP_PLUGIN_DIRS` | `/opt/yt-dlp/plugins` (baked)         | Directory yt-dlp loads plugins from — each plugin nested one level down (`<dir>/<name>/yt_dlp_plugins/…`). Defaults to the baked-in bgutil plugin dir when present; override only to add your own plugins.                                                                                              |
| `VIDEO_INGEST_COOKIES_FILE` | unset | Path inside the worker to a Netscape cookie file. Protect it as account credentials and use only an authorized session. The organization-scoped browser-session pool in the video guide offers managed import and revocation. |
| `VIDEO_INGEST_PLAYER_CLIENT`     | `default,tv_simply`                   | Comma-separated YouTube player-client fallback list. When a PO-token provider is wired the default widens to `default,mweb,tv_simply` (mweb needs a GVS token); set explicitly to force a list.                                                                                                         |
| `VIDEO_INGEST_PO_TOKEN`          | unset                                 | Manually pinned PO token (`CLIENT.CONTEXT+TOKEN`). Mainly for testing — tokens are video-ID-bound and short-lived; prefer the provider.                                                                                                                                                                 |
| `VIDEO_INGEST_IMPERSONATE`       | unset                                 | Browser TLS/JA3 impersonation target (e.g. `safari`). Requires `curl_cffi` in the image; leave unset unless you know it's available.                                                                                                                                                                    |
| `VIDEO_INGEST_BIN_DIR`           | unset                                 | Directory prepended to the yt-dlp/ffmpeg child's `PATH` so a self-provisioned `yt-dlp` (and its Deno runtime) installed outside the image's pinned bin dirs is found first. The backend image bakes yt-dlp into `PATH`, so leave it unset there; set it on a host or dev box running its own toolchain. |
| `VIDEO_INGEST_FFMPEG_LOCATION`   | `/usr/bin/ffmpeg`                     | Absolute path to the ffmpeg yt-dlp uses for post-processing (subtitle conversion, audio extraction). Override when ffmpeg lives elsewhere — e.g. Homebrew's `/opt/homebrew/bin/ffmpeg` on a macOS dev box.                                                                                              |

# Observability configuration
Source: https://docs.tale.dev/self-hosted/configuration/observability-config

Start with container logs and dependency health. Add Prometheus metrics for trends and alerts, and configure error reporting if you need a searchable history of failures. Tale does not send these signals to an external monitoring service unless you configure one.

## Read the application logs

Containers write logs to stdout and stderr. The shipped Compose configuration uses Docker’s `json-file` logging driver with rotation at 10 MB per file and three files per container. Use the service names from your deployment’s Compose file:

```bash
docker compose logs --tail=100 backend-api backend-worker
docker compose logs -f backend-api
```

Stop following with `Ctrl-C`; the containers keep running. Look at `backend-api` for requests, authentication, and interactive chat generation; use `backend-worker` for background jobs, queued agent turns, and ingestion. Use `docker compose ps` to find a container that is restarting.

`journalctl -u docker` shows the Docker daemon’s journal. With the default `json-file` driver, it does not replace container logs. If you use journald or a log aggregator, configure the Docker logging driver and collection separately. Tale does not include a log shipper. Changing a logging driver requires recreating the affected containers.

## Enable authenticated metrics {#metrics}

Set a strong `METRICS_BEARER_TOKEN` in the deployment environment and apply the change by recreating the affected services through your deployment workflow. A simple container restart does not reload Compose environment values. Store the same token in your monitoring system’s secret store.

The proxy requires `Authorization: Bearer <token>` for these routes. Without a configured token, requests receive **401**.

| Route | Content | How to use it |
| --- | --- | --- |
| `/metrics/platform` | Web-tier process metrics and response-time targets | Prometheus scrape target |
| `/metrics/backend` | Backend HTTP and process metrics, queue depth, active generations and drain state | Prometheus scrape target |
| `/metrics/sla-rules` | Generated recording and alerting rules in YAML | Load as a Prometheus rules file |

The backend serves knowledge requests and runs ingestion jobs. Its HTTP and queue metrics help detect failures and backlog; they are not dedicated measurements of retrieval or generation latency. `BACKEND_UPSTREAM` selects the backend target for a split deployment. It does not create a separate knowledge metrics service.

Use a separate scrape job for each metrics route. In this example, `/run/secrets/tale_metrics_token` is a file inside the Prometheus container containing only the token. Create it through your secret-management system and grant Prometheus read access.

```yaml
scrape_configs:
  - job_name: tale-platform
    scheme: https
    metrics_path: /metrics/platform
    authorization:
      credentials_file: /run/secrets/tale_metrics_token
    static_configs:
      - targets: ['tale.example.com']
  - job_name: tale-backend
    scheme: https
    metrics_path: /metrics/backend
    authorization:
      credentials_file: /run/secrets/tale_metrics_token
    static_configs:
      - targets: ['tale.example.com']
```

Do not scrape `/metrics/sla-rules` as metrics. The generated rules reference latency series that need additional instrumentation; loading the file alone does not measure response-time compliance. Review them before loading through Prometheus’s rule configuration; [Prometheus and Grafana](https://docs.tale.dev/self-hosted/operate/observability/prometheus-grafana) covers the full setup.

## Choose where errors go

`SENTRY_DSN` enables optional error reporting. It can point to Sentry or a compatible service such as GlitchTip or Bugsink. Browser, backend and sandbox use the DSN and `SENTRY_ENVIRONMENT` reporting label; server events carry the process role and release version.

```bash
SENTRY_DSN=https://your-key@your-sentry-host/project-id
SENTRY_ENVIRONMENT=example-pr
SENTRY_TRACES_SAMPLE_RATE=0.1
```

Managed deployments default the reporting label to their retained `name`. To select another label, declare `"environment": { "SENTRY_ENVIRONMENT": { "env": "TALE_REPORTING_ENVIRONMENT" } }` in the deployment specification and supply the variable at the destination. The value starts with a lowercase letter or digit and contains 1–64 lowercase letters, digits or hyphens. Deployment identity, state and stored credentials stay at their existing paths.

Sandbox errors include HTTP and background-task failures. Expected client aborts and closed SSE streams after cancellation are excluded. Sandbox reporting sends errors only; browser and backend tracing settings do not enable sandbox tracing. It uses the backend’s request privacy filter described below.

`SENTRY_TRACES_SAMPLE_RATE` applies to browser performance traces; their default is 1.0 in development. Backend tracing is disabled by default. To enable it, set `BACKEND_SENTRY_TRACES_SAMPLE_RATE` between `0` and `1` (for example, `0.05` samples 5% of operations) and use a destination that accepts Sentry transactions. Recreate the backend API and worker services after changing the setting. Choose rates that fit your monitoring budget; setting the backend rate to `0` disables spans while keeping error reporting.

Backend spans measure HTTP handler completion and worker job execution. A job includes child spans for its drain check, handler or handover. Health and metrics probes are excluded; HTTP spans do not measure the lifetime of a streamed response body. Span names use route classes and registered queue names. Spans omit request and job payloads, raw SQL, identifiers, URLs, user context and breadcrumbs. Outgoing requests carry no trace headers. Agent work also has child spans for acquire, gateway provisioning, staging, execution, persistence and harvest; these use a fixed vocabulary and carry no prompts, file paths or credentials.

Backend events never include request cookies or bodies. Authorization, cookie, API-key, token, secret and session headers, webhook and share tokens in URLs, and credential query values such as OAuth codes are replaced with `[Filtered]` before sending. Stack frames and error messages are sent as they are, so choose the destination according to your data-handling requirements.

A database restart is not reported as an error; a managed upgrade recreates the database on every release. While it is unreachable, requests answer `503 DATABASE_UNAVAILABLE` with `Retry-After`, background jobs fail and retry under their queue's policy, and open live-update streams back off and resume. Each logs a warning line instead. The job queue logs one for the whole outage, not one for every failed poll. When the database stays unreachable for more than about a minute, an API process with live-update streams open sends one warning-level event for that outage. A backend process that starts while the database is unreachable waits up to about a minute for it instead of exiting, and logs a warning line for each new attempt. If the database is still unreachable after that, the start fails and is reported as an error. So a wrong host or port in `DATABASE_URL` takes about a minute to fail the start.

The backend does not report a request its client abandoned either, for example when you close a tab or cancel an upload while its body is still arriving. The request is answered with status `499`, counted among the client errors in the request metrics, and logged as a single debug line. Any other error in a request whose client has disconnected is still reported. An app request whose JSON body is empty or cut short is answered with `400 INVALID_JSON` and is not reported.

The browser leaves out errors that do not indicate a defect in Tale:

- errors thrown inside a browser extension
- requests the page cancelled itself, for example because you left the page before it finished loading
- requests the backend refused with a status below 500, such as a missing permission or a name that is already taken
- requests that got no response at all, for example while the device was offline
- requests that fail while the platform or its database restarts: the proxy's `UPSTREAM_UNAVAILABLE` during a deployment or restart, and the platform's `503 DATABASE_UNAVAILABLE`

Other server errors, with a status of 500 or above, are still reported.

## Aggregate analytics with Umami

Aggregate traffic collection is disabled by default and enabled separately for each deployment. Set `UMAMI_URL`, `UMAMI_WEBSITE_ID` and `UMAMI_PROXY_TOKEN` as described in the [environment reference](https://docs.tale.dev/self-hosted/configuration/environment-reference). Use a separate website ID for each deployment. Apply environment changes by recreating the affected production service; no image rebuild is needed. Clear the website ID and apply the change to disable collection. The Vite development server does not inject this configuration.

The browser loads the Umami tracker from its own origin at `/_a/script.js` and sends curated events to `/_a/api/send`. A configured base path prefixes these URLs. Only the website ID and proxy path enter the browser configuration; the collector origin and bearer token stay on the server.

`UMAMI_URL` must point to a collector gateway that authenticates `GET /_collect/script.js` and `POST /_collect/api/send` with that bearer token. A stock Umami dashboard URL alone does not provide this gateway contract. Caddy must overwrite `X-Analytics-Client-IP` from a trusted client address. Keep application ports private, and configure trusted proxy ranges when another proxy sits in front. The server forwards the validated IP, browser User-Agent and required Umami headers; it drops browser cookies, credentials and referrer headers.

Reports contain known public page paths or private platform route templates, referrer origins, browser language, screen size, browser/OS/device information and approximate location. The collector derives visits and location from the IP without storing the raw address. Private organization and resource IDs become placeholders. Page titles, query strings, fragments, form fields and product content are excluded. The marketing site also counts completed contact and demo submissions without their contents. There is no cross-site identity, automatic click capture or session replay. Do Not Track and Global Privacy Control disable collection.

After rollout, verify the behavior with a browser that permits analytics:

1. Open a known page, navigate to another page and confirm both pageviews in the deployment’s Umami website.
2. Inspect the request body. Private routes contain placeholders; query strings, titles and form data are absent.
3. Enable Do Not Track or Global Privacy Control and confirm that collection stops.
4. Block the collector or test with it unavailable. Normal navigation must continue to work.

## Know the limits

Tale does not currently export OpenTelemetry traces through OTLP. An OpenTelemetry Collector can collect the Prometheus metrics, but scraping metrics does not produce distributed traces. End-to-end trace export needs application instrumentation as well as a collector.

For alert thresholds and response procedures, continue with [Operations](https://docs.tale.dev/self-hosted/operate/observability/operations). For a failing service, use the symptom tables in [Troubleshooting](https://docs.tale.dev/self-hosted/operate/observability/troubleshooting).

# Providers
Source: https://docs.tale.dev/self-hosted/configuration/providers

Configure an AI provider by keeping three things distinct: the connector definition, the organization’s credentials and the model server. The connector describes the endpoint and protocol; credentials control access; the endpoint operator runs the model service.

Use this page for custom provider definitions and environment-backed secrets. For creating credentials and choosing defaults in the app, follow [AI providers](https://docs.tale.dev/platform/admin/providers).

## Local provider endpoints

A local inference server needs both a provider definition and permission for the backend to reach its host. The definition does not install the server or load a model.

1. Make the inference server reachable from every backend role that will call it. `localhost` inside a container refers to that container, not the host machine. Test name resolution, network access and any TLS certificate from the actual runtime network.
2. For a private or loopback endpoint, set `TALE_ALLOW_PRIVATE_PROVIDER_HOSTS=1` in the backend deployment environment. This permits private provider hosts across that deployment; it is not a per-provider allowlist. Cloud-metadata endpoints remain blocked. Apply the change by recreating the affected containers; restarting them retains their existing Compose environment.
3. Declare the organization’s provider in `TALE_CONFIG_DIR/<orgSlug>/providers/local-models.yml`, or through the [managed configuration workflow](https://docs.tale.dev/self-hosted/configuration/config-releases). Use the native provider schema and a name that does not collide with a shipped definition. An organization admin can also create the same file from the app: **Add credential** > **Custom provider** under **Settings > AI providers**; see [Define a custom provider](https://docs.tale.dev/platform/admin/providers#define-a-custom-provider).

For example, replace the private IP and port below with your own reachable server. HTTP is accepted only for hosts recognized as private or loopback; public endpoints require HTTPS. An internal DNS name alone does not bypass the request-time private-host check.

```yaml
name: local-models
displayName: Local models
apiFormat: openai
baseUrl: http://192.168.1.20:8000/v1
catalog:
  source: models-endpoint
auth:
  - method: api-key
  - method: env
```

This uses an OpenAI-compatible chat API and discovers models from `/v1/models`. Check the server’s actual compatibility; model listing alone does not prove that generation, tool calls or streaming work. If the server cannot list models, use `catalog.source: none` and enter exact model identifiers in the credential’s allowlist. Organization-defined providers do not load an organization-side static model file.

Then have an organization admin add a credential through [AI providers](https://docs.tale.dev/platform/admin/providers), refresh the catalog and select a specific model for a short chat. Verify the completed request in the intended inference server’s logs. Embeddings, speech and tool traffic require their own routing review; a local chat endpoint does not make them local.

## Configure audio transcription

The organization policy lives at `TALE_CONFIG_DIR/<org>/governance/transcription-model.yml`, with policy type `transcription_model`. The [Models page](https://docs.tale.dev/platform/admin/governance/content-models) edits the same selection. An absent file or an empty object means automatic selection:

```yaml
{}
```

To pin a model, supply both fields. This example uses the shipped OpenAI Whisper model and still requires an active, usable organization credential:

```yaml
providerSlug: openai
modelId: whisper-1
```

A partial pin is invalid. An unavailable pin never falls back to another model; restore its credential or the credential’s allowed models, or explicitly return to automatic selection. A configuration read or validation failure also refuses server transcription. The policy covers audio/video file transcription, video-link audio fallback and server dictation. Browser speech recognition remains independent.

With an active default credential for OpenRouter, Tale also discovers dedicated speech-to-text models from `/models?output_modalities=transcription`. The same credential and its allowed models apply. Use the exact identifier from that catalog when pinning a model, or keep automatic selection. See [OpenRouter’s speech-to-text guide](https://openrouter.ai/docs/guides/overview/multimodal/stt) for the provider’s endpoint contract.

For a custom OpenAI-compatible endpoint, use `catalog.source: models-endpoint` and have its `/models` response declare the audio model with an exact `id` and either `type: transcription` or `architecture.output_modalities: [transcription]`. A pure transcription model may omit `context_window` or report `0`; other models still require a positive value. An audio-input chat model or a text-to-speech model is not automatically a transcription candidate.

Tale sends bearer-authenticated multipart `file` and `model` fields to `POST <baseUrl>/audio/transcriptions`. For OpenRouter it requests `response_format: json`, because some of its models reject `verbose_json`. Other compatible endpoints must accept `response_format: verbose_json`. The JSON response provides the transcript as `text`. Tale prefers a valid `duration` and falls back to valid `usage.seconds`. When neither is usable, it uses a local duration measurement where available. Timestamped `segments` can supply video timestamps; without them, the transcript remains plain text. Listing the model does not prove this API works. Refresh the catalog, select the model, then test a short recording and verify the request in that endpoint’s logs.

## Configure image generation

The organization policy lives at `TALE_CONFIG_DIR/<org>/governance/image-generation.yml`, with policy type `image_generation`. The [Models page](https://docs.tale.dev/platform/admin/governance/content-models#let-agents-generate-images) edits the same settings. A new organization is seeded with image generation off, and an absent file means off too:

```yaml
enabled: false
```

Set `enabled: true` for automatic selection, or pin a model with both fields:

```yaml
enabled: true
providerSlug: openai
modelId: gpt-image-1
```

A partial pin or an unknown field is invalid. An invalid or unreadable file leaves image generation off, and the Models page names the problem. Automatic selection tries `google/gemini-2.5-flash-image`, `gpt-image-1-mini`, `gpt-image-1` and `black-forest-labs/flux.2-pro`, in that order, through an OpenRouter or OpenAI default credential. An unavailable pin never falls back to another model. A pin may stay in the file while `enabled` is `false`.

The backend calls the image model with the organization's credential; no key enters the sandbox. For OpenRouter it sends `POST <baseUrl>/images`, OpenRouter's Image API, with an aspect ratio of `1:1`, `3:2` or `2:3`, and records the cost the response reports. For any other provider it speaks OpenAI's images API: `POST <baseUrl>/images/generations`, or `POST <baseUrl>/images/edits` as multipart form data when the agent passes reference images, asking a GPT image model for `medium` quality. It then prices the token counts the response reports from the model's catalog entry. Tale discovers OpenRouter's image models from `/models?output_modalities=image`, and the shipped OpenAI catalog lists `gpt-image-1` and `gpt-image-1-mini`.

A custom OpenAI-compatible endpoint's `/models` response must declare an image model with `image` among `architecture.output_modalities` or `modalities.output`, and a positive `context_length` or `context_window`. Tale saves raster images only (PNG, JPEG, WebP, GIF) and refuses a model's SVG; a reference image an agent passes must be a PNG, JPEG or WebP file of at most 4 MB. Listing a model does not prove the endpoint works: turn image generation on, pin the model, have an agent create a test image, then check the request in the endpoint's logs.

One agent turn creates at most 16 images and runs one generation at a time. Before each call, Tale holds USD 0.25 per image against the turn's allowance and the budget caps, then books the reported cost in place of the hold when the call ends. The turn's gateway key gives up the same amount from its cap, so the model and the images together stay within one allowance; if the gateway cannot lower that cap, the image is refused. A turn on a vendor subscription has no gateway allowance, so its images are measured against the deployment's default turn allowance.

## Configure the standard agent {#configure-the-standard-agent}

The organization policy lives at `TALE_CONFIG_DIR/<org>/governance/standard-agent.yml`, with policy type `standard_agent`. The [Models page](https://docs.tale.dev/platform/admin/governance/content-models#standard-agent) edits the same settings. A new organization is seeded with the standard agent on, and an absent file means on too:

```yaml
enabled: true
```

Pin the runtime, the model or both, and replace the built-in instructions:

```yaml
enabled: true
harness: claude-code
providerSlug: anthropic
modelId: claude-sonnet-5
instructions: |
  Write in the house style. Deliver every document as a Word file.
```

`harness` takes the slug of a runtime a project agent can use, such as `claude-code` or `codex`; the Models page refuses one that isn't. A model pin needs both `providerSlug` and `modelId`. A partial pin, an unknown field, or instructions longer than 20,000 characters are invalid. An invalid or unreadable file stops every standard agent from starting, and the Models page names the problem; it is never read as on. An unavailable pin never falls back to another model, and neither does a pin that a person's model access denies. The policy is read whenever a run starts, so an edit applies to the next run. With `enabled: false`, the standard agents already set up stay in their projects, but none of them starts.

## Verify sandbox model access

Chat calls a provider from the backend. Coding-agent sessions use `sandbox-llm-gateway`, so a successful chat does not prove the agent path. Make the endpoint resolvable and reachable from both the backend and the gateway; each HTTPS client must trust its certificate. A hostname such as `https://models.internal/v1` still needs the private-provider opt-in when DNS resolves it to a private address. Plain HTTP remains limited to hostname forms accepted by the provider schema, such as private IP literals, `localhost` and `.local`.

When a new sandbox session starts, the backend checks the custom provider’s hostname and DNS answers before provisioning its gateway configuration. Private destinations require `TALE_ALLOW_PRIVATE_PROVIDER_HOSTS=1`; metadata destinations are refused even with it. This preflight does not pin DNS for the gateway’s later requests. Keep provider configuration and DNS under trusted operator control.

After recreating the affected backend processes, start a new sandbox session with the intended provider, model and compatible agent runtime. Use a harmless request and verify a completed reply and the matching inference-server log entry. Inspect `sandbox-llm-gateway` logs if chat works but the agent cannot reach its model. `SANDBOX_EGRESS_ALLOWLIST` controls general sandbox web access, not this separate model connection.

Coding agents also rely on the context window the catalog reports for the model: the `context_length` or `context_window` your server lists on `/v1/models`, or 128,000 tokens when the listing publishes neither, as for a provider configured with `catalog.source: none`. Make the listing report the context your server actually serves. When that window, or a lower [context limit](https://docs.tale.dev/platform/admin/governance/policies-and-limits) for the person who started the run, is below 200,000 tokens, a managed Claude Code session compacts its conversation into a summary before the prompt outgrows it. Claude Code treats any value below 100,000 tokens as 100,000, so a model that serves less can still receive longer prompts than it holds. Give Claude Code a model with at least that much context.

A managed Claude Code session on a model other than Claude also leaves out the attribution line Claude Code otherwise puts at the start of every system prompt. That line changes with each request, so a server that caches prompt prefixes would recompute the whole conversation on every turn.

## Where the connectors live

Shipped definitions live at `configs/platform/system/providers/<slug>/provider.yml`. Their static catalogs live at `configs/platform/system/models/<slug>/models.yml`; for example, Anthropic uses `providers/anthropic/provider.yml` and `models/anthropic/models.yml`. These files belong to the image and change with its release.

<Warning>

Shipped files are read-only image inputs and are replaced on upgrade. For an external provider, use the reviewed `configuration` deployment declaration described in [CLI installation](https://docs.tale.dev/self-hosted/install/cli-install#configure-the-platform). It creates an organization-owned connector under `TALE_CONFIG_DIR/<org>/providers/` through the same native schema, while credential and policy changes use native APIs. The **Custom provider** entry of **Add credential** in the app writes the same organization-owned file and keeps every saved version under `.history/`.

</Warning>

## What a connector declares

A definition describes protocol, endpoint, catalog, and accepted authentication methods. It contains no organization credentials. These two excerpts show the format:

<CodeGroup>

```yaml anthropic.yml
name: anthropic
displayName: Anthropic
apiFormat: anthropic
baseUrl: https://api.anthropic.com
catalog:
  source: static
auth:
  - method: api-key
  - method: env
  - method: subscription-broker
    constraints:
      execution: sandbox
      harness: claude-code
```

```yaml openrouter.yml
name: openrouter
displayName: OpenRouter
apiFormat: openai
baseUrl: https://openrouter.ai/api/v1
catalog:
  source: openrouter-api
auth:
  - method: api-key
  - method: env
```

</CodeGroup>

| Field | Meaning |
| --- | --- |
| `apiFormat` | The request format: `openai` or `anthropic`. |
| `wireDialect: openai-modern` | For OpenAI-format endpoints: use `max_completion_tokens` and omit custom temperature for reasoning models. Leave it unset for endpoints that need the classic fields. |
| `baseUrl` | A fixed endpoint shared by credentials. |
| `endpointMode: per-credential` | Use an endpoint supplied with each credential instead of `baseUrl`, as Azure OpenAI does. |
| `catalog.source` | `static`, `openrouter-api`, `models-endpoint`, or `none`. Static entries use the model catalog described above. |
| `embedding` | Whether the provider serves embeddings: `supported` when its catalog ships a curated vector width, `unsupported` when the vendor offers no embedding model, so **Settings > Data residency > Embedding model** refuses it, or `unknown`, the default, when an admin enters the model and its vector width. Declare `unsupported` only where the vendor's own documentation says so. |
| `auth` and `constraints` | Allowed credential methods and any execution requirements, such as a named sandbox harness. |

## Environment-variable key source

For **Environment variable** authentication, the credential stores a variable name; the backend reads its value from its process environment when making a request. Inject the value through your deployment secret manager. This method does not store the API key in the application database.

Only names beginning with `TALE_PROVIDER_KEY_` are accepted. The complete name may contain at most 40 characters; the suffix uses letters, digits, or underscores. The form supplies the prefix automatically.

```bash
TALE_PROVIDER_KEY_OPENROUTER=sk-or-...
TALE_PROVIDER_KEY_OPENAI_PROD=sk-...
```

<Note>

The reserved prefix prevents a credential from selecting unrelated secrets such as `SOPS_AGE_KEY` or `BETTER_AUTH_SECRET`. Validation rejects an invalid name before it can be saved.

</Note>

After adding or rotating the value, recreate both `backend-api` and `backend-worker` with the updated environment. A Compose restart retains old environment values. Leading and trailing whitespace is removed before use; verify a real request after the rollout.

## Connect a subscription broker

A subscription broker supplies a pool of OAuth access tokens; Tale chooses a usable account for each agent turn. The shipped integrations are Anthropic with Claude Code and OpenAI ChatGPT with Codex, for task and automation agents. Keep direct API credentials for chats and other direct model calls. An OAuth token is not a provider API key.

Use a separate endpoint for each provider. Tale AI gateway exposes `/api/tokens/anthropic` and `/api/tokens/openai`, authenticated with its API key as a bearer token. Its combined `/api/tokens` endpoint is not the right source for a single-provider credential. The backend must reach the broker under the same host policy described for provider endpoints above.

The following example is the broker credential document built by the [AI providers form](https://docs.tale.dev/platform/admin/providers#connect-a-subscription-broker), not a provider definition file. Replace the hostname with your broker and provision `TALE_TOKEN_SOURCE_AI_GATEWAY` in both backend processes with that broker's API key. The mapped property names match Tale AI gateway; adapt them for another broker.

```json
{
  "endpoint": "https://broker.example.com/api/tokens/anthropic",
  "httpMethod": "GET",
  "auth": {
    "method": "bearer",
    "secretEnv": "TALE_TOKEN_SOURCE_AI_GATEWAY"
  },
  "responseMapping": {
    "tokensPath": "$.tokens",
    "tokenField": "access_token",
    "statusField": "status",
    "activeValue": "active",
    "expiresField": "expires_at"
  },
  "targetEnvVar": "CLAUDE_CODE_OAUTH_TOKEN",
  "selection": "round-robin"
}
```

For OpenAI, change the endpoint suffix to `/api/tokens/openai` and `targetEnvVar` to `TALE_SUBSCRIPTION_TOKEN`. Every usable OpenAI item must also contain its vendor `account_id`. Tale passes that value as `TALE_SUBSCRIPTION_ACCOUNT_ID`, alongside the token, to Codex's ChatGPT connection. Do not substitute the gateway's `id` or `CODEX_ACCESS_TOKEN` for these values. Restrict the credential's model allowlist to model IDs supported by the ChatGPT plan; the OpenAI API catalog may contain models that are unavailable to subscriptions.

For Anthropic OAuth, use `CLAUDE_CODE_OAUTH_TOKEN`. The legacy `ANTHROPIC_AUTH_TOKEN` target remains supported when explicitly configured; it uses Claude Code's generic bearer-authentication path. Tale clears competing provider credential variables before supplying the chosen token. A target variable unsupported by the selected runtime is refused.

### Account identity and quota

Alongside the mapped token, status and expiry fields, a broker may provide these standard fields on each token item. Their names are fixed and require no additional response mapping.

| Field | Role |
| --- | --- |
| `id` | Broker account identifier |
| `provider` | Provider identifier |
| `account_id` | Vendor account identifier |
| `available` | Availability for new work |
| `available_at` | Time it becomes available again |
| `hold` | Why an unavailable account is held back |
| `usage` | Usage snapshot |

Keep `id` stable when the account's access token rotates, so retries recognize the same account. It is distinct from the vendor's `account_id` required by OpenAI. If `provider` names a different provider than the credential, the item is excluded.

`available: false` excludes the account until the ISO timestamp in `available_at`. If no reset is known, omit that timestamp or use `null`; the account then stays excluded until the broker reports it available. Status and token expiry are checked separately. Tale AI gateway computes availability from a `usage` snapshot containing `checked_at` and `windows`, each with its kind, utilization and reset time.

Older brokers can omit the optional metadata. Without `id`, retry identity falls back to a hash of the token, so it cannot recognize an account after its token changes. Missing quota information leaves an account eligible; it does not establish that quota remains.

Tale AI gateway excludes an account when a fresh usage snapshot reports a global session or weekly window at 100% and its reset has not passed. A vendor's explicit limit signal (`usage.limited: true`) also makes the account unavailable, even when its displayed utilization is lower or missing. Model-specific limits do not exclude the whole account. Usage is considered stale after 15 minutes, so unknown or stale readings leave the account eligible; an exhausted window with no reset time is held only while its reading is fresh. The next token request refreshes stale usage where the vendor supports it. After the applicable reset, the account can rejoin the pool. Provider-side rejection is still possible between usage refreshes. The gateway also reports an account as unavailable until its planned token refresh, `refresh_at`, once that refresh is less than an hour away (its default hand-out floor) and another account can take the work. Such an account carries `hold: "refresh"`, while a spent quota reads `hold: "quota"`. The gateway decides that another account can take the work without seeing Tale's own rules: the cooldown after an HTTP 429 described below, and the `account_id` that OpenAI requires. When those leave no available account, Tale uses the account held for its refresh whose refresh is furthest away instead of refusing the work. A turn therefore starts on a token that is about to be revoked only when the pool has nothing better, and a pool of one account is never held back this way. A broker that sends no `hold` field keeps every unavailable account excluded.

### Selection and recovery

`random` is the form's initial selection; `first` follows broker order. `round-robin` chooses the usable account selected least recently, with selection history stored per organization and credential. Concurrent requests from different backend processes update that history atomically; response reordering and backend restarts do not reset it. Preserving the account's history across token refreshes requires a stable `id`. These strategies distribute account selections, not tokens or active-agent capacity. Existing credentials retain their saved strategy.

When an account returns HTTP 429, Tale excludes it from new selections for this organization and credential for 60 seconds. Retries prefer accounts not yet tried during that run's failure streak. If every otherwise usable account was tried, retries may reuse one; quota and cooldown exclusions still apply. When every account is cooling down, an automatic task or automation retry is queued at once but starts only when the first account is available again. That wait uses no automatic retry when the refused run was itself retrying a failure on an HTTP 429.

An HTTP 401 during a turn served by a broker token can mean the token rotated while the agent worked. Tale requests credentials from the broker again and resumes the conversation when its handle and sandbox session remain available; otherwise it starts a fresh turn. The first two consecutive interruptions of this kind do not spend an automatic retry or exclude the account, so a replacement token on the same account can be used. A third counts like any other failure. This bound also handles a 401 caused by invalid authorization rather than rotation. An interruption after at least fifteen minutes of work starts the count again.

Unless overridden, pool requests time out after 10 seconds and accept at most 262,144 bytes. A mapped token expiry must be further away than the expiry safety margin, `expirySkewMs`, which defaults to five minutes. Keep the status and expiry mappings when using Tale AI gateway so inactive or nearly expired tokens are skipped; its own hand-out floor already holds back accounts that are about to be refreshed. The gateway's `refresh_at` field is the moment its refresh ends a token, earlier than the vendor's `expires_at`. Mapping `refresh_at` as the expiry and raising `expirySkewMs` (at most 3,600,000 ms) makes that rule strict: no turn starts on a token with less than the margin left, but while every account is that close to its refresh, the pool refuses new work, and a pool of one account does so before every refresh. Expiry values may be ISO timestamps or Unix timestamps in seconds or milliseconds.

The minimum remaining lifetime protects the start of a turn, not its full length. Long task or automation runs can outlast a token and need the bounded recovery described above. A broker retry does not guarantee that the account will provide working credentials.

If the pool has no usable account, inspect broker authorization, account status, token expiry and planned refreshes, quota resets and the response mapping. Renew the account authorization, or wait for the quota reset or the token refresh, as appropriate. Then verify a completed task or automation reply with the intended provider and runtime. A successful broker fetch alone does not test the vendor connection.

## Broker secrets from the environment

A **Subscription broker** credential can read its broker secret from the deployment environment. Use the separate `TALE_TOKEN_SOURCE_` prefix in **Secret from environment variable** and leave **Broker secret** empty. Names outside that namespace are rejected. If you supply both, the stored broker secret takes precedence. Recreate the consuming processes when rotating an environment-backed value.

When the replacement configuration still uses broker authentication, leaving both secret fields empty preserves its existing stored secret. Entering an environment reference without a new broker secret switches to the environment source. Choosing **None** for broker authentication removes the stored secret from the replacement configuration.

## Keep organization settings with the organization

Credential names, allowed models, defaults, and enabled state remain organization data, normally managed under [AI providers](https://docs.tale.dev/platform/admin/providers). A managed configuration release can create exact environment-backed credentials through native APIs after verifying the organization and operator. It does not install an inference server or prove model behavior; complete the local endpoint checks above after deployment.

# Configure retention bounds
Source: https://docs.tale.dev/self-hosted/configuration/retention

Retention controls how long Tale keeps each category of data. Operators set the allowed bounds; organization admins enable categories and choose a duration within those bounds. A shorter duration can delete existing history, so review its effect before applying it.

## Understand bounds and policy

Two files under `TALE_CONFIG_DIR/<orgSlug>/governance/` have different jobs:

| File | Purpose |
| --- | --- |
| `retention.yml` | Operator bounds and defaults for every category. JSON is also accepted. |
| `retention-policy.yml` | The organization’s chosen enabled states and durations. Managed by the governance settings. |

The organization gets its own files when it is created. A change to one organization’s file does not change another organization’s policy. There is no fallback to a `default` organization when an organization’s bounds file is missing.

Each category has `min`, `max`, `default` and `unit`. Raising `min` requires data to be kept longer; lowering `max` limits how long it may be kept. Neither value enables cleanup by itself. The applied policy determines whether the category is enabled.

## Edit the organization’s bounds

Start from the organization’s existing complete file. Preserve categories you are not changing. This fragment shows the shape of one category, rather than a replacement for the whole file:

```yaml
chatHistory:
  min: 30
  max: 730
  default: 90
  unit: days
```

Most categories use days; `userTempHours` and `agentTempHours` use hours. The token-usage category is named `usageLedger`. Use the category identifiers already present in the file so validation can catch mistakes.

Environment overrides are declared explicitly by the file’s root `_metadata.envNames`, with an optional `_metadata.envPrefix`. The bundled file maps `TALE_RETENTION_AUDIT_MIN` to `auditLog.min`, for example. A minimum override can only raise the floor; a maximum override can only lower the ceiling. Restart the backend processes after changing their environment.

Two floors are fixed: `auditLog.min` cannot be lower than 180 days, and `loginAttempt.min` cannot be lower than 90 days. Tale does not load a file that undercuts either. Until you correct it, the organization’s **Retention policy** shows no allowed ranges and cannot be saved, and the backend log names both floors. Scheduled cleanup keeps using the bounds applied last.

The bundled file lets an organization keep audit logs for 180 to 3650 days. Upgrading Tale does not rewrite an organization’s file, so an organization created by an earlier release can still have `auditLog.min: 365`. Lower that value to allow a shorter audit retention, or raise it when a regulation or contract requires a longer audit history.

## Review and apply a change

After editing bounds, ask the organization admin to review the proposed change in [Policies and limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits). Cleanup uses the applied bounds snapshot; an operator’s file edit alone does not silently apply new bounds.

Review enabled categories, the old and new durations, and any grace period before applying. A value such as `auditLogRetentionDays: 730` is a chosen duration, while `auditLog.min: 180` is a lower bound. Keep those meanings separate when reviewing a diff.

<Tip>

Test a shorter policy on synthetic data first. Confirm that a record inside the window remains, an expired record follows its category’s deletion behavior, and a held record remains protected.

</Tip>

## Understand the cleanup result

The backend worker runs scheduled cleanup per organization. Threads, documents, contacts and external conversations have lifecycle handling; row-level categories can be deleted directly after their applicable retention and grace period. Do not assume that every deleted record appears in Trash.

Each run deletes a limited number of records per category and organization: up to 50,000 chat filter events, and batches of up to 1,000 records for every other category. A larger backlog, such as a long history when a category is first enabled, takes several daily runs to clear.

Audit retention is also organization-scoped. It removes the oldest eligible prefix of that organization’s audit chain, stopping when a held row must remain. One tenant’s shorter window does not shorten another tenant’s history.

Each run is recorded in the organization’s [audit log](https://docs.tale.dev/platform/admin/governance/audit-logs) as system events in the data category. It begins with **Retention run started**, adds one event for each category that deleted records, carrying the number removed rather than one event per record, and ends with **Retention run completed**. A run that stops on an error, or keeps due records because their deletion failed, ends with **Retention run failed** instead; the next scheduled run retries those records. All events of one run name the same retention run as their target, and a run that finds nothing to delete still records its start and end.

`TALE_RETENTION_DISABLED=true` pauses scheduled retention cleanup for an operator-controlled maintenance window. It does not restore deleted data or disable other deletion paths. Record when you enable it and remove it when the maintenance is complete.

## Preserve held data

Legal holds override retention for their supported scope. An organization-wide hold protects the organization; narrower holds protect the matching entities or custodians. Review the [legal hold workflow](https://docs.tale.dev/platform/admin/governance/legal-hold) before changing a policy that affects held data.

A hold is not a backup. Once deletion has completed outside a hold, increasing the retention duration cannot recover the data; recovery depends on a retained backup and its matching deployment state.

# Protect configuration secrets with SOPS
Source: https://docs.tale.dev/self-hosted/configuration/secrets-with-sops

Tale uses SOPS and age for supported configuration secret sidecars, including knowledge-database and object-storage connection files. Current AI-provider credentials are stored separately in the application database and use `ENCRYPTION_SECRET_HEX`. Rotating an age key does not rotate those database credentials.

## Identify the secret you are changing

Use the storage mechanism to choose the correct key:

| Secret storage | Encryption control | Operational consequence |
| --- | --- | --- |
| SOPS-enabled `*.secrets.json` configuration sidecar | `SOPS_AGE_KEY` or `SOPS_AGE_KEY_FILE` | Preserve a key that can decrypt every retained file and backup. |
| Database provider credentials and other secret-box values | `ENCRYPTION_SECRET_HEX` | Replacing the key makes existing ciphertext unreadable; age rotation does not migrate it. |
| Provider credential backed by an environment variable | `TALE_PROVIDER_KEY_*` | Rotate through the deployment’s secret manager and restart the consumers. |

A retired `providers/<name>.secrets.json` file may still exist in old configuration trees. Its presence does not mean that current provider credentials use that file. See [Providers](https://docs.tale.dev/self-hosted/configuration/providers) for the current credential model.

## Choose an age-key source

An inline `SOPS_AGE_KEY` takes precedence over `SOPS_AGE_KEY_FILE`. Use one source deliberately. The file form accepts one private age key per line and ignores blank lines and `#` comments; all configured recipients are included when Tale writes new SOPS ciphertext.

The file path is resolved inside the process that reads it. A host path in `.env` is insufficient by itself: mount the key file into each container that needs it, set the in-container path and restrict filesystem access. Recreate the consuming containers after changing their environment; `docker compose restart` does not load changed environment definitions.

If both variables are unset, the SOPS helper writes supported sidecars as plaintext JSON with mode `0600`. It still recognizes existing encrypted files and refuses to read them without a key. Unsetting the variables does not decrypt existing files.

## Prepare a rotation

Inventory the SOPS-encrypted files and their backups before replacing a key. Keep a protected copy of the old key and verify that you can decrypt a representative file without printing its contents or sending them to logs.

Create a new age key through your existing secret-management tooling. Build a protected key file containing **both the existing private key and the new private key**. Do not overwrite the old key file with a command that generates only the new key.

Update the deployment to mount that file and use `SOPS_AGE_KEY_FILE`. Remove the inline value from the consuming environment, or it will continue to take precedence. Roll out the environment change and confirm that existing connections still work.

## Re-encrypt and verify

Rewrite each affected sidecar through its supported configuration save path or an operator-controlled SOPS re-encryption procedure. Tale addresses newly encrypted files to all currently configured recipients; merely adding a key leaves existing ciphertext unchanged.

<Warning>

Do not remove the old key until every active encrypted file has been checked with the new key alone. Keep the old key protected for historical backups that still require it.

</Warning>

After that verification, deploy a key file containing only the new key. Restart the consuming processes to clear decrypted caches, then test each affected connection. A successful process restart alone does not prove that every file can be decrypted.

## Recover a decryption failure

| Symptom | Check |
| --- | --- |
| Encrypted file found without a key | Restore the matching key source; disabling encryption does not convert the file. |
| Key-file read fails | Check the mount, in-container path, ownership and permissions. |
| Old key is still selected | Remove the non-empty inline `SOPS_AGE_KEY` before relying on the file. |
| New key cannot decrypt one file | Keep the old key and re-encrypt that file before completing the rotation. |
| Provider credential fails after changing `ENCRYPTION_SECRET_HEX` | Follow the database-secret recovery path; changing age keys cannot repair it. |

For secrets managed by Vault, Kubernetes or another external store, prefer a provider’s [environment-variable key source](https://docs.tale.dev/self-hosted/configuration/providers#environment-variable-key-source) where supported. Keep encryption keys with your recovery plan, separately protected from the data backups they unlock.

# TLS and domains
Source: https://docs.tale.dev/self-hosted/configuration/tls-and-domains

Choose the URL users will open and the service that terminates TLS before configuring sign-in or inviting people. Tale's Caddy proxy can use its internal certificate authority, obtain public certificates, or serve HTTP behind your own TLS proxy.

## Choose a TLS mode

| `TLS_MODE` | Use it when | What you operate |
| --- | --- | --- |
| `selfsigned` | Developing locally or using a private environment whose clients trust your CA. | Install Caddy's root certificate in each client trust store. |
| `letsencrypt` | Serving a public hostname through Tale's proxy. | Public DNS, reachable ports 80/443, and persistent Caddy certificate storage. |
| `external` | A load balancer or reverse proxy already handles TLS. | The upstream certificate, trusted forwarding, and the private HTTP connection to Tale. |

Keep `SITE_URL` as the public URL and `HOST` as its hostname. Applying new environment values requires recreating the affected services. With the workspace CLI, use the deployment workflow and include `--stop` when the proxy must be recreated; inspect the preview and allow for downtime. With your own Compose file, the service is `proxy`, not the generated container name.

## Trust a private development certificate

`TLS_MODE=selfsigned` makes Caddy issue certificates from its internal CA. A browser warning means that client does not trust the issuing CA or the hostname does not match; check both.

Copy the **public root certificate** from the running proxy container. Set `TALE_PROXY_CONTAINER` to the actual container name from your deployment:

```bash
docker cp "$TALE_PROXY_CONTAINER:/data/caddy/pki/authorities/local/root.crt" ./tale-local-root.crt
```

Verify that the certificate came from your own instance, then install it using the operating system's or browser's trusted-certificate settings on each client that needs access. Do not distribute the CA's private key. Running `caddy trust` through `docker exec` affects the container's trust store, not your workstation's. See [Caddy's local HTTPS guidance](https://caddyserver.com/docs/automatic-https#local-https) for the trust boundary.

## Obtain a public certificate

1. Point the hostname's public DNS records at the intended host. Check both A and AAAA records when IPv6 is configured.
2. Make ports 80 and 443 reachable at that proxy, and preserve its `caddy-data` volume across replacements.
3. Configure the public URL and certificate mode:

```bash
HOST=tale.example.com
SITE_URL=https://tale.example.com
TLS_MODE=letsencrypt
TLS_EMAIL=ops@example.com
```

4. Apply the configuration, inspect `tale logs proxy`, and open the public URL from another machine. Check the hostname and certificate chain in the browser.

Caddy handles issuance and renewal. DNS, firewall, ACME, and storage problems can delay or prevent them, so monitor certificate expiry and proxy errors rather than assuming a fixed issuance time. `TLS_EMAIL` provides the ACME contact address; it is not a substitute for expiry monitoring. [Caddy's automatic HTTPS requirements](https://caddyserver.com/docs/automatic-https) describe the public network prerequisites.

## Use an upstream TLS proxy or custom certificate

Set `TLS_MODE=external` when another proxy terminates TLS, while keeping the browser-facing HTTPS URL:

```bash
HOST=tale.example.com
SITE_URL=https://tale.example.com
TLS_MODE=external
TRUSTED_PROXIES=10.20.0.0/16
```

Tale's Caddy instance serves HTTP inside this arrangement, so your proxy has to report how the browser connected. Forward the original `Host` header and send `X-Forwarded-Proto: https`; Tale uses both to keep each browser on the origin it opened. Caddy accepts forwarded headers only from the addresses in `TRUSTED_PROXIES`: CIDR ranges separated by spaces, or `private_ranges` for every private and loopback address, which is the default when the variable is unset. Set it to the range your proxy connects from. The proxy refuses to start on any other value, and the other TLS modes ignore the variable.

Keep the HTTP hop private. The proxy container publishes port 80, so allow only your TLS proxy to reach it: a client inside a trusted range could otherwise claim an HTTPS connection it never made. Verify sign-in callbacks, secure cookies, uploads, and streaming through the complete path. A custom certificate installed on the upstream proxy is independent of Tale's TLS mode.

If you maintain a custom Tale proxy image and Caddyfile instead, mount your certificate and private key read-only and configure Caddy's `tls <cert-file> <key-file>` directive yourself. Merely mounting the files or setting `TLS_MODE=external` does not make Caddy load them. The custom configuration must retain Tale's routes, health behavior, and metrics protection.

## Change the public domain or base path

Update `HOST` and `SITE_URL` together, plus any browser-facing storage endpoint and identity-provider callback registrations that use the old origin. Recreate the affected application and proxy services, then test sign-in, an existing file download, an upload, and a live-updating page at the new URL.

For a managed deployment created with `identity.bootstrap: "fresh"`, follow the [managed hostname migration procedure](https://docs.tale.dev/self-hosted/install/cli-install#managed-origin-migration) as part of this transition. It requires the retained deployment state and an explicit `identity.migrateOriginFrom`; changing only `HOST` and `SITE_URL` does not update the managed identity and client journals. Keep the existing account, organization and client credentials, then export the consumer configuration for the new issuer after the deployment is ready.

For a subpath such as `https://example.com/app`, also set `BASE_PATH=/app`. Keep that prefix on requests sent to Tale's proxy: its generated routing strips the prefix internally. Check absolute links and callbacks rather than verifying only the home page. Keep the old domain available during a planned transition if users still need its existing links or sessions.

## Serve several domains {#several-domains-at-once}

List additional bare origins in `ADDITIONAL_SITE_URLS`, separated by commas or whitespace:

```bash
HOST=tale.example.com
SITE_URL=https://tale.example.com
ADDITIONAL_SITE_URLS=https://tale.partner.example,https://app.example.org
```

An origin has a scheme, host, and optional port, but no path. Caddy serves the listed origins and requests their public certificates in `letsencrypt` mode. Configure DNS and reachability for each. These origins are separate entry points, with cookies scoped to the domain where the user signs in.

Tale accepts only configured origins when deriving browser-facing URLs; an unrecognized host falls back to `SITE_URL`. Do not use that fallback as a domain-configuration shortcut.

In a managed deployment, declare these origins as `additionalOrigins` in the deployment specification instead of editing the runtime environment; see [Serve additional origins](https://docs.tale.dev/self-hosted/install/cli-install#managed-additional-origins). The CLI manages `ADDITIONAL_SITE_URLS` there and keeps the native identity on the primary origin.

### Keep canonical settings stable

| Setting | Why the canonical domain matters |
| --- | --- |
| E-mail links and notifications | Background work has no browser origin to use. |
| SAML SP entity ID | The identity provider identifies one stable service provider. |
| SCIM resource locations | Directory synchronization needs stable resource URLs. |
| Passkeys | Credentials are bound to a relying-party domain and do not transfer automatically between domains. |
| Public object-storage endpoint | Background work signs file links for this endpoint. A link handed to a browser uses the domain the browser is on when the endpoint is one of this deployment's origins; review a separate file host when changing domains. |

### Register every provider callback

Open **Settings > Enterprise SSO** to copy each domain's OIDC redirect or SAML ACS URL. SAML metadata includes the configured ACS entries. For connector consent, use the per-domain redirect URLs under **Settings > Connectors > OAuth apps**. Register the required URLs with each provider and test a fresh sign-in from every supported origin.

# Configure video transcript ingestion
Source: https://docs.tale.dev/self-hosted/configuration/video-ingestion

Tale uses `yt-dlp` to retrieve content for video-link ingestion. Availability depends on the video, supported captions or extraction path, and the source platform's access checks. A video that plays on your laptop may still reject the server's network or session.

This operator guide covers transcript retrieval configuration. Start with a public video you can access and inspect its ingestion error before adding credentials or changing egress.

## Identify the failing stage

| Observation | Check first |
| --- | --- |
| One video fails | Whether the URL is supported, the content is still available, and a usable transcript or audio path exists. |
| Many videos fail from one host | Worker extractor errors, source-platform responses, and that host's network path. |
| Retrieval works but knowledge search does not | The organization's embedding configuration and indexing status. |
| Failures begin after a session worked | Session expiry, source-account state, and cooling or retirement in the pool. |

Read `tale logs backend-worker --tail 200` and the item's failure reason. Keep the URL and error category, but remove account cookies, signed URLs, and credentials before sharing diagnostics. Retries may help a transient failure; repeated identical refusals need investigation.

## Check the built-in token provider

The platform image includes the token plugin, and the packaged deployment starts `bgutil-provider` on the internal network. The default endpoint is `http://bgutil-provider:4416`. It supplies proof-of-origin tokens used by supported extractor requests; it does not grant access to private content or guarantee that a source accepts the request.

Check `tale logs bgutil-provider` and whether the worker can reach the service. The sidecar is best-effort: its failure does not prevent the core deployment from starting, though transcript retrieval may degrade.

`VIDEO_INGEST_POT_PROVIDER_URL` selects another provider endpoint. `VIDEO_INGEST_PO_TOKEN` supplies a manually obtained token. Keep token material in your secret configuration. The [environment reference](https://docs.tale.dev/self-hosted/configuration/environment-reference) also lists extractor-client and plugin options; change them only when the observed error calls for it.

## Configure an egress proxy

Use `VIDEO_INGEST_PROXY_URL` when your deployment requires video retrieval through an approved proxy. Metadata, captions, and audio requests use that configured path. Supported schemes include `http`, `https`, `socks4`, `socks4a`, `socks5`, and `socks5h`; the latter resolves DNS at the proxy.

```bash
VIDEO_INGEST_PROXY_URL=socks5h://proxy.example.com:1080
```

Add credentials through your secret-management workflow if the proxy requires them. An invalid or unsupported proxy URL is ignored with a warning, so confirm the applied configuration and a real retrieval result. Recreate the worker after changing its container environment; restarting the existing container does not import a changed `.env`.

A different route is not a promise of access. Confirm that your proxy and the source account are authorized for the content you need. If the source remains unavailable, import a transcript you already have as a [Knowledge document](https://docs.tale.dev/platform/knowledge/documents).

## Import an authorized browser session

The server can draw cookies from a session pool keyed by **organization and domain**. It encrypts cookie jars using `ENCRYPTION_SECRET_HEX` and does not return those cookies in list responses. Pool access is part of server-side video ingestion, not a cookie export to agent scripts.

There is no in-app import form. The REST write requires a key whose user is an organization administrator and is on `TALE_DEPLOYMENT_CONFIG_ADMINS`; the key must also resolve the target organization. `GET /api/v1/me` reports `capabilities.deploymentEditor` for the key. Name the organization explicitly with `X-Organization-Slug`, especially when the user belongs to several organizations.

1. Export a Netscape-format cookie jar from an authorized browser session for the source domain. Treat the file as account credentials and keep it outside source control.
2. Set `TALE_URL`, `TALE_API_KEY`, and `TALE_ORG_SLUG` for the intended instance and organization. Keep `cookies.txt` readable only by the operator's account.
3. Import the jar without placing its content in command arguments:

```bash
jq -n --arg domain youtube.com --rawfile cookiesJar cookies.txt \
  '{domain: $domain, cookiesJar: $cookiesJar, label: "operator-managed session"}' |
  curl --fail-with-body -sS -X POST "$TALE_URL/api/v1/browser-sessions/import" \
    -H "Authorization: Bearer $TALE_API_KEY" \
    -H "X-Organization-Slug: $TALE_ORG_SLUG" \
    -H 'Content-Type: application/json' \
    --data-binary @-
```

A successful import returns HTTP 201 with a `sessionId`. Invalid data returns a validation refusal; a permission failure returns 403. Resolve the named gate rather than granting a broader role just to make the request pass.

## Check and retire sessions

```bash
curl --fail-with-body -sS "$TALE_URL/api/v1/browser-sessions" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG"
```

The list shows metadata such as status, expiry, and failure count. The default lifetime is 14 days; an import can set positive `ttlMs` up to 180 days. Source cookies can expire earlier, so an unexpired pool record does not prove the account session still works.

Blocked retrieval cools a session; repeated blocks can retire it, and a scheduled sweep handles cooled or expired records. A later retry can use another healthy session for the same organization and domain. If no session is available, retrieval can continue without one using the other configured options.

To revoke an imported session, use `DELETE /api/v1/browser-sessions/<sessionId>` with the same organization scope and write permissions. Confirm the ID from the list first. Rotate or revoke the source account's session as well if its cookie jar was exposed. Finally, retry a controlled video and verify the transcript and indexing result; importing cookies alone does not prove ingestion succeeded.

# Run Tale on your infrastructure
Source: https://docs.tale.dev/self-hosted

Self-hosted Tale gives your organization control of the deployment, storage, and model connections. The open-source platform provides the same product functionality used in the enterprise edition. Your team operates the infrastructure and decides which external services it may contact.

For a first installation, follow the [local quickstart](https://docs.tale.dev/self-hosted/install/quickstart): install the published CLI, run `tale init`, then `tale dev`. The guide takes you through the owner account, provider connection and first chat reply. Docker runs the packaged services; no source checkout or build toolchain is required. If `tale --help` lists `doctor`, you can use `tale doctor` to check your machine before creating the project.

## Choose your starting point

| What you need | Start here |
| --- | --- |
| Try a local instance or install a new workspace | [Installation quickstart](https://docs.tale.dev/self-hosted/install/quickstart) |
| Understand services, data, and network connections | [Architecture overview](https://docs.tale.dev/self-hosted/overview) |
| Supply your own Compose or Kubernetes deployment | [Run your own stack](https://docs.tale.dev/self-hosted/install/own-compose) |
| Change the application source | [Contributor setup](https://docs.tale.dev/develop/contributor-setup) |
| Use an instance someone else operates | [Send your first message](https://docs.tale.dev/get-started/quickstart) |

## Plan what your team will operate

Assign responsibility for access, TLS, upgrades, backups, monitoring, and incident response before inviting users. Configure an AI provider and, when you need searchable documents, an embedding model and knowledge storage. Test an upload and a complete chat before treating the instance as ready.

Hosting the application yourself does not keep every request on the same network. A configured model provider, connector, web crawler, or external monitoring destination can receive data. Review the actual destinations in [Security hardening](https://docs.tale.dev/self-hosted/operate/security/hardening) and your provider configuration. An isolated deployment needs locally available images, models, credentials, and dependencies.

## Configure and maintain the instance

Use the [environment reference](https://docs.tale.dev/self-hosted/configuration/environment-reference) for deployment variables and the configuration guides for organization settings. The [container architecture](https://docs.tale.dev/self-hosted/operate/container-architecture) explains operational dependencies; [Backups and restore](https://docs.tale.dev/self-hosted/operate/backups-and-restore) covers recovery planning.

If your team wants Tale to operate the service, read [Tale Cloud](https://docs.tale.dev/cloud). Platform guides apply to both hosting options.

# Install the tale CLI
Source: https://docs.tale.dev/self-hosted/install/cli-install

The `tale` CLI installs, deploys and operates Tale. Install it on the machine where you will run operator commands, then choose the [local quickstart](https://docs.tale.dev/self-hosted/install/quickstart) or the deployment workflow below.

The same CLI owns workspace container operations, managed deployments from exact source commits, and client configuration releases. Your deployment automation selects destination, pins and credential references, then calls the CLI. [Release client configurations](https://docs.tale.dev/self-hosted/configuration/config-releases) covers content from the client's own repository.

For your first instance, use the [quickstart](https://docs.tale.dev/self-hosted/install/quickstart). The ordinary path is `tale init` followed by `tale dev`. You only need a managed deployment specification when your automation must pin exact runtime and client source commits.

## Before you begin

You need:

- A workstation running macOS, Linux, or Windows with PowerShell.
- For local container operations: Docker with Compose and a running Docker daemon.
- For a remote workspace: access to its Docker daemon, usually through an SSH Docker context. The remote operator must be able to run Docker.

The bundled object store currently ships only a `linux/amd64` image. On an ARM64 host, local development and workspace deployment need working amd64 emulation: Docker Desktop includes it; a standalone Linux Docker host needs [QEMU registered on the host](https://docs.docker.com/build/building/multi-platform/#install-qemu-manually). Tale selects the amd64 image but does not install emulation. Managed bundles still require native images for their declared architecture, so an ARM64 managed deployment must wait for a native object-store image.

The installer downloads a release binary from GitHub. It needs access to `raw.githubusercontent.com`, `api.github.com`, `github.com` and the release download destinations that GitHub redirects to.

## Run install-cli.sh or install-cli.ps1

On macOS or Linux:

```bash
curl -fsSL https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.sh | bash
```

On Windows PowerShell:

```powershell
irm https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.ps1 | iex
```

The Unix installer selects the binary for your OS and CPU. By default, it replaces an existing `tale` executable found on `PATH`, or installs into `/usr/local/bin`; it requests `sudo` only when needed to write there. The Windows installer uses `%LOCALAPPDATA%\Programs\tale` by default and updates your user `PATH`.

Release binaries cover macOS on Apple Silicon and Intel, Linux on x86_64 and arm64, and Windows x64. Windows ARM requires x64 emulation. An unsupported Unix architecture produces a build-from-source message.

Set `VERSION` to a release version to pin the install, and `INSTALL_DIR` to choose another destination. In a Unix shell, **export** these variables before running the pipeline so the `bash` process receives them; setting them only before `curl` does not pass them to the installer. In PowerShell, use `$env:VERSION` and `$env:INSTALL_DIR`.

| OS      | Installer script          |
| ------- | ------------------------- |
| macOS   | `scripts/install-cli.sh`  |
| Linux   | `scripts/install-cli.sh`  |
| Windows | `scripts/install-cli.ps1` |

## Verify

```bash
tale --version
```

The CLI prints its installed version. If the command is not found, check the destination in the installer output and ensure that directory is on `PATH`. If an existing Windows terminal still cannot find `tale`, reopen it. If the download fails, check the network destinations above; an optional `GITHUB_TOKEN` environment variable authenticates the release lookup when anonymous GitHub API requests are rate limited.

## Confirm configuration

For workspace container operations, use the project created by `tale init` in the [quickstart](https://docs.tale.dev/self-hosted/install/quickstart). The CLI walks up the directory tree to find its `tale.json`; check the selected project before operating on it:

```bash
tale config show
```

Configuration releases and [managed deployments](https://docs.tale.dev/self-hosted/install/cli-install#managed-deployments) select their sources and destinations explicitly and do not align to a nearby workspace. `config show` keeps its existing local-project behavior.

For a workspace deployment, the host the proxy answers on, TLS settings, and every secret live in the project's `.env`. For production, edit `HOST` there or pass `--host` to `tale deploy`. Local `tale dev` defaults to `localhost`; its `--host` and `--port` flags apply only to that run. To operate a remote workspace host, point your shell's Docker context (or `DOCKER_HOST`) at it. Managed bundle deployment instead runs on its declared destination with the local Docker daemon.

## Run tale deploy

```bash
tale deploy
```

Without `--bundle`, `tale deploy` ships the CLI's own version: it pulls that version's images, restarts affected containers in order and runs schema migrations. Use `tale update` first to choose another workspace version. For independently pinned runtime and client source commits, follow [Managed deployments](https://docs.tale.dev/self-hosted/install/cli-install#managed-deployments).

## Command reference

The CLI groups its commands by what you are doing, the same way `tale --help` does. Each command and its arguments are listed below. How to read the notation:

- A positional argument in `[square brackets]` is **optional**; one in `<angle brackets>` is **required**.
- Required options are named explicitly for configuration releases; other flags are optional unless command help marks them as required.
- A flag written `--flag <value>` **requires a value** when you use it (e.g. `--port 8443`); a bare flag like `--detach` is a boolean switch.
- **Defaults** are shown in parentheses after the description. No default means the flag is off, or the command resolves the value from `.env` / context.

This reference includes commands in the current source code. The published v0.5.70 CLI does not include `tale doctor` or `tale dev --stop`. Run `tale --help` and `tale <command> --help` for the commands and options available in your installed version.

**Global flags** work on every command:

- `--verbose` — verbose output: debug logs and the raw subprocess stream (long form only; there is no `-v`).
- `-q, --quiet` — only warnings and errors.
- `-y, --yes` — assume "yes" for all prompts (non-interactive).
- `--no-color` — disable ANSI colour (also honours `NO_COLOR` / `FORCE_COLOR`).
- `--json`—machine-readable JSON on stdout; supported by `doctor`, `status`, `sandbox status`, every `config` subcommand and managed deployment commands.
- `--ci` — force non-interactive, append-only output (no cursor control).

Commands exit `0` on success, `2` on a usage error, `3` on an unmet precondition (no project, Docker not running, port in use), `4` on a user abort (Ctrl-C, or a required prompt with no terminal), and `5` on an external-dependency failure — so scripts can branch on the cause.

### Setup

`tale doctor` — inspect local startup prerequisites without creating a project, installing software or changing configuration. It checks the Docker daemon, Compose support and Linux-container mode, reports the daemon architecture and checks local ports. A remote Docker context skips local port checks. ARM64 and occupied-port warnings require review; an existing instance may already own a port.

- `-p, --port <port>` — HTTPS port to check (default `443`); the sandbox port `8003` is also checked.
- `--json` — emit the checks as machine-readable JSON.

Docker, Compose, unsupported container-mode failures or selecting HTTPS port `8003` exit `3`. Warnings alone exit `0`; this does not verify image downloads, storage capacity or a model provider. Check a different port with `tale doctor --port 8443`, then use the same port with `tale dev`.

`tale init [directory]` — create a project: it scaffolds the example configs, `AGENTS.md` + a `CLAUDE.md` pointer, and a local-default `.env` (localhost, self-signed certificate, generated secrets). No Docker is needed, and the production domain and TLS are chosen later, at `tale deploy`. In a terminal it asks for a project name when `directory` is omitted, confirms before overwriting an existing project, and asks once whether agents may run `docker` inside sandboxes (default: no — enabling it runs a privileged inner Docker); non-interactive runs skip all prompts. `directory` is optional (default: the current directory).

- `-f, --force` — overwrite an existing `tale.json` instead of aborting.
- `--no-env` — scaffold the project but skip `.env` generation.

`tale dev` — launch all services locally with a self-signed certificate. The selected host and port set the local application origin for this run, without rewriting the production settings in `.env`. Readiness waits for services with health probes to become healthy and the remaining services to be running. If startup times out, inspect the reported service logs before retrying.

- `-d, --detach` — run in the background instead of streaming logs.
- `--stop` — stop this project’s local development containers and preserve their data. Run `tale dev` again to resume.
- `-p, --port <port>` — HTTPS port to expose (default `443`).
- `--host <hostname>` — host alias for the proxy (default `localhost`).
- `-y, --yes` — non-interactive: auto-accept prompts (e.g. installing or starting Docker).

`tale deploy` — deploy the current CLI version with blue-green replacement of application roles. Shared execution services roll in place; database and proxy replacement needs `--stop`. On first deployment, the CLI asks for the production domain and TLS email unless supplied. Read [Upgrades](https://docs.tale.dev/self-hosted/operate/upgrades) before changing an existing installation.

- `--stop` — also update the stop-gated tier (`db`, `proxy`) — recreates those containers, so accept a brief downtime; without it, running `db`/`proxy` are left untouched.
- `-s, --services <list>` — update only these comma-separated services (default: all rotatable services).
- `--host <hostname>` — host alias for the proxy (default: the `HOST` value from `.env`).
- `--override` — overwrite container config from the host workspace (encrypted `*.secrets.json` and `.history/` are always preserved).
- `--override-all` — factory-reseed the builtin catalog into every org server-side; implies `--stop`.
- `-q, --quiet` — suppress container logs during the deploy.
- `-y, --yes` — auto-accept destructive confirmation prompts (e.g. `--override-all`).
- `--skip-backup` — skip the automatic pre-deploy volume snapshot.
- `--dry-run` — preview what would change without touching anything.

### Managed deployments

Use a reviewed deployment specification when the runtime and client configurations must follow exact source commits. Deployment automation selects the destination, credentials and pins and calls the Tale CLI. The CLI acquires source, resolves and verifies image digests, prepares the transfer, preserves supported existing state, takes recovery snapshots when required, rolls the stack, provisions the native instance and verifies configuration content. Keep those deployment internals in Tale.

#### Prepare the runtime and source pins

Run preparation with a compiled CLI built from a clean, committed Tale checkout on Linux, matching the destination's `linux/amd64` or `linux/arm64` architecture. That same executable is included for backend-local provisioning. Preparation needs Git and Docker for source/image verification; applying runs on the destination with its local Docker daemon, retained state directory and environment. The full CLI commit, runtime source commit and client configuration source commit are separate pins. On the destination, the prepared runtime publishes only the proxy's ports 80 and 443 and the two databases on `127.0.0.1:5432` and `127.0.0.1:5433`; the sandbox spawner (8003) and its device hub (8004) stay on the internal network, where the backend and the proxy reach them.

A managed deployment records its recovery point before it changes anything: the pre-deployment snapshot and the bundle being applied, kept in the state directory until the ready receipt is written. An interrupted deployment therefore expects the same bundle on retry and refuses a different one, naming the pending bundle's sha256. When that bundle can no longer complete — a corrected CLI is now pinned, say — declare the named sha256 as `supersedesPendingBundle` in the deployment specification and prepare again: the reviewed bundle takes over the same snapshot, the ready receipt lists it under `supersededBundles`, and the declaration comes out afterwards. That takeover covers the deployment's recovery point, not a runtime rollout in progress. A rollout that stopped after verifying its images — at Compose startup or while waiting for health checks — resumes only with the same prepared runtime (`runtime/runtime.json`) and the same origin, TLS and environment settings; a bundle whose runtime or settings differ is refused, superseding or not, with `A different runtime operation is pending; recover that exact operation first.` Finish it with the bundle that started it before you move the CLI pin in either direction: a different CLI can prepare a different runtime from the same runtime commit. The backend-local phases (`deploy provision`, `deploy export-client-native`) run inside the backend as its own user, the owner of its data directory, and when one fails the deploy result repeats the inner CLI's own summary.

The pre-deployment snapshot also holds the model gateway's store, `llm-gateway-data`, which a newer gateway migrates forward-only the first time it starts on it. A pending deployment that changed nothing records no snapshot; a `supersedesPendingBundle` takeover of it, or a retry that would change the runtime, first takes the snapshot and records it with the pending deployment. A recovery point without the gateway store (a snapshot taken before the CLI captured it, or none after an older CLI's takeover) blocks any rollout that would start a gateway image the store has not run, as the runtime receipt and the gateway container record it: the apply is refused before anything changes, and the pending receipt stays as it was, because a snapshot taken now could already hold a migrated store. Do not remove the receipt. While no runtime rollout is pending, a reviewed bundle that still resolves the gateway image the deployment last ran can take it over with `supersedesPendingBundle`; the rollout after it takes a snapshot that holds the gateway store. Once a runtime rollout is pending, the CLI has no way forward for this state. A rollout on a gateway image the store has already run completes, and warns when its snapshot leaves the store out, or when it has no recovery point at all. A managed deployment never rolls back on its own and restores no volume; it keeps its pending state for recovery.

Managed bundle commands are unavailable on Windows, including `deploy verify-bundle` and backend-local `deploy provision`: their custody checks require POSIX executable modes. Run the complete managed deployment on a Linux host. Ordinary workspace commands and standalone `config build`, `verify`, `stage`, `deploy` and `verify-native` remain available on Windows.

This synthetic specification targets an existing organization and project. Replace its public identifiers and set the named environment values. `revision` accepts a full commit SHA directly or an environment reference; credentials remain references and are resolved privately at the destination. `tlsMode: "external"` means an existing edge handles public TLS; `letsencrypt` additionally requires `tlsEmail`.

For Linux or macOS ARM64 GitHub Actions jobs, use Tale's `.github/actions/setup-cli` composite action. Pin the action itself to a full Tale commit and pass that full commit as its `revision` input. It builds with Bun 1.4.2, verifies the final executable, returns `executable` and adds the binary to `PATH`. macOS builds support general configuration preparation; managed Linux stack preparation still requires a matching Linux executable. Set `linux-baseline: 'true'` on a Linux x64 runner when the destination CPU lacks AVX2 (Intel before Haswell, for example): the default executable aborts there with `Illegal instruction`; the baseline one runs. Other runners refuse the option.

`origin` and individual native `redirectUris` can also use environment references, so a deployment registry can own public addresses. Preparation resolves them to literal validated HTTPS URLs in the bundle.

The example sets `runtime.containerPrefix` to make its environment recognizable in container listings. This optional setting is explained below.

```json
{
  "schemaVersion": 1,
  "name": "example-native",
  "stateDirectory": "/opt/tale-example",
  "composeProject": "tale-example",
  "runtime": {
    "revision": { "env": "TALE_RUNTIME_REF" },
    "platform": "linux/amd64",
    "containerPrefix": "north-desk-prod"
  },
  "origin": { "env": "TALE_PUBLIC_ORIGIN" },
  "tlsMode": "external",
  "identity": {
    "email": { "env": "EXAMPLE_OPERATOR_EMAIL" },
    "password": { "env": "EXAMPLE_OPERATOR_PASSWORD" },
    "slug": "example-team",
    "name": "Example team",
    "ssoEnabled": false,
    "nativeClients": [
      {
        "key": "example-portal",
        "name": "Example portal",
        "clientId": { "env": "EXAMPLE_NATIVE_CLIENT_ID" },
        "redirectUris": [{ "env": "EXAMPLE_PORTAL_CALLBACK" }]
      }
    ]
  },
  "configs": [
    {
      "repository": "https://github.com/example-team/client-app",
      "revision": { "env": "EXAMPLE_CONFIG_REF" },
      "client": "example-team",
      "descriptor": "tale/client.json",
      "automation": "document-review",
      "projectId": "existing-project-id",
      "skillOwner": "native-operator-id"
    }
  ]
}
```

#### Choose the error reporting environment

Managed runtime events default `SENTRY_ENVIRONMENT` to the retained deployment `name`. To use a canonical label such as `example-pr`, declare `"environment": { "SENTRY_ENVIRONMENT": { "env": "TALE_REPORTING_ENVIRONMENT" } }` and set that variable at the destination. The label starts with a lowercase letter or digit and contains 1–64 lowercase letters, digits or hyphens. Browser, backend and sandbox use this label without changing `name`, `composeProject`, `stateDirectory` or stored credentials.

#### Choose container names

Set `runtime.containerPrefix` when you want names such as `north-desk-prod-db` and `north-desk-prod-backend-api` in container listings. The prefix starts with a lowercase letter and uses lowercase letters, digits and single hyphens, up to 40 characters. Spaces, underscores, repeated hyphens and a trailing hyphen are refused.

| Setting | What it identifies |
| --- | --- |
| `runtime.containerPrefix` | Visible container names: `<prefix>-<service>` for every managed service. |
| `name` and `composeProject` | The retained deployment and its Compose project, including volume ownership. |
| `stateDirectory` | The existing deployment state, credentials and recovery records. |

Keep the last two rows unchanged when renaming an existing deployment's containers. The prefix leaves service DNS names unchanged, so internal service addresses continue to use their existing names. Omit it to use the source's container naming policy.

Adding, changing or removing a prefix recreates containers and can briefly interrupt service. Prepare a new bundle, review its dry run, then apply it through the normal snapshot and recovery flow. If application is interrupted, retry that exact bundle; a pending rollout refuses a different bundle. Once the rollout is ready, removing the prefix through another prepared bundle restores the source naming policy.

Run one complete managed runtime per Docker daemon. A name prefix does not allocate separate ports, sandbox networks or host workspaces.

#### Serve additional origins {#managed-additional-origins}

Declare `additionalOrigins` when the same instance also answers on other HTTPS origins, such as a partner domain or the previous hostname during a move. Each entry is a bare HTTPS origin on the default port, or an environment reference that preparation resolves to one. List 1 to 16 distinct origins; none may repeat `origin`.

```json
{
  "origin": "https://desk.example.org",
  "additionalOrigins": [
    "https://desk.partner.example",
    { "env": "TALE_EXTRA_ORIGIN" }
  ]
}
```

The CLI writes the list to the runtime's `ADDITIONAL_SITE_URLS` and manages that variable, so an `environment` entry cannot set it. Every origin is a full entry point with its own sessions, file links, sign-in doors and connector callbacks. With `tlsMode: "letsencrypt"`, the proxy obtains a certificate for each origin, and local hostnames or IP addresses are refused. With `tlsMode: "external"`, your TLS proxy must forward each origin's original `Host` and send `X-Forwarded-Proto: https` from an address the Tale proxy trusts. When that address range is narrower than the private ranges, set `TRUSTED_PROXIES` through an `environment` reference.

The native identity stays on `origin`: account and organization bindings, client journals, the OIDC issuer, passkeys and email links use it alone. An entry may equal `identity.migrateOriginFrom` to keep the previous hostname answering while a migration completes.

Preparation refuses a runtime revision whose proxy cannot trust an external TLS terminator and reports `Runtime does not serve additional origins`. Adding, changing or removing the list recreates the services that read it. After you remove the declaration, applying the next bundle removes the variable. Register each origin's callback URLs with your identity and connector providers, and plan DNS and certificates with [TLS and domains](https://docs.tale.dev/self-hosted/configuration/tls-and-domains#several-domains-at-once).

#### Name who may create organizations {#managed-organization-creators}

A managed deployment refuses organization creation at its proxy for everyone: the organization picker shows no **Create organization** entry, and `POST /api/auth/organization/create` answers 403. To let named people open further workspaces, declare `organizations.creators` — 1 to 64 distinct sign-in addresses, literal or as environment references that preparation resolves.

```json
{
  "organizations": {
    "creators": ["ops@example.org", { "env": "TALE_WORKSPACE_LEAD" }]
  }
}
```

The CLI writes the list to the runtime's `TALE_ORGANIZATION_CREATORS` and manages that variable, so an `environment` entry cannot set it. With the declaration in place the proxy no longer refuses organization creation; the backend judges every caller against the list instead, answers anyone else with `403 ORGANIZATION_CREATION_FORBIDDEN`, and the app shows **Create organization** only to the people named. Addresses are matched case-insensitively, so two spellings of one address are refused as a duplicate.

The managed organization itself is unaffected: the deployment creates it during bootstrap, and a deployment's first organization is always allowed. Remove the declaration and apply the next bundle to restore the proxy refusal and remove the variable. The same variable works on a deployment you run yourself; see the [environment reference](https://docs.tale.dev/self-hosted/configuration/environment-reference).

#### Prepare, verify, and apply the bundle

Set `TALE_DEPLOY_SPEC` to that JSON file, `TALE_DEPLOY_BUNDLE` to a new absolute output directory, and `TALE_CLI_COMMIT` to the compiled CLI's full commit. `DEPLOYMENT_COMMIT` is optional orchestration provenance; omit its flags when unused. Prepare and verify, transfer the whole directory to the destination, then preview and apply there with the same pinned CLI.

```bash
tale --json deploy prepare \
  --spec "$TALE_DEPLOY_SPEC" \
  --deployment-ref "$DEPLOYMENT_COMMIT" \
  --output "$TALE_DEPLOY_BUNDLE"

tale --json deploy verify-bundle \
  --bundle "$TALE_DEPLOY_BUNDLE" \
  --cli-ref "$TALE_CLI_COMMIT" \
  --deployment-ref "$DEPLOYMENT_COMMIT"

tale --json deploy --bundle "$TALE_DEPLOY_BUNDLE" \
  --cli-ref "$TALE_CLI_COMMIT" \
  --deployment-ref "$DEPLOYMENT_COMMIT" --dry-run

tale --json --yes deploy --bundle "$TALE_DEPLOY_BUNDLE" \
  --cli-ref "$TALE_CLI_COMMIT" \
  --deployment-ref "$DEPLOYMENT_COMMIT"
```

`deploy prepare` accepts optional `--sources-file <file>` mapping `repository@fullSHA` to an existing exact checkout. Otherwise it fetches canonical GitHub repositories. Inject the read-only private-client SSH key contents through `TALE_SOURCE_SSH_KEY` only during preparation; the CLI verifies GitHub's SSH host keys over HTTPS and keeps the key out of the bundle and runtime. Registry access must already be available to Docker.

Preparation checks each configuration first, with this CLI's own schemas, and only then pulls and verifies the runtime images. It names each phase and image as it goes. A pack that declares fields this CLI does not know is refused within seconds with `native manifest normalization changes release semantics at <fields>`; prepare it with a CLI at least as new as the Tale the pack targets. A failure the CLI raises deliberately shows its own cause. Any other error keeps a fixed summary, so no credential or registry output reaches the log.

`deploy verify-bundle` checks the complete file inventory and hashes without a destination. `deploy --bundle --dry-run` checks configuration artifacts and destination preconditions without applying changes. Managed bundle deployment does not accept workspace-only overrides such as `--services`, `--host` or `--override-all`. It is a state-preserving stack rollout with health and provenance checks; the workspace blue-green behavior described above is a separate path.

#### Provision the native identity

`deploy provision [--bundle <directory>]` is the backend-local phase normally invoked by bundle deployment. It reads at most 64 KiB of private JSON from stdin, proves the local account and selected organization, and always signs out before reporting success. Its fields include `origin`, `email`, `password`, `slug`, `name`, `ssoEnabled`, optional Entra credentials, and `nativeClients`. Existing-account behavior remains the default. An explicit `identity.bootstrap: "fresh"` permits creation of the initial local account and organization. A bundle binds this choice and the staged configurations before native changes. `deploy provision` refuses workspace flags and `--dry-run`; use read-only bundle/config verification for review. Its optional `--cli-ref` and `--deployment-ref` expectations require `--bundle` and are checked before login.

For an administratively verified fresh operator, explicitly declare `identity.emailVerification: "operator-attested"`. This is an operator assertion of the authenticated account’s email ownership, not proof of mailbox delivery. The backend uses a short-lived native verification token bound to that exact account and email, retaining native hooks without sending email, changing the address or creating another session. It is permitted only with `bootstrap: "fresh"`. Omit it to retain normal native email verification. A previously ready account whose verification changes holds for review.

For a fresh target, replace a config's `projectId` with `project: { "key": "NORTH", "name": "Configuration" }`. Native project keys have 2–6 uppercase letters and names at most 80 characters. `skillOwner: "operator"` transfers a verified source capsule and compiles it for the authenticated native user inside the backend; the host independently checks the resulting artifact. Existing explicit IDs and owner-bound releases retain their exact behavior.

Each native client chooses an existing `clientId` or explicit `managed: true`. Managed creation persists its private intent before the native request, then returns only a private handoff path and SHA for client credentials. Replays preserve IDs, security policy and secrets; uncertain request acceptance without a matching native object holds. Existing clients converge only their display name and HTTPS callback URLs. On maintained 0.5 backends, necessary create/update operations use fixed backend-local auth adapters and close their connections. This enables no public registration/update route, arbitrary module path or secret rotation.

#### Change a managed deployment’s hostname {#managed-origin-migration}

Use the retained managed deployment and its private state directory. This changes the origin bindings of the existing account, organization and clients; it does not move a database or create replacement identities.

1. Set the deployment specification’s `origin` to the new HTTPS origin and `identity.migrateOriginFrom` to the exact previous HTTPS origin, for example `https://old.example.org`. The two origins must differ. Keep `identity.bootstrap: "fresh"`, the same account and organization, and the same managed client keys.
2. Check the retained state before preparing the bundle. Bootstrap must be complete. Every declared email attestation and managed client needs its matching completed journal. Missing, pending or unrelated identity/client journals block migration.
3. Prepare, verify, preview and apply the bundle through the workflow above. The CLI authenticates the retained account and verifies client credentials before updating origin bindings. Completed journals at either declared origin are accepted on retry, preserving IDs and secrets.
4. After the deployment receipt is ready, export consumer configuration for the new issuer. Remove `migrateOriginFrom` from future deployment specifications.

When native configuration is declared, its retained receipt is required too. Migration preserves the organization ID and slug and checks every resource through the normal plan and readback flow. An interrupted configuration write at the new origin resumes only its exact pending plan. A pending configuration receipt at the old origin blocks migration.

To reverse a completed migration, explicitly swap the two origins and repeat the verified deployment workflow. Plan DNS, certificates, callback registrations and access checks with [TLS and domains](https://docs.tale.dev/self-hosted/configuration/tls-and-domains); changing the bundle origin does not perform those external changes.

#### Rename the deploy operator’s address {#managed-operator-address-migration}

A managed deployment signs in as its `identity` operator on every run. To give that account a machine address, so that people sign in with accounts of their own, keep the account and change only its sign-in address. Its user ID, and everything bound to it — managed clients, operator-owned skills, API keys and retained journals — stays.

1. Set `identity.email` to the new address and `identity.migrateEmailFrom` to the exact previous address. The two must differ. Keep `identity.bootstrap: "fresh"` and the account’s password. Bootstrap must be complete, and a declared email attestation needs its completed journal.
2. Prepare, verify, preview and apply the bundle. The CLI reads the retained account’s current address inside the backend, signs in with it and proves the retained user ID. It journals the change, renames the account through the native adapter, ends every session the account holds and signs in again with the new address. The rename is guarded by the previous address, so a concurrent change is refused rather than overwritten. A declared email attestation then verifies the new address.
3. A retry after an interruption finds the address already moved and completes the journals without a second rename. Keeping `migrateEmailFrom` declared afterwards is harmless; remove it once the deployment receipt is ready.

Another account holding the new address, a retained account holding neither address, or a single sign-on link on the operator account stops the deployment before any change. Remove such a link first: it belongs to the person who signed in with it, not to a machine account.

#### Declare a break-glass administrator {#managed-break-glass}

`identity.breakGlass` keeps one administrator for when the deploy operator is unavailable, for example `{ "email": "break-glass@example.org", "passwordHash": { "env": "TALE_BREAK_GLASS_PASSWORD_HASH" } }`. The address is a literal or a required environment reference and must differ from the operator’s current and previous address. The password never reaches the deployment: create its hash where the password is kept, with `tale auth hash-password`, and supply only the hash.

Every deployment makes the backend match the declaration. An absent account is created with a verified address and exactly the declared credential, and a retained journal binds the address to its account ID as soon as the account exists. Later deployments set the bound account back to the declared credential and end every session it held whenever the credential changes, also when they finish an interrupted run. An account at the address that this deployment did not create, or a different account holding it later, stops the deployment. The account becomes an `admin` of the managed organization through the native member endpoints; an `owner` is never changed. The deployment never signs in as this account. Rotate its password by changing the declared hash, not in the application. The deployment records no password-change time, so an organization password rotation policy may ask this account for a new password, which the next deployment sets back.

#### Enforced two-factor sign-in

A managed deployment signs in as its operator with the password alone. When the organization enforces `two_factor_policy`, give the operator a passkey and never an authenticator app: a password sign-in of an account with an authenticator app is answered with a challenge, and an account with neither factor is held at enrolment once its grace period ends. The CLI stops at either answer and names the one it received. People sign in with their own accounts and may use either factor.

#### Export native-client credentials

To hand a managed client’s credentials to a separate application, set `NATIVE_CLIENT_KEY` to its declared key and `PRIVATE_EXPORT_DIRECTORY` to a new private output directory. Its parent must already belong to your account, have mode `0700` and have trusted ancestors. Export from the same ready deployment without interpreting backend paths or container names:

```bash
tale --json deploy export-client --bundle "$TALE_DEPLOY_BUNDLE" \
  --client "$NATIVE_CLIENT_KEY" --output "$PRIVATE_EXPORT_DIRECTORY" \
  --env-prefix TALE_OIDC --cli-ref "$TALE_CLI_COMMIT" \
  --deployment-ref "$DEPLOYMENT_COMMIT"
```

The output directory has mode `0700`. Its regular `0600` files are `client.json`, `receipt.json` and, when `--env-prefix` is selected, `consumer-env.json`. The latter is a literal four-string map: `TALE_OIDC_ISSUER`, `TALE_OIDC_CLIENT_ID`, `TALE_OIDC_CLIENT_SECRET` and `TALE_OIDC_ORG_SLUG`. The issuer is the Tale origin followed by `/api/auth`. Transfer these bytes through your private credential channel and let the application read JSON; do not source the file as shell or publish it as a CI artifact. Stdout contains only safe metadata, paths, sizes and hashes. An identical export is reused only after current ready-state and complete artifact checks; partial, stale or foreign output holds without overwrite.

### Configure the platform

Use `tale config` to manage existing platform settings through the native APIs. Save this declaration as `configuration.json` to set the accent color and a 45-minute idle timeout:

```json
{
  "schemaVersion": 1,
  "resources": [
    {
      "kind": "branding",
      "config": {
        "accentColor": "#336699"
      }
    },
    {
      "kind": "governance",
      "key": "session_idle_timeout",
      "config": {
        "enabled": true,
        "idleTimeoutMinutes": 45
      }
    }
  ]
}
```

Set `TALE_URL` to the instance’s HTTPS origin and `TALE_ORG_ID` to the native organization ID. Provide an authorized session cookie through `TALE_CONFIG_COOKIE`; keep it out of arguments and committed files. Validate locally, save and review the plan, then apply it and compare native state:

```bash
tale --json config validate --file configuration.json
tale --json config plan --file configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID" --output configuration-plan.json
tale --json --yes config apply --file configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID" \
  --plan configuration-plan.json --receipt configuration-receipt.json
tale --json config read --file configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID"
```

The output and receipt directories must already exist. A loopback HTTP connection also needs `--origin` with the instance’s public HTTPS origin. `read` reports `matches` for each declared resource. The plan identifies organization versus instance scope, current and desired hashes, and native side effects. Applying requires the exact declaration and target; a conflicting native edit refuses the write instead of overwriting it. Undeclared resources remain unchanged. There is no delete or arbitrary file-writing command.

These resource kinds use the platform’s shared schemas and native permissions:

| Kind                  | Configuration                                              | Scope        |
| --------------------- | ---------------------------------------------------------- | ------------ |
| `branding`            | Native branding fields                                     | Organization |
| `governance`          | A file-backed policy `key` and its native `config`         | Organization |
| `provider`            | A custom provider definition and optional `expectedModels` | Organization |
| `provider-credential` | Named environment credential metadata                      | Organization |
| `knowledge-embedding` | Provider, model, dimensions, endpoint and server limits    | Organization |
| `deployment`          | Instance deployment settings, including sandbox runtime    | Instance     |

Retention and DSAR policies require their dedicated native workflows. Pause uploads, synchronization and crawls before changing the embedding model. The CLI checks organization-wide document and website counts; it does not lock ingestion or migrate existing vectors. For an organization with documents or registered websites, a model change requires a separate native indexing migration. A change limited to `minSimilarity`, `maxConcurrentRequests`, `minTokensPerSecond`, `maxTokensPerMinute` or `maxRequestsPerMinute` keeps existing vectors valid, so it skips this check. Instance settings also require the native deployment editor allowlist. Standalone application reports `restartRequired` for boot settings; saving those settings alone does not activate them. Review the plan’s effects before applying.

Managed deployments use the same engine through `configuration`. Merge this example into the deployment declaration when an external operator already serves the provider. Replace the synthetic endpoint and catalog with verified values, and inject `EXTERNAL_PROVIDER_SECRET` from your secret manager:

```json
{
  "environment": {
    "TALE_PROVIDER_KEY_EXTERNAL": {
      "env": "EXTERNAL_PROVIDER_SECRET"
    }
  },
  "configuration": {
    "schemaVersion": 1,
    "resources": [
      {
        "kind": "provider",
        "config": {
          "name": "external-chat",
          "displayName": "External chat",
          "apiFormat": "openai",
          "baseUrl": "https://models.example.invalid/v1",
          "catalog": {
            "source": "models-endpoint"
          },
          "embedding": "unknown",
          "auth": [
            {
              "method": "env"
            }
          ]
        },
        "expectedModels": [
          {
            "id": "Example-chat",
            "provider": "external-chat",
            "tags": ["chat"],
            "supportsTools": true,
            "supportsVision": false,
            "contextWindow": 131072
          }
        ]
      },
      {
        "kind": "provider-credential",
        "config": {
          "providerSlug": "external-chat",
          "authMethod": "env",
          "name": "Managed external provider",
          "envName": "TALE_PROVIDER_KEY_EXTERNAL",
          "modelAllowlist": ["Example-chat"]
        }
      }
    ]
  }
}
```

`envName` uses the native `TALE_PROVIDER_KEY_` prefix and 40-character limit. Each alias needs a required `environment` reference. Private endpoints additionally require an explicit `TALE_ALLOW_PRIVATE_PROVIDER_HOSTS` reference whose value is `1`; native host restrictions still apply. `expectedModels` checks Tale’s freshly resolved catalog during readback. It does not prove inference capacity, latency or business output.

Use `governance` with `key: "vision_model"` and native `providerSlug`/`modelId` fields for vision selection. Embedding uses `knowledge-embedding` with `providerSlug`, `model`, `dimensions` and `baseUrl`, plus the optional settings the platform keeps next to the model in [`embedding.json`](https://docs.tale.dev/self-hosted/configuration/data-residency#the-organizations-embedding-model): `minSimilarity`, the assistant's cosine floor for this model, and the server limits `maxConcurrentRequests`, `minTokensPerSecond`, `maxTokensPerMinute` and `maxRequestsPerMinute` ([Pace requests to a self-hosted embedding server](https://docs.tale.dev/self-hosted/configuration/data-residency#embedding-server-capacity)). Each follows the platform's own rule: a value sets it, an omitted key leaves whatever the file holds (a hand-set value survives a release that does not mention it), and `null` clears it — `"minSimilarity": null`, for example, is the only way to remove a floor through the CLI. To replace a default credential, also declare the existing environment credential with `isDefault: false`; the CLI applies that explicit change first. Credential values never enter the declaration or receipt.

Native provisioning runs after identity and before configuration releases. The `native.configuration` receipt binds the declaration and bundle hashes, organization, resource hashes and native revisions. Writes retain a pending receipt before the first change; if a later resource fails, earlier changes may remain. Read the native state and retained receipt, then retry the same reviewed plan. Native compare-and-set protects each resource against concurrent admin changes; there is no cross-resource transaction. Keep deployment state, snapshots and receipts for recovery.

Managed deployments also activate a declared `deployment` resource before reporting ready. The CLI records the pending activation, drains the verified sandbox spawner for up to five minutes, and restarts that container once sessions have finished. If sessions remain, the operation stays pending. The `configurationActivation` receipt records the mounted configuration and observed container boot; ready requires fresh health checks. Retrying an interrupted operation verifies an already accepted restart, and an unchanged ready replay does not restart the service again.

#### Replace a pending configuration plan

If an interrupted plan can still complete, retry that same plan. Use explicit replacement when its declared settings can no longer work, for example because an embedding endpoint is no longer available. Keep the existing receipt: it records writes that may already have reached the platform.

1. Read the pending receipt and compare the declared resources with current native state. Prepare `replacement-configuration.json` with corrected settings, the same target and exactly the same resource identities. You cannot use replacement to add or drop resources.
2. Calculate the hash of the retained receipt’s `plan`, not the whole receipt or the replacement plan. The following command requires Bun and hashes canonical JSON: object keys sorted recursively, array order preserved, and no whitespace.

```bash
PENDING_PLAN_SHA=$(bun -e '
  const receipt = await Bun.file(process.argv[1]).json();
  if (receipt.phase !== "pending") throw new Error("Receipt is not pending");
  function canonical(value) {
    if (Array.isArray(value)) return "[" + value.map(canonical).join(",") + "]";
    if (value !== null && typeof value === "object") {
      return "{" + Object.keys(value).sort().map(key =>
        JSON.stringify(key) + ":" + canonical(value[key])
      ).join(",") + "}";
    }
    return JSON.stringify(value);
  }
  console.log(new Bun.CryptoHasher("sha256")
    .update(canonical(receipt.plan)).digest("hex"));
' configuration-receipt.json)
```

3. Create a fresh plan from the replacement declaration and review it before applying:

```bash
tale --json config plan --file replacement-configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID" --output replacement-plan.json
```

After reviewing the plan, apply it with the original receipt path and the retained plan’s hash:

```bash
tale --json --yes config apply --file replacement-configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID" \
  --plan replacement-plan.json --receipt configuration-receipt.json \
  --supersedes-pending-plan "$PENDING_PLAN_SHA"
tale --json config read --file replacement-configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID"
```

Each resource must still match the pending plan’s original state, intended write, or verified result. An unrelated native edit blocks replacement before any write. Resolve that difference with the administrator who made it; do not remove the receipt to bypass the check.

The receipt retains the previous plan and its verified resources under `superseded`, including across interruption and replay. Check that the receipt reaches `phase: "ready"` and that `config read` reports matching resources. Omit the one-shot selector from later operations.

For a managed deployment, set `supersedesPendingConfigurationPlan` to the same retained plan hash in the deployment specification, alongside the corrected `configuration`, then prepare and review a new bundle. If that bundle also replaces a pending rollout, select its hash separately with `supersedesPendingBundle`. That bundle selector alone does not authorize replacing a native configuration plan. Remove both recovery selectors from later specifications after the operation is ready.

The public `native.configuration` proof records each resource’s intended hash as `configurationSha256` and its native readback hash as `observedConfigurationSha256`. These can differ when a setting preserves an existing value, such as an omitted embedding similarity floor or server limit. The private receipt retains the exact observed state for recovery.

### Operate

`tale status` — show the current deployment status. No arguments.

`tale logs <service>` — stream a service's logs (`service` is one of the running services; on a dev-only stack with no deployment, it falls back to the dev container).

- `-f, --follow` — follow log output as it is written.
- `-n, --tail <lines>` — show only the last N lines.
- `--since <duration>` — show logs since a relative time (e.g. `1h`, `30m`).
- `-c, --color <color>` — target a specific deployment colour (`blue` or `green`).
- `--raw` — stream raw, unfiltered log output (no classification).

`tale backup` — snapshot the supported, existing project volumes. No arguments. External databases and buckets need separate backups; see [Backup coverage](https://docs.tale.dev/self-hosted/operate/backups-and-restore).

`tale restore [snapshot-id]` — restore a snapshot; omit the id to list available snapshots.

- `--stop` — stop running project containers before restoring.
- `-y, --yes` — skip the confirmation prompt.

`tale rollback` — roll back to the previous patch version (patch-level only). Prompts for confirmation before it touches anything.

- `-y, --yes` — skip the confirmation prompt (required when running non-interactively).

### Maintain

`tale update`—move a workspace instance to a new version: update the CLI binary, then sync project files; run `tale deploy` afterward. Workspace commands align to that version. Managed bundles and configuration releases retain their separately pinned CLI revision.

- `-v, --version <version>` — update to this exact version (e.g. `0.9.0`) instead of the latest; allows downgrades.
- `-f, --force` — force re-sync and overwrite locally modified project files.
- `--dry-run` — show what would change without modifying anything.

`tale migrate` — re-provision the built-in defaults for every organization against the running deployment — the same idempotent step every deploy runs, on demand. Schema migrations are not a command: the backend applies them at boot, so a deployed container is always at its own schema.

- `--dry-run` — show what would run without executing it.

`tale cleanup` — remove inactive (non-current colour) containers. No arguments.

`tale reset` — remove all blue-green containers.

- `-f, --force` — skip the confirmation prompt.
- `-a, --all` — also remove the stateful infrastructure containers.
- `--dry-run` — preview the reset without making changes.

`tale uninstall` — remove the `tale` CLI binary from this system. It prompts before deleting anything and _offers_ to also disconnect this machine's [sandbox device](https://docs.tale.dev/self-hosted/install/cli-install#sandbox-device), remove `~/.tale-daemon` left by the retired `tale daemon`, and tear down a project's Docker resources and files. Without `--purge`, a project and its containers are left intact — run `tale reset --all` inside one to remove those. If the sandbox device cannot be stopped, nothing is uninstalled.

- `-f, --force` — skip the confirmation prompt (removes the binary only; the optional cleanups still need `--purge`).
- `--purge` — also disconnect the sandbox device and delete its workspaces, remove `~/.tale-daemon` and, for a project found from the current directory, tear down its Docker resources and delete its files. Irreversible.
- `--dry-run` — show what would be removed without removing anything.

`tale config show`—print the resolved local project directory and CLI version. Outside a project, it reports that no project was found and exits successfully.

### Configuration releases

These commands use the selected CLI revision without instance alignment or Docker operations. [Release client configurations](https://docs.tale.dev/self-hosted/configuration/config-releases) covers descriptors, source commits, credentials and recovery. The default release identity is the full source SHA: manifest schema 4/compiler 3, with `releaseRef === sourceCommit`. Native integer automation versions remain separate.

`build`, `verify` and `stage` require `--repo <directory>`, `--descriptor <path>` and `--automation <name>`. The descriptor is repository-relative. A verification manifest may be absolute or repository-relative.

| Command              | Required options                             | Optional options                                                                                                          |
| -------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `tale config build`  | `--source-commit <sha>`                      | `--skill-owner <user-id>` (required for owned skills), `--output <directory>`, compatibility `--config-version <version>` |
| `tale config verify` | `--manifest <path>`                          | `--rebuild` for exact offline reconstruction                                                                              |
| `tale config stage`  | `--config-ref <sha>`, `--output <directory>` | `--skill-owner <user-id>`, `--client <name>`, `--deployment-ref <sha>`                                                    |

Source staging requires checkout `HEAD` at that full commit and output outside the checkout. It rebuilds committed content without a generated catalogue commit. Explicit `stage --config-version` instead selects the compatibility catalogue path and requires `--catalogue-commit`, `--catalogue-repository`, `--client` and `--ops-commit`. Do not mix `--config-ref` and `--config-version`.

Native commands require `--stage <directory>`, `--url <origin>`, `--org <id>` and `--project <id>`. HTTPS is required except for loopback HTTP; use `--origin <origin>` for the canonical browser origin behind a proxy. Both read `TALE_CONFIG_COOKIE` only from the environment.

| Command                     | Required options          | Optional options                                       |
| --------------------------- | ------------------------- | ------------------------------------------------------ |
| `tale config deploy`        | `--receipt <path>`        | Global `--yes` for an authorized unattended deployment |
| `tale config verify-native` | No extra required options | `--native-version <number>`, `--allow-retained`        |

Both native commands accept exact expectations through `--config-ref`, `--source-repository`, `--artifact-sha256`, `--deployment-ref`, `--client` and `--automation`. Historical catalogue expectation flags remain available for compatibility. `verify-native` is read-only; `--allow-retained` verifies an explicitly selected retained version without claiming it is deployed. Without `--native-version`, verification selects the latest saved version. The native API exposes the task contract only for the deployed version, so retained verification cannot attest that field.

Configuration commands have no `--dry-run`: use `stage`, `verify --rebuild` and `verify-native`. Success JSON is `{ok:true,command:"config <verb>",data}`. Build and verify data include `automationName`, `releaseRef`, `sourceCommit`, `artifactSha256`, `artifactPath` and `verified`; compatibility output uses `configVersion` instead of `releaseRef`. SHA stage and native receipts use schema 2. A deploy result includes `automationVersion` and `unchanged`; the explicit `verified` field belongs to verification output.

### Sandbox device

These commands run your Tale organization's sandboxes on the machine where you run them. [Run sandboxes on your own devices](https://docs.tale.dev/platform/admin/sandbox-devices) covers adding a device under **Settings > Sandboxes**, which hands out the `connect` command. The device keeps its configuration and workspaces in `~/.tale/sandbox`; `TALE_SANDBOX_HOME` moves them.

`tale sandbox connect <site> --token <token>` — connect this machine to the organization that issued the token: it checks Docker (and offers to install it), registers the machine, and starts the device's containers at the server's release. `site` is your Tale site, such as `https://your-org.tale.dev`. The token (`tsdj_…`) works once, within an hour. Linux and macOS only.

- `--name <name>` — the name Tale shows for the device (default: the machine's hostname). Characters other than `A`–`Z`, `a`–`z`, digits, `.`, `-` and `_` become dashes.
- `--max-sessions <n>` — how many sandboxes run here at once, from 1 to 256 (default: one per two CPUs and per 4 GiB of memory Docker can use, at most 16).
- `--no-auto-update` — do not follow the server's release automatically; run `tale sandbox update` after each Tale update instead.
- `--docker-socket <path>` — the Docker socket the device's containers use, for rootless Docker (default: `/var/run/docker.sock`).

`tale sandbox status` — show the device's connection, organization, release and containers, and the sandboxes running now. No arguments.

`tale sandbox update` — move the device to the server's release now, and take the server's current addresses for its sandboxes (needed after the backend or model gateway address changed). No arguments.

`tale sandbox logs` — show the device's log.

- `-f, --follow` — keep printing new lines.
- `--tail <lines>` — how many lines to show first (default: `200`).

`tale sandbox disconnect` — remove the device from its organization, stop its sandboxes and delete their workspaces from this machine. It prompts first, and changes nothing while Docker is not running. If the server cannot be reached, the machine is cleaned up anyway, and an admin removes the device under **Settings > Sandboxes**.

- `--keep-data` — keep the workspaces on this machine.
- `-f, --force` — skip the confirmation prompt.

### Advanced

`tale auth hash-password` — print the Better Auth hash of a password, for a [break-glass administrator](https://docs.tale.dev/self-hosted/install/cli-install#managed-break-glass).

It reads the password from stdin, or from a hidden prompt with confirmation in an interactive terminal. It refuses a password that fails the platform’s default password policy and prints nothing but the hash.

`tale auth reset-owner` — reset the owner account credentials.

For a manual recovery, run it without flags in an interactive terminal to enter the new password through a masked prompt. This avoids putting the password in shell history or command arguments. The reset invalidates existing sessions.

- `-e, --email <email>` — set a new owner email address.
- `-p, --password <password>` — set a new owner password.

## Troubleshooting

- **`tale deploy` targets the wrong machine.** The CLI uses your shell's Docker context / `DOCKER_HOST`. Switch with `docker context use …` (or set `DOCKER_HOST`) so it points at the intended host, then re-run.
- **`tale deploy` uses the wrong host alias.** The host the proxy answers on comes from `HOST` in the project's `.env`, not a separate CLI store. Edit `.env` or pass `--host` to override it for one run.
- **Installer fails on macOS because the binary cannot execute.** When the freshly installed binary refuses to run (e.g. Gatekeeper kills it), the installer fails with recovery hints instead of reporting success — follow them, then re-run the installer.
- **`tale` not found after install on Linux.** The installer drops the binary in `/usr/local/bin`; verify the directory is on the user's `PATH` (`echo $PATH`).

For ongoing operations, use [Upgrades](https://docs.tale.dev/self-hosted/operate/upgrades), [Backups and restore](https://docs.tale.dev/self-hosted/operate/backups-and-restore), or [Container architecture](https://docs.tale.dev/self-hosted/operate/container-architecture).

# Create the first owner account
Source: https://docs.tale.dev/self-hosted/install/first-admin

On an empty instance, Tale’s setup flow creates the first account and organization. That account becomes the Owner. Complete this step while you still control access to the new instance, before sharing its address with others.

## Confirm the instance is ready

Open the address printed by `tale dev`, or the configured `SITE_URL` for a deployment, and check the certificate and hostname. For a CLI deployment, run `tale status`; for a deployment you maintain yourself, inspect its services and probes. An unhealthy backend needs [troubleshooting](https://docs.tale.dev/self-hosted/operate/observability/troubleshooting) before account setup.

A login page instead of setup usually means an account already exists. This is expected in a seeded development environment. Do not erase the database to recover access; sign in with the existing account or ask an administrator to add your account.

## Complete setup

Open the instance URL. Follow the setup flow to create your account and name the organization. Keep your sign-in credentials in a password manager.

After creating the account and organization, use the setup completion page’s provider link or open **Settings > AI providers**. Without a provider you can inspect the app, but a real model reply still needs valid credentials and an available model. Follow [AI providers](https://docs.tale.dev/platform/admin/providers) when you are ready to connect one.

## Confirm ownership

Open **Settings > Members** and verify that your account has the **Owner** role. The organization name and account should match the instance you intended to initialize.

<Frame caption="Check the owner and each member’s role before giving the team access.">

![The organization members page lists people and their assigned roles.](https://docs.tale.dev/images/get-started/settings-organization-members.webp)

</Frame>

Sign out and sign in again to verify the credentials independently of the setup session. Keep another tested administrative recovery path before changing authentication settings.

## Add teammates {#invite-teammates}

Add people through **Settings > Members** and choose their roles deliberately. For a new account, the form sets an initial password; an existing account keeps its credentials. This flow does not send an invitation email. Share initial credentials through a secure channel. Public self-service registration closes after the first account. Corporate SSO and provisioning have their own [setup and membership rules](https://docs.tale.dev/platform/admin/enterprise-sso).

The backend enforces that, not only the proxy in front of it: once any account exists, `/api/auth/sign-up/email` answers 403. This matters because the backend is also reachable from the agent sandbox network, which the proxy never sees, so code running in an agent session cannot create accounts either. **Settings > Members** creates accounts server-side and is unaffected. A throwaway test deployment that needs the open route sets `TALE_ALLOW_OPEN_SIGN_UP=true`; never set it on a real one.

Creating a further organization is open to every signed-in user unless you name who may do it: set `TALE_ORGANIZATION_CREATORS` to their sign-in addresses, and everyone else loses the **Create organization** entry in the organization picker and is refused at the API with `403 ORGANIZATION_CREATION_FORBIDDEN`. The first organization is always allowed, so setup is not affected. A managed deployment declares the same list as `organizations.creators` in its specification; see [Install the tale CLI](https://docs.tale.dev/self-hosted/install/cli-install#managed-organization-creators) and the [environment reference](https://docs.tale.dev/self-hosted/configuration/environment-reference).

Use [Members and roles](https://docs.tale.dev/platform/admin/members-and-roles) to choose access. Then [send your first message](https://docs.tale.dev/get-started/quickstart) and verify a completed reply. Create a [project agent](https://docs.tale.dev/tutorials/editor/first-agent-end-to-end) when you are ready to delegate a task. A working dashboard confirms access to the application; it does not verify the model provider or every background service.

# Choose an installation method
Source: https://docs.tale.dev/self-hosted/install

Use the Tale CLI for the standard workspace installation. Choose a custom stack when your infrastructure tooling must own the service definitions. Both paths need the same application services and an operator responsible for configuration and maintenance.

## Install with the CLI

The [quickstart](https://docs.tale.dev/self-hosted/install/quickstart) takes you through the prerequisites, project creation, startup, and first sign-in. `tale init` prepares a project directory; `tale dev` starts a development instance and `tale deploy` deploys that workspace.

The CLI manages container operations, but you still own the project's configuration, credentials, volumes, and updates. Keep the project directory and its deployment settings together. [Install the CLI](https://docs.tale.dev/self-hosted/install/cli-install) covers supported systems, remote Docker access, commands, and managed deployment options.

## Use your own service definitions

[Run your own stack](https://docs.tale.dev/self-hosted/install/own-compose) describes the services, volumes, networking, readiness checks, and boot order you must preserve. Use it when maintaining Compose yourself. [Deploy on Kubernetes](https://docs.tale.dev/self-hosted/install/kubernetes) translates that contract into Deployments, Services, and NetworkPolicies, and lists the checks a cluster must pass. Tale does not ship an official Helm chart.

For changes to Tale's source code, follow [Contributor setup](https://docs.tale.dev/develop/contributor-setup) instead of starting with a production deployment.

## Complete the first setup

After the instance is ready, [create the first administrator](https://docs.tale.dev/self-hosted/install/first-admin), connect a provider, and test a chat. Add team members through [Members and roles](https://docs.tale.dev/platform/admin/members-and-roles), using the account and sign-in options available in your organization.

Before using production data, configure TLS and backups, confirm the [environment settings](https://docs.tale.dev/self-hosted/configuration/environment-reference), and read the [operating architecture](https://docs.tale.dev/self-hosted/operate/container-architecture).

# Deploy on Kubernetes
Source: https://docs.tale.dev/self-hosted/install/kubernetes

Tale runs on Kubernetes when you translate the [service contract](https://docs.tale.dev/self-hosted/install/own-compose) into Deployments, Services, and volumes and switch the sandbox spawner to `SANDBOX_BACKEND=kubernetes`. There is no official Helm chart. This guide carries a complete manifest set for one namespace, verified end to end with Tale 0.5.31 on a single-node cluster, together with the checks that prove the result. You own the cluster, its storage, its public entry point, and the rollout procedure.

## Check the prerequisites

| Requirement | Why it matters |
| --- | --- |
| A CNI that enforces NetworkPolicy, such as Calico, Cilium, or kube-network-policies | The sandbox egress fence and the backend fence are NetworkPolicy objects. Every API server accepts them; only the CNI makes them block traffic. |
| A default StorageClass whose `ReadWriteOnce` volumes re-bind where a Pod is scheduled | The database, the object store, the proxy certificates, the gateway state, and every sandbox workspace live on PersistentVolumeClaims. A deleted sandbox workspace's volume follows the StorageClass's `reclaimPolicy`: with `Delete`, its files go with it; with `Retain`, they stay until you remove the volume. |
| `ReadWriteMany` storage, or a single node, for the organization configuration | The backend roles write `config-data`; the web tier and the spawner read it. `ReadWriteOnce` is enough on one node. Several nodes need `ReadWriteMany` or a node pin for those Pods. |
| Nodes that grant `NET_ADMIN` and provide ip6tables, or allow the IPv6 sysctls | The egress proxy installs its firewall at start and refuses to start without it. |
| Ports 80 and 443 reachable at the public address | Caddy obtains certificates itself in `selfsigned` and `letsencrypt` mode. Behind an Ingress that terminates TLS, set `TLS_MODE=external`. |
| Pull access to `ghcr.io/tale-project/tale/*` on every node, including the sandbox runtime image | Session Pods start from `SANDBOX_RUNTIME_IMAGE`. A node that cannot pull it fails the first session scheduled there. |
| A sysbox or kata RuntimeClass if agents need Docker inside their sandbox | Without one, keep `SANDBOX_DOCKER_IN_CONTAINER=false`. The `runc` tier would need privileged Pods. |
| `kubectl` and `envsubst` on the machine that applies the manifests | The manifests carry one `${VERSION}` variable that kubectl does not expand. |

Reserve memory for the application roles plus one agent session per concurrent task; `SANDBOX_AGENT_MEMORY` and the other session limits are in the [environment reference](https://docs.tale.dev/self-hosted/configuration/environment-reference#sandbox-infrastructure).

## Lay out the namespace

Every service runs in one namespace, `tale`. Session Pods must reach `backend-api` and `sandbox-llm-gateway` directly, and the egress fence the spawner installs allows only the namespace it runs in, so the application roles belong there too. The Service names equal the Compose service names: the images resolve `db`, `knowledge-db`, `object-store`, `backend-api`, `platform`, `sandbox`, `sandbox-egress`, `sandbox-llm-gateway` with its `llm-gateway` alias, and `bgutil-provider` by name.

<Warning>

Every Pod below sets `enableServiceLinks: false`. Kubernetes otherwise injects Docker-style variables for each Service in the namespace, such as `SANDBOX_PORT=tcp://10.96.6.49:8003` and `DB_PORT=tcp://10.96.150.113:5432`. The spawner reads `SANDBOX_PORT` as its listen port and exits at start, and the platform image derives its database URL from `DB_PORT`.

</Warning>

| Compose service | Kubernetes objects | Notes |
| --- | --- | --- |
| `db` with the `knowledge-db` alias | StatefulSet `db`; Services `db` and `knowledge-db` selecting the same Pod | `TALE_DB_ROLE` stays unset: the image creates both databases and applies the knowledge migrations, and the backend migrates the application schema at boot. An in-memory `emptyDir` of 256 MiB serves `/dev/shm`. The image stops on `SIGINT` within 60 seconds of grace. |
| `object-store` | Deployment with strategy `Recreate`, PVC at `/data`, Service on 9000 | The backend creates the bucket at boot. |
| `platform` | Deployment; Service on 3000 | `config-data` read-only, `TALE_BACKEND_URL=http://backend-api:3005`. |
| `backend-api` | Deployment with two replicas; Service on 3005 | `config-data` read-write. Two replicas give a rollout without a gap. |
| `backend-worker` | Deployment | No Service and no HTTP probe. |
| `proxy` | Deployment with strategy `Recreate`; `hostPort` 80 and 443; PVC for `/data` | The certificate store survives restarts on the PVC. |
| `sandbox` | ServiceAccount, Role, RoleBinding, Deployment; Service on 8003 | `SANDBOX_BACKEND=kubernetes`; `config-data` read-only at `/app/platform-config`. No Docker socket. |
| `sandbox-egress` | Deployment; Service on 3128 | The shipped capability set, no sysctls. |
| `sandbox-llm-gateway` | Deployment with strategy `Recreate`, PVC at `/app/data`; Services `sandbox-llm-gateway` and `llm-gateway` on 8080 | The image runs as uid 1000; `fsGroup: 1000` lets it write its state. It reads `SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD` from `tale-env`: until it has an admin account, it creates one only for a caller that presents that secret. |
| `bgutil-provider` | Deployment; Service on 4416 | Optional video-token provider. |

The probes translate the Compose health checks:

| Service | Startup probe | Readiness probe | Liveness probe |
| --- | --- | --- | --- |
| `backend-api` | `GET /ping` on 3005, allow five minutes for migrations | `GET /ready` on 3005 | `GET /ping` on 3005 |
| `platform` | `curl -sf http://localhost:3000/api/health && [ -f /tmp/platform-ready ]`, allow three minutes | the same command | none |
| `db` | `pg_isready -U tale -d tale && [ -f /tmp/.db_ready ]`, allow three minutes | the same command | `pg_isready -U tale -d tale` |
| `object-store` | none | `mc ready local` | none |
| `proxy` | none | `GET /health` on 2020 | none |
| `sandbox` | `GET /health` on 8003 | `GET /health` on 8003 | none |
| `sandbox-egress` | none | `curl -sS -o /dev/null --max-time 3 --noproxy '*' http://127.0.0.1:3128/` | none |
| `sandbox-llm-gateway` | none | `GET /health` on 8080 | none |

Kubernetes has no `depends_on`. A backend role that starts before Postgres answers exits once with `ECONNREFUSED`, and the restart policy heals it.

## Prepare the manifests

Save each YAML block in the following sections as the file named in its first line, in one directory. Edit the Secret: replace every `<...>` placeholder and set `HOST`, `SITE_URL`, `TLS_MODE`, and `OBJECT_STORE_PUBLIC_ENDPOINT` for your address. If that address carries a non-standard port, also set it as the proxy's `containerPort` and `hostPort` in `30-proxy.yaml`; Caddy listens on the port in `SITE_URL`. Then pin one release for every Tale image, `0.5.31` at the time of writing, and apply the files in order:

```bash
export VERSION=0.5.31
for f in 00-namespace.yaml 10-stores.yaml 20-application.yaml 30-proxy.yaml 40-sandbox.yaml; do
  envsubst '${VERSION}' < "$f" | kubectl apply -f -
done
```

`envsubst` replaces only `${VERSION}`; every other value in the files is literal. The same loop applies an upgrade: change `VERSION`, run it again, and the Deployments roll to the new image.

## Create the shared environment

The first file holds the namespace, the deployment-wide values from the Compose `.env`, and the shared configuration claim. Generate each secret once and keep it; `ENCRYPTION_SECRET_HEX` in particular must stay stable for existing encrypted values. The [environment reference](https://docs.tale.dev/self-hosted/configuration/environment-reference) explains every variable.

```yaml
# 00-namespace.yaml
apiVersion: v1
kind: Namespace
metadata: { name: tale }
---
apiVersion: v1
kind: Secret
metadata: { name: tale-env, namespace: tale }
type: Opaque
stringData:
  HOST: tale.example.com
  SITE_URL: https://tale.example.com
  TLS_MODE: letsencrypt
  POSTGRES_USER: tale
  POSTGRES_DB: tale
  DB_PASSWORD: <generated>
  DATABASE_URL: postgresql://tale:<DB_PASSWORD>@db:5432/tale_app
  KNOWLEDGE_DB_NAME: tale_knowledge
  INSTANCE_SECRET: <openssl rand -hex 32>
  BETTER_AUTH_SECRET: <openssl rand -hex 32>
  ENCRYPTION_SECRET_HEX: <openssl rand -hex 32>
  TALE_AUDIT_PEPPER: <openssl rand -hex 32>
  SANDBOX_TOKEN: <openssl rand -hex 32>
  SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD: <generated>
  OBJECT_STORE_ACCESS_KEY: tale
  OBJECT_STORE_SECRET_KEY: <generated>
  OBJECT_STORE_BUCKET: tale-blobs
  OBJECT_STORE_ENDPOINT: http://object-store:9000
  OBJECT_STORE_REGION: us-east-1
  OBJECT_STORE_PUBLIC_ENDPOINT: https://tale.example.com
---
# Organization configuration: backend roles write, platform and spawner read.
# ReadWriteOnce is enough on one node; several nodes need ReadWriteMany.
apiVersion: v1
kind: PersistentVolumeClaim
metadata: { name: config-data, namespace: tale }
spec:
  accessModes: [ReadWriteOnce]
  resources: { requests: { storage: 2Gi } }
```

`DATABASE_URL` carries the same password as `DB_PASSWORD`; the knowledge connection defaults to `knowledge-db:5432/tale_knowledge` with that password. `SITE_URL` must match the address in the browser, including a non-standard port.

## Run the stores

The StatefulSet keeps the data volume across Pod replacements and gives the image the shutdown it expects. MinIO runs as a single Deployment on its own claim.

```yaml
# 10-stores.yaml
apiVersion: v1
kind: Service
metadata: { name: db, namespace: tale }
spec:
  selector: { app: db }
  ports: [{ name: pg, port: 5432, targetPort: 5432 }]
---
apiVersion: v1
kind: Service
metadata: { name: knowledge-db, namespace: tale }
spec:
  selector: { app: db }
  ports: [{ name: pg, port: 5432, targetPort: 5432 }]
---
apiVersion: apps/v1
kind: StatefulSet
metadata: { name: db, namespace: tale }
spec:
  serviceName: db
  replicas: 1
  selector: { matchLabels: { app: db } }
  template:
    metadata: { labels: { app: db } }
    spec:
      enableServiceLinks: false
      terminationGracePeriodSeconds: 60
      containers:
        - name: postgres
          image: ghcr.io/tale-project/tale/tale-db:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          ports: [{ name: pg, containerPort: 5432 }]
          volumeMounts:
            - { name: data, mountPath: /var/lib/postgresql/data }
            - { name: shm, mountPath: /dev/shm }
          startupProbe:
            exec: { command: [sh, -c, 'pg_isready -U tale -d tale && [ -f /tmp/.db_ready ]'] }
            periodSeconds: 5
            failureThreshold: 36
          readinessProbe:
            exec: { command: [sh, -c, 'pg_isready -U tale -d tale && [ -f /tmp/.db_ready ]'] }
            periodSeconds: 5
          livenessProbe:
            exec: { command: [sh, -c, 'pg_isready -U tale -d tale'] }
            periodSeconds: 15
          resources:
            requests: { cpu: 250m, memory: 512Mi }
      volumes:
        - name: shm
          emptyDir: { medium: Memory, sizeLimit: 256Mi }
  volumeClaimTemplates:
    - metadata: { name: data }
      spec:
        accessModes: [ReadWriteOnce]
        resources: { requests: { storage: 20Gi } }
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata: { name: object-store-data, namespace: tale }
spec:
  accessModes: [ReadWriteOnce]
  resources: { requests: { storage: 20Gi } }
---
apiVersion: v1
kind: Service
metadata: { name: object-store, namespace: tale }
spec:
  selector: { app: object-store }
  ports: [{ name: s3, port: 9000, targetPort: 9000 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: object-store, namespace: tale }
spec:
  replicas: 1
  strategy: { type: Recreate }
  selector: { matchLabels: { app: object-store } }
  template:
    metadata: { labels: { app: object-store } }
    spec:
      enableServiceLinks: false
      terminationGracePeriodSeconds: 30
      containers:
        - name: minio
          image: ghcr.io/tale-project/ops/minio:RELEASE.2025-04-22T22-12-26Z
          args: ['server', '/data', '--address', ':9000', '--console-address', ':9001']
          env:
            - name: MINIO_ROOT_USER
              valueFrom: { secretKeyRef: { name: tale-env, key: OBJECT_STORE_ACCESS_KEY } }
            - name: MINIO_ROOT_PASSWORD
              valueFrom: { secretKeyRef: { name: tale-env, key: OBJECT_STORE_SECRET_KEY } }
            - { name: MINIO_BROWSER, value: 'off' }
          ports: [{ name: s3, containerPort: 9000 }]
          volumeMounts: [{ name: data, mountPath: /data }]
          readinessProbe:
            exec: { command: [sh, -c, 'mc ready local'] }
            periodSeconds: 10
          resources:
            requests: { cpu: 100m, memory: 256Mi }
      volumes:
        - name: data
          persistentVolumeClaim: { claimName: object-store-data }
```

For an external Postgres, set `DATABASE_URL` and `KNOWLEDGE_DATABASE_URL` as described in [Connect external stores](https://docs.tale.dev/self-hosted/install/own-compose#connect-external-stores) and drop the StatefulSet and its Services; for an external bucket, set the `OBJECT_STORE_*` values and drop the MinIO objects.

## Run the application roles

The three roles share the platform image: the API and the worker write `config-data`, the web tier reads it. The file also carries the optional video-token provider the worker uses; remove its two objects if you do not ingest videos.

<Warning>

The backend roles run without `NET_ADMIN` and with `TALE_SKIP_SSRF_FIREWALL=1`. With that capability the image installs its iptables egress fence, which accepts only the subnets the Pod is directly connected to and rejects the rest of the private address space. On a Pod network that rejects the cluster DNS and every Service address, so the role fails with `getaddrinfo EAI_AGAIN db` and restarts until you remove the capability. The NetworkPolicy at the end of the file provides the fence instead: the roles reach every peer in the namespace, the cluster DNS, and the public internet, and never the cloud metadata service, the nodes, or private networks. Extend its last rule when your model providers or connectors live on a private range.

</Warning>

```yaml
# 20-application.yaml
apiVersion: v1
kind: Service
metadata: { name: backend-api, namespace: tale }
spec:
  selector: { app: backend-api }
  ports: [{ name: http, port: 3005, targetPort: 3005 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: backend-api, namespace: tale }
spec:
  replicas: 2
  selector: { matchLabels: { app: backend-api } }
  template:
    metadata: { labels: { app: backend-api, tale.tier: backend } }
    spec:
      enableServiceLinks: false
      terminationGracePeriodSeconds: 45
      containers:
        - name: backend-api
          image: ghcr.io/tale-project/tale/tale-platform:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          env:
            - { name: TALE_ROLE, value: api }
            - { name: PORT, value: '3005' }
            - { name: TALE_CONFIG_DIR, value: /app/data }
            - { name: SANDBOX_URL, value: http://sandbox:8003 }
            - { name: SANDBOX_HTTP_API_BASE_URL, value: http://backend-api:3005 }
            - { name: TALE_SKIP_SSRF_FIREWALL, value: '1' }
          ports: [{ name: http, containerPort: 3005 }]
          volumeMounts: [{ name: config-data, mountPath: /app/data }]
          startupProbe:
            httpGet: { path: /ping, port: 3005 }
            periodSeconds: 5
            failureThreshold: 60
          readinessProbe:
            httpGet: { path: /ready, port: 3005 }
            periodSeconds: 5
          livenessProbe:
            httpGet: { path: /ping, port: 3005 }
            periodSeconds: 10
          resources:
            requests: { cpu: 500m, memory: 1Gi }
      volumes:
        - name: config-data
          persistentVolumeClaim: { claimName: config-data }
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: backend-worker, namespace: tale }
spec:
  replicas: 1
  selector: { matchLabels: { app: backend-worker } }
  template:
    metadata: { labels: { app: backend-worker, tale.tier: backend } }
    spec:
      enableServiceLinks: false
      terminationGracePeriodSeconds: 45
      containers:
        - name: backend-worker
          image: ghcr.io/tale-project/tale/tale-platform:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          env:
            - { name: TALE_ROLE, value: worker }
            - { name: TALE_CONFIG_DIR, value: /app/data }
            - { name: SANDBOX_URL, value: http://sandbox:8003 }
            - { name: SANDBOX_HTTP_API_BASE_URL, value: http://backend-api:3005 }
            - { name: TALE_SKIP_SSRF_FIREWALL, value: '1' }
          volumeMounts: [{ name: config-data, mountPath: /app/data }]
          resources:
            requests: { cpu: 500m, memory: 1Gi }
      volumes:
        - name: config-data
          persistentVolumeClaim: { claimName: config-data }
---
apiVersion: v1
kind: Service
metadata: { name: platform, namespace: tale }
spec:
  selector: { app: platform }
  ports: [{ name: http, port: 3000, targetPort: 3000 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: platform, namespace: tale }
spec:
  replicas: 1
  selector: { matchLabels: { app: platform } }
  template:
    metadata: { labels: { app: platform } }
    spec:
      enableServiceLinks: false
      terminationGracePeriodSeconds: 45
      containers:
        - name: platform
          image: ghcr.io/tale-project/tale/tale-platform:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          env:
            - { name: TALE_BACKEND_URL, value: http://backend-api:3005 }
            - { name: TALE_CONFIG_DIR, value: /app/data }
          ports: [{ name: http, containerPort: 3000 }]
          volumeMounts: [{ name: config-data, mountPath: /app/data, readOnly: true }]
          startupProbe:
            exec: { command: [sh, -c, 'curl -sf http://localhost:3000/api/health && [ -f /tmp/platform-ready ]'] }
            periodSeconds: 5
            failureThreshold: 36
          readinessProbe:
            exec: { command: [sh, -c, 'curl -sf http://localhost:3000/api/health && [ -f /tmp/platform-ready ]'] }
            periodSeconds: 5
          resources:
            requests: { cpu: 250m, memory: 512Mi }
      volumes:
        - name: config-data
          persistentVolumeClaim: { claimName: config-data }
---
apiVersion: v1
kind: Service
metadata: { name: bgutil-provider, namespace: tale }
spec:
  selector: { app: bgutil-provider }
  ports: [{ name: http, port: 4416, targetPort: 4416 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: bgutil-provider, namespace: tale }
spec:
  replicas: 1
  selector: { matchLabels: { app: bgutil-provider } }
  template:
    metadata: { labels: { app: bgutil-provider } }
    spec:
      enableServiceLinks: false
      automountServiceAccountToken: false
      containers:
        - name: provider
          image: brainicism/bgutil-ytdlp-pot-provider:1.3.1
          ports: [{ name: http, containerPort: 4416 }]
          readinessProbe:
            tcpSocket: { port: 4416 }
            periodSeconds: 30
          resources:
            requests: { cpu: 50m, memory: 128Mi }
            limits: { memory: 512Mi }
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata: { name: tale-backend-egress, namespace: tale }
spec:
  podSelector:
    matchLabels: { tale.tier: backend }
  policyTypes: [Egress]
  egress:
    - to:
        - podSelector: {}
    - to:
        - namespaceSelector: {}
      ports:
        - { protocol: UDP, port: 53 }
        - { protocol: TCP, port: 53 }
    - to:
        - ipBlock:
            cidr: 0.0.0.0/0
            except:
              - 169.254.0.0/16
              - 10.0.0.0/8
              - 172.16.0.0/12
              - 192.168.0.0/16
```

The platform containers start as root, fix the ownership of `/app/data`, and drop to the application user; do not set `runAsNonRoot` on them.

## Expose the proxy

The proxy is the only public service. It binds `hostPort` 80 and 443 on the node it runs on, so point the public name at that node's address. Caddy listens on the port named in `SITE_URL`: with `https://tale.example.com:8443` the pod must expose 8443 instead of 443, while port 80 keeps serving the redirect to HTTPS. The strategy is `Recreate`: two proxy Pods cannot share one `hostPort` or one `ReadWriteOnce` volume.

```yaml
# 30-proxy.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata: { name: caddy-data, namespace: tale }
spec:
  accessModes: [ReadWriteOnce]
  resources: { requests: { storage: 1Gi } }
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: proxy, namespace: tale }
spec:
  replicas: 1
  strategy: { type: Recreate }
  selector: { matchLabels: { app: proxy } }
  template:
    metadata: { labels: { app: proxy } }
    spec:
      enableServiceLinks: false
      containers:
        - name: caddy
          image: ghcr.io/tale-project/tale/tale-proxy:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          env:
            - { name: BACKEND_UPSTREAM, value: 'backend-api:3005' }
            - { name: OBJECT_STORE_UPSTREAM, value: 'object-store:9000' }
          ports:
            - { name: http, containerPort: 80, hostPort: 80 }
            - { name: https, containerPort: 443, hostPort: 443 }
          volumeMounts:
            - { name: caddy-data, mountPath: /data }
            - { name: caddy-config, mountPath: /config }
          readinessProbe:
            httpGet: { path: /health, port: 2020 }
            periodSeconds: 10
          resources:
            requests: { cpu: 50m, memory: 64Mi }
      volumes:
        - name: caddy-data
          persistentVolumeClaim: { claimName: caddy-data }
        - name: caddy-config
          emptyDir: {}
```

Two alternatives keep the same Pod:

- A LoadBalancer Service on 80 and 443 in front of the proxy instead of the `hostPort` entries. `TLS_MODE=selfsigned` and `letsencrypt` work unchanged; the proxy also serves `docs.<HOST>` and obtains that certificate.
- An Ingress that terminates TLS. Set `TLS_MODE=external` and `TRUSTED_PROXIES` to the Ingress address range so forwarded headers are accepted, as described in [TLS and domains](https://docs.tale.dev/self-hosted/configuration/tls-and-domains).

## Run the sandbox tier

The egress proxy needs the capability set from the Compose contract and no sysctls: the entrypoint installs the IPv6 firewall with ip6tables when the node kernel offers it, and otherwise disables IPv6 in its own network namespace. A cluster that denies both blocks the Pod at start; allow the `net.ipv6.conf.*` sysctls on the kubelet in that case. The spawner creates session Pods, Secrets, and workspace claims through the Kubernetes API, so it runs with a namespaced Role and no Docker socket.

The proxy serves `SANDBOX_EGRESS_MAX_CLIENTS` connections at once (2000 by default) for every session together, each with a thread and two open files. A Pod spec cannot set process or open-file limits: at start the proxy raises its open-file limit to what its connections need, as far as the hard limit of the container runtime allows, and warns in its log when that is too low. Its threads count against the kubelet's `podPidsLimit`; on nodes that set one, keep it above the connection limit, or lower `SANDBOX_EGRESS_MAX_CLIENTS` to fit.

```yaml
# 40-sandbox.yaml
apiVersion: v1
kind: Service
metadata: { name: sandbox-egress, namespace: tale }
spec:
  selector: { app: sandbox-egress }
  ports: [{ name: proxy, port: 3128, targetPort: 3128 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: sandbox-egress, namespace: tale }
spec:
  replicas: 1
  selector: { matchLabels: { app: sandbox-egress } }
  template:
    metadata: { labels: { app: sandbox-egress } }
    spec:
      enableServiceLinks: false
      automountServiceAccountToken: false
      containers:
        - name: egress
          image: ghcr.io/tale-project/tale/tale-sandbox-egress:${VERSION}
          env:
            - { name: SANDBOX_EGRESS_MAX_CLIENTS, value: '2000' }
          securityContext:
            runAsUser: 0
            capabilities:
              drop: ['ALL']
              add: ['NET_ADMIN', 'DAC_OVERRIDE', 'CHOWN', 'SETUID', 'SETGID', 'NET_BIND_SERVICE', 'KILL']
          ports: [{ name: proxy, containerPort: 3128 }]
          readinessProbe:
            exec: { command: [sh, -c, "curl -sS -o /dev/null --max-time 3 --noproxy '*' http://127.0.0.1:3128/"] }
            periodSeconds: 10
          resources:
            requests: { cpu: 50m, memory: 64Mi }
            limits: { memory: 512Mi }
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata: { name: llm-gateway-data, namespace: tale }
spec:
  accessModes: [ReadWriteOnce]
  resources: { requests: { storage: 1Gi } }
---
apiVersion: v1
kind: Service
metadata: { name: sandbox-llm-gateway, namespace: tale }
spec:
  selector: { app: sandbox-llm-gateway }
  ports: [{ name: http, port: 8080, targetPort: 8080 }]
---
apiVersion: v1
kind: Service
metadata: { name: llm-gateway, namespace: tale }
spec:
  selector: { app: sandbox-llm-gateway }
  ports: [{ name: http, port: 8080, targetPort: 8080 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: sandbox-llm-gateway, namespace: tale }
spec:
  replicas: 1
  strategy: { type: Recreate }
  selector: { matchLabels: { app: sandbox-llm-gateway } }
  template:
    metadata: { labels: { app: sandbox-llm-gateway } }
    spec:
      enableServiceLinks: false
      automountServiceAccountToken: false
      securityContext: { fsGroup: 1000 }
      containers:
        - name: gateway
          image: ghcr.io/tale-project/tale/tale-sandbox-llm-gateway:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          ports: [{ name: http, containerPort: 8080 }]
          volumeMounts: [{ name: data, mountPath: /app/data }]
          readinessProbe:
            httpGet: { path: /health, port: 8080 }
            periodSeconds: 10
          resources:
            requests: { cpu: 50m, memory: 128Mi }
            limits: { memory: 512Mi }
      volumes:
        - name: data
          persistentVolumeClaim: { claimName: llm-gateway-data }
---
apiVersion: v1
kind: ServiceAccount
metadata: { name: tale-sandbox-spawner, namespace: tale }
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata: { name: tale-sandbox-spawner, namespace: tale }
rules:
  - apiGroups: ['']
    resources: ['pods']
    verbs: ['create', 'get', 'list', 'delete', 'patch']
  - apiGroups: ['']
    resources: ['secrets']
    verbs: ['create', 'delete', 'list']
  - apiGroups: ['']
    resources: ['persistentvolumeclaims']
    verbs: ['get', 'list', 'create', 'delete']
  - apiGroups: ['networking.k8s.io']
    resources: ['networkpolicies']
    verbs: ['create', 'update']
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata: { name: tale-sandbox-spawner, namespace: tale }
roleRef: { apiGroup: rbac.authorization.k8s.io, kind: Role, name: tale-sandbox-spawner }
subjects: [{ kind: ServiceAccount, name: tale-sandbox-spawner, namespace: tale }]
---
apiVersion: v1
kind: Service
metadata: { name: sandbox, namespace: tale }
spec:
  selector: { app: sandbox }
  ports: [{ name: http, port: 8003, targetPort: 8003 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: sandbox, namespace: tale }
spec:
  replicas: 1
  selector: { matchLabels: { app: sandbox } }
  template:
    metadata: { labels: { app: sandbox } }
    spec:
      enableServiceLinks: false
      serviceAccountName: tale-sandbox-spawner
      terminationGracePeriodSeconds: 30
      containers:
        - name: spawner
          image: ghcr.io/tale-project/tale/tale-sandbox:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          env:
            - { name: SANDBOX_BACKEND, value: kubernetes }
            - { name: SANDBOX_K8S_NAMESPACE, value: tale }
            - { name: SANDBOX_RUNTIME_IMAGE, value: 'ghcr.io/tale-project/tale/tale-sandbox-runtime:${VERSION}' }
            - { name: NODE_EXTRA_CA_CERTS, value: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt }
            - { name: SANDBOX_RUNTIME, value: runc }
            - { name: SANDBOX_DOCKER_IN_CONTAINER, value: 'false' }
            - { name: SANDBOX_EGRESS_PROXY, value: 'http://sandbox-egress:3128' }
          ports: [{ name: http, containerPort: 8003 }]
          volumeMounts: [{ name: config-data, mountPath: /app/platform-config, readOnly: true }]
          startupProbe:
            httpGet: { path: /health, port: 8003 }
            periodSeconds: 5
            failureThreshold: 24
          readinessProbe:
            httpGet: { path: /health, port: 8003 }
            periodSeconds: 10
          resources:
            requests: { cpu: 100m, memory: 256Mi }
            limits: { memory: 512Mi }
      volumes:
        - name: config-data
          persistentVolumeClaim: { claimName: config-data }
```

| Setting | Requirement |
| --- | --- |
| `SANDBOX_BACKEND` | `kubernetes`. Docker-only host paths and bridge names do not configure this backend. |
| `SANDBOX_K8S_NAMESPACE` | The namespace the session Pods, Secrets, and workspace claims are created in; the spawner's own namespace in this layout. Defaults to `tale-sandbox`. |
| `SANDBOX_RUNTIME_IMAGE` | The matching Tale sandbox runtime image, available to every node. |
| `NODE_EXTRA_CA_CERTS` | The cluster CA file, normally `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt` inside the spawner. It is the only CA-trust mechanism the spawner honors; keep TLS verification on. |
| `SANDBOX_K8S_WORKSPACE_SIZE_LIMIT` | The size of each agent session's `/agent` workspace claim, default `4Gi`; also bounds a crawler render's temporary workspace, which needs no claim because it is never resumed, and the inner Docker temporary store when that is enabled. |
| `SANDBOX_K8S_CPU_REQUEST` / `SANDBOX_K8S_MEMORY_REQUEST` | What every session Pod requests from the scheduler, as Kubernetes quantities. Unset, an agent Pod requests `250m` and `512Mi` (`1Gi` with Docker inside the sandbox) and a crawler render `250m` and `512Mi`; a request never exceeds the Pod's limit. Raise them when agents on your nodes run heavier builds than this, so the scheduler does not place more sessions than a node can hold. |
| `SANDBOX_K8S_CACHE_STORAGECLASS` | The StorageClass for workspace claims; unset uses the cluster default. |
| `SANDBOX_RUNTIME` / `SANDBOX_RUNTIME_CLASS` | A supported runtime tier and, when needed, the installed RuntimeClass name. |
| `SANDBOX_EGRESS_PROXY` | The egress Service the sessions use, default `http://sandbox-egress:3128`. |

The spawner scales horizontally. Any replica resolves a session it did not create by its deterministic Pod name and adopts it, so exec, stop, and destroy work through whichever replica the Service picks. `SANDBOX_MAX_SESSIONS` counts the namespace, but simultaneous admissions on several replicas can exceed it briefly; use a ResourceQuota for a hard bound. The [sandbox Kubernetes contract](https://github.com/tale-project/tale/blob/main/services/sandbox/docs/kubernetes.md) documents the Pod shape and runtime details.

### What the spawner enforces

At start the spawner applies the NetworkPolicy `tale-sandbox-session-egress`: session Pods may reach DNS and the Pods of their own namespace and nothing else, so the cloud metadata service, the nodes, and other namespaces stay unreachable even for a process that ignores `HTTP_PROXY`. Public destinations pass through `sandbox-egress`. A missing `networkpolicies` permission is logged and does not stop the spawner; verify that the policy exists before you admit workloads.

Session Pods run the runner as uid 65534 with all capabilities dropped, a read-only root filesystem, no ServiceAccount token, and the session Secret mounted only as environment. The `/agent` workspace is a claim that survives an idle stop. An explicit destroy deletes it, and so does the workspace cleanup once its owner is removed or it stays unused past the organization's window; the cleanup finds the claims with `list`. Session operations use plain HTTP to runnerd on the Pod IP, port 8200; no `pods/exec` is involved.

<Note>

The namespace-wide allowance is broader than the Compose network. From a session Pod, Postgres and the object store answer on their Service ports, although the session holds no credentials for them. Keeping those stores in another namespace would tighten this; that layout was not verified and needs its own policy for the backend roles.

</Note>

For Docker inside sessions, choose an explicit `SANDBOX_DIND_INNER_POOL` outside the Pod, Service, and VPC ranges and read the [inner Docker network prerequisites](https://docs.tale.dev/self-hosted/configuration/environment-reference#sandbox-infrastructure); a Pod cannot discover every cluster network.

## Roll out and verify

After the apply loop, wait for every Pod to become ready and check the signals that matter:

```bash
kubectl -n tale get pods
kubectl -n tale logs -l 'app in (backend-api,backend-worker)' --tail=-1 | grep -c 'applying app migration'
kubectl -n tale get networkpolicy tale-sandbox-session-egress tale-backend-egress
curl -s https://tale.example.com/api/health
```

Whichever backend role boots first applies the migrations under an advisory lock, so the count comes from both roles together and the API log ends with `api listening on :3005`; the health endpoint answers `{"status":"ok","version":"0.5.31"}`. Then open the site, [create the first owner](https://docs.tale.dev/self-hosted/install/first-admin), and connect a provider.

Under **Settings > Sandboxes**, the deployment card carries the namespace scope in its title and shows no host CPU or memory figures; that is expected on this backend. Assign a task to an agent and wait for its deliverable: the run creates a session Pod named `tale-sbx-ses-<hash>` in the namespace, together with a `-spec` Secret and a `-ws` claim.

Prove the fence from a live session Pod:

```bash
POD=$(kubectl -n tale get pods -l tale.sandbox/role=session -o name | head -1)
kubectl -n tale exec $POD -c runner -- curl -m 5 http://169.254.169.254/
kubectl -n tale exec $POD -c runner -- curl -m 20 -s -o /dev/null -w '%{http_code}\n' https://example.com/
```

The first command times out; the second prints `200`, reached through the egress proxy. Then test the lifecycle the way an operator would rely on it: a runner restart keeps the Pod and the workspace, an idle session stops after `SANDBOX_SESSION_MAX_IDLE_MS` and leaves its claim behind, the next task resumes it with the files intact, and destroying it removes the Pod, the Secret, and the claim. With two spawner replicas, repeat a task after scaling and confirm that the second replica serves it.

Roll the API without a gap by keeping two replicas and restarting the Deployment:

```bash
kubectl -n tale rollout restart deploy/backend-api
kubectl -n tale rollout status deploy/backend-api
```

Migrations run at boot under an advisory lock while the previous image keeps serving, so the health endpoint stays green through the roll. Pin one `VERSION` across all Tale images and follow [Upgrade and recover a deployment](https://docs.tale.dev/self-hosted/operate/upgrades) before changing it; a release that changes the proxy image needs the proxy Pod recreated too.

The CLI's snapshots, blue-green flips, and rollback checks do not run on Kubernetes. Back up the claims with your storage provider's snapshots and keep the Secret, the encryption key, and the organization configuration with them; [Backups and restore](https://docs.tale.dev/self-hosted/operate/backups-and-restore) lists what a restore needs.

## Verified scope

These five files were applied unchanged, apart from the Secret values, to a fresh single-node kind cluster with Kubernetes 1.36, kube-network-policies, the local-path StorageClass, and Tale 0.5.31: boot and migrations, the public edge, the first-owner setup and the Sandboxes card, an agent task with a deliverable, the session lifecycle including idle stop, resume, and cross-replica access, the fence probes above, and a rolling restart of the API with two replicas. Multi-node scheduling with `ReadWriteMany` configuration storage, Docker inside sessions on a sysbox or kata RuntimeClass, an Ingress with `TLS_MODE=external`, and highly available stores were not part of that run.

# Run Compose yourself
Source: https://docs.tale.dev/self-hosted/install/own-compose

Use this reference when your team maintains the deployment files and rollout process. The [CLI quickstart](https://docs.tale.dev/self-hosted/install/quickstart) is the shorter path when you want Tale to generate those files and coordinate upgrades. There is no official Helm chart. The sandbox spawner supports Docker and Kubernetes backends; choose the matching runtime and network configuration.

This is a deployment contract with an application-tier example, not a complete Compose file ready to start. Assemble and validate the storage, proxy, and sandbox services before using that example.

## Choose the service layout

| Group | Services | Lifecycle |
| --- | --- | --- |
| Replicable application | `platform`, `backend-api`, `backend-worker` | Same image and release. Keep shared wire contracts compatible during replacement. |
| Persistent stores and edge | `db`, `object-store`, `proxy` | Preserve volumes, credentials, certificates, and stable network names when replacing containers. |
| Shared execution services | `sandbox`, `sandbox-egress`, `sandbox-llm-gateway` | Coordinate active sessions before replacement; the spawner needs the Docker daemon and matching workspace paths. |
| Optional video support | `bgutil-provider` | Best-effort token provider; its failure can affect video retrieval. |

The packaged layout keeps `tale_app` and `tale_knowledge` in one Postgres service with a `knowledge-db` alias. Separate database services or managed databases are also possible; configure their connections and backup coverage explicitly. Recreating a stateful container does not inherently destroy its data, but removing or replacing its volume can.

## Pin compatible images

Set `VERSION` in Compose's `.env` to the Tale release you have reviewed and tested. Export that same value in your shell when running the separate runtime-image pull below. Keep Tale images on one release; the two upstream services have their own pinned versions.

| Service | Image |
| --- | --- |
| `platform`, `backend-api`, `backend-worker` | `ghcr.io/tale-project/tale/tale-platform:<version>` |
| `proxy` | `ghcr.io/tale-project/tale/tale-proxy:<version>` |
| `db` | `ghcr.io/tale-project/tale/tale-db:<version>` |
| `sandbox` | `ghcr.io/tale-project/tale/tale-sandbox:<version>` |
| `sandbox-egress` | `ghcr.io/tale-project/tale/tale-sandbox-egress:<version>` |
| `sandbox-llm-gateway` | `ghcr.io/tale-project/tale/tale-sandbox-llm-gateway:<version>` |
| `object-store` | `ghcr.io/tale-project/ops/minio:RELEASE.2025-04-22T22-12-26Z` |
| `bgutil-provider` | `brainicism/bgutil-ytdlp-pot-provider:1.3.1` |

Session containers use the additional image `ghcr.io/tale-project/tale/tale-sandbox-runtime:<version>`. Set `SANDBOX_RUNTIME_IMAGE` on the spawner and pull it before startup. Its default local development tag is not sufficient on a host that never built it. If you enable Docker-in-container or shared build caching, also provision the compatible runtime and cache images described in the [environment reference](https://docs.tale.dev/self-hosted/configuration/environment-reference).

## Prepare secrets and public addresses

Generate unique values before the first start, and persist them in your secret-management system. Do not copy the sample credentials from a development environment into a production stack.

| Value | Requirement |
| --- | --- |
| `BETTER_AUTH_SECRET` | Stable, high-entropy authentication secret. |
| `ENCRYPTION_SECRET_HEX` | A 32-byte hex value, for example generated with `openssl rand -hex 32`; preserve it for existing encrypted database values. |
| `DB_PASSWORD` or external database credentials | Match the database role the backend actually uses. |
| `SANDBOX_TOKEN` | The same high-entropy token in backend and spawner. |
| `SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD` | The same stable secret in backend and gateway; a gateway without an admin account creates one only for a caller that presents it. The username defaults to `admin`. |
| `OBJECT_STORE_ACCESS_KEY`, `OBJECT_STORE_SECRET_KEY` | Credentials valid for the chosen store. Map them to `MINIO_ROOT_USER` and `MINIO_ROOT_PASSWORD` on bundled MinIO. |
| `OBJECT_STORE_PUBLIC_ENDPOINT` | The browser-reachable endpoint, usually `SITE_URL` when Tale's proxy forwards the bundled store. |
| SOPS age identity | Required to decrypt the configuration sidecars you have encrypted; see [Secrets with SOPS](https://docs.tale.dev/self-hosted/configuration/secrets-with-sops). |

The backend reconciles an environment-managed default object-store connection at startup. A `managedBy: operator` file is deliberately left alone. Changing storage credentials does not move or inherently orphan blobs, but the store and backend must agree before reads and writes work. The gateway retains its established password hash; restore the matching secret or follow its credential-rotation procedure rather than deleting its volume as routine troubleshooting.

Set `HOST`, `SITE_URL`, and `TLS_MODE` for the public path. [TLS and domains](https://docs.tale.dev/self-hosted/configuration/tls-and-domains) covers certificates, additional origins, and subpaths.

## Assemble the application tier

The three roles share an image. `TALE_ROLE=api` and `TALE_ROLE=worker` select backend roles; keep that variable unset for the web service. Do not put a fixed `container_name` on roles you intend to scale.

```yaml
# Application-tier fragment; add the stores, proxy, and sandbox services.
# No container_name on replicated services.
services:
  platform:
    image: ghcr.io/tale-project/tale/tale-platform:${VERSION}
    env_file: [.env]
    volumes: ['config-data:/app/data:ro']
    restart: unless-stopped
    stop_grace_period: 45s
    healthcheck:
      test:
        [
          'CMD-SHELL',
          'curl -sf http://localhost:3000/api/health && [ -f /tmp/platform-ready ]',
        ]
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 180s
    networks:
      internal:
        aliases: [platform]
  backend-api:
    image: ghcr.io/tale-project/tale/tale-platform:${VERSION}
    environment:
      TALE_ROLE: api
      PORT: '3005'
      TALE_CONFIG_DIR: /app/data
      DATABASE_URL: ${DATABASE_URL:-postgresql://tale:${DB_PASSWORD:?required}@db:5432/tale_app}
      SANDBOX_URL: http://sandbox:8003
      SANDBOX_HTTP_API_BASE_URL: http://backend-api:3005
      OBJECT_STORE_ENDPOINT: ${OBJECT_STORE_ENDPOINT-http://object-store:9000}
    env_file: [.env]
    volumes: ['config-data:/app/data']
    cap_add: [NET_ADMIN]
    restart: unless-stopped
    healthcheck:
      test: ['CMD-SHELL', 'curl -sf http://localhost:3005/ping']
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 30s
    networks:
      internal:
        aliases: [backend-api]
      sandbox:
        aliases: [backend-api]
  backend-worker:
    image: ghcr.io/tale-project/tale/tale-platform:${VERSION}
    environment:
      TALE_ROLE: worker
      TALE_CONFIG_DIR: /app/data
      DATABASE_URL: ${DATABASE_URL:-postgresql://tale:${DB_PASSWORD:?required}@db:5432/tale_app}
      SANDBOX_URL: http://sandbox:8003
      SANDBOX_HTTP_API_BASE_URL: http://backend-api:3005
      OBJECT_STORE_ENDPOINT: ${OBJECT_STORE_ENDPOINT-http://object-store:9000}
    env_file: [.env]
    volumes: ['config-data:/app/data']
    cap_add: [NET_ADMIN]
    restart: unless-stopped
    healthcheck: { disable: true }
    networks: [internal]
volumes:
  config-data:
networks:
  internal:
  sandbox:
    name: tale-sandbox-net
    internal: true
    enable_ipv6: false
```

Explicit `environment` entries override `env_file`. The fragment therefore preserves external database and object-store overrides instead of silently forcing bundled addresses. Add health-based dependencies in a single Compose project, or enforce startup ordering in your orchestrator when services live in separate projects.

## Preserve network names and isolation

| Address | Target and network requirement |
| --- | --- |
| `platform` | Web replicas on the internal application network. They reach the backend at `TALE_BACKEND_URL`, `http://backend-api:3005` unless you set it. |
| `backend-api` | API replicas on the application and sandbox networks, reachable on port 3005. |
| `knowledge-db` | The knowledge Postgres target, or use `KNOWLEDGE_DATABASE_URL`. |
| `object-store` | Bundled MinIO on the application network. |
| `sandbox` | Spawner reachable by the backend on port 8003. |
| `sandbox-egress` | Egress proxy reachable by sandbox sessions on port 3128. |
| `sandbox-llm-gateway` / `llm-gateway` | Gateway reachable from backend and sandbox sessions on port 8080. |
| `bgutil-provider` | Token sidecar reachable by the worker on port 4416. |

The sandbox network must be isolated from direct outbound access. The generated stack names it `tale-sandbox-net`; if you choose another name, keep `SANDBOX_EGRESS_NETWORK` and the actual network consistent. Egress must still go through `sandbox-egress`.

Configure `BACKEND_UPSTREAM=backend-api:3005` on the proxy. For bundled file storage, set `OBJECT_STORE_UPSTREAM=object-store:9000` and use the same `OBJECT_STORE_BUCKET` on proxy and backend. Publish the public proxy's ports 80/443; keep databases, store administration, gateway, and sandbox APIs private. Preserve trusted client forwarding if another proxy sits upstream.

## Mount persistent state and required capabilities

| Resource | Required mounts or settings |
| --- | --- |
| Organization configuration | `config-data:/app/data` read-write on backend roles, read-only on `platform`; read-only at `/app/platform-config` on the spawner. |
| Application and bundled knowledge data | `db-data:/var/lib/postgresql/data`; separate knowledge service needs its own persistent volume. |
| Bundled object storage | `object-store-data:/data` and MinIO `command: server /data`. |
| Proxy certificates and state | `caddy-data:/data`, `caddy-config:/config`. |
| Gateway state | `llm-gateway-data:/app/data`. |
| Spawner | `/var/run/docker.sock` and `/var/lib/tale-sandbox` mounted at the same host/container paths. Docker-socket access gives control over the host daemon. |
| Backend roles | `cap_add: [NET_ADMIN]` for the shipped entrypoint's network fence. |
| Egress service | The shipped restricted capability set after dropping all others: `NET_ADMIN`, `DAC_OVERRIDE`, `CHOWN`, `SETUID`, `SETGID`, `NET_BIND_SERVICE` and `KILL`. Without `KILL` the root supervisor cannot signal tinyproxy after it has dropped to `nobody`, so a stop waits out the grace period and ends in exit 137 instead of draining. |
| Egress IPv6 | `sysctls` with `net.ipv6.conf.all.disable_ipv6: '1'` and `net.ipv6.conf.default.disable_ipv6: '1'`, as in the shipped stack. The egress firewall fails closed: it needs working IPv6 firewall support or IPv6 disabled for the default and every interface, and a container cannot write those sysctls itself through a read-only `/proc/sys`. Without them the proxy refuses to start on a kernel without the `ip6_tables` module; see [Sandbox infrastructure](https://docs.tale.dev/self-hosted/configuration/environment-reference#sandbox-infrastructure). |
| Postgres shutdown | `stop_signal: SIGINT`, `stop_grace_period: 60s`, `shm_size: 256mb` in the reference stack. |
| Web and spawner shutdown | Allow the web tier's 45-second and spawner's 30-second stop grace; coordinate active work before stopping. |

Keep `db-backup` if your database tooling writes to `/var/lib/postgresql/backup`; mounting it alone does not create a backup schedule. Older `convex-data` configuration volumes need a deliberate transfer into `config-data`, not deletion. Preserve the old copy until verified.

## Use the right health probes

| Service | Probe | Meaning |
| --- | --- | --- |
| `backend-api` | `curl -sf http://localhost:3005/ping` | Process liveness; stays available during drain. |
| `backend-api` | `GET /ready` on port 3005 | Whether the backend is accepting new work; separate from external-store health. |
| `platform` | `curl -sf http://localhost:3000/api/health && [ -f /tmp/platform-ready ]` | Web service startup completed. |
| `backend-worker` | Disable the image's web healthcheck. | No HTTP server; monitor jobs and worker progress separately. |
| `proxy` | `curl -sf http://127.0.0.1:2020/health` | Proxy process responds. |
| `db` | `pg_isready -U tale && [ -f /tmp/.db_ready ]` | Postgres and initialization are ready; adapt the user to your configuration. |
| `object-store` | `mc ready local` | Bundled MinIO readiness. |
| `sandbox` | `curl -fsS http://127.0.0.1:8003/health` | Spawner readiness after runtime-image preparation. |
| `sandbox-egress` | `curl -sS -o /dev/null --max-time 3 --noproxy '*' http://127.0.0.1:3128/` | The proxy answers a non-proxy request itself (400 page), so this proves it serves without reaching a third-party website. Do not probe the port with a bare TCP connect: tinyproxy logs every connect-and-close at error level, one line per interval. |
| `sandbox-llm-gateway` | `wget -q -O /dev/null http://127.0.0.1:8080/health` | Use the image's available client; it does not ship `curl`. |

Give cold starts enough time: downloading the sandbox runtime can take longer than a warm-host probe budget. A successful readiness probe does not prove file access, model credentials, or an entire user task. Check those separately.

## Connect external stores

External application Postgres replaces `DATABASE_URL`; external knowledge uses `KNOWLEDGE_DATABASE_URL`. The latter needs pgvector and, for full hybrid search, pg_search. Supply a session-compatible connection and any required `POSTGRES_CA_FILE`. Do not assume a transaction pooler preserves the session behavior Tale needs.

For external S3-compatible storage, set the `OBJECT_STORE_*` values and browser endpoint explicitly. AWS S3 can use an empty custom endpoint; other stores may need path-style addressing. Provision object permissions and browser CORS, then test an actual upload and download. Remove only the bundled services you no longer use, along with their `depends_on` references; keep old volumes until migration is verified.

Changing URLs does not migrate existing rows or files. [Data residency](https://docs.tale.dev/self-hosted/configuration/data-residency) describes the per-organization and deployment-wide choices. External stores require their own coordinated backups, outside `tale backup`'s volume archives.

## Start and accept the installation

Bring stores up before dependent services and use restart policies such as `unless-stopped`. Prepare `VERSION` in the shell as described above, then validate your complete Compose file:

```bash
docker compose config --quiet
docker pull "ghcr.io/tale-project/tale/tale-sandbox-runtime:$VERSION"
docker compose up -d
docker compose ps
docker compose logs --tail=100 backend-api backend-worker
```

Confirm healthy services, successful backend migrations, and worker progress. Open the public URL, follow [First administrator](https://docs.tale.dev/self-hosted/install/first-admin), configure a provider and embedding model, and test a controlled chat, file upload/download, and knowledge query. If harnesses are required, verify a sandbox session too.

Database migrations run at backend boot. Your deployment procedure must keep compatible versions serving during that work, stop on migration failures, drain active work before replacement, and retain a recovery record. The CLI's blue-green coordination, pending-flip recovery, automatic snapshots, and rollback checks do not happen merely because you copied its service layout.

## Map the contract to Kubernetes

[Deploy on Kubernetes](https://docs.tale.dev/self-hosted/install/kubernetes) translates this contract into Deployments, Services, StatefulSets, and NetworkPolicies, switches the sandbox spawner to `SANDBOX_BACKEND=kubernetes`, and lists the checks a cluster must pass before you admit users. Keep this page as the reference for the service names, volumes, probes, and environment the Kubernetes objects must reproduce.

# Run your first self-hosted instance
Source: https://docs.tale.dev/self-hosted/install/quickstart

Run Tale locally with the published CLI, then create your workspace and send a message. You do not need to clone the repository, install Bun or build the application. The CLI downloads the container images and prepares the configuration.

## Prepare the local machine

You need:

- macOS, Linux or Windows with PowerShell, and Docker running Linux containers with Compose. Docker Desktop includes Compose on macOS and Windows. If Docker is missing, `tale dev` offers to help install it.
- Network access to GitHub for the CLI and container registries for the images. The first start downloads several GB; leave room for the images and your data.
- A supported model provider credential for the first reply. You can create the account and explore the application before connecting a provider.

On ARM64, including Apple Silicon, the bundled object store needs amd64 emulation. Docker Desktop includes it; a standalone Linux Docker host needs emulation configured separately. Check the [architecture requirements](https://docs.tale.dev/self-hosted/install/cli-install#before-you-begin) before starting on ARM64 Linux.

The default HTTPS port is `443`; the sandbox service also uses `127.0.0.1:8003`. Keep the instance private until you have created its owner account.

## Install the CLI

Choose the installer for your operating system:

<Tabs>

<Tab title="macOS / Linux">

```bash
curl -fsSL https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.sh | bash
```

</Tab>

<Tab title="Windows (PowerShell)">

```powershell
irm https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.ps1 | iex
```

</Tab>

</Tabs>

Run `tale --version` in the same terminal to confirm installation. If the command is missing, follow the installer’s `PATH` guidance and reopen any terminals that were already open. The [CLI installation guide](https://docs.tale.dev/self-hosted/install/cli-install) covers pinned versions and custom installation directories.

Check `tale --help` before using `tale doctor`. If `doctor` is not listed, run `docker info` and `docker compose version` to check Docker and Compose. When available, `tale doctor` also checks container architecture and local ports without installing software or changing files. Follow any reported recovery steps; a passing check does not verify image downloads or model access.

## Initialize and start

Choose where you want to keep the project, then run:

```bash
tale init my-project
cd my-project
tale dev
```

`tale init` creates the project and a private `.env` containing generated secrets. Keep that file and its encryption keys in secure backups. At the sandbox Docker prompt, keep the default disabled unless your agents need to run Docker: enabling it permits privileged nested Docker.

`tale dev` starts the containers and prints the address when the application is ready. Leave it running during the first image downloads and database setup. Open the printed URL, normally `https://localhost`. The local certificate is self-signed; verify that the address is your own instance before accepting the browser warning.

<Note>

The generated `default/` directory contains catalog examples as well as automatically installed entries. You do not need to edit it for this first run. Its `README.md` explains which configuration changes affect an organization.

</Note>

## Create the owner and test a reply

1. Follow the setup flow to create your account and name the organization. This first account becomes its **Owner**; [First owner](https://docs.tale.dev/self-hosted/install/first-admin) covers ownership and existing accounts.
2. After setup, open **Settings > AI providers** and add a supported credential. The setup completion page also links to provider settings. Follow [AI providers](https://docs.tale.dev/platform/admin/providers) for the fields and supported authentication methods.
3. Open **Home**, choose **New chat**, select an available model and send a short request such as “Write a three-item meeting checklist.” Wait for the answer to finish.

A completed reply confirms that the account, provider and chosen model work together. If the model list is empty or the request fails, use the provider guide’s recovery steps. [Send your first message](https://docs.tale.dev/get-started/quickstart) explains how to continue and find the conversation again. When you are ready to delegate project work, [create your first agent](https://docs.tale.dev/tutorials/editor/first-agent-end-to-end).

## Stop and return later

Press `Ctrl-C` in the terminal running `tale dev` to stop the foreground instance. From the same project directory, run `tale dev` again to resume it with its existing data.

Check `tale dev --help` before using the background commands below. If it does not list `--stop`, keep `tale dev` in the foreground and stop it with `Ctrl-C`.

```bash
tale dev --detach
tale dev --stop
```

Stopping preserves the project, secrets and persistent data. Keep using the same project directory; creating a new project starts a separate instance.

## Resolve startup problems

| Symptom | Next action |
| --- | --- |
| `tale` is not found | Check the installer destination and terminal `PATH`; on Windows, open a new terminal. |
| Docker cannot start | Open Docker Desktop or start the daemon. Confirm `docker info` works in the same terminal, then retry. |
| Compose is missing | Check `docker compose version`; install the Compose plugin or update Docker Desktop. |
| An image pull is slow or fails | Check the reported registry/network error and free disk space. After fixing the cause, rerun `tale dev` in the same directory. |
| HTTPS port is busy | Inspect the process using port `443`. With the published v0.5.70 CLI, free that port before retrying. |
| Port `8003` is busy | Stop the other local Tale stack or service using it. Changing `--port` changes HTTPS only. |
| A container keeps restarting | Run `tale status`, then `tale logs backend-api --tail 100` or `tale logs platform --tail 100`. Use the reported service’s logs to find the cause. |
| Login appears instead of first-time setup | An account already exists. Sign in with it; do not reset the data to repeat setup. |
| The app opens but no reply arrives | Check the provider credential and selected model under **Settings > AI providers**. |

Rerun after correcting the reported cause; keep `.env` and the data volumes. For persistent failures, follow [Troubleshooting](https://docs.tale.dev/self-hosted/operate/observability/troubleshooting) and include the CLI version and relevant error when asking for help. Remove credentials from logs before sharing them.

## Prepare a production deployment

`tale deploy` deploys the project configuration to the selected Docker host. Development and deployment use separate data volumes: deploying does not transfer the local account, chats or uploaded files. Prepare DNS, TLS, backups and access controls before adding a production team.

Read [TLS and domains](https://docs.tale.dev/self-hosted/configuration/tls-and-domains), [Backups and restore](https://docs.tale.dev/self-hosted/operate/backups-and-restore) and [Hardening](https://docs.tale.dev/self-hosted/operate/security/hardening). If your infrastructure requires service definitions you maintain directly, use [Run Compose yourself](https://docs.tale.dev/self-hosted/install/own-compose).

# Backups and restore
Source: https://docs.tale.dev/self-hosted/operate/backups-and-restore

A recoverable Tale instance needs more than a database archive: keep its files, organization configuration, deployment workspace, and decryption keys together with the version that wrote them. Set your recovery-point and recovery-time objectives first, then test whether your backup schedule and restore procedure meet them.

This guide covers the workspace CLI's Docker-volume snapshots. If you maintain Compose yourself, use a backup process that covers the same stores. External databases and buckets need separate, coordinated backups.

## Prepare an empty recovery host

Recover the original workspace and confirm that your Docker connection targets the recovery host. Keep the stack stopped. Replace `your-project-id` below with the original ID from `tale.json`; for a development snapshot, use `TALE_RESTORE_PREFIX="${TALE_RESTORE_PROJECT}-dev_"` instead. Production and development namespaces are different, and the CLI selects production first when both exist.

```bash
TALE_RESTORE_PROJECT=your-project-id
TALE_RESTORE_PREFIX="${TALE_RESTORE_PROJECT}_"
docker volume create --label "project=$TALE_RESTORE_PROJECT" "${TALE_RESTORE_PREFIX}config-data"
docker volume create --label "project=$TALE_RESTORE_PROJECT" "${TALE_RESTORE_PREFIX}backups"
docker volume inspect "${TALE_RESTORE_PREFIX}backups"
```

This prepares the configuration and backup volumes without starting a backend or applying migrations. Restore the complete saved contents of `backups` into that volume using your backup system; the inspected mountpoint belongs to the Docker host, which may be remote. Snapshot directories and their manifests must retain their original layout. `tale restore` must then list the expected snapshot. During an actual restore, the CLI creates any other missing target volumes after verifying the snapshot.

## Check the snapshot's scope

`tale backup` captures existing project volumes from this inventory:

| Volume | Included data |
| --- | --- |
| `db-data` | Application data and, in the packaged single-host stack, the knowledge database. |
| `knowledge-db-data` | The separate knowledge database when this volume exists, as in source Compose. |
| `config-data` | Organization configuration, supported secret sidecars, and branding. Provider credentials stored in Postgres belong to the database backup. |
| `object-store-data` | Uploaded files and generated media when the deployment default uses the bundled store. |
| `caddy-data`, `caddy-config` | Certificates and proxy state. |
| `llm-gateway-data` | The model gateway's store: its admin account, provider keys, session keys with their budgets and spend, and its request log. |

A snapshot contains an archive and SHA-256 sidecar for each captured volume. `manifest.json` is written last and records the platform version when it can be determined. A directory without a manifest is incomplete: it is excluded from restore listings and can be removed by rotation after a newer complete snapshot exists. Snapshots taken before the CLI captured the gateway's store have no `llm-gateway-data` archive.

Also preserve the workspace containing `tale.json`, its `.env`, and any separately mounted key files. In particular, retain `ENCRYPTION_SECRET_HEX` and the age identity needed to decrypt SOPS sidecars. Sandbox workspaces are outside this snapshot inventory; include them in your own plan if you need to retain their state.

<Warning>

External Postgres data is not captured, even when an unused local database volume still appears in the snapshot. The CLI does not warn about this database configuration. External buckets are also outside the snapshot; the CLI reports a repointed default bucket or organization-specific buckets it discovers. Check each organization's storage connections before declaring backup coverage complete.

</Warning>

## Create and verify a snapshot

Run these commands in the intended deployment workspace:

```bash
tale status
tale backup
tale restore
```

`backup` prints the snapshot result. `restore` without an ID only lists available snapshots, including the recorded version and whether blobs or the gateway's store are absent. Record the snapshot ID with your external backup IDs.

The snapshot process pauses containers using each volume while that volume is archived. Uploads, downloads, database work, and model calls through the gateway can stall during the relevant pause; duration depends on data size and host throughput. Docker reports a paused container as `unhealthy` until its next successful health check, so after each archive the snapshot waits until every container that was healthy before the pause reports `healthy` again; this usually takes one health-check interval. If a container does not recover within the retries its health check allows, the snapshot fails. These are volume-level crash-consistent archives, not an atomic transaction across all stores. For a coordinated recovery point, stop incoming writes and scheduled work or use a maintenance window that also covers external stores.

A version-changing `tale deploy`, or a host-config override, takes a snapshot before its mutating steps. Snapshot failure aborts that deployment. `--skip-backup` bypasses this protection; use it only when your recovery plan already provides the required backup.

## Retain a copy off the host

Snapshots live in the project's `backups` Docker volume. A host or disk failure can destroy both live data and local snapshots. Copy completed snapshots, workspace configuration, and keys into your existing protected off-host backup system; Tale does not upload them for you.

Use the project ID from `tale.json` to locate the volume:

```bash
docker volume inspect <project-id>_backups
```

The mount location belongs to the Docker host, which may be a VM or remote machine. Point your backup agent there rather than assuming the path exists on your workstation. Verify that the off-host copy includes `manifest.json`, every archive it names, and each checksum sidecar.

Local rotation keeps the newest five snapshots **and** snapshots from the last 14 days. It deletes a snapshot only when it is outside both windows. Set `BACKUP_KEEP_COUNT` and `BACKUP_KEEP_DAYS` in `.env` to change these windows; configure off-host retention separately.

## Restore the matching data and version

<Warning>

Restoring replaces the contents of the included data volumes. Preserve the current state if you may need it, verify the destination workspace, and keep users and scheduled integrations away from the recovery environment until it is accepted.

</Warning>

1. Retrieve the completed snapshot, deployment workspace, matching keys, and any external-store backups. On a fresh host, follow the empty-host preparation above before proceeding.
2. Run `tale restore` to select an ID and read its platform version. If that version is unknown, resolve it from your deployment records before starting the application.
3. Restore with the stack stopped. `--stop` stops running project containers; the CLI then verifies archive checksums and asks for confirmation before replacing data. Run it with your current CLI, before step 5 changes it: a CLI from before gateway capture skips the gateway archive.

```bash
tale restore <snapshot-id> --stop
```

4. Restore external databases and buckets to the coordinated recovery point while traffic remains stopped. A snapshot marked `without blobs` leaves the existing local blob volume untouched. One marked `without gateway` leaves `llm-gateway-data` untouched and cannot return the gateway to its store from before a gateway upgrade; the CLI warns before it asks for confirmation. If the gateway was upgraded after that snapshot, put your own copy of the volume back before the next step, as [Upgrades](https://docs.tale.dev/self-hosted/operate/upgrades) describes.
5. Select the version recorded for the snapshot and deploy it, including the stateful services:

```bash
tale update --version <snapshot-platform-version>
tale deploy --stop
tale status
```

The version matters because a newer backend can apply migrations as soon as it starts. A data restore followed by an arbitrary current image is not a rollback to the recorded state. Older `convex-data` config archives are restored into the current `config-data` volume by the CLI.

## Prove recovery before reopening traffic

In an isolated drill, sign in, open a known conversation, download an old file, check organization configuration, and run a controlled knowledge query. Verify access to provider secrets and external storage without triggering production notifications or automations. Record lost-data range, elapsed recovery time, and every manual step.

Repeat the drill after material storage, key, or deployment changes and at the interval your recovery objectives require. Use [Upgrades](https://docs.tale.dev/self-hosted/operate/upgrades) for version selection and [Troubleshooting](https://docs.tale.dev/self-hosted/operate/observability/troubleshooting) if a restored service does not become healthy.

# Find the service behind a failure
Source: https://docs.tale.dev/self-hosted/operate/container-architecture

Use service ownership to narrow an incident before changing containers. The packaged stack combines the application and knowledge databases in `db`; source Compose can run `knowledge-db` separately. Confirm your actual layout with `tale status` or your orchestrator's service inventory.

## Choose the first logs

| Symptom | Start with | Check next |
| --- | --- | --- |
| Public URL or TLS fails | `proxy` | DNS, certificate state, public ports, upstream reachability. |
| App shell fails to load | `platform`, then `proxy` | Web health, static assets, and the selected deployment version. |
| Shell loads, but sign-in or data requests fail | `backend-api` | API health, database access, request errors, and proxy routing. |
| Jobs, scheduled automations, or ingestion stop progressing | `backend-worker` | Queue state, job errors, credentials, and required stores. |
| Reads or writes fail across the application | `db` or the external application database | Connectivity, disk space, locks, and database logs. |
| Files cannot be uploaded or downloaded | `backend-api`, then `object-store` or the external bucket | The resolved organization connection, credentials, public endpoint, and browser CORS. |
| A harness cannot start or reach its model | `sandbox`, `sandbox-llm-gateway` | Session creation, gateway authentication, model availability, and runtime image. |
| Sandboxed network access or page rendering fails | `sandbox-egress`, `sandbox` | Target hostname, allowed ports, egress policy, and session logs. |
| Video transcript retrieval fails | `backend-worker`, `bgutil-provider` | Video access, extractor errors, configured proxy, and browser-session status. |

Use logical service names with `tale logs <service>`. For your own Compose stack, use `docker compose logs --tail=200 <service>`; generated container names may include a project, colour, and replica number.

## Follow an interactive chat request

1. The browser reaches `proxy`. Web assets go to `platform`; application and authentication requests go to `backend-api`.
2. The API checks the session and organization, resolves the chosen model and credential, and executes the interactive turn. It stores progress in the application database.
3. The browser reads turn progress through the thread's stream endpoint. `/events` carries invalidation hints for refreshed data; it is not the token payload stream.
4. Knowledge tools access the requesting organization's knowledge connection. Original files are read through its storage configuration.
5. A turn using a coding harness needs a sandbox session and the model gateway. Queued tasks, workflow agent jobs, and REST chat turns can also depend on workers.

A worker outage therefore has a different scope from an API outage, but it is not safe to declare all chat or agent work unaffected. Check the entry point and execution type that failed. Preserve the original error before retrying a turn that might spend tokens or perform an external action.

## Understand the sandbox dependencies

`sandbox` is a spawner with access to the host's Docker daemon. It creates temporary containers from the pinned sandbox-runtime image and mounts their workspaces. Those sessions use an isolated network: outbound web requests pass through `sandbox-egress`, while model calls use the gateway's scoped session access.

The runtime also supplies Chromium and Playwright for page rendering and document generation. A healthy web UI does not prove that this execution plane works. Check image availability, workspace mounts, the shared sandbox token, and gateway credentials before diagnosing an individual script.

The egress service blocks private and metadata destinations and can enforce a hostname allowlist. An unavailable egress path can cause refusals or network failures; the precise error depends on the operation. [Hardening](https://docs.tale.dev/self-hosted/operate/security/hardening) describes the policy, and [Run Compose yourself](https://docs.tale.dev/self-hosted/install/own-compose) lists required capabilities and mounts.

## Recognize knowledge-index repair

A damaged BM25 index can cause ingestion failures even when the underlying document tables remain readable. The backend checks knowledge indexes with `pdb.verify_index`; an advisory lock coordinates repair attempts for a database. Organization-specific databases are checked when they are first used.

| Result | Backend behavior | Operator response |
| --- | --- | --- |
| Healthy | Continue normal work. | No repair is needed. |
| Damaged index at or below `KNOWLEDGE_INDEX_REPAIR_INLINE_MAX_BYTES` | Rebuild inline and verify again; the default limit is 1 GiB. | Allow for slower startup and inspect the final result. |
| Larger damaged index | Schedule a concurrent background rebuild; affected indexing can wait with an index-rebuilding reason. | Watch worker progress and the final verification. |
| Repair fails or verification cannot establish health | Record the failure; affected corpus operations can remain unavailable. | Inspect the exact cause, database permissions, and storage health before attempting manual repair. |

Repair events can produce `knowledge_index_repaired`, `knowledge_index_rebuild_scheduled`, or `knowledge_index_repair_failed` audit entries and administrator notifications. A failed rebuild is not proof that source documents are lost, and a successful rebuild does not replace a database backup.

`KNOWLEDGE_INDEX_REPAIR_DISABLED=1` disables the automatic check; it is not a fix for corruption. Repeated damage after restarts warrants investigating the database shutdown path and storage. Prefer normal stops with the configured grace period over forced kills. [Troubleshooting](https://docs.tale.dev/self-hosted/operate/observability/troubleshooting) gives the read-only index check and recovery precautions.

# Monitor and respond to incidents
Source: https://docs.tale.dev/self-hosted/operate/observability/operations

Monitor the actions people need to complete, as well as the services beneath them. A successful HTTP probe does not prove that sign-in, a file download, a knowledge query, or an automation finishes. Define alert severity from the impact on your deployment and give each alert an owner and a recovery procedure.

[Observability config](https://docs.tale.dev/self-hosted/configuration/observability-config) explains the endpoints and access token. [Prometheus and Grafana](https://docs.tale.dev/self-hosted/operate/observability/prometheus-grafana) provides a collection example.

## Choose signals with a useful response

| Signal | How to investigate | When to escalate |
| --- | --- | --- |
| Public URL, certificate, or sign-in fails | Check the public path from outside the host, then proxy and backend logs. | Users cannot reach a required service, or certificates are near expiry without a working renewal path. |
| Backend 5xx responses rise | Compare `tale_backend_http_requests_total` by `route` and `status` with the affected action. | Errors affect active users or critical integrations. |
| A store becomes unreachable | Inspect `tale_backend_store_up` and the store's own monitoring. | The missing store blocks required data, search, or file access. |
| Queued or failed jobs accumulate | Inspect `tale_backend_jobs{state=...}`, workers, and representative run errors. | The backlog stops clearing or a completion deadline is at risk. |
| Disk or connection headroom shrinks | Use host/database monitoring; these are not all Tale-exported metrics. | Forecast exhaustion early enough to add capacity or resolve the cause. |
| A scheduled backup or copy is missing | Check the backup job, completed manifest, and off-host destination. | Your recovery-point objective is no longer met. |
| Provider requests are throttled or rejected | Read the provider response and affected run; check quota, credentials, and provider status. | Required work fails or waits beyond its allowed delay. |

An 80% disk alert can be a starting point, but growth rate and recovery lead time matter more than one universal percentage. A knowledge outage can be critical for a team whose work depends on retrieval; do not automatically defer it because the UI still loads.

## Choose the right health endpoint

Use these paths on the public origin of a production deployment behind the bundled proxy:

| Path | What a successful response establishes |
| --- | --- |
| `/health` | Caddy answers `OK`. This stays healthy while the platform restarts. |
| `/api/health` | The platform web process answers its liveness request. |
| `/status.json` | The public dependency-status report is available; inspect its component verdicts. Results are cached for five seconds. |
| `/status` | The same availability report in a page for people. |

Check the expected response body as well as the HTTP status. An unrecognized frontend path such as `/healthz` can return the app shell with `200`; that is not a health report. See [Status page](https://docs.tale.dev/develop/status-page) for the response contract.

## Understand what the metrics prove

The backend exports process metrics, HTTP response counts and durations, queue counts, in-flight generations, open hint streams, the drain flag, and store reachability. Inspect the actual series from your deployed version before writing an alert against it.

- `tale_backend_store_up` probes the **deployment-default** application database, knowledge database, and bucket. Organization-specific connections need their own monitoring.
- Store probes are cached for 30 seconds. An object-store `403` on the bucket probe counts as reachable: it can mean the key cannot list the bucket. A value of `1` does not prove that a particular object can be uploaded or downloaded.
- `/ready` expresses rollout readiness. It does not incorporate external-store health, so a healthy replica can still depend on an unavailable store.
- The public backend metrics URL can reach different API replicas. Process metrics describe the replica that answered; queue and generation collectors read shared database state. Do not sum shared counts as if every replica owned a separate queue.

Use a controlled end-to-end check for the gaps: sign in with a monitoring account, read a known record, and test the file or knowledge flow your team depends on. Keep that check within a dedicated scope and avoid sends or other external effects.

## Keep latency targets separate from measurements

Tale exports `tale_sla_target_seconds` and a rule template at `/metrics/sla-rules`. The current targets are a 1-second mean time to first token over 30 minutes and a 40-second mean long-operation duration over 6 hours. These are target metadata, not observations or a guarantee that your deployment meets them.

The generated rules expect `tale_dialog_ttft_seconds` and `tale_long_operation_seconds` histograms. The backend does not automatically emit those two latency series. Its HTTP request-duration histogram measures request handling, which is not interchangeable with first-token time or the full duration of queued work. Instrument the actual operation boundaries and confirm samples exist before enabling these rules. An empty query is missing evidence, not a passing latency check.

## Investigate before changing state

1. Record the affected organization, URL or action, error code, time range, and scope of impact. Check whether the symptom is reproducible without changing data.
2. Inspect `tale status` and `tale logs <service>`. For a deployment you manage directly, use the Compose service name with `docker compose ps` and `docker compose logs --tail=200 <service>`.
3. Compare browser network failures with API/worker logs and store or provider health. Preserve relevant logs before a restart rotates or obscures them.
4. Address the identified cause: capacity, connectivity, configuration, credentials, or a failed process. Recreate affected containers when changing environment values; `docker compose restart` keeps their previous environment.
5. Verify the original action and related queued work after recovery. Record any interrupted requests or jobs that need an explicit retry, then update the incident timeline.

Escalate as soon as your incident policy requires it. A restart is a recovery action with possible interruption, not a mandatory diagnostic step or a reason to delay escalation. [Troubleshooting](https://docs.tale.dev/self-hosted/operate/observability/troubleshooting) maps common symptoms to narrower checks.

# Prometheus and Grafana
Source: https://docs.tale.dev/self-hosted/operate/observability/prometheus-grafana

Use your existing Prometheus and Grafana installation when you have one. The example below runs a separate monitoring Compose project that scrapes Tale through its public proxy. It includes persistent metrics storage, a mounted token file, and two starter alerts.

## Prepare access and files

Set `METRICS_BEARER_TOKEN` for Tale's proxy, then apply the environment change through your deployment workflow. A container restart alone does not load changed environment values. Confirm the token-gated paths in [Observability config](https://docs.tale.dev/self-hosted/configuration/observability-config#metrics) before configuring a scraper.

Create a separate monitoring directory with `compose.monitoring.yml`, `prometheus.yml`, `tale-alerts.yml`, and `secrets/tale-metrics-token`. Put only the token value in that secret file using your secret manager. Keep it and the monitoring `.env` out of version control, with access limited to the operator and the container that needs it.

In the monitoring `.env`, pin tested `PROMETHEUS_IMAGE` and `GRAFANA_IMAGE` tags and set `GRAFANA_ADMIN_PASSWORD`. Select supported releases from the projects' official [Prometheus](https://prometheus.io/download/) and [Grafana](https://grafana.com/grafana/download) distribution pages. These versions are independent of Tale's release tag.

## Define the monitoring services

Both interfaces bind to loopback. Reach them on the Docker host or through an SSH tunnel; a remote Docker context does not bind them to your workstation.

```yaml
# compose.monitoring.yml
services:
  prometheus:
    image: ${PROMETHEUS_IMAGE:?set a tested Prometheus image tag}
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - ./tale-alerts.yml:/etc/prometheus/tale-alerts.yml:ro
      - prometheus-data:/prometheus
    secrets: [tale_metrics_token]
    ports: ['127.0.0.1:9090:9090']
    restart: unless-stopped
  grafana:
    image: ${GRAFANA_IMAGE:?set a tested Grafana image tag}
    environment:
      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD:?set a strong password}
      GF_USERS_ALLOW_SIGN_UP: 'false'
    volumes: ['grafana-data:/var/lib/grafana']
    ports: ['127.0.0.1:3001:3000']
    restart: unless-stopped
secrets:
  tale_metrics_token:
    file: ./secrets/tale-metrics-token
volumes:
  prometheus-data:
  grafana-data:
```

The secret is mounted inside Prometheus at `/run/secrets/tale_metrics_token`. Make sure your container runtime can read the source file without opening it to other users.

## Configure collection and alerts

Replace `tale.example.com` with the reachable Tale hostname, including a port when it is not 443. Add your deployment's base path to each `metrics_path` if needed. Use a trusted HTTPS certificate or configure a CA file; do not disable certificate verification to make a scrape pass.

```yaml
# prometheus.yml
global:
  scrape_interval: 30s
rule_files:
  - /etc/prometheus/tale-alerts.yml
scrape_configs:
  - job_name: tale-platform
    scheme: https
    metrics_path: /metrics/platform
    authorization:
      credentials_file: /run/secrets/tale_metrics_token
    static_configs:
      - targets: ['tale.example.com']
  - job_name: tale-backend
    scheme: https
    metrics_path: /metrics/backend
    authorization:
      credentials_file: /run/secrets/tale_metrics_token
    static_configs:
      - targets: ['tale.example.com']
```

The token comes from `credentials_file`, as supported by [Prometheus HTTP configuration](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#http_config). A literal `${METRICS_BEARER_TOKEN}` in this YAML is not a substitution supplied by Docker Compose, because Compose mounts the file without rewriting it.

```yaml
# tale-alerts.yml
groups:
  - name: tale
    rules:
      - alert: TaleTargetDown
        expr: up{job=~"tale-.*"} == 0
        for: 2m
        labels: { severity: page }
        annotations:
          summary: 'Tale metrics target {{ $labels.job }} is down'
      - alert: TaleDefaultStoreUnreachable
        expr: tale_backend_store_up == 0
        for: 5m
        labels: { severity: page }
        annotations:
          summary: 'Tale cannot reach its default {{ $labels.store }} store'
```

Adjust severity and waiting periods to your service requirements, and configure Alertmanager or Grafana alert delivery. A rule visible in Prometheus does not send a notification by itself. The store alert covers deployment defaults; it does not monitor organization-specific databases or buckets.

## Start and verify collection

Validate the files before starting the services:

```bash
docker compose -f compose.monitoring.yml config --quiet
docker compose -f compose.monitoring.yml run --rm --entrypoint promtool \
  prometheus check config /etc/prometheus/prometheus.yml
docker compose -f compose.monitoring.yml up -d
```

Open `http://127.0.0.1:9090/targets`. Both Tale jobs should show **UP**. Check the query `up{job=~"tale-.*"}` and inspect the alert rules. A `401` points to token configuration; DNS, connection, and certificate errors require checking the scraper's own network path. An **UP** target proves a successful scrape, not every application feature.

Open Grafana at `http://127.0.0.1:3001` and add a Prometheus data source at `http://prometheus:9090`. That address is resolved inside the monitoring Compose network.

## Build a useful first dashboard

| Panel | Query | Interpretation |
| --- | --- | --- |
| Scrape availability | `up{job=~"tale-.*"}` | Whether each public metrics path answered the scraper. |
| Backend memory | `process_resident_memory_bytes{job="tale-backend"}` | Memory of the API replica that answered. |
| Backend response rate | `sum by (status) (rate(tale_backend_http_requests_total[5m]))` | Request rates grouped by response status class. |
| Job states | `tale_backend_jobs` | Jobs by queue state; inspect sustained growth and failures. |
| Default stores | `tale_backend_store_up` | Cached reachability for `app_db`, `knowledge_db`, and `object_store`. |
| Deployment drain | `tale_backend_drain_active` | Whether deployment draining is refusing new turns. |

Some collectors read shared database counts; others describe one process. With multiple replicas, collect per-replica process metrics through your private monitoring network and avoid double-counting shared gauges. [Operations](https://docs.tale.dev/self-hosted/operate/observability/operations) explains the limits of the store probes and the additional measurements required by the SLA rule template.

# Troubleshoot a self-hosted instance
Source: https://docs.tale.dev/self-hosted/operate/observability/troubleshooting

Record the time, affected organization, URL or action, and error code before restarting anything. Check whether the failure affects one item, one organization, or the whole deployment. That distinction determines whether to inspect a file, an organization connection, or shared infrastructure.

For a workspace deployment, start with `tale status` and `tale logs <service> --tail 200`. In your own Compose project, use `docker compose ps` and `docker compose logs --tail=200 <service>`. Service names such as `platform` and `backend-api` differ from generated container names.

## Public URL, certificate, or sign-in fails

| Symptom | Check | Next action |
| --- | --- | --- |
| Connection fails or TLS warns | DNS, public ports, certificate hostname and issuer, proxy logs. | Fix the failing layer. For an internal CA, install its public root certificate on the client; `docker exec ... caddy trust` does not change the client's trust store. |
| Proxy returns 502/503 | Identify the failing path and upstream. `/api/health` and web assets use `platform`; application requests use `backend-api`. | Inspect that service's startup error and readiness before changing proxy configuration. |
| Requests return `503 DATABASE_UNAVAILABLE` | `backend-api` is running, but its database is restarting or unreachable; its log shows `database unavailable` warnings. | Check the database container's state and logs. Requests recover on their own once it accepts connections again. |
| `400 BODY_LENGTH_MISMATCH` or `400 BODY_CHUNK_MALFORMED` | The request body ended before its declared length, or its HTTP/1.1 chunk framing is malformed. | Correct the sender’s body framing or declared length, then retry the well-formed request. |
| Sign-in returns to the login page | Browser cookie and callback requests; configured `SITE_URL`, additional origins, base path, and provider registration. | Correct the mismatched origin or callback and recreate services after environment changes. |

A loading shell with empty data points first to application requests, not necessarily the web server. Inspect failed requests in the browser and `backend-api` logs. A proxy, expired session, permission refusal, and backend outage require different fixes. [TLS and domains](https://docs.tale.dev/self-hosted/configuration/tls-and-domains) and [Authentication](https://docs.tale.dev/self-hosted/configuration/authentication) cover their configuration.

## File uploads or downloads fail

Start by comparing the server's response with the browser's request to the presigned URL. A failure for one organization can come from its own storage connection even when the deployment-default bucket is healthy.

| Observation | Meaning and response |
| --- | --- |
| `object store (skipped)` at boot | The default credential pair is absent. Check `OBJECT_STORE_ACCESS_KEY` and `OBJECT_STORE_SECRET_KEY`; do not generate replacements for an existing store without coordinating its credentials. |
| `object store (ignored)` | The file is operator-managed. Inspect `default/object-storage/connection.json`; environment reconciliation deliberately leaves it alone. |
| `seeded` or `reconciled` | The default connection was written or updated from the environment. This does not prove every object permission or browser route works. |
| Store probe is down | Check endpoint, connectivity, credentials, bucket existence, and the detailed backend error. |
| Server connection test passes but browser upload fails | Check the public endpoint, certificate trust, and bucket CORS for the actual browser origin. Include `GET`, `PUT`, and `HEAD` as required by the file flow. |

`tale_backend_store_up` covers deployment defaults and measures reachability, not a complete upload. An object-store `403` can still produce an up value. Verify an actual controlled upload and download after fixing the connection. [Data residency](https://docs.tale.dev/self-hosted/configuration/data-residency) explains connection changes and file migration.

## A document stays unindexed

Check the document's status and failure reason, then `backend-worker` logs. Confirm the organization's embedding model and credential, vector dimensions, knowledge-database connection, and file support. A successful upload only proves that the original file was stored.

If the worker or a dependency was unavailable, restore it and inspect whether the job resumes or needs **Index now** in [Knowledge](https://docs.tale.dev/platform/knowledge/documents). For a corrupt, encrypted, or unsupported source file, correct the source before retrying. Do not delete a document as the first diagnostic step: its identity, history, and references may matter.

## A website scan reports a certificate error

A crawl error with `tls_error` identifies a failed TLS handshake, such as an expired certificate, a hostname mismatch or an untrusted certificate chain. Fix the site’s certificate or the crawler runtime’s trust configuration, then request another scan. Repeating the same request does not repair certificate trust; do not disable certificate checks to hide the failure.

`network_error` points instead to a connection failure. Read its underlying cause and compare DNS, routing and service availability. [Website crawling](https://docs.tale.dev/platform/knowledge/crawling) explains the page-level errors and scan results.

## Knowledge Postgres crashes during ingestion

Repeated `PANIC: corrupted page pointers` or `signal 6` errors can indicate a damaged BM25 index. Inspect the database logs and the automatic repair result described in [Container architecture](https://docs.tale.dev/self-hosted/operate/container-architecture#recognize-knowledge-index-repair). Confirm the exact corpus database; in the packaged stack it is `tale_knowledge` inside `db`, while other deployments use a separate service or external host.

From an authorized SQL session on that database, this query only verifies the named index:

```sql
SELECT * FROM pdb.verify_index('private_knowledge.idx_pk_chunks_bm25');
```

A missing function, permission error, or timeout is not the same as a confirmed corrupt index. If damage is confirmed and automatic repair did not succeed, preserve a backup and plan a database maintenance operation. Rebuilding a derived index is different from deleting document tables:

```sql
REINDEX INDEX private_knowledge.idx_pk_chunks_bm25;
```

The non-concurrent command can block work. Coordinate it with your database operator, verify the index again afterward, and check ingestion recovery. Do not run speculative reindex or extension-installation commands against the wrong database. Repeated corruption warrants checking disk health and whether shutdowns are being forced past the configured grace period.

## Chat or an automation stops

Check the run or chat error and the owning API/worker logs. A provider `429`, credential refusal, execution timeout, approval wait, and disconnected browser stream are distinct states. An approval wait needs a decision, not a service restart. A disconnected stream can hide an operation that still runs; inspect its stored result before retrying.

For provider failures, check the selected credential's quota and permissions, and the provider's status. Change models only if the replacement is allowed and suitable for the task. For harness failures, inspect `sandbox`, `sandbox-llm-gateway`, the runtime image, and session logs.

## Sandbox network access is refused

Inspect `sandbox-egress` and the target URL. A configured `SANDBOX_EGRESS_ALLOWLIST` must include the required hostname; private and cloud-metadata targets remain blocked. HTTPS tunnels use the supported port policy. Confirm the intended destination before broadening an allowlist, then recreate the egress service when changing its environment.

A healthy egress process does not prove that the remote host, DNS, certificate, or account is available. Keep the specific request error with the incident report.

When many sessions install packages or load pages at once and connections fail with resets while the proxy stays healthy, the proxy may have reached `SANDBOX_EGRESS_MAX_CLIENTS`, the connections it serves at once for all sessions together. Its log then reports that the maximum number of connections was reached. Raise the value, together with the egress container's process and open-file limits, and recreate the egress service.

## Writes fail or storage fills up

Check application-database connectivity, free space, connection usage, and locks. Stop avoidable growth and follow your database procedure to recover capacity. Do not delete volume contents, reset encryption keys, or assume failed writes will replay after a restart. Retry the original operation only after checking whether it persisted.

When seeking help, include versions, sanitized errors, time range, affected scope, and reproduction steps. `tale diagnostics` collects a diagnostic bundle; inspect it before sharing because deployment details can still be sensitive. Report reproducible defects through the [project issue tracker](https://github.com/tale-project/tale/issues).

# Review a release before upgrading
Source: https://docs.tale.dev/self-hosted/operate/release-notes/format

Read the [GitHub release notes](https://github.com/tale-project/tale/releases) for the version you plan to deploy. Start with your installed version, then review every release you will cross. A patch number alone does not establish that there are no migrations or operator actions.

## Identify your starting point

Run `tale --version` to identify the CLI. Also check the deployed runtime version: updating the CLI and rolling the running containers are separate operations. For a managed deployment, use the deployment receipt and its pinned runtime source and image digests.

The current CLI's `tale update` selects a newer version within its existing `x.y` release line. Moving between release lines requires an explicit `--version`. Use `tale update --help` for the options in your installed CLI; read the notes on GitHub.

## Read for deployment impact

Use this order when scanning a release. Headings and detail vary by release; follow any linked migration or advisory before applying the change.

| Information | Decision to make |
| --- | --- |
| Breaking and behavior changes | Which user workflows, defaults or configuration values change? |
| Migrations and upgrading instructions | What prerequisites, downtime or recovery preparation does this version require? |
| API contract changes | Do clients need updated request fields, endpoint behavior or error handling? This section is generated at release time from the contract fingerprint: when `info.version` moved since the previous tag it lists the old and new version, the operations added or removed and the contract changelog entry; otherwise it states that the contract stayed. |
| Security | Is your deployment affected, and what patched version or mitigation applies? |
| Known issues | Can you accept the remaining limitations, and are the workarounds practical? |
| Highlights and full change list | Which new capabilities or fixes should your users know about? |

Tale is a rolling-release 0.x project. Patch releases can include additive migrations and behavior changes. Security fixes target the latest release, without backports to older versions; see the [security policy](https://github.com/tale-project/tale/security/policy).

## Prepare the change

1. Record the current and target versions, including exact source pins for a managed deployment.
2. Read the notes between them and identify changes to configuration, authentication, data storage and integrations.
3. Arrange the backup, recovery path and maintenance window required by [Upgrades](https://docs.tale.dev/self-hosted/operate/upgrades).
4. Try the target in a separate environment and exercise your important workflows, including API clients and approval policies.
5. After deployment, check health and repeat those workflows. Keep the release notes with the deployment record.

A successful image pull is not proof that the application works after a migration. Verify the running platform before considering the upgrade complete. [Security advisories](https://docs.tale.dev/self-hosted/operate/security/advisories) explains how to assess and report a vulnerability.

# Follow security advisories
Source: https://docs.tale.dev/self-hosted/operate/security/advisories

Check [Tale’s GitHub Security Advisories](https://github.com/tale-project/tale/security/advisories) and the target version’s [release notes](https://github.com/tale-project/tale/releases) when reviewing a security update. The repository’s [security policy](https://github.com/tale-project/tale/security/policy) defines reporting and supported versions.

## Assess an advisory

Read the affected and patched versions first. Match them to the running runtime and enabled components, not just the CLI installed on your workstation.

| Information | What to establish |
| --- | --- |
| Affected versions and components | Whether the vulnerable code is present in your deployment. |
| Preconditions and impact | Whether your configuration exposes the vulnerable path and what access it could allow. |
| Patched versions | The release that contains the fix. |
| Severity and any CVSS vector | The reported impact and assumptions; also assess your own exposure. |
| Workarounds | The temporary restrictions available if you cannot deploy the fix immediately. |
| Advisory identifier and references | The stable record to use in your incident and deployment notes. |

Do not infer that a deployment is safe solely because it sits on a private network. Authentication, connector behavior and internal access can still matter. Prioritize the response using the advisory and your incident procedure.

## Apply and verify the fix

Tale is a rolling-release 0.x project. Security fixes land in the latest release only; older versions do not receive backports. Read the notes for every release you cross, then follow [Upgrades](https://docs.tale.dev/self-hosted/operate/upgrades), including backup and recovery preparation.

Record the installed fix and verify the affected behavior after deployment. If you used a temporary workaround, remove it only when the corrected runtime is running and your checks pass.

## Report a vulnerability privately

Open the repository’s **Security** tab and choose **Report a vulnerability**. If you cannot use GitHub, email `security@tale.dev`. Do not disclose an unpatched vulnerability in a public issue.

Include the affected component and version, reproduction steps and likely impact. Use a minimal reproduction without credentials, personal data or unnecessary production records. Reporters can request credit in the resulting advisory.

The security policy commits to acknowledgement and triage within 72 hours, a fix or workaround shared privately with the reporter within 14 days, and publication of a GitHub Security Advisory with the patched release. Use the private report for coordination while investigation is underway.

## Keep the review repeatable

Bookmark the advisory and release pages and include them in your regular update review. Record who checks them, which deployments they cover and where urgent findings are escalated. [Release review](https://docs.tale.dev/self-hosted/operate/release-notes/format) provides the broader checklist; [Hardening](https://docs.tale.dev/self-hosted/operate/security/hardening) covers controls that reduce exposure between updates.

# Investigate audit-log integrity
Source: https://docs.tale.dev/self-hosted/operate/security/audit-log-integrity

Use this runbook when **Chain integrity** reports a break or you receive an audit integrity notification. You need an Admin or Owner account to follow the settings workflow, and access to your deployment operator for database investigation.

## Check the reported range

1. Open **Settings > Governance > Logs** and find **Chain integrity**.
2. Record the status and last automated check. **Not yet checked** means there is no scheduled-check result; it is not a successful verification.
3. Select **Verify now**. A successful result reports how many entries were checked. This on-demand check covers at most 1,000 entries from the beginning of the retained chain.
4. If the result is truncated, ask the operator to verify the remaining range. Clicking again starts the same range; it does not advance a cursor. A clean first page does not establish that the entire history is intact.

The on-demand result and scheduled-check status are separate. Clicking **Verify now** does not update the timestamp of the last automated check.

## Understand what is checked

The current PostgreSQL backend checks the SHA-256 hash of each retained, unscrubbed audit entry and the links between entries. The first surviving row supplies the starting hash link. This detects many changes within the retained chain, but it is not an independently signed record of everything that ever existed.

Retention can remove a prefix of the chain. The scheduled check can resume from its recorded progress; if retention legitimately removed its old anchor, it starts from the first surviving link. A missing anchor inside the retention window is not excused in this way.

For rows scrubbed during personal-data erasure, the verifier checks linkage without recomputing the erased content. It also counts scrubbed rows without a matching erasure request. Investigate such a warning against the erasure records; the current backend does not verify HMAC-signed checkpoints or use an audit signing key to repair these findings.

<Warning title="Keep an independent record">
Hash chaining does not prevent database edits or prove that every action was recorded. Protect database access and retain independent evidence appropriate to your investigation. A complete rewrite of the stored chain is outside what this check alone can establish.
</Warning>

## Preserve a failure

A hash or linkage mismatch shows **Chain integrity broken**, the **Entry ID**, occurrence time, **Expected hash** and **Stored hash**. Use **Open this entry** to inspect the event.

1. Save the finding and the affected organization, entry ID, time and deployed version. Preserve the values exactly.
2. Keep database snapshots and relevant deployment, access and backup logs before making repairs. Restrict access to copies containing personal data.
3. Compare the timing with retention, erasure, restore and maintenance operations. An operation occurring at the same time is a lead to investigate, not proof that the mismatch is harmless.
4. Follow your incident procedure if the mismatch remains unexplained. Do not edit or delete the flagged row to make verification pass.

The [audit-log guide](https://docs.tale.dev/platform/admin/governance/audit-logs) explains event fields and exports. Its filtered, capped export is not a full backup or necessarily a complete chain.

## Follow the scheduled result

A daily job checks organizations with audit entries incrementally. A detected hash break records an active integrity incident and sends a security notification to organization admins. Repeated checks deduplicate the same finding; a changed finding can produce another notification.

After repair or recovery, confirm the affected range verifies successfully. A subsequent successful scheduled check clears the active incident. Explaining a failure to a colleague or dismissing a notification does not repair the chain.

For deployment controls, see [Hardening](https://docs.tale.dev/self-hosted/operate/security/hardening). For the limits that remove old evidence, see [Retention](https://docs.tale.dev/self-hosted/configuration/retention).

# Cryptography and key ownership
Source: https://docs.tale.dev/self-hosted/operate/security/cryptography

Use this inventory to determine which key protects each kind of data and what happens if that key changes. Application secrets, database volumes, network traffic and audit evidence have separate controls. Keep those controls distinct when designing a backup or reviewing a deployment.

## Identify encrypted data

Current provider credentials use the database secret box: AES-256-GCM with a purpose-specific key derived from `ENCRYPTION_SECRET_HEX` through HKDF-SHA256. Other database credentials, including connector OAuth tokens, can use the JWE `dir`/`A256GCM` path backed by the same deployment root. These formats are not interchangeable.

Supported configuration secret sidecars use SOPS with age recipients. This includes external knowledge and object-storage connection secrets. SOPS encryption is configured by `SOPS_AGE_KEY` or `SOPS_AGE_KEY_FILE`; without either, the helper supports plaintext files with restricted permissions. See [Secrets with SOPS](https://docs.tale.dev/self-hosted/configuration/secrets-with-sops) before changing that setting.

Names, addresses, conversations and document content do not receive blanket field-level encryption from those secret mechanisms. Protect the database, object storage and backups with the storage encryption and access controls required for your deployment. TLS protects traffic, not a database file copied from disk.

## Protect network traffic

The public reverse proxy terminates HTTPS. Set the correct domain and certificate source using [TLS and domains](https://docs.tale.dev/self-hosted/configuration/tls-and-domains), then verify the certificate and accepted TLS versions on the deployed endpoint.

Internal Docker networking separates services but is not itself TLS encryption. If your database, object store or other dependency crosses hosts or trust boundaries, configure and verify transport protection for that connection too.

## Preserve password and session controls

Local passwords are hashed with bcrypt. `BETTER_AUTH_SECRET` protects authentication state; keep it stable and consistent across the backend replicas. Changing it can invalidate sessions and disrupt active authentication flows.

An identity provider has its own signing keys and rotation process. Register its current metadata and certificates through [Enterprise SSO](https://docs.tale.dev/platform/admin/enterprise-sso); rotating a Tale session secret does not rotate an IdP key.

## Verify audit evidence

Audit entries form a SHA-256 chain. The current PostgreSQL verifier checks retained rows and their links, starting from the first surviving stored link. It accounts for retention and checks scrubbed rows against erasure requests. It does not verify signed checkpoints.

A chain is tamper-evident, not tamper-proof storage. Protect database access, retain evidence independently where needed and investigate an alert through [Audit-log integrity](https://docs.tale.dev/self-hosted/operate/security/audit-log-integrity). The separate `TALE_AUDIT_PEPPER` pseudonymizes sensitive failed-sign-in identifiers; rotating it changes correlation across that boundary.

## Plan key recovery

Use this table when assembling a restore plan:

| Control | Keep with the recovery plan | If it changes or is lost |
| --- | --- | --- |
| Database secret encryption | `ENCRYPTION_SECRET_HEX` matching the snapshot | Existing encrypted credentials may no longer decrypt. |
| SOPS sidecars | Matching private age keys, including keys for old backups | Files addressed only to a lost recipient cannot be read. |
| Authentication | `BETTER_AUTH_SECRET` and consistent deployment configuration | Existing sessions and active sign-in flows may stop working. |
| Audit verification | Retained audit rows, erasure records and independent evidence | Lost or rewritten history cannot be established from the current chain alone. |
| Host and managed storage encryption | The storage provider’s recovery material and access | Application keys alone cannot unlock the volume or bucket. |

Keep keys in a secret manager or protected recovery store, separate from publicly accessible source and build artifacts. Retain old decryption keys for old backups even after the active deployment rotates. Test a restore with the actual key material in an isolated environment.

For organization certifications and assurance documents, use [Trust and compliance](https://docs.tale.dev/cloud/trust-and-compliance). This implementation inventory explains the technical controls; evaluate the configuration of your own installation alongside those materials.

# Harden a production deployment
Source: https://docs.tale.dev/self-hosted/operate/security/hardening

Review these controls before launch and after changes to your host, network or identity setup. You need operator access to the deployment and a recovery route that remains available while you change access rules.

## Restrict host administration

Use named operator accounts, SSH keys and a supported, patched operating system. Limit access to the host, configuration directory, backups and Docker socket to the people who operate the deployment.

Membership in the `docker` group grants root-level capabilities through the Docker daemon. Running the CLI as a non-root account does not remove that authority. Treat Docker access as privileged administration, as described in [Docker’s post-installation guidance](https://docs.docker.com/engine/install/linux-postinstall/).

## Check public exposure

Allow the intended public proxy ports and restrict administrative access to trusted sources. Keep databases, object-store administration, backend internals and sandbox services off the public network unless a separately reviewed design requires them.

Inspect the ports published by your actual Compose configuration and verify reachability from outside the host. Host firewall rules alone can be misleading because Docker manages forwarding and port-publication rules; follow [Docker’s firewall guidance](https://docs.docker.com/engine/network/packet-filtering-firewalls/).

If you use trusted-header authentication, only the trusted upstream proxy may reach the application. That proxy must remove caller-supplied identity headers before setting its own. See [Authentication](https://docs.tale.dev/self-hosted/configuration/authentication).

The platform’s `robots.txt` discourages indexing of the application but explicitly allows public developer and status paths, including `/docs`, `/openapi.json`, `/llms.txt`, `/llms-full.txt` and `/status`. These crawler instructions are not access controls. Keep confidential data behind authentication and review what your public status report exposes.

## Verify TLS at the public address

Use a trusted certificate for the address people actually open. Configure `TLS_MODE=letsencrypt` for the bundled public TLS path, or `TLS_MODE=external` when your edge terminates TLS. A self-signed local setup does not establish public certificate trust.

Check the certificate chain, expiry and renewal process, then exercise sign-in and callbacks through the public address. [TLS and domains](https://docs.tale.dev/self-hosted/configuration/tls-and-domains) explains the configuration.

## Protect secrets and keys

Replace the example values before production. Give each deployment its own database password, authentication secrets and encryption key. Restrict `.env` and secret files to the operator; store recovery copies in your secret-management system.

Use [SOPS](https://docs.tale.dev/self-hosted/configuration/secrets-with-sops) for supported file-based secrets when appropriate. SOPS does not encrypt every application record or the whole disk. Preserve the matching keys for retained backups. Rotate deliberately using [Cryptography](https://docs.tale.dev/self-hosted/operate/security/cryptography); an arbitrary key replacement can invalidate sessions or make stored credentials unreadable.

Set `TALE_AUDIT_PEPPER` for failed-sign-in pseudonymization. Audit retention is organization-scoped: review each organization’s applied policy and your required evidence period in [Retention](https://docs.tale.dev/self-hosted/configuration/retention).

## Prove recovery

Choose a backup frequency and retention period that match the data loss your organization can tolerate. Include database, configuration, object storage and the secrets needed to restore them. External storage needs its own coordinated backup.

Keep protected copies off the deployment host and restore to an isolated destination periodically. Verify sign-in, files and essential workflows after recovery. [Backups and restore](https://docs.tale.dev/self-hosted/operate/backups-and-restore) explains the CLI snapshot’s scope and service interruptions.

## Limit sandbox destinations

The sandbox egress proxy allows public HTTPS destinations by default while enforcing its private-address and metadata-address restrictions. Set `SANDBOX_EGRESS_ALLOWLIST` to restrict hostnames further. This example belongs in the project’s `.env` and permits two Python package hosts:

```dotenv .env
SANDBOX_EGRESS_ALLOWLIST=^pypi\.org$|^files\.pythonhosted\.org$
```

Recreate the egress service with the updated environment. Confirm required destinations work and an unlisted destination is refused. Add other registries or source hosts only when your workloads need them. The built-in document skills need none to create and read Word, PowerPoint, Excel and PDF files: the libraries they use ship in the sandbox image. Text recognition (OCR) for scanned PDFs is not included. Model traffic uses the separate sandbox model gateway, so this allowlist is not a policy for every outbound connection in Tale.

Review private-network opt-ins separately. `TALE_ALLOW_PRIVATE_PROVIDER_HOSTS=1` admits model-provider destinations, including the sandbox model gateway; it does not open general sandbox egress. `TALE_ALLOW_PRIVATE_CRAWL_HOSTS=1` admits intranet crawl targets and private product image URL values. Enable only the needed path and keep its configuration under operator control. [Providers](https://docs.tale.dev/self-hosted/configuration/providers) explains the model checks; the [environment reference](https://docs.tale.dev/self-hosted/configuration/environment-reference) distinguishes both flags.

## Monitor and investigate

Configure authenticated metrics access with `METRICS_BEARER_TOKEN` and connect your monitoring system. Test that an alert reaches the responsible operator. [Operations](https://docs.tale.dev/self-hosted/operate/observability/operations) covers useful signals.

A daily job verifies retained audit rows incrementally and notifies admins of detected hash-chain breaks. **Verify now** under **Settings > Governance > Logs > Chain integrity** checks at most 1,000 entries. Follow [Audit-log integrity](https://docs.tale.dev/self-hosted/operate/security/audit-log-integrity) for the limits and evidence-preservation procedure.

## Check the deployed response

Inspect security headers at the public address after proxy changes. A proxy can alter the headers produced by Tale, so source configuration alone is insufficient. Check content-security policy, framing restrictions, HTTPS transport policy and content-type handling alongside actual sign-in behavior.

Do not copy cross-origin isolation or HSTS preload settings from another deployment without reviewing your callbacks, external assets and subdomains. Keep the results with your deployment record and repeat the checks after upgrades.

# Upgrade and recover a deployment
Source: https://docs.tale.dev/self-hosted/operate/upgrades

For a workspace deployment, `tale update` changes the CLI and workspace files; `tale deploy` changes the running services. Choose the target version and recovery point before either step. A blue-green rollout overlaps application replicas, but snapshots, drain periods, and stateful-service replacements can interrupt work.

Managed deployments use pinned source revisions and prepared bundles instead of this workspace procedure. Follow [Managed deployments](https://docs.tale.dev/self-hosted/install/cli-install#managed-deployments) for that workflow, or [Configuration releases](https://docs.tale.dev/self-hosted/configuration/config-releases) when only client content changes.

## Prepare the upgrade

1. Run `tale status` in the intended workspace. Record the running version, workspace version, and current deployment state.
2. Read the target release notes for compatibility, required configuration, and known limitations. A pre-0.5 instance needs the separate cutover below.
3. Confirm a restorable off-host backup, the matching keys, and coverage of external databases and buckets. [Backups and restore](https://docs.tale.dev/self-hosted/operate/backups-and-restore) defines the recovery set.
4. Allow capacity for old and new application replicas at the same time. Agree on a maintenance window when snapshots, sandbox replacement, or stateful updates can interrupt required work.
5. Preview the selected update and deployment. Inspect warnings rather than treating a successful preview as proof that a live migration will succeed.

## Select the version

Workspace instance commands try to align the CLI with the version recorded in `tale.json`. If downloading that version fails, the CLI warns and continues with the current binary. Resolve an unexpected mismatch before making deployment changes.

Without a version argument, `tale update` selects the newest release in the workspace's current `major.minor` line. Moving to another line is explicit:

```bash
tale update --dry-run
tale update --version <target-version> --dry-run
tale update --version <target-version>
```

The update replaces the CLI and synchronizes workspace templates, leaving running containers alone. If file synchronization fails, it attempts to return the binary to the workspace's prior version. Review the resulting files and output before deploying.

## Preview and deploy

```bash
tale deploy --dry-run
tale deploy
tale status
```

A version-changing deployment or host-config override takes a local snapshot before mutation unless `--skip-backup` is supplied. This snapshot is additional protection, not an off-host recovery plan.

| Service group | Ordinary deployment | When to plan extra interruption |
| --- | --- | --- |
| `platform`, `backend-api`, `backend-worker` | Roll together as the new application colour. | Old and new replicas overlap, and draining can refuse new turns. |
| `sandbox`, `sandbox-egress`, `sandbox-llm-gateway` | Replace in place after draining relevant work. | These are shared execution dependencies, not a second blue-green application group. |
| `db`, `object-store`, `proxy` | Keep the running services; the CLI reports skipped updates. | Add `--stop` when these services need replacement. |

```bash
tale deploy --stop
```

The role replica variables `TALE_PLATFORM_REPLICAS`, `TALE_BACKEND_API_REPLICAS`, and `TALE_BACKEND_WORKER_REPLICAS` accept 1–16. Increase the role that measurements show is constrained; adding workers does not solve an unavailable database or provider quota.

## Understand the handover

The CLI starts the idle colour and waits for its replicas to pass health checks before completing the handover. Both versions can serve during the overlap, so releases must remain compatible with the previous application version while migrations run.

The old API is drained before removal: new chat turns can receive a drain refusal while existing turns get time to finish. The chat drain waits up to three minutes; the web drain uses `DRAIN_TIMEOUT`, which defaults to 30 seconds. The web health route stays healthy while its alias is still shared. Disconnecting the old containers from serving networks removes them from DNS and can sever remaining connections, so it follows the drains.

Browser tabs opened before the handover still run the previous version. The first time such a tab needs a part of the application that the new version replaced, such as a document preview, it reloads once and continues on the new version. If that part still cannot load after the reload, for example because the tab reached the old colour again, the tab does not reload a second time. It shows **A new version is available** with a **Reload** action instead. A tab that cannot reach Tale at all does not reload; it shows its connection notice until Tale answers again.

If the new group does not become healthy within `HEALTH_CHECK_TIMEOUT`, the deploy does not complete the flip. Inspect the recorded deployment state and logs before retrying. An interrupted rollout can leave both groups or pending handover state; use the CLI's recovery output rather than deleting containers or state files by hand.

## Check migrations and the user outcome

At boot, the backend applies its numbered migrations in file-name order under a session advisory lock. SQL migrations change the schema; TypeScript data migrations update existing rows by the application's own rules. The `app_migrations` table records both kinds by file name, so each runs once per database. Other replicas wait for that migration path. A migration error prevents the new backend from starting normally; inspect its error and the database before retrying. Forward-only migrations are not undone by changing an image tag.

`tale migrate` refreshes built-in organization defaults; it is not a command for rolling database migrations backward. Review whether local configuration was meant to be replaced before using host-config override options.

After deployment, verify the public certificate and sign-in, open an existing project or conversation, download a known file, and run a controlled check of the knowledge and automation paths you use. Check worker progress, store health, and the final deployed version. Keep the pre-upgrade recovery set until the deployment has met your acceptance criteria.

## Choose a rollback path

| Situation | Recovery path |
| --- | --- |
| Return to the recorded previous version in the same `major.minor` line | `tale rollback` checks that boundary and asks for confirmation before redeploying. Review that release's compatibility notes as well. |
| Return across a minor or major boundary | Restore the coordinated pre-upgrade data and deploy its matching version. `tale rollback` refuses this image-only downgrade. |
| Target version or data compatibility is unknown | Resolve the version and backup provenance before starting an older binary. |

```bash
tale rollback
```

`--yes` skips its confirmation for an already approved unattended operation. The CLI's same-line check is a version guard, not an independent proof that every external integration or locally customized configuration is compatible. Never assume that downgrading is safe merely because an old migration list is a prefix of the new one.

`tale rollback` swaps the application images of `platform`, `backend-api`, and `backend-worker` only. It restores no volume and leaves the database, the stores, the proxy, the sandbox services, and the model gateway as they are. No deployment step restores data on its own either: a default deploy (without `--services`) that fails its health checks keeps the previous application colour serving, but the services it already replaced in place stay replaced. Only `tale restore` puts a snapshot's volumes back.

## Bifrost 1.6 → 2.2: the model gateway's store is migrated

A release after 0.5.64 moves the model gateway (`sandbox-llm-gateway`) from Bifrost 1.6 to Bifrost 2.2; its release notes list the move. On its first start, the new gateway migrates its store in `llm-gateway-data` in place and keeps its providers, keys, budgets and admin account; nothing needs to be done by hand. The migration also indexes the gateway's request log, so that start can take longer on an instance with a long request history.

`tale deploy` replaces the gateway before it starts the new application colour, so a deployment that fails later can leave the store already migrated. The snapshot that a version-changing `tale deploy` takes first holds `llm-gateway-data` with the other volumes, so it is the gateway's recovery point too. Snapshots taken before the CLI captured the gateway's store have no such archive; `tale restore` lists them as `without gateway`. If you deploy with `--skip-backup`, copy the volume yourself first: stop the gateway, which ends running agent turns and model calls, copy the volume, then deploy. `<id>` is the `id` in `tale.json`:

```bash
docker stop <id>-sandbox-llm-gateway
docker run --rm -v <id>_llm-gateway-data:/from:ro -v "$PWD/llm-gateway-data-backup:/to" alpine:3.22 cp -a /from/. /to/
```

The gateway of a release before the move starts on the migrated store and serves Tale, but it logs `no such column: oauth_configs.token_id` errors, and Bifrost does not support that downgrade. `tale rollback` does not start that gateway: it leaves the gateway on the newer image and store. That gateway starts when a release before the move is deployed again, for example with `tale update --version` and `tale deploy` after a snapshot restore. Return the store first. Restoring the snapshot taken before the upgrade puts `llm-gateway-data` back with the other volumes. If that snapshot is listed `without gateway`, stop the gateway and put your copy back before you deploy the older release:

```bash
docker stop <id>-sandbox-llm-gateway
docker run --rm -v "$PWD/llm-gateway-data-backup:/from:ro" -v <id>_llm-gateway-data:/to alpine:3.22 sh -c 'find /to -mindepth 1 -delete && cp -a /from/. /to/'
```

A gateway without an admin account, on a new installation or after its volume was replaced, now creates the account only for a caller that presents its setup token, which the image takes from `SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD`. `tale deploy`, the Compose file in the repository and the Kubernetes manifests in these docs already give the gateway that variable. A hand-written Compose file or manifest that passes it only to the backend must pass it to the gateway as well.

Two behaviours change. A caller that hangs up now ends the model call, whether it asked for a whole answer or a stream, so an abandoned request no longer keeps a self-hosted model busy; the model endpoints book such a call at its prompt and the output that had reached the caller. And an upstream that holds back a streamed answer's response headers, such as a router that queues requests until a model is free, must begin its answer within the gateway's request timeout: 600 seconds, or longer when `SANDBOX_LLM_GATEWAY_STREAM_IDLE_TIMEOUT_SECONDS` raises it.

## 0.4 → 0.5: a separate installation

The 0.5 application store replaced the earlier Convex database with Postgres. There is no in-place importer between those stores. Keep the old instance and its backups intact while preparing a fresh deployment in a separate workspace and data set.

Recreate organizations and users, review and transfer compatible configuration, and reimport required documents. Files left in an external bucket do not automatically acquire references in the new application database. Accept the replacement environment before decommissioning the old one.

The CLI refuses the unsupported cutover by default. Its expert `--accept-data-loss` override is not a migration tool and must not be used to preserve old application data. Historical volumes or databases can remain after earlier upgrades; their presence alone is not a reason to delete them during this procedure.

## 0.3 → 0.4: the OpenAI-compatible API was removed

From 0.2.10 through 0.3, Tale served an OpenAI-compatible layer under `/api/v1`: `POST /api/v1/chat/completions` and `POST /api/v1/images/generations` in the OpenAI request and response shapes, and an OpenAI-shaped `GET /api/v1/models`. Its `model` field could name an agent. The 0.4 rebuild removed this layer. Callers of these routes, including OpenAI SDKs pointed at the instance, stop working, because 0.4 serves none of the three routes, and later releases keep them removed. A current release answers chat completions and image generations with `404 NOT_FOUND`, or with `400 ORG_SLUG_REQUIRED` when the key holder belongs to several organizations and the request carries no `X-Organization-Slug`, which an OpenAI SDK does not send by default. Its `GET /api/v1/models` is Tale's own listing of models and agent harnesses, which an OpenAI client cannot read.

Find those callers before the upgrade and plan their replacement. A caller that needs a model's answer can move to the governed model endpoints that releases with API contract 3.7.0 or later offer. They differ from the 0.3 layer: the base URL is `/api/v1/openai`, or `/api/v1/anthropic` for Anthropic clients, rather than `/api/v1`; `model` names a model as `<providerSlug>/<modelId>`, never an agent; image generation is not served; and the endpoints are off until an Admin turns on **Model endpoints for API keys** under **Settings > Governance > Models**. From then on, every call passes model access, the input guardrails, and the budgets. The model endpoints reach the models through the same model gateway as managed agents. Scripted questions for the workspace assistant move to the asynchronous REST chat API, which answers as the assistant rather than as a bare model. Editor integrations that want Tale's knowledge use the MCP endpoint, and work that should run inside Tale, in a sandbox and with a person's review, goes to a project agent on a task. [Use Tale from your editor or a script](https://docs.tale.dev/develop/use-tale-from-your-editor) describes each path.

# Self-hosted architecture
Source: https://docs.tale.dev/self-hosted/overview

A self-hosted Tale deployment runs the application, its storage, and the sandbox services on infrastructure you operate. One deployment can contain several organizations; each organization's records and configuration remain scoped to that organization.

Start with this map when planning capacity or deciding which data to back up. [Run Compose yourself](https://docs.tale.dev/self-hosted/install/own-compose) describes the exact network, mount, and health-probe contract. [Container architecture](https://docs.tale.dev/self-hosted/operate/container-architecture) helps locate a failure in a running instance.

## How the services fit together

The packaged single-host stack has ten services before replicas and temporary sandbox sessions are counted. The contributor stack can use a separate knowledge database. Service names are more useful than container counts when comparing those layouts.

| Layer | Services | Responsibility |
| --- | --- | --- |
| Public entry point | `proxy` | Caddy terminates TLS and routes the browser to the web tier, APIs, and file storage. |
| Application | `platform`, `backend-api`, `backend-worker` | The web tier serves the UI; the API authenticates requests and serves application operations; workers process queued tasks, automations, and ingestion. |
| Persistent storage | `db`, `object-store` | Postgres holds application and knowledge data; the S3-compatible store holds original files and generated media. |
| Sandboxed execution | `sandbox`, `sandbox-egress`, `sandbox-llm-gateway` | The spawner creates execution sessions, the egress proxy controls outbound requests, and the model gateway supplies scoped model access. |
| Video support | `bgutil-provider` | Supplies proof-of-origin tokens for video ingestion. Its availability can affect transcript retrieval. |

The browser connects through the public proxy. Internal database, gateway, and sandbox ports should not be exposed as public services. With an external bucket, presigned file requests can instead go directly from the browser to that bucket's public endpoint.

The application roles use the same Tale platform image. `TALE_ROLE=api` starts the API; `TALE_ROLE=worker` starts a worker. Workers do not expose an HTTP server. The sandbox runtime is a separate image used to create temporary session containers, rather than another permanently running Compose service.

## Where persistent data lives

| Location in the packaged stack | Data to preserve |
| --- | --- |
| `db-data` | `tale_app`: users, chats, runs, audit records, and encrypted database secrets. `tale_knowledge`: extracted content, embeddings, search indexes, and crawled pages. |
| `config-data` | Organization configuration files, including agents, skills, provider definitions, governance settings, SSO configuration, and branding. |
| `object-store-data` | Uploaded documents, attachments, audio, and generated files. |
| `caddy-data`, `caddy-config` | Certificates and proxy state. |
| `llm-gateway-data` | Gateway configuration, session access state, and the gateway's request log of model, tokens and timing, without prompts or answers. |

The packaged stack puts the two databases in one Postgres service and exposes its knowledge connection through the `knowledge-db` network alias. They remain separate databases. A source Compose deployment with a separate knowledge service also has `knowledge-db-data`.

Replacing a container preserves data only if its persistent volumes or external stores remain attached. Keep the deployment workspace, environment, encryption keys, and off-host backups as well. The CLI's snapshots cover these volumes but no external store, and skip the blob volume when the deployment default points at an external bucket; check [Backups and restore](https://docs.tale.dev/self-hosted/operate/backups-and-restore) before relying on them.

## Secrets and sign-in

`ENCRYPTION_SECRET_HEX` protects provider credentials and other encrypted values in the application database. SOPS and age protect supported configuration secret sidecars, such as external storage passwords. Back up the required keys separately from the data they protect; replacing a key does not decrypt existing secrets.

Better Auth runs in the backend. Local sign-in, two-factor authentication, passkeys, enterprise SSO, and trusted-header authentication have different setup requirements. Use [Authentication](https://docs.tale.dev/self-hosted/configuration/authentication) to choose the applicable route, and [Members and roles](https://docs.tale.dev/platform/admin/members-and-roles) for organization permissions.

## Capacity and isolation choices

Application roles can have multiple replicas. The CLI rolls them as one versioned group; upgrades temporarily run both old and new groups, so allow capacity for that overlap. The database, object store, and sandbox plane need their own capacity and recovery plan.

You can move the application database, knowledge database, or blob storage to external infrastructure. An organization can also select its own knowledge database and bucket. Changing a connection does not migrate existing content: plan the copy, cutover, verification, and backup coverage using [Data residency](https://docs.tale.dev/self-hosted/configuration/data-residency).

Self-hosting controls where Tale runs. Provider calls, connectors, web retrieval, and sandbox network access still depend on your configuration. Review those destinations alongside storage placement in [Hardening](https://docs.tale.dev/self-hosted/operate/security/hardening).

# Connect a local model server
Source: https://docs.tale.dev/tutorials/admin/connect-local-provider

Connect a local model server when your organization wants a model served from its own infrastructure. You need an enabled inference endpoint, an exact model ID, access to **Settings > AI providers**, and an operator who can configure the deployment’s network policy. Tale does not install or load the model server for you.

A local chat provider controls where that model request goes. Embeddings, speech, tools and other providers have their own routes; connecting this server does not make all organization traffic local.

## Agree on the endpoint with the operator

Ask the operator for the provider name, compatible API format, base URL, model IDs and authentication method. The address must work from the backend processes, not just from your browser. Inside a container, `localhost` names that container.

For a self-hosted deployment, the operator follows [Local provider endpoints](https://docs.tale.dev/self-hosted/configuration/providers#local-provider-endpoints). You can also create the provider yourself under **Settings > AI providers** with **Add credential** > **Custom provider** ([Define a custom provider](https://docs.tale.dev/platform/admin/providers#define-a-custom-provider)); the operator's steps for network access and policy remain. Private hosts require an explicit deployment opt-in. Public endpoints require HTTPS; supported private addresses can use HTTP when the operator accepts that network arrangement. Adding a proxy hostname does not bypass the private-host policy.

Ollama, LM Studio and vLLM can expose compatible APIs, but compatibility depends on the enabled server features and model. Check the actual model list and a supported chat call before configuring Tale.

## Add the organization’s credential

1. Open **Settings > AI providers** and select **Add credential**.
2. Choose the provider definition the operator prepared, or pick **Custom provider** to define one yourself; a provider you defined carries a **Custom** badge.
3. Name the credential for its purpose and choose the supported authentication method.
4. Supply the server’s real token, or the environment-variable reference the operator provided. If the inference server ignores authentication, agree on the required placeholder with its operator; do not reuse an unrelated secret.
5. Review **Model allowlist**, then save. Make the credential the provider default if ordinary calls should use it.

<Frame caption="A provider credential belongs to the organization; its default and model allowlist affect model selection.">

![The AI providers settings page shows a provider credential and its default badge.](https://docs.tale.dev/images/get-started/settings-providers.webp)

</Frame>

With a model catalog, an empty allowlist permits that catalog. A provider without a catalog needs explicit model IDs. Use **Refresh catalogs** after changing the server’s available models. The organization’s model-access policy also applies.

## Prove one request reaches the server

Start a chat and explicitly select the local model. Leave **Auto** for later: this check needs a known provider and model. Send a short, harmless prompt, such as “Reply with ready.”

Ask the operator to confirm the request in the intended inference server’s logs. Check that Tale displays a completed reply. A saved credential or a populated model list proves less than a completed generation; timing depends on model size, hardware and load.

If coding agents will use this provider, repeat the check in a new sandbox session with the intended model and compatible runtime. Ask the operator to verify the gateway’s DNS, connectivity and TLS trust as well as the backend’s. General sandbox web-access rules do not configure model access. A chat reply and an agent reply verify different paths.

## Resolve a failed check

| Symptom | What to check |
| --- | --- |
| Provider missing from the selection | Definition location, validation errors and organization scope. |
| Private-host refusal | The deployment’s explicit private-provider opt-in; a DNS name alone does not change the rule. |
| Empty model list | Server model discovery, loaded models, credential allowlist and model policy. |
| Connection or certificate error | Backend network reachability, container hostname and TLS trust. |
| Model rejected or no reply | Exact upstream model ID, authentication, API compatibility and server capacity. |
| Chat works but an agent cannot reach the model | Gateway DNS, network access, TLS trust, private-provider opt-in and runtime compatibility. |

[AI providers](https://docs.tale.dev/platform/admin/providers) covers credential rotation and defaults. Keep the endpoint and model ID in the operating handoff so another admin can repeat this test after a server change.

# Make a meeting transcript searchable
Source: https://docs.tale.dev/tutorials/admin/meeting-transcription

Turn an exported meeting transcript into a project reference that people can question from chat. Start with one reviewed text file and verify its scope and indexing before automating the delivery. You need permission to edit the target project and a transcript you are authorized to share with its members.

Tale does not include a dedicated Meetily connector or a watched transcript folder. Export from your transcription tool, then use Tale’s supported document upload or API. This guide starts after transcription; it does not record a meeting or configure the transcription tool.

## Prepare the transcript

Export readable text, preferably a `.txt` file for the first test. Check names, speaker attribution, important numbers and decisions against the meeting record. Automated transcripts can mishear the details people later rely on.

Use a recognizable name such as `2026-09-14-project-review.txt`. Include the meeting date, topic and participants in the file. Remove content the project’s members should not receive. Uploading the text does not require uploading the audio.

## Choose who should find it

Upload to the project’s **Knowledge** tab when the transcript belongs to that project. Project membership controls access, and retrieval happens from that project’s chats. Upload to **Knowledge > Documents** only when it should be organization knowledge under the applicable team scope.

Check the intended audience before uploading. A separate project file is not automatically visible in the organization’s document library or in another project’s chat.

## Upload and inspect

1. Open the target project and select **Knowledge**.
2. Choose the destination folder, then select **Add file** and upload the transcript.
3. Open the file and confirm the title and readable text.
4. Wait for **Indexed** before testing search. **Queued** and **Indexing…** mean the file is still being prepared.

<Frame caption="Use the project’s file list to confirm the destination and indexing status.">

![The project Knowledge tab shows uploaded files and their indexing badges.](https://docs.tale.dev/images/platform/project-knowledge-files.webp)

</Frame>

If the status is **Failed**, inspect the error and use **Retry indexing** after addressing it. If it is **Not indexed**, use **Index now** when offered. Persistent failures may need an admin to check storage, extraction and the embedding provider. [Manage project files](https://docs.tale.dev/platform/projects/manage-files) explains the states and limits.

## Verify retrieval from the project

Open a chat in the same project. Ask a narrow question whose answer you checked in the transcript, such as “In the September 14 review, who agreed to prepare the next draft?” Inspect the cited source and compare the answer with the original text. A completed upload alone does not prove retrieval works, and an assistant answer is not a substitute for that comparison.

Check provider routing before using sensitive transcripts: indexing may send text to an embedding provider, and answering may send retrieved passages to a chat model. Local transcription alone does not keep these later steps local. Ask the admin or operator to verify both routes.

## Make the delivery repeatable

For occasional meetings, keep the upload checklist. For repeated delivery, have a developer use the [project upload API](https://docs.tale.dev/develop/api-reference) or an [automation webhook](https://docs.tale.dev/tutorials/developer/trigger-automation-via-webhook) with an explicitly authored ingestion automation. A webhook starts that automation; it is not a transcript-storage endpoint by itself.

The integration must choose the project, avoid duplicate deliveries, request indexing and monitor its result. REST project-file uploads skip indexing by default unless the bind requests `skipRagIndexing: false`. Reusing a filename does not create a revision; use the supported replacement flow when you need reviewed version history.

# Call Tale from a script
Source: https://docs.tale.dev/tutorials/developer/call-tale-from-a-script

Send one message to Tale and print its reply in your terminal. This tutorial creates a personal chat thread, checks each HTTP response and waits for the assistant to finish. It uses Python 3’s standard library and curl; no Python package installation is needed.

## Prepare access

You need a reachable Tale instance, permission to create an API key, your organization’s slug and a directly callable model. Admins and Developers can create keys. A model listed by Tale can still fail if the provider account has no credit or does not include that model.

Open **Settings > API > REST**, choose **Create API key**, enter a name such as `Reporting script` and choose an expiration. Choose **Create key** and copy the secret shown once. Load it into `TALE_API_KEY` through your secret manager or a private shell environment; do not put it in the Python file or commit it.

<Frame caption="Give the key a recognizable purpose so you can revoke it without disrupting another integration.">

![The Create API key dialog asks for a descriptive name and an expiry before a key is generated.](https://docs.tale.dev/images/get-started/settings-api-keys.webp)

</Frame>

Set the non-secret connection values below. Use the slug, not the organization ID; send the header on every request so the script stays explicit if your account joins another organization.

```bash
export TALE_BASE_URL="https://your-host.example.com"
export TALE_ORG_SLUG="your-org-slug"
export TALE_MODEL="model-id-from-the-catalog"
```

## Find a model you can call

List the models available to this key holder:

```bash
curl --fail-with-body --silent --show-error "$TALE_BASE_URL/api/v1/models" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG"
```

A `200` response contains a `models` array. Set `TALE_MODEL` to an entry’s `id`. If the same ID appears under several providers, also set `TALE_PROVIDER` to the chosen `providerSlug`. An empty array means there is no directly callable model for this account; ask an admin to check credentials and model access.

## Send and wait for one reply

Save this as `tale-chat.py`, then run `python3 tale-chat.py` in the environment configured above. The script creates data in your personal chat history and may incur model usage charges.

```python
import json
import os
import time
from urllib.error import HTTPError
from urllib.request import Request, urlopen

base = os.environ["TALE_BASE_URL"].rstrip("/")
headers = {
    "Authorization": f"Bearer {os.environ['TALE_API_KEY']}",
    "X-Organization-Slug": os.environ["TALE_ORG_SLUG"],
    "Content-Type": "application/json",
}

def request(method, path, body=None):
    data = None if body is None else json.dumps(body).encode()
    req = Request(f"{base}/api/v1{path}", data=data, headers=headers, method=method)
    try:
        with urlopen(req, timeout=30) as response:
            raw = response.read()
            return json.loads(raw) if raw else None
    except HTTPError as error:
        detail = error.read().decode(errors="replace")
        raise SystemExit(f"HTTP {error.code}: {detail}") from error

models = request("GET", "/models")["models"]
model_id = os.environ["TALE_MODEL"]
provider = os.environ.get("TALE_PROVIDER")
candidates = [m for m in models if m["id"] == model_id
              and (not provider or m["providerSlug"] == provider)]
if len(candidates) != 1:
    raise SystemExit("Choose one available model/provider pair from GET /api/v1/models")

thread = request("POST", "/threads", {})
path = f"/threads/{thread['id']}"
sent = request("POST", f"{path}/messages", {
    "content": "In one sentence: what is Tale?",
    "model": candidates[0]["id"],
    "providerSlug": candidates[0]["providerSlug"],
})
reply_id = sent["messageId"]
deadline = time.monotonic() + 600
while True:
    generation = request("GET", f"{path}/generation")
    if generation["status"] == "idle":
        break
    if time.monotonic() >= deadline:
        request("DELETE", f"{path}/generation")
        raise SystemExit("Stopped the turn after the local 10-minute deadline")
    time.sleep(2)

if generation.get("lastMessageId") != reply_id:
    raise SystemExit("The accepted turn did not finish in this thread scope")
reply = request("GET", f"{path}/messages/{reply_id}")
if reply["status"] != "complete":
    raise SystemExit(f"Turn {reply['status']}: {reply.get('errorCode', '')} {reply.get('error', '')}")
if reply.get("finishReason") == "length":
    raise SystemExit("The reply reached its output limit; inspect it before using it")
text = "".join(part["text"] for part in reply["parts"] if part.get("type") == "text")
if not text:
    raise SystemExit("The turn completed without a text answer")
print(text)
```

The message endpoint returns `202` with `messageId` before generation finishes. The generation endpoint becoming `idle` means the turn has settled, not necessarily succeeded. The script then reads that specific assistant message and checks its status, output limit and text before printing.

<Tip>

Keep the thread ID when extending this into an integration. Send later messages to the same thread to preserve conversation context; creating a thread on every invocation starts a new conversation.

</Tip>

## Diagnose a failed request

| Result | Next action |
| --- | --- |
| `401` | Check whether the key expired, was revoked or was copied incorrectly. |
| `400` with `ORG_SLUG_REQUIRED` | Supply the intended organization slug from `data.organizations`. |
| `404` with `ORG_SLUG_INVALID` | The slug names no organization at all — check for a typo, and never paste the dashboard URL's organization ID. Pick a slug from `data.organizations`. |
| `403` with `ORG_FORBIDDEN` | The organization exists, but the key holder is not a member of it — pick a slug from `data.organizations`. |
| `403` | Check the key holder’s permissions for the operation. |
| No model candidate | Read `/models` again and select an exact ID/provider pair. |
| `429` | Honor `Retry-After`; see [Rate limits](https://docs.tale.dev/develop/rate-limits). |
| Message status `failed` | Inspect `errorCode`; fix the provider account or model configuration before retrying. |
| Network timeout | Check the instance and the existing thread before submitting another message. |

A timed-out POST may already have been accepted. Do not blindly send it again: inspect the thread’s generation state and messages first.

The ten-minute deadline belongs to this example, not to the server. A queued turn may be waiting behind other clients, and reasoning can keep a model active before any answer text appears. The script does not automatically repeat a failed send. For unattended retries, persist an `Idempotency-Key` of 1–255 printable ASCII characters with the request body, reuse both after a lost response, and honor `Retry-After` on `429`. See [safe message retries](https://docs.tale.dev/develop/api-reference#retry-a-send-safely).

## Extend the integration

For project-scoped conversations, use `/api/v1/projects/{id}/threads` consistently for creation, messages, generation and reads. You need access to the active project; adding `projectId` to a personal-thread request does not switch its scope.

The [API reference](https://docs.tale.dev/develop/api-reference) covers project access, message parts and automation runs. To start work when an external event arrives, continue with [Trigger an automation via webhook](https://docs.tale.dev/tutorials/developer/trigger-automation-via-webhook).

# Trigger an automation via webhook
Source: https://docs.tale.dev/tutorials/developer/trigger-automation-via-webhook

Connect an external event to a deployed automation and verify both acceptance and the finished run. This tutorial uses a project-scoped webhook, an API key for setup and polling, and curl for delivery. The external sender needs only the webhook URL.

## Prepare a harmless test automation

Choose a deployed automation whose tests pass and whose first run cannot send messages, change customer data or trigger other external effects. A transform that returns its input is enough to verify delivery. Create and deploy it through the app or [MCP](https://docs.tale.dev/develop/mcp-endpoint); REST does not create or deploy automation definitions.

Use an active project where you have edit access and a Developer-capable API key. Set `TALE_BASE_URL`, `TALE_API_KEY`, `TALE_ORG_SLUG`, `TALE_PROJECT_ID` and `TALE_AUTOMATION`. The organization value is a slug; the project value is an ID. In automation URLs, replace `/` within a name with `__`.

## Install the automation in the project

A webhook delivery requires the automation to be installed in the project named by its URL. Install it with the automation name in the path and an empty request body:

```bash
curl --fail-with-body --silent --show-error --request POST \
  "$TALE_BASE_URL/api/v1/projects/$TALE_PROJECT_ID/automations/$TALE_AUTOMATION" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG" \
  -H "Content-Type: application/json" --data '{}'
```

The first installation returns `201`; repeating it returns `200`. A request to the collection `/automations` does not install anything. Read the deployed version’s input contract before sending a delivery.

## Create and protect the trigger

For this new test automation, bind a webhook trigger:

```bash
curl --fail-with-body --silent --show-error --request PUT \
  "$TALE_BASE_URL/api/v1/automations/$TALE_AUTOMATION/triggers" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG" \
  -H "Content-Type: application/json" --data '{"kind":"webhook"}'
```

Copy the returned `token` into the private environment variable `TALE_WEBHOOK_TOKEN`. Tale returns the plaintext only when creating or rotating the token. A later read cannot recover it.

<Warning>

The URL is a credential. Anyone with it can submit deliveries. Keep it out of source, screenshots and public logs. Binding a webhook replaces any existing trigger kind on that automation; do this on the test automation you selected.

</Warning>

The trigger follows the automation name and uses its deployed version. A later deployment can therefore change what the same URL executes. If the URL leaks, rotate or remove the trigger; disabling it only suspends it and re-enabling restores the same token.

## Send one delivery

Post the test event with a stable delivery ID:

```bash
curl --fail-with-body --silent --show-error \
  "$TALE_BASE_URL/api/projects/$TALE_PROJECT_ID/automations/webhook/$TALE_WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-paid" \
  --data '{"orderId":"12345","amount":199.0}'
```

An accepted response is `202` with `runId`. Store that ID as `TALE_RUN_ID`. The automation receives `{"trigger":"webhook","payload":<body>}`, so the order ID is at `input.payload.orderId`. A declared input schema must describe this wrapper.

Repeat the same command. Within the deduplication window, the response keeps the original `runId` and adds `duplicate: true`; no second run starts. IDs are retained for 24 hours. Without an ID header, identical request bytes are deduplicated only within two minutes. Use a new ID for a genuinely new event.

## Verify the run result

Use your API key to read the run in the same project:

```bash
curl --fail-with-body --silent --show-error \
  "$TALE_BASE_URL/api/v1/projects/$TALE_PROJECT_ID/runs/$TALE_RUN_ID" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG"
```

Wait for a terminal status and inspect `output` and `trace`. In the input-returning test automation, confirm that the received payload contains the order ID and amount you sent. A `202` delivery response alone does not prove this result.

When a run fails, read its `failureCode` and `detail`, then inspect the failed node and earlier effects. Replaying the same delivery ID returns the original run, including a failed one; it does not retry its work. A different ID starts new work, so first decide whether repeating already completed nodes is safe.

## Recover the delivery

| Response | Recovery |
| --- | --- |
| `400` | Read `code` and input issues. Fix the payload wrapper or remove a `projectId` query parameter. |
| `403` | Check that the project is active and the automation is installed there. |
| `404` | Check the token and trigger enablement. The endpoint does not reveal which is wrong. |
| `409` | Read `code`: deploy a version, correct the URL scope or resolve the delivery-scope conflict. |
| `413` | Reduce the payload below 256 KiB or send a reference. |
| `429` | Wait for `Retry-After`, then retry with the same delivery ID. |

Retry network failures and temporary server errors with bounded backoff and the same ID. Fix other client errors before retrying; repeated invalid requests cannot repair configuration. Remove the test trigger when you no longer need its URL. The [webhook reference](https://docs.tale.dev/develop/webhooks) lists all accepted ID headers, rotation behavior and limits.

# Build your first agent
Source: https://docs.tale.dev/tutorials/editor/first-agent-end-to-end

Build an agent that summarizes a contact message and recommends a next action. This exercise uses the task description as its input, so you can check the whole loop before adding connectors or shared knowledge: configure the agent, start one task, then review the result.

## Before you begin

You need a project you can edit, an available coding-agent harness with compatible model credentials, and a working sandbox allocation. An administrator manages [AI providers](https://docs.tale.dev/platform/admin/providers) and [Sandboxes](https://docs.tale.dev/platform/admin/sandboxes). A model that works in Chat is not enough by itself: the selected harness must be able to use its credential.

If the Agents page or model list is unavailable, resolve access or setup first. This tutorial does not require skills, connectors, platform tools, or injected secrets.

## Create the agent

Open the project's **Agents** tab and click **New agent**.

<Frame caption="The Agents table identifies each agent by its harness, provider, and model.">

![Website relaunch lists Content editor using Claude Code and Redirect auditor using Codex, with their provider and model beside the New agent button.](https://docs.tale.dev/images/platform/project-agents-models.webp)

</Frame>

1. Set **Name** to `Triage assistant`.
2. Choose an **Agent type** that your administrator has configured.
3. Under **Model**, search by model name or API ID and select the entry for the intended provider. The same model can appear from more than one provider.
4. Under **Skills, connectors & tools**, untick any document skills that are preselected, and leave **Secrets** empty for this exercise.
5. Paste the instructions below into **Instructions**, then click **Create agent**.

```text
Read the contact message in the task description. Return two lines:
Summary: one sentence explaining what the person needs.
Next action: reply, escalate, or close, followed by a short reason.
If the message has no usable request, say what information is missing.
Do not contact anyone or change records.
```

The new row is ready to be assigned a task. There is no separate publish step. Keep the agent's instructions about its recurring job; the individual message belongs in the task.

## Give it a task with a checkable answer

Open **Tasks**, create a task called `Triage the invoice-copy request`, and paste this into its description:

```text
Contact message:
“Hello, I received the order confirmation, but cannot find the invoice.
Could you send me a copy? The order number is A-1042.”

Acceptance criteria:
- Summarize the request in one sentence.
- Recommend reply, escalate, or close, with a reason.
- Do not say the invoice has already been sent.
```

Assign the task to `Triage assistant`. Open its details to set a **Reviewer** if someone else should review it; otherwise the task's creator receives the review request. Click **Start agent**. Assigning alone does not start work.

The task moves to **In progress**. A successful run posts its report as a comment and moves the task to **In review**. The sandbox and provider must be working for that run to complete.

## Review and improve the result

Read the agent's comment against the acceptance criteria. A suitable answer recognizes a request for an invoice copy and recommends replying; it must not claim an email was sent. Wording may vary by model.

Move the task to **Done** when you accept the result. If something is missing, mention the assigned agent in a task comment and give a specific correction, such as “Keep the summary to one sentence and explain why a reply is needed.” The follow-up continues the task conversation and returns a new result for review.

<Tip>

Change the task comment for a one-time correction. Edit the agent's instructions when the same rule should apply to its future tasks. Add tools only when a later exercise needs the agent to read or change something outside the supplied input.

</Tip>

## If the run cannot start or finish

A missing model calls for a provider and harness check. A sandbox error needs an administrator to check capacity and infrastructure. A failed task run stays visible for inspection; correct the cause before retrying. Avoid repeatedly starting the task while a run is already active.

[Task automation](https://docs.tale.dev/platform/projects/task-automation) explains retries, cancellation, reviewer handoff, and rework. [Project agents](https://docs.tale.dev/platform/projects/project-agents) covers the equipment you can add after this first task works.

# Build a workflow with an approval
Source: https://docs.tale.dev/tutorials/editor/workflow-with-approvals

This exercise creates a two-step workflow: prepare a message, then request permission to send it. You will inspect the exact recipient and text on a waiting run and reject the operation. That gives you a complete approval example without needing to deliver a real message.

## Before you begin

Use a Developer, Admin, or Owner account. Confirm that your organization's approval policy requires approval for `imap-smtp.send`; the default policy does. A custom policy can change that behavior, so check [Configure approvals](https://docs.tale.dev/platform/approvals/configure) before starting the live part.

The mock test needs no mailbox credential. A real approved send would need a configured IMAP / SMTP connector and a recipient you intend to contact. This exercise ends with **Reject**.

## Import the example

Save the following as `workflow.yml`. The `draft` node returns fixed text so the result is easy to verify. The `send` node reads it; those references create the connection on the canvas.

```yaml
version: 1
name: docs/approval-check
description: Practice reviewing an outgoing message before it is sent.
nodes:
  - id: draft
    type: transform
    code: |
      return {
        subject: "Approval practice",
        text: "This is a test message for the approval walkthrough."
      };
  - id: send
    type: imap-smtp.send
    input:
      to: reviewer@example.com
      subject: '{{ nodes.draft.output.subject }}'
      text: '{{ nodes.draft.output.text }}'
output:
  messageId: '{{ nodes.send.output.messageId }}'
tests:
  - name: prepares the outgoing message
    input: {}
    expect:
      effects:
        - connector: imap-smtp.send
```

1. Open **Automations > Create automation > Upload package**.
2. Choose `workflow.yml` and leave **Install into** set to **Organization**.
3. Click **Upload package**. Tale validates the document and saves `docs/approval-check` as a draft.
4. Choose **Later** in the deployment prompt, then open **Approval check** from the list. It opens on **Editor**.

If that name already exists, uploading adds another version. Use a different workflow `name` if you want a separate exercise.

<Frame caption="Upload package accepts the workflow file and lets you choose its organization or project scope.">

![The Upload package dialog shows a file picker and the Install into selector set to Organization.](https://docs.tale.dev/images/platform/automations-upload-dialog.webp)

</Frame>

## Test the data flow

On **Editor**, click **Test run**. This example has no runtime input, so it can run with an empty object. Switch to **Runs**. The list should show a **Succeeded** test run.

Open the run and check that the canvas shows both nodes as **Ran**. Select `send` and inspect its resolved input. The recipient should be `reviewer@example.com`, the subject `Approval practice`, and the text the sentence from `draft`. The connector uses a deterministic mock in this mode. No email is sent and no approval card appears.

The workflow includes a test expecting the `imap-smtp.send` effect. A passing mock confirms the graph and proposed call; it does not prove mailbox credentials or message delivery.

## Start the live approval check

Return to **Editor** and click **Deploy v1** to make the tested version live. Leave the trigger unconfigured; this exercise starts once by hand.

Choose **Run live**, read the confirmation and organization scope, then confirm. Switch to **Runs** and open the new **Waiting** run. Its approval card should show **Waiting for your approval**, `imap-smtp.send`, the `send` node, and **The step would call with** containing the same recipient, subject, and text you checked in the mock.

If the run does not wait, inspect its status and policy before continuing. A failed connector call is not proof that an approval was requested.

## Reject and inspect the outcome

Click **Reject** on the card. The operation is refused and the run ends as **Failed**. This is the expected result of this exercise: the workflow reached its human decision, and the outgoing message was not sent.

You cannot edit a pending call's parameters on the card. If a real proposed message is wrong, reject it, correct the definition or input, and start a new run. Approval of a later correct call authorizes that actual operation; it is not just an acknowledgment that you read the card.

For an agent that needs an answer instead of permission, use its `ask_human` capability. That is a different wait, explained in [Approvals in workflows](https://docs.tale.dev/platform/automations/approvals-in-workflows). [Execution logs](https://docs.tale.dev/platform/automations/execution-logs) helps distinguish these waits from an agent still working.

# Get a useful answer from chat
Source: https://docs.tale.dev/tutorials/member/chat-effectively

A useful chat answer starts with a clear question and ends with a source check. In this exercise, use a short document you are allowed to upload, ask about a fact in it, then test whether the assistant distinguishes what the document says from what it leaves open.

You need access to Chat and an available model. For document questions, your organization also needs working knowledge indexing. If you already have a suitable indexed document, you can use it instead of the example.

## Prepare a small source

Save this text as `launch-brief.txt` on your device:

```text
Website relaunch brief
The customer review is on 18 September 2026.
Maya Chen owns the review checklist.
The launch date has not been approved.
The review must cover accessibility, redirects, and the contact form.
```

Open a new chat and attach the file through **Add photos & files** in the composer menu. Wait until uploading and indexing have finished before asking about its text. [Chat attachments](https://docs.tale.dev/platform/chat/attachments) explains the status shown on the attachment.

## Ask for a specific result

Send:

```text
Using launch-brief.txt, list the review date, the checklist owner, and the
three review topics. Cite the source. Keep the answer to four bullets.
```

The request names the source, the facts you need, and the output shape. It is easier to evaluate than “Tell me about the launch.” **Auto** is a reasonable starting point; choose a model explicitly when you need to compare its behavior with another one.

<Frame caption="Keep the question visible while checking whether the answer meets it.">

![A chat shows a focused question about onboarding feedback and a response organized into a table.](https://docs.tale.dev/images/platform/chat-thread-reply.webp)

</Frame>

## Check the answer against the file

The review date should be **18 September 2026**, the owner **Maya Chen**, and the topics **accessibility, redirects, and the contact form**. Open the cited source and compare those values. Formatting can vary; the facts should not.

If the answer lacks a source, ask it to cite the document rather than assuming the attached file was read. If it cannot find the content, check the attachment's indexing state and retry after it is ready. A fluent answer is not evidence of retrieval.

## Ask a follow-up that exposes uncertainty

In the same conversation, ask:

```text
What is the approved launch date? If the brief does not give one, say so.
```

The source does **not** give an approved launch date. A good answer preserves that distinction instead of using the review date as the launch date. When an answer makes an unsupported assumption, point to the conflicting sentence and request a correction.

<Tip>

Change one part of the request at a time. “Make it shorter” tests length; “separate confirmed dates from open decisions” tests interpretation. Changing the source, model, question, and format together makes it difficult to see what improved the result.

</Tip>

## Keep the useful context

Continue the same chat for related questions. Start a new one for an unrelated topic so old assumptions do not distract from the new task. If several conversations need this brief, put it in a [project](https://docs.tale.dev/tutorials/member/use-projects) and use project chat.

Before [sharing a chat](https://docs.tale.dev/platform/chat/shared-threads), read the messages and any source excerpts in the answer. If the next step is producing a deliverable that needs an owner and review, create a [project task](https://docs.tale.dev/platform/projects/tasks) with the verified facts and acceptance criteria.

# Use a project for shared context
Source: https://docs.tale.dev/tutorials/member/use-projects

A project keeps the files, instructions, conversations, and tasks for one piece of work together. In this walkthrough, you ask a question that a project's reference file answers, share the useful conversation, and hand the follow-up deliverable to one of the project's agents. Allow about fifteen minutes, plus the time needed to index a file and for the agent's run.

## Before you begin

As a **Member**, you work in the projects shared with you: you ask in their chats, share conversations, and create tasks for the project's agents. Pick a project you can open that has an indexed reference file, and start at [Ask a question and check the source](https://docs.tale.dev/tutorials/member/use-projects#ask-a-question-and-check-the-source). A project without agents of its own hands its tasks to the organization's [standard agent](https://docs.tale.dev/platform/projects/project-agents#standard-agent), unless an admin has turned it off. Creating a project, uploading its files, saving its instructions, and adding agents need the **Editor** role or higher; if you are setting the project up, start at [Set up the project](https://docs.tale.dev/tutorials/member/use-projects#set-up-the-project). You need a short text document, PDF with selectable text, or modern Office file. Choose a file whose contents you can verify, such as a project brief with a named owner and a review date. An admin must have configured document storage and an embedding model for searchable uploads.

New projects are **Org-wide**. Use non-sensitive material for this walkthrough; if the real project needs restricted access, set its owning team under **General > Sharing** before uploading its files. Project chats remain personal until you share them.

## Set up the project

Editors and higher roles do this once per project. Members skip to [Ask a question and check the source](https://docs.tale.dev/tutorials/member/use-projects#ask-a-question-and-check-the-source).

### Create the project

1. In Home, click **New project**, the folder icon beside **Projects**.
2. Set **Project name** to a recognizable name, such as `Website relaunch`.
3. Check **Project key**, the short prefix used in task identifiers such as `WEB-1`. It cannot be changed after creation.
4. Add an optional **Description** and click **Create project**.

The new project opens on **Tasks** and appears under **Projects** in Home. The project's navigation also includes **General**, **Chats**, **Knowledge**, and **Agents**. You do not need to create an agent to use project chat.

### Upload a reference file

Open **Knowledge** in the project and click **Add file**, or drop your file onto the upload area. The file appears in the project’s file tree. Wait for **Indexed** before relying on search; **Queued** and **Indexing…** mean the file is still being prepared.

<Frame caption="The Knowledge tab keeps reference files inside the project; the status beside each file shows whether it is searchable.">

![The Website relaunch project’s Knowledge tab lists two indexed files and offers controls to add files and folders.](https://docs.tale.dev/images/platform/project-knowledge-files.webp)

</Frame>

A file uploaded here belongs to this project. To ask about it, use a chat inside the project. The organization’s general chat does not search project files.

### Add instructions that apply to every project chat

Open **General**, find **Instructions**, and describe the context or constraints that every chat should follow. For example:

> Use the project files when answering questions about this launch. Cite the source for dates and decisions. If a launch date has not been approved, say that it is unconfirmed.

Click **Save** in the page header. The instructions are part of the project’s chat context; they do not replace the need to upload and retrieve the underlying documents.

<Frame caption="Instructions live on General, alongside the project’s name and description.">

![The General tab contains the project name, description, Instructions editor, and Sharing section, with Save and Discard in the header.](https://docs.tale.dev/images/platform/project-general-tab.webp)

</Frame>

The last part of this walkthrough hands a task to an agent: one of the project's own or, until it has any, the organization's [standard agent](https://docs.tale.dev/platform/projects/project-agents#standard-agent). [Project agents](https://docs.tale.dev/platform/projects/project-agents) explains how to add one.

## Ask a question and check the source

Open **Chats** and click **New chat**. Leave the model on **Auto** when it is available, then ask a question that your file answers. For a launch brief, try:

> Read the launch brief. Who owns the review, and which dates are confirmed? Cite the file and distinguish confirmed dates from open decisions.

Check the search and reading steps above the reply, then compare the answer with the file. A fluent reply without a supporting source is not proof that Tale used your document. Reopen **Knowledge** to inspect the original when necessary.

<Tip>

Name the document and the specific question. “Which review date is confirmed in the launch brief?” gives the assistant a clearer retrieval target than “Tell me about the project.”

</Tip>

## Share the useful conversation

The **Chats** tab separates **Your chats** from **Shared with project**. Enable **Share with project** on a chat when the people who can access this project should be able to read it. Uploading project files does not share your chats automatically.

For a one-off link to a snapshot for organization members, follow [Shared chats](https://docs.tale.dev/platform/chat/shared-threads). Check the transcript before sharing: its text may contain details from sources with a narrower audience.

## Hand the follow-up work to a project agent

Chat answers questions; it doesn't produce files. When the answer should become a document, such as a one-page launch summary, give the work to one of the project's agents on a task.

1. In the conversation's header, select **Create task**. Because the chat belongs to this project, **Create task** opens there, holding your last question as the description, a link back to the chat, and any files you attached.
2. Rewrite the description as the result you want, for example: `Draft a one-page launch summary from the brief as a Word document. Cite the brief for every date.`
3. Under **Assignee**, choose one of the project's agents if none is chosen yet; in a project without agents of its own, the standard agent already is. Then select **Create and start agent**.
4. Follow the run above the chat's message box; **Open** there takes you to the task.

When the run ends, the agent's report is in the task's comments, the file is under **Deliverables**, and the task waits in **In review**. Mention the agent with `@` in a comment to ask for changes, and move the task to **Done** when the result meets the description.

Any member can create tasks in a project they can open. A run that a Member starts keeps to that task and its subtasks and works without the agent's secrets; [Agent runs a Member starts](https://docs.tale.dev/platform/projects/tasks#agent-runs-a-member-starts) lists the limits.

## If the file is missing from the answer

| What you see | What to check |
| --- | --- |
| Upload fails before a row appears | Retry with a small supported file. If that also fails, ask an admin to check document storage and the upload policy. |
| **Queued** or **Indexing…** | Let processing finish, then ask again. |
| **Failed** | Use **Retry indexing**. If the failure returns, ask an admin to check the embedding model and knowledge service. |
| **Not indexed** | Use **Index now** when offered. Convert a legacy Office file to its modern format if it has no supported text extractor. |
| **Indexed**, but the reply has no relevant source | Confirm the chat belongs to this project, name the file, and ask for one specific fact. Verify the result against the original. |

The project now holds its sources, conversations, and tasks together. [Manage project tasks](https://docs.tale.dev/platform/projects/tasks) covers the task board, reviews, and repeating work.

# Tutorials
Source: https://docs.tale.dev/tutorials/overview

Choose a task you want to try in your workspace. Each tutorial gives you a starting point, example inputs, and checkpoints so you can tell whether it worked. If you have never used Tale, start with [your first chat](https://docs.tale.dev/get-started/quickstart).

## Start with everyday work

<CardGroup cols="2">

<Card title="Get a useful chat response" icon="message-circle" href="https://docs.tale.dev/tutorials/member/chat-effectively">

Give the model context, refine its answer, and check the result before using it.

</Card>

<Card title="Organize work in a project" icon="folder" href="https://docs.tale.dev/tutorials/member/use-projects">

Bring a task, a source file, and project instructions together. Choose what to share with your team.

</Card>

</CardGroup>

## Build and connect

These tutorials need additional permissions or a configured service. Check the prerequisites on the tutorial before you start; an ordinary chat does not need an agent runtime.

| Your goal | Tutorial | What you need |
| --- | --- | --- |
| Delegate a project task | [Run your first agent](https://docs.tale.dev/tutorials/editor/first-agent-end-to-end) | Permission to configure project agents, a model, and a working agent runtime |
| Review a workflow action before it runs | [Build a workflow with approvals](https://docs.tale.dev/tutorials/editor/workflow-with-approvals) | Automation editing access and an eligible approver |
| Send a message from your own program | [Call Tale from a script](https://docs.tale.dev/tutorials/developer/call-tale-from-a-script) | A running instance, a model, an API key, and Python |
| Start an automation from another system | [Trigger an automation via webhook](https://docs.tale.dev/tutorials/developer/trigger-automation-via-webhook) | A published automation and a securely stored webhook credential |
| Connect a local model server | [Connect a local provider](https://docs.tale.dev/tutorials/admin/connect-local-provider) | Administrative access and a model server reachable from Tale |
| Make a meeting transcript searchable | [Add meeting transcripts to a project](https://docs.tale.dev/tutorials/admin/meeting-transcription) | A reviewed transcript, project editing access, and working document indexing |

## Find a reference while you work

The [Platform guides](https://docs.tale.dev/platform) explain individual features and their limits. [Self-hosted documentation](https://docs.tale.dev/self-hosted) covers deployment and server configuration. The [developer documentation](https://docs.tale.dev/develop/overview) covers APIs and source contributions.

# Episode 5 — Automations & approvals
Source: https://docs.tale.dev/tutorials/videos/automations-and-approvals

By the end of this episode you'll have used an automation for real: you read the installed triage workflow before trusting it, create a task and watch it get scored and assigned on camera, follow that run through its journal, open the one that failed and trace it to its step — and approve an outbound customer email with your own click, then find that decision in the audit log seconds later. Step by step, at a pace you can follow along with. The approval scene was recorded on the earlier version, where the card sat in chat and could be adjusted before submitting; in this version a gated connector write parks the run, and the card — **Approve** or **Reject**, no edits — sits on the run's detail page.

<Video src="https://docs.tale.dev/videos/en/tutorials/ep5-automations/ep5-automations.en.mp4" poster="https://docs.tale.dev/videos/en/tutorials/ep5-automations/ep5-automations.en.webp" captions="https://docs.tale.dev/videos/en/tutorials/ep5-automations/ep5-automations.en.vtt" lang="en" title="Episode 5 — Automations & approvals" caption="Episode 5 — Automations & approvals (6:20, captions available)">

</Video>

## What the episode shows

| At   | Scene                                                    |
| ---- | -------------------------------------------------------- |
| 0:27 | The job: a board of unowned tasks                        |
| 0:48 | The catalog, and what a bundle's preview panel tells you |
| 1:44 | Reading the workflow: trigger, score step, schema        |
| 2:45 | The tester — and the honest way to trigger a run         |
| 3:04 | A real task, created and auto-assigned on camera         |
| 3:58 | The red run, diagnosed down to its step                  |
| 4:40 | The approval card: read, adjust, submit                  |
| 5:32 | The decision in the audit log                            |

## Where to go next

[Automation concepts](https://docs.tale.dev/platform/automations/concepts) and the [catalog](https://docs.tale.dev/platform/automations/catalog) cover the bundles; the [editor](https://docs.tale.dev/platform/automations/editor), [triggers](https://docs.tale.dev/platform/automations/triggers), and [execution logs](https://docs.tale.dev/platform/automations/execution-logs) go deep on what you saw. For the card itself, read [approval concepts](https://docs.tale.dev/platform/approvals/concepts) and [approvals in workflows](https://docs.tale.dev/platform/automations/approvals-in-workflows) — then build one with the editor tutorial [a workflow with approvals](https://docs.tale.dev/tutorials/editor/workflow-with-approvals).

# Episode 2 — Chat, in depth
Source: https://docs.tale.dev/tutorials/videos/chat-in-depth

Episode 1 toured the workspace; this episode moves into the room your team will actually live in — and runs a full working session. Its core beat is a controlled experiment: the same onboarding question asked twice, once with no context and once with the Q2 support review attached, so you watch a fluent answer and a grounded answer stop being the same thing. Then the grounded thread gets questioned ("which document says that?"), an Arena verdict gets decided with reasons, and a leadership brief lands on the canvas — and gets cut to three bullets with one sentence.

<Video src="https://docs.tale.dev/videos/en/tutorials/ep2-chat/ep2-chat.en.mp4" poster="https://docs.tale.dev/videos/en/tutorials/ep2-chat/ep2-chat.en.webp" captions="https://docs.tale.dev/videos/en/tutorials/ep2-chat/ep2-chat.en.vtt" lang="en" title="Episode 2 — Chat, in depth" caption="Episode 2 — Chat, in depth (5:44, captions available)">

</Video>

## What the episode shows

| At   | Scene                                                    |
| ---- | -------------------------------------------------------- |
| 0:27 | The composer's three choices: agent, model, context      |
| 0:48 | The experiment, part one: asking with nothing attached   |
| 1:06 | The trap, read together — fluent, confident, guessing    |
| 1:24 | Part two: the same question, grounded in a real document |
| 2:00 | Questioning the answer: "which document says that?"      |
| 2:20 | Rating an answer — where feedback analytics begin        |
| 3:00 | Arena Mode: two models, one prompt, a reasoned verdict   |
| 3:53 | The canvas: a brief lands as a file, then gets refined   |
| 4:39 | Deep research, and where it lives                        |

## Where to go next

[Chat basics](https://docs.tale.dev/platform/chat/basics) covers the composer, the three retrieval tools, and the thought timeline in reference depth. For the model side, read [models](https://docs.tale.dev/platform/models) and [Arena Mode](https://docs.tale.dev/platform/chat/arena-mode); for work that ends in a deliverable, [Agent concepts](https://docs.tale.dev/platform/agents/concepts) is where chat hands off.

# Episode 7 — Connectors & the outside world
Source: https://docs.tale.dev/tutorials/videos/connectors

Your workspace does not live alone. This episode walks the doors to the outside world and the discipline built into each one: a connector you can read before you open it, the capability that lights up when a connector is bound, the MCP door as the earlier version showed it, and a sandbox network that answers no by default.

<Video src="https://docs.tale.dev/videos/en/tutorials/ep7-connectors/ep7-connectors.en.mp4" poster="https://docs.tale.dev/videos/en/tutorials/ep7-connectors/ep7-connectors.en.webp" captions="https://docs.tale.dev/videos/en/tutorials/ep7-connectors/ep7-connectors.en.vtt" lang="en" title="Episode 7 — Connectors & the outside world" caption="Episode 7 — Connectors & the outside world (2:30, captions available)">

</Video>

<Note>

The MCP segment (1:00–1:31) was recorded on the earlier version's **MCP servers** panel. Registering an external server and its per-tool approval flags are not part of this version — Tale's one MCP surface is the inbound endpoint under **Settings > API > MCP**, where your client drives Tale. Watch it for the pattern at every door; [MCP servers](https://docs.tale.dev/platform/connectors/mcp-servers) says what replaced the panel.

</Note>

## What the episode shows

| At   | Scene                                                                |
| ---- | -------------------------------------------------------------------- |
| 0:13 | The catalog: connect once, the whole workspace borrows it            |
| 0:30 | Reading the door: operations and allowed hosts, before anything runs |
| 0:46 | The payoff: deep research exists because Tavily is bound             |
| 1:00 | MCP: your own tools, served to agents like native ones               |
| 1:15 | Per-tool approval flags — native-looking is not native-trusted       |
| 1:51 | The pattern at every door                                            |

## Where to go next

The [connectors overview](https://docs.tale.dev/platform/connectors/overview) covers connecting and sharing connectors; [MCP servers](https://docs.tale.dev/platform/connectors/mcp-servers) what stands in for the MCP door in this version. For the network boundary, read [Hardening](https://docs.tale.dev/self-hosted/operate/security/hardening) — and for what a bound connector unlocks, see [automation concepts](https://docs.tale.dev/platform/automations/concepts).

# Episode 9 — Governance, cost & trust
Source: https://docs.tale.dev/tutorials/videos/governance-and-trust

The finale is for whoever answers for AI in the organization. It tours the control room end to end — which models run and for whom, the guardrails that scan both directions, the audit log where episode five's approval actually landed, the cost and quality charts where episode two's Arena verdicts ended up, and the region dial — then closes the series with its five habits: ground it, gate it, scope it, log it, measure it.

<Video src="https://docs.tale.dev/videos/en/tutorials/ep9-governance/ep9-governance.en.mp4" poster="https://docs.tale.dev/videos/en/tutorials/ep9-governance/ep9-governance.en.webp" captions="https://docs.tale.dev/videos/en/tutorials/ep9-governance/ep9-governance.en.vtt" lang="en" title="Episode 9 — Governance, cost & trust" caption="Episode 9 — Governance, cost & trust (3:01, captions available)">

</Video>

## What the episode shows

| At   | Scene                                                           |
| ---- | --------------------------------------------------------------- |
| 0:16 | Providers: one gateway, your own keys, or your own hardware     |
| 0:32 | Model policy: who may use which model                           |
| 0:47 | Guardrails: PII masked, unsafe content blocked, both directions |
| 1:06 | The audit log — episode five's approval, on the record          |
| 1:24 | Usage analytics: cost with names on it, budgets that warn       |
| 1:40 | Feedback analytics: quality measured, Arena verdicts included   |
| 1:56 | Data residency: a setting, not a negotiation                    |
| 2:10 | The five habits of using AI well                                |

## Where to go next

[Providers](https://docs.tale.dev/platform/admin/providers) and [models](https://docs.tale.dev/platform/models) cover the machinery; [content models](https://docs.tale.dev/platform/admin/governance/content-models) and [policies and limits](https://docs.tale.dev/platform/admin/governance/policies-and-limits) the policy layer; [guardrails](https://docs.tale.dev/platform/admin/governance/guardrails), [audit logs](https://docs.tale.dev/platform/admin/governance/audit-logs), [usage analytics](https://docs.tale.dev/platform/admin/governance/usage-analytics), and [feedback analytics](https://docs.tale.dev/platform/admin/governance/feedback-analytics) the controls you toured. For residency, see [cloud data residency](https://docs.tale.dev/cloud/data-residency).

# Video tutorials
Source: https://docs.tale.dev/tutorials/videos

The video series walks the platform the way a colleague would show it to you: on screen, area by area, with the honest caveats spoken out loud. Episodes are short — three to four minutes — and each one picks up a piece of general AI literacy along the way: what grounding means, why hallucinations happen, where a human belongs in the loop.

Every episode page carries the video with captions in the page's language, a chapter list, and links into the deeper reference pages.

<CardGroup cols="1">

<Card title="Episode 1 — Welcome to Tale" icon="play" href="https://docs.tale.dev/tutorials/videos/welcome-to-tale">

The guided tour: ask a grounded question, find the cited file in Knowledge, meet the agent that answered, and read a live automation's journal. Four minutes.

</Card>

<Card title="Episode 2 — Chat, in depth" icon="play" href="https://docs.tale.dev/tutorials/videos/chat-in-depth">

A real working session: the same question ungrounded and grounded, a source check, a reasoned Arena verdict, and a brief built and refined on the canvas. Six minutes.

</Card>

<Card title="Episode 3 — Knowledge" icon="play" href="https://docs.tale.dev/tutorials/videos/knowledge">

Work inside the library: create an entry and hear it cited back, learn what Indexed means, look up a record, read the crawler's boundary — and meet the stale-knowledge trap live. Six minutes.

</Card>

<Card title="Episode 4 — Your first agent" icon="play" href="https://docs.tale.dev/tutorials/videos/your-first-agent">

An agent built end to end on camera in the earlier agent editor — instructions, knowledge scope, tools, model — then tested live; the screens have changed since, the reasoning has not. Capability is exposure: start small. Three minutes.

</Card>

<Card title="Episode 5 — Automations & approvals" icon="play" href="https://docs.tale.dev/tutorials/videos/automations-and-approvals">

Use a live automation end to end: read the triage workflow, trigger a real run with a task created on camera, debug the run that failed, and approve an outbound email yourself. Six minutes.

</Card>

<Card title="Episode 6 — Projects with AI" icon="play" href="https://docs.tale.dev/tutorials/videos/projects-with-ai">

The board mid-flight, files as scoped context, and a task created on camera that an agent visibly takes. Initiative stays human. Two and a half minutes.

</Card>

<Card title="Episode 7 — Connectors & the outside world" icon="play" href="https://docs.tale.dev/tutorials/videos/connectors">

Connectors you can read before opening, the MCP door as the earlier version showed it, and egress that fails closed. Every door opened deliberately. Two and a half minutes.

</Card>

<Card title="Episode 8 — People, roles & teams" icon="play" href="https://docs.tale.dev/tutorials/videos/people-roles-and-teams">

The human half of trust: the role ladder, teams as knowledge walls, and identity hygiene. Access is designed, not assumed. Two minutes.

</Card>

<Card title="Episode 9 — Governance, cost & trust" icon="play" href="https://docs.tale.dev/tutorials/videos/governance-and-trust">

The finale: providers and model policy, guardrails, the audit log, cost and quality charts, residency — and the five habits of using AI well. Three minutes.

</Card>

<Card title="Bonus — Tale for developers" icon="play" href="https://docs.tale.dev/tutorials/videos/tale-for-developers">

The builder's lap: scoped keys, four API doors, webhooks, and harnesses that fail closed. Two minutes.

</Card>

</CardGroup>

## The series ahead

That completes the series: the tour, seven deep dives, and a developer bonus — each in English, German, and French. The documentation around every episode goes further; start wherever your role starts.

# Episode 3 — Knowledge
Source: https://docs.tale.dev/tutorials/videos/knowledge

The grounded answers of episode 2 all came from one place; this episode works in it. You add a real fact as a knowledge entry, learn what the Indexed badge actually means (and why indexing is not training), look a price up in a typed record, read the crawler's scan interval, open the control that limits a document to one team — and then meet the failure you'll actually hit: not a missing fact, an outdated one. At the end, a fresh chat cites the entry you created minutes earlier.

<Video src="https://docs.tale.dev/videos/en/tutorials/ep3-knowledge/ep3-knowledge.en.mp4" poster="https://docs.tale.dev/videos/en/tutorials/ep3-knowledge/ep3-knowledge.en.webp" captions="https://docs.tale.dev/videos/en/tutorials/ep3-knowledge/ep3-knowledge.en.vtt" lang="en" title="Episode 3 — Knowledge" caption="Episode 3 — Knowledge (5:50, captions available)">

</Video>

## What the episode shows

| At   | Scene                                                         |
| ---- | ------------------------------------------------------------- |
| 0:27 | The map: Documents, entries, websites, products — one tab row |
| 0:54 | Entry vs document vs record — picking the right shape         |
| 1:18 | A knowledge entry created live: topic, content, save          |
| 1:44 | What Indexed means — retrieval at answer time, not training   |
| 2:11 | A real lookup in a typed record                               |
| 2:37 | The crawler: a domain, a scan interval, an honest boundary    |
| 3:09 | Who reads what: a document assigned to a team                 |
| 3:41 | The stale-knowledge trap, asked live                          |
| 4:35 | The proof: a fresh chat cites the entry you just created      |

## Where to go next

The [knowledge overview](https://docs.tale.dev/platform/knowledge/overview) maps the whole library; [documents](https://docs.tale.dev/platform/knowledge/documents) covers the indexing pipeline, [knowledge entries](https://docs.tale.dev/platform/knowledge/knowledge-entries) the curated facts, [structured data](https://docs.tale.dev/platform/knowledge/structured-data) the typed records, and [crawling](https://docs.tale.dev/platform/knowledge/crawling) the websites. For how a project agent reads it, read [project agents](https://docs.tale.dev/platform/projects/project-agents).

# Episode 8 — People, roles & teams
Source: https://docs.tale.dev/tutorials/videos/people-roles-and-teams

Episode five gated the machines; this episode gates the people. It walks the workspace roster and the four-step role ladder, opens the add-member dialog just long enough to learn it, draws the team boundaries that decide who reads what, and closes on the boring guardrails that matter most: two-factor and single sign-on.

<Video src="https://docs.tale.dev/videos/en/tutorials/ep8-people/ep8-people.en.mp4" poster="https://docs.tale.dev/videos/en/tutorials/ep8-people/ep8-people.en.webp" captions="https://docs.tale.dev/videos/en/tutorials/ep8-people/ep8-people.en.vtt" lang="en" title="Episode 8 — People, roles & teams" caption="Episode 8 — People, roles & teams (2:15, captions available)">

</Video>

## What the episode shows

| At   | Scene                                                      |
| ---- | ---------------------------------------------------------- |
| 0:13 | The roster: five people, four roles                        |
| 0:26 | Adding someone — and the role ladder that matters          |
| 0:47 | Roles are blast radius, not status                         |
| 1:02 | Teams: the walls of the smallest library                   |
| 1:20 | Identity hygiene: 2FA and enterprise SSO                   |
| 1:35 | One principle, both sides: access is designed, not assumed |

## Where to go next

[Members and roles](https://docs.tale.dev/platform/admin/members-and-roles) is the full reference for the ladder; [teams](https://docs.tale.dev/platform/admin/teams) covers the boundaries you saw. For identity, read [two-factor authentication](https://docs.tale.dev/platform/admin/two-factor-authentication) and [enterprise SSO](https://docs.tale.dev/platform/admin/enterprise-sso).

# Episode 6 — Projects with AI
Source: https://docs.tale.dev/tutorials/videos/projects-with-ai

Chat is where you ask; projects are where the work lives. This episode walks the relaunch project the team actually runs — and then creates a task on camera, the usual way, so you can watch the triage automation score it and an agent take it. The backlog closes the loop: agents propose, people promote.

<Video src="https://docs.tale.dev/videos/en/tutorials/ep6-projects/ep6-projects.en.mp4" poster="https://docs.tale.dev/videos/en/tutorials/ep6-projects/ep6-projects.en.webp" captions="https://docs.tale.dev/videos/en/tutorials/ep6-projects/ep6-projects.en.vtt" lang="en" title="Episode 6 — Projects with AI" caption="Episode 6 — Projects with AI (2:21, captions available)">

</Video>

## What the episode shows

| At   | Scene                                                            |
| ---- | ---------------------------------------------------------------- |
| 0:13 | The relaunch board, mid-flight — avatars say who holds what      |
| 0:26 | Project files: the shelf agents read first                       |
| 0:39 | Discussions live beside the work                                 |
| 0:52 | A task created the usual way                                     |
| 1:08 | The agent takes it: scored, assigned, its reasoning in a comment |
| 1:28 | The backlog: agents propose, a person promotes                   |
| 1:42 | Each project staffs its own crew of agents and models            |

## Where to go next

[Project concepts](https://docs.tale.dev/platform/projects/concepts) and the [overview](https://docs.tale.dev/platform/projects/overview) map the surface; [task automation](https://docs.tale.dev/platform/projects/task-automation) explains the score-assign-report loop you watched, [backlog](https://docs.tale.dev/platform/projects/backlog) the proposal flow, and [project agents](https://docs.tale.dev/platform/projects/project-agents) the per-project crew.

# Bonus — Tale for developers
Source: https://docs.tale.dev/tutorials/videos/tale-for-developers

Everything the series showed has an API underneath. The bonus episode walks the developer surface: named, revocable API keys; REST, MCP, WebDAV, and sandbox runtimes; webhooks that fire agents from any system; the harnesses — Claude Code, Cursor — working in isolated containers. Power tools, contained blast radius.

<Video src="https://docs.tale.dev/videos/en/tutorials/ep10-developers/ep10-developers.en.mp4" poster="https://docs.tale.dev/videos/en/tutorials/ep10-developers/ep10-developers.en.webp" captions="https://docs.tale.dev/videos/en/tutorials/ep10-developers/ep10-developers.en.vtt" lang="en" title="Bonus — Tale for developers" caption="Bonus — Tale for developers (2:08, captions available)">

</Video>

## What the episode shows

| At   | Scene                                             |
| ---- | ------------------------------------------------- |
| 0:14 | API keys: named, scoped, revocable, audited       |
| 0:29 | Four doors: REST, MCP, WebDAV, sandbox runtimes   |
| 0:44 | Webhooks: any system can fire an agent            |
| 0:59 | Harnesses: Claude Code, Cursor, and peers         |
| 1:35 | Power tools, contained blast radius               |

## Where to go next

The [develop overview](https://docs.tale.dev/develop/overview) maps the whole surface; the [API reference](https://docs.tale.dev/develop/api-reference) and [webhooks](https://docs.tale.dev/develop/webhooks) carry the contracts. For harness turns, read [Harnesses](https://docs.tale.dev/platform/agents/harnesses); for the sandbox network boundary, [Hardening](https://docs.tale.dev/self-hosted/operate/security/hardening).

# Episode 1 — Welcome to Tale
Source: https://docs.tale.dev/tutorials/videos/welcome-to-tale

The series opener walks the workspace one area at a time, at a pace you can follow along with. You ask a real question grounded in a company document, watch the answer name its sources, then close the loop: find that exact file in Knowledge, meet the Assistant that answered, and read the journal of an automation that's been running the whole time. Every stop shows a real artifact — nothing is asserted that isn't on screen.

<Video src="https://docs.tale.dev/videos/en/tutorials/ep1-welcome/ep1-welcome.en.mp4" poster="https://docs.tale.dev/videos/en/tutorials/ep1-welcome/ep1-welcome.en.webp" captions="https://docs.tale.dev/videos/en/tutorials/ep1-welcome/ep1-welcome.en.vtt" lang="en" title="Episode 1 — Welcome to Tale" caption="Episode 1 — Welcome to Tale (4:07, captions available)">

</Video>

## What the episode shows

| At   | Scene                                                 |
| ---- | ----------------------------------------------------- |
| 0:18 | Reading the sidebar: every stop on the tour, one rail |
| 0:36 | The hero ask — a document attached as context         |
| 1:12 | Why grounding matters (and what a hallucination is)   |
| 1:32 | Closing the loop: the cited file, found in Knowledge  |
| 1:50 | The Assistant — an agent is AI with a job description |
| 2:12 | Automations: the catalog, and a journal of real runs  |
| 2:55 | Projects: your people and your agents on one board    |
| 3:12 | Control: providers, data residency, and the audit log |

## Where to go next

The [quickstart](https://docs.tale.dev/get-started/quickstart) reproduces the episode's first chat in your own workspace in about five minutes. For the concepts in depth: [chat](https://docs.tale.dev/platform/chat/overview), [knowledge](https://docs.tale.dev/platform/knowledge/overview), [agents](https://docs.tale.dev/platform/agents/concepts), [automations](https://docs.tale.dev/platform/automations/concepts), and [approvals](https://docs.tale.dev/platform/approvals/concepts).

# Episode 4 — Your first agent
Source: https://docs.tale.dev/tutorials/videos/your-first-agent

Chat taught you to ask; knowledge taught you what answers stand on. This episode builds the thing that puts both to work: an agent, created from scratch on camera. The through-line is the trust boundary — every tool you grant widens what the agent can do, so the smallest agent that does the job is the safest one.

<Video src="https://docs.tale.dev/videos/en/tutorials/ep4-agent/ep4-agent.en.mp4" poster="https://docs.tale.dev/videos/en/tutorials/ep4-agent/ep4-agent.en.webp" captions="https://docs.tale.dev/videos/en/tutorials/ep4-agent/ep4-agent.en.vtt" lang="en" title="Episode 4 — Your first agent" caption="Episode 4 — Your first agent (2:46, captions available)">

</Video>

<Note>

The episode was recorded on the earlier agent editor. The agents list, the create dialog, the **Knowledge** and **Tools** tabs, and the "visible in chat" step are not part of this version — the agents you create now live on a project's **Agents** tab and work board tasks, and chat has no agent picker. Watch it for the reasoning; take the steps from [Build your first agent](https://docs.tale.dev/tutorials/editor/first-agent-end-to-end).

</Note>

## What the episode shows

| At   | Scene                                                           |
| ---- | --------------------------------------------------------------- |
| 0:13 | The agents list — builtins, and where yours will live           |
| 0:26 | Create: a technical name, a display name, continue              |
| 0:43 | Instructions — the job description, including the hand-off rule |
| 1:00 | Knowledge scope: the smallest library that does the job         |
| 1:13 | Tools: capability is exposure — start with none                 |
| 1:33 | The model and its fallback                                      |
| 1:44 | Visible in chat, then the first live ask                        |
| 2:06 | Iterate freely: versions keep every draft                       |

## Where to go next

[Agent concepts](https://docs.tale.dev/platform/agents/concepts) is the mental model behind the four decisions, and [Build your first agent](https://docs.tale.dev/tutorials/editor/first-agent-end-to-end) walks them on the screens this version ships — a project agent with a harness, a model, and instructions, put to work on a task. [Project agents](https://docs.tale.dev/platform/projects/project-agents) is the field-by-field reference. The create dialog and the Tools, Knowledge, and History tabs the episode shows are not part of this version; the settings they carried live on the project agent's dialog now.

# Privacy and your data
Source: https://docs.tale.dev/legal/privacy

The [Tale privacy policy](https://tale.dev/legal/privacy-policy) explains how Ruler GmbH handles personal data when you visit its website or contact the company. For personal data processed through Tale Cloud on behalf of your organization, read your service agreement and the [Data Processing Agreement (DPA)](https://tale.dev/legal/data-processing-agreement). This page helps you find the right document and product workflow.

## Find the policy that applies

| Your situation | Start here |
| --- | --- |
| You visited the website, requested a demo, or contacted Tale | The [privacy policy](https://tale.dev/legal/privacy-policy) names the controller, purposes, data categories, and contact route. |
| Your organization uses Tale Cloud | Your organization's privacy information and the DPA explain the respective controller and processor responsibilities. |
| Your organization runs Tale itself | Ask its operator for the deployment's privacy information, providers, retention rules, and request process. |
| You are reviewing a supplier | Read the [subprocessor guide](https://docs.tale.dev/legal/subprocessors) and [trust and compliance](https://docs.tale.dev/cloud/trust-and-compliance). |

## Understand the data involved

Tale stores account information, organization membership, and content created or uploaded in the platform. Depending on the features you use, that content can include conversations, documents, tasks, knowledge entries, automation definitions, and their execution records. Operational records such as audit events serve a different purpose and can have different retention requirements.

A model provider, connector, or other external service may receive data when you use a feature that calls it. Hosting Tale yourself does not make those calls local. Ask your administrator which services are enabled, and use the [data-residency guide](https://docs.tale.dev/cloud/data-residency) to distinguish hosting from processing destinations.

Optional aggregate analytics uses self-hosted Umami on Tale’s own sites and on deployments where the operator enables it. It records known public page paths or private route templates, referrer origins, browser language, screen size, device/browser information and approximate location. The IP address derives location and short-lived visit grouping without raw IP storage. No cookies, persistent browser identifiers, cross-site identity, page titles, query strings, form contents, organization/resource identifiers or session replays are collected. Do Not Track and Global Privacy Control disable this collection. The marketing site counts completed contact/demo submissions without their contents.

## Request access, correction, or erasure

Start with the organization responsible for your account and workspace. Describe the data and the request; use its approved secure channel rather than placing sensitive evidence in a public issue. For requests concerning Tale's own website or your contact with the company, use the contact route in the privacy policy.

You can edit account details and content where you have permission. An administrator can manage an erasure request through [Data subject requests](https://docs.tale.dev/platform/admin/governance/data-subject-requests), subject to the applicable permissions and legal holds. A workspace user does not gain administrative export or erasure rights merely by submitting a request.

Deleting a record in the UI is not proof that every copy in backups or an external service has been erased. The controller and operator must follow the applicable agreement, retention requirements, and provider processes. [Retention configuration](https://docs.tale.dev/self-hosted/configuration/retention) describes the self-hosted controls; it is not a Cloud service retention promise.

## Review the contractual commitments

The DPA covers processing instructions, security measures, subprocessors, data-subject requests, audits, and return or deletion of data. Its AI-processing section sets out the no-training commitment and the requirement for a separate written agreement to vary it; a product toggle is not that agreement. Use the current DPA and your signed agreement for the exact scope and timelines.

# Subprocessors
Source: https://docs.tale.dev/legal/subprocessors

A subprocessor is a third party engaged to process personal data on a customer's behalf. **Appendix A of the [Data Processing Agreement (DPA)](https://tale.dev/legal/data-processing-agreement)** is Tale Cloud's authoritative list: it names the legal entities, service, place of processing, and data categories. Use that appendix and your agreement for a procurement or privacy review.

## Read the list by service

The published appendix distinguishes platform hosting from AI processing. It lists **Akenes SA (Exoscale)** for infrastructure and **OpenRouter, Inc.** for the AI calls routed through that service. A provider's registered address and the contractual processing location are separate facts.

| What you are checking | Where to look |
| --- | --- |
| Hosting region and recovery location | The appendix's EU/EEA and Swiss customer tables, plus your service agreement |
| Data sent for a model call, transcription, or image feature | The service and data-category columns, and the AI-processing section of the DPA |
| Model providers reached through an intermediary | The appendix's notes on upstream providers and the intermediary's terms |
| Training restrictions | Section 5 of the DPA, including the separate written opt-in requirement |
| Changes to the list and objection process | Section 6 of the DPA; follow its notification and subscription conditions |
| Security evidence | The appendix's trust links and [Tale's trust guide](https://docs.tale.dev/cloud/trust-and-compliance) |

## Account for organization integrations

An administrator can configure additional model providers and connectors. Review those destinations and their terms as part of your organization's own data-handling decisions; a list of Tale's contracted Cloud subprocessors is not an inventory of every service your organization may choose to connect.

For example, a chat using an external model sends the input needed for that call to its configured provider. A connector can send a search query or action arguments to another system. Uploaded documents may also be processed by the configured embedding service. The [data-residency guide](https://docs.tale.dev/cloud/data-residency) explains these distinct paths.

## If you run Tale yourself

Your operator selects the hosting, model providers, object storage, and integrations. Tale Cloud's vendor list does not describe that deployment automatically. Use the [self-hosted data-residency reference](https://docs.tale.dev/self-hosted/configuration/data-residency) to inspect configuration and document your own processing destinations.

For a review pack, collect the current DPA, your service agreement, the applicable privacy information, and the security evidence relevant to your deployment. Contact Tale through the route in the DPA if you need clarification or supporting evidence.

# Tarife, Rechnungen und Nutzung
Source: https://docs.tale.dev/de/cloud/billing

Dein Cloud-Vertrag legt die Kosten für Hosting, Support, Plätze und Speicher fest. Hinzu kommt die Modellnutzung: Anbieter und Modell beeinflussen die Kosten jeder KI-Anfrage.

## Die Kosten unterscheiden

Tale bietet die kostenlose Community-Ausgabe für den Eigenbetrieb und Enterprise für die verwaltete Cloud oder betreute eigene Installationen. Beide enthalten dieselben Produktfunktionen. Enterprise ergänzt Dienstleistungen und Support; die Produktkontrollen sind nicht einem gesonderten Tarif vorbehalten.

Die [Preisseite](https://tale.dev/pricing) nennt aktuelle Preise für Plätze und Speicher, Abrechnungszeiträume und enthaltene Leistungen. KI-Nutzung wird dort zu Anbieterpreisen ohne Aufschlag ausgewiesen. Für deine Organisation gelten das vereinbarte Angebot und der Dienstleistungsvertrag.

## Rechnungen finden oder Rechnungsdaten ändern

Wende dich bei Rechnungen, Rechnungsdaten, Änderungen der Platzanzahl oder Fragen zu einer Position an deinen Enterprise-Supportkontakt. Die gemeinsame Produktoberfläche hat keine Seite **Einstellungen > Abrechnung**. Nutzungsansichten dienen dem Betrieb und sind kein Rechnungsportal.

Nenne bei Rückfragen den Abrechnungszeitraum, die Organisation und die Rechnungsnummer. Sende keine Anbieter- oder API-Schlüssel mit.

## Modellnutzung nachvollziehen

Unter [Nutzungsanalyse](https://docs.tale.dev/de/platform/admin/governance/usage-analytics) siehst du die erfasste Nutzung. Grenze den Zeitraum ein und prüfe die Aufschlüsselung nach Modell oder Person, um die Aktivität zuzuordnen.

Ein angezeigter Nutzungswert und eine Rechnung erfüllen unterschiedliche Zwecke. Der Vertrag und die Abrechnungsregeln des Anbieters bestimmen den geschuldeten Betrag. Eine Dashboard-Summe ist weder eine Schlussrechnung noch ein Steuerbeleg.

<Tip>

Teste ein neues Modell vor dem breiten Einsatz mit einer typischen Aufgabe. Prüfe Ergebnisqualität und erfasste Nutzung zusammen. Eine günstigere Anfrage hilft nur, wenn dein Team das Ergebnis verwenden kann.

</Tip>

## Grenzen für den Arbeitsbereich setzen

Konfiguriere die benötigten Kontrollen unter [Richtlinien und Limits](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits). Prüfe den Geltungsbereich jeder Regel und teste sie mit einem betroffenen Konto. Plattformlimits gelten für die jeweils erfasste Aktivität; sie ändern deinen Hosting-Vertrag nicht.

Bei Community im Eigenbetrieb betreibst du die Infrastruktur und bezahlst deine Anbieter direkt. Dieselben Nutzungs- und Richtlinienseiten helfen dir, diese Aktivität nachzuvollziehen.

# Datenresidenz in der Cloud verstehen
Source: https://docs.tale.dev/de/cloud/data-residency

Datenresidenz betrifft den Speicherort und den Ort der Verarbeitung. Mit einer Cloud-Region legst du den Standort des gehosteten Dienstes fest. Daraus folgt nicht automatisch, wo jeder Modellanbieter oder angebundene Dienst deine Daten verarbeitet.

## Das Hosting klären

Kläre vor der Einrichtung die primäre Region, Sicherungsstandorte, Aufbewahrung, Wiederherstellungsziele und den Supportablauf mit Tale. Maßgeblich sind der Dienstleistungsvertrag und die Datenschutzvereinbarungen für deine Installation. Aus einer Regionsbezeichnung im Produkt lässt sich weder ein Sicherungsstandort noch eine Wiederherstellungsgarantie ableiten.

Tale betreibt den Cloud-Dienst. Konfigurationsdateien, Datenbank-Zugangsdaten und Umgebungsvariablen des Hosts liegen beim Betreiber. Die [Referenz für den Eigenbetrieb](https://docs.tale.dev/de/self-hosted/configuration/data-residency) erklärt das technische Modell.

## Den Weg einer Anfrage verfolgen

Eine Chatnachricht erreicht deine Tale-Instanz. Nutzt der Assistent Wissen, lädt er passende Inhalte aus dem Wissensspeicher der Organisation. Die Nachricht und der ausgewählte Kontext gehen anschließend an den Modellanbieter dieser Antwort. Ein Werkzeug kann weitere Dienste aufrufen, etwa eine Website oder eine angebundene Anwendung.

| Datenfluss | Was du klären solltest |
| --- | --- |
| Gespeicherte Chats, Dokumente und Konfiguration | Vereinbarte Hosting- und Sicherungsstandorte |
| Wissensindexierung | Welcher Embedding-Anbieter Dokumentinhalte erhält |
| Modellinferenz | Endpunkt, Verarbeitungsbedingungen und Aufbewahrung des gewählten Anbieters |
| Konnektoren und Webwerkzeuge | Welche externen Systeme Anfragen und Inhalte erhalten |
| Betriebsdaten | Vereinbarter Umgang mit Logs, Sicherungen und Supportzugriff |

Ein Anbieter kann regionale oder lokal betriebene Endpunkte anbieten. Prüfe den tatsächlich konfigurierten Endpunkt. Der Markenname allein belegt keinen Verarbeitungsort.

<Tip>

Prüfe neben dem Chatmodell auch den Embedding-Anbieter. Ein Dokument kann schon während der Indexierung an ihn gesendet werden, bevor jemand eine Frage dazu stellt.

</Tip>

## Eine neue Integration prüfen

Bestimme vor dem Anbinden, welche Daten die geplante Aufgabe sendet und welches Konto der Konnektor nutzt. Prüfe die Verarbeitungsbedingungen, begrenze den Zugriff und teste mit unkritischen Beispieldaten. Halte die Entscheidung in deiner [Sicherheitsprüfung](https://docs.tale.dev/de/cloud/trust-and-compliance) fest.

## Die Region wechseln

Stimme einen Regionswechsel mit Tale ab. Der Migrationsplan muss gespeicherte Daten, Sicherungen, externe Endpunkte, Unterbrechungen und die Abnahme berücksichtigen. Eine zweite Organisation verschiebt die Daten der ersten nicht.

Die [Migrationsplanung](https://docs.tale.dev/de/cloud/migrate-to-self-hosted) enthält Fragen und Prüfschritte, die auch beim Wechsel zwischen Cloud-Regionen gelten.

# Tale Cloud
Source: https://docs.tale.dev/de/cloud

Mit Tale Cloud nutzt du eine verwaltete Tale-Instanz. Dein Team erhält dieselben Produktfunktionen wie in der Open-Source-Ausgabe; Tale betreibt den Dienst gemäß eurem Enterprise-Vertrag.

## Wähle deine nächste Aufgabe

<CardGroup cols="2">

<Card title="Zugang zur Instanz erhalten" href="https://docs.tale.dev/de/cloud/onboarding">

Eine Instanz anfragen oder der vorhandenen Instanz deiner Organisation beitreten.

</Card>

<Card title="Kosten und Rechnungen verstehen" href="https://docs.tale.dev/de/cloud/billing">

Dienstleistungskosten von Modellnutzung trennen und den passenden Kontakt finden.

</Card>

<Card title="Datenflüsse prüfen" href="https://docs.tale.dev/de/cloud/data-residency">

Hosting sowie die Anbieter und Werkzeuge prüfen, die Inhalte verarbeiten.

</Card>

<Card title="Eine Sicherheitsprüfung vorbereiten" href="https://docs.tale.dev/de/cloud/trust-and-compliance">

Zertifizierungsnachweise sammeln und eure Zuständigkeiten prüfen.

</Card>

<Card title="Den Wechsel auf eigene Infrastruktur planen" href="https://docs.tale.dev/de/cloud/migrate-to-self-hosted">

Eine betreute Migration koordinieren und das Zielsystem prüfen.

</Card>

</CardGroup>

Für Chats, Projekte, Agenten und Einstellungen nutze die [Plattformanleitungen](https://docs.tale.dev/de/platform). Die Cloud-Seiten erklären Hosting und Zuständigkeiten; die Produktabläufe sind dieselben.

# Den Wechsel in den Eigenbetrieb planen
Source: https://docs.tale.dev/de/cloud/migrate-to-self-hosted

Beim Wechsel von der Cloud in den Eigenbetrieb übernimmt dein Team die Infrastruktur. Plane den Umzug mit Tale und dem Betreiber des Zielsystems, damit Anwendungsdaten, Wissen, Dateien, Konfiguration und Verschlüsselungsschlüssel zusammenpassen.

Plane mit dem Betreiber die Übertragung der Datenbanken, Dateien, Konfiguration und benötigten Secrets. Einzelne API-Exporte erfassen ausgewählte Ressourcen; sie ersetzen keine konsistente Sicherung der Instanz.

## Festlegen, was erhalten bleiben muss

Liste die Organisationen und Daten, das erlaubte Wartungsfenster, die Zielversion und die Personen für die Abnahme auf. Prüfe die Infrastrukturvoraussetzungen in der [Installationsanleitung](https://docs.tale.dev/de/self-hosted/install/quickstart).

| Bereich | Vor dem Umzug zu klären |
| --- | --- |
| Anwendungsdatenbank | Welche Sicherung ist konsistent und welche Versionen können sie wiederherstellen? |
| Wissensspeicher | Welche organisationsbezogenen Speicher, Indizes und Embedding-Einstellungen müssen mitziehen? |
| Dateien und Konfiguration | Welche Objektspeicherdaten und Konfigurationsverzeichnisse gehören zur Installation? |
| Verschlüsselung | Welche Verschlüsselungs- und Signaturschlüssel müssen sicher erhalten bleiben? |
| Externe Dienste | Welche Rückrufadressen, Webhook-Ziele, Zugangsdaten oder Netzwerkregeln ändern sich? |
| Hintergrundarbeit | Welche Ausführungen müssen vor der letzten Kopie enden oder pausieren? |

Arbeite mit dem Betreiber die [Sicherung und Wiederherstellung](https://docs.tale.dev/de/self-hosted/operate/backups-and-restore) durch. Eine Sammlung von API-Exporten ersetzt diesen Plan nicht.

## Die Wiederherstellung getrennt proben

Stelle vor dem Umzug eine Kopie in einer isolierten Umgebung wieder her. Kontrolliere ausgehende Automatisierungen und geplante Aufgaben, damit die Probe keine doppelten Nachrichten sendet oder unbeabsichtigte Änderungen auslöst.

Prüfe Anmeldung, Rollen, repräsentative Dokumente, Projektdateien, eine Chatantwort und die Konfiguration wichtiger Integrationen. Vergleiche Anzahlen und ausgewählte Datensätze mit der Quelle. Wenn der Dienst startet, ist erst die erste Prüfung bestanden.

## Umschaltung und Rückfall vereinbaren

Halte fest, wer Schreibzugriffe sperrt, die letzte Kopie erstellt, die Weiterleitung umstellt und das Ziel prüft. Definiere Rückfallkriterien und verhindere, dass beide Instanzen gleichzeitig Änderungen annehmen. Bewahre Quelle und geprüfte Sicherungen bis zur Abnahme auf.

Passe öffentliche Adressen, TLS, SSO-Rückrufadressen und Integrationsziele bei Bedarf an. Sitzungen oder externe Zugangsdaten können eine Erneuerung erfordern. Teste sie, statt ihre Übernahme vorauszusetzen.

## Den Betrieb übergeben

Kläre Überwachung, Sicherungspläne, Zuständigkeit für Wiederherstellungen, Upgrades und Supportkontakte. Dokumentiere die Abnahme und teile dem Team die neue Adresse mit. Zum laufenden Betrieb gehören danach [Upgrades](https://docs.tale.dev/de/self-hosted/operate/upgrades), [Beobachtbarkeit](https://docs.tale.dev/de/self-hosted/operate/observability/operations) und geprobte Wiederherstellungen.

# Mit Tale Cloud beginnen
Source: https://docs.tale.dev/de/cloud/onboarding

Der Cloud-Einstieg beginnt mit der Instanz, die deine Organisation nutzen wird. Sobald du Zugang hast, gelten dieselben Chat-, Projekt- und Verwaltungsanleitungen wie im Eigenbetrieb.

## Einer vorhandenen Instanz beitreten

Frage deinen Admin nach Instanzadresse und Anmeldemethode. Öffne diese Adresse und nutze dein eigenes Konto. Verwendet die Organisation SSO, folge diesem Anmeldeweg, statt ein zweites Konto zu erstellen.

Nach der Anmeldung kannst du [deine erste Nachricht senden](https://docs.tale.dev/de/get-started/quickstart). Fehlt die erwartete Organisation oder ein Projekt, lass Mitgliedschaft, Rolle und Projektfreigaben prüfen.

## Einen neuen Cloud-Dienst einrichten

<Steps>

<Step title="Die Instanz vereinbaren">

[Frage eine Demo an](https://tale.dev/request-demo) oder kontaktiere das Tale-Team. Klärt Hosting-Region, Vertragsbedingungen, Identitätsanforderungen und die zuständige Person für den Arbeitsbereich. [Datenresidenz](https://docs.tale.dev/de/cloud/data-residency) und [Sicherheit und Compliance](https://docs.tale.dev/de/cloud/trust-and-compliance) helfen bei diesen Entscheidungen.

</Step>

<Step title="Den Arbeitsbereich einrichten">

Nutze die Instanzadresse und Einrichtungshinweise von Tale. Erscheint der Assistent für die Ersteinrichtung, erstelle das erste Konto und die Organisation. Ist eine Organisation schon vorhanden, öffne sie. Eine weitere Organisation erzeugt einen getrennten Arbeitsbereich.

Wenn der Betreiber das Erstellen von Organisationen verwaltet, bietet die Organisationsauswahl keine Aktion dafür an. Ein direkter Link zur Einrichtung erklärt die Einschränkung. Wende dich an den Betreiber, um einen weiteren Arbeitsbereich anzufordern.

<Frame caption="Der Organisationsname kennzeichnet den Arbeitsbereich deines Teams.">

![Der Assistent zum Erstellen einer Organisation zeigt das Feld für den Organisationsnamen.](https://docs.tale.dev/images/get-started/org-create-wizard.webp)

</Frame>

</Step>

<Step title="Einen Anbieter verbinden und das Team hinzufügen">

Folge [Arbeitsbereich einrichten](https://docs.tale.dev/de/get-started/admins), um Anbieter-Zugangsdaten zu hinterlegen, eine Modellantwort zu prüfen und Konten mit passenden Rollen anzulegen. Der Arbeitsbereich kann bestehen, bevor ein Anbieter bereit ist. Ein funktionierender Chat prüft den Modellzugriff.

</Step>

</Steps>

## Den ersten nützlichen Ablauf prüfen

Wähle eine reale Aufgabe des Teams: ein Dokument besprechen, Projektarbeit organisieren oder einen Projektagenten testen. Prüfe das Ergebnis mit der vorgesehenen Rolle. [Tale im Team nutzen](https://docs.tale.dev/de/get-started/members) und [Projektagent erstellen](https://docs.tale.dev/de/get-started/editors) zeigen die nächsten Schritte.

<Tip>

Teste vor einem großen Import mit wenigen unkritischen Beispieldaten. So kannst du Zugriff und Datenflüsse prüfen, solange die Einrichtung überschaubar ist.

</Tip>

## Hilfe bei Zugang und Einrichtung finden

Bei Konto- und Projektzugriff hilft zuerst dein Admin. Für Verfügbarkeit, Dienstkonfiguration und Vertragsfragen nutze den vereinbarten Tale-Supportkanal. Nenne Instanzadresse, Zeitpunkt, Aktion und angezeigten Fehler. Sende keine Passwörter oder Schlüssel mit.

# Sicherheit und Compliance
Source: https://docs.tale.dev/de/cloud/trust-and-compliance

Ruler GmbH, das Unternehmen hinter Tale, ist nach ISO/IEC 27001 zertifiziert. Die Zertifizierung umfasst das Tale-Enterprise-Angebot und die Dienstleistungen des Unternehmens. Fordere für eine Sicherheitsprüfung das gültige Zertifikat, seinen Geltungsbereich und die Nachweise für den von deiner Organisation bezogenen Dienst bei deinem Tale-Kontakt an.

Die Produktkontrollen unterstützen eure Prozesse. Ob ein Einsatz eure Anforderungen erfüllt, hängt auch von der Konfiguration, den angebundenen Anbietern und den betrieblichen Abläufen ab.

## Eine Prüfung vorbereiten

Stelle den Dienstleistungsvertrag, die Vereinbarung zur Auftragsverarbeitung, die relevanten Zertifizierungsnachweise und eine Beschreibung der Installation zusammen. Die [Datenschutzerklärung](https://docs.tale.dev/de/legal/privacy) und die Angaben zu [Unterauftragsverarbeitern](https://docs.tale.dev/de/legal/subprocessors) ergänzen die Prüfung. Halte Version und Geltungsbereich jedes Dokuments fest.

Kläre, welche Organisation und Installation geprüft werden. Eine Zertifizierungsaussage ersetzt nicht die Prüfung, ob ein konkreter Dienst oder eine Konfiguration vom Bericht abgedeckt ist.

## Zuständigkeiten klären

| Bereich | Tale in der Cloud | Deine Organisation |
| --- | --- | --- |
| Hosting und Wartung | Betreibt den vereinbarten Dienst | Wählt das Angebot und stimmt Änderungen ab |
| Identität und Zugriff | Stellt Konten, Rollen und SSO bereit | Fügt Mitglieder hinzu und prüft deren Rechte |
| Modellanbieter und Konnektoren | Stellt Integrationskontrollen bereit | Wählt Dienste, Zugangsdaten und zulässige Nutzung |
| Nutzungs- und Inhaltsrichtlinien | Stellt Regeln und Aufzeichnungen bereit | Konfiguriert Regeln und bearbeitet Ereignisse |
| Datenanfragen und Aufbewahrung | Stellt die unterstützten Abläufe bereit | Legt Anforderungen fest und genehmigt Aktionen |

Im Eigenbetrieb trägt dein Betreiber zusätzlich die Verantwortung für die Infrastruktur. Welche Unterstützung Enterprise umfasst, regelt euer Vertrag.

## Kontrollen im Produkt prüfen

- [Mitglieder und Rollen](https://docs.tale.dev/de/platform/admin/members-and-roles) regeln den Zugriff. Prüfe inaktive Konten und erhöhte Rechte.
- [Enterprise-SSO](https://docs.tale.dev/de/platform/admin/enterprise-sso) bindet euren Identitätsanbieter an. Teste Anmeldung und Wiederherstellung, bevor du SSO verpflichtend machst.
- [Audit-Logs](https://docs.tale.dev/de/platform/admin/governance/audit-logs) helfen bei der Untersuchung erfasster Aktionen. Die [Integritätsprüfung](https://docs.tale.dev/de/self-hosted/operate/security/audit-log-integrity) erklärt Manipulationsnachweise und deren Grenzen.
- [Schutzregeln](https://docs.tale.dev/de/platform/admin/governance/guardrails), [Legal Hold](https://docs.tale.dev/de/platform/admin/governance/legal-hold) und [Betroffenenanfragen](https://docs.tale.dev/de/platform/admin/governance/data-subject-requests) unterstützen bestimmte Prozesse. Prüfe ihren Geltungsbereich, bevor du dich auf sie stützt.

## Einen Vorfall melden

Nutze bei einem Betriebsproblem den vereinbarten Enterprise-Supportkanal. Melde vermutete Sicherheitslücken über [GitHubs vertraulichen Meldeweg](https://github.com/tale-project/tale/security) oder an `security@tale.dev`. Nenne die betroffene Version und Schritte zur Reproduktion. Veröffentliche keine Zugangsdaten oder personenbezogenen Daten in einem Issue.

Wo Daten verarbeitet werden, beschreibt [Datenresidenz in der Cloud](https://docs.tale.dev/de/cloud/data-residency).

# Konfiguration mit einem Coding-Agenten bearbeiten
Source: https://docs.tale.dev/de/develop/ai-assisted-development

Ein Coding-Agent kann dir helfen, ein mit der CLI verwaltetes Tale-Konfigurationsprojekt zu bearbeiten. Das Projekt enthält Anweisungen, Konfigurationsbeispiele und ausgewählten Quellcode als Referenz. Prüfe den Vorschlag trotzdem selbst und kläre, welche Organisationen er betrifft.

Änderungen am Tale-Anwendungsquellcode folgen einem anderen Ablauf. Beginne dafür mit [Entwicklungsumgebung einrichten](https://docs.tale.dev/de/develop/contributor-setup) und der `AGENTS.md` des Repositorys.

## Eine Arbeitsumgebung anlegen

Installiere die [Tale-CLI](https://docs.tale.dev/de/self-hosted/install/cli-install) und lege das Konfigurationsprojekt in einem neuen Verzeichnis an:

```bash
tale init agent-config-example --no-env
cd agent-config-example
ls -a
```

Dieser Auszug zeigt die erzeugten Pfade:

```text
AGENTS.md
CLAUDE.md
default/
.gitignore
.tale/
tale.json
```

`--no-env` überspringt die Umgebungseinrichtung. Der Aufruf erzeugt weder eine betriebsbereite Installation noch eine `.env`. So kannst du die Konfiguration zunächst ohne Container prüfen. Wenn du später `tale dev` ausführst, richtet die CLI die lokale Umgebung ein. Prüfe vorher die [Voraussetzungen des Schnellstarts](https://docs.tale.dev/de/self-hosted/install/quickstart).

Öffne das Verzeichnis in deinem Editor. Lass den Agenten zuerst `AGENTS.md`, passende vorhandene Konfigurationen und den Quellcode unter `.tale/reference/` lesen.

## Die beiden Anweisungsdateien

`AGENTS.md` enthält die Tale-Konfigurationshinweise. `CLAUDE.md` verweist darauf, damit nur ein gemeinsamer Anweisungstext gepflegt werden muss. Die CLI erkennt auch eine vorhandene `AGENT.md` oder eine `CLAUDE.md` unter `.claude/`.

Die CLI verwaltet den Abschnitt zwischen den Kommentar-Markierungen `tale:begin` und `tale:end`. Ergänze eigene Projektregeln außerhalb dieses Abschnitts; Initialisierung und Updates erhalten diesen umgebenden Text. Zugangsdaten gehören in keine der beiden Dateien.

Die CLI erzeugt keine getrennten Regeln für Cursor, Windsurf oder Copilot. Falls dein Editor die Projektanweisungen nicht automatisch lädt, füge sie ausdrücklich zum Kontext hinzu. Prüfe die tatsächlichen Konfigurationsschemata, statt dich auf das Wissen des Agenten über ältere Releases zu verlassen.

## Die Verzeichnisse unterscheiden

| Pfad | Verwendung |
| --- | --- |
| `default/agents/` | Agentenkatalog mit dem mitgelieferten Beispiel für einen Coding-Agenten. |
| `default/automations/` | Automatisierungen, die installiert oder bereitgestellt werden können. Eine Datei auf dem Datenträger ist noch keine aktive Automatisierung. |
| `default/skills/` | Skill-Bundles für Dokumente und visuelle Analysen; jedes Bundle liegt in einem Verzeichnis. |
| `default/branding/` | Branding-Konfiguration und Bilddateien der Vorlage. |
| `default/governance/` | Beispiele für Richtlinien und Aufbewahrung. Halte dich an die Dateiformate deiner installierten CLI. |
| `default/README.md` | Erläutert die Vorlage und welche Katalogeinträge automatisch installiert werden. |
| `.tale/reference/` | Ausgewählter Quellcode, den die CLI mitliefert. Nutze ihn zum Lesen; die nächste Generierung ersetzt Änderungen. Er ist kein vollständiger Repository-Checkout. |
| `.tale/orgs/<slug>/<domain>/` | Laufzeitkonfiguration tatsächlich in der App angelegter Organisationen. |
| `.tale/checksums.json` | Prüfsummen der erzeugten Dateien, anhand derer Updates lokale Änderungen erkennen. |

`default/` ist die Vorlage für neue Organisationen, keine selbst bereitstellbare Organisation. Eine Änderung daran aktualisiert eine vorhandene Organisation nicht automatisch. Git ignoriert `.tale/` und die Geheimnisdateien; öffentliche Vorlagendateien gehören in die Versionsverwaltung.

## Die Referenz aktuell halten

`tale update` aktualisiert die CLI innerhalb ihrer Release-Reihe und erneuert erzeugte Projektinhalte. Es erstellt die Referenz neu, aktualisiert verwaltete Anweisungsabschnitte, ergänzt neue Katalogdateien und ersetzt unveränderte Dateien anhand ihrer Prüfsummen. Lokal bearbeitete Katalogdateien bleiben erhalten, solange du nicht `--force` verwendest.

Prüfe geplante Änderungen mit `tale update --dry-run`. Halte öffentliche Konfiguration unter Versionsverwaltung und sichere Laufzeitkonfiguration sowie Geheimnisse geschützt. Pflege einen eigenen Fork nicht in `.tale/reference/`. Ein CLI-Update ersetzt keine laufenden Container. Für die bereitgestellte Version gilt die [Upgrade-Anleitung](https://docs.tale.dev/de/self-hosted/operate/upgrades).

## Cursor beim Bearbeiten und bei der Ausführung

Ein Editor-Agent in diesem Verzeichnis ändert lokale Konfigurationsdateien. Ein Tale-[Projektagent](https://docs.tale.dev/de/platform/projects/project-agents) mit Cursor-Harness arbeitet dagegen in einer von Tale verwalteten Sandbox. Beide Kontexte haben eigene Zugangsdaten und unterschiedliche Auswirkungen.

Der Sandbox-Harness nutzt sein konfiguriertes Anbieterkonto und Modell. Die Projektanweisungen im Editor richten dieses Konto nicht ein. Den Laufzeitaufbau erklären die [Harnesses](https://docs.tale.dev/de/platform/agents/harnesses).

## Einen Vorschlag prüfen und anwenden

1. Begrenze den Auftrag auf eine konkrete Änderung. Benenne, ob sie die Vorlage für neue Organisationen oder eine vorhandene Organisation betrifft.
2. Prüfe jeden geänderten Pfad, Schemawert, Slug und Zugangsdatenverweis. Halte Geheimnisse aus Prompt und öffentlichem Diff heraus.
3. Validiere oder teste über die passende Produktoberfläche. Prüfe bei einer Automatisierung die Validierung und ihre Mock-Tests vor dem Deployment.
4. Kontrolliere Deployment-Plan und Zielorganisation. `tale deploy --override` kann Laufzeitkonfiguration durch die lokale Kopie ersetzen; nutze es nur für ein bewusst geprüftes Überschreiben.
5. Lies die gespeicherte Konfiguration zurück und teste das Verhalten nach dem Deployment.

Schlägt der Agent ein Feld vor, das im installierten Schema fehlt, korrigiere den Vorschlag vor der Bereitstellung. Bleibt eine vorhandene Organisation nach einer Änderung an `default/` unverändert, prüfe das Ziel, statt die Vorlage wiederholt bereitzustellen.

# API-Referenz
Source: https://docs.tale.dev/de/develop/api-reference

Die REST-API liest und verändert Tale-Ressourcen mit einem API-Schlüssel: Projekte, Dateien, Aufgaben, Automationen, Läufe und Chat-Threads. Prüfe den Zugriff mit [deiner ersten API-Anfrage](https://docs.tale.dev/de/get-started/developers) und nutze danach die passenden Abschnitte unten.

Deine Instanz stellt das OpenAPI-Schema mit allen Feldern unter `/openapi.json` und eine interaktive Referenz unter `/docs` bereit. Erzeuge Clients aus dem Schema dieser Instanz. Diese Seite erklärt Berechtigungen, Geltungsbereiche, asynchrone Arbeit und Fehler über die einzelnen Operationen hinweg.

## Eine erste Anfrage

Setze `TALE_URL` auf die Adresse der Anwendung, `TALE_API_KEY` auf deinen Schlüssel und `TALE_ORG_SLUG` auf die gewünschte Organisation. Bewahre Geheimnisse in der Umgebung auf. Prüfe zuerst die Identität, bevor du Ressourcen anlegst:

```bash
curl --fail-with-body --compressed "$TALE_URL/api/v1/me" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG"
```

Bei `200` enthält die Antwort `user`, die ausgewählte `organization`, alle aktuellen `organizations`, Deployment-`capabilities` sowie Name und Ablauf des verwendeten `key`. Prüfe Organisation und Rolle vor den nächsten Schritten. Die weiteren Beispiele verwenden Platzhalter für Projekt-, Datei- und Lauf-IDs. Übernimm echte IDs aus vorherigen Antworten, nicht aus Anzeigenamen oder Vermutungen.

### Alle Seiten einer Liste lesen

Listen liefern benannte Sammlungen statt eines nackten Arrays. Das OpenAPI-Schema der `200`-Antwort nennt mit `x-tale-pagination` die passende Form der Seitennavigation.

| Form | Anfrage | Antwort und Abbruchbedingung |
| --- | --- | --- |
| Keyset | `cursor`, `limit` | Einträge, `isDone` und `continueCursor`; bei `isDone: true` stoppen |
| Offset: nur Website-Seiten | `cursor` oder `offset`, nie beide | `pages`, `total`, `offset`, `hasMore`, zusätzlich `isDone` und signierter `continueCursor` |
| Ohne Seitennavigation | Weder `cursor` noch `limit` | Benanntes Array mit vollständiger oder ausdrücklich begrenzter Auswahl |

Sende bei Keyset-Listen `continueCursor` unverändert zurück. Dekodiere oder erhöhe ihn nicht. Auf der letzten Seite ist er leer; sendest du diesen leeren Wert erneut, folgt `400 INVALID_QUERY`, nicht die erste Seite. Die Obergrenze steht je Operation im Schema: meist 100 oder 200, bei Aufgabenkommentaren 500. Größere Query-Limits werden begrenzt.

Kontakte, Produkte, Dokumente, Wissenseinträge, Threads, Nachrichten, Websites und Benachrichtigungsexporte liefern ihre Keyset-Einträge unter `page`. Läufe, Zustellungen, Aufgabenkommentare, Projekte und Projektdateien verwenden den Ressourcennamen, etwa `runs` oder `files`. Lauflisten sind absteigend nach Zeit sortiert, liefern standardmäßig 50 Einträge und akzeptieren 1–200. `GET /api/v1/runs` umfasst sichtbare Läufe über Automatisierungen hinweg.

Automatisierungen, Agenten, Skills, Ordner, Modelle, Browsersitzungen, Versionen und Trigger haben keine Seitennavigation. Eine Website-Seitenanfrage mit `cursor` und `offset` erhält `400 INVALID_QUERY`. Der signierte Cursor für den nächsten Offset funktioniert auch mit der normalen Keyset-Schleife.

Kontakte und Produkte sind nach `updatedAt`, dann `id`, jeweils absteigend sortiert. Wird ein Eintrag während des Durchlaufens geändert, kann er vor deinen Cursor rücken; dieser Durchlauf erfasst die Änderung dann möglicherweise nicht. Vergleiche für einen vollständigen Abgleich das `updatedAt` jedes Eintrags und wiederhole vollständige Durchläufe. Ein Cursor garantiert keinen unveränderlichen Datenstand. Hub-Dokumente, Projekte, Projektdateien und Websites stehen dagegen nach `createdAt` mit den neuesten zuerst.

## Authentifizierung

Erstelle Schlüssel unter **Einstellungen > API > REST** als Inhaber, Admin oder Entwickler oder als Mitglied, dem ein Admin eine Kompetenz zugewiesen hat, die mit einem Schlüssel genutzt wird (`tale:models.api`, `tale:notifications.export` oder `tale:rest.act-as`); alle anderen lehnt Tale mit `403 API_KEY_CREATE_FORBIDDEN` ab; [API-Schlüssel](https://docs.tale.dev/de/platform/admin/api-keys) erklärt die Oberfläche. Ein Schlüssel erscheint einmal und handelt als sein Ersteller. Diese REST-Oberfläche erstellt, listet, rotiert oder widerruft keine Schlüssel.

| Header | Regel |
| --- | --- |
| `Authorization: Bearer <key>` | Einzige erlaubte Stelle; die vollständige Zeichenfolge samt Präfix `tale` unverändert übernehmen |
| `X-Organization-Slug: <slug>` | Aktuelle Mitgliedschaft auswählen; in wiederverwendbaren Integrationen immer mitsenden |
| `x-api-key` | Führt zu `401`, auch neben einem gültigen Bearer-Header; macht aus dem Schlüssel keine App-Sitzung. Am Anthropic-kompatiblen [Modell-Endpunkt](https://docs.tale.dev/de/develop/api-reference#model-endpoints) nennt die Ablehnung den richtigen Weg: den Schlüssel als Auth-Token übergeben, mit `ANTHROPIC_AUTH_TOKEN` für Claude Code oder `authToken` beziehungsweise `auth_token` für die Anthropic-SDKs, und `ANTHROPIC_API_KEY` ungesetzt lassen (Vertrag 3.6.0) |

Bei genau einer Organisation ist der Organisations-Header optional. Mit mehreren Mitgliedschaften braucht jede Anfrage ihn, auch beim Lesen. Die im Dashboard ausgewählte Organisation bestimmt niemals den API-Kontext. Die Groß-/Kleinschreibung des Slugs spielt keine Rolle; leere Werte oder reiner Leerraum gelten als fehlend.

| Organisationsauswahl | Ergebnis |
| --- | --- |
| Mehrere Mitgliedschaften, kein Slug | `400 ORG_SLUG_REQUIRED` |
| Unbekannter Slug oder ein Wert, der kein Slug sein kann | `404 ORG_SLUG_INVALID` |
| Vorhandene Organisation ohne Mitgliedschaft oder mit deaktivierter Mitgliedschaft | `403 ORG_FORBIDDEN` |
| Gültige Mitgliedschaft | Anfrage läuft mit Organisation und Rolle weiter |

Jede dieser drei Ablehnungen nennt in `data.organizations` die Organisationen, die du wählen kannst, jeweils als Paar aus `slug` und `name`. Deaktivierte Mitgliedschaften fehlen darin; bleibt keine übrig, ist die Liste leer. Wiederhole die Anfrage mit einem der genannten Slugs.

`GET /api/v1/me` liefert die Mitgliedschaften auch als `organizations`. `key.expiresAt` enthält Unixzeit in Millisekunden oder `null` bei unbegrenzter Gültigkeit. Rotiere unbeaufsichtigte Zugangsdaten vor dem Ablauf, bevor `401` den Dienst unterbricht. `key.name` benennt den verwendeten Schlüssel.

Prüfe vor einer Operation sowohl die Rolle als auch den Zugriff auf die Ressource. Projektleser dürfen chatten, kommentieren und Aufgaben anlegen; die Aufgaben, die sie selbst angelegt haben oder die ihnen zugewiesen sind, dürfen sie auch ändern und starten. Änderungen an anderen Ressourcen und an Aufgaben anderer benötigen Bearbeitungszugriff.

| Berechtigung aus `/me` | Bedeutung |
| --- | --- |
| `developer` | Inhaber, Admins und Entwickler dürfen beliebige Live-Läufe starten, Läufe abbrechen oder löschen, Trigger binden oder lösen, Automatisierungen löschen sowie Projekt-Automatisierungen installieren oder deinstallieren. Ohne diese Berechtigung liefern diese REST-Operationen `403 ROLE_FORBIDDEN`. MCP prüft sie ebenfalls beim Speichern, Bereitstellen und für weitere privilegierte Tools, nutzt aber sein eigenes Fehlerformat. Validierung und Mock-Tools bleiben für Mitglieder verfügbar. Der Projektzugriff wird gesondert geprüft. |
| `deploymentEditor` | Die Freigabeliste des Betreibers erlaubt Import und Widerruf von Browsersitzungen. Eine administrative Rolle allein reicht dafür nicht. |
| `notificationExport` | Der Schlüssel darf Benachrichtigungen von Mitgliedern über `GET /api/v1/notifications/sync` exportieren. Inhaber und Admins haben diese Berechtigung durch ihre Rolle, alle anderen Mitglieder nur mit einer gültigen Berechtigung `tale:notifications.export`, die ein Admin erteilt hat; siehe [Export ohne Admin-Rolle delegieren](https://docs.tale.dev/de/develop/api-reference#export-ohne-admin-rolle-delegieren). Ohne sie liefert der Export `403 ROLE_FORBIDDEN`. |
| `skillPublish` | Der Schlüssel darf über `PUT /api/v1/skills/{slug}` einen Skill mit der ganzen Organisation teilen. Ohne Richtlinie zur Skill-Freigabe darf das jedes Mitglied; mit ihr nur die zugelassenen Rollen und Mitglieder mit einer gültigen `tale:skills.publish`-Zuweisung — siehe [Skill-Pakete speichern und abgleichen](https://docs.tale.dev/de/develop/api-reference#skill-pakete-speichern-und-abgleichen). Ohne dieses Recht liefert ein solches Speichern `403 SKILL_PUBLISH_FORBIDDEN`. |
| `actAs` | Der Schlüssel darf auf `POST …/runs/{runId}/asks/{askId}` und `POST …/tasks/{taskId}/review` einen `actor` nennen — das verifizierte Mitglied, für das eine weitergereichte Handlung festgehalten wird. Inhaber und Admins haben das Recht durch ihre Rolle; jedes andere Mitglied nur, solange eine `tale:rest.act-as`-Freigabe eines Admins gilt — siehe [Das Mitglied benennen, für das gehandelt wird](https://docs.tale.dev/de/develop/api-reference#das-mitglied-benennen-fuer-das-gehandelt-wird). Ohne dieses Recht antwortet ein gesendeter `actor` mit `403 ROLE_FORBIDDEN`. |
| `modelApi` | Der Schlüssel darf die [kompatiblen Modell-Endpunkte](https://docs.tale.dev/de/develop/api-reference#model-endpoints) aufrufen: Die Organisation hat sie eingeschaltet, und der Schlüsselinhaber darf sie aufrufen. Inhaber, Admins und Entwickler dürfen das durch ihre Rolle, jedes andere Mitglied nur, solange eine `tale:models.api`-Zuweisung eines Admins gilt. Ohne dieses Recht antworten diese Routen mit `403 MODEL_API_DISABLED` oder `403 MODEL_API_FORBIDDEN` (Vertrag 3.6.0). |

## Was für jede Anfrage gilt

### JSON und Query-Parameter validieren

Sende JSON in UTF-8. Ungültiges UTF-8, NUL-Zeichen, ungepaarte UTF-16-Surrogate in Schlüsseln oder Werten sowie Ganzzahlen über 2^53 − 1 führen zu `400 INVALID_BODY`. Übertrage große Kennungen als Strings. Bei verschachtelten Werten nennt `data.issues` den vollständigen Pfad, etwa `messages.0.createdAt`. IDs sind Strings, Zeitstempel Unixzeit in Millisekunden. Ein gesendeter Zeitstempel ist eine ganze Zahl von Millisekunden von `0` bis `8640000000000000` (13.09.275760, der späteste Zeitpunkt, den ein JavaScript-`Date` darstellen kann); jeder andere Wert führt zu `400 INVALID_BODY`. `updatedAt` eines Skills bezeichnet den Schreibzeitpunkt seiner `SKILL.md`.

| Eingabe | Regel |
| --- | --- |
| Unbekannter Body-Schlüssel | `400 INVALID_BODY`, mit Angabe des Schlüssels |
| Doppelter JSON-Schlüssel | Der letzte Wert gilt |
| Unbekannter, doppelter oder leerer Query-Parameter | `400 INVALID_QUERY` |
| Query bei einer Schreiboperation | Abgelehnt; Schreiboperationen akzeptieren keine Query-Parameter |
| Query-`limit` außerhalb des Bereichs | Auf den Bereich der Operation begrenzt |
| Body-Zahl außerhalb des Bereichs | `400 INVALID_BODY`, etwa Such-`limit` oder `maxOutputTokens` |
| `Content-Type` | Der Body wird unabhängig davon als JSON gelesen; diese Oberfläche liefert kein `415` |
| `Accept` | JSON-Operationen liefern auch dann JSON, wenn der Header ein anderes Format verlangt oder JSON ausschließt; es gibt kein `406` |

### Größe und Übertragungsdauer begrenzen

| Body | Maximum |
| --- | --- |
| Normale JSON-Anfrage | 1 MiB |
| Eingebetteter Dokumentinhalt | 32 MiB |
| Anfrage an einen Modell-Endpunkt | 32 MiB |
| Kontakt-Sammelimport | 8 MiB |
| Konversations-Snapshot | 8 MiB |
| Bereitgestellter Konversationsupload | 30 MiB |
| Skill speichern | 4 MiB |
| Zustellung beanspruchen, Fehler melden oder bestätigen | 64 KiB |

Ein zu großer Body erhält `413 BODY_TOO_LARGE`. Überschreitet schon die deklarierte Größe das Limit, liest die Plattform den Body nicht. Andernfalls stoppt sie beim ersten Chunk über der Grenze. Ein übergroßer Body wird nie vollständig gepuffert. Uploadregeln können niedrigere Grenzen setzen als diese Transportlimits.

Header und Body müssen innerhalb von 15 Minuten eintreffen. Für 30 MiB sind dafür ungefähr 35 KB/s nötig. Eine langsamere Anfrage erhält `408 REQUEST_TIMEOUT`, und die Verbindung wird geschlossen. Nutze eine schnellere Verbindung, kleinere unterstützte Anfragen oder den zweistufigen Projektupload, dessen Dateiübertragung außerhalb dieses JSON-Zeitfensters läuft.

### Methoden und Antwortkennungen

Vorhandene Leserouten unterstützen `HEAD` mit der unkomprimierten `GET`-Länge und ohne Body. `HEAD` wird nie komprimiert. `OPTIONS` benötigt keinen Schlüssel und liefert `204` mit `Allow`. Eine nicht unterstützte Methode auf einer vorhandenen Route erhält `405 METHOD_NOT_ALLOWED` mit den erlaubten Methoden. Ein abschließender Schrägstrich wird toleriert.

Die produktive REST-Oberfläche ist für Server-zu-Server-Aufrufe gedacht und aktiviert kein CORS. Halte API-Schlüssel hinter deinem eigenen Backend. Das schlüssellose Status-JSON ist eine getrennte Oberfläche mit CORS.

Jede API-Antwort enthält `X-Request-Id`. Zur Zuordnung in Logs kannst du bis zu 255 Zeichen aus Buchstaben, Ziffern, `_`, `-` und `=` senden. Ein ungültiger Wert wird durch eine neue UUID ersetzt; die Antwort nennt die tatsächlich verwendete Kennung. Bei `429`, `500`, `413` und `414` steht `requestId` zusätzlich in der JSON-Hülle. Zwei Ablehnungen sind die Ausnahme, weil der HTTP-Parser des Edge sie beantwortet, bevor eine Anfrage existiert, die sich loggen ließe: Die nackte `431` für Kopfzeilen über dem 64-KiB-Budget und die nackte `400` für ein Steuerzeichen in einem Kopfzeilenwert tragen keine `X-Request-Id`, keinen Umschlag und keine `X-Tale-Api-Version` — es gibt nichts zu zitieren, und die Anfrage selbst ist das, was du änderst.

`Idempotency-Key` lesen nur die Operationen, die die Kopfzeile deklarieren — ein Lauf-Start, ein Chat-Senden; das OpenAPI-Dokument listet sie, und die Webhook-Türen lesen sie nach ihrer eigenen Regel als Zustellungs-ID. Jede andere Operation ignoriert die Kopfzeile: Ihr Höchstens-einmal-Schutz ist der natürliche Schlüssel, den ihr Body nennt — die `externalId` eines Kontakts, das `(externalSystem, externalId)` einer Aufgabe, die `externalItemId` eines Projekts. Ein `Expect: 100-continue` holt sich vom Edge ein `100 Continue`, sobald er den Body weiterleitet; das Urteil der Plattform — eine `413` für eine deklarierte Länge über der Grenze — kommt trotzdem, bevor ein Body-Byte gelesen ist.

Antworten von `/api/v1` und Webhook-Routen enthalten `X-Tale-Api-Version`; siehe [Versionierung](https://docs.tale.dev/de/develop/api-reference#versionierung). Die schlüssellosen Pfade `/api/health`, `/status`, `/status.json` und `/openapi.json` gehören nicht zu diesem Vertrag und haben keinen Versionsheader.

<Accordion title="Details zu HTTP und Proxy-Verhalten">

Die URL einschließlich Query ist auf 32 KiB begrenzt; größere URLs erhalten vor der Routensuche `414 URI_TOO_LONG`. Am Proxy gilt für Header insgesamt 64 KiB. HTTP/1.1 lässt vor einer nackten `431` einige KiB Spielraum zu. Eine URL mit 66 KiB kann deshalb die Plattform erreichen und `414` erhalten. HTTP/2 setzt die Headergrenze exakt durch und schließt die Verbindung ohne Antwort.

Steuerzeichen unter 0x20 außer Tabulator sowie DEL in Headerwerten werden vor der Plattform abgelehnt: HTTP/1.1 liefert eine reine Textantwort mit `400` ohne `X-Request-Id`; HTTP/2 setzt den Stream zurück oder schließt eine Verbindung mit Body.

Fehlerhafte HTTP/1.1-Chunk-Kodierung, etwa eine nicht hexadezimale Chunk-Größe oder ein fehlendes CRLF, führt am Proxy zu `400 BODY_CHUNK_MALFORMED`. Korrigiere den HTTP-Client oder die Zwischenstelle, die die Anfrage kodiert. Dieselben fehlerhaften Bytes erneut zu senden hilft nicht.

Bei einem bereits laut Länge zu großen Body kann der HTTP/1.1-Proxy vor der Fehlerausgabe bis zu 256 KiB verwerfen, obwohl die Plattform nichts liest. Endet ein Body vor seiner deklarierten Länge, liefert HTTP/2 `400 BODY_LENGTH_MISMATCH`, sofern nicht die Plattform mit ihrer `413` schneller war. HTTP/1.1 wartet bis zum Ablauf der 15 Minuten auf die fehlenden Bytes.

Proxy-Fehler haben eine eigene Anfragekennung und kein `X-Tale-Api-Version`: Der Proxy kennt den Anwendungsvertrag nicht. Beispiele sind eine `404` für Punktsegmente, `BODY_LENGTH_MISMATCH`, `BODY_CHUNK_MALFORMED` und `502`/`503`/`504 UPSTREAM_UNAVAILABLE` beim Neustart. Ein `503 DATABASE_UNAVAILABLE` kommt dagegen von der Plattform selbst, während ihre Datenbank neu startet, und trägt deshalb wie jede andere Antwort der Plattform deren Anfragekennung und `X-Tale-Api-Version`. Verlasse dich nicht darauf, dass jede Zwischenstelle die JSON-Fehlerhülle der API liefert.

</Accordion>

## Caching, Kompression und gezieltes Lesen

### Unveränderte Antworten wiederverwenden

Jede JSON-Leseantwort — ein `GET`, das **200** antwortet — trägt einen `ETag`, der über ihre Bytes berechnet ist, und `Cache-Control: private, no-cache`: Behalte die Antwort und schicke den Tag beim nächsten Lesen als `If-None-Match` zurück. Eine unveränderte Ressource antwortet **304** ohne Body — wer einen fertigen Lauf, einen ruhenden Thread oder den Indexierungsstatus eines Dokuments pollt, zahlt so einen Roundtrip statt der Nutzlast.

Schick den Tag genau so zurück, wie du ihn bekommen hast: Hinter dem komprimierenden Edge lautet der Tag einer komprimierten Antwort `"…-gzip"` oder `"…-zstd"`, und diese Form passt, ebenso die schwache Form `W/"…"`; die 304 trägt den Tag, den die API berechnet hat. Dateiinhalte — `GET /api/v1/projects/{id}/files/{documentId}/content` und das `GET /api/v1/documents/{id}/content` eines Dokuments der Wissensdatenbank gleichermaßen — prüfen `If-None-Match` und `If-Modified-Since` genauso gegen den `ETag` und das `Last-Modified`, die sie ausgeben — ein Spiegel lädt eine Datei nur dann neu, wenn sich ihre Bytes geändert haben.

Das Datum wird sekundengenau beurteilt — genauer ist ein HTTP-Datum nicht —, und reisen beide mit, entscheidet `If-None-Match` allein; bei einem Dokument der Wissensdatenbank mit reinem Inline-Inhalt ist `Last-Modified` das eigene `updatedAt` des Dokuments, das auch ein Patch des Titels oder der Metadaten bewegt — ein Spiegel, der Bytes verfolgt, sendet also den `ETag`. Eine **304** zählt trotzdem als eine Anfrage gegen die [Rate-Limits](https://docs.tale.dev/de/develop/rate-limits).

```bash
# Das erste Lesen antwortet 200 und seinen ETag; die Wiederholung mit diesem Tag antwortet 304
curl -sS --compressed -D - -o /dev/null "https://your-host.example.com/api/v1/projects/<projectId>/runs/<runId>?fields=status,finishedAt" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG" \
  -H 'If-None-Match: "<ETag aus der vorigen Antwort>"'
```

### Kompression anfordern

JSON- und Textantworten werden ab ungefähr 512 Bytes komprimiert, wenn die Anfrage `gzip` oder `zstd` über `Accept-Encoding` anbietet. `curl --compressed` fordert unterstützte Formate an; `br` wird nicht ausgeliefert.

`Content-Length` bezeichnet bei einer komprimierten Antwort die komprimierte Größe, falls der Header vorhanden ist. Große Antworten können ohne ihn streamen. Das ETag trägt entsprechend den Zusatz `-gzip` oder `-zstd`. `HEAD` bleibt unkomprimiert und nennt die unkomprimierte Größe. Fordere Kompression für große JSON-Antworten an, wenn dein Client sie unterstützt; die Einsparung hängt vom Inhalt ab und verringert nicht die Zahl berechneter Anfragen.

### Nur benötigte Felder lesen

Wo eine Ressource groß ist und ein Lesen nur einen Teil davon braucht, sagt es die Operation: Ein Lauf-Lesen nimmt `?fields=status,finishedAt` (beliebige Schlüssel des Laufs, kommagetrennt) und antwortet genau mit diesen Schlüsseln, und eine Laufliste, die über `?include=` volle Zeilen einbettet, liest höchstens 25 Zeilen pro Seite und antwortet mit höchstens 8 MiB davon — sie endet bei der letzten Zeile, die noch passt, mit `isDone: false` und einem `continueCursor` an dieser Zeile; folge dem Cursor also weiter, bis `isDone` gilt.

## Mit Tale bei einer Anwendung anmelden

Tale ist auch ein OpenID-Connect-Aussteller. Eine registrierte Anwendung führt dich durch die native Anmeldung und Einwilligung in Tale. Sie erhält eine signierte Identität mit bestätigter E-Mail-Adresse und der Mitgliedschaft in genau der Organisation, an die ihr Client gebunden ist. Ein API-Schlüssel ersetzt in diesem Ablauf keine persönliche Anmeldung.

Registriere die Anwendung mit einer aktiven Owner- oder Admin-Sitzung, deren ausgewählte Organisation `TALE_ORG_ID` entspricht. `TALE_ORIGIN` ist der Ursprung deiner Tale-Instanz, `TALE_SESSION_COOKIE` der Cookie-Header dieser Sitzung. Verwende die genaue HTTPS-Callback-URL der Anwendung; HTTP ist nur auf Loopback für die lokale Entwicklung erlaubt:

```bash
curl -sS --compressed -X POST "$TALE_ORIGIN/api/app/identity/clients?orgId=$TALE_ORG_ID" \
  -H "Cookie: $TALE_SESSION_COOKIE" \
  -H "Origin: $TALE_ORIGIN" \
  -H "Content-Type: application/json" \
  -d '{"key":"office-app","name":"Office application","redirectUri":"https://office.example.com/api/auth/oauth2/callback/tale"}'
```

Die erste Antwort lautet **201** mit `{ "created": true, "client": { "client_id": "…", "client_secret": "…", … } }`. Speichere das Geheimnis in der geheimen Umgebungskonfiguration der Anwendung. Derselbe Schlüssel mit unveränderter Konfiguration liefert bei Wiederholung **200**, `created: false` und dieselbe Client-ID ohne Geheimnis. Eine geänderte Callback-URL oder Richtlinie führt zu **409**. Ein erneuter Lauf kann eine bestehende Integration so nicht unbemerkt umleiten.

| Zweck               | Endpoint oder Anforderung                                                      |
| ------------------- | ------------------------------------------------------------------------------ |
| Aussteller          | `https://your-host.example.com/api/auth`                                       |
| Discovery           | `GET /api/auth/.well-known/openid-configuration`                               |
| Autorisierung       | `GET /api/auth/oauth2/authorize`                                               |
| Code-Austausch      | `POST /api/auth/oauth2/token`, `client_secret_basic` oder `client_secret_post` |
| Signaturschlüssel   | `GET /api/auth/jwks`                                                           |
| Aktuelle Identität  | `GET /api/auth/oauth2/userinfo`, Bearer-Zugriffstoken                          |
| Angeforderte Scopes | `openid profile email tale:organization`                                       |

Verwende einen gepflegten OIDC-Client mit Authorization Code Flow, S256 PKCE sowie einmaligem State und Nonce. Prüfe Aussteller, Zielgruppe, RS256-Signatur, Ablaufzeit und Nonce des ID-Tokens und verlange `email_verified: true`. Der Claim `https://tale.dev/organization` enthält `{id, slug, role}` für die registrierte Organisation.

Das ID-Token enthält die Standard-Claims der angeforderten Scopes mit denselben Werten, die Userinfo liefert. Um sie zu lesen, brauchst du also keine Userinfo-Anfrage. `email` ergänzt `email` und `email_verified`. `profile` ergänzt `name`, dazu `given_name` (alle Wörter außer dem letzten) und `family_name` (das letzte Wort), wenn der Name aus mindestens zwei Wörtern besteht, sowie `picture`, wenn das Konto ein Bild hat.

Jedes ID-Token trägt denselben Wert `acr: "0"`. Die Discovery führt `"0"` unter `acr_values_supported` und `acr` unter `claims_supported`. Er bescheinigt keinen stärkeren Authentifizierungskontext und keine abgeschlossene MFA-Prüfung; verwende ihn dafür nicht als Zugangskriterium. Die Versionen ab v0.5.45 dokumentierten `urn:mace:incommon:iap:bronze`, während das Token bereits `"0"` trug; eine Relying Party, die auf die URN festgelegt ist, muss `"0"` akzeptieren. `prompt_values_supported` nennt die unterstützten Werte `none`, `login` und `consent`; `select_account` und `create` werden nicht angeboten.

Tale prüft vor der Token-Ausgabe und beim Abruf von Userinfo die aktuelle Mitgliedschaft und die native MFA-Pflicht erneut. Die Anwendung bleibt für ihre eigene Zugangsrichtlinie verantwortlich. Codes, Zugriffs- und ID-Tokens laufen nach fünf Minuten ab, und ein Code lässt sich einmal einlösen. Dynamische Registrierung, Implicit Grants und Refresh Tokens sind deaktiviert.

Zugriffstokens gelten nur für die native Userinfo-Schnittstelle; externe Ressourcenzielgruppen sind deaktiviert. Verwende für REST-Anfragen native API-Schlüssel.

### Fehler des Identitätsanbieters behandeln

Fehler folgen RFC 6749 und RFC 6750 — genau das, was ein gepflegter Client erwartet. `userinfo` antwortet auf ein ungültiges oder abgelaufenes Zugriffstoken mit **401** `invalid_token` und einer `WWW-Authenticate: Bearer`-Challenge — jeder Ablauf nach fünf Minuten nimmt diesen Weg, behandle ihn also als erneute Anmeldung, nicht als Wiederholung — und ohne Token mit **401** und der bloßen Challenge; ein Token ohne den Scope `openid` ergibt **403** `insufficient_scope`.

Token- und Autorisierungs-Endpoint antworten mit `{ "error", "error_description" }`: Ein anderer Grant als `authorization_code` ist `unsupported_grant_type`, eine fehlerhafte Anfrage — ein fehlendes `grant_type` eingeschlossen — `invalid_request`, wobei die Beschreibung den Parameter nennt (`grant_type is required`, `client_id is required`, `response_type must be one of "code"`). Ein Body des falschen Medientyps an einem reinen JSON-Endpoint (ein Formular, das an `register` gepostet wird) ergibt **400** `invalid_request` mit dem Typ, den er nimmt — ein 415 gibt es auf dieser Oberfläche nicht.

Eine Autorisierungsanfrage, deren `client_id` keinen registrierten Client benennt, wird auf die eigene Fehlerseite des Ausstellers umgeleitet — nie auf die `redirect_uri`, die sie geschickt hat — mit `error=invalid_client` und einer Beschreibung, die den Client als unbekannt benennt, damit eine vertippte ID nicht für eine fehlende gehalten wird. Discovery führt `https://tale.dev/organization` unter `claims_supported`; sie nennt außerdem die Introspection-, Revocation- und End-Session-Endpoints des Providers, die der Ablauf oben nicht braucht.

### Anwendungs-Client rotieren oder deaktivieren

Für einen geprüften Client-Schlüssel liefert `POST /api/app/identity/clients/office-app/rotate-secret?orgId=<orgId>` mit `{}` einmalig ein neues `client_secret` und macht das alte ungültig. `POST /api/app/identity/clients/office-app/status?orgId=<orgId>` mit `{ "disabled": true }` sperrt neue Autorisierungen; `false` aktiviert denselben Client wieder. Beide Aufrufe benötigen wie die Registrierung dieselbe aktuelle Organisation, eine Admin-Sitzung, den Origin-Header und JSON als Inhaltstyp. Beim Löschen einer Organisation werden ihre Clients und Einwilligungen entfernt.

## Endpoint-Gruppen

Bei Projektressourcen unter `/api/v1` steht die Projekt-ID in der URL. Ein `projectId` im Anfrageinhalt ergibt hier **400**, weil die Schemas unbekannte Felder ablehnen. Die Ressource muss zum benannten Projekt gehören und für den Schlüsselbesitzer sichtbar sein; andernfalls antwortet Tale mit **404**. Antworten dürfen `projectId` als Metadatum enthalten. Organisationskataloge wie Automatisierungsdefinitionen und Skill-Bundles behalten ihre Organisationspfade.

Jede **201**, die eine adressierbare Ressource anlegt, trägt `Location` — den eigenen Pfad der Ressource, relativ zur Anfrage-URL —, damit ein generischer Client ihr folgt, welche Form der Body auch hat (`{id}` bei einem Kontakt, `{project}` bei einem Projekt, `{task}` bei einer Aufgabe); der Massenimport von Kontakten legt viele an und trägt keine.

| Ressource | Pfad und Umfang |
| --- | --- |
| Automatisierungen | `/api/v1/automations/...`<br>Definitionen, Versionen, Trigger und die Projekte, in denen jede installiert ist; eine Definition löschen; Läufe ohne Projekt starten und auflisten. |
| Projekt-Automatisierungen | `/api/v1/projects/{id}/automations/...`<br>Installierte Automatisierungen auflisten, eine installieren oder wieder entfernen und Läufe dieses Projekts starten oder lesen. |
| Läufe | `/api/v1/runs`, `/api/v1/projects/{id}/runs` und ein einzelner Lauf unter `/api/v1/projects/{id}/runs/{runId}` oder `/api/v1/runs/{runId}`<br>Läufe über Automatisierungen hinweg auflisten; einen vollständig lesen — Status, Ausgabe, Trace, Effekte; einen laufenden mit `POST .../cancel` abbrechen und einen beendeten mit `DELETE` entfernen; die Frage eines wartenden Laufs unter `GET .../ask` lesen und unter `POST .../asks/{askId}` beantworten; Projektläufe verwenden den Projektpfad. |
| Threads | `/api/v1/projects/{id}/threads/...` oder `/api/v1/threads/...`<br>Eigene Chats innerhalb eines Projekts oder ohne Projekt: auflisten, anlegen, lesen, archivieren oder wiederherstellen, löschen, Nachrichten senden, den Turn abfragen und abbrechen. |
| Modelle | `GET /api/v1/models`<br>Konfigurierte Chat-Modelle, die dem Schlüsselbesitzer in dieser Organisation zur Verfügung stehen — dazu `harnesses`, die Coding-Harnesses, auf denen ein Projektagent laufen darf — mit `contextWindow`, `maxOutputTokens` (fehlt, wenn der Katalog keine Obergrenze nennt — dann prüft ein Senden auch keine), Fähigkeiten, optionalen `pricing`-Angaben bei veröffentlichten Katalogpreisen und `default: true` an der Wahl der Organisation, wenn eine konfiguriert und zugänglich ist. |
| Teams | `GET /api/v1/teams`<br>Jedes Team der Organisation — `id`, `name` und ob der Schlüsselbesitzer `member` ist — als vollständige Menge: die IDs, die ein Team-Publikum nimmt (`teamIds` bei einem Projekt oder Hub-Dokument, `teams` bei einem Skill). Teams werden in der App (Einstellungen > Teams) oder von einem Identitätsanbieter angelegt und besetzt; nichts auf dieser Oberfläche schreibt eines. |
| Agenten | `/api/v1/projects/{id}/agents/...`<br>Agenten im angegebenen Projekt auflisten, lesen, anlegen, ändern (bedingt, mit `expectedUpdatedAt`) und löschen. Ein `PUT`, das genau die gespeicherte Konfiguration nennt, schreibt nichts und lässt `updatedAt` in Ruhe. |
| Skills | `/api/v1/skills/...`<br>Skill-Bundles der Organisation auflisten, lesen, anlegen oder ändern und löschen; jede Datei eines Bundles lesen — ein validierter Lesezugriff (`ETag` und `Last-Modified` über die Bytes; `If-None-Match` / `If-Modified-Since` antworten **304**), ein Spiegel lädt also nur neu, was sich geändert hat. Jeder Skill nennt seine Version (`etag`, `updatedAt`), und ein Speichern lässt sich mit `If-Match` absichern; eine Versionshistorie hat ein Skill an dieser Oberfläche nicht — das Lesen antwortet nur mit dem aktuellen Bundle. |
| Wissenseinträge | `/api/v1/knowledge-entries/...`<br>Themen-Fakten: auflisten (`?topic=`, `?status=`), anlegen, ablösen, löschen, dazu der Versionsverlauf eines Themas unter `GET .../{id}/versions`. |
| Wissenssuche | `POST /api/v1/projects/{id}/knowledge/search` oder `POST /api/v1/knowledge/search`<br>Indexierte Dateien eines Projekts oder sichtbare Dokumente der Wissensdatenbank ohne Projektzuordnung und Websites durchsuchen. |
| Dokumente | `/api/v1/documents/...`<br>Dokumente der Wissensdatenbank: CRUD (ein `PATCH` antwortet mit dem aktualisierten Dokument), `GET .../content` für die Bytes, plus `POST .../retry-indexing`; jedes dateigestützte Dokument trägt seinen `indexing`-Zustand. Projektdateien tauchen hier nie auf — sie leben unter Projekte. |
| Websites | `/api/v1/websites/...`<br>Gecrawlte Quellen: CRUD (ein `PATCH` antwortet mit der aktualisierten Website) plus `.../pages` — jede Seite mit ihrem `status` (`discovered`, bis ein Abruf sie speichert, danach `active`), `failCount` und, wenn ihr letzter Versuch fehlschlug, `lastError`, `lastErrorKind` und `lastErrorAt`, sodass eine Seite, die die Abrufsperre abgelehnt hat (eine Weiterleitung auf eine private Adresse), von einer zu unterscheiden ist, die noch niemand abgerufen hat; `?state=failed` oder `?state=skipped` beschränkt das Fenster auf die Seiten in diesem Zustand (`total`, `hasMore` und der Cursor zählen dann nur ihn, und ein unter einem Zustand ausgestellter Cursor wird unter einem anderen abgewiesen), und jedes Fenster trägt `counts`, die Zahl der fehlgeschlagenen und der übersprungenen Seiten —, `.../sync` und `.../search`. Die Suche antwortet `{results, total}` — jedes Ergebnis mit `url`, `title`, `content`, `chunkIndex` und `score` —, eine eigene Form, nicht das `{hits, diagnostics}` der Endpunkte zur Wissenssuche; ihr `limit` (1–100, Standard 10) ist ein Body-Feld und wird außerhalb des Bereichs mit **400**, `INVALID_BODY`, abgewiesen — nie begrenzt. An der Website zählt `crawledPageCount` die Seiten, die der Crawler versucht hat, gespeichert oder nicht, und `failedPageCount` die, deren letzter Versuch fehlschlug; die drei Zähler stempelt der Abgleich Korpus → Zeile, der nach dem Entdecken, nach jedem gespeicherten Batch, am Ende jedes Abschnitts und am Ende des Scans läuft (`metadata.lastStatusSyncAt` sagt, wann) und den `POST .../sync` erzwingt, und `lastScannedAt` ist das Ende des letzten Scans. Das Entdecken hält sich auf jedem Weg, über den eine URL hereinkommen kann, an die `Disallow`-Regeln der `robots.txt` — gelistete URLs ausgenommen —, und eine Seite, die eine Regel abdeckt, verlässt den Index beim nächsten Scan; `POST /api/v1/websites` weist eine `http://`-Domain ab (`WEBSITE_DOMAIN_INVALID` — der Crawler wählt nur https) und lässt einen Punkt am Ende fallen, `example.com.` ist also `example.com`; das `lastError` einer Seite ist eine Zeile, die die Ursache nennt, nie das Aufrufprotokoll eines Frameworks. |
| Browser-Sessions | `/api/v1/browser-sessions/...`<br>Browser-Cookies für die [Video-Ingestion](https://docs.tale.dev/de/self-hosted/configuration/video-ingestion). Organisationsmitglieder dürfen die maskierte Liste lesen. `POST .../import` und `DELETE .../{id}` verlangen einen freigegebenen Deployment-Editor; `/me` nennt dies unter `capabilities.deploymentEditor`. Sitzungen gelten standardmäßig 14 Tage und höchstens 180 Tage. |
| Produkte | `/api/v1/products/...`<br>Produktkatalog-Einträge: CRUD (ein `PATCH` antwortet mit dem aktualisierten Produkt). |
| Kontakte | `/api/v1/contacts/...`<br>Kontaktdaten: CRUD (ein `PATCH` antwortet mit dem aktualisierten Kontakt) plus `POST /api/v1/contacts/bulk`. |
| Gespräche | `/api/v1/conversations/...`<br>Externe Gespräche als versionierte Snapshots in den Posteingang spiegeln, die Snapshot-Quittung einer Quelle lesen, in die Zustellwarteschlange einer Quelle schauen, native Antworten abholen, ihre Zustellung bestätigen oder als fehlgeschlagen melden, eine unzustellbar abgelegte neu anstoßen und ein gespiegeltes Gespräch einem Team zuweisen; genaue Schemas stehen unter `/docs` der laufenden Instanz. |
| Benachrichtigungen | `GET /api/v1/notifications/sync`<br>Persönliche oder sichtbare Organisationsmeldungen eines bestätigten Mitglieds exportieren; für Inhaber/Admins oder Mitglieder, denen ein Admin `tale:notifications.export` erteilt hat. Signierte Pagination, übersetzte Texte, stabile IDs und Hashes für Inhalt und Lesestatus. |
| Projekte | `/api/v1/projects/...`<br>Der Maschinenzugang für externe Worker: Projekte auflisten oder eines per externer ID nachschlagen, anlegen, archivieren und wiederherstellen, löschen; Ordner vorbereiten, Dateien hochladen, herunterladen und löschen, eine Datei sofort indexieren, Ordner löschen. |
| Aufgaben | `/api/v1/projects/{id}/tasks/...`<br>Aufgaben aus externen Referenzen idempotent anlegen, Status lesen, Workflows starten (die Antwort nennt die `runId` zum Pollen), kommentieren und die Prüfung einer Aufgabe unter `GET .../review` lesen bzw. unter `POST .../review` für ein Mitglied entscheiden, jeweils im benannten Projekt. |
| MCP | `POST /api/v1/mcp`<br>Der [MCP-Endpoint](https://docs.tale.dev/de/develop/mcp-endpoint) — derselbe Schlüssel, JSON-RPC statt REST. |
| Modell-Endpunkte | `/api/v1/openai/...` und `/api/v1/anthropic/...`<br>OpenAI- und Anthropic-kompatible Aufrufe der Modelle der Organisation, ausgeschaltet, bis ein Admin sie einschaltet; siehe [Kompatible Modell-Endpunkte](https://docs.tale.dev/de/develop/api-reference#model-endpoints). |
| Webhook-Trigger | `POST /api/projects/{id}/automations/webhook/{token}` oder `POST /api/automations/webhook/{token}`<br>Eine bereitgestellte Automatisierung per Token starten; [Webhooks](https://docs.tale.dev/de/develop/webhooks) erklärt URLs mit und ohne Projekt. |

Automatisierungsdefinitionen bearbeitest du über den [MCP-Endpoint](https://docs.tale.dev/de/develop/mcp-endpoint) oder den Editor der App: Dort kannst du sie speichern, validieren, testen und bereitstellen. Diese REST-Oberfläche bietet dafür keine Routen. `tale deploy` veröffentlicht Deployment-Konfigurationen; der Befehl ist kein REST-Endpoint zum Bearbeiten von Definitionen.

### Gleichzeitige Änderungen schützen

Sende bei einem Kontakt-, Produkt- oder Dokument-`PATCH` das zuletzt gelesene `updatedAt` als `expectedUpdatedAt`, wenn deine Änderung auf diesem Stand aufbaut. Ein veralteter Wert ergibt `409 CONTACT_STALE`, `PRODUCT_STALE` oder `DOCUMENT_STALE`. Lade die Ressource erneut, führe deine Änderung mit der zwischenzeitlichen Bearbeitung zusammen und sende die neue Vorbedingung.

Hub-Dokumente unterstützen zusätzlich `If-Match`: Sende den starken `ETag` aus dem `GET` des Dokuments. Der Vergleich erfolgt innerhalb derselben Transaktion wie die Änderung. Passt der Tag nicht mehr, folgt `412 PRECONDITION_FAILED` mit dem aktuellen Tag in `data.etag`; nichts wird geschrieben. Eine Liste von Tags oder `*` ist erlaubt. Ein schwacher `W/`-Tag passt nie. Der Tag umfasst die gesamte Antwort einschließlich `indexing`; der Indexierungsfortschritt kann ihn daher ändern, ohne das `updatedAt` der Dokumentzeile zu verändern.

Ein erfolgreicher Kontakt-, Produkt-, Dokument- oder Website-`PATCH` liefert `200` mit der aktualisierten Ressource; ein Dokument-`PATCH` trägt außerdem den `ETag` der neuen Darstellung, den Wert, den das nächste `If-Match` sendet. Bleiben bei einem Kontakt, Produkt, Dokument oder Projekt alle gespeicherten Werte gleich, schreibt Tale nichts und bewahrt `updatedAt`. Vorbedingungen werden zuerst geprüft: Auch ein unveränderter Body umgeht kein veraltetes `expectedUpdatedAt` oder `If-Match`.

### Kontakte, Produkte und Website-Identität bearbeiten

Für Kontakte und Produkte gelten dieselben Grundregeln beim Bearbeiten. Tale entfernt äußere Leerzeichen aus Strings und speichert Kontakt-E-Mails in Kleinbuchstaben. Der Teil vor `@` darf höchstens 64 Zeichen haben. Diese Duplikate werden beim Anlegen und bei `PATCH` mit **409** abgewiesen:

| Ressource | Bereits vorhandener Wert | Code |
| --- | --- | --- |
| Kontakt | `email`, unabhängig von Groß- und Kleinschreibung | `CONTACT_DUPLICATE_EMAIL` |
| Kontakt | `externalId` | `CONTACT_DUPLICATE_EXTERNAL_ID` |
| Produkt | `name`, unabhängig von Groß- und Kleinschreibung | `DUPLICATE_PRODUCT_NAME` |
| Produkt | `externalId` | `DUPLICATE_PRODUCT_EXTERNAL_ID` |

`null` leert ein optionales Feld. Bei `PATCH` wird auch ein leerer String als `null` behandelt. Ein leeres Pflichtfeld, etwa der Produktname, ergibt **400** `INVALID_BODY`. Beim Anlegen und Massenimport gelten leere Strings — und `null` — dagegen als ausgelassene Felder, eine CSV-Zeile oder ein JSON-Export importiert also sauber (das OpenAPI-Dokument deklariert die optionalen Felder des Anlegens deshalb als nullable). Der Massenimport verlangt mindestens einen Kontakt; `contacts: []` ergibt **400** `INVALID_BODY`.

Ein Kontakt benötigt mindestens eines der Felder `name`, `email` oder `externalId`. Ein `PATCH`, der das letzte dieser Identitätsfelder entfernt, ergibt **400** `CONTACT_IDENTITY_REQUIRED`.

Werte einen Kontakt-Sammelimport zeilenweise aus. `POST /api/v1/contacts/bulk` erwartet ausschließlich `contacts`, ein Array mit 1–500 Zeilen. Die Zeilen werden einzeln geprüft; auch bei einzelnen Fehlern lautet die Antwort `201`:

| Antwortfeld | Verwendung |
| --- | --- |
| `success`, `failed` | Anzahl angenommener und abgewiesener Zeilen |
| `created[]` | `id` jedes angelegten Kontakts und sein ursprünglicher, bei null beginnender `index` |
| `errors[]` | Ursprünglicher `index` und `contact`, lesbarer `error`, stabiler `errorCode` sowie feldbezogene `issues` bei Schemafehlern |

Eine ungültige E-Mail, ein unbekannter Zeilenschlüssel oder eine fehlende Identität ergibt einen Zeilenfehler mit `INVALID_BODY`. Duplikate haben eigene Codes. Korrigiere nur die fehlgeschlagenen Zeilen und sende diese erneut. Eine ungültige äußere Struktur, überschrittene Transportgrenzen oder fehlerhafte JSON-Kodierung weisen weiterhin die gesamte Anfrage vor der Zeilenverarbeitung ab.

Der Filter `source` der Kontaktliste akzeptiert dieselbe feste Auswahl wie Schreiboperationen, darunter `manual_import`, `api_import`, `shopify`, `hubspot`, `webhook` und `custom`. Die vollständige Auswahl steht im OpenAPI-Schema der Instanz. Ein anderer Wert führt zu `400 INVALID_QUERY`.

Für `metadata` verwenden Kontakte, Produkte und Dokumente JSON Merge Patch nach RFC 7396: Gesendete Schlüssel werden gesetzt, ausgelassene bleiben erhalten und Schlüssel mit dem Wert `null` werden entfernt. `metadata: null` leert das gesamte Feld. `address` wird dagegen vollständig ersetzt.

Für `address` und `metadata` gelten jeweils höchstens 64 KiB JSON, 8 Verschachtelungsebenen und insgesamt 500 Schlüssel. Größere oder tiefere Werte ergeben **400** `INVALID_BODY` mit dem betroffenen Pfad.

`price` und `stock` eines Produkts sind Zahlen im sicheren Ganzzahlbereich, negative Werte eingeschlossen (eine über die API gebuchte Korrektur); das Produktformular und der Dateiimport der App lehnen negative Werte und einen nicht ganzzahligen Bestand ab. Die `currency` eines Produkts ist ein ISO-4217-Code wie `USD` oder `EUR`; Tale akzeptiert jede Groß-/Kleinschreibung und speichert Großbuchstaben. `imageUrl` muss eine absolute HTTP- oder HTTPS-URL mit öffentlichem Host sein. Relative Pfade, andere Protokolle, private oder Loopback-IP-Adressen, Hostnamen ohne Domain und Cloud-Metadatenhosts ergeben `400 INVALID_BODY`. Die Prüfung liest nur die URL, löst kein DNS auf und ruft das Bild nicht ab. Die Betreibereinstellung `TALE_ALLOW_PRIVATE_CRAWL_HOSTS=1` erlaubt private Netzwerkziele, jedoch niemals Metadatenhosts.

Für ein über das Produktformular hochgeladenes Bild gilt ein eigener Ablauf. Die App nimmt PNG-, JPEG-, WebP-, GIF- und SVG-Dateien bis 5 MiB an, prüft ihren Inhalt und liefert eine dauerhaft nutzbare, geschützte URL. REST-Leseantworten geben diese Adresse als absolute URL zurück. Du kannst sie in `imageUrl` erneut übermitteln, auch bei einer privaten Bereitstellung: Das Bild muss zur selben Organisation gehören und entweder von dir hochgeladen worden sein oder bereits von einem vorhandenen Produkt verwendet werden. Ein fehlendes oder nicht zugängliches Bild ergibt `404 FILE_NOT_FOUND`, eine veränderte verwaltete URL `400 INVALID_BODY`. Zum Abrufen der Bilddaten brauchst du eine berechtigte App-Sitzung. Die URL ist kein öffentlicher Freigabelink; ein REST-API-Schlüssel gewährt keinen Zugriff auf diese App-Route. Mit `imageUrl: null` in PATCH entfernst du das Bild vom Produkt. Die Bilddatei lädst du über das App-Formular hoch; einen REST-Endpunkt für Produktbilduploads gibt es nicht.

Die `domain` einer Website ist unveränderlich: `PATCH /api/v1/websites/{id}` akzeptiert den gespeicherten Wert als Echo (ein Client darf die Ressource senden, die er gelesen hat) und antwortet auf jeden anderen mit **400**, `WEBSITE_DOMAIN_IMMUTABLE`.

`POST /api/v1/websites` speichert den Host so, wie er kommt — `www.` bleibt erhalten —, und die Schreibweisen mit `www.` und ohne (Apex) zählen als eine Site: Eine Domain, die unter einer der beiden schon registriert ist, ergibt **409**, `WEBSITE_DUPLICATE_DOMAIN`, mit `data.websiteId` und `data.domain` für die bestehende Zeile.

Eine Ausnahme gilt für URL-Listen: Ist die Domain bereits als Liste registriert und stimmt ihre Schreibweise exakt überein, erweitert ein erneuter Aufruf diese Liste und liefert **200** mit derselben ID. Eine URL-Liste kann keinen bestehenden vollständigen Website-Crawl ersetzen; das ergibt **409** und reiht nichts ein. Prüfe vor dem Aufruf `kind` und verwende die Domain-Schreibweise aus der bestehenden Ressource oder der Konfliktantwort.

Der `status` einer Website beschreibt den Scan. `GET /api/v1/websites?status=` akzeptiert `scanning` (hier beginnt eine registrierte Website), `active`, `error` oder `deleting`; andere Werte ergeben `400 INVALID_QUERY`, ebenso `?scanInterval=` außerhalb seiner sieben Werte. `active` bedeutet, dass nach dem abgeschlossenen Scan mindestens eine Seite gespeichert ist. Es bedeutet nicht, dass alle Seiten aktualisiert wurden. Bei einem fehlgeschlagenen Scan oder wenn nach den Abrufversuchen keine gespeicherten Seiten verbleiben, lautet der Status `error`; lies dazu `metadata.lastSyncError`. Ein Fehler des Embedding-Modells beginnt mit `The embedding model could not embed the pages [<class>]:`, wobei die Klasse `credential`, `credit`, `unresolved`, `dimension`, `throttled` oder `upstream` ist, gefolgt vom Satz des Anbieters.

Das `lastErrorKind` einer Seite unterscheidet Netzwerk- und TLS-Probleme (`network_error`, `tls_error`), abgewiesene Ziele (`private_ip`), HTTP-Fehler (`http_error`), Extraktions- oder Darstellungsfehler, nicht in Text umwandelbare Inhalte (`unsupported_content`) und eine `robots_noindex`-Ablehnung — der Ursprung hat mit `X-Robots-Tag: noindex` geantwortet oder die Seite trägt ein `<meta name="robots" content="noindex">`-Tag. Nach einer fehlgeschlagenen Aktualisierung kann älterer indexierter Inhalt erhalten bleiben. Prüfe deshalb neben dem Website-Status auch die Seitenfehler.

`POST /api/v1/websites/{id}/search` sucht mit Stichwörtern in den gespeicherten Textabschnitten dieser Website. Der BM25-`score` hat keine feste Obergrenze und lässt sich nur innerhalb einer Antwort vergleichen. Ohne ParadeDB verwendet die Instanz eine Teilstringsuche und liefert bei jedem Treffer `0`. Für semantische Ähnlichkeit und `minSimilarity` verwende `POST /api/v1/knowledge/search` mit `corpus: "web"`. Das durchsucht den sichtbaren Webbestand, nicht nur eine ausgewählte Website.

### Skill-Pakete speichern und abgleichen

`PUT /api/v1/skills/{slug}` legt ein neues Bundle an (**201**) oder aktualisiert das vorhandene (**200**). Für einen Abgleich brauchst du deshalb keinen vorgelagerten Existenztest. `description` und `body` sind Pflicht. Für optionale Felder gilt:

- Ausgelassene `icon`, `labels`, `teams`, `visibility` und `disableModelInvocation` behalten ihre gespeicherten Werte.
- `null` leert `icon` oder `labels`.
- `disableModelInvocation: false` entfernt dieses Flag.

`body` enthält Markdown mit höchstens 507.893 UTF-8-Bytes. Die Grenze lässt Platz für Frontmatter innerhalb der maximal 512 KiB großen `SKILL.md`. Fehlt ein abschließender Zeilenumbruch, hängt Tale einen an; ein späterer Abruf kann deshalb ein Byte mehr enthalten.

Beim Speichern wird nur `SKILL.md` neu geschrieben. Andere Bundle-Dateien und zusätzliche Frontmatter-Schlüssel wie `license`, `recommended-packages` oder Community-Erweiterungen bleiben erhalten. Zum Ersetzen eines vollständigen Bundles verwendest du den ZIP-Upload der App.

Jeder Skill enthält `etag`, den in Anführungszeichen gesetzten SHA-256-Hash seiner `SKILL.md`, und `updatedAt`, den letzten Schreibzeitpunkt dieser Datei. Änderungen anderer Bundle-Dateien verändern diese Versionsangaben nicht.

Ist die zusammengesetzte `SKILL.md` bytegleich mit der gespeicherten Datei, bleibt sie unverändert. Tale liefert **200** mit dem bisherigen `etag` und `updatedAt` und legt keinen Verlaufseintrag an. Vorbedingungen werden trotzdem geprüft: Ein veraltetes `If-Match` ergibt auch bei identischem Inhalt **412**.

`GET /api/v1/skills/{slug}` trägt den Tag als `ETag` und antwortet **304** auf ein `If-None-Match`, das ihn nennt — die schwache Form `W/"…"` und die `"…-gzip"`-Form des Edge eingeschlossen —, mit demselben `Cache-Control: private, no-cache` wie seine **200**. `GET /api/v1/skills` antwortet außerdem mit `failures` — Bundles auf der Platte, die sich nicht lesen ließen, jedes mit `slug`, `path` und `message`; normalerweise ein leeres Array —, eine Liste scheitert also nie daran, dass ein Bundle kaputt ist.

Sende beim Aktualisieren oder Löschen das zuletzt gelesene `etag` als `If-Match`. Hat sich die Datei geändert, folgt **412** `SKILL_STALE` mit dem aktuellen Tag in `data.etag`. Es wird nichts geschrieben. Ein geschütztes `PUT` auf einen Skill, den es nicht gibt, ergibt dieselbe **412** mit `data.etag: null`; ein geschütztes `DELETE` auf einen solchen Skill ergibt schlicht **404** `SKILL_NOT_FOUND` — was schon weg ist, ist erledigt. Lade den aktuellen Inhalt und führe die Änderungen zusammen, bevor du erneut speicherst.

Für diese Schreibprüfung ist ein starker Tag erforderlich; `W/"…"` passt nicht. Die Anfragevalidierung findet vor der Vorbedingungsprüfung statt. Mit `If-None-Match: *` erlaubst du ausschließlich das Anlegen: Ein bereits vorhandenes Bundle ergibt **412** `SKILL_EXISTS`.

`GET /api/v1/skills/{slug}/files/{path}` liest jede Datei des Bundles — `SKILL.md` eingeschlossen — als rohe Bytes, benannt über `Content-Disposition`, mit `path` genau so, wie `files[].path` es listet (`/` roh oder als `%2F`); der Lesezugriff ist validiert — der `ETag` sind die Bytes der Datei, `Last-Modified` ihre Änderungszeit, und `If-None-Match` oder `If-Modified-Since` antwortet **304** —; ein Pfad, den die Liste nie tragen würde, ergibt **404**, `SKILL_FILE_NOT_FOUND`, und ein Bundle, das die Dateischicht ablehnt — ein eingeschleuster Symlink, eine Datei über der Staging-Grenze von 4 MiB — **422**, `SKILL_MALFORMED`.

Ein rohes Punktsegment in der URL (`../`, oder `%2e%2e/` — die Punkte kodiert, der Schrägstrich nicht) erreicht die Route nie: Der Edge weist es zuerst ab, mit einer eigenen **404**, `NOT_FOUND`, einer eigenen `X-Request-Id` und ohne `X-Tale-Api-Version`; eine Schreibweise, in der auch die Schrägstriche kodiert sind (`%2e%2e%2f…`), erreicht die Route und wird als `SKILL_FILE_NOT_FOUND` gelesen. Jeder Skill trägt `canEdit` — ob dieser Schlüssel das Bundle bearbeiten darf; mitgelieferte Skills sind Organisations-Bundles, die ein Administrator überschreiben darf —, prüfe es also vor einem Speichern, das eines ersetzen soll. Skills unterstützen die Sichtbarkeit `org` und `team`; `teams` muss Teams dieser Organisation benennen.

Jeder Skill sagt außerdem, wer ihn erstellt und wer ihn zuletzt bearbeitet hat. `origin` ist `release` für einen Skill, den ein verwaltetes Konfigurations-Release installiert hat, `builtin`, wenn kein Ersteller festgehalten ist (die Dokument-Skills, mit denen eine Organisation startet), und sonst `member`; dann nennt `owner` die Benutzer-ID des Erstellers. `ownerName` ist dessen Anzeigename, solange er Mitglied der Organisation ist, und fehlt, sobald er sie verlassen hat. `updatedBy` und `updatedByName` nennen das Mitglied, dessen Speichern in Tale den gespeicherten `SKILL.md` erzeugt hat. Sie fehlen, wenn seit dem Erstellen niemand den Skill bearbeitet hat oder die Datei seit der letzten Bearbeitung außerhalb von Tale geändert wurde. Ein Speichern, das den Skill ändert, landet im Audit-Log der Organisation, mit der Person hinter dem Schlüssel als Akteur: `skill.created`, `skill.updated` und `skill.sharing_changed`, wenn sich `visibility` oder `teams` geändert haben (Vertrag 3.4.0).

Eine Organisation kann organisationsweite Skills mit ihrer [Richtlinie zur Skill-Freigabe](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits#skill-sharing) vorbehalten: Redakteuren und höher oder Inhabern und Admins, dazu Mitgliedern mit einer gültigen `tale:skills.publish`-Zuweisung. Wer außerhalb dieses Kreises einen Schlüssel nutzt, erhält **403**, `SKILL_PUBLISH_FORBIDDEN`, für ein Speichern, das einen Skill mit `visibility: org` anlegen, einen auf `org` erweitern oder einen `org`-Skill direkt ändern würde; nichts wird geschrieben, und die Ablehnung landet als `skill.publish_denied` im Audit-Log. Offen bleiben ein Speichern mit `visibility: team` und den eigenen `teams`, ein byte-identisches Speichern und `DELETE`. `capabilities.skillPublish` in `GET /api/v1/me` beantwortet die Frage vor dem ersten Speichern (Vertrag 3.5.0).

Die Sichtbarkeit `private` gibt es für Skills nicht mehr: setzen lässt sie sich nicht, und ein Bundle, das sie noch trägt, behält sie nur, wenn das Speichern `visibility` weglässt. Ein Slug hat höchstens 64 Zeichen aus Kleinbuchstaben, Ziffern und einzelnen Bindestrichen, und `anthropic` und `claude` sind reserviert; `PUT` weist einen fehlerhaften mit **400**, `INVALID_SKILL_SLUG`, ab und nennt die verletzte Regel, während `GET` und `DELETE` ihn als nicht vorhanden mit **404**, `SKILL_NOT_FOUND`, beantworten.

### Konversationen spiegeln und Antworten zustellen

Lege zuerst den Kontakt mit `POST /api/v1/contacts` an. Ein Konversations-Snapshot verweist über `externalContactId` auf dessen `externalId` in derselben Organisation. Fehlende Kontakte ergeben **404** `CONTACT_NOT_FOUND`, mehrdeutige Zuordnungen **409** `CONTACT_AMBIGUOUS`. Ein bereits gespiegeltes Quellgespräch lässt sich nicht einem anderen Kontakt zuordnen; eine abweichende `externalContactId` ergibt **409** `CONVERSATION_CONTACT_CONFLICT`.

`POST /api/v1/conversations/sync` verarbeitet die ganzzahlige `version` nach diesen Regeln:

| Eingang | Ergebnis |
| --- | --- |
| Neuere Version | Snapshot übernehmen. |
| Ältere Version | Snapshot ignorieren. |
| Gleiche Version, anderer Inhalt | **409** `CONVERSATION_SNAPSHOT_CONFLICT`. |
| `deleted: true`, Version mindestens so hoch wie gespeichert | Spiegelung schließen; Wiederholung nach dem Schließen ändert nichts. |

Das Schließen behält Gespräch und Nachrichten im Posteingang. Diese API löscht sie nicht endgültig.

Antworten aus dem Tale-Posteingang holst du über `POST /api/v1/conversations/deliveries/claim` ab. Willst du eine solche Antwort später im Snapshot zurückmelden, setze `taleMessageId` auf ihre `messageId` und bestätige zuvor die Zustellung unter ihrer `externalId`. Andernfalls folgt **409** `DELIVERY_UNACKNOWLEDGED`. Ohne `taleMessageId` gilt eine Nachricht als Nachricht des Quellsystems, unabhängig von `isCustomer`.

Ein Claim muss eine von dir gespiegelte Quelle benennen. Eine unbekannte Quelle ergibt **404** `CONVERSATION_SOURCE_NOT_FOUND`; eine Quelle, die ausschließlich anderen Service-Benutzern gehört, **403** `INTEGRATION_NOT_OWNED`. Eine falsche Quelle liefert somit keine irreführend leere Warteschlange.

Abgeholte Zustellungen enthalten `attempts`, `leaseExpiresAt`, `lastErrorCode` und `firstClaimedAt`. Mit `GET /api/v1/conversations/deliveries?source=` liest du die Warteschlange, ohne eine Zustellung zu übernehmen. Die Antwort enthält Status (`queued`, `leased`, `failed`, `delivered`), Versuchszahl und Zeitstempel, aber weder Claim-Token noch Nachrichteninhalt. Die am längsten fälligen Einträge stehen zuerst in `{deliveries, isDone, continueCursor}`; verwende `?cursor=` für Folgeseiten.

`?status=failed` beschränkt die Liste auf unzustellbare Antworten. `POST /api/v1/conversations/deliveries/{id}/retry` stößt eine solche Zustellung erneut an und wird wie die entsprechende Aktion im Posteingang protokolliert. Für andere Zustellungen folgt **409** `DELIVERY_RETRY_UNAVAILABLE`.

Mit `POST /api/v1/conversations/assignment` weist du ein gespiegeltes Gespräch einem Team zu: `{source, externalId, teamId}`, wobei `teamId` aus `GET /api/v1/teams` stammt und `null` die Zuweisung aufhebt. Die Mitglieder des Teams können das Gespräch danach im Posteingang öffnen und werden benachrichtigt. Wie im Posteingang dürfen nur Schlüssel von Admins und Inhabern zuweisen; ein Schlüssel mit Bearbeitungsrechten erhält **403** `ROLE_FORBIDDEN` und kann seine Quelle stattdessen über eine [Routing-Regel](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits) zuordnen. Ein Team außerhalb der Organisation ergibt **400** `TEAM_NOT_IN_ORG`, ein Spiegel ohne Snapshot **404** `CONVERSATION_NOT_FOUND` und einer, der einem anderen Dienstnutzer gehört, **403** `INTEGRATION_NOT_OWNED`.

Bereite Anhänge vor dem Snapshot über `POST /api/v1/conversations/uploads` vor. Ungültige Anhänge verhindern die Übernahme:

| Problem | Antwort |
| --- | --- |
| Nicht vorbereitete, abgelaufene, ungültige oder organisationsfremde `storageId` | **400** `ATTACHMENT_NOT_STAGED`. |
| Von einem anderen Service-Benutzer derselben Organisation vorbereiteter Anhang | **403** `ATTACHMENT_NOT_OWNED`. |
| Deklarierte `size` weicht von den hochgeladenen Bytes ab | **400** `ATTACHMENT_SIZE_MISMATCH`. |

`replyConstraints` begrenzt Textlänge, Anzahl und Größe der Anhänge sowie Dateiendungen für Antworten, die Personen im Posteingang verfassen. Diese Grenzen werden beim Antworten durchgesetzt, nicht beim Einlesen eines Snapshots.

`GET .../deliveries/{id}/attachments/{index}` liefert `DELIVERY_NOT_FOUND`, wenn keine abgeholte Zustellung mit dieser ID existiert. Eine fehlende Anhangposition oder ein Index außerhalb der ganzen Zahlen von 0 bis 9 ergibt `ATTACHMENT_NOT_FOUND`.

Nicht gebundene vorbereitete Uploads werden automatisch bereinigt: nach dem Zwei-Stunden-Fenster plus 24 Stunden Karenz, beim nächsten Upload in derselben Organisation. Eine Löschroute dafür gibt es nicht. Gebundene Anhänge bleiben so lange erhalten wie ihre Nachricht. Alle Anfrageinhalte dieser Familie sind strikt; unbekannte Schlüssel, auch innerhalb von Nachrichten oder Anhängen, ergeben **400** `INVALID_BODY` mit dem Feldnamen.

`GET /api/v1/conversations/sync` nennt außerdem die gebundene `externalContactId`, die `contactId` der gebundenen Zeile und `contactStatus`: `active`, `trashed` oder `missing` — sowie `sourceDeleted` mit dem Inbox-`status`, damit eine Engine, die von der Quittung aus weitermacht, einen gelandeten Abbau erkennt: Ein Inhalts-Snapshot auf einen abgebauten Spiegel antwortet in jeder Version **409** `CONVERSATION_CLOSED` (spiegle die Quellunterhaltung unter einer neuen `externalId`, um neu zu beginnen). Die Bindung behält die ursprüngliche Kontaktzeile. Ein gelöschter Kontakt liegt im Papierkorb; seine E-Mail und externe ID werden wieder frei. Ein neuer Kontakt mit denselben Kennungen übernimmt jedoch niemals den alten Konversationsverlauf. Ein im CRM umgeschlüsselter Kontakt (ein `PATCH` seiner `externalId`) behält dagegen seine Unterhaltungen: Ein Snapshot, der die aktuelle ID nennt, greift, und die Quittung folgt ihr, während die ID, die er nicht mehr trägt, **409** `CONVERSATION_CONTACT_CONFLICT` ergibt und die ID nennt, an die die Unterhaltung gebunden ist. `GET /api/v1/conversations?source=` listet jede Unterhaltung, die du unter einer Quelle gespiegelt hast — `conversationId`, `externalId`, `externalContactId`, `contactId`, `contactStatus`, `version`, `sourceDeleted`, `status`, `subject` —, neueste zuerst als Keyset-Seite unter `conversations` (dieselbe `?cursor=`-Schleife wie bei jeder Liste), und `?contactStatus=trashed` findet die Spiegel, die ein gelöschter Kontakt eingefroren hat.

Ein neuerer Inhalts-Snapshot für einen Kontakt im Papierkorb ergibt `409 CONVERSATION_CONTACT_TRASHED`. Stelle den Kontakt wieder her — mit `POST /api/v1/contacts/{id}/restore`, das nach der Regel des Anlegens arbeitet (ein lebender Kontakt, der seitdem seine E-Mail oder `externalId` übernommen hat, weist die Wiederherstellung mit der **409** des Anlegens ab), oder über den Papierkorb der App —, bevor du weiteren Inhalt sendest, oder beende die Spiegelung mit `deleted: true` und einer gleichen oder höheren Version; eine beendete Spiegelung öffnet die Wiederherstellung nicht wieder, ein späterer Inhalts-Snapshot ergibt also dieselbe 409, solange der Kontakt im Papierkorb bleibt. Ältere Snapshots bleiben ignoriert, und für Wiederholungen derselben Version gelten weiterhin die Versionsregeln oben. Das Löschen macht also nicht jede Wiederholung zu einem Fehler.

### Durchsuchbares Wissen und Hub-Dokumente erstellen

`POST /api/v1/documents` kann Text direkt als `content` speichern. Dieser Inline-Inhalt bleibt lesbar, wird aber nicht indexiert. Die Wissenssuche findet nur dateigestützte Dokumente. `POST .../retry-indexing` liefert deshalb bei Inline-Dokumenten `{"status": "skipped", "reason": "content-only"}`.

Weitere Gründe für `skipped` sind `untracked-blob`, `unsupported` (dauerhafter Indexierungsfehler; siehe `indexing.errorCode`) und `in-progress` (ein frischer Indexierungsjob wartet bereits oder läuft). Frage im letzten Fall den Dokumentzustand erneut ab. Für eine bisher von der Indexierung ausgenommene Datei hebt ein Retry diese Ausnahme auf und liefert `indexing`.

Eine Projektdatei gehört nicht zu dieser Schnittstelle — sie ergibt **404**, `DOCUMENT_NOT_FOUND`, wie jede ID außerhalb der Wissensdatenbank —, hat aber denselben Retry unter `POST /api/v1/projects/{id}/files/{documentId}/retry-indexing`, der die beim Binden gesetzte Abmeldung `skipRagIndexing` aufhebt (siehe **Prüfen, was angekommen ist** unten). Der eine wie der andere Retry läuft durch dieselben Schutzmechanismen wie **Jetzt indexieren** in der App, ein Budget von 10 pro Benutzer und Minute eingeschlossen (**429**, `RATE_LIMITED`). Die Alternative `fileId` verlangt einen noch ungebundenen Upload für die Wissensdatenbank, den der Schlüsselbesitzer selbst in der ausgewählten Organisation über die App angelegt hat. REST erstellt keinen solchen Upload.

Für durchsuchbaren Text verwendest du `POST /api/v1/knowledge-entries`. Tale erstellt ein dateigestütztes Dokument mit `sourceProvider: knowledge` und startet die Indexierung. Erlaubt sind höchstens 8.000 Zeichen und ein aktiver Eintrag pro Thema. Die Antwort **201** `{id, documentId}` enthält bereits die Dokument-ID; frage damit `GET /api/v1/documents/{documentId}` ab, bis die Indexierung abgeschlossen ist.

Ein `PATCH` ersetzt den aktiven Eintrag durch eine neue Version und indexiert unter derselben `documentId` erneut. Sind `topic` und `content` nach dem Trimmen unverändert, entsteht keine Version; die Antwort nennt die vorhandene Eintrags-ID. Ein `PATCH` auf eine abgelöste Zeile ergibt **409**, `KNOWLEDGE_ENTRY_SUPERSEDED`, und nennt in `data.activeId` die aktive Zeile des Themas (in `data.supersededBy` ihre direkte Nachfolgerin) — ändere diese Zeile, ohne die Kette entlangzuhangeln. Ein Eintrag, der über diese Tür angelegt oder abgelöst wird, trägt `source: "api"` (das Formular der App schreibt `manual`, das Festhalten durch den Assistenten `chat`), sodass die Tabelle der Wissenseinträge die drei auseinanderhält. Ein Löschen verschiebt das zugehörige Dokument in den Papierkorb.

Die Endpunkte für Wissenseinträge benötigen das Schreibrecht für Wissen — ein Mitglied mit Leserechten ergibt **403**, `KNOWLEDGE_ENTRY_FORBIDDEN` —, und ein Objektspeicher, der den Inhalt nicht binnen 30 Sekunden annimmt, ergibt **503**, `KNOWLEDGE_ENTRY_STORE_TIMEOUT`, ohne dass etwas geschrieben wird. Dieses Dokument verweigert ein direktes `DELETE /api/v1/documents/{id}` und ein `PATCH` seines Titels oder Inhalts mit **409**, `DOCUMENT_HAS_KNOWLEDGE_ENTRY` und `data.entryId` — der Eintrag ist der Weg, es zu ändern. `GET /api/v1/knowledge-entries?topic=<topic>&status=superseded` listet die abgelösten Versionen eines Themas, jede mit `supersededAt` gestempelt, und `GET /api/v1/knowledge-entries/{id}/versions` antwortet mit der ganzen Kette von jeder ihrer Zeilen aus, die neueste zuerst.

`GET /api/v1/documents` listet Hub-Dokumente mit den neuesten zuerst. Wenn du die Ordneransicht der App nachbildest, wähle den Bereich ausdrücklich:

| Abfrageparameter `folderId` | Zurückgegebene Dokumente |
| --- | --- |
| Nicht angegeben | Alle sichtbaren Hub-Dokumente, auch innerhalb von Ordnern. |
| `root` | Nur Dokumente, die in keinem Ordner liegen. |
| Eine Ordner-ID | Dokumente direkt in diesem Ordner. |

`GET /api/v1/documents/{id}/content` liefert den Inhalt mit denselben Download-Funktionen wie Projektdateien: `Content-Disposition`, `Range` und `HEAD`. Bei Inline-Dokumenten liefert die Route den Text mit dem gespeicherten `mimeType`. Die Metadatenroute `GET /api/v1/documents/{id}` enthält `content` nur für Inline-Inhalt; bei dateigestützten Dokumenten ist es `null`.

`contentHash` ist ein eigenes Antwortfeld, kein Schlüssel in deinen `metadata`. Es enthält den SHA-256-Hash, sofern Tale ihn für den Inhalt berechnet hat, etwa bei Wissenseinträgen und synchronisierten Dateien; andernfalls ist es `null`.

Ein Dokument-`PATCH`, der nichts ändert — ein leerer Body, oder jedes Feld schon auf seinem Wert —, schreibt nichts und lässt `updatedAt` in Ruhe, ein wiederholter No-op macht also nie das `expectedUpdatedAt` eines anderen Clients ungültig; Inhalt, MIME-Typ, Erweiterung oder Quellanbieter eines kontrollierten Records werden mit **400**, `DOCUMENT_RECORD_FROZEN` (in Prüfung oder freigegeben) oder `DOCUMENT_RECORD_REPLACEMENT_REQUIRED` (ein Entwurf — nimm den Ersetzungs-Ablauf), abgewiesen, und ein Eintrag in `teamIds`, dessen Team der Schlüsselbesitzer nicht angehört, mit **403**, `TEAM_ACCESS_DENIED` (ein Team, das nicht zur Organisation gehört, mit **400**, `TEAM_NOT_IN_ORG`; eine wiederholte ID fällt auf eine zusammen).

Jedes dateigestützte Dokument trägt `indexing` — `status` ist `pending`, `queued`, `running`, `completed`, `failed`, `unsupported` oder `skipped`, mit `indexedAt`, `error` und `errorCode`, sobald gesetzt —, polle das Dokument nach dem Anlegen oder einem `retry-indexing` also, statt zu schlafen. Bereits an ein Dokument, einen Thread oder ein Gespräch gebundene Uploads lassen sich hier nicht erneut verwenden. Fehlende Uploads, Uploads anderer Benutzer und gebundene Uploads ergeben **404**, `FILE_NOT_FOUND`. Projekt-, Chat- und Gesprächsuploads können über diese Route nicht zu Dokumenten der Wissensdatenbank werden. Gelöschte oder abgelaufene Dokumente, auch Dateien, die zusammen mit ihrem Projekt gelöscht wurden, erscheinen hier nicht. Dateien, die du beim Löschen eines Projekts in die Wissensbibliothek verschiebst, bleiben dort verfügbar.

Die Inhalte von `POST` und `PATCH` sind strikt: Ein `projectId` ergibt **400**. Projektdateien legst du über die Upload- und Dateirouten des Projekts an.

Verzweige nach `indexing.errorCode`, nicht nach dem Wortlaut von `error`. Das OpenAPI-Schema enthält diese feste Auswahl:

| Status und Codes | Nächster Schritt |
| --- | --- |
| `unsupported`: `unsupported_type`, `image_no_vision`, `empty`, `not_text`, `malformed` | Ersetze die Quelle oder exportiere sie in einem unterstützten Format. Bei `not_text` brauchst du tatsächlichen UTF-8-Text. `malformed` bezeichnet derzeit ein unlesbares PDF; beschädigte Office-Dateien können stattdessen `indexer_error` liefern. Die Retry-Route überspringt dauerhafte Codes auch bei älteren Zeilen mit Status `failed`. |
| `failed`: `embedding_upstream`, `indexer_error`, `index_rebuilding` | Der Hintergrundauftrag wiederholt diese Fehler. Prüfe den Status, bevor du selbst erneut anstößt. |
| `failed`: `embedding_not_configured`, `embedding_provider_refused`, `index_repair_failed` | Lass Anbieter-Konfiguration, Berechtigungen oder Indexzustand vom Betreiber korrigieren und versuche es danach erneut. `embedding_provider_refused` deckt auch ein Modell ab, das Vektoren mit einer anderen Breite liefert, als die Einstellungen angeben, sowie Embedding-Zugangsdaten, die die Plattform nicht verwenden kann (keine konfiguriert, gelöscht, deaktiviert oder nicht lesbar); das Speichern korrigierter Embedding-Einstellungen oder das Anlegen beziehungsweise Reparieren der Zugangsdaten, die das Embedding-Modell verwendet, stellt jedes Dokument, das am Embedding-Modell gescheitert ist, erneut in die Warteschlange. |
| `failed`: `secret_detected`, `pii_blocked` | Korrigiere die Quelle oder die freigegebene Inhaltsrichtlinie der Organisation vor dem nächsten Versuch. |
| `failed` ohne `errorCode` | Die Plattform hat den Fehler abgeschlossen, ohne ihn einzuordnen, meist weil die Indexierung vor dem Ende abbrach (ein verlorener Auftrag oder ein angehaltener Worker). Warte nicht auf einen automatischen neuen Versuch: Stoße `retry-indexing` an. |

## Benachrichtigungen eines Mitglieds spiegeln

`GET /api/v1/notifications/sync` exportiert die Benachrichtigungen, die ein bestimmtes Mitglied sehen darf. Die Route ist seit API-Vertrag 1.8.0 verfügbar und eignet sich für eine einseitige Synchronisierung in eine andere Anwendung. Der API-Schlüssel muss einem Inhaber oder Admin der ausgewählten Organisation gehören oder einem Mitglied, dem ein Admin die Berechtigung `tale:notifications.export` erteilt hat (seit API-Vertrag 1.14.0). Eine andere Rolle allein reicht nicht, auch nicht die Entwicklerrolle.

### Export ohne Admin-Rolle delegieren

Ein Dienst, der Benachrichtigungen spiegelt, braucht kein Admin-Konto. Mit der Admin-Rolle lassen sich auch Mitglieder, Single Sign-on und SCIM verwalten und Passwörter rangniedrigerer Mitglieder zurücksetzen. Betreibe den Dienst deshalb als gewöhnliches Mitglied und erteile diesem Mitglied genau die Berechtigung, die der Export prüft. Sie ist ein Eintrag im Kompetenzregister der Organisation: Sie gilt nur in dieser Organisation, wird protokolliert, kann ein Ablaufdatum haben und wird automatisch widerrufen, wenn ein Admin das Mitglied entfernt oder dein Identitätsanbieter die Mitgliedschaft per SCIM aufhebt.

Ein Inhaber oder Admin erteilt sie unter **Einstellungen > Richtlinien > Kompetenzen** ([Kompetenzen](https://docs.tale.dev/de/platform/admin/governance/competences)) oder per HTTP aus einer aktiven Sitzung. `TALE_ORIGIN` ist der Ursprung deiner Tale-Instanz, `TALE_SESSION_COOKIE` der Cookie-Header dieser Sitzung. `TALE_ORG_ID` und `TALE_WORKER_USER_ID` sind die Werte `organization.id` und `user.id`, die `GET /api/v1/me` für den Schlüssel des Dienstes liefert:

```bash
GRANT_BODY=$(jq -n --arg user "$TALE_WORKER_USER_ID" \
  '{userId:$user,competence:"tale:notifications.export",evidence:"Notification mirror worker"}')
curl -sS --compressed -X POST "$TALE_ORIGIN/api/app/governance/competences?orgId=$TALE_ORG_ID" \
  -H "Cookie: $TALE_SESSION_COOKIE" \
  -H "Origin: $TALE_ORIGIN" \
  -H "Content-Type: application/json" \
  -d "$GRANT_BODY"
```

Die Antwort ist **201** mit `{ "recordId": "…" }`. Mit `expiresAt`, einem künftigen Zeitpunkt in ganzen Unixzeit-Millisekunden bis höchstens `8640000000000000`, endet die Berechtigung von selbst; ohne das Feld läuft sie nicht ab. Ein vergangener Zeitpunkt liefert **400** `COMPETENCE_EXPIRY_IN_PAST`, ein Wert, der keine ganze Zahl in diesem Bereich ist, **400** `invalid body`. Solange eine Berechtigung gültig ist, liefert eine erneute Erteilung **409** `COMPETENCE_ALREADY_GRANTED`. Ein anderer Name unter `tale:` liefert **400** `COMPETENCE_CAPABILITY_UNKNOWN`, ein Benutzer außerhalb der Organisation **400** `COMPETENCE_USER_NOT_MEMBER` und eine Sitzung ohne Inhaber- oder Admin-Rolle **403** `COMPETENCE_FORBIDDEN`. Prüfe vor der ersten Seite mit dem Schlüssel des Dienstes, dass `GET /api/v1/me` `capabilities.notificationExport: true` meldet.

Um die Berechtigung zu entziehen, suche mit derselben Sitzung ihre `id` in `GET /api/app/governance/competences?orgId=<orgId>&userId=<userId>` und sende `POST /api/app/governance/competences/<recordId>/revoke?orgId=<orgId>`. Die nächste Exportanfrage des Dienstes liefert `403 ROLE_FORBIDDEN`. Ein widerrufener Eintrag bleibt als Prüfpfad in der Liste; erteile die Berechtigung neu, um den Export wieder zu erlauben.

### Empfänger und Datenstrom wählen

Setze `TALE_RECIPIENT_EMAIL` auf die bestätigte E-Mail-Adresse des gewünschten Mitglieds. Es muss genau eine passende aktive Mitgliedschaft in der Organisation geben. Die Route prüft Mitgliedschaft und E-Mail-Bestätigung bei jeder Seite erneut. Für Organisationsbenachrichtigungen gelten die Sichtrechte der empfangenden Person: Ein Admin-Schlüssel exportiert keine Sicherheitsmeldungen, die diese Person in Tale nicht sehen dürfte.

| Query-Parameter | Regel |
| --- | --- |
| `recipientEmail` | Gültige E-Mail-Adresse als Pflichtfeld, höchstens 320 Zeichen. Der Abgleich ignoriert Groß- und Kleinschreibung. |
| `stream` | Pflichtfeld: `personal` für persönliche Meldungen oder `organization` für sichtbare Organisationsmeldungen. Für eine vollständige Spiegelung musst du beide getrennt lesen. |
| `locale` | Optional `en`, `de` oder `fr`. Ohne Angabe gilt die Organisationssprache; fehlende Meldungstexte werden aus Englisch ergänzt. |
| `limit` | Standard und Höchstwert 100, Mindestwert 1. Ganze Zahlen außerhalb des Bereichs werden auf die Grenze begrenzt. |
| `cursor` | Bei der ersten Anfrage weglassen, danach den vorherigen `continueCursor` unverändert senden. Ein numerischer `offset` wird nicht unterstützt. |

```bash
curl --fail-with-body --silent --show-error --compressed --get \
  "$TALE_URL/api/v1/notifications/sync" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --data-urlencode "recipientEmail=$TALE_RECIPIENT_EMAIL" \
  --data-urlencode 'stream=personal' \
  --data-urlencode 'locale=de' \
  --data-urlencode 'limit=100'
```

Eine erfolgreiche Anfrage liefert `200` mit `{recipientId, page, isDone, continueCursor}`. Fehlt die Person, ist sie deaktiviert oder ihre E-Mail nicht bestätigt, oder ist die Mitgliedschaft mehrdeutig, lautet die Antwort `recipientId: null`, `page: []`, `isDone: true` mit leerem Cursor. Die Route lädt niemanden ein und legt kein Konto an.

### Einträge lesen und einen Durchlauf abschließen

| Feld eines Eintrags | Bedeutung |
| --- | --- |
| `id` | Stabile Quell-ID im Format `<organizationId>:<stream>:<notificationId>`. Nutze sie zum Abgleichen und Aktualisieren in der Spiegelung dieser Person. Organisationsmeldungen können bei mehreren Personen dieselbe ID haben; halte ihre Spiegelungen getrennt. |
| `version` | SHA-256-Hash mit 64 Hexadezimalzeichen über den exportierten Eintrag, bevor der Hash ergänzt wird. Inhalt und Lesestatus beeinflussen ihn; geänderte Übersetzungen von Titel oder Text ebenfalls. Er kennzeichnet Änderungen und ist keine fortlaufende Nummer. |
| `title`, `body` | Texte aus Tales Benachrichtigungskatalogen mit eingesetzten Parametern, begrenzt auf 500 beziehungsweise 8.000 UTF-16-Codeeinheiten. Behalte die Sprache zwischen Durchläufen bei. |
| `path` | Dasselbe organisationsbezogene Ziel unter `/dashboard/...` wie in der Benachrichtigungsglocke, einschließlich kodierter IDs und Query-Parameter. Ergänze den Browser-Ursprung von Tale, nicht die interne API-Adresse. Die Person braucht weiterhin Zugriff und gegebenenfalls eine Verbindung zum privaten Netz. |
| `createdAt` | Erstellungszeit als Millisekunden seit Unix-Epoch. |
| `read` | Ob die empfangende Person die Meldung in Tale gelesen hat. |

Persönliche Meldungen sind nach absteigender Sequenznummer sortiert, Organisationsmeldungen nach absteigender Erstellungszeit und ID. Beide verwenden signierte Keyset-Cursor. Jeder Cursor gilt nur für seine Organisation, Person und seinen Datenstrom. Verwende ihn nicht für eine andere Person oder den anderen Datenstrom.

So hältst du die Spiegelung aktuell:

1. Beginne beide Datenströme ohne Cursor. Gleiche Einträge anhand ihrer `id` ab und erkenne Änderungen an `version`.
2. Sende bei `isDone: false` den erhaltenen Cursor zurück. Beende den Datenstrom bei `true`; sende keinen leeren Abschlusscursor.
3. Entferne fehlende Einträge im Ziel erst, wenn beide Datenströme vollständig und erfolgreich gelesen wurden. Bei einem Fehler behältst du die vorherige Spiegelung und behebst die fehlgeschlagene Abfrage.
4. Beginne spätere Durchläufe wieder auf der ersten Seite. So erkennst du auch geänderte Texte oder Lesestatus älterer Meldungen. Ein Cursor ist eine Position innerhalb der Liste, kein Fortschrittsmarker für einen Änderungsstrom.

Der Export markiert keine Tale-Meldung als gelesen und löscht keine Meldung. Es gibt hier keinen Aufruf zum Bestätigen oder Zurückschreiben. Ein geänderter Lesestatus im Zielsystem verändert Tale nicht.

### Fehler beim Export beheben

| Antwort | Nächster Schritt |
| --- | --- |
| `401 UNAUTHORIZED` | Fehlenden, ungültigen oder abgelaufenen API-Schlüssel ersetzen. |
| `403 ROLE_FORBIDDEN` | Einen Schlüssel eines Inhabers oder Admins der ausgewählten Organisation verwenden oder dem Benutzer des Schlüssels von einem Admin `tale:notifications.export` erteilen lassen; `capabilities.notificationExport` in `GET /api/v1/me` bestätigt es. Eine abgelaufene oder widerrufene Berechtigung erlaubt den Export nicht mehr. Die Mitgliedschaft der empfangenden Person erteilt dem Aufrufer keine Exportrechte. |
| `400 INVALID_QUERY` | Fehlende oder ungültige Empfänger-, Datenstrom- oder Sprachangaben, unbekannte oder doppelte Parameter sowie leere Cursor oder Limits korrigieren. `data.issues` nennt die Felder. |
| `400 INVALID_LIMIT` | Eine ganze Zahl als Limit senden. |
| `400 INVALID_CURSOR` | Den betroffenen Datenstrom ohne Cursor neu beginnen. Eine entfernte oder geänderte Mitgliedschaft kann den bisherigen Cursor ungültig machen. |
| `200`, `recipientId: null` | Aktuelle Mitgliedschaft und bestätigte E-Mail prüfen. Die leere abgeschlossene Seite bestätigt nicht, dass ein Konto existiert. |
| `429 RATE_LIMITED` | `Retry-After` und das [gemeinsame API-Budget](https://docs.tale.dev/de/develop/rate-limits) beachten. Währenddessen die vorhandene Spiegelung beibehalten. |

Zusätzlich gelten die üblichen Fehler bei der Organisationsauswahl. Behandle einen fehlgeschlagenen Export im Zielsystem niemals als erfolgreich gelesene leere Liste.

## Agenten eines Projekts verwalten

Jeder Agent gehört zu einem Projekt. Die Projekt-ID steht bei jeder Operation verpflichtend in der URL; die Antwort enthält `projectId` und die `id` des Agenten. API und Projekt-Tab **Agenten** verwalten dieselben Datensätze mit denselben Zugriffsrechten.

| Operation                       | Route                                           | Erfolg         |
| ------------------------------- | ----------------------------------------------- | -------------- |
| Agenten auflisten               | `GET /api/v1/projects/{id}/agents`              | `200 {agents}` |
| Anlegen                         | `POST /api/v1/projects/{id}/agents`             | `201 {agent}`  |
| Lesen                           | `GET /api/v1/projects/{id}/agents/{agentId}`    | `200 {agent}`  |
| Gesamte Konfiguration speichern | `PUT /api/v1/projects/{id}/agents/{agentId}`    | `200 {agent}`  |
| Löschen                         | `DELETE /api/v1/projects/{id}/agents/{agentId}` | `204`          |

Wähle ein vorhandenes Projekt, einen Harness, den `GET /api/v1/models` unter `harnesses` führt — die, die die Plattform mit ihren eigenen Zugangsdaten betreibt —, und ein Modell, das er bedienen kann. Das Beispiel legt einen Claude-Code-Agenten an und liest seine Konfiguration zurück; eine Aufgabe startet es nicht.

```bash
: "${BASE:?Set BASE to your Tale origin}"
: "${TALE_API_KEY:?Set TALE_API_KEY}"
: "${ORG_SLUG:?Set ORG_SLUG}"
: "${PROJECT_ID:?Set PROJECT_ID to an existing project ID}"
: "${MODEL_ID:?Set MODEL_ID to a model served by your harness}"
AGENT_URL="$BASE/api/v1/projects/$PROJECT_ID/agents"
AGENT_BODY=$(jq -n --arg model "$MODEL_ID" \
  '{name:"Reviewer",harness:"claude-code",model:$model,skills:[],connectors:[]}')
AGENT_ID=$(curl -fsS "$AGENT_URL" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $ORG_SLUG" \
  -H 'Content-Type: application/json' -d "$AGENT_BODY" | jq -er '.agent.id')
curl -fsS "$AGENT_URL/$AGENT_ID" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $ORG_SLUG" \
  | jq '.agent | {name, harness, skills, connectors}'
```

```json
{
  "name": "Reviewer",
  "harness": "claude-code",
  "skills": [],
  "connectors": []
}
```

### Vollständige Agentenkonfiguration speichern

`POST` und `PUT` verlangen `name`, `harness`, `model`, `skills` und `connectors`; ein `harness` außerhalb der zulässigen Menge ergibt **400**, `PROJECT_AGENT_HARNESS_INVALID`, mit der Menge in `data.harnesses`. Optional sind `modelProvider`, `tools`, `secrets` und `instructions`. Ein `PUT` speichert die gesamte Konfiguration: Ausgelassene Anbieter- und Anweisungsfelder werden `null`, ausgelassene Tool- und Secret-Listen werden leer. Die Agenten-ID muss bereits existieren; ein `PUT` legt keinen neuen Agenten an. Übergib das zuletzt gelesene `updatedAt` als `expectedUpdatedAt`, um das Speichern bedingt zu machen: Ein Agent, der sich seitdem geändert hat, ergibt **409**, `PROJECT_AGENT_STALE`, mit dem aktuellen `updatedAt` in `data`, und nichts wird geschrieben — lade ihn neu und führe zusammen, bevor du erneut speicherst.

Ein Agent mit `managed` gleich `true` ist der [Standard-Agent](https://docs.tale.dev/de/platform/projects/project-agents#standard-agent) der Organisation: Tale hat ihn in einem Projekt ohne eigene Agenten eingerichtet und hält Laufzeit, Modell und Anweisungen im Einklang mit den Einstellungen der Organisation. Ein `PUT` auf ihn ergibt **409**, `PROJECT_AGENT_MANAGED`, und schreibt nichts; `DELETE` entfernt ihn wie jeden anderen Agenten (Vertrag 3.9.0).

### Modelle, Freigaben und Grenzen prüfen

Ein Projekt fasst höchstens 50 Agenten. Namen müssen innerhalb des Projekts unabhängig von Groß- und Kleinschreibung eindeutig sein und dürfen bis zu 120 Zeichen lang sein; jede Ausstattungsliste erlaubt 25 Einträge, Anweisungen 20.000 Zeichen. Ungültige Konfiguration oder eine überschrittene Grenze ergibt **400**; ein Name, den ein anderer Agent des Projekts schon trägt, ergibt **409**, `PROJECT_AGENT_NAME_TAKEN` — die Klasse, mit der jedes andere Duplikat an dieser Schnittstelle antwortet —, verwende also den bestehenden Agenten, statt es erneut zu versuchen.

`model` muss ein Modell aus dem Katalog der Organisation sein (nenne `modelProvider`, wenn mehrere Anbieter es bedienen), und `tools` darf nur bekannte Tool-Freigaben nennen — ein falscher Wert ergibt **400** mit `PROJECT_AGENT_MODEL_INVALID`, `PROJECT_AGENT_PROVIDER_UNKNOWN` oder `PROJECT_AGENT_TOOL_UNKNOWN`, das sagt, was zu korrigieren ist, statt eines Agenten, der an seiner ersten Aufgabe scheitert. Mit `task_start_agent` kann der Agent einen anderen Agenten desselben Projekts an einer Aufgabe arbeiten lassen (Vertrag 3.8.0). `secrets` enthält Namen von Organisationsgeheimnissen, niemals deren Werte; ein Name, den die Organisation nicht gespeichert hat, wird mit **400**, `PROJECT_AGENT_SECRET_UNKNOWN`, abgewiesen und in `data.secrets` genannt (der Dialog der App entfernt solche Namen, die API nicht — ein Tippfehler ergibt also nie einen Agenten, der ohne seine Zugangsdaten läuft).

`task_update_metadata` ist eine optionale Freigabe für Projekt-Agenten (Vertrag 3.10.0), mit der sie Priorität und Agentenzuweisung bestehender Aufgaben ändern, ohne eine Ausführung zu starten. Die Anfrage nennt `taskId`, `priority` und/oder `agentId` sowie in `expected` den aktuellen Wert jedes betroffenen Felds. `null` hebt einen Wert auf, ausgelassene Felder bleiben unverändert. Bilde `expected.assignee` als `{type, id}` aus `assigneeType` und `assigneeId` der Antwort von `task_get`; ohne Zuweisung verwendest du `null`, ebenso bei fehlender Priorität. Ein veralteter Wert führt zur Ablehnung der gesamten Anfrage. Die [Anleitung zu Projekt-Agenten](https://docs.tale.dev/de/platform/projects/project-agents) beschreibt den Schutz laufender Arbeit und ausstehender Prüfungen. `task_upsert_by_external_ref` verwendet `priority` weiterhin nur beim Anlegen einer Aufgabe.

`task_review` ergänzt mit Vertrag 3.11.0 eine optionale Freigabe für Projektagenten. Sie entscheidet nur ein ausstehendes natives Review, das dem aktiven Reviewer-Agenten zugewiesen ist, über einen abgeschlossenen Lauf eines anderen Agenten desselben Projekts. Übergib `taskId`, `expected: {approvalId, runId, evidenceRevision}` aus dem aktuellen `task_get.pendingReview`, `decision: "approve" | "request_changes"`, eine nicht leere `feedback`-Rückmeldung und `evidence: {checks, pullRequests}`. Jede Prüfung nennt ihr Ergebnis (`passed` oder `failed`) und Details; ein mitgegebener Pull Request auf GitHub nennt URL, exakten `headSha` und Prüfstatus. Für eine Freigabe müssen alle angegebenen Prüfungen bestanden sein. Die GitHub-Belege stammen vom Agenten; Tale verifiziert sie nicht beim externen Dienst.

Das Tool prüft die aktuelle Freigabe, die Rechte des aktiven aufrufenden Laufs, den gespeicherten Reviewer, den Umsetzungslauf und die lokale Belegrevision erneut. Ein veraltetes Ergebnis muss neu gelesen werden; eine andere aktuelle Aufgabenzuweisung macht den Reviewer nicht unabhängig. Die Freigabe verschiebt die Aufgabe nach `done`, `request_changes` mit Rückmeldung nach `todo`, ohne einen Lauf zu starten, auch bei einer Erwähnung in der Rückmeldung. Menschliche Kompetenzanforderungen und Workflow-Genehmigungen bleiben außerhalb dieses Tools. Für eine Agentenentscheidung gibt es keinen öffentlichen REST-Endpunkt.

Seit Vertrag 3.15.0 enthält das native `task_get.agentRuns` einen expliziten booleschen Wert `retryPending`. Nur beim neuesten fehlgeschlagenen Lauf eines noch vorhandenen Agenten kann er `true` sein. Dabei gelten dieselben Prüfungen auf vorgemerkte oder endgültig abgelehnte Wiederholungen und das verbleibende Versuchskontingent wie auf der Aufgabenkarte. Lass diese Wiederholung bestehen. `false` erlaubt keinen Neustart und nennt keinen Rücksetzzeitpunkt des Anbieters; fehlt das Feld auf einer älteren Plattform, ist der Zustand unbekannt. Gleiche vor jeder Aktion Aufgabe, Zuständigkeit, Läufe und Prüfung neu ab und beachte Wartezeiten des Anbieters sowie `retryAfter` einer Startablehnung. Es kommen weder ein öffentlicher REST-Endpunkt noch rohe Fehlertexte hinzu.

Vertrag 3.13.0 ergänzt die bestehende native Berechtigung `task_start_agent` um einen abgesicherten Überarbeitungsstart: Übergib `{taskId, resumeFrom: {kind: "review_repair", approvalId, runId}, feedback?}` für eine gespeicherte native Entscheidung `request_changes`. Der Server ermittelt Umsetzungsagent, Rückmeldung und Kommentar-ID. Er prüft atomar denselben neuesten abgeschlossenen Umsetzungslauf, die unveränderte Zuständigkeit, `todo`, das Fehlen neuerer Prüfungen oder zwischenzeitlicher Status-, Zuständigkeits- oder Archivierungsentscheidungen sowie die bestehenden Startgrenzen. Eine explizite `agentId` muss dem Umsetzungslauf entsprechen; `moveToInProgress: false` wird abgelehnt. Die Form `{approvalId, runId}` ohne `kind` behält ihre getrennte Bedeutung für offene Fragen. `stale_repair` startet nichts; versuche es nicht ohne diese Absicherung erneut.

Ein erfolgreicher Überarbeitungsstart liefert `started`, `runId` und `repairReceipt` mit `taskId`, `approvalId`, `sourceRunId`, `feedbackCommentId`, `implementationAgentId`, gestarteter `runId`, `managerAgentId`, ursprünglicher `issuerRunId` und `admittedAt`. Derselbe Manager-Agent kann den Beleg aus einem späteren aktiven, berechtigten Lauf mit `replayed: true` abrufen. Jeder Aufruf prüft die aktuelle Delegationsberechtigung und den Projektzugriff; eine Wiederholung hat keine weiteren Auswirkungen. `task_get.reviewDecision` zeigt genau den neuesten gültigen nativen Entscheidungsbeleg oder `null` bei einer neueren offenen, menschlichen oder Workflow-Prüfung beziehungsweise nicht verfügbaren Metadaten. Der Beleg ist historisch und kein aktueller Aufgabenstatus; `null` beweist keine fehlgeschlagene Speicherung. Es entsteht weder ein öffentlicher REST-Endpunkt für Überarbeitungsstarts noch ein automatischer Start durch das Prüfungsurteil.

Vertrag 3.12.0 erweitert auch die nativen Aufgabentools. `task_find` akzeptiert `reviewerAgentId` und liefert je Aufgabe `pendingReview: null` oder `{approvalId, runId, reviewer}`. Der Filter gilt für den gespeicherten Agenten des ausstehenden Reviews und gehört zur Abfrageidentität des signierten Cursors; beim Blättern muss er gleich bleiben. Er filtert nicht nach dem Umsetzungsagenten.

Für ein gespeichertes Agentenreview mit nutzbarem Umsetzungslauf liefert `task_get.reviewFiles` die Form `{expected, files, page, maxStageBytes}`. Eine Seite enthält bis zu 50 Anhänge und Ergebnisdateien. Solange `page.isDone` falsch ist, gib `page.continueCursor` als `reviewFileCursor` zurück. Der Cursor ist an Aufgabe, Reviewer, Review-Anfrage, Umsetzungslauf und Belegrevision gebunden. Einträge enthalten ihre gespeicherten Metadaten und `unavailableReason`; fehlt eine sichere Dateiidentität, nennen sie ausdrücklich ungültige Metadaten als Grund. Eine nicht gespeicherte `runId` wird nicht hergeleitet.

Dieselbe `task_review`-Berechtigung akzeptiert `{operation: "stage_file", taskId, expected: {approvalId, runId, evidenceRevision}, fileId}`, um eine aufgeführte, verfügbare Datei von höchstens 20 MiB bereitzustellen. Eigene Pfade, Speicherreferenzen oder URLs werden nicht angenommen. Die Antwort nennt den vom Server gewählten lokalen `path` und `bytes`; der Agent muss die Datei lesen, bevor er ihren Inhalt als Beleg anführt. Aufgabenzugehörigkeit, gespeicherter Reviewer, aktiver aufrufender Lauf, Berechtigung und Richtlinie werden vor der Übertragung und vor der Erfolgsmeldung geprüft. Geschützte Dokumentzuordnungen behalten ihre Zugriffsregeln; nicht unterstützte oder nicht verfügbare Dateien werden abgelehnt. Bei einem gleichzeitigen Entzug der Berechtigung oder einer Übergabe können zuvor berechtigt übertragene Bytes im Arbeitsbereich bleiben, während Erfolg und veraltete Entscheidung abgelehnt werden. Dies ist eine native Tool-Operation, kein neuer öffentlicher REST-Endpunkt für Dateien oder Entscheidungen.

Nur Inhaber und Admins der Organisation dürfen die Freigaben ändern. Ein Redakteur muss vorhandene Freigaben beim Speichern beibehalten.

Projektleser dürfen die Agenten lesen; Änderungen verlangen Bearbeitungsrechte und ein aktives Projekt. Ein unsichtbares oder fehlendes Projekt sowie eine Agenten-ID aus einem anderen Projekt ergibt **404**. Bei Mitgliedschaft in mehreren Organisationen muss jede Lese- und Schreibanfrage `X-Organization-Slug` enthalten. [Projekt-Agenten](https://docs.tale.dev/de/platform/projects/project-agents) erklärt die Arbeit an Aufgaben; der direkte Chat verwendet weiterhin den eingebauten Assistenten.

## Automatisierungsnamen in URLs

Der Name einer Automatisierung ist ein `/`-Pfad — `billing/dunning` — und ein Pfad passt nicht in ein einzelnes URL-Segment. Schreib den Namen in jeder `.../automations/{name}/...`-URL mit `__` an Stelle jedes `/`:

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/automations/billing__dunning/versions" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG"
```

Antworten tragen immer den echten Namen (`"name": "billing/dunning"`); die `__`-Form existiert nur in URLs. Skill-Slugs sind flach und brauchen keine Kodierung. Projekt-Agenten verwenden die Projekt-ID und die Agenten-ID.

### Die tatsächlich ausgeführte Version lesen

`GET /api/v1/automations` listet jede Automatisierung mit `latestVersion`, `deployedVersion` und `projectIds` — den Projekten, in denen sie installiert ist und die die Lauf-Routen unten verlangen — plus dem, was ein Starter ohne zweiten Aufruf braucht: ihre `description`, das `inputs`-Schema, zu dem ein Lauf passen muss (das der deployten Version, sonst das der neuesten gespeicherten), und ihren `trigger` — Art, Schalter und Gesundheit: `lastFiredAt`, `lastSkippedAt` und `lastSkipReason`, dieselben Stempel, die `GET .../triggers` liest, ein einziger Listenaufruf findet also jede Bindung, die eingeschaltet ist und nicht feuert — oder `null`, wenn keine gebunden ist.

`GET /api/v1/automations/{name}` antwortet standardmäßig mit der neuesten gespeicherten Version (`?version=latest` schreibt den Standard aus), und die kann ein Entwurf sein; ein Live-Lauf führt die deployte aus, lies den Vertrag des Codes, der wirklich läuft, also mit `?version=deployed` (eine Zahl benennt jede gespeicherte Version). Eine Version, die die Automatisierung nicht hat, ergibt **404** `AUTOMATION_VERSION_UNKNOWN` — `?version=deployed` ohne deployte Version ebenso —, während eine unbekannte Automatisierung `AUTOMATION_NOT_FOUND` ergibt.

`GET /api/v1/automations/{name}/versions` nennt die `deployedVersion` und markiert jede Zeile mit `deployed`, und jede Zeile trägt das Testurteil der Version: `testsPassed` ist `null`, bis die Tests gelaufen sind (ein Dokument ohne Tests bleibt `null`), sonst `true` oder `false` für den letzten Lauf — den des Speicherns, wenn `save_automation` per MCP ein Dokument mit Tests speichert, oder den des Deploy-Gates, das eine Ablehnung festhält —, und `testsCheckedAt` sagt, wann — neben einem Urteil, das festgehalten wurde, bevor 0.5.24 die Zeit mitzuschreiben begann, steht `null`, verlass dich fürs Urteil also auf `testsPassed` und auf `testsCheckedAt` nur dafür, wie frisch es ist; das jüngste Urteil gilt.

`DELETE /api/v1/automations/{name}` entfernt die Automatisierung samt Versionen, Triggern und Projektbindungen — ihre Läufe bleiben: `GET /api/v1/runs` listet sie weiterhin, per ID bleiben sie lesbar, und `GET /api/v1/automations/{name}/runs` (samt Projekt-Zwilling) antwortet sie weiter unter dem Namen, unter dem sie gelaufen sind — auf den `GET /api/v1/automations/{name}`, seine Versionen und seine Trigger dann **404** antworten — und antwortet mit **409** `AUTOMATION_HAS_ACTIVE_RUNS`, solange ein Lauf in Arbeit ist; es verlangt die Entwickler-Fähigkeit. Anlegen, Speichern und Deployen einer Automatisierung gehören nicht auf diese Oberfläche: Das sind `save_automation` und `deploy_automation` des [MCP-Endpoints](https://docs.tale.dev/de/develop/mcp-endpoint), der Canvas der App oder ein Konfigurations-Release per `tale deploy` — REST listet, liest, startet, installiert und verdrahtet Trigger für Automatisierungen, die dort gebaut wurden.

## Trigger

Ein Trigger startet eine Automatisierung ohne deinen Aufruf: nach Zeitplan, über eine Webhook-URL oder wenn die Plattform ein Event auslöst. Binde einen mit `PUT /api/v1/automations/{name}/triggers` — ein Trigger pro Automatisierung, und das `PUT` ersetzt, was vorher gebunden war:

```bash
curl -sS --compressed -X PUT "https://your-host.example.com/api/v1/automations/billing__dunning/triggers" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "event", "event": "contact.created" }'
# → 200 { "name": "billing/dunning", "deployed": true }
```

### Triggertyp auswählen

`kind` ist `schedule` (mit einem fünfteiligen `cron` und einer optionalen IANA-`timezone`), `webhook` (die Antwort trägt das `token` der URL genau einmal — die [Webhooks-Seite](https://docs.tale.dev/de/develop/webhooks) behandelt diesen Zugang) oder `event`. Einen Trigger, der nie feuern könnte, weist Tale mit **400** `AUTOMATION_TRIGGER_INVALID` und einem Satz ab, der die Korrektur nennt: ein Cron-Ausdruck, der auf nichts passt (auch ein Tag, den kein benannter Monat hat, `0 0 30 2 *`), eine Zeitzone, die keine IANA-Zone ist, ein Event, das die Plattform nicht auslöst.

Jede Art nimmt ihre eigenen Schlüssel — `cron` und `timezone` nur mit `schedule`, `event` nur mit `event`, `rotateToken` nur mit `webhook` —, und ein Schlüssel, der zu einer anderen Art gehört, wird als unbekannter Schlüssel abgewiesen (**400** `INVALID_BODY`, unter `data.issues` beim Namen genannt), ein Webhook-Trigger kann sich also nie als einer zurücklesen, der auch nach Zeitplan läuft. Ein Event-Trigger bindet eines der Events, die die Plattform heute auslöst, und die Eingabe des Laufs ist `{ "trigger": "event", "event": "<name>", "payload": <die Daten des Events> }`:

| Event                                                   | Ausgelöst, wenn                                                                                                                                                              |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contact.created`, `contact.updated`, `contact.deleted` | ein Kontakt angelegt, geändert oder gelöscht wird — über die API, die App oder einen Import                                                                                  |
| `conversation.created`                                  | ein Gespräch im Posteingang aufgeht — eine eintreffende E-Mail oder ein hereingespiegeltes externes Gespräch                                                                 |
| `conversation.message_received`                         | eine Nachricht auf einem bestehenden Gespräch landet                                                                                                                         |
| `project.created`                                       | ein Projekt angelegt wird                                                                                                                                                    |
| `task.created`                                          | eine Aufgabe angelegt wird — auf einem Board, über die API oder durch einen Intake                                                                                           |
| `task.status_changed`                                   | eine Person eine Aufgabe in einen anderen Status verschiebt (die eigenen Züge eines Agenten lösen nichts aus, eine Automatisierung kann sich also nicht selbst neu triggern) |
| `comment.created`                                       | ein Kommentar auf einer Aufgabe landet                                                                                                                                       |
| `comment.mentioned`                                     | ein Aufgabenkommentar jemanden mit `@` erwähnt                                                                                                                               |

### Triggerzustand prüfen und gezielt pausieren

`GET .../triggers` liest die Bindung zurück — als `triggers`, eine Liste mit höchstens einem Eintrag, der eine Plural in dieser Familie — samt ihrer Gesundheit: `lastFiredAt` ist der letzte Zeitpunkt, zu dem diese Bindung **einen Lauf gestartet** hat — `lastRunId` nennt ihn, und beide bleiben `null`, bis es so weit war —, während `lastSkippedAt` und `lastSkipReason` das letzte Mal festhalten, dass sie fällig war und nichts gestartet hat: `not_deployed` (nichts ist live — deploy eine Version), `unusable_cron` (der Ausdruck oder die Zone ließ sich nicht lesen; der Scheduler lässt die Bindung in Ruhe, bis sie bearbeitet wird), `start_refused` (das `inputs`-Schema der Live-Version hat die Eingabe des Laufs abgelehnt) oder `paused_after_failures` (ein Zeitplan, der sich nach wiederholten Fehlern selbst ausgeschaltet hat — siehe unten). Eine Webhook-Zustellung, die das `inputs`-Schema der Live-Version ablehnt, ist ein anderer Fall: Der Absender erhält **400** `AUTOMATION_INPUT_INVALID`, nichts startet, und keiner dieser Stempel bewegt sich — die Bindung war nicht fällig, ein Webhook, dessen jede Zustellung abgelehnt wird, liest sich also wie einer, der nie aufgerufen wurde. Prüfe Zustellungen auf der Absenderseite.

Eine Bindung lebt, wenn `lastFiredAt` mit ihrem Takt Schritt hält; eine, deren `lastSkippedAt` der neuere Stempel ist, wird fällig und läuft nicht, und der Grund sagt, was zu korrigieren ist. Ein Umbinden auf eine andere Art setzt jeden Stempel neu. `enabled: false` pausiert einen Trigger, ohne ihn zu verlieren; `DELETE .../triggers` entfernt ihn — und bei einem Webhook widerruft es die URL. Dasselbe tut das Binden einer anderen Art über einen lebenden Webhook: Der `PUT` antwortet weiterhin **200**, mit `"revoked": "webhook"` neben dem Namen, und die alte URL ist endgültig weg — ein späteres Webhook-Binden erzeugt ein anderes Token.

Ein Zeitplan, dessen Läufe immer wieder scheitern, pausiert sich selbst. `consecutiveFailures` zählt die Läufe dieser Bindung, die nacheinander mit einem `failureCode` gescheitert sind, den auch der nächste Termin wiederholen würde — `node_error`, `connector_error`, `llm_output_invalid`, `auth_error`, `missing_api_key`, `credit_exhausted` oder `model_not_found` —, und `lastFailedAt`, `lastFailureCode` und `lastFailedRunId` nennen den letzten davon. Ein Erfolg setzt die Zählung auf `0` zurück; jeder andere Fehler zählt nicht und setzt auch nichts zurück. Hat sich ein Zeitplan selbst pausiert (`enabled: false` mit `lastSkipReason: "paused_after_failures"`), behält er die Zählung, die zur Pause geführt hat, auch wenn ein Lauf, der bei der Pause noch lief, danach erfolgreich endet; nur ein `PUT` setzt die Zählung zurück. Erreicht die Zählung eines Zeitplans fünf, setzt die Plattform `enabled: false` und `lastSkipReason: "paused_after_failures"`, schreibt eine Audit-Zeile `automation.trigger.paused` und benachrichtigt die Inhaber und Admins der Organisation. Behebe den Fehler in der Automatisierung und sende dann einen `PUT` des Triggers mit `enabled: true`. Jeder `PUT` setzt die Zählung zurück und löscht diesen Grund; ein `PUT` ohne `enabled` schaltet den Trigger wieder ein, weil `enabled` standardmäßig `true` ist. Webhook- und Ereignis-Bindungen zählen weiter, werden aber nie pausiert (Vertrag 3.1.0).

Der `PUT` antwortet außerdem mit `deployed`: Binden vor dem Deployen ist erlaubt, und ein Trigger, der an eine Automatisierung ohne deployte Version gebunden ist, startet nichts — jeder Termin wird als `not_deployed` übersprungen, was der `trigger` der Zeile in `GET /api/v1/automations` zeigt —, bis eine Version deployt ist.

## Einen Lauf starten, dann pollen

Ein Lauf wird dauerhaft gespeichert und kann mehrere Minuten dauern — der Start antwortet deshalb mit **202** und der Identität des Laufs, nicht mit seinem Ergebnis:

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/automations/billing__dunning/runs" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "customerId": "cus_123" } }'
# → 202 { "runId": "...", "version": 2, "name": "billing/dunning", "mode": "live" }
```

### Laufende und wartende Zustände auswerten

Polle `GET /api/v1/projects/{id}/runs/{runId}?fields=status,finishedAt`, bis `status` `queued`/`running`/`waiting` verlässt — mit den benannten Schlüsseln bleibt der Poll eine Zeile statt des ganzen Laufs, und der `ETag` der Antwort als `If-None-Match` macht aus einem unveränderten Poll eine **304** ohne Body ([Caching](https://docs.tale.dev/de/develop/api-reference#caching-kompression-und-gezieltes-lesen)); dann lies den Lauf vollständig: Er trägt `output`, den `trace` pro Knoten und die `effects`, die er erzeugt hat.

`waiting` deckt zwei Familien ab, und nur eine braucht dich: Solange ein Lauf parkt, sagt `waitingFor`, worauf — `approval` (die Entscheidung einer Person an einem Kontrollpunkt) und `ask` (eine Frage, die eine Person beantworten muss) brauchen einen Menschen; `agent` (ein noch laufender Agent-Turn), `room` (ein Agent-Turn, dessen Start auf Platz in der Sandbox wartet, seit Vertrag 3.14.0) und `repeat` (ein Knoten, der pollt, bis seine `repeatUntil`-Bedingung gilt) nicht, und ein Lauf kann in jedem davon minutenlang gesund sitzen. „Läufe, die eine Person brauchen“ ist `waitingFor` in (`approval`, `ask`) — nie `status=waiting` allein, das sich mit pollenden Läufen füllt. `detail` benennt das Parken (`approval:<approvalId>`, `agent:<nodeId>`, `room:<nodeId>`, `repeat:<nodeId>`) und, sobald fehlgeschlagen, den Fehlersatz.

`POST /api/v1/projects/{id}/runs/{runId}/cancel` stoppt den Lauf an der nächsten Knotengrenze; erledigte Arbeit wird nicht rückgängig gemacht. Die Antwort enthält `cancelled` und den resultierenden `status`. Bei erfolgreichem Abbruch lauten sie `true` und `"cancelled"`; das `detail` des Laufs wird `null`. Ist der Lauf bereits beendet, stehen neben `cancelled: false` sein Endstatus `success`, `failed` oder `cancelled`.

Bei fehlgeschlagenen Läufen ergänzt der stabile `failureCode` die lesbare Fehlerbeschreibung in `detail`. Andere Zustände liefern `null`; auch ältere fehlgeschlagene Läufe können noch keinen Code haben. In Zusammenfassungen fehlt ein nicht gesetzter Code.

Ein Lauf, den ein Trigger gestartet hat (`startedBy: "trigger:<id>"`), trägt außerdem `startedVia` — `schedule`, `webhook` oder `event` —, gelesen aus der Eingabe des Laufs selbst. So unterscheidet eine Auflistung einen geplanten Lauf von einer Webhook-Zustellung, und ein alter Lauf behält seine Art, auch wenn die Bindung später ihre Art wechselt. Läufe, die eine Person oder ein API-Schlüssel gestartet hat, lassen das Feld weg (Vertrag 2.1.0).

| Fehlergruppe | Beispiele und nächster Schritt |
| --- | --- |
| Automatisierung | `node_error`, `connector_error`, `llm_output_invalid`, `approval_rejected`, `execution_limit`, `automation_deleted`: Prüfe den betroffenen Knoten und die Ablaufspur. Korrigiere Eingabe oder Definition. Wurde eine Aktion abgelehnt, kläre den Grund vor einem neuen Lauf. |
| Modellanbieter | Etwa `credit_exhausted` oder `rate_limited`: Behebe die Ursache beim Anbieter vor dem nächsten Versuch. |
| Agentenausführung | Etwa `harness_error`, `session_gone`, `deadline` oder `budget_exceeded`: Prüfe die Fehlerbeschreibung und Grenzen des Agenten. Die vollständige Auswahl steht in OpenAPI. |

Der Code benennt die Ursache, garantiert aber keinen gefahrlosen Neustart des ganzen Laufs: Frühere Knoten können externe Systeme bereits verändert haben. `startedAt` bezeichnet die Annahme des Starts, noch vor der Übernahme durch einen Worker. Einen gesonderten Übernahmezeitpunkt gibt es nicht; `finishedAt - startedAt` enthält daher Warteschlangen- und andere Wartezeiten.

### Start ohne zusätzlichen Lauf wiederholen

Ein Start lässt sich gefahrlos wiederholen, wenn du ihn benennst: Sende `Idempotency-Key: <dein Schlüssel>`, und eine Wiederholung innerhalb von 24 Stunden — ein wiederholter Timeout, eine verlorene Antwort — antwortet mit **202**, dem Lauf, den der erste Versuch gestartet hat, und `"duplicate": true`; ein zweiter Lauf entsteht also nicht. Derselbe Schlüssel mit anderem Body ergibt **409** `IDEMPOTENCY_KEY_REUSED`. Der Schlüssel gilt je Automatisierung und URL-Projekt, und ein abgewiesener Start merkt sich nichts — derselbe Schlüssel läuft also, sobald die Ablehnung behoben ist.

Ein optionaler `Idempotency-Key` muss nach dem Entfernen äußerer Leerzeichen 1–255 druckbare ASCII-Zeichen enthalten. Ein vorhandener, aber leerer, zu langer oder anders kodierter Header ergibt `400 INVALID_HEADER`; `data.issues` nennt den Header, und nichts startet. Verwende für eine Wiederholung denselben getrimmten Wert und denselben Body. Lasse den Header nur weg, wenn du keinen Schutz vor doppelter Ausführung brauchst.

### Live- oder Mock-Ausführung wählen

`mode` ist standardmäßig `live`. Frei gestartete Live-Läufe und das Abbrechen von Läufen verlangen die Entwickler-Fähigkeit. Für Projektläufe brauchst du außerdem Bearbeitungsrechte auf ein aktives Projekt, auch mit `mode: "mock"`. Mock-Läufe verwenden deterministische Mocks; ohne Projekt genügt dafür eine Mitgliedschaft. Ein Trigger ist für den Start nicht nötig. Ohne bereitgestellte Version antwortet Tale mit **409**, sofern du nicht ausdrücklich eine gespeicherte Version für einen Mock-Lauf auswählst.

Eine unbekannte Automatisierung antwortet mit **404**. Ein Live-Lauf darf nur die deployte `version` verwenden; eine andere gespeicherte Version ergibt **409**. Teste diese mit `mode: "mock"`. Ohne Body gilt `{}`; fehlerhaftes JSON ergibt **400** und startet nichts. Definiert die Automatisierung ein `inputs`-Schema, muss die Eingabe dazu passen, bevor ein Lauf entsteht: Eine Abweichung ergibt **400** `AUTOMATION_INPUT_INVALID` mit jedem Problem unter `data.issues` (`path`, `message`), genau wie ein abgelehnter Body. `input` fällt nur auf `{}` zurück, wenn es fehlt — `null` geht als null durch, damit das Schema darüber urteilt.

### Geltungsbereich und Laufhistorie auswählen

Das Projekt in der URL bestimmt den Kontext der Aufgaben- und Dokumentwerkzeuge des Laufs. Hat die Automatisierung Projektbindungen, darf sie nur in einem dieser Projekte laufen; eine ohne Bindungen läuft in jedem Projekt, das der Aufrufer bearbeiten darf — sie zu installieren (`POST /api/v1/projects/{id}/automations/{name}`) listet sie unter diesem Projekt und grenzt sie darauf ein, ist aber keine Hürde, die eine nie gebundene Automatisierung nehmen müsste. `GET /api/v1/projects/{id}/automations/{name}/runs` liest die Historie dieses Projekts für eine Automatisierung, `GET /api/v1/projects/{id}/runs` für alle.

Listen antworten mit Zusammenfassungen — Identität, Geltungsbereich, Status und Zeiten, jede Zeile nennt den Lauf als `id` und, unter dem Namen, den der Start beantwortet hat, als `runId`, ein Wert unter beiden Namen —, die neuesten zuerst, als `{ "runs": [...], "isDone": ..., "continueCursor": ... }`: Hänge `?status=failed` an (ein oder mehrere Status, kommagetrennt), um sie einzugrenzen, `?include=input,output` (auch `trace`, `effects`, `checkpoints`), um die Felder der vollen Zeile einzubetten, die eine Zusammenfassung weglässt — eine einbettende Seite liest höchstens 25 Zeilen, ist auf 8 MiB davon begrenzt und endet vorzeitig mit `isDone: false`, wenn die nächste Zeile nicht mehr passt —, und gib `continueCursor` als `?cursor=` zurück, bis `isDone` gilt.

`GET /api/v1/runs` ist die Sicht quer über alles: jeder Lauf, den der Schlüsselbesitzer sehen darf, Organisationsläufe wie Läufe sichtbarer Projekte, jede Zeile mit ihrer `projectId`. Eine Automatisierung ohne Bindungen kannst du mit `POST /api/v1/automations/{name}/runs` ohne Projekt starten; eine gebundene Automatisierung ergibt dort **409**. `GET /api/v1/automations/{name}/runs` und `/api/v1/runs/{runId}` zeigen ausschließlich Läufe ohne Projekt. Zum Lesen, Abbrechen und Löschen eines Projektlaufs brauchst du dessen Projekt-URL. `DELETE /api/v1/projects/{id}/runs/{runId}` (oder `/api/v1/runs/{runId}`) entfernt einen beendeten Lauf — samt gespeicherter Eingabe und Ausgabe — unter der Entwickler-Fähigkeit; ein Lauf, der noch in Arbeit ist, ergibt **409** `RUN_ACTIVE`, brich ihn also zuerst ab.

## Für ein Mitglied handeln: Frage eines Laufs beantworten, Prüfung einer Aufgabe entscheiden

Ein Lauf mit `waitingFor: "ask"` wartet auf eine Person; eine Aufgabe in `in_review` kann auf eine Person oder einen benannten Agenten warten. Diese beiden REST-Endpunkte reichen die Handlung einer Person aus einer anderen Anwendung weiter und nennen sie als `actor`. Tale hält die Person fest, nicht den Schlüssel. Beide Endpunkte brauchen API-Vertrag 1.16.0; Vertrag 3.11.0 ergänzt die ausdrückliche Ablehnung einer menschlichen Freigabe, solange das Review einem Agenten gehört.

### Die Frage beantworten, auf die ein Lauf wartet

`GET /api/v1/projects/{id}/runs/{runId}/ask` liefert die offene Frage als `PendingAsk` — den Satz, optional ein strukturiertes `questions`-Set, den fragenden Knoten und die Frist `expiresAt` — oder `ask: null`, wenn niemand gefragt ist. Zum Lesen genügt derselbe Zugriff wie zum Lesen des Laufs.

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/projects/<projectId>/runs/<runId>/ask" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "ask": { "askId": "...", "question": "...", "expiresAt": 1758210000000, "taskId": "..." } }
```

Die Antwort geht an `POST /api/v1/projects/{id}/runs/{runId}/asks/{askId}`. Tale speichert sie, setzt den Lauf in derselben Transaktion fort und stellt die Antwort als eigenen Kommentar der antwortenden Person auf die Zeitleiste der Aufgabe. Bei einem `questions`-Set sendest du pro Frage eine Zeile, so wie es die App tut: `<Frage> → <gewählte Option>; <eingetippter Text> (in their own words)`.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/runs/<runId>/asks/<askId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "answer": "Im Februar buchen.", "actor": { "email": "reviewer@example.com" } }'
# → 200 { "ok": true, "askId": "...", "runId": "...", "answeredBy": "<userId>", "actorUserId": "<userId>", "taskId": "..." }
```

Ein Projektlauf verlangt Schreibzugriff auf ein aktives Projekt, ein Organisationslauf die Mitgliedschaft. Ohne `actor` antwortet der Schlüssel als er selbst, und `answeredBy` lautet `api-key:<userId>`. Eine bereits beantwortete oder geschlossene Frage liefert **409** `HUMAN_ASK_NOT_PENDING`, eine abgelaufene **409** `HUMAN_ASK_EXPIRED` — der Lauf scheitert dann mit `failureCode: "ask_expired"` — und eine Frage, die nicht dieser Lauf gestellt hat, **404** `HUMAN_ASK_NOT_FOUND`. Eine leere Antwort liefert **400** `EMPTY_ANSWER`.

### Die Prüfung einer Aufgabe entscheiden

`GET /api/v1/projects/{id}/tasks/{taskId}/review` liefert den Aufgabenstatus und das ausstehende `TaskReview`, sonst `review: null`. Seit Vertrag 3.11.0 ist `reviewer` entweder `{kind: "user", userId}`, `{kind: "agent", agentId}` oder `null`. `implementationAgentId` benennt den tatsächlichen Agenten des Umsetzungslaufs, `evidenceRevision` den aktuellen lokalen Belegstand; beide können `null` sein. `requestedFor` bleibt das Kompatibilitätsfeld für Personen und ist bei einem Agenten `null`. `agentSlug` ist Anzeigetext, keine Identität des Umsetzungslaufs. Ein `POST` auf denselben Pfad reicht eine menschliche Entscheidung weiter und verlangt `actor`:

Vertrag 3.12.0 ergänzt `agentReviewBlockedReason`: `null`, `reviewer_unavailable`, `permission_missing`, `source_required`, `source_changed`, `self_review`, `human_policy` oder `policy_unavailable`. Dieselbe Diagnose steht im nativen `task_get.pendingReview`. Sie folgt aus der aktuellen Berechtigung und Quelle, ist kein eigener Review-Status und überträgt keine Prüfung automatisch. Einreichungen ohne nativen Quelllauf und neue Reviews unter einer Richtlinie für menschliche Unabhängigkeit oder Kompetenzen folgen der menschlichen Prüferkette; bereits einem Agenten zugewiesene Reviews erfordern eine ausdrückliche Übergabe.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/tasks/<taskId>/review" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "decision": "approve", "actor": { "email": "reviewer@example.com", "userId": "<userId>" } }'
# → 200 { "task": { "id": "...", "status": "done" }, "decision": "approve", "approvalId": "...", "actorUserId": "<userId>" }
```

`approve` entspricht dem Verschieben nach Erledigt auf dem Board: Es gelten das Recht des Mitglieds, die Aufgabe zu ändern (als Redakteur oder höher, oder weil es sie angelegt hat oder sie ihm zugewiesen ist), und die `review_policy` der Organisation genau wie dort (**403** `REVIEW_INDEPENDENT_REVIEWER_REQUIRED` oder `REVIEW_COMPETENCE_REQUIRED`, wenn die Richtlinie die Person ablehnt), die Prüfung wird als vom Mitglied freigegeben festgehalten, und die Aufgabe wird `done`; eine Aufgabe mit offenen Teilaufgaben liefert **409** `TASK_HAS_OPEN_SUBTASKS`. `request_changes` braucht `comment` und `workflowSlug`: Die Prüfung wird zurückgezogen, der Kommentar landet auf der Zeitleiste, und der Workflow startet erneut auf der Aufgabe und liest den Kommentar als Rückmeldung; die Antwort nennt die `runId` zum Pollen, mit `started: false`, wenn ein laufender Lauf weiterverwendet wurde. Eine Aufgabe, die nicht in Prüfung ist, liefert **409** `TASK_NOT_IN_REVIEW`. Jede Entscheidung wird als `task.review_relayed` protokolliert, mit dem Mitglied und dem Schlüssel, der für es gehandelt hat.

Auch ein menschliches `approve` liest die aktuelle Richtlinie strikt. Eine ungültige oder nicht lesbare `review_policy` liefert **409** `TASK_REVIEW_POLICY_UNAVAILABLE`, selbst nach einer ausdrücklichen Übergabe vom Agenten an eine Person. Es wird weder eine Freigabe noch ein Abschluss gespeichert. Stelle eine gültige Konfiguration wieder her und lies das Review erneut. Eine tatsächlich nicht vorhandene optionale Richtlinie bleibt zulässig. Diese Ablehnung ergänzt keine Richtlinienfreigabe für `request_changes` oder das Zurückziehen eines Reviews.

Die Freigabe eines einem Agenten zugewiesenen Reviews antwortet mit **409**, `TASK_AGENT_REVIEW_REQUIRED`. Ein Redakteur muss das ausstehende Review zuerst ausdrücklich [an eine berechtigte Person übertragen](https://docs.tale.dev/de/platform/projects/tasks#transfer-review). Erst danach kann dieser Endpunkt die menschliche Freigabe annehmen. Gib nicht den Agenten als `actor` aus und behandle ein fehlendes menschliches `requestedFor` nicht als Review ohne Zuständigkeit.

### Das Mitglied benennen, für das gehandelt wird

`actor.email` benennt das Mitglied über seine E-Mail-Adresse. Tale löst sie in der Organisation nach derselben Regel auf wie den Benachrichtigungsexport: genau eine aktive Mitgliedschaft mit verifizierter Adresse. Kein solches Mitglied liefert **404** `ACTOR_NOT_FOUND`, zwei liefern **409** `ACTOR_AMBIGUOUS`, eine nicht verifizierte Adresse **403** `ACTOR_UNVERIFIED`, eine deaktivierte Mitgliedschaft **403** `ACTOR_DISABLED`. Jede Antwort nennt die aufgelöste `actorUserId`; pinne sie bei späteren Aufrufen als `actor.userId`. Eine Adresse, die inzwischen zu einem anderen Konto gehört, liefert dann **409** `ACTOR_REBOUND`, statt für den neuen Inhaber zu handeln. Ein Mitglied, das das Projekt nicht sehen darf – oder an der Review-Tür seine Aufgabe nicht ändern darf –, liefert **403** `ACTOR_FORBIDDEN`; der Zugriff des Schlüsselinhabers wird zuerst geprüft, dieser Code spricht also immer vom Handelnden.

Einen `actor` zu nennen ist ein eigenes Recht. Ein Inhaber- oder Admin-Schlüssel hat es durch seine Rolle; jeder andere Schlüsselinhaber braucht die Berechtigung `tale:rest.act-as`, die genau wie die Exportberechtigung in [Export ohne Admin-Rolle delegieren](https://docs.tale.dev/de/develop/api-reference#export-ohne-admin-rolle-delegieren) erteilt und entzogen wird, mit `"competence":"tale:rest.act-as"` im Freigabetext. `GET /api/v1/me` meldet sie als `capabilities.actAs`; ein ohne dieses Recht gesendeter `actor` liefert **403** `ROLE_FORBIDDEN`, bevor ein Mitglied nachgeschlagen wird. Was die weitergereichte Handlung darf, entscheiden weiterhin die eigenen Berechtigungen des Mitglieds.

## Eine Nachricht senden, dann den Turn pollen

Projektchats folgen ebenfalls dem Ablauf 202, dann Statusabfrage. Wähle ein Projekt, das du lesen darfst, lege einen Thread an, sende eine Nachricht, frage den Status ab und lies die Antwort:

### Aufrufbares Modell auswählen

Rufe vor dem Senden die Modelle ab. Jeder Eintrag trägt, was ein Client zum Auswählen braucht — `contextWindow`, `maxOutputTokens`, `capabilities` (`tools`, `vision`, `reasoning`), `pricing`, wenn der Katalog einen Preis kennt, `tags` — und `default: true` markiert die Wahl der Organisation für diesen Schlüsselbesitzer; es erscheint nur, wenn die Organisation ein Standardmodell festgelegt hat, warte also nicht darauf. Übernimm `id` als `model`; ergänze `providerSlug`, wenn dieselbe ID unter mehreren Anbietern gelistet ist. Die Liste berücksichtigt die Modellzugriffsregeln der Organisation und enthält nur Modelle, die REST direkt aufrufen kann. Ist sie leer, steht dem Schlüsselbesitzer kein Chat-Modell zur Verfügung.

`maxOutputTokens` fehlt, wenn der Katalog keine Obergrenze nennt. Die Senderoute prüft dann keine Kataloggrenze. Dein Client muss das fehlende Feld beim Lesen der Modellliste akzeptieren.

`capabilities` und `tags` beschreiben das Modell, nicht das, was diese Oberfläche ihm schicken kann: Das Senden per REST ist reiner Text (`content`), ein `vision`-Modell liest hier also nur dann ein Bild, wenn der Thread aus der App mit einem Bildanhang fortgesetzt wurde — eine Data-URI, die in `content` eingefügt wird, erreicht das Modell als Text und wird als Text beantwortet, und nichts in Anfrage oder Antwort kennzeichnet das; Bildeingabe über REST gibt es in dieser Version nicht.

Die Liste ist der konfigurierte Katalog der Organisation, kein Versprechen des Anbieterkontos: Ein Modell, das der Tarif des Anbieters nicht abdeckt, schließt ein Operator über die Modell-Allowlist der Zugangsdaten in den Einstellungen aus. Das Paar wird beim Senden geprüft, direkt an der Schnittstelle: Eine ID, die die Liste nicht kennt, ergibt **400**, `CHAT_MODEL_UNKNOWN`; eine ID, die mehrere Anbieter bedienen, ohne dass einer genannt ist, **400**, `CHAT_MODEL_AMBIGUOUS` mit den Kandidaten in `data.providers`; ein `providerSlug`, den die Liste nicht kennt, **400**, `CHAT_PROVIDER_UNKNOWN`; einer, der das gewählte `model` nicht bedient, **400**, `CHAT_MODEL_NOT_ON_PROVIDER`.

Die 202 nennt den Anbieter, auf dem der Turn läuft — er weicht nie stillschweigend auf einen anderen aus.

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/models" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# Kein Modell verfügbar → 200 { "models": [] }
```

```bash
# 1. Ein eigener Thread
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/threads" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" -d '{}'
# → 201 { "id": "<threadId>" }

# 2. Nachricht senden — auf dieser API ist das Modell immer explizit, nie automatisch gewählt
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/threads/<threadId>/messages" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Fasse mir dieses Quartal zusammen.", "model": "<model-id>", "providerSlug": "<provider-slug>" }'
# → 202 { "threadId": "...", "status": "accepted", "model": "...", "providerSlug": "...", "messageId": "<assistantMessageId>", "poll": "/api/v1/projects/<projectId>/threads/<threadId>/generation" }

# 3. Bis idle pollen, dann lesen
curl -sS --compressed "https://your-host.example.com/api/v1/projects/<projectId>/threads/<threadId>/generation" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "status": "queued", "messageId": "..." } … dann { "status": "streaming", "messageId": "...", "text": "Das Quartal…", "textOffset": 0, "textLength": 12, "reasoning": "", "reasoningOffset": 0, "reasoningLength": 0, "cancelRequested": false, "updatedAt": 1774... } … dann { "status": "idle", "lastMessageId": "<assistantMessageId>", "lastStatus": "complete" }

# 4. Die Antwort über die ID lesen, die die 202 genannt hat
curl -sS "https://your-host.example.com/api/v1/projects/<projectId>/threads/<threadId>/messages/<assistantMessageId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "id": "<assistantMessageId>", "role": "assistant", "status": "complete", "finishReason": "stop", "parts": [ … ], "usage": { … }, … }
```

### Die angenommene Nachricht verfolgen

Angenommene Chatnachrichten teilen sich eine Warteschlange für alle Organisationen und Schlüssel der Instanz; ältere Aufträge kommen zuerst. Der Hintergrund-Worker verarbeitet pro Durchgang bis zu `WORKER_CONCURRENCY` Antwortläufe, standardmäßig 5. Sein nächster Durchgang beginnt erst, wenn der aktuelle abgeschlossen ist. Eine angenommene Nachricht kann deshalb hinter Aufträgen anderer Clients warten. Die API liefert weder Warteschlangenposition noch voraussichtlichen Startzeitpunkt.

Bewahre die `messageId` aus der `202`-Antwort auf. Unter dieser ID wird die Assistentenantwort gespeichert. Frage die Generierung alle zwei bis fünf Sekunden ab und werte ihren Zustand aus:

| Generierungsstatus | Bedeutung und nächster Schritt |
| --- | --- |
| `queued` | Angenommen, wartet auf einen Worker; weiter abfragen. Bis ein Worker den Lauf öffnet, ist diese Abfrage die einzige Sicht darauf: `GET .../messages` listet den Lauf noch nicht (die Seite liest sich ohne ihn als vollständig), und `.../messages/{messageId}` kann für die vom Senden genannte ID **404** antworten |
| `streaming` | Der Anbieter erzeugt die Ausgabe; `text` und `reasoning` enthalten den bisherigen Zwischenstand |
| `idle`, passende `lastMessageId` | Dein Antwortlauf ist beendet; `lastStatus` nennt das Ergebnis |
| `idle`, andere `lastMessageId` | Die Zusammenfassung gehört zu einer anderen Nachricht; lies deine gespeicherte Nachrichten-ID direkt |

Lies das Ergebnis unter `GET /api/v1/projects/{id}/threads/{threadId}/messages/{messageId}`. Mit `GET .../messages?order=desc` blätterst du den Verlauf von der neuesten Nachricht aus. Ein Cursor bleibt an seine ursprüngliche Sortierrichtung gebunden. Ein späterer Antwortlauf kann die Zusammenfassung ändern: Eine andere ID beweist deshalb nicht, dass dein früherer Aufruf nie ausgeführt wurde.

Setze ein Zeitlimit je Statusanfrage und eine separate Gesamtdauer für deinen Client; 30 Sekunden je gewöhnlicher Abfrage sind ein sinnvoller Ausgangspunkt. Der Server hat keine feste Gesamtdauer für einen Antwortlauf. Nach 180 Sekunden ohne Anbieteraktivität bricht er die Anfrage ab. Jedes empfangene Byte, auch Reasoning, setzt diese Uhr zurück. Hohe Denktiefe kann den Lauf daher ohne sichtbaren Antworttext aktiv halten. Wenn du ihn nicht mehr brauchst, rufe `DELETE .../generation` auf, statt nur die Abfrageschleife zu beenden.

Für inkrementelle Updates sende die bisherige `textLength` als `since` und `reasoningLength` als `reasoningSince`. Die Einheit sind UTF-16-Code-Units — JavaScripts `String.length`, ein Emoji zählt zwei; keine Codepunkte —, gib also die Längen zurück, die der Poll geantwortet hat, statt selbst Zeichen zu zählen. `textOffset` und `reasoningOffset` zeigen den Beginn der zurückgegebenen Ausschnitte: der Wert, den du gesendet hast, eins darunter, wenn er ein Surrogatpaar zerschnitten hätte (der Ausschnitt schickt das ganze Zeichen dann noch einmal), oder 0, wenn eine abgeschlossene Tool-Runde den Ausgabestrom zurückgesetzt hat. Setze nach einer Regel zusammen, `held = held.slice(0, textOffset) + text`, und keiner der drei Fälle braucht eine eigene Behandlung.

Ging die Sendeantwort verloren, lies zuerst `.../generation`, bevor du erneut sendest. `queued` und `streaming` kennzeichnen einen aktiven Antwortlauf. Bei `idle` prüfe die neueste Assistentenantwort oder suche die neueste Benutzernachricht mit deinem `content`. Ohne gespeicherte Nachrichten-ID darfst du eine andere aktuelle Antwort nicht einfach dem verlorenen Aufruf zuordnen.

### Eine Nachricht sicher erneut senden

Sende einen stabilen `Idempotency-Key` für die Nachricht. Eine Wiederholung innerhalb von 24 Stunden liefert dieselbe `202`-Antwort einschließlich `messageId` und zusätzlich `duplicate: true`. Es wird kein zweiter Antwortlauf gestartet oder abgerechnet. Derselbe Schlüssel mit anderem Body führt zu `409 IDEMPOTENCY_KEY_REUSED`.

Der Schlüssel gilt für den Thread und das Projekt in der URL. Ein abgelehnter Aufruf, etwa wegen eines laufenden Antwortlaufs, wird nicht gespeichert. Du kannst denselben Schlüssel erneut verwenden, sobald die Generierung `idle` meldet.

Ein optionaler `Idempotency-Key` muss nach dem Entfernen äußerer Leerzeichen 1–255 druckbare ASCII-Zeichen enthalten. Ein vorhandener, aber leerer, zu langer oder anders kodierter Header ergibt `400 INVALID_HEADER`; `data.issues` nennt den Header, und nichts startet. Verwende für eine Wiederholung denselben getrimmten Wert und denselben Body. Lasse den Header nur weg, wenn du keinen Schutz vor doppelter Ausführung brauchst.

### Assistentenverhalten und Token-Grenzen verstehen

Ein Antwortlauf, technisch ein Turn, umfasst die gesamte Verarbeitung einer angenommenen Nachricht einschließlich Modellrunden und Tool-Aufrufen. REST-Chat verwendet den integrierten Arbeitsbereichsassistenten mit seinen Anweisungen, Sicherheitsregeln und drei Recherche-Tools. Diese belegen ungefähr 3.000 Prompt-Tokens je Modellrunde und zählen zu `usage.inputTokens`. Mit Tools kann ein Lauf bis zu fünf Runden umfassen, deren vollständiger Prompt jeweils abgerechnet wird. Wünsche nach Arbeitsergebnissen wie Dokumenten oder Berichten verweist der Assistent an Aufgaben.

Projekt-Threads können Dateien dieses Projekts und die Wissensdatenbank der Organisation abrufen, aber keine Dateien anderer Projekte. Threads ohne Projekt greifen nur auf die Wissensdatenbank zu. Ob eine Suche nötig ist, entscheidet der Assistent anhand der Frage. Ein Dateiname oder eine ausdrückliche Suchanweisung verdeutlicht dein Ziel; kein Anfragefeld erzwingt jedoch einen Suchaufruf.

| Feld | Verhalten |
| --- | --- |
| `reasoningEffort` | `low`, `medium`, `high`, `extra` oder `max`; ohne `capabilities.reasoning` ignoriert |
| `maxOutputTokens` | Gesamtbudget des Antwortlaufs über alle Modellrunden; höchstens die Modellgrenze aus `/models` |

Ein zu hohes Ausgabebudget ergibt `400 INVALID_BODY` mit der Obergrenze. Jede Runde erhält nur das Restbudget; ist es aufgebraucht, startet keine weitere. Reasoning-Tokens zählen zu diesem Budget und zu `usage.outputTokens` und werden zum Preis für Ausgabe-Tokens berechnet. Sie können die gesamte Grenze verbrauchen: Dann endet ein berechneter Antwortlauf mit `complete` und `finishReason: "length"`, aber ohne Antworttext. Erhöhe das Ausgabebudget oder reduziere die Denktiefe, wenn deine Aufgabe eine sichtbare Antwort benötigt.

Eine Ausnahme gilt für Anbieter mit einem ausdrücklichen Denkbudget nach dem Extended-Thinking-Verfahren von Anthropic: Werte unter 2.048 werden auf 2.048 angehoben, damit mindestens 1.024 Tokens fürs Denken und ebenso viele für die Antwort verfügbar sind. Modelle mit einer Denktiefenstufe, darunter GLM und DeepSeek, haben diese Untergrenze nicht.

Lies `finishReason`, statt nur `status: "complete"` oder die Token-Zahl zu prüfen. Mögliche Werte sind `stop`, `length`, `tool-calls`, `content-filter`, `cancelled` und `other`; ohne Anbieterangabe fehlt das Feld. Erreicht eine Runde die Längengrenze, wird keiner ihrer Tool-Aufrufe ausgeführt, auch wenn einzelne Argumente vollständig sind. Jeder zurückgehaltene `tool-result` hat `status: "invalid_args"`; seine Meldung unterscheidet vollständige von abgeschnittenen Argumenten. Prüfe daher Abbruchgrund und Tool-Ergebnisse, selbst wenn der abschließende Text vollständig wirkt.

Eine leere Antwort oder ein Abbruch vor dem ersten Text hat keinen Textteil. `parts` kann leer sein oder nur Reasoning- und Tool-Teile enthalten. Prüfe auf tatsächlichen Text, bevor du eine Antwort anzeigst oder exportierst.

Threads, Nachrichten und Generierungsstatus sind nur für ihren Besitzer sichtbar. Eine gemeinsame Projektmitgliedschaft gibt keinen Einblick in fremde Chats. `GET /api/v1/projects/{id}/threads` listet deine Threads; `GET /api/v1/projects/{id}/threads/{threadId}` liest einen davon.

### Sprache, Status, Verbrauch und Nachrichtenteile lesen

`content` wird getrimmt. Ein leerer Prompt — nichts als Leerraum und unsichtbare Formatzeichen wie Leerzeichen ohne Breite — führt ohne Antwortlauf zu `400` (Markdown, das als nichts gerendert wird, etwa ein leerer Codeblock, ist trotzdem ein Prompt). Mit `locale` kannst du einen BCP-47-Sprachcode wie `de` oder `en-GB` angeben. Er weist den Assistenten über System- und Nachrichtenanweisungen an, in dieser Sprache zu antworten. Verbindliche Organisationsanweisungen haben Vorrang. Ohne `locale` nutzt der Assistent die Sprache des Prompts.

Die Sprache ist eine Anweisung an das Modell, keine validierte Ausgabegarantie. Gerade bei kurzen Prompts mit aktiviertem Reasoning kann die Antwort abweichen. Es gibt dafür kein Fehlerkennzeichen. Wenn eine bestimmte Sprache zwingend ist, prüfe die Antwort vor ihrer Verwendung.

| Nachrichtenstatus | Bedeutung |
| --- | --- |
| `pending` | Assistentenzeile mit leeren `parts` vorhanden; die Generierung nennt ihre `messageId` |
| `complete` | Antwortlauf beendet; `finishReason` auf Längengrenzen oder andere Abbruchgründe prüfen |
| `cancelled` | Gestoppt, mit bereits eingetroffenen Teilinhalten |
| `failed` | Fehlgeschlagen, mit `error` und gegebenenfalls `errorCode` |

| Verbrauchsfeld | Bedeutung |
| --- | --- |
| `inputTokens`, `outputTokens` | Gemeldete Eingabe- und Ausgabetokens |
| `reasoningTokens` | Anteil der Ausgabetokens fürs Denken; fehlend bedeutet nicht gemeldet, `0` bedeutet ausdrücklich null |
| `cachedInputTokens` | Anteil der Eingabetokens aus dem Cache des Anbieters |
| `costEstimateCents` | Katalogschätzung in US-Cent mit Nachkommastellen, auf ein Millionstel Cent gerundet; fehlt ohne Katalogpreis |
| `estimated: true` | Von der Plattform geschätzte Werte, meist wenn Anbieterzahlen durch einen Abbruch oder einen Fehler mitten im Stream verloren gingen |
| `stepLimitHit: true` | Die Tool-Schleife hat ihr vollständiges Rundenbudget verbraucht |

Die Verbrauchserfassung bucht dieselbe Katalogschätzung. Eingaben aus dem Cache werden zum normalen Eingabepreis angesetzt; bei solchen Aufrufen ist die Schätzung daher eine Obergrenze. Geschätzter Verbrauch berücksichtigt den vollständigen Prompt einschließlich der Assistenten-Tools. Auch ein fehlgeschlagener Lauf trägt `usage` für das, was er verbraucht hat: seine abgeschlossenen Modellrunden und, falls der Anbieter die Anfrage bereits angenommen hatte, die fehlgeschlagene Runde – geschätzt, wo der Anbieter keine Zähler gemeldet hat. Eine Runde, die der Anbieter abgelehnt hat, zählt nicht mit, ob er mit einem HTTP-Fehlerstatus geantwortet oder eine Ablehnung wie ein Rate-Limit gemeldet hat, bevor eine Antwort oder ein positiver Verbrauch gemeldet wurde. Wird schon die erste Runde abgelehnt, fehlt `usage`.

`parts` ist eine geordnete Liste mit dem Unterscheidungsfeld `type`: `text`, `reasoning`, `attachment`, `tool-call`, `tool-result` oder `approval`. OpenAPI beschreibt jede Variante als eigenes benanntes Schema (`TextPart`, `ReasoningPart`, `AttachmentPart`, `ToolCallPart`, `ToolResultPart`, `ApprovalPart`) hinter einem `type`-Diskriminator mit explizitem Mapping, ein generierter Client bekommt also eine Klasse je Art. Behandle künftig unbekannte Varianten als undurchsichtige Daten, statt die gesamte Nachricht abzulehnen.

Ein `reasoning`-Teil enthält Überlegungen, nicht die abschließende Antwort. Er kann dem Modell übergebene Anweisungen wiedergeben, darunter Organisations- und Projektanweisungen sowie Vertrauensregeln für abgerufene Inhalte. Zeige ihn getrennt und nur Personen, die diese Anweisungen sehen dürfen.

### Thread-Kontext und Zugriff beachten

Für persönliche Chats ohne Projekt verwendest du `/api/v1/threads` sowie die zugehörigen Detail-, Nachrichten- und Statuspfade. Projektthreads sind dort nicht erreichbar. Ein falsches Projekt in der URL ergibt **404**. Beide Chatarten verwenden den eingebauten Assistenten; `projectId`, `agentSlug` oder `agentId` beim Anlegen oder Senden ergibt **400**. Projektleser einschließlich Mitgliedern dürfen Threads anlegen und Nachrichten senden. Ein archiviertes Projekt verweigert diese Aufrufe mit **403**.

Ein archivierter Thread verweigert eine Nachricht mit **409**, `CHAT_THREAD_ARCHIVED`, ein Sandbox-Thread mit **409**, `CHAT_THREAD_NOT_DIRECT`, und ein Thread, dessen Turn noch läuft — oder dessen angenommenes Senden noch in der Warteschlange steht —, mit **409**, `CHAT_TURN_IN_PROGRESS`; nichts wird eingereiht, und der laufende Turn behält seine `messageId`. Den letzten wiederholst du, sobald die Abfrage idle meldet, die anderen beiden nie.

### Thread umbenennen, archivieren, löschen oder stoppen

Den Lebenszyklus steuerst du über dieselben URLs. `PATCH .../threads/{threadId}` mit `{ "archived": true }` archiviert einen Thread, `false` holt ihn zurück (ein Thread, dessen Turn läuft oder dessen Senden noch wartet, weist das Archivieren wie das Löschen mit **409** `CHAT_TURN_IN_PROGRESS` ab — brich zuerst ab; Zurückholen und Umbenennen bleiben mitten im Turn offen), und `{ "title": "Q3 review" }` benennt ihn um (sende mindestens eines von beiden; ein Titel wird getrimmt und hat 1–120 Zeichen, beim Anlegen wie beim Umbenennen); einen ohne Titel angelegten Thread benennt der Assistent nach seiner ersten Nachricht, und das `title` des Threads trägt den Namen in beiden Fällen.

Archivieren stempelt `archivedAt` auf den Thread und lässt `updatedAt` in Ruhe — `updatedAt` ist die letzte Nachrichtenaktivität, ein Abgleich, der darauf schaut, muss also `archived` und `archivedAt` lesen, um ein Archivieren oder Zurückholen zu sehen. `DELETE .../threads/{threadId}` verschiebt ihn in den Papierkorb (**409**, `CHAT_TURN_IN_PROGRESS`, solange ein Turn läuft oder ein Senden noch in der Warteschlange steht); `DELETE .../threads/{threadId}/generation` bittet den laufenden Turn zu stoppen — **202** `{ "status": "cancelling", "messageId": "..." }`, danach pollst du bis idle; die gestoppte Antwort landet als `status: "cancelled"` mit dem, was schon gestreamt war.

Ein Senden, das noch in der Warteschlange steht (der Poll sagt `queued`), wird genauso gestoppt: **202** mit der Antwort, die die 202 des Sendens versprochen hat, das Modell wird nie aufgerufen, und diese Antwort landet als `cancelled` mit leeren `parts`. Läuft nichts und wartet nichts, **404**, `CHAT_TURN_NOT_RUNNING` — sein `data.lastMessageId` und `data.lastStatus` nennen die neueste Assistenten-Nachricht, wie ein idle-Poll es tut, ein Stopp, der das Rennen gegen ein schnelles Modell verloren hat, liest sich also ohne zweiten Aufruf als „die Antwort ist schon da". Ein archiviertes Projekt verweigert alle drei mit **403**.

### Modell- und Zugriffsfehler beheben

Ein Modellfehler kann als Assistenten-Nachricht mit lesbarem `error` und, wenn verfügbar, `errorCode` erscheinen. Die Modellliste ist der konfigurierte Katalog der Organisation, kein Versprechen des Anbieterkontos — zwei Codes meinen deshalb das Konto, nicht die Anfrage: `credit_exhausted` (Guthaben aufgebraucht) und `model_not_entitled` (der Tarif des Anbieters enthält dieses Modell nicht). `error` ist die Antwort des Anbieters selbst, mit seinem HTTP-Status davor — eine **429** des Anbieters kann als `model_not_entitled` eingestuft werden, wenn der Tarif und nicht die Rate das Modell verweigert hat —, verzweige also auf `errorCode`, nie auf den Satz.

Wähl ein anderes Modell oder bring das Konto in Ordnung — Warten ändert nichts, und keiner von beiden ist ein `rate_limited`. Vor dem Öffnen des Turns prüft der Worker den angenommenen Thread und den Projektzugriff erneut. Wechselt der Thread während der Wartezeit das Projekt oder entfällt der Zugriff, führt er den Turn nicht aus und schreibt auch keine Fehlermeldung in den neuen Kontext.

## Kompatible Modell-Endpunkte {#model-endpoints}

Drei Routen beantworten die Schnittstellen von OpenAI und Anthropic für die Modelle der Organisation. So kann ein SDK oder ein Coding-Tool, das eine der beiden spricht, Tale als Modellanbieter verwenden (Vertrag 3.7.0). Sie sind ein reiner Zugang zum Modell: Die Anfrage geht an das Modell, das sie nennt, und die Antwort kommt so zurück, wie das Modell sie geschickt hat, ohne Assistent, Thread oder Tool von Tale dazwischen. Die Routen sind ausgeschaltet, bis ein Admin **Modell-Endpunkte für API-Schlüssel** einschaltet. Danach dürfen Inhaber, Admins und Entwickler sie aufrufen; jedes andere Mitglied braucht eine gültige `tale:models.api`-Zuweisung. [Tale aus deinem Editor oder einem Skript nutzen](https://docs.tale.dev/de/develop/use-tale-from-your-editor#model-endpoints) beschreibt die Einrichtung der Clients.

| Route | Bedient |
| --- | --- |
| `POST /api/v1/openai/chat/completions` | OpenAI Chat Completions, als Server-Sent Events gestreamt oder vollständig beantwortet, mit Tools und `tool_calls`, Bildern und Dateien. Ein Stream endet mit `data: [DONE]`; den abschließenden Chunk mit dem Verbrauch gibt es nur, wenn `stream_options.include_usage` ihn anfordert. |
| `GET /api/v1/openai/models` | Die Modell-IDs, die der Schlüsselinhaber aufrufen darf, als OpenAI-Liste: `owned_by` ist der Slug des Anbieters, `created` ist immer `0`. |
| `POST /api/v1/anthropic/v1/messages` | Anthropic Messages, gestreamt oder vollständig, mit Tools, Bildern und Dokumenten. `anthropic-version` und `anthropic-beta` werden weitergereicht. |

Die Authentifizierung ist dieselbe wie bei jeder anderen Operation: `Authorization: Bearer <key>` und, bei mehreren Mitgliedschaften, `X-Organization-Slug`. Die Routen teilen sich das allgemeine Ratenbudget und antworten wie alle anderen mit `X-Request-Id`. Sie ignorieren Query-Parameter, auch das `?beta=true` eines Anthropic-SDKs, und nehmen Bodys bis 32 MiB an. Tale liest die Felder, die es prüft, und reicht den Rest des Bodys unverändert weiter; die strengen Body- und Query-Regeln der übrigen Operationen gelten hier nicht.

`model` hat an beiden Schnittstellen die Form `<providerSlug>/<modelId>`: der Slug des Anbieters, ein Schrägstrich und die ID des Modells im Katalog dieses Anbieters, etwa `openrouter/anthropic/claude-sonnet-4.6`. Da eine Katalog-ID Schrägstriche enthalten kann, ist der Anbieter der Teil vor dem ersten Schrägstrich. Antworten nennen die ID, die die Anfrage gesendet hat. Aufrufen darf der Schlüsselinhaber die Chatmodelle der Organisation, die Zugangsdaten mit API-Schlüssel oder Umgebungsvariable bereitstellen, eingeschränkt durch die erlaubten Modelle dieser Zugangsdaten und seinen Modellzugriff. Modelle hinter Abonnement-Zugangsdaten und Anbieter mit einem Endpunkt je Zugangsdaten-Eintrag, etwa Azure, werden nicht bedient. `GET /api/v1/models` nennt für jedes dieser Modelle Kontextfenster, Fähigkeiten und Preise, unter demselben `providerSlug` und derselben `id`.

Jede Anfrage unterliegt dem Modellzugriff des Schlüsselinhabers, wird gegen jede Budgetgrenze geprüft, die für ihn, seine Teams, die Organisation und den Schlüssel gilt, und unter der Person und dem Schlüssel verbucht. Die Eingabe-Guardrails der Organisation prüfen jeden Text der Anfrage, bevor sie weitergeht; die Antworten werden nicht gefiltert. Eine Person und jeder Schlüssel dürfen acht Anfragen gleichzeitig laufen haben.

### Eine Ablehnung im Format der Schnittstelle lesen

Jede Ablehnung auf diesen Routen, auch die zu Authentifizierung, Organisation, Ratenlimit und Body-Größe, kommt im Fehlerformat der Schnittstelle, sodass ein SDK des Anbieters sie wie eine eigene liest. `code` enthält den stabilen Code von Tale. Auf den OpenAI-Routen:

```json
{ "error": { "message": "The model endpoints are not enabled for this organization. An admin turns them on under Settings → Governance → Models → Model access.", "type": "permission_error", "param": null, "code": "MODEL_API_DISABLED" } }
```

Auf der Anthropic-Route, die zusätzlich den Header `request-id` setzt:

```json
{ "type": "error", "error": { "type": "permission_error", "message": "The model endpoints are not enabled for this organization. An admin turns them on under Settings → Governance → Models → Model access.", "code": "MODEL_API_DISABLED" }, "request_id": "<X-Request-Id>" }
```

| Status | `code` | Bedeutung |
| --- | --- | --- |
| **403** | `MODEL_API_DISABLED` | Die Organisation hat die Endpunkte nicht eingeschaltet. |
| **403** | `MODEL_API_FORBIDDEN` | Die Rolle des Schlüsselinhabers darf sie nicht aufrufen, und er hat keine gültige `tale:models.api`-Zuweisung. |
| **403** | `MODEL_API_MODEL_FORBIDDEN` | Der Modellzugriff der Organisation sperrt das Modell für den Schlüsselinhaber. |
| **404** | `MODEL_API_MODEL_UNKNOWN` | Kein Modell, das der Schlüsselinhaber aufrufen darf, hat diese ID; `GET /api/v1/openai/models` listet sie. |
| **400** | `MODEL_API_VISION_UNSUPPORTED` | Die Anfrage enthält Bilder, und das Modell liest keine. |
| **400** | `MODEL_API_TOOLS_UNSUPPORTED` | Die Anfrage bietet Tools an, und das Modell nimmt keine an. |
| **400** | `MODEL_API_VENDOR_TOOL_UNSUPPORTED` | Die Anfrage lässt ein Tool vom Modellanbieter selbst ausführen: bei OpenAI `web_search_options` oder ein Tool, dessen Typ nicht `function` oder `custom` ist; bei Anthropic Websuche, Web-Abruf, Codeausführung, ein MCP-Toolset, `mcp_servers` oder `container`. |
| **400** | `MODEL_API_GUARDRAIL_BLOCKED` | Eine Eingabe-Guardrail hat einen Text der Anfrage blockiert; an das Modell wurde nichts gesendet. |
| **403** | `MODEL_API_GUARDRAIL_UNSUPPORTED` | Der PII-Schutz der Organisation tokenisiert, und das lässt sich bei einer weitergereichten Antwort nicht umsetzen. |
| **503** | `MODEL_API_GUARDRAIL_UNAVAILABLE` | Ein Moderationsschritt ist unter einer Fail-closed-Richtlinie fehlgeschlagen, oder eine Guardrail-Einstellung lässt sich nicht lesen. Versuche es später erneut. |
| **413** | `MODEL_API_TEXT_TOO_LARGE` | Eine Guardrail ist aktiv, und die Anfrage enthält mehr als 2 MB Text. |
| **429** | `BUDGET_EXCEEDED` | Eine Budgetgrenze, die für den Schlüsselinhaber oder den Schlüssel gilt, ist erreicht, oder der ungünstigste Fall der Anfrage, ihr Prompt und ihre Ausgabegrenze zum Preis des Modells, passt nicht in das, was übrig ist; ein kleineres `max_tokens` passt eher. Die Meldung nennt die Grenze, `Retry-After` die Zeit bis zum Zurücksetzen einer erreichten Grenze, und `x-should-retry: false` sagt den SDKs, dass sie es nicht erneut versuchen sollen. |
| **429** | `MODEL_API_CONCURRENCY_EXCEEDED` | Der Schlüsselinhaber oder der Schlüssel hat schon acht Anfragen laufen. `Retry-After` bittet um zwei Sekunden Wartezeit. |
| **503** | `MODEL_API_UNAVAILABLE` | Tale kann die Anfrage gerade nicht bedienen, etwa weil das Modell-Gateway das Modell nicht bereitstellen kann. Versuche es in Kürze erneut. |
| **400**, **413**, **422**, **429**, **503**, **529** oder **502** | `MODEL_API_UPSTREAM_ERROR` | Der Modellanbieter hat die Anfrage abgelehnt. Die ersten sechs Status übernehmen den des Anbieters; jede andere Ablehnung wird mit **502** beantwortet. |
| **400** | `INVALID_BODY` | Der Body ist keine Anfrage, die die Route weiterreichen kann, etwa mit einer Audioeingabe oder -ausgabe, einer Rolle, die sie nicht weiterreicht, einer Bild-URL, die weder `data:` noch `https:` ist, mehr als acht Antworten (`n`), einer Datei im Konto des Anbieters (`file_id`, eine Quelle vom Typ `file`), einem anderen `service_tier` als dem Standard oder `store: true`. Die Meldung nennt das Feld, im OpenAI-Format auch `param`. |
| **413** | `BODY_TOO_LARGE` | Der Body ist größer als 32 MiB. |

## Die Dateien eines Projekts durchsuchen

Verwende die Projekt-URL, wenn alle Treffer aus einem Projekt stammen sollen. Die Suche erfasst ausschließlich dessen indexierte Dateien und verlangt Leserechte, auch bei einem archivierten Projekt. Dokumente der Wissensdatenbank oder von Teams, andere Projekte, Websites und E-Mail-Anhänge bleiben außen vor. Lass `corpus` weg oder setze es auf `"documents"`. Ein anderer Korpus oder `projectId` im Anfrageinhalt ergibt **400**.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/knowledge/search" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "Frist für die Q1-Meldung", "limit": 10 }'
```

### Suchwerte und Fehler einordnen

`query` ist erforderlich und wird vor der Prüfung getrimmt. Optional sind `limit` (1–50, Standard 10) und `minSimilarity` (0–1). Tale sucht zunächst in einem größeren Kandidatenpool, prüft die aktuelle Sichtbarkeit jedes Dokuments und begrenzt erst nach dem Zusammenführen die Ergebnismenge. `limit: 1` liefert so die beste lesbare Passage (bei gleichem `fusedScore` geht eine Passage, die der Stichwort-Zweig gerankt hat, einer vor, die nur der Vektor-Zweig gefunden hat, danach die niedrigere Zeilenidentität — ein exakter Begriff ist ein stärkerer Beleg als ein nächster Nachbar).

`minSimilarity` begrenzt nur die Vektorsuche, bevor deren Ergebnisse mit den Stichworttreffern zusammengeführt werden. Für die REST-Route gibt es keinen Standardwert; auch schwache Vektortreffer können deshalb erscheinen. Die Stichwortsuche hat keine solche Untergrenze. Der eingebaute Assistent verwendet hingegen die Organisationskonfiguration: `minSimilarity` in [`embedding.json`](https://docs.tale.dev/de/self-hosted/configuration/data-residency#das-embedding-modell-der-organisation), standardmäßig 0,45.

| Feld | Bedeutung und Grenze |
| --- | --- |
| `fusedScore` | Sortierwert aus Σ 1/(60+Rang) der passenden Suchzweige, normalisiert am bestmöglichen Wert für deren Anzahl. Nur innerhalb derselben Antwort vergleichbar; keine Konfidenz. Der beste Treffer einer Suche mit nur einem Zweig kann 1,0 erreichen, auch wenn er inhaltlich schwach passt. |
| `similarity` | Kosinuswert der Vektorsuche auf der modellabhängigen Skala 0–1; `null` bei reinen Stichworttreffern — die behältst du, ein exakter Bezeichner- oder Phrasentreffer ist ein stärkerer Beleg als jeder Kosinus (im Code: `hits.filter(h => h.similarity === null ? h.keywordScore !== null : h.similarity >= floor)`). Für eine Schwelle nutzbar, aber keine kalibrierte Wahrscheinlichkeit. |
| `keywordScore` | Unbeschränktes BM25-Gewicht der Stichwortsuche; `null` bei reinen Vektortreffern. |
| `matchedLegs` | Suchzweige, die den Treffer geliefert haben: `documents:keyword`, `documents:dense`, `web:keyword`, `web:dense`. |
| `legs` | Anzahl dieser Zweige; 2, wenn Stichwort- und Vektorsuche dieselbe Passage finden. |
| `score` | Ursprünglicher Wert des ersten passenden Suchzweigs. |

Hohe Ähnlichkeit allein beweist keine passende Antwort. Unbekannte oder falsch geschriebene Begriffe können unerwartete Vektortreffer erzeugen. Prüfe die Passage selbst, besonders wenn ein Dokumenttreffer ohne `documents:keyword` ausschließlich aus der Vektorsuche stammt. Unsichtbare Dokumente werden vor der Zusammenführung entfernt und beeinflussen die Rangfolge nicht.

Jeder Treffer enthält die Passage und ihre `source`. `diagnostics.cached` und `diagnostics.reranked` sind immer `false`: Tale liefert weder einen semantischen Cache noch einen Reranker aus, beide Felder bleiben aus Kompatibilitätsgründen erhalten. `diagnostics.legs` nennt jeden Zweig, der gelaufen ist, mit den zugelassenen Kandidaten, die er beigesteuert hat — `0`, wenn er lief und nichts übrig blieb (`documents:dense: 0` ist ein Vektor-Zweig, der im Geltungsbereich nichts gefunden hat, nie ein fehlender) —, und `diagnostics.dense` ist nur dann `false`, wenn der Korpus den Vektor-Zweig gar nicht bedienen konnte, so wie `diagnostics.bm25` für den Stichwort-Index. Passagen tragen außer Tab, Zeilenvorschub und Wagenrücklauf keine Steuerzeichen, und eine Passage, die sich innerhalb eines Dokuments wiederholt — ein Export aus einer Zeile, ein Bericht aus einer Vorlage —, wird einmal indexiert, über ihr erstes Vorkommen, eine Datei voller Duplikate verstopft also weder den Vektor-Zweig noch rankt sie ihre Kopien eine nach der anderen. Dokumenttreffer enthalten neben der Blob-`ref` auch `source.documentId`:

- Ohne Projektzuordnung (`source.projectId: null`) verwendest du `GET /api/v1/documents/{id}`.
- Bei Projektdateien verwendest du `GET /api/v1/projects/{projectId}/files/{documentId}/content` oder `DELETE .../files/{documentId}`. Die organisationsweite Dokumentroute ergibt dafür **404**.

| Antwort | Nächster Schritt |
| --- | --- |
| **409** `EMBEDDING_NOT_CONFIGURED` | Ein Admin muss ein Embedding-Modell konfigurieren. |
| **409** `EMBEDDING_CREDIT_EXHAUSTED` | Guthaben, Ausgabenlimit und Tarif des Anbieterkontos prüfen. |
| **409** `EMBEDDING_CREDENTIAL_REJECTED` | Zugangsdaten und Berechtigung für das Modell korrigieren. Denselben Code liefert die Suche, wenn die Plattform gar keine nutzbaren Zugangsdaten senden kann: Der Anbieter hat keinen Standard, oder die in den Embedding-Einstellungen genannten wurden gelöscht, deaktiviert oder sind nicht lesbar; `error` nennt den Grund. |
| **503** `EMBEDDING_UPSTREAM_ERROR` | `Retry-After` beachten und mit wachsender Wartezeit erneut versuchen. |

Die beiden Kontofehler sind keine Rate-Limits; Warten allein behebt sie nicht. Für sichtbare Dokumente der Wissensdatenbank und von Teams ohne Projektzuordnung sowie registrierte Websites verwendest du `POST /api/v1/knowledge/search`. Dort erlaubt `corpus` `"documents"`, `"web"` und den Standard `"all"`. Projektdateien und E-Mail-Anhänge sind ausgeschlossen. Beide Suchen finden nur dateigestützte Dokumente; Inline-`content` wird nicht indexiert.

## Ein externes System in ein Projekt spiegeln

Die Projekt-Gruppe ist für einen unbeaufsichtigten Worker gebaut, der ein externes System — ein CRM, eine Kanzleisoftware — nach Tale spiegelt: das Projekt des Kunden finden oder anlegen, Ordner vorbereiten, Dateien hochladen, prüfen. Jeder Aufruf handelt als der Benutzer, der den Schlüssel erzeugt hat: ein Projekt, das dieser Benutzer nicht sieht, antwortet wie eines, das nicht existiert, und Schreiben braucht eine bearbeitende Rolle (Redakteur oder höher — Mitglied liest hier nur) plus Bearbeitungszugriff auf das Projekt.

Diese Routen — und die Aufgaben-Routen unten — raten nie, welche Organisation gemeint ist: ein Schlüssel, dessen Benutzer mehreren Organisationen angehört, muss `X-Organization-Slug` bei jedem Aufruf senden — eine Anfrage ohne den Header antwortet **400**. Erzeuge Maschinen-Schlüssel für einen eigenen Benutzer mit genau einer Mitgliedschaft, und die Frage stellt sich nie; die Beispiele senden den Header trotzdem — er wird immer auf Mitgliedschaft geprüft, nie ignoriert.

### Projekt finden oder anlegen

Ein Projekt trägt sein Publikum in `teamIds` — die Teams, die es sehen dürfen; leer heißt die ganze Organisation. Die IDs liest du aus `GET /api/v1/teams` (jedes Team mit Namen, mit `member: true` bei denen, in denen der Schlüsselbesitzer Mitglied ist — wer kein Organisations-Admin ist, darf nur diese nennen), schickst sie bei `POST /api/v1/projects` mit oder ersetzt die ganze Menge mit `PATCH /api/v1/projects/{id} { "teamIds": [...] }` (ein Admin-Verb). Eine wiederholte ID fällt auf eine zusammen, das Publikum erneut zu nennen, das das Projekt schon trägt, ist ein No-op und lässt `updatedAt` in Ruhe, und ein archiviertes Projekt weist die Änderung wie jede andere Schreiboperation ab (**403**, `PROJECT_ARCHIVED`), es sei denn, derselbe Body stellt es wieder her.

`externalItemId` ist dein Schlüssel, nicht der von Tale — ein opaker String (die Datensatz-ID deines CRM), eindeutig pro Organisation, von der Plattform nie interpretiert. Gespeichert und verglichen wird er nach NFC-Normalisierung und Trimmen: Ein Schlüssel, den ein macOS-Dateisystem in NFD übergibt, findet das Projekt, das ein Worker aus einer CSV in NFC angelegt hat, und ein Zeilenumbruch am Ende einer Shell-Variable erzeugt nie ein zweites Projekt.

Eine Altzeile, deren Schlüssel sich von einem anderen nur in der Normalisierung unterschied, hat die Plattform freigegeben — ihre `externalItemId` ist leer, die Zeile mit der kanonischen Schreibweise hat den Schlüssel behalten —, gib ihr also mit `PATCH /api/v1/projects/{id}` einen neuen Schlüssel, wenn sie die gemeinte ist. Schlag ihn zuerst nach; die Suche antwortet mit höchstens einem Projekt, und ein Treffer, den der Benutzer des Schlüssels nicht sehen darf, sieht genauso aus wie keiner:

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/projects?externalItemId=crm-4711" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "projects": [] } — oder [ { "id": "...", "name": "ACME Ltd", "externalItemId": "crm-4711" } ]
```

Ein Treffer trägt `archivedAt`, wenn das Projekt archiviert ist — entscheide vorher, was dein Worker mit diesem Fall macht. Ohne `externalItemId` listet dieselbe Route jedes Projekt, das der Benutzer des Schlüssels sehen darf, die neuesten zuerst, Keyset-paginiert wie jede andere Liste — `{projects, isDone, continueCursor}`; gib `continueCursor` als `?cursor=` zurück, bis `isDone` gilt (solange weitere Seiten bleiben, trägt die Antwort auch `cursor`, dasselbe Token unter seinem Namen vor 1.5 — veraltet, lies `continueCursor`; ein Nachschlagen antwortet `isDone: true` mit leerem `continueCursor`) —, archivierte Projekte ausgenommen, sofern du nicht danach fragst (`?archived=include` oder `?archived=only`).

Jede Zeile trägt `createdAt` und `updatedAt`, ein Worker kann also abgleichen, was er angelegt hat:

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/projects?limit=50" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "projects": [ { "id": "...", "name": "ACME Ltd", "externalItemId": "crm-4711", "createdAt": 1774..., "updatedAt": 1774... } ], "isDone": true, "continueCursor": "" }
```

Eine leere Suche heißt anlegen:

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ACME Ltd", "externalItemId": "crm-4711" }'
# → 201 { "project": { "id": "...", "name": "ACME Ltd", "key": "ACME", "externalItemId": "crm-4711" } }
```

`key` (das Präfix der Aufgaben-Kennungen) und `description` sind optional — der Key leitet sich aus dem Namen ab, wenn du ihn weglässt. Ein zweites Anlegen mit derselben `externalItemId` — derselben nach NFC-Normalisierung und Trimmen — antwortet **409**; derselbe String in einer anderen Organisation ist in Ordnung, die Eindeutigkeit gilt pro Organisation. Ein Schlüssel, der getrimmt leer ist, ergibt **400**, `INVALID_BODY`.

Ein expliziter Projekt-`key` besteht aus 2–6 Buchstaben oder Ziffern, beginnt mit einem Buchstaben und landet in Großbuchstaben. Ungültige Werte ergeben **400**, ohne Kürzung. Lässt sich aus dem Namen kein gültiger Key ableiten, entsteht das Projekt ohne Key. Kollidiert ein abgeleiteter Key, leitet Tale so lange neu ab, bis er frei ist; ein expliziter Key, der kollidiert, ergibt **409**, `PROJECT_KEY_TAKEN` — sende einen freien mit. Dieselbe `externalItemId` ein zweites Mal ergibt **409**, `PROJECT_DUPLICATE_EXTERNAL_ID`.

### Ordner anlegen

Ordner entstehen per Get-or-create: derselbe Name unter demselben Elternordner — verglichen ohne Rücksicht auf Groß- und Kleinschreibung, `inbox` und `INBOX` sind also ein Ordner — antwortet mit dem bestehenden Ordner, seinem gespeicherten Namen und `created: false` (**200**) statt mit einem Duplikat; ein Worker darf seinen Setup-Schritt nach einem Absturz blind wiederholen, und zwei Worker, die denselben Ordner gleichzeitig anlegen, bekommen einen Ordner.

Ein Name ist ein Name, nie ein Pfad: Ein `/` oder `\`, ein Steuerzeichen, `.` oder `..` ergibt **400**, `FOLDER_NAME_INVALID`, der Satz nennt die verletzte Regel und `data.issues` nennt `name` — dieselbe Regel, der ein Dateiname folgt, und wie ein Dateiname wird der Ordnername getrimmt und NFC-normalisiert gespeichert —, und `parentId` ist entweder ein Ordner dieses Projekts oder bleibt für einen Wurzelordner weg (ein leeres ergibt **400**, `INVALID_BODY`). Ordnernamen haben keine plattformseitig reservierte Bedeutung — das Layout gehört dir:

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/folders" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "2026-Q1" }'
# → 201 { "folder": { "id": "<folderId>", "name": "2026-Q1" }, "created": true }
```

`parentId` (ein Ordner dieses Projekts) verschachtelt tiefer; lass es für einen Wurzelordner weg. Ein Name hat höchstens 128 Zeichen, wird getrimmt und ist nie ein Pfad — `a/b`, `.` und `..` ergeben **400**, `FOLDER_NAME_INVALID` —, und ein Ordner in 20 Ebenen Tiefe nimmt kein Kind mehr an (**400**, `FOLDER_DEPTH_EXCEEDED`).

Der Baum liest sich Ebene für Ebene zurück: `GET .../folders` listet die Wurzelordner, `GET .../folders?parentId=<folderId>` die Kinder eines Ordners, und jeder Ordner trägt seine `parentId` (`null` an der Wurzel); `GET .../folders/{folderId}` löst einen einzelnen Ordner auf — die `folderId`, die jede Datei in `GET .../files` trägt —, ein Worker, der den Baum nicht gebaut hat, kann ihn also trotzdem entdecken, und ein Pfad ist die aufwärts gelaufene Elternkette. Eine `parentId` oder `folderId`, die kein Ordner dieses Projekts ist, ergibt **404**, `FOLDER_NOT_FOUND`.

### Eine Datei in zwei Schritten hochladen

Zwei REST-Aufrufe umgeben einen direkten Upload zum Objektspeicher: Übergabe vorbereiten, Bytes übertragen und dann dem Projekt zuordnen. Das Shell-Beispiel benötigt `jq`, einen vorhandenen Projektordner und eine lokale Datei mit erlaubter Endung und passendem MIME-Typ. Führe den nächsten Befehl erst aus, wenn der vorherige erfolgreich war.

```bash
: "${TALE_URL:?Set TALE_URL to your Tale origin}"
: "${TALE_API_KEY:?Set TALE_API_KEY}"
: "${TALE_ORG_SLUG:?Set TALE_ORG_SLUG}"
: "${TALE_PROJECT_ID:?Set TALE_PROJECT_ID}"
: "${TALE_FOLDER_ID:?Set TALE_FOLDER_ID to a folder in this project}"
: "${FILE_PATH:?Set FILE_PATH to an existing local file}"
: "${FILE_MIME:?Set FILE_MIME, for example application/pdf}"

FILE_NAME=$(basename "$FILE_PATH")
FILE_SIZE=$(wc -c < "$FILE_PATH" | tr -d ' ')
UPLOAD_BODY=$(jq -n --arg name "$FILE_NAME" --arg type "$FILE_MIME" \
  --argjson size "$FILE_SIZE" '{fileName:$name,contentType:$type,size:$size}')
UPLOAD_JSON=$(curl --fail-with-body --silent --show-error \
  "$TALE_URL/api/v1/projects/$TALE_PROJECT_ID/uploads" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --header 'Content-Type: application/json' --data "$UPLOAD_BODY")
UPLOAD_ID=$(printf '%s' "$UPLOAD_JSON" | jq -er '.uploadId')
UPLOAD_URL=$(printf '%s' "$UPLOAD_JSON" | jq -er '.url')
FILE_REF=$(printf '%s' "$UPLOAD_JSON" | jq -er '.s3Ref')
printf '%s' "$UPLOAD_JSON" | jq '{uploadId,method,expiresAt,maxBytes}'
```


#### Bytes vor dem Zuordnen senden

Die zurückgegebene `url` ist eine vorsignierte URL für einen direkten `PUT` zum Objektspeicher. Sende keinen `Authorization`-Header: Die URL enthält bereits eine Signatur; eine zusätzliche Authentifizierung wird abgewiesen. Falls du bei der Vorbereitung einen `contentType` angegeben hast, muss der `Content-Type` des PUT exakt damit übereinstimmen. Ohne diese Angabe ist kein bestimmter Header vorgeschrieben. Verwende anschließend die zurückgegebene `s3Ref` als `fileId` beim Zuordnen.

Gib `fileName` schon bei der Vorbereitung an, etwa `"fileName": "ledger-2026-q1.pdf"`. Tale prüft dann Dateiformat und Upload-Richtlinie, bevor es eine URL ausstellt. Ein nicht erlaubter Dateityp oder ein Name ohne Endung ergibt **400** mit `UPLOAD_POLICY_REJECTED` oder `UNSUPPORTED_FILE_TYPE`. Ein angegebener MIME-Typ ersetzt die erforderliche Endung nicht.

`maxBytes` nennt die zulässige Dateigröße für den angegebenen Typ: höchstens 100 MiB (104.857.600 Bytes), bei einer strengeren Organisationsrichtlinie entsprechend weniger. Mit dem optionalen Feld `size` lässt du die geplante Größe vorab prüfen. Über der Plattformgrenze folgt **400** `FILE_TOO_LARGE`; bei einer verletzten Organisationsgrenze oder einem ausgeschöpften Volumenkontingent folgt **400** `UPLOAD_POLICY_REJECTED`. `data.limitBytes` nennt die Grenze.

Die Vorprüfung spart die Übertragung einer zu großen Datei. Beim Zuordnen zählt trotzdem die tatsächliche Größe im Objektspeicher. Tale vergleicht sie mit den geltenden Grenzen, nicht mit der zuvor deklarierten `size`; eine zu kleine Größenangabe umgeht die Prüfung daher nicht.

Übertrage die Bytes an die zurückgegebene URL. Sende dorthin keinen Tale-API-Schlüssel: Die Signatur authentifiziert den Zugriff auf den Objektspeicher bereits. Ordne die Datei erst nach erfolgreichem Upload zu.

```bash
curl --fail-with-body --silent --show-error --request PUT "$UPLOAD_URL" \
  --header "Content-Type: $FILE_MIME" \
  --upload-file "$FILE_PATH"
```

```bash
BIND_BODY=$(jq -n --arg upload "$UPLOAD_ID" --arg ref "$FILE_REF" \
  --arg folder "$TALE_FOLDER_ID" --arg name "$FILE_NAME" \
  '{uploadId:$upload,fileId:$ref,folderId:$folder,fileName:$name}')
curl --fail-with-body --silent --show-error \
  "$TALE_URL/api/v1/projects/$TALE_PROJECT_ID/files" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --header 'Content-Type: application/json' --data "$BIND_BODY"
```

Die Zuordnung liefert `201 {file}` mit der neuen Dokument-ID. Bewahre `file.id` für spätere Abrufe, Downloads, Indexierung oder Löschung auf. Sie unterscheidet sich von `uploadId` und `s3Ref`.

#### Ablauf, Formatregeln und abgebrochene Uploads behandeln

`uploadId` lässt sich einmal verwenden. Sie und die vorsignierte URL laufen nach 30 Minuten ab; `expiresAt` gilt für beide. Ist die Frist nach einem abgebrochenen Upload verstrichen, bereite einen neuen Upload vor.

`fileName` muss ein einzelner Dateiname sein. Tale entfernt äußere Leerzeichen und normalisiert ihn nach NFC. Pfadtrenner oder Steuerzeichen ergeben **400**. Eine erlaubte Dateiendung ist bei Vorbereitung und Zuordnung erforderlich: Namen wie `CON` oder `attachment-4711` ergeben `UNSUPPORTED_FILE_TYPE`, auch wenn du `contentType` angibst.

Beim Zuordnen prüft Tale die Upload-Richtlinie erneut. Erlaubt sind `pdf`, `doc`, `docx`, `odt`, `ppt`, `pptx`, `xls`, `xlsx`, `csv`, `txt`, `md`, `json`, `yaml`, `yml`, `py`, `jpg`, `jpeg`, `png`, `gif`, `webp` und `ac2` (Banana-Buchhaltungsjournal), soweit die Organisation diese Formate zulässt. Die Meldung zu `UNSUPPORTED_FILE_TYPE` enthält die sortierte Formatliste. Ein nicht erlaubtes Format oder eine überschrittene Größenbegrenzung ergibt **400** mit dem jeweiligen Fehlercode.

Sind die Bytes noch nicht im Objektspeicher angekommen, folgt **404** `BLOB_NOT_FOUND`. Die Upload-ID bleibt nach dieser Ablehnung verwendbar: Führe den PUT aus und wiederhole die Zuordnung mit derselben ID.

Ohne konfigurierten Objektspeicher ergeben Vorbereitung und Zuordnung **503** `OBJECT_STORE_UNCONFIGURED`. Nicht zugeordnete Blobs werden automatisch bereinigt: frühestens 24 Stunden nach Ablauf der 30-minütigen Upload-Frist, bei einer späteren Upload-Vorbereitung in derselben Organisation. Jede solche Anfrage bereinigt einen Stapel abgelaufener Upload-Datensätze samt Blobs. Das betrifft auch abgelehnte Zuordnungen und Uploads, deren Client zwischen Übertragung und Zuordnung abgebrochen ist.

Bis zur Bereinigung liegen diese Bytes im Bucket, erscheinen aber in keiner Dateiliste und zählen nicht zum Kontingent.

#### Über die Dateiindexierung entscheiden

Projektdateien werden standardmäßig nicht für die Wissenssuche indexiert: Beim Zuordnen gilt `skipRagIndexing: true`. Setze den Wert auf `false`, wenn die Datei in die Projektsuche aufgenommen werden soll. Projektdateien erscheinen unabhängig davon nicht unter `/api/v1/documents`; diese Route ist für Dokumente der Wissensdatenbank vorgesehen.

Der Projektchat kann auch nicht indexierte Dateien auflisten. Im Tab **Wissen** des Projekts steht eine solche Datei als **Nicht indexiert**. Für die Suche musst du sie erst indexieren: über **Jetzt indexieren** in der Dateizeile oder `POST /api/v1/projects/{id}/files/{documentId}/retry-indexing`.

Der REST-Aufruf verwendet dieselbe Indexierungslogik und dasselbe Budget von 10 Aufrufen pro Benutzer und Minute wie bei Dokumenten der Wissensdatenbank. Er hebt die bisherige Ausnahme von der Indexierung auf und liefert `{"status": "indexing"}` oder `skipped` mit einem `reason`. Eine reine Textdatei bis 4 MiB kann der Assistent auch ohne Indexierung lesen: `rag_fetch` mit ihrer ID liefert den Text direkt.

Der gespeicherte `mimeType` wird aus der Dateierweiterung bestimmt und beim Download als `Content-Type` verwendet. Der Medientyp eines Multipart-Uploads oder ein Upload-Hinweis überschreibt diese Regel nicht.

### Prüfen, was angekommen ist

Mit `folderId` wählst du den Bereich: Ohne den Parameter erhältst du alle Projektdateien, mit `folderId=root` nur Dateien ohne Ordner auf der obersten Projektebene. Eine Ordner-ID liefert die Dateien dieses Ordners. Gehört der Ordner nicht zum Projekt, lautet die Antwort **404**, `FOLDER_NOT_FOUND`.

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/projects/<projectId>/files?folderId=<folderId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "files": [ { "id": "...", "fileName": "ledger-2026-q1.pdf", "folderId": "<folderId>", "mimeType": "application/pdf", "size": 48213, "indexing": { "status": "skipped" }, "createdAt": 1774... } ], "isDone": true, "continueCursor": "" }
```

Jede Dateizeile enthält die tatsächliche `size` und ein `indexing`-Objekt mit denselben Statuswerten wie bei `/api/v1/documents`. Nach einer Zuordnung mit dem Standard `skipRagIndexing: true` lautet der Status `skipped`. Starte bei Bedarf `POST .../files/{documentId}/retry-indexing` und frage den Zustand erneut ab. Erst `completed` bestätigt die abgeschlossene Indexierung für die Suche.

Die Liste liefert `{files, isDone, continueCursor}`. Solange `isDone` `false` ist, übergib das unveränderte, signierte Token als `?cursor=`. `?limit=` erlaubt höchstens 100 Einträge. Wenn weitere Seiten folgen, enthält die Antwort zusätzlich das veraltete Feld `cursor` aus der Zeit vor Version 1.5; verwende in neuen Clients `continueCursor`.

Für eine einzelne Datei genügt `GET /api/v1/projects/{id}/files/{documentId}`. Die Antwort `{file}` enthält `id`, `fileName`, `folderId`, `mimeType`, `createdAt` und `size` in Bytes (`null`, wenn unbekannt) sowie den Indexierungszustand, sofern vorhanden. Sende den `ETag` als `If-None-Match`, um bei unverändertem Zustand `304` zu erhalten. Nach `POST .../retry-indexing` kannst du diese eine Zeile abfragen, bis die Indexierung endet; ein erneuter Durchlauf durch die ganze Dateiliste ist unnötig. Fehlende, gelöschte, projektfremde oder nicht dateibasierte Einträge ergeben einheitlich `404 FILE_NOT_FOUND`.

```bash
curl --fail-with-body --compressed "$TALE_URL/api/v1/projects/<projectId>/files/<documentId>" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG"
```

### Löschen, was du nicht mehr brauchst

`DELETE .../files/{documentId}` löscht eine Projektdatei endgültig: Dokumentdatensatz, Suchdaten und Blob werden gemeinsam bereinigt. Erfolg ergibt **204**; eine fehlgeschlagene Bereinigung wird als Fehler zurückgegeben.

```bash
curl -sS --compressed -X DELETE "https://your-host.example.com/api/v1/projects/<projectId>/files/<documentId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 204
```

`DELETE .../folders/{folderId}` löscht einen Ordner samt Unterordnern und Dateien. Tale bereinigt zuerst die Dateien einschließlich ihrer Suchdaten und entfernt dann den Teilbaum. Liegt darin ein geschütztes gelenktes Dokument oder ein Dokument unter Legal Hold, wird die gesamte Aktion vor der ersten Änderung mit **409** abgewiesen.

Kann die Bereinigung im Objektspeicher nicht abgeschlossen werden, folgt **503** `PURGE_INCOMPLETE`; es wurde nichts entfernt. Wiederhole die Anfrage. Beide Löschrouten verlangen Bearbeitungsrechte auf ein aktives Projekt. Bereits gelöschte Ressourcen und IDs aus anderen Projekten ergeben **404** mit `FILE_NOT_FOUND` beziehungsweise `FOLDER_NOT_FOUND`.

#### Projekt archivieren, umbenennen oder löschen

Auch das Projekt selbst hat einen Lebenszyklus, für Organisations-Admins (**403**, `ROLE_FORBIDDEN`, für alle anderen). `PATCH /api/v1/projects/{id}` mit `{ "archived": true }` archiviert es — es bleibt über diesen Zugang lesbar, verweigert jedes Schreiben mit **403**, `PROJECT_ARCHIVED`, hält seine `externalItemId` belegt, und `{ "archived": false }` holt es zurück.

Derselbe `PATCH` trägt die Identität, die ein Spiegel weiterreicht, wenn sich der Quelldatensatz ändert: `name` (getrimmt, nie leer), `description` (`null` leert sie) und `externalItemId` (NFC-normalisiert und getrimmt gespeichert; `null` gibt den Schlüssel frei, der Schlüssel eines anderen Projekts ergibt **409**, `PROJECT_DUPLICATE_EXTERNAL_ID`, mit dem Schlüssel in `data`) — für Redakteure mit Projektbearbeitungsrechten an einem aktiven Projekt, jedes Feld optional und mindestens eines Pflicht. Ein Body, der zurückholt und umbenennt, wendet das Zurückholen zuerst an, einer, der umbenennt und archiviert, das Archivieren zuletzt; ein archiviertes Projekt umzubenennen, das der Body nicht zurückholt, ergibt **403**, `PROJECT_ARCHIVED`.

Wird aus „ACME Ltd“ im CRM „ACME Group“, ist `{ "name": "ACME Group" }` der ganze Umzug — nichts unter dem Projekt wird angefasst. `DELETE /api/v1/projects/{id}` entfernt es und gibt den Schlüssel frei: standardmäßig als Kaskade — jedes Dokument läuft in die Aufbewahrungs-Pipeline ab, deine eigenen Chats wandern in den Papierkorb, jede Aufgabe wird stillgelegt und ihre laufenden Läufe abgebrochen — oder, mit dem Body `{ "mode": "detach" }`, werden Dokumente und Chats stattdessen in die Organisation entlassen. Die Laufhistorie des Projekts geht in beiden Fällen mit, beendete Läufe eingeschlossen — anders als beim Löschen einer Automatisierung, das ihre Läufe behält.

Agenten und Ordner gehen in beiden Fällen mit dem Projekt, und eine Kaskade zehrt vom selben Budget pro Benutzer wie das Löschen in der App (5 pro Minute):

```bash
curl -sS --compressed -X DELETE "https://your-host.example.com/api/v1/projects/<projectId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 204
```

Das Löschen wird mit **409** abgewiesen, bevor irgendetwas geschrieben ist, solange eine Automatisierung im Projekt installiert ist — `PROJECT_HAS_BOUND_AUTOMATIONS`, `data.automations` nennt sie; deinstalliere jede zuerst über `DELETE /projects/{id}/automations/{name}` —, solange eine Kaskade ein gelenktes Dokument zerstören würde, das in Prüfung oder genehmigt ist oder eine genehmigte Version behält (`PROJECT_HAS_PROTECTED_RECORDS`, `data.documents` nennt sie), oder solange ein Legal Hold eines seiner Dokumente erfasst (`PROJECT_LEGAL_HOLD`).

## Eine Aufgabe anlegen, dann ausführen

Die Aufgabenrouten machen aus einem externen Datensatz eine Aufgabe auf dem Projektboard, starten einen bereitgestellten Workflow und liefern die Ergebnisse zurück. Eine projektgebundene Automatisierung muss zuvor in diesem Projekt installiert sein. Das Installieren ist idempotent: **201** beim ersten Aufruf, **200** bei vorhandener Bindung. Es verlangt die Entwickler-Fähigkeit und Bearbeitungsrechte auf ein aktives Projekt. Fehlen dem Worker diese Rechte, richte die Bindung vorher ein:

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/automations/vat-return" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{}'
# → 201 { "name": "vat-return", "added": true }
```

`GET /api/v1/projects/{id}/automations` listet die in diesem Projekt installierten Automatisierungen. Eine Automatisierung ganz ohne Projektbindungen darf ebenfalls in einem zugänglichen Projekt laufen, wenn der Aufrufer die nötigen Bearbeitungsrechte hat; in der Liste der installierten Automatisierungen erscheint sie jedoch nicht. `DELETE /api/v1/projects/{id}/automations/{name}` entfernt eine Installation wieder — **204**, oder **404** `AUTOMATION_NOT_INSTALLED`, wenn sie dort nicht installiert war — unter derselben Entwickler-Fähigkeit und denselben Bearbeitungsrechten.

### Gespiegelte Aufgabe erstellen oder aktualisieren

Das Anlegen einer Aufgabe ist pro `(projectId, externalSystem, externalId)` idempotent: Der erste Aufruf legt sie an (**201**, `created: true`) — in `backlog`, der Eingangsspalte des Spiegels, während die App eine neu angelegte Aufgabe unter „To do“ einsortiert —, ein erneuter liefert dieselbe Aufgabe (**200**, `created: false`). Beide Schlüssel werden nach NFC-Normalisierung und Trimmen gespeichert und verglichen — dieselbe Regel wie bei der `externalItemId` eines Projekts —, eine Wiederholung mit Leerzeichen drumherum oder anderer Normalisierung ist also noch dieselbe Aufgabe, und ein Schlüssel, der getrimmt leer ist, ergibt **400**. Die `projectId` kommt aus der URL; im Anfrageinhalt ergibt sie **400**. Anlegen darf jeder Schlüsselinhaber, der ein aktives Projekt lesen kann, Mitglieder eingeschlossen (Vertrag 3.6.0). Eine Wiederholung ändert die Aufgabe, die sie benennt, und braucht deshalb das Recht, diese Aufgabe zu ändern: als Redakteur oder höher oder als Mitglied, das die Aufgabe angelegt hat oder dem sie zugewiesen ist. Alle anderen erhalten **403**, `RBAC_FORBIDDEN`, und nichts wird geschrieben.

Bei `externalSystem: "github"` oder `"glitchtip"` ändert `externalState` den Status der Tale-Aufgabe nicht. Neue Aufgaben landen in `backlog`; wenn ein Issue an der Quelle geschlossen, gelöst oder wieder geöffnet wird, bleibt der lokale Fortschritt erhalten. Die Automatisierungen zum Issue-Import zeigen den Quellstatus separat an der Aufgabe an.

Für andere Quellsysteme übernimmt `externalState` den Zustand des Quelldatensatzes nach folgenden Regeln:

- `closed` setzt die Aufgabe auf `in_review`, damit eine Person den Abschluss prüft. Nur die Workflow-Engine setzt einen automatischen Abschluss direkt auf `done`.
- `open` setzt eine zuvor durch diese Spiegelung geschlossene Aufgabe aus `in_review` oder `done` zurück auf `backlog`.
- Hat eine Person oder ein Agent den Zustand geändert, überschreibt `open` diese Entscheidung nicht. Eine Statusänderung über das Board beendet die Zuständigkeit der Spiegelung für den zuvor gesetzten Status.
- Abgebrochene Aufgaben bleiben abgebrochen.

Ein ausstehendes Review eines Agenten behält seinen Status und Reviewer. Die Synchronisierung einer solchen Quelle erfasst Schließen und Wiederöffnen getrennt davon, ohne das Review freizugeben oder zurückzuziehen.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/tasks" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "externalSystem": "crm", "externalId": "case-991", "title": "Prepare the Q1 filing" }'
# → 201 { "task": { "id": "<taskId>", "created": true } }
```

Ein erneuter Aufruf mit derselben externen Referenz einer aktiven Aufgabe aktualisiert Titel und Beschreibung. Ohne `description` wird die Beschreibung gelöscht; Labels ändern sich nur, wenn du sie mitsendest. Archivierte Aufgaben bleiben unverändert. Die Aufgaben-ID bleibt gleich; `runWorkflowSlug` startet dabei keinen weiteren Lauf. Sende beim Wiederholen nach einer verlorenen Antwort dieselben Daten.

### Einrichtungsordner und Automatisierungszuordnung festlegen

Optional sind `description`, `labels`, `externalUrl` und `setupFolderName`. `title` erlaubt höchstens 200 UTF-16-Codeeinheiten, `description` höchstens 20.000; die meisten Emojis zählen doppelt. `labels` nimmt bis zu 50 Namen mit je höchstens 50 Codeeinheiten auf. Eine direkt angegebene `externalUrl` muss eine absolute `http(s)`-URL sein. Ungültige Werte ergeben **400**; Tale kürzt oder ersetzt sie nicht automatisch.

Mit `setupFolderName` wählst du einen Wurzelordner des Projekts anhand seines Namens, unabhängig von Groß- und Kleinschreibung. Tale speichert dessen ID als `externalUrl` der Aufgabe. Eine Automatisierung kann so den Einrichtungsordner aus ihrer Aufgaben-Eingabe lesen. Bei wiederholten Anfragen wird der Name erneut aufgelöst.

Ein Name, den kein Wurzelordner des Projekts trägt, ergibt **400**, `SETUP_FOLDER_MISSING`, und es entsteht keine Aufgabe; zusammen mit `externalUrl` gesendet ergibt er **400**, `INVALID_BODY`.

Labelnamen werden getrimmt und nach NFC normalisiert. Der Abgleich mit vorhandenen Projektlabels ignoriert Groß- und Kleinschreibung. Neue Labels werden in der gesendeten Schreibweise angelegt; vorhandene behalten ihre gespeicherte Schreibweise. Die Antwort übernimmt deine Reihenfolge. So bleibt `["Bug", "P1"]` unverändert, während `["bug"]` bei einem vorhandenen Label `Bug` auf dieses Label verweist. Namen, die sich nur in der Schreibweise unterscheiden, erzeugen keine zwei Labels. Neue Labels legt so nur an, wer im Projekt Redakteur oder höher ist; alle anderen Schlüsselinhaber nennen Labels, die der Katalog schon hat, und ein neuer Name ergibt **400**, `TASK_LABEL_UNKNOWN`, ohne dass etwas geschrieben wird.

Mit `automationSlug` weist du die Aufgabe einer Automatisierung zu. Diese Zuordnung aktiviert im Aufgabendialog den Arbeitsbereich mit Startschaltfläche, Fortschritt und Rückfragen des Laufs. Eine spätere Anfrage ergänzt eine fehlende Zuordnung, überschreibt aber keine bereits zuständige Person oder Automatisierung.

`runWorkflowSlug` startet einen bereitgestellten Workflow direkt beim Anlegen einer neuen Aufgabe. Der Start erfolgt vor der Antwort; diese enthält die `runId` für spätere Statusabfragen. Das veraltete Feld `executionId` enthält denselben Wert. Gibt es unter dem Slug keine bereitgestellte Automatisierung oder schlägt der Start nach dem Speichern der Aufgabe fehl, ist `runId` `null`. Die Aufgabe bleibt gespeichert. Prüfe den Workflow und verwende nach der Korrektur den separaten Startaufruf.

Verwende den separaten Startaufruf, wenn du den Workflow erst nach dem Anlegen auswählen möchtest. Eine angegebene `automationSlug` muss auf eine vorhandene Automatisierung mit bereitgestellter Version verweisen: Andernfalls folgen **404** `AUTOMATION_NOT_FOUND` oder **409** `AUTOMATION_NOT_DEPLOYED`. Eine Automatisierung, die ausschließlich an andere Projekte gebunden ist, ergibt **403**.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/tasks/<taskId>/start" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "workflowSlug": "vat-return" }'
# → 200 { "started": true, "runId": "<runId>", "executionId": "<runId>" }
```

### Prüfen, ob ein Aufgabenlauf gestartet wurde

Zum Starten brauchst du das Recht, die Aufgabe zu ändern — als Redakteur oder höher oder als Mitglied, das sie angelegt hat oder dem sie zugewiesen ist (sonst **403**, `RBAC_FORBIDDEN`) —, ein aktives Projekt und eine aktive Aufgabe; eine archivierte Aufgabe ergibt **403**, `TASK_ARCHIVED` (das Lesen der Aufgabe trägt `archivedAt`, solange sie es ist; `PATCH …/tasks/{taskId}` mit `{ "archived": false }` stellt sie wieder her — siehe unten). Der Lauf erhält die Aufgabe als `{task: ...}`; eine zusätzliche Entwickler-Fähigkeit ist dafür nicht nötig. Das Laufprotokoll ordnet den Start deinem Schlüssel zu. Polle `GET /api/v1/projects/{id}/runs/{runId}` mit der `runId` (`executionId` trägt denselben Wert und ist veraltet).

Die Antwort ist **200**, ob ein Lauf gestartet ist oder nicht, verzweige also auf `started`, nie auf den Status allein: Bei `started: false` liefert `reason: "already_running"` die `runId` des bereits laufenden Laufs — eine Aufgabe hält höchstens einen lebenden Lauf, egal welche Automatisierung ihn gestartet hat, dieser Lauf kann also zu einer anderen Automatisierung gehören (sein `name` sagt, zu welcher); polle diesen. Ein Workflow, der an andere Projekte gebunden ist, ergibt **403**, `AUTOMATION_PROJECT_FORBIDDEN`.

Solange ein Projektagent an der Aufgabe arbeitet, wird ein Workflow-Start mit **409** `TASK_HAS_LIVE_RUN` abgelehnt. Warte, bis der Agent fertig ist, oder brich seinen Lauf ab, bevor du den Workflow startest. Umgekehrt kann kein Agent starten, solange ein Workflow die Aufgabe bearbeitet.

Neue Läufe werden außerdem mit **403** `TASK_AUTOMATION_DISABLED` abgelehnt, wenn die Aufgabenautomatisierung ausgeschaltet ist, oder mit **409** `TASK_AUTOMATION_UNAVAILABLE`, wenn ihre Richtlinie nicht gelesen werden kann. Bitte einen Admin, die Aufgabenautomatisierung einzuschalten oder die Richtlinie wiederherzustellen. Bereits laufende Arbeit kann fertig werden; Kommentare werden weiterhin gespeichert.

Der `workflowSlug` benennt die Automatisierung so, wie `GET /api/v1/automations` sie listet — in der `/`-Form (`billing/dunning`), nie in der `__`-Schreibweise des URL-Pfads —, und muss eine benennen, die es gibt — sonst **404**, `AUTOMATION_NOT_FOUND` — und die eine bereitgestellte Version hat: Eine gespeicherte, aber nicht bereitgestellte ergibt **409**, `AUTOMATION_NOT_DEPLOYED` — dieselben zwei Ablehnungen, die das Anlegen einer Aufgabe einem `automationSlug` gibt, beurteilt, bevor das Execute-Budget belastet wird; `reason: "not_started"` bleibt dem einen Restfall vorbehalten, einer Bereitstellung, die zwischen dieser Prüfung und dem Start zurückgezogen wurde.

Gleichzeitige Starts derselben Aufgabe verwenden denselben laufenden Durchgang, egal welche Automatisierung sie nennen. Das ist keine Unterstützung für `Idempotency-Key` bei Aufgabenstarts: Nach dessen Abschluss kann ein weiterer Start einen neuen Lauf erzeugen. Speichere die zurückgegebene `runId` und prüfe diesen Lauf, bevor du einen unklaren Start wiederholst.

### Aufgabe archivieren oder wiederherstellen

`PATCH /api/v1/projects/{id}/tasks/{taskId}` mit `{ "archived": true }` archiviert die Aufgabe — genau wie das Board: sie bleibt hier lesbar und verweigert Kommentare und Starts mit **403**, `TASK_ARCHIVED` — und `{ "archived": false }` stellt sie wieder her. Beides ist idempotent; ein Spiegel, der eine Aufgabe ablöst (eine erneute Lieferung, die eine neue Aufgabe eröffnet hat, ein storniertes Quellobjekt), legt die alte Aufgabe ab, ohne sie vorher zu lesen. Nötig sind ein **aktives** Projekt und das Recht, die Aufgabe zu ändern, als Redakteur oder höher oder als Mitglied, das sie angelegt hat oder dem sie zugewiesen ist (**403**, `PROJECT_ARCHIVED` oder `RBAC_FORBIDDEN`); die Aufgabe selbst darf archiviert sein — dafür ist die Wiederherstellung da. Der Body enthält genau `archived`; Titel, Beschreibung und Labels laufen über die Wiederholung der Aufnahme. Die Antwort ist die Aufgabe in ihrem neuen Zustand.

```bash
curl -sS --compressed -X PATCH "https://your-host.example.com/api/v1/projects/<projectId>/tasks/<taskId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'
# → 200 { "task": { "id": "<taskId>", "status": "in_progress", "archivedAt": 1789921403000, ... } }
```

### Kommentieren und Aufgabenstatus lesen

Melde zurück und lies den Zustand — der Kommentar erscheint als der Benutzer, der den Schlüssel erzeugt hat, ununterscheidbar von derselben Person in der App, @-Erwähnungen eingeschlossen. Projektleser einschließlich Mitgliedern dürfen eine aktive Aufgabe in einem aktiven Projekt kommentieren; eine archivierte Aufgabe verweigert den Kommentar mit **403**, `TASK_ARCHIVED`, so wie ein archiviertes Projekt mit `PROJECT_ARCHIVED`. Nach der Archivierung bleiben Aufgabe und Kommentare lesbar. Jede Aufgaben-URL wird von links nach rechts beurteilt: Ein fehlendes oder unsichtbares Projekt ergibt **404**, `PROJECT_NOT_FOUND`, und nur eine Aufgabe, die fehlt oder zu einem anderen Projekt gehört, ergibt `TASK_NOT_FOUND`.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/tasks/<taskId>/comments" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Filed. Confirmation 2026-8842." }'
# → 201 { "comment": { "id": "..." } }

curl -sS --compressed "https://your-host.example.com/api/v1/projects/<projectId>/tasks/<taskId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "task": { "id": "<taskId>", "title": "...", "status": "in_progress", "externalId": "case-991", "labels": [], "dueDate": 1790719200000, "repeat": null, ... } }
```

Eine gelesene Aufgabe enthält auch ihre Termine; über diese API lassen sie sich nur lesen. `startDate` und `dueDate` sind Unixzeit in Millisekunden und erscheinen nur, wenn sie gesetzt sind. Wählst du diese Termine in der App, speichert sie die Mitternacht zu Beginn des gewählten Kalendertags in der Zeitzone deines Browsers. `repeat` ist immer vorhanden: `null`, wenn sich die Aufgabe nicht wiederholt, sonst ein `TaskRepeat` wie `{ "frequency": "weekly", "interval": 2, "weekdays": [2, 4], "timezone": "Europe/Zurich", "createOn": "dueDate" }`. `frequency` ist `daily`, `weekly`, `monthly` oder `yearly`, und `interval` reicht von 1 bis 99; `weekly` nennt `weekdays` von 0 (Sonntag) bis 6 (Samstag), `monthly` einen `monthDay` und `yearly` einen `month` und einen `monthDay`. `createOn` erscheint nur, und zwar als `"dueDate"`, wenn die nächste Aufgabe auch zu Beginn des Fälligkeitstags entsteht; fehlt es, entsteht sie, wenn diese Aufgabe erledigt oder abgebrochen wird. Wird eine wiederkehrende Aufgabe abgeschlossen, in der App oder durch eine hier freigegebene Prüfung, oder beginnt unter `createOn: "dueDate"` ihr Fälligkeitstag, entsteht ihre nächste Aufgabe in `todo`, und `repeatNextTaskId` nennt sie von da an. Wird diese nächste Aufgabe gelöscht, fällt `repeatNextTaskId` weg, doch diese Aufgabe erstellt trotzdem keine weitere (Vertrag 3.3.0).

### Kommentare und Arbeitsergebnisse lesen

Beim Schreiben eines Kommentars wird `body` außen von Leerraum bereinigt und muss danach 1 bis 10.000 UTF-16-Codeeinheiten enthalten; die meisten Emojis zählen doppelt. Neben diesem ursprünglichen `body` kannst du optional `bodyByLocale` mitsenden. Beim Lesen wird es zurückgegeben, sofern vorhanden. Liefere inhaltlich gleichwertige, nicht leere Übersetzungen für `en`, `de` und `fr`; weitere Sprach- oder Sprachregionsschlüssel wie `nl`, `it` und `de-CH` sind erlaubt. Jeder Wert wird ebenso bereinigt und begrenzt; pro Kommentar sind bis zu 16 Sprachvarianten erlaubt. Zeige zuerst die genaue Spracheinstellung des Lesers, danach die Grundsprache, dann `en` und zuletzt `body` an. Als Autor bleibt der Schlüsselinhaber eingetragen. Eine reine Textbearbeitung in Tale entfernt die alten Übersetzungen, damit sie die Änderung nicht verdecken.

Aufgaben- und Workflow-Agenten erhalten die Anweisung, die Sprache aus Titel und Beschreibung der Aufgabe beizubehalten. Ist keine erkennbar, gilt die Standardsprache der Organisation für Agenten. Vorgegebene Wörter einer Titelvorlage, Quartalskennungen, die Sprache der Quelldokumente und die Oberflächensprache der startenden Person legen die Aufgabensprache nicht fest. Das gilt auch für Rückfragen, fortgesetzte Läufe und neue zugehörige Aufgaben. Dies sind Anweisungen an das Modell; gespeicherte Übersetzungen von Fortschrittsmeldungen erlauben Clients, die angezeigte Sprache unabhängig davon zu wählen.

Lies die Lauf-Ausgabe und die Kommentare, um die Ergebnisse der Automatisierung abzurufen. Ob sie zusätzlich Dateien erstellt und in welchem Ordner diese liegen, bestimmt der Workflow; aus dem Aufgabenstart allein folgt keine Ablage im Beispielordner.

Kommentare werden seitenweise geliefert: zuerst die neueste Seite, innerhalb jeder Seite chronologisch. `limit` ist standardmäßig 200 und höchstens 500. Solange `isDone` `false` ist, übergib `continueCursor` unverändert als `cursor`, um ältere Kommentare zu lesen. Das Token ist signiert und keine Seitennummer.

Der Content-Endpoint streamt die Bytes selbst (**200**, kein Redirect, dem du folgen müsstest), benannt über eine `Content-Disposition` nach RFC 6266; ein schlichtes `curl -o` legt die Datei also ab, und `--fail-with-body` macht aus einer Ablehnung einen Exit-Code ungleich null statt einer Datei voller JSON.

`Range` wird beachtet: Ein einzelner Bytebereich (`bytes=0-1023`, `bytes=1024-`, `bytes=-512`) antwortet **206** mit `Content-Range`; ein Bereich, der am oder hinter dem Dateiende beginnt — was `curl -C -` sendet, sobald die lokale Kopie vollständig ist —, antwortet **416** mit leerem Body und `Content-Range: bytes */<size>` mit der Größe, ein fortsetzender Worker erfährt also, dass er fertig ist; mehrere Bereiche oder ein `Range`, das der Server nicht lesen kann, werden ignoriert, und die ganze Datei antwortet **200**.

Ein `HEAD` antwortet mit denselben Kopfzeilen, die ein `GET` trägt — `Content-Length`, `Content-Type`, `ETag`, `Last-Modified`, `Accept-Ranges` —, ohne die Bytes, und ignoriert `Range`, ein Poller prüft also mit `curl -I` (nicht `curl -X HEAD`, das auf einen Body wartet) auf eine neue Version und sendet den `ETag` als `If-None-Match` zurück, um **304** zu bekommen, solange sich nichts geändert hat:

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/projects/<projectId>/tasks/<taskId>/comments?limit=100" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "comments": [ { "id": "...", "authorType": "agent", "body": "…", ... } ], "isDone": false, "continueCursor": "<opakes Token>" }

curl -sS --compressed --fail-with-body "https://your-host.example.com/api/v1/projects/<projectId>/files/<documentId>/content" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -o report.md
# → die Datei-Bytes (Content-Disposition trägt den Dateinamen)
```

## Fehlermodell

Ablehnungen der API verwenden normalerweise dieses flache JSON-Format. Antworten ohne Body, etwa `304` oder `HEAD`, und die oben beschriebenen frühen Ablehnungen am Proxy sind Ausnahmen:

```json
{ "error": "Automation not found", "code": "AUTOMATION_NOT_FOUND" }
```

Die [kompatiblen Modell-Endpunkte](https://docs.tale.dev/de/develop/api-reference#model-endpoints) sind die Ausnahme: Unter `/api/v1/openai` und `/api/v1/anthropic` kommt jede Ablehnung, auch die zu Authentifizierung und Ratenlimit, im Fehlerformat von OpenAI oder Anthropic und trägt dort denselben `code`.

`error` beschreibt das Problem für Menschen; `code` ist der stabile Wert für deine Programmlogik. Das OpenAPI-Schema `Error.code` enthält die bekannten Codes. Neue Codes können mit einem Minor-Release hinzukommen: Behandle unbekannte Werte anhand des HTTP-Status, statt die Antwort zurückzuweisen.

Das optionale Feld `data` ergänzt strukturierte Angaben, etwa `issues` bei ungültigen Eingaben, `retryAfterMs` bei einem Rate-Limit oder `providers` bei einem mehrdeutigen Modell. Werte bekannte Codes gezielt aus und verwende den Status als Rückfall:

**400: Korrigiere die Anfrage vor dem nächsten Versuch.** Ungültige Anfrageinhalte ergeben `INVALID_BODY` mit `data.issues`. Jedes Problem enthält einen Feldpfad wie `price` oder `contacts.2.email` und eine kurze Meldung, etwa `is required`, `must be a string`, `must not be blank`, `must be at most 200 UTF-16 code units` oder `must be one of "a", "b"`. Unbekannte Schlüssel werden unter ihrem eigenen Namen gemeldet. Verwende `code` für die Programmlogik; die Meldung ist für Menschen bestimmt.

Die Prüfung weist fehlende Pflichtwerte, falsche Typen, unbekannte Schlüssel, ungültiges JSON oder UTF-8, NUL-Zeichen, ungepaarte UTF-16-Surrogate, ganze Zahlen jenseits von 2^53 − 1 und Zahlen außerhalb ihres Feldbereichs ab. Ein Such-`limit` im JSON-Body wird bei Überschreitung abgewiesen, nicht begrenzt. Die API liest den Body unabhängig von `Content-Type` als JSON und liefert dafür kein 415.

| Weitere 400-Codes | Bedeutung und Korrektur |
| --- | --- |
| `INVALID_CURSOR` | Das Token stammt nicht aus dieser Liste. Beginne die Seitennavigation ohne Token neu. |
| `INVALID_LIMIT` | Ein Query-`limit` ist keine ganze Zahl. Ganze Zahlen außerhalb des Bereichs werden dagegen auf die Grenze begrenzt. |
| `INVALID_QUERY` | Ein anderer Query-Parameter ist ungültig. `data.issues` nennt den Parameter; Query-Fehler führen nie unbemerkt zur ersten Seite zurück. |
| `AUTOMATION_INPUT_INVALID` | Korrigiere die Eingabe anhand des `inputs`-Schemas und der `data.issues`. |
| `AUTOMATION_TRIGGER_INVALID` | Korrigiere einen nicht ausführbaren Trigger, etwa ein unmögliches Datum wie `0 0 30 2 *`. |
| `CONTACT_IDENTITY_REQUIRED` | Behalte mindestens ein Identitätsfeld des Kontakts. |
| `DOCUMENT_RECORD_FROZEN`, `DOCUMENT_RECORD_REPLACEMENT_REQUIRED` | Verwende den Ersetzungsablauf für gelenkte Dokumente statt einer direkten Inhaltsänderung. |
| `ORG_SLUG_REQUIRED` | Gib bei mehreren Mitgliedschaften die Organisation an. |
| `INVALID_HEADER` | Verwende nach dem Trimmen 1–255 druckbare ASCII-Zeichen für `Idempotency-Key`; `data.issues` nennt den Header. |
| `INVALID_URL` | Entferne NUL-Bytes (`%00`) aus Pfad oder Query. Diese Prüfung findet vor Routing und Anmeldung statt. |
| `BODY_CHUNK_MALFORMED` | Korrigiere die HTTP/1.1-Chunk-Kodierung im Client oder Proxy. Die Edge-Antwort hat eine eigene `requestId` und keinen Vertragsversionsheader. |
| `BODY_LENGTH_MISMATCH` | Unter HTTP/2 endete der Body vor der angegebenen `Content-Length`. Die Proxyantwort enthält eine neue `requestId`, aber kein `X-Tale-Api-Version`. |

- **401** — fehlender oder ungültiger API-Schlüssel (`UNAUTHORIZED`), mit einer `WWW-Authenticate: Bearer`-Challenge.
- **403** — die Rolle (`ROLE_FORBIDDEN`, `KNOWLEDGE_ENTRY_FORBIDDEN`) oder Projektbearbeitungsrechte fehlen, die Aufgabe eines anderen Mitglieds darf nicht geändert werden (`RBAC_FORBIDDEN`), die `teamIds` eines Dokuments oder Projekts benennen ein Team, dem der Besitzer nicht angehört (`TEAM_ACCESS_DENIED`), ein Skill würde mit der ganzen Organisation geteilt, obwohl die Organisation das vorbehält (`SKILL_PUBLISH_FORBIDDEN`), die gewünschte Änderung betrifft ein archiviertes Projekt oder eine archivierte Aufgabe (`PROJECT_ARCHIVED`, `TASK_ARCHIVED` — die `teamIds` eines Projekts eingeschlossen), die Automatisierung darf in diesem Projekt nicht laufen, oder `X-Organization-Slug` benennt eine Organisation, in der der Schlüsselbesitzer kein Mitglied ist (`ORG_FORBIDDEN`).
- **404** — die Ressource fehlt, ist für den Schlüsselbesitzer unsichtbar, gehört einem anderen Threadbenutzer oder liegt in einem anderen Projekt als dem der URL; jede Familie nennt ihren eigenen Code (`PROJECT_NOT_FOUND`, `DOCUMENT_NOT_FOUND`, `THREAD_NOT_FOUND`, …), ein `X-Organization-Slug`, der keine Organisation benennt, antwortet `ORG_SLUG_INVALID`, und eine unbekannte Route antwortet `NOT_FOUND` — sobald der Schlüssel geprüft ist: Ohne Schlüssel kommt die **401** der Schnittstelle zuerst, ein Pfad, den diese Schnittstelle nie bedient hat (etwa `/api/v1/openapi.json`), antwortet also ohne Schlüssel **401** und mit Schlüssel **404**; das Dokument selbst liegt unter `/openapi.json`, außerhalb der Schnittstelle und ohne Schlüssel.
- **405** — die Route existiert, aber nicht für dieses Verb (`METHOD_NOT_ALLOWED`); `Allow` nennt die Verben, die sie bedient.
- **409** — der Zustand verhindert die Aktion: keine bereitgestellte Version, eine gebundene Automatisierung ohne Projekt-URL, ein beim Löschen noch laufender Lauf (`RUN_ACTIVE`), ein `Idempotency-Key`, der mit anderem Body wiederverwendet wurde (`IDEMPOTENCY_KEY_REUSED`), ein archivierter Thread oder laufender Turn, ein Duplikat — die `email` oder `externalId` eines Kontakts (`CONTACT_DUPLICATE_EMAIL`, `CONTACT_DUPLICATE_EXTERNAL_ID`), der `name` oder die `externalId` eines Produkts (`DUPLICATE_PRODUCT_NAME`, `DUPLICATE_PRODUCT_EXTERNAL_ID`), das Thema eines Wissenseintrags (`KNOWLEDGE_ENTRY_DUPLICATE`), die `externalItemId` eines Projekts (`PROJECT_DUPLICATE_EXTERNAL_ID`) —, ein abgelöster Wissenseintrag (`KNOWLEDGE_ENTRY_SUPERSEDED`), ein veraltetes `expectedUpdatedAt` (`CONTACT_STALE`, `PRODUCT_STALE`, `DOCUMENT_STALE`), ein Dokument, hinter dem ein aktiver Wissenseintrag steht (`DOCUMENT_HAS_KNOWLEDGE_ENTRY` — lösche oder ändere stattdessen den Eintrag), ein erneutes Anstoßen einer Zustellung, die nicht als unzustellbar abgelegt ist (`DELIVERY_RETRY_UNAVAILABLE`), ein neuerer Konversationsinhalt für einen Kontakt im Papierkorb (`CONVERSATION_CONTACT_TRASHED`) oder eine Suche ohne Embedding-Modell.
- **412** — eine Vorbedingung ist gescheitert, und nichts wurde geschrieben: `If-Match` auf einem Skill, dessen `SKILL.md` sich seit deinem Lesen geändert hat, oder ohne gespeichertes Dokument (`SKILL_STALE` — `data.etag` nennt den aktuellen Tag, `null`, wenn nichts gespeichert ist); `If-None-Match: *` auf einem Skill-Slug, der schon ein Bundle hat (`SKILL_EXISTS`).
- **413** — der Body ist zu groß (`BODY_TOO_LARGE`; der Satz nennt die Grenze): jeder JSON-Body an seiner Grenze (1 MiB, sofern die Operation nichts anderes sagt — die Grenzen stehen oben), der Webhook-Trigger an seiner Grenze von 256 KiB (262.144 Bytes). Eine hochgeladene Datei, die die Größen- oder Typ-Policy verletzt, wird beim Binden stattdessen mit **400** und einem Reason-Code abgewiesen.
- **422** — ein Skill-Bundle, das die Dateischicht nicht lesen kann — ein eingeschleuster Symlink, eine Datei über der Staging-Grenze von 4 MiB, eine `SKILL.md`, die sich nicht parsen lässt (`SKILL_MALFORMED`): kommt von den Lesezugriffen und bei `PUT` nur für das Bundle, das schon unter dem Slug gespeichert ist — der Body, den du sendest, wird als **400** validiert (`INVALID_BODY`, `INVALID_SKILL`), ein JSON-Body allein löst die 422 also nie aus.
- **429** — Rate-Limit erreicht (`RATE_LIMITED`). `error` beschreibt die Wartezeit; `requestId` identifiziert die Anfrage. Warte vor dem nächsten Versuch die Dauer aus `Retry-After` in ganzen Sekunden oder `data.retryAfterMs` in Millisekunden ab. Siehe [Rate-Limits](https://docs.tale.dev/de/develop/rate-limits).

| Status | Bedeutung und nächster Schritt |
| --- | --- |
| **414** | die Anfrage-URL (Pfad und Query) übersteigt 32 KiB (`URI_TOO_LONG`); der Umschlag trägt eine `requestId`. |
| **408** | die Anfrage ist nicht binnen 15 Minuten vollständig angekommen, Kopfzeilen und Body zusammen (`REQUEST_TIMEOUT`); der Umschlag trägt eine frische `requestId` (die abgebrochene Anfrage hat nie eine eigene bekommen), und die Verbindung wird geschlossen — wiederhole über eine schnellere Leitung oder in kleineren Stücken. |
| **431** | die Anfrage-Kopfzeilen insgesamt übersteigen das 64-KiB-Budget des Edge; unter HTTP/1.1 kommt die Antwort ohne Umschlag und ohne `X-Request-Id`, weil der Parser des Edge sie schreibt, bevor irgendeine Route läuft (und erst nach ein paar KiB Spielraum — eine URL oder Kopfzeile knapp über dem Budget erreicht die Plattform noch und wird nach deren Regeln beurteilt, eine 66-KiB-URL antwortet **414**), unter HTTP/2, wo das Budget exakt gilt, wird die Verbindung geschlossen. |
| **500** | interner Fehler (`INTERNAL_ERROR`); der Umschlag trägt eine `requestId`, die du beim Melden nennst. |
| **503** | eine Abhängigkeit, die die Anfrage brauchte, ist nicht erreichbar: die Datenbank der Plattform, etwa während eines Neustarts (`DATABASE_UNAVAILABLE`, mit `Retry-After` und einer `requestId` — bei jeder Operation und beim Webhook-Trigger, auch bei der Schlüsselprüfung, sodass ein gültiger Schlüssel in dieser Zeit nie mit **401** abgelehnt wird), der Embedding-Anbieter (`EMBEDDING_UPSTREAM_ERROR`, mit `Retry-After`), der Objektspeicher hinter einem Datei-Download (`OBJECT_STORE_UNAVAILABLE`, mit `Retry-After`) oder ein Deployment ohne Objektspeicher (`OBJECT_STORE_UNCONFIGURED`), eine Dokumentbereinigung, die nicht abschließen konnte (`PURGE_INCOMPLETE`), oder ein Objektspeicher, der das Schreiben eines Wissenseintrags angenommen und binnen 30 Sekunden nie beantwortet hat (`KNOWLEDGE_ENTRY_STORE_TIMEOUT` — nichts wird geschrieben) — wiederhole mit Backoff. |
| **502**, **503**, **504** | am Edge beantwortet, während die Plattform neu startet oder nicht erreichbar ist (`UPSTREAM_UNAVAILABLE`, mit `Retry-After`, einer frischen `requestId` und ohne `X-Tale-Api-Version`), an jedem Maschinenzugang — `/api/*`, `/events`, `/status.json`, `/openapi.json`, `/.well-known/*`; eine Browser-Navigation bekommt stattdessen die Wartungsseite — wiederhole mit Backoff. |

Auch ein Dokument-`If-Match`, das nicht mehr zur gelesenen Darstellung passt, ergibt `412 PRECONDITION_FAILED`. `data.etag` nennt den aktuellen Tag; nichts wurde geschrieben.

Das Lösen eines Triggers einer vorhandenen Automatisierung (`DELETE .../triggers`) antwortet mit **204**, auch wenn kein Trigger gebunden war. Eine unbekannte Automatisierung ergibt **404**. Das Löschen einer fehlenden Ressource ergibt ebenfalls **404**, auch bei einem Kontakt im Papierkorb, einem bereits gelöschten Produkt oder einem bereits gelöschten Wissenseintrag. Das `DELETE` eines Kontakts verschiebt ihn in den Papierkorb (`POST /api/v1/contacts/{id}/restore` holt ihn zurück); das eines Produkts ist endgültig — Produkte haben weder Papierkorb noch Wiederherstellung, und Name wie `externalId` sind sofort wieder frei für ein neues Produkt, das eine neue Zeile mit neuer ID ist. Es nimmt das hochgeladene Bild des Produkts mit (ebenso ein `PATCH`, der `imageUrl` ersetzt oder entfernt), sofern kein anderes Produkt denselben Upload noch zeigt; unter einem aktiven Legal Hold — einer Organisationssperre oder einer Mitgliedssperre für die Person, die das Bild hochgeladen hat — wird das Löschen mit **409**, `LEGAL_HOLD_ACTIVE`, verweigert, und ein Patch behält das ersetzte Bild. Das Löschen eines aktiven Wissenseintrags legt jede Version seines Themas still und verschiebt das Dokument der Wissensdatenbank dahinter in den Papierkorb — und nimmt dessen Passagen sofort aus dem Suchkorpus; dieses Dokument direkt zu löschen wird verweigert. Ein unbekannter Lauf ergibt beim Abbrechen **404**; `{cancelled: false}` bedeutet, dass der Lauf existiert und bereits beendet ist.

Die vollständige Liste der Fehlercodes kannst du ohne Schlüssel lesen:

```bash
curl --fail --silent --show-error "$TALE_URL/openapi.json" \
  | jq -r '.components.schemas.Error.properties.code.enum[]'
```

## Versionierung

Drei Nummern beschreiben eine laufende Instanz, und sie bedeuten Verschiedenes. Der Build (`GET /api/health` antwortet mit ihm) ist das Release des Deployments. Der REST-Präfix, `/api/v1/`, ist die Kompatibilitätslinie: Eine Route darunter wird bedient, bis ein `/api/v2/` existiert und die Abschaltung von `/api/v1/` in den Release-Notes mindestens zwei Minor-Releases im Voraus angekündigt wurde, mit `Deprecation`- und `Sunset`-Kopfzeilen auf den auslaufenden Routen in der Zwischenzeit.

`info.version` in `/openapi.json` beschreibt den API-Vertrag nach Semver: Ein Minor-Release ergänzt etwa eine Operation, ein Feld, einen Header oder einen Fehlercode. Eine Entfernung oder Bedeutungsänderung verlangt ein Major-Release. `X-Tale-Api-Version` nennt die implementierte Vertragsversion in jeder API-Antwort; damit erkennt ein Client Versionsänderungen.

Das OpenAPI-Dokument enthält Routen sowie Anfrage- und Antwortschemas der laufenden Instanz. `servers` verweist auf diese Instanz; unter `/docs` findest du die gerenderte Referenz.

Nutze das OpenAPI-Dokument als Vertrag für deinen Client. Unter **API-Vertragsänderungen** nennen die Release-Notes jede Änderung mit vorherigem und neuem Verhalten; siehe [Release-Notes-Format](https://docs.tale.dev/de/self-hosted/operate/release-notes/format).

Einige Endpunkte sind bewusst nicht in diesem Dokument enthalten: `GET /api/health` ist der Liveness-Probe ohne Anmeldung (`{"status":"ok","version":"<build>"}`), `GET /status` und `/status.json` die eigene [Status-Seite](https://docs.tale.dev/de/develop/status-page) des Deployments, `/openapi.json` und `/docs` der Vertrag selbst; die [WebDAV](https://docs.tale.dev/de/develop/webdav-api)- und OpenID-Connect-Oberflächen (oben) sprechen ihre eigenen Protokolle.

Veröffentlichte Versionshinweise findest du auf [GitHub Releases](https://github.com/tale-project/tale/releases).

## Wo das hingehört

Über den [MCP-Endpoint](https://docs.tale.dev/de/develop/mcp-endpoint) greifen MCP-Clients auf Tale zu und erstellen oder bearbeiten Automatisierungen. Die [Webhooks-Anleitung](https://docs.tale.dev/de/develop/webhooks) beschreibt eingehende Trigger, die Läufe ohne API-Schlüssel starten. Für die Arbeit mit Projekt-Agenten und Automatisierungen in der App führt dich der Bereich [Plattform](https://docs.tale.dev/de/platform) weiter. Wie du Tale in opencode, Claude Code oder ein Shell-Skript holst, als Modellanbieter über die [kompatiblen Modell-Endpunkte](https://docs.tale.dev/de/develop/api-reference#model-endpoints) oder als Quelle für Wissen und Tools, beschreibt [Tale aus deinem Editor oder einem Skript nutzen](https://docs.tale.dev/de/develop/use-tale-from-your-editor).

# Compose-Dateien für Beiträge
Source: https://docs.tale.dev/de/develop/compose-files

Nutze die Compose-Dateien des Repositorys, um Tale aus dem Quellcode zu entwickeln oder zu testen. Im üblichen lokalen Ablauf [laufen App und Backend direkt auf dem Rechner, ihre Abhängigkeiten in Docker](https://docs.tale.dev/de/develop/contributor-setup). Wähle den folgenden Containerablauf, wenn deine Änderung die Entwicklungsimages prüfen soll.

Paketierte selbst gehostete Installationen verwenden den von der CLI erzeugten Stack aus dem [Schnellstart](https://docs.tale.dev/de/self-hosted/install/quickstart). Die Erweiterungsdateien im Quellbaum enthalten Entwicklungsports und Verzeichniseinbindungen. Prüfe sie, bevor du einen Host öffentlich erreichbar machst.

Wähle einen Ablauf für die zu prüfende Änderung. Native Entwicklung und Container-Frontend auf demselben Port führen zu einem Konflikt, nicht zu zwei isolierten Instanzen.

## Die Containerentwicklung starten

Führe die Befehle im Repository-Stamm mit der festgelegten Bun-Version und verfügbarem Docker Compose aus:

```bash
bun install
bun run docker:dev
bun run docker:dev:logs
```

`docker:dev` bereitet Image und Netzwerk der Sandbox vor, erzeugt eine Umgebungserweiterung und startet Basis-, Entwicklungs- und Docs-Konfiguration zusammen. Nutze diesen Einstieg statt nur seinen letzten Compose-Befehl zu kopieren: Die Vorbereitung gehört zum Ablauf. Die generierte Erweiterung reicht die meisten Hostvariablen an den Plattformcontainer weiter. Prüfe deshalb die Umgebung, aus der du sie startest.

Mit `Ctrl-C` beendest du die laufende Protokollanzeige. `bun run docker:dev:down` stoppt diesen Stack. Behalte Datenvolumes und die bestehende Umgebung, wenn du dieselbe Instanz später fortsetzen möchtest. Ein zweiter Worktree braucht eigene Ports, Containernamen und Speicher, um unabhängig zu laufen.

## Eine Erweiterungsdatei wählen

| Datei | Zweck |
| --- | --- |
| `compose.yml` | Basisdienste aus dem Quellcode und ihre Abhängigkeiten. |
| `compose.dev.yml` | Quellcodeeinbindungen und Entwicklungsbefehle. |
| `compose.docs.yml` | Dokumentationsseite und Proxyzuordnung. |
| `compose.web.yml` | Marketingseite und Proxyzuordnung. |
| `compose.test.yml` | Containertests der Plattform. |
| `compose.docs.test.yml` | Containertests der Dokumentation. |
| `compose.web.test.yml` | Containertests der Marketingseite. |
| `compose.test.mock.yml` | Integrationskonfiguration mit simulierten Diensten. |

Lies vor dem direkten Aufruf einer Testerweiterung das zugehörige Skript. Es kann Images, Ports und Testdaten vorbereiten. Die passenden Prüfungen beschreibt [An Docker arbeiten](https://docs.tale.dev/de/develop/contributing-docker).

## Die Zusammenführung prüfen

Compose wendet Dateien von links nach rechts an. Spätere Dateien überschreiben oder ergänzen frühere Einträge nach den Zusammenführungsregeln von Compose. So prüfst du die Dienstnamen, ohne die aufgelöste Umgebung samt Geheimnissen auszugeben:

```bash
docker compose -f compose.yml -f compose.dev.yml -f compose.docs.yml config --services
```

Der Befehl prüft die statischen Dateien. `docker:dev` ergänzt seine erzeugte Umgebungsdatei. Ein vollständiges `docker compose config` kann aufgelöste Zugangsdaten ausgeben. Halte diese Ausgabe aus öffentlichen Protokollen und Fehlerberichten heraus.

## Die wichtigsten Dienste verstehen

Der Quellcode-Stack trennt `backend-api` und `backend-worker`. Die API verarbeitet Anwendungsanfragen und Anmeldung; der Worker führt Aufgaben, Modellaufrufe und Wissensverarbeitung aus. `platform` stellt die Webanwendung bereit. `proxy` verteilt Anfragen; `db`, `knowledge-db` und `object-store` speichern Anwendungsdaten, Wissen und Dateien.

`sandbox`, `sandbox-egress` und `sandbox-llm-gateway` ermöglichen isolierte Ausführung samt Netzwerk- und Modellzugriff. Der Quellcode-Stack enthält außerdem den Hilfsdienst zur Videoverarbeitung. Die Produktivtopologie kann abweichen: Der generierte Einzelhost-Stack kombiniert Anwendungs- und Wissensdatenbank. Zuständigkeiten erklärt [Containerarchitektur](https://docs.tale.dev/de/self-hosted/operate/container-architecture), die Konfiguration die [Umgebungsreferenz](https://docs.tale.dev/de/self-hosted/configuration/environment-reference).

## Den ersten Fehler eingrenzen

Lies bei einer fehlgeschlagenen Vorbereitung den ersten Fehler des Startskripts, bevor du Compose wiederholst. Prüfe bei Imagefehlern Docker und den Imagebau, bei fehlendem Sandbox-Netz die Netzwerkerstellung und bei Konflikten mit einem zweiten Checkout belegte Ports oder vorhandene Container. Sieh dir `docker compose ps` und die Protokolle des betroffenen Dienstes an. Entferne keine Volumes, um einen Startfehler zu beheben: Damit geht der Zustand verloren, den du zur Reproduktion brauchst.

# Connectors
Source: https://docs.tale.dev/de/develop/connectors

Ein Connector stellt Tale einen wiederverwendbaren Zugriff auf einen Dienst bereit. Seine Definition beschreibt Authentifizierung, erlaubte Ziele und Aktionen; jede Organisation hinterlegt eigene Zugangsdaten. Diese Seite hilft dir, den Vertrag zu prüfen oder einen neuen Connector beizutragen.

Wenn du ein Konto in der Anwendung verbinden möchtest, nutze [Connector-Zugangsdaten](https://docs.tale.dev/de/platform/admin/connectors). Verfügbare Integrationen findest du im [Connector-Katalog](https://docs.tale.dev/de/platform/connectors/overview).

## Wie ein Connector deklariert wird

Definitionen liegen unter `configs/platform/system/connectors/<slug>/connector.yml`, zusammen mit dem Symbol des Connectors. Der Verzeichnis-Slug muss `name` entsprechen. Automatisierungen rufen Aktionen mit `<connector>.<action>` auf, etwa `tavily.search`. Anbieter-Connectoren erscheinen in den Einstellungen; interne Connectoren mit Plattformauthentifizierung nicht.

Dieser Ausschnitt aus der mitgelieferten Tavily-Definition zeigt Identität und Authentifizierung. Er ist kein vollständiger Connector: Die Aktionsdefinitionen fehlen hier bewusst.

```yaml
name: tavily
displayName: Tavily
description: Real-time web search and page extraction for AI research.
tags:
  - Search
allowedHosts:
  - api.tavily.com
auth:
  - method: api-key
```

### Erlaubte Ziele festlegen

| Feld | Bedeutung |
| --- | --- |
| `endpointMode: fixed` | Standard. Live-HTTP-Aufrufe verwenden feste Anbieter-URLs; `allowedHosts` enthält genaue Hostnamen |
| `endpointMode: per-credential` | Jeder Zugang enthält eine HTTPS-`endpointUrl`; Aktionen lesen den Ursprung ohne abschließenden Schrägstrich über `ctx.endpoint` |
| `allowedHosts` bei per-credential | Hostsuffixe: `atlassian.net` erlaubt seine Subdomains |
| `configFields` | Nicht geheime Angaben je Zugang, etwa Serverhost, Port, Region oder API-Version |

Confluence, GlitchTip und Shopify verwenden Ursprünge je Zugang. Geheimnisse gehören nicht in `configFields`, sondern in die verschlüsselten Zugangsdaten. Bei JavaScript-Aktionen setzt `ctx.http` die erlaubten HTTP-Ziele durch. Native Backends, etwa für Mailprotokolle, prüfen ihren Transport selbst; eine HTTP-Freigabeliste beschreibt nicht ihre gesamte Sicherheitsgrenze.

<Info>

Ein neuer Connector ist ein Quellcodebeitrag. Die Laufzeit liest den Plattformkatalog; Organisationen können keine Connector-Definition hochladen. Beginne mit der [Entwicklungsumgebung](https://docs.tale.dev/de/develop/contributor-setup) und prüfe vor der Umsetzung einen vorhandenen Connector mit ähnlicher Authentifizierung und ähnlichem Transport.

</Info>

## Was eine Aktion zusichert

| Feld | Vertrag für Autor und Aufrufer |
| --- | --- |
| `name`, `description` | Stabiler Aktionsname in snake_case und eine Erklärung zum Einsatzzweck |
| `input` | Objekt-JSON-Schema, vor der Ausführung validiert; Felder beschreiben und Pflichtfelder markieren |
| `output` | Ergebnissignatur im TypeScript-Stil; Dokumentation, keine Laufzeitvalidierung der Ausgabe |
| `effects` | `read` oder `write`; Schreibaktionen durchlaufen die Genehmigungsrichtlinie |
| `mock` | Erforderliches deterministisches JavaScript: gleiche Eingabe, gleiche Ausgabe, kein Netzwerkzugriff |
| `backend` | Optionale Live-Implementierung: `yaml-js` mit `live` oder `native` mit `impl`-Kennung |
| `exampleInput` | Optionales kleines, aussagekräftiges Beispiel für Erkennung und Tests |

Ohne Live-Backend läuft ein Connector nur mit Mocks und lehnt echte Aufrufe ab. Schreibaktionen werden nicht ausgeführt, wenn keine Genehmigungsentscheidung ermittelt werden kann. Die [Genehmigungsreferenz](https://docs.tale.dev/de/self-hosted/configuration/approvals) erklärt Vorrangregeln und ausstehende Entscheidungen.

Lies bei Ergebnisverträgen auch die Live-Implementierung. Tavily beschreibt beispielsweise `max_results` als Eingabe, begrenzt die zurückgegebenen Suchergebnisse aber auf fünf. Die Ausgabesignatur allein erklärt diese Grenze nicht.

### Das richtige Konto auswählen

Der Zugang wird beim Aufruf bestimmt: der ausdrücklich benannte, sonst der Standardzugang des Connectors. Ein geänderter Standard kann daher beeinflussen, welches Konto ein späterer Lauf nutzt. Benenne den Zugang ausdrücklich, wenn das Konto Teil deines Integrationsvertrags ist.

Für Postfächer gilt eine gezielte Ausnahme: `conversation.sync_mailbox` und `conversation.list_mailbox_messages` durchlaufen alle aktiven Zugänge des Connectors. So werden sämtliche verbundenen Postfächer berücksichtigt, nicht nur das Standardkonto.

## Die Authentifizierungsmethoden

Ein Connector kann mehrere Verfahren unterstützen; ein gespeicherter Zugang verwendet genau eines.

| Methode   | Bezeichnung in der Oberfläche | Was der Eintrag hält                                                                                                       |
| --------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `api-key` | API-Schlüssel                 | Ein einzelnes Secret, das der Aktionsrumpf selbst platziert — ein Anbieter-Header, ein Query-Parameter oder ein Body-Feld. |
| `bearer`  | Token                         | Ein Token, gesendet als Authorization-Header unter dem Schema, das der Connector nennt.                                    |
| `basic`   | Benutzername & Passwort       | Benutzername und Passwort als HTTP Basic — dieselbe Form, die auch ein Postfach-Login annimmt.                             |
| `oauth2`  | OAuth                         | Ein Authorization-Code-Grant: Access Token, Refresh Token, Ablauf und die erteilten Scopes.                                |

Das interne Verfahren `platform` hat keine gespeicherten Zugangsdaten und lässt sich nicht mit Anbieter-Verfahren kombinieren. Es ist nativen Plattformfunktionen wie Aufgaben- und Dokumentaktionen vorbehalten.

Geheimnisse werden verschlüsselt gespeichert. Listen liefern maskierte Vorschauen und Metadaten statt Klartext. Die autorisierte Live-Laufzeit löst das Geheimnis für den eigentlichen Aufruf auf. Erfolgreiches Speichern bestätigt nur die Ablage, nicht die Gültigkeit beim Anbieter oder ausreichende Berechtigungen.

## Eine OAuth-App registrieren

Der Connector deklariert Autorisierungs- und Token-URLs sowie angeforderte Berechtigungen. Konfiguriere zuerst die Anbieteranwendung und verbinde danach ein Konto darüber.

| Quelle | Vorrang und Einrichtung |
| --- | --- |
| Organisations-App | Hat Vorrang. Ein Administrator hinterlegt Client-ID und Geheimnis unter **Einstellungen > Connectoren > OAuth-Apps** |
| Deployment-App | Standard ohne Organisations-App: `CONNECTOR_OAUTH_<SLUG>_CLIENT_ID` und `CONNECTOR_OAUTH_<SLUG>_CLIENT_SECRET` |

Schreibe den Slug in Umgebungsvariablen groß und ersetze Bindestriche durch Unterstriche. Bei einer Microsoft-App für einen einzelnen Mandanten gehört die Verzeichnis-ID dazu, damit die Autorisierung diesen Mandanten statt `/common` nutzt. Organisationsgeheimnisse werden verschlüsselt und nicht erneut angezeigt.

### Die Callback-URL exakt registrieren

Alle OAuth-Connectoren der Organisation verwenden diese Redirect-URI:

```text
${SITE_URL}${BASE_PATH}/api/connectors/oauth2/callback
```

Schema, Host und Pfad müssen exakt übereinstimmen, einschließlich des fehlenden abschließenden Schrägstrichs. Ohne `SITE_URL` startet Tale die Einwilligung nicht; es leitet keine öffentliche Callback-URL aus der Anfrage ab. Ein `redirect_uri`-Fehler beim Anbieter deutet meist darauf hin, dass registrierte und gesendete URI voneinander abweichen.

Persönliche OneDrive-/Google-Drive-Importe für Wissen sind ein eigener Ablauf. Google Drive verwendet dieselbe OAuth-App für Connector und Import. Registriere deshalb beide Redirect-URIs beim Google-Client. Die Import-URL steht in der [Umgebungsreferenz](https://docs.tale.dev/de/self-hosted/configuration/environment-reference).

### Slacks Ereignisendpunkt einrichten

Die Slack-App wird ausschließlich für das Deployment konfiguriert: `CONNECTOR_OAUTH_SLACK_*` und `CONNECTOR_SLACK_SIGNING_SECRET`. Eingehende Ereignisse müssen geprüft werden, bevor Tale die Organisation kennt; eine Organisations-App kann dieses Geheimnis daher nicht bereitstellen.

Registriere `${SITE_URL}${BASE_PATH}/api/connectors/slack/events` als Events Request URL. Ohne Signaturgeheimnis erhält schon die Registrierung `503`. Mit gültiger Konfiguration prüft Tale Signaturen und ordnet den Slack-Workspace einer Organisation zu. Der Endpunkt bestätigt Ereignisse derzeit nur. Er macht aus eingehenden Slack-Nachrichten keine Konversationen und startet nicht automatisch eine Automatisierung.

## Die passende Oberfläche wählen

| Bedarf | Weg |
| --- | --- |
| Unterstützte Anbieteraktion | Mitgelieferter Connector mit Organisationszugang |
| Wiederverwendbare Aktion fehlt im Katalog | Quellcodebeitrag mit Schema, deterministischem Mock, Live-Backend und Tests |
| Projektspezifische Aufrufe deines Dienstes | Geheimnisse und Sandbox-Code eines Projektagenten, innerhalb der Netzwerkfreigaben der Sandbox |
| Eigene Logik in einer Automatisierung | `transform`-Knoten im Rahmen der Fähigkeiten und Netzwerkregeln des Runners |

Ein Geheimnis ermöglicht die Anmeldung, aber nicht die Erreichbarkeit eines privaten Dienstes. Prüfe den Netzwerkzugriff aus der tatsächlichen Sandbox oder dem Runner, bevor du deine Integration darauf aufbaust.

Externe MCP-Server lassen sich nicht registrieren. Über Tales [MCP-Endpunkt](https://docs.tale.dev/de/develop/mcp-endpoint) ruft ein externer Client Tale auf; dadurch entsteht kein ausgehender Connector zu einem anderen MCP-Server.

## Wo das hingehört

Prüfe bei einem Beitrag drei Bereiche getrennt: Schemavalidierung, deterministisches Mock-Verhalten und echte Anbieteraufrufe. Prüfe auch Fehlerfälle: fehlender Zugang, falsche Berechtigungen, gesperrtes Ziel, ungültige Eingabe, Anbieterfehler und ausstehende Genehmigung bei Schreibaktionen. Die [Entwicklungsanleitung](https://docs.tale.dev/de/develop/contributor-setup) beschreibt die lokale Umgebung, die [Zugangsdaten-Anleitung](https://docs.tale.dev/de/platform/admin/connectors) die Einrichtung durch Administratoren.

# Tale-Images bauen und pflegen
Source: https://docs.tale.dev/de/develop/contributing-docker

Baue ein Image, wenn du Container-Abhängigkeiten, Startverhalten oder den enthaltenen Anwendungscode änderst. Du brauchst einen Quellcode-Checkout nach [Entwicklungsumgebung einrichten](https://docs.tale.dev/de/develop/contributor-setup), einen laufenden Docker-Daemon und Zugriff auf die im Dockerfile verwendeten Image- und Paketregistries.

Ein erfolgreicher Build belegt, dass sich das Image erzeugen lässt. Starte es in einem getrennten Entwicklungsstack und prüfe das geänderte Verhalten, bevor du es bereitstellst.

## Die Images unterscheiden

Die Dockerfiles verwenden das Repository-Stammverzeichnis als Build-Kontext. Exakte Basisversionen und Build-Argumente stehen im jeweiligen Dockerfile. Die Tabelle erklärt die Aufgaben der Images.

| Image | Dockerfile-Verzeichnis | Inhalt und Aufgabe |
| --- | --- | --- |
| `tale-platform` | `services/platform/` | Debian-basiertes Anwendungsimage mit gebautem Webclient und nativem Backend. Build-Stufen nutzen Bun und Node; API und Worker verwenden dasselbe Image. |
| `tale-db` | `services/db/` | PostgreSQL mit den mitgelieferten Such- und Vektorerweiterungen auf ParadeDB-Basis. Anwendungs- und Wissensdatenbank nutzen es gemeinsam. |
| `tale-proxy` | `services/proxy/` | Caddy-Konfiguration und Proxy-Start. |
| `tale-sandbox` | `services/sandbox/` | Sandbox-Verwaltung mit Bun und Docker-CLI. |
| `tale-sandbox-runtime` | `services/sandbox-runtime/` | Python-basierte Ausführungsumgebung mit Coding-Harnesses, Node, Bun, Browsern und Dokumentwerkzeugen. |
| `tale-sandbox-egress` | `services/sandbox-egress/` | Alpine-basierter ausgehender Proxy mit DNS-Unterstützung. |
| `tale-sandbox-buildkitd` | `services/sandbox-buildkitd/` | BuildKit mit Netzwerk- und Startkonfiguration der Sandbox. |
| `tale-sandbox-llm-gateway` | `services/sandbox-llm-gateway/` | Modell-Gateway auf Bifrost-Basis. |

Objektspeicher und Sidecar für Videoverarbeitung verwenden direkt bereitgestellte Upstream-Images. Dafür gibt es kein Tale-Dockerfile. Sandbox-Runtime und BuildKit werden bei Bedarf gestartet. Ein Build der Compose-Dienste baut diese Images daher nicht automatisch mit.

## Lokal bauen

Führe diesen isolierten Proxy-Build im Repository-Stammverzeichnis aus:

```bash
docker build -f services/proxy/Dockerfile -t tale-proxy:docs-review .
```

Der lokale Tag `docs-review` unterscheidet das Ergebnis von einem veröffentlichten Release. Erst nach erfolgreichem Build kannst du es testen oder für die Weitergabe markieren.

Dienste mit einer `build:`-Definition in der Repository-Compose-Datei baust du so:

```bash
docker compose build platform
```

Ohne Dienstnamen wählt `docker compose build` alle Dienste mit einer Build-Definition. Dauer und Voraussetzungen hängen von Cache, Netzwerk, Zielplattform und Image ab. Ein Browser- oder Anwendungsimage braucht andere Schritte als der Proxy.

Die Repository-Compose-Datei setzt `PULL_POLICY` standardmäßig auf `build`. Erzeugte Produktionsdateien laden normalerweise Release-Images. Unter [Compose-Dateien](https://docs.tale.dev/de/develop/compose-files) findest du den vorgesehenen Entwicklungsstart, der auch zusätzliche Dienste und Images vorbereitet.

## Den passenden Änderungsort wählen

Wähle die kleinste Änderung, die deinen Bedarf erfüllt:

| Bedarf | Einstiegspunkt |
| --- | --- |
| Routing, TLS oder öffentliche Header | `services/proxy/Caddyfile` und Proxy-Konfiguration. Prüfe danach Rückleitungen und Streaming. |
| Oberfläche, Backend oder Extraktion | Anwendungscode unter `services/platform/`, anschließend Image-Build und passende Tests. |
| Pakete oder Browser in Agentensitzungen | `services/sandbox-runtime/Dockerfile`. Prüfe das geänderte Image in einer neuen Sitzung. |
| Ausgehende Sandbox-Verbindungen | Zuerst vorhandene Umgebungsoptionen; nur bei Bedarf Proxy-Vorlagen und Startcode. |
| BuildKit-Verhalten | `services/sandbox-buildkitd/` einschließlich der Netzwerkannahmen. |

Entrypoints, Zustandsprüfungen und interne Pfade gehören zum Implementierungsvertrag. Ein Fork muss Änderungen daran über Upgrades hinweg pflegen und testen. Reine Konfigurationsänderungen benötigen möglicherweise kein neues Image; siehe [Compose selbst betreiben](https://docs.tale.dev/de/self-hosted/install/own-compose).

## In deiner Registry veröffentlichen

Lege nach dem Test deinen Registry-Namensraum und einen unveränderlichen Tag fest. Dieses Beispiel veröffentlicht nur das zuvor gebaute Proxy-Image, keinen vollständigen Deployment-Satz. Du brauchst eine Registry-Anmeldung mit Schreibberechtigung.

```bash
export REGISTRY=registry.internal.example.com/tale
export IMAGE_TAG=reviewed-build-1
docker tag tale-proxy:docs-review "$REGISTRY/tale-proxy:$IMAGE_TAG"
docker push "$REGISTRY/tale-proxy:$IMAGE_TAG"
```

Notiere Digest, Quell-Commit und Build-Plattform. Stelle alle am Ziel benötigten Images bereit, auch Sandbox-Images und Upstream-Abhängigkeiten. Eine Offline-Umgebung braucht zusätzlich einen Plan für Pakete, Browser-Downloads und Modellzugriff. Ein einzelnes übertragenes Image macht das Gesamtsystem nicht unabhängig.

Die CLI liest den Tale-Image-Namensraum aus `GHCR_REGISTRY`. Die ausgewählte Version bestimmt weiterhin den Tag. Veröffentliche deshalb die Namen und Versionstags, die das Deployment erwartet. Unabhängig festgelegte Images und Quell-Commits beschreibt die [Referenz für verwaltete Deployments](https://docs.tale.dev/de/self-hosted/install/cli-install#managed-deployments).

## Mit Upstream aktuell bleiben

Versioniere deine Quelländerungen und prüfe Upstream-Änderungen vor dem nächsten Build. Halte Basisversionen oder Digests beim Build fest. Aktualisiere diese Referenzen bewusst: Ein unveränderter Pin lädt durch einen erneuten Build nicht automatisch eine neuere Version.

Prüfe vor der Bereitstellung Startrolle, Zustandsprüfungen, öffentliche Routen und die geänderte Funktion. Bei Sandbox-Änderungen gehören eine neue Sitzung und deren Netzwerkaufrufe dazu. Bringe allgemein nützliche Korrekturen möglichst upstream ein, damit dein Fork weniger eigenen Code pflegen muss.

## Build- und Startfehler eingrenzen

| Symptom | Nächste Prüfung |
| --- | --- |
| Eine Quelle für `COPY` fehlt | Nutze das Repository-Stammverzeichnis als vorgesehenen Kontext und prüfe `.dockerignore` sowie den Quellpfad. |
| Paket- oder Image-Download scheitert | Prüfe Registry-Zugriff, Anmeldung und den ersten fehlgeschlagenen Build-Schritt. |
| Das gebaute Image beendet sich beim Start | Lies die Container-Protokolle und prüfe Umgebung, Mounts und Rolle. |
| Eine Sandbox nutzt weiterhin alte Pakete | Prüfe das eingestellte Runtime-Image und starte eine neue Sitzung. Ein neuer Image-Tag ersetzt keinen laufenden Container. |

Die [Container-Architektur](https://docs.tale.dev/de/self-hosted/operate/container-architecture) erklärt Abhängigkeiten; [Upgrades](https://docs.tale.dev/de/self-hosted/operate/upgrades) beschreibt Bereitstellung und Wiederherstellung.

# Tale aus dem Quellcode starten
Source: https://docs.tale.dev/de/develop/contributor-setup

Starte Tale aus dem Quellcode, wenn du das Produkt ändern oder einen Beitrag testen möchtest. App und Backend laufen auf deinem Rechner; Datenbanken und Sandbox-Dienste laufen in Docker. Für eine fertige Installation folge dem [Schnellstart für selbst gehostete Instanzen](https://docs.tale.dev/de/self-hosted/install/quickstart).

## Rechner vorbereiten

Arbeite in einem lokalen Checkout des [Tale-Repositorys](https://github.com/tale-project/tale). Führe die folgenden Befehle im Stammverzeichnis aus.

| Voraussetzung | Aufgabe | Prüfung |
| --- | --- | --- |
| Bun-Version aus der `package.json` im Repository-Stamm | Workspaces, Abhängigkeiten, Vite und Entwicklungsskripte | `bun --version` |
| Node.js ab 22.21.1 innerhalb von 22.x | Anwendungsbackend; das Container-Image verwendet 22.21.1 | `node --version` |
| Docker mit Compose | Anwendungs- und Wissensdatenbank, Objektspeicher und Sandbox-Dienste | `docker info` und `docker compose version` |
| Freie lokale Ports | App auf 3000 und Backend auf 3005 | `bun run setup:check` |

Das Repository legt die Paketmanager-Version fest. Nutze sie beim Nachstellen eines Fehlers oder bei einer Lockfile-Änderung; die Startprüfung kontrolliert nur eine Mindestversion.

Die Vorabprüfung kontrolliert Bun und die beiden Ports. Prüfe Node und Docker separat; ein grünes Ergebnis bestätigt diese Voraussetzungen nicht. Beim ersten Start brauchst du außerdem Netzwerkzugriff für Abhängigkeiten und Container-Images. Für echte AI-Antworten brauchst du einen Modellanbieter, für die Anmeldung und das Erkunden der App noch nicht.

## Installieren und starten

Installiere die Abhängigkeiten, prüfe die lokalen Ports und starte die Entwicklungsumgebung:

```bash
bun install
bun run setup:check
bun run dev
```

Das Entwicklungsskript im Stammverzeichnis ergänzt fehlende Geheimnisse in der von Git ignorierten `.env` und behält vorhandene Werte bei. Schütze diese Datei und bewahre sie zwischen Neustarts auf: Backend und Sandbox brauchen dieselben Geheimnisse.

Der Orchestrator startet die Docker-Dienste und das Node-Backend, wartet auf API und Authentifizierung und startet danach Vite. Fehlt das Sandbox-Runtime-Image, etwa beim ersten Start oder nachdem du lokale Images entfernt hast, baut der Orchestrator es aus dem Quellcode, bevor das Backend startet. Dieser Schritt allein kann mehrere Minuten dauern; Agentensitzungen und das Ausführen von Code sind erst danach verfügbar. Das Backend führt beim Start die Datenbankmigrationen aus. Warte auf `READY`, bevor du `http://localhost:3000` öffnest; Downloads und die erstmalige Einrichtung können den ersten Start verlängern.

<Check>

Öffne die App und melde dich an. Das Dashboard bestätigt die Verbindung zwischen Browser und Backend. Sende mit einem eingerichteten Anbieter eine Nachricht, um auch einen Modellaufruf zu prüfen.

</Check>

Beende die Vordergrundprozesse mit `Ctrl-C`. Die Docker-Datenvolumes bleiben erhalten; das Beenden löscht die Instanz nicht.

## Am lokalen Workspace anmelden

Die lokale Entwicklungsumgebung legt `dev@tale.test` mit dem Passwort `TaleDev!Passw0rd` und der Organisation **Dev Workspace** an. Ein vorhandenes Konto bleibt unverändert. Diese Einrichtung ist auf Loopback-Adressen in `SITE_URL` beschränkt.

Setze `TALE_DEV_SEED_USER=0`, um stattdessen die Ersteinrichtung zu testen. Für eine andere lokale Identität übergib `TALE_DEV_SEED_USER_EMAIL` und `TALE_DEV_SEED_USER_PASSWORD` als Umgebungsvariablen. Neue Werte setzen das Passwort eines bestehenden Kontos nicht zurück.

## Passende Startweise wählen

Verwende für die normale Produktentwicklung `bun run dev`. Der Befehl startet Backend und App gemeinsam und stellt ihre gemeinsame Konfiguration bereit.

Laufen die benötigten Dienste bereits mit passenden Ports und Zugangsdaten, überspringe nur ihren Docker-Start:

```bash
TALE_DEV_SKIP_DOCKER=1 bun run dev
```

Dabei startet weiterhin ein lokales Backend. Postgres, Objektspeicher und Sandbox bleiben erforderlich. Nutze [Compose-Dateien für die Entwicklung](https://docs.tale.dev/de/develop/compose-files), wenn du den vollständigen Container-Build prüfen musst.

Für reine Frontend-Arbeit mit einem vorhandenen Backend starte Vite direkt aus `services/platform` und gib dessen Adresse an:

```bash
cd services/platform
TALE_BACKEND_URL=http://localhost:3005 bunx --bun vite --host 127.0.0.1 --port 3000
```

Dieser Befehl startet keine Dienste, legt keine Konten an und führt keine Migrationen aus. Das Backend muss den verwendeten Browser-Ursprung bereits erlauben.

## Startprobleme eingrenzen

| Symptom | Nächste Prüfung |
| --- | --- |
| `node` fehlt oder kennt eine Option nicht | Installiere die oben genannte Node-Version und prüfe den Aufruf in deiner Shell. |
| Docker stellt keine Verbindung her | Starte Docker und prüfe `docker info` in derselben Shell. |
| Port 3000 oder 3005 ist belegt | Ermittle den Prozess, bevor du ihn beendest; er kann zu einem anderen Checkout gehören. |
| Das Backend scheitert vor dem Vite-Start | Lies den ersten Backend-Fehler und prüfe Datenbankverbindung und Zugangsdaten. |
| Anmeldung funktioniert, Modellaufrufe scheitern | Prüfe Anbieterzugangsdaten, Modellwahl und Sandbox-Dienste. |
| Änderungen erscheinen in der falschen App | Prüfe die URL und den Checkout des laufenden Prozesses. |

Unter macOS oder Linux findest du die lauschenden Prozesse mit:

```bash
lsof -nP -iTCP:3000 -sTCP:LISTEN
lsof -nP -iTCP:3005 -sTCP:LISTEN
```

Beende einen bekannten Entwicklungsprozess in seinem ursprünglichen Terminal. Ein belegter Port allein ist kein Grund, einen Prozess zu beenden.

## Lokale Daten bewusst behalten oder zurücksetzen

Datenbanken und hochgeladene Dateien liegen außerhalb des Quellcode-Checkouts. Ein zweiter Git-Worktree trennt Docker-Dienstnamen, Ports, Volumes und `.env`-Zugangsdaten nicht automatisch. Gib parallelen Instanzen jeweils eigene Dienste und eine eigene Konfiguration.

Ein Zurücksetzen löscht Entwicklungsdaten und kann einen anderen Checkout mit demselben Compose-Projekt treffen. Prüfe Container und Volumes des Projekts, sichere benötigte Daten und stoppe die Umgebung, bevor du Zustand entfernst. Konfigurationsverzeichnisse unter `TALE_CONFIG_DIR` bleiben davon unabhängig; eine gelöschte Datenbank setzt diese Dateien nicht zurück.

## Vorhandene UI-Komponenten nutzen

Lies vor einer Änderung an der Oberfläche die [Dokumentation zum Design-System](https://ui.tale.dev). Sie erklärt `@tale/ui` für die App und `@tale/marketing-ui` für Marketing-Seiten anhand interaktiver Beispiele, Design-Tokens und Layoutmuster. Prüfe zuerst, ob eine vorhandene Paketkomponente deine Aufgabe erfüllt. Die Inhalte dieser Dokumentation sind auf Englisch.

## Einen Beitrag prüfen

Lies vor Änderungen `AGENTS.md` und `.agents/repo.md` im Repository. Führe während der Arbeit passende Prüfungen aus und danach die gemeinsame Prüfung im Stammverzeichnis:

```bash
bun run check
```

Sie umfasst Formatierung, Lint, Typen und automatisierte Tests. Die Python-Formatierung verwendet zusätzlich `uvx`; installiere dieses Werkzeug vor dem vollständigen Durchlauf. Prüfe Browser-Verhalten auch im Browser. Für Datenbankänderungen verlangt der Repository-Vertrag den Integrationstest mit echtem Postgres.

Aktualisiere betroffene Dokumentation und alle ausgelieferten Sprachen gemeinsam mit deiner Änderung. Für Container-Arbeit lies [Docker-Images bauen](https://docs.tale.dev/de/develop/contributing-docker); für externe Integrationen beginne mit [Tale aus einem Skript aufrufen](https://docs.tale.dev/de/tutorials/developer/call-tale-from-a-script).

# MCP-Endpoint
Source: https://docs.tale.dev/de/develop/mcp-endpoint

Verbinde einen MCP-Client, wenn ein Agent Tale-Tools entdecken, Wissen abrufen oder Automatisierungen entwickeln und ausführen soll. Die Verbindung verwendet denselben API-Schlüssel und Organisationskontext wie [REST](https://docs.tale.dev/de/develop/api-reference). Tale ist dabei der Server: Dein externer Client ruft Tale auf.

Beginne mit `initialize`, prüfe `tools/list` und rufe vor dem Schreiben einer Automatisierung `get_docs` auf. Deine Installation liefert ihre unterstützte Grammatik selbst. Der Client muss Knotentypen und Konfigurationsfelder deshalb nicht erraten.

## Einen Client verbinden

### Die Verbindung vorbereiten

Erstelle einen [API-Schlüssel](https://docs.tale.dev/de/platform/admin/api-keys) und hinterlege ihn in der sicheren Konfiguration deines Clients. Unter **Einstellungen > API > MCP** findest du Endpunkt, Organisations-Slug und eine kopierbare Anfrage zur Tool-Erkennung.

| Einstellung | Wert |
| --- | --- |
| Endpunkt | `https://your-host.example.com/api/v1/mcp` |
| Transport | HTTPS-POST mit JSON-RPC und normalen JSON-Antworten |
| Authentifizierung | `Authorization: Bearer <api-key>` |
| Organisation | `X-Organization-Slug: <slug>` |
| Protokollrevisionen | `2025-06-18` oder `2025-03-26`, wenn der Client diese vorschlägt |

Der Client muss entfernte HTTP-Endpunkte mit eigenen Headern unterstützen. Es gibt keinen SSE-Ereignisstrom, keine Sitzung zum Löschen und keinen OAuth-Anmeldeablauf. OAuth-Discovery-URLs antworten mit JSON und `404`; ein Client, der diesen Ablauf voraussetzt, braucht eine andere Authentifizierungskonfiguration. Ein reiner stdio-Client kann diese URL nicht direkt nutzen. Fertige Konfigurationen für opencode und Claude Code findest du unter [Tale aus deinem Editor oder einem Skript nutzen](https://docs.tale.dev/de/develop/use-tale-from-your-editor).

Sende in wiederverwendbaren Integrationen immer den Organisations-Header. Er ist nur bei genau einer Mitgliedschaft optional. Ohne ihn führt ein Schlüsselinhaber mit mehreren Organisationen zu `400 ORG_SLUG_REQUIRED`. Ein unbekannter Slug liefert `404 ORG_SLUG_INVALID`, eine Organisation ohne Mitgliedschaft `403 ORG_FORBIDDEN`. Jede dieser Ablehnungen nennt in `data.organizations` die Slugs, die du senden kannst.

### Initialisieren und die Referenz abrufen

Die Beispiele setzen `TALE_URL`, `TALE_API_KEY` und `TALE_ORG_SLUG` in deiner Umgebung voraus. `TALE_URL` ist die Anwendungsadresse ohne `/api/v1`.

```bash
curl --fail-with-body "$TALE_URL/api/v1/mcp" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"docs-client","version":"1.0.0"}}}'
```

Der Server meldet sich als `tale-platform`. Lies `result.protocolVersion` und sende den ausgehandelten Wert bei späteren Aufrufen als `MCP-Protocol-Version`. Das nächste Beispiel verwendet `2025-06-18`; passe ihn an, falls die ältere Revision ausgehandelt wurde. Ein nicht unterstützter Headerwert führt zu `400`.

```bash
curl --fail-with-body "$TALE_URL/api/v1/mcp" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --header 'MCP-Protocol-Version: 2025-06-18' \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_docs","arguments":{}}}'
```

Bei Erfolg enthält `get_docs` die Automatisierungsreferenz als Text, ohne gesetztes Fehlerkennzeichen. Mit `method: "tools/list"` erhältst du stattdessen die Tool-Schemas. Der aktuelle Katalog umfasst 22 Tools. Bewahre die JSON-RPC-`id`, damit dein Client Antwort und Anfrage zuordnen kann.

### Transport und Sammelanfragen

| Anfrage | Antwort |
| --- | --- |
| Einzelne JSON-RPC-Nachricht | Ein JSON-RPC-Ergebnis oder -Fehler |
| Bis zu 20 Nachrichten im Batch | Array mit Antworten; Benachrichtigungen erhalten keinen eigenen Eintrag |
| Nur Benachrichtigungen | HTTP `202` |
| `OPTIONS` | HTTP `204`, `Allow: POST, OPTIONS`; kein Schlüssel nötig |
| Andere HTTP-Methode | HTTP `405`, `Allow: POST, OPTIONS` |

Jeder zusätzliche Tool-Aufruf im Batch verbraucht dasselbe Anfragebudget wie ein eigener Aufruf. Ist das Budget erschöpft, enthält der betroffene Eintrag JSON-RPC `-32000` mit `data.retryAfterMs`. Die HTTP-Antwort bleibt `200` ohne `Retry-After`. Eine einzelne Anfrage, die bereits am HTTP-Eingang abgelehnt wird, erhält REST `429`. Behandle beide Fälle nach der [Referenz zu Ratenlimits](https://docs.tale.dev/de/develop/rate-limits).

Der Endpunkt liefert keine CORS-Header für API-Schlüssel in Webseiten. Bewahre den Schlüssel auf einem vertrauenswürdigen Server oder im Zugangsdaten-Speicher des MCP-Clients auf.

## Die Tools

`tools/list` liefert das Eingabeschema jedes Tools. Fehlende, falsch typisierte, leere oder unerwartete Argumente führen vor der Ausführung zu JSON-RPC `-32602`. Das Dokument in `validate_automation`, `run_automation`, `test_automation` oder `save_automation` hat bewusst eine offene Hülle: `get_docs` erklärt die Grammatik, die Engine validiert den Inhalt.

Tools liefern außerdem `readOnlyHint`, `destructiveHint`, `idempotentHint` und `openWorldHint`. Ein Host kann damit einen Aufruf erklären; die Hinweise erteilen aber weder Rechte noch Sicherheitsgarantien. Lesezugriffe sind als solche markiert, Speichern schreibt eine Version, Bereitstellung und Triggeränderungen können Bestehendes ersetzen. Live-Ausführungen können echte Dienste ansprechen.

### Automatisierungen entwickeln {#autorieren}

| Tool                  | Was es tut                                                               |
| --------------------- | ------------------------------------------------------------------------ |
| `get_docs` | Automatisierungsreferenz als Text abrufen: Grammatik, Knotentypen, Capability-Knoten und Methodentabelle für `tools/call`. |
| `get_catalog` | Unterstützte Knotentypen auflisten; `kind` filtert die Art, `compact: true` lässt Eingabeschemas weg. |
| `search_catalog` | Knotenkatalog nach Stichwörtern durchsuchen. |
| `validate_automation` | Ein Automatisierungsdokument validieren, ohne es zu speichern.           |
| `run_automation`      | Ein Automatisierungsdokument direkt gegen die deterministischen Mocks ausführen. |
| `test_automation`     | Die eigenen Abnahmetests einer Automatisierung ausführen.                |
| `save_automation`     | Ein Automatisierungsdokument als neue unveränderliche Version speichern. |
| `get_automation`      | Eine gespeicherte Version lesen — ohne Angabe die neueste, `version: "deployed"` die live geschaltete (`AUTOMATION_VERSION_UNKNOWN`, solange nichts deployt ist). |
| `list_automations` | Automatisierungen mit neuester und bereitgestellter Version sowie Installationsprojekten (`projectIds`) auflisten. |
| `deploy_automation` | Eine gespeicherte Version für Live-Ausführungen bereitstellen. |

Arbeite in dieser Reihenfolge: Grammatik und Katalog lesen, Dokument validieren, mit Mocks ausführen, Akzeptanztests ausführen, Version speichern und dann bereitstellen. Ein erfolgreicher Mock-Test bestätigt den simulierten Ablauf. Er bestätigt keine echten Zugangsdaten, Netzwerkverbindungen oder Auswirkungen beim Anbieter.

### Läufe und Trigger verwalten

| Tool             | Was es tut                                                                                                              |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `run_deployed` | Die bereitgestellte Version live ausführen und bis zu 30 Sekunden auf Ausgabe, Trace und Effekte warten. Läuft sie weiter, die zurückgegebene `runId` abfragen. Nimmt denselben optionalen `idempotencyKey` wie `start_run`, im selben Register wie die REST-Tür: eine Wiederholung antwortet mit dem ersten Lauf und `duplicate: true` und startet nichts — egal, welche Tür ihn gestartet hat. |
| `start_run` | Die bereitgestellte Version im Hintergrund starten; die zurückgegebene Lauf-ID mit `get_run` abfragen. Nimmt optional einen `idempotencyKey` — den `Idempotency-Key` der REST-Tür, dasselbe Register: derselbe Schlüssel mit denselben Argumenten antwortet mit dem Handle des ersten Laufs und `duplicate: true` und startet nichts, derselbe Schlüssel mit anderen Argumenten wird abgelehnt (`IDEMPOTENCY_KEY_REUSED`). Die HTTP-Kopfzeile `Idempotency-Key` weist dieser Endpoint ab (**400**, `INVALID_HEADER`) — ein Batch trägt bis zu 20 Aufrufe, der Schlüssel reist also in den Tool-Argumenten. |
| `list_runs` | Sichtbare Läufe einer Automatisierung oder über Projekte hinweg auflisten, neueste zuerst und jeweils mit `projectId`. |
| `get_run` | Status, Ausgabe, Trace, Effekte und `projectId` eines Laufs lesen. Die ID eines Projektlaufs passt zu `GET /api/v1/projects/{id}/runs/{runId}`. |
| `cancel_run` | Einen Lauf beim nächsten Übergang zwischen Knoten stoppen. |
| `list_versions`  | Die unveränderliche Versionshistorie einer Automatisierung; jede Zeile sagt, ob sie die `deployed` ist, und `deployedVersion` nennt sie neben der Liste (`null`, solange nichts deployt ist).                                                             |
| `list_triggers` | Triggerbindungen lesen, ohne das Webhook-Geheimnis auszugeben. |
| `delete_trigger` | Einen Trigger entfernen; Versionen und Laufhistorie bleiben erhalten. |
| `set_trigger` | Einen Zeitplan-, Webhook- oder Event-Trigger einrichten. Das `token` eines Webhooks wird einmal beantwortet, hier, und nie wieder — bewahr es auf; `deployed` sagt, ob Zustellungen laufen werden: Ein Trigger an einer Automatisierung ohne deployte Version wird gespeichert und löst nichts aus, bis eine deployt ist. |

| Tool | Geeignet für |
| --- | --- |
| `run_automation` | Ungespeichertes Dokument mit deterministischen Mocks ausprobieren; `mode: "live"` wird abgelehnt |
| `run_deployed` | Bereitgestellte Version live ausführen und bis zu 30 Sekunden warten; danach gegebenenfalls die `runId` abfragen |
| `start_run` | Bereitgestellte Version im Hintergrund starten und mit `get_run` verfolgen; mit `idempotencyKey` wird eine Wiederholung sicher |

Beide Tools für bereitgestellte Versionen verwenden denselben dauerhaften Runner mit denselben Berechtigungsprüfungen und Ausführungsdaten. `start_run` akzeptiert optional `projectId`. Eine projektgebundene Automatisierung darf nur in einem ihrer Installationsprojekte laufen; bei genau einer Bindung kann dieses automatisch gewählt werden. Ohne Bindungen bedeutet eine fehlende Angabe Organisationskontext. Lies `projectIds` aus `list_automations` und die tatsächliche `projectId` aus dem zurückgegebenen Handle, statt die REST-URL zum Abfragen zu erraten.

### Capabilities und Wissen

| Tool                  | Was es tut                                                                                                                                |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `search_capabilities` | Bereitgestellte Automatisierungen dieser Organisation nach Name und Beschreibung durchsuchen. |
| `invoke_capability` | Eine Capability über ihre `id` aufrufen. Ist eine Genehmigung erforderlich, liefert das Tool einen wartenden Genehmigungszustand, statt die Aktion auszuführen. |
| `get_knowledge` | Passagen aus Dokumenten und gecrawlten Websites der Organisation abrufen. `corpus` ist `private` (Dokumente), `public-web` (gecrawlte Seiten) oder `all`; die REST-Schreibweisen `documents` und `web` gehen auch. `query` ist auf 2000 Zeichen begrenzt. Jede Passage trägt `text`, `source` (einen Titel), `ref`, `corpus`, `chunkIndex`, `score`, `similarity`, wenn der dichte Zweig sie gefunden hat, `url` bei einer Webseite und — bei einem Dokument — die `documentId`, die `GET /api/v1/documents/{id}` nimmt (bei einem Projekttreffer die Datei-ID), sowie seine `projectId`: dieselbe Quellenangabe, die die REST-Suche liefert. |

Das Capability-Verzeichnis enthält derzeit bereitgestellte Automatisierungen. Integrierte Tools, Connector-Aktionen, Skills und externe MCP-Server gehören nicht dazu. Eine bereitgestellte Automatisierung aufzurufen entspricht derselben Live-Operation wie `run_deployed`. Wenn eine Genehmigung nötig ist, kann der Client anhand von `pending` erklären, dass zuerst ein Mensch entscheiden muss.

## Was der Schlüssel darf

| Vorgang | Erforderlicher Zugriff |
| --- | --- |
| Lesen, Validierung, Mock-Ausführungen und Akzeptanztests, Capability-Suche, Wissensabruf | Mitgliedschaft plus normale Zugriffsregeln der Ressource |
| Speichern, Bereitstellen, Trigger setzen/löschen, Lauf abbrechen oder live ausführen | Entwicklerberechtigung plus normale Zugriffsregeln der Ressource |

Der Schlüssel identifiziert seinen Inhaber. Er erweitert weder dessen Rolle noch dessen Projektzugriff. Auch eine Live-Ausführung über `invoke_capability` durchläuft die Ausführungsprüfungen.

Lies vor dem Einrichten privilegierter Tools `GET /api/v1/me`: `capabilities.developer` nennt die aktuelle Rollenberechtigung. `deploymentEditor` gehört dagegen zu einer separaten Freigabeliste des Betreibers und erteilt keine MCP-Bearbeitungsrechte. Tool-Fehler verwenden weiterhin das unten beschriebene MCP-Format; die REST-Berechtigungsabfrage ändert die JSON-RPC-Fehlerbehandlung nicht.

### Protokollfehler und abgelehnte Tools unterscheiden

| Ergebnis | Umgang damit |
| --- | --- |
| JSON-RPC `-32601` | Unbekannte Methode korrigieren |
| JSON-RPC `-32602` | Tool-Name oder Argumente anhand von `tools/list` korrigieren; ein Wert außerhalb einer aufgezählten Menge wird abgelehnt, und die Meldung nennt die Menge |
| Tool-Ergebnis mit `isError: true` | Stabilen `code`, erklärenden `error` und Handlungshinweis `hint` im Textinhalt lesen; `data` kann Feldprobleme enthalten |
| `validate_automation` mit `valid: false` | Normales Validierungsergebnis; `errors` auswerten, obwohl `isError` false bleibt |
| Capability mit `pending` | Normales Genehmigungsergebnis; weder als fertig noch als erneut zu versuchenden Fehler behandeln |
| Capability mit `refused` | Fehlerergebnis; die genannte Ursache beheben |

Zu den Tool-Codes gehören `AUTOMATION_NOT_FOUND`, `AUTOMATION_VERSION_UNKNOWN`, `AUTOMATION_NOT_DEPLOYED`, `RUN_NOT_FOUND`, `AUTOMATION_INVALID`, `AUTOMATION_TESTS_FAILING`, `LIVE_MODE_UNAVAILABLE` und `NOT_SUPPORTED`. Letzterer bedeutet, dass der Host den Vorgang für Läufe, Versionen oder Trigger nicht unterstützt. `start_run` lehnt einen wiederverwendeten `idempotencyKey` mit anderen Argumenten als `IDEMPOTENCY_KEY_REUSED` ab; `invoke_capability` lehnt eine ID, die das Register nicht führt — eine nur gespeicherte Automatisierung steht nicht darin —, als `CAPABILITY_NOT_FOUND` ab und Eingaben, die ihr Schema zurückweist, als `CAPABILITY_INPUT_INVALID`; `get_knowledge` reicht die eigenen Codes der Wissens-Tür durch (`KNOWLEDGE_UNAVAILABLE`, wenn die Suche selbst fehlgeschlagen ist). Plattformfehler behalten ihren eigenen Code, Hinweis und gegebenenfalls Daten; fehlender Entwicklerzugriff liefert etwa `FORBIDDEN_DEVELOPER_SETTINGS`.

Ein unbekannter Automatisierungsname ist auch bei `list_versions`, `list_runs` und `list_triggers` ein Fehler. Eine leere Liste bedeutet, dass eine vorhandene Automatisierung keine passenden Einträge hat. Die eine Ausnahme ist die Laufhistorie: Eine gelöschte Automatisierung behält ihre Läufe, `list_runs {name}` antwortet sie also, solange es sie gibt, und nur ein Name, der nie gelaufen ist, ergibt `AUTOMATION_NOT_FOUND`. `get_catalog`, auf eine Kern-Knotenart eingegrenzt (`transform`, `llm`, `agent`, `subautomation`), antwortet mit einer leeren Liste und einem `hint` auf `get_docs`, wie `search_catalog` auch. Ungültige Dokumente für Tools, die ein gültiges Dokument benötigen, fehlgeschlagene Suchen und fehlende Bereitstellungen setzen `isError: true`. Nur das Validierungstool meldet ein ungültiges Dokument als normales Prüfergebnis.

## Wo das hingehört

REST und MCP teilen Schlüssel, Organisationskontext und dauerhafte Ausführungsobjekte. Verwende REST für ausdrückliche HTTP-Routen und MCP für Clients mit Tool-Erkennung und Tool-Aufrufen. Über diesen Endpunkt registriert oder ruft Tale keine externen MCP-Server auf.

# Mit Tale entwickeln
Source: https://docs.tale.dev/de/develop/overview

Diese Anleitungen helfen dir, einen Client zu schreiben, ein externes System anzubinden oder Tale selbst zu ändern. Beginne mit einer kleinen, funktionierenden Anfrage. Ergänze danach Authentifizierung, Geltungsbereich und Fehlerbehandlung für deine Integration.

## Eine Entwicklungsaufgabe wählen

| Dein Vorhaben | Einstieg |
| --- | --- |
| Ein Skript schreiben, das eine Nachricht sendet und die Antwort liest | [Tale aus einem Skript aufrufen](https://docs.tale.dev/de/tutorials/developer/call-tale-from-a-script) |
| Einen Client für Projekte, Aufgaben, Dateien oder andere Ressourcen bauen | [API-Referenz](https://docs.tale.dev/de/develop/api-reference) |
| Einen MCP-Client verbinden | [MCP-Endpunkt](https://docs.tale.dev/de/develop/mcp-endpoint) |
| KI-Hilfe im Editor mit dem Wissen oder den Modellen von Tale | [Tale aus deinem Editor oder einem Skript nutzen](https://docs.tale.dev/de/develop/use-tale-from-your-editor) |
| Eine Automatisierung aus einem anderen System auslösen | [Webhooks](https://docs.tale.dev/de/develop/webhooks) |
| Über einen Dateisystem-Client auf Dokumente zugreifen | [WebDAV-API](https://docs.tale.dev/de/develop/webdav-api) |
| Einen Connector entwickeln | [Connector-Entwicklung](https://docs.tale.dev/de/develop/connectors) |
| Den Anwendungscode von Tale ändern | [Entwicklungsumgebung einrichten](https://docs.tale.dev/de/develop/contributor-setup) |

## Die erste Anfrage zuverlässig machen

Wähle die Zugangsdaten passend zur Schnittstelle: REST, MCP und die Modell-Endpunkte verwenden API-Schlüssel, WebDAV ein App-Passwort und Webhooks eine geheime Trigger-URL. Diese Zugangsdaten sind nicht austauschbar.

Erstelle für jede Integration einen eigenen API-Schlüssel. Sende ihn nur an die vorgesehene Instanz und speichere ihn nicht in der Versionsverwaltung. [Deine erste API-Anfrage](https://docs.tale.dev/de/get-started/developers) erklärt Instanz-URLs und den Organisationskontext. Bei längeren Vorgängen ist eine angenommene Anfrage noch kein fertiges Ergebnis: Frage die Ressource oder den Lauf ab und behandle auch fehlgeschlagene Ergebnisse.

Lies die [Ratenbegrenzungen](https://docs.tale.dev/de/develop/rate-limits), bevor du Wiederholungsversuche einbaust. Prüfe bei Verbindungsproblemen die [Verfügbarkeit der Instanz](https://docs.tale.dev/de/develop/status-page). Die API-Referenz beschreibt das Fehlerformat und die erzeugte Spezifikation des aktuellen Checkouts.

## Innerhalb der Plattform entwickeln

Für Agenten, Projekte und den Automatisierungseditor nutzt du den [Entwicklerleitfaden](https://docs.tale.dev/de/platform/developer/overview). [KI-gestützte Entwicklung](https://docs.tale.dev/de/develop/ai-assisted-development) erklärt, wie du Autorenwerkzeuge mit Validierung und Prüfung verbindest.

<Video src="https://docs.tale.dev/videos/de/tutorials/ep10-developers/ep10-developers.de.mp4" poster="https://docs.tale.dev/videos/de/tutorials/ep10-developers/ep10-developers.de.webp" captions="https://docs.tale.dev/videos/de/tutorials/ep10-developers/ep10-developers.de.vtt" lang="de" title="Bonus — Tale für Entwickler" caption="Bonus — Tale für Entwickler (2:38)">

</Video>

# Anfragelimits berücksichtigen
Source: https://docs.tale.dev/de/develop/rate-limits

Tale begrenzt API-Verkehr pro Schlüsselinhaber. Alle API-Schlüssel derselben Person teilen deren Budget. Berücksichtige daher sämtliche Integrationen und Polling-Prozesse dieser Identität, statt jeden Schlüssel einzeln zu planen.

Die folgenden Grenzen gelten für das aktuelle Backend. Ein vorgeschalteter Proxy oder nachgelagerter Anbieter kann zusätzliche Limits setzen.

## Die Budgets

Ein Token-Bucket füllt sich kontinuierlich bis zu seiner Burst-Kapazität auf. Eine kurze Serie kann diese Reserve nutzen; die dauerhafte Anfragerate muss innerhalb der Auffüllrate bleiben.

| Verkehr | Dauerhafte Rate | Burst | Budget gilt für |
| --- | --- | --- | --- |
| Allgemeine `/api/v1`-Aufrufe einschließlich MCP und Modell-Endpunkten | 120/Minute | 200 | Schlüsselinhaber |
| Laufstarts, Modellnachrichten und Aufgabenstarts | 20/Minute | 40 | Schlüsselinhaber |
| Upload-Freigabe und Dateizuordnung im Projekt | 240/Minute | 300 | Schlüsselinhaber |
| Fehlgeschlagene API-Schlüsselprüfung | 20/Minute | 40 | Quell-IP |
| Webhook-Zustellungen vor der Tokenprüfung | 120/Minute | 240 | Absenderadresse |
| Zustellungen an einen geprüften Webhook-Auslöser | 20/Minute | 40 | Auslöser |

REST-Ausführungen und Uploads verbrauchen zusätzlich das allgemeine Budget. Eine Projektdatei braucht beispielsweise eine Upload-Freigabe und eine anschließende Dateizuordnung. Beide Aufrufe zählen gegen allgemeines und Upload-Budget. Das größere Upload-Budget umgeht die allgemeine Grenze nicht.

Zur Ausführung gehören projektgebundene und globale Automatisierungsstarts, Thread-Nachrichten und ausdrückliche Aufgabenstarts. Die Aufgabenübernahme verbraucht ebenfalls Ausführungsbudget, wenn `runWorkflowSlug` gesetzt ist. Eine Arbeit-startende Anfrage wird belastet, sobald Body und Kopfzeilen die eigenen Prüfungen der Tür bestanden haben — eine `400 INVALID_BODY` oder `INVALID_HEADER` kostet nichts — und bevor irgendetwas nachgeschlagen wird, eine `404` für einen Thread, eine Aufgabe oder eine Automatisierung, die du nicht sehen kannst, kostet also ein Token, so wie eine `409`, die der Zustand antwortet. Manche Änderungen, etwa Aufgabenkommentare und Ordneränderungen, unterliegen weiteren Fachbereichslimits, die auch für die App gelten.

MCP-Batches rechnen zusätzliche Werkzeugaufrufe als zusätzliche Anfragen ab. Der [MCP-Endpunkt](https://docs.tale.dev/de/develop/mcp-endpoint) erklärt den Unterschied zwischen HTTP `429` und einer einzelnen abgelehnten Batch-Nachricht. Webhooks haben getrennte Budgets; sowohl Absender- als auch Auslöserlimit müssen die Zustellung zulassen.

Aufrufe der [Modell-Endpunkte](https://docs.tale.dev/de/develop/api-reference#model-endpoints) unter `/api/v1/openai` und `/api/v1/anthropic` zählen nur gegen das allgemeine Budget, jeweils als eine Anfrage, ob gestreamt oder nicht; was ein Aufruf ausgeben darf, begrenzen die Budgetregeln gesondert. Außerdem dürfen eine Person und jeder API-Schlüssel acht dieser Aufrufe gleichzeitig laufen haben: Ein neunter erhält `429` mit `code` `MODEL_API_CONCURRENCY_EXCEEDED` und `Retry-After: 2`.

Das Ausführungsbudget begrenzt, wie schnell Nachrichten angenommen werden, nicht die Zahl gleichzeitig laufender Antworten. Angenommene Chatnachrichten teilen sich eine Warteschlange über alle Organisationen und Schlüssel der Instanz. Ein Worker verarbeitet pro Durchgang bis zu `WORKER_CONCURRENCY` Antwortläufe, standardmäßig 5. Sein nächster Durchgang beginnt erst, wenn der aktuelle abgeschlossen ist. Eine erfolgreich angenommene Nachricht kann deshalb hinter anderen Clients warten. Die API liefert weder Warteschlangenposition noch geschätzten Startzeitpunkt.

## Die Antwort 429

Bei einer HTTP-Limitüberschreitung nennt `Retry-After` die Wartezeit in ganzen Sekunden. Der JSON-Body enthält dieselbe Wartezeit in Millisekunden. Dieses Beispiel verlangt mindestens zwei Sekunden Pause:

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json

{
  "error": "Too many requests — retry after 1500 ms",
  "code": "RATE_LIMITED",
  "requestId": "example-request-id",
  "data": {"retryAfterMs": 1500}
}
```

Entscheide anhand von `code`. `error` beschreibt die Wartezeit als Satz; `requestId` identifiziert die Anfrage für die Fehlersuche. Das ist das REST-Format. Bei `/api/app` und Webhook-Limits bleibt der maschinenlesbare Code in `error`; werte diesen Text daher nicht oberflächenübergreifend aus. Tale liefert keinen Restbudget-Zähler. Erfasse deinen Verkehr und beachte die vorgegebene Wartezeit.

1. Stoppe die unmittelbare Wiederholungsschleife.
2. Warte mindestens `Retry-After`. Teilen mehrere Prozesse die Identität, koordiniere ihre Pause.
3. Vergrößere bei weiteren Ablehnungen den Abstand exponentiell mit einer Obergrenze und einer zufälligen Streuung. Beispielsweise kann er von einer auf sechzig Sekunden wachsen; eine längere Servervorgabe hat Vorrang.
4. Behalte bei unterstützten Operationen den ursprünglichen Idempotenzschlüssel. Nach einem Timeout beim Laufstart kann der Lauf bereits angenommen worden sein.

Auch ein Ausgabenlimit antwortet mit `429`, dann mit `code` `BUDGET_EXCEEDED`: Eine Budgetregel, die für den Schlüsselinhaber gilt – seine eigene, die eines Teams, der Organisation oder des API-Schlüssels –, ist ausgeschöpft. Kurzes Warten hilft hier nicht. `Retry-After` nennt die Zeit bis zum Zurücksetzen des Zeitraums, und `data` beschreibt die Grenze: `scope`, `period`, `limitCode`, `used`, `limit` und `resetsAt` in Epoch-Millisekunden. Es wird nichts eingereiht. Pausiere die Arbeit bis `resetsAt` oder bitte eine Person mit Administratorrechten, das Limit unter [Richtlinien & Limits](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits) zu erhöhen. An den Modell-Endpunkten kommen beide `429` im Fehlerformat von OpenAI oder Anthropic, mit demselben `code` und `Retry-After`. Ein ausgeschöpftes Budget nennt seine Grenze dort in der Meldung statt in `data` und trägt `x-should-retry: false`, damit die SDKs der Anbieter es nicht selbst erneut versuchen.

Andere `4xx`-Antworten erfordern meist korrigierte Daten, Zugangsdaten oder Berechtigungen. Behandle nicht jeden Fehler als Limitüberschreitung; nutze das [Fehlermodell](https://docs.tale.dev/de/develop/api-reference#fehlermodell).

## Polling und Wiederholungen planen

Auch eine `304`-Antwort auf eine `ETag`-Prüfung zählt als Anfrage. Sie spart Datenvolumen, kein Budget. Ein Lauf, den du alle fünf Sekunden abfragst, braucht zwölf Leseaufrufe pro Minute, noch ohne Wiederholungen oder andere Arbeit. Reserviere Kapazität für diese zusätzlichen Aufrufe.

Fordere nur benötigte Felder an, etwa `?fields=status,finishedAt` bei einem Lauf. Frage seltener ab, wenn ein Mensch entscheiden muss, und beende Polling bei abgeschlossenen Läufen. [Einen Lauf starten und abfragen](https://docs.tale.dev/de/develop/api-reference#einen-lauf-starten-dann-pollen) erklärt Zustände und idempotente Starts.

Nutze bei größeren Importen unterstützte Sammelaufrufe wie `POST /api/v1/contacts/bulk` und verteile die Batches zeitlich. Weitere Schlüssel derselben Person vergrößern das Budget nicht. Benötigt ein Ablauf eine eigene Dienstidentität, richte sie über den normalen Konto- und Berechtigungsprozess ein. Schlüsselrotation ist keine Wiederholungsstrategie.

# Erreichbarkeit der Instanz prüfen
Source: https://docs.tale.dev/de/develop/status-page

Öffne `/status` auf deinem Tale-Host, um die Erreichbarkeit ohne Anmeldung zu prüfen. Überwachungssysteme lesen dieselbe Übersicht unter `/status.json`. Sie umfasst Backend und Bereitstellungsspeicher, bestätigt aber nicht die Funktion jedes Modells oder jeder organisationsspezifischen Verbindung.

## Das Statusdokument abrufen

Setze `TALE_BASE_URL` auf die Instanz-URL und frage ihren Status ab:

```bash
curl --fail-with-body --silent --show-error \
  "$TALE_BASE_URL/status.json"
```

Prüfe den JSON-Inhalt, nicht nur den HTTP-Status. Bei der lokalen Prüfung mit nicht erreichbarem Objektspeicher lieferte der Endpunkt HTTP `200` und dieses eingeschränkte Ergebnis:

```json
{
  "status": "degraded",
  "checkedAt": "2026-09-14T04:31:20.847Z",
  "components": [
    { "id": "backend", "status": "operational" },
    { "id": "database", "status": "operational" },
    { "id": "object-store", "status": "outage" }
  ]
}
```

Hier beantwortet die App Anfragen und erreicht ihre Datenbank; Dateioperationen müssen aber untersucht werden. Eine Überwachung, die jedes HTTP `200` als gesund wertet, übersieht diesen Fehler.

## Komponenten einordnen

| Feld oder Komponente | Bedeutung |
| --- | --- |
| `status: operational` | Alle gemeldeten Komponenten sind erreichbar. |
| `status: degraded` | Einige Komponenten sind nicht erreichbar. |
| `status: outage` | Alle gemeldeten Komponenten sind nicht erreichbar. |
| `checkedAt` | Zeitpunkt der Statusprüfung in UTC. |
| `backend` | Erreichbarkeit des Anwendungsbackends. |
| `database` | Zusammengefasster Zustand von Anwendungs- und Bereitstellungs-Wissensdatenbank. |
| `object-store` | Zustand des Dateispeichers der Bereitstellung. |

Komponenten melden `operational` oder `outage`. Antwortet das Backend nicht, lässt sich der Zustand abhängiger Speicher nicht feststellen; auch sie erscheinen als nicht erreichbar. Dein Parser sollte neue Komponenten-IDs akzeptieren.

## Eine Überwachung einrichten

Für eine automatisierte Prüfung benötigst du `jq`. Lass das Prüfergebnis den Exit-Status bestimmen: Das Beispiel schlägt bei Netzwerkfehlern, ungültigem JSON oder jedem Gesamtzustand außer `operational` fehl.

```bash
set -o pipefail
curl --fail-with-body --silent --show-error --max-time 10 \
  "$TALE_BASE_URL/status.json" | jq -e '.status == "operational"'
```


Der JSON-Endpunkt braucht keinen API-Schlüssel und verbraucht kein Schlüsselbudget. Sein Ergebnis bleibt fünf Sekunden zwischengespeichert. Speicherprüfungen im Backend werden separat aktualisiert; jede Abfrage startet deshalb nicht sofort einen neuen Speichertest. Setze eine Zeitüberschreitung und alarmiere nach deinem Betriebsbedarf bei wiederholten Fehlern oder einem eingeschränkten Zustand.

`/status.json` erlaubt ursprungsübergreifende Lesezugriffe mit `Access-Control-Allow-Origin: *`. `HEAD` liefert Kopfzeilen ohne Inhalt, `OPTIONS` nennt `GET, HEAD, OPTIONS`. Verwende `GET`, wenn die Überwachung die Komponenten auswerten soll.

## Prozessantwort und Funktionsbereitschaft unterscheiden

`/api/health` am produktiven Webserver ist eine kleine Prozessprüfung. Sie eignet sich für Container-Liveness, ersetzt aber nicht die Abhängigkeitsprüfungen des Statusdokuments. Ein Vite-Entwicklungsserver kann den Pfad anders weiterleiten und `404` liefern. Nutze dort `/status.json` für die laufende App.

Im produktiven Deployment prüft `/health` nur den Edge-Proxy: Er antwortet selbst mit `OK`, auch während die Anwendung neu startet. Eine unbekannte Route wie `/healthz` kann die App-Oberfläche mit HTTP `200` liefern. Beides ist keine Bereitschaftsprüfung der Plattform. Wähle je nach Prüfziel den dokumentierten Pfad `/status.json` oder `/api/health`.

Ein grüner Status prüft weder Guthaben noch Freischaltung oder Erreichbarkeit externer Modelle. Er führt auch keinen vollständigen Upload, keine Wissensabfrage, keinen Chat und keine Automation aus. Ergänze einen kontrollierten Ende-zu-Ende-Test für die Aktion, von der deine Integration abhängt.

## Einen Fehler untersuchen

Bei eingeschränkten Komponenten führt [Fehlerbehebung](https://docs.tale.dev/de/self-hosted/operate/observability/troubleshooting) zu den passenden Protokollen. Scheitert ein API-Aufruf bei gesundem Instanzstatus, prüfe den [API-Fehlercode](https://docs.tale.dev/de/develop/api-reference). `429` bezeichnet ein [Ratenlimit](https://docs.tale.dev/de/develop/rate-limits), keinen Instanzausfall.

Cloud-Instanzen bieten dieselben Statuspfade auf ihrem Host. Informationen zu Störungen und Nachweisen findest du unter [Vertrauen und Compliance](https://docs.tale.dev/de/cloud/trust-and-compliance).

# Tale aus deinem Editor oder einem Skript nutzen
Source: https://docs.tale.dev/de/develop/use-tale-from-your-editor

Tale lässt sich auf vier Wegen in deine Entwicklungsarbeit einbinden. Sie unterscheiden sich darin, welches Sprachmodell läuft und wie viel der Arbeit Tale steuert:

| Du möchtest | Weg | Modell | Was Tale steuert |
| --- | --- | --- | --- |
| Die Modelle deiner Organisation als Modellanbieter von opencode, Claude Code oder einem SDK-Skript | [Die Modell-Endpunkte](https://docs.tale.dev/de/develop/use-tale-from-your-editor#model-endpoints) | Ein Modell der Organisation, das du in jeder Anfrage mit seiner ID nennst | Jeden Modellaufruf: Modellzugriff, Eingabe-Guardrails, Budgets, Verbrauch unter deinem Namen und Schlüssel; nicht die Antworten |
| Den eingebauten Assistenten aus einem Skript fragen | [Die REST-Chat-API](https://docs.tale.dev/de/develop/use-tale-from-your-editor#die-rest-chat-api-aus-einem-skript-nutzen) | Ein Modell der Organisation, das du in jeder Anfrage nennst | Den ganzen Turn: Modellzugriff, Budgets, Verbrauch unter deinem Namen |
| Wissen und Automatisierungs-Tools von Tale in opencode oder Claude Code | [Der MCP-Endpoint](https://docs.tale.dev/de/develop/use-tale-from-your-editor#opencode-oder-claude-code-verbinden) | Das Modell, das in deinem Editor eingerichtet ist | Nur die Tool-Aufrufe; die Modellaufrufe des Editors laufen an Tale vorbei |
| Ein Skript mit den Modellen deiner Organisation bearbeiten lassen | [Ein Projektagent an einer Aufgabe](https://docs.tale.dev/de/develop/use-tale-from-your-editor#skripte-von-einem-projektagenten-bearbeiten-lassen) | Das Modell der Organisation, mit dem der Agent eingerichtet ist | Den ganzen Lauf: Sandbox, Budgets, Verbrauch, Prüfung |

Ein Editor kann zwei davon mit demselben Schlüssel nutzen: die Modell-Endpunkte als Modellanbieter und den MCP-Endpoint für das Wissen von Tale. [Der letzte Abschnitt](https://docs.tale.dev/de/develop/use-tale-from-your-editor#was-aus-dem-openai-kompatiblen-endpunkt-wurde) erklärt, worin sich die Modell-Endpunkte von der OpenAI-kompatiblen Schicht aus Tale 0.3 unterscheiden.

## Einen API-Schlüssel erstellen

Jeder Zugriff von außerhalb der App beginnt mit einem persönlichen API-Schlüssel. Inhaber, Admins und Entwickler erstellen ihn unter **Einstellungen > API > REST** mit **API-Schlüssel erstellen** und legen dabei Namen und Ablaufzeit fest. Das kann auch ein Mitglied, dem ein Admin eine Kompetenz zugewiesen hat, die mit einem Schlüssel genutzt wird, etwa **Modelle über die API aufrufen**. Der geheime Wert erscheint nur einmal. Kopiere ihn in deinen Secret-Speicher oder eine private Shell-Umgebung, bevor du den Dialog schließt. [API-Schlüssel](https://docs.tale.dev/de/platform/admin/api-keys) beschreibt Erstellen, Rotieren und Widerrufen.

Ein Schlüssel handelt in deinem Namen. Er trägt deine aktuelle Rolle und deinen Projektzugriff, und der Verbrauch, den er verursacht, wird dir zugeordnet. Chat-Turns, Modellaufrufe und Automatisierungsläufe, die du mit dem Schlüssel startest, erfassen zusätzlich den Schlüssel, sodass auch API-Schlüssellimits für sie gelten. Ein Lauf eines Projektagenten wird nur dir zugeordnet. Ein Admin kann deine Ausgaben mit einem persönlichen, Team- oder Rollenbudget unter [Richtlinien und Limits](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits) begrenzen. Eine Anfrage über der Grenze lehnt Tale mit `429 BUDGET_EXCEEDED` ab.

Die Beispiele auf dieser Seite lesen drei Umgebungsvariablen. `TALE_URL` ist der Ursprung deiner Instanz ohne `/api/v1`. `TALE_ORG_SLUG` ist der Slug der Organisation; du findest ihn unter **Einstellungen > API > MCP**, unter **Einstellungen > API > Modelle**, sobald die Modell-Endpunkte eingeschaltet sind, und in der Antwort von `GET /api/v1/me`. Exportiere alle drei in deiner Shell. `TALE_API_KEY` gehört in keine Datei, die du committest.

## Die Modelle deiner Organisation aus deinen Tools nutzen {#model-endpoints}

Mit den Modell-Endpunkten verwenden opencode, Claude Code und Skripte, die auf den SDKs von OpenAI oder Anthropic aufbauen, die freigegebenen Modelle deiner Organisation als Modellanbieter. Tale spricht die Schnittstellen OpenAI Chat Completions und Anthropic Messages, die diese Tools ohnehin nutzen. Du änderst also Basis-URL, Schlüssel und Modellnamen, nicht deinen Code. Jede Anfrage ist ein reiner Modellaufruf: Weder der eingebaute Assistent noch ein Thread noch ein Tool von Tale ist beteiligt, und die Antwort kommt so zurück, wie das Modell sie geschickt hat.

### Voraussetzungen

Die Endpunkte sind ausgeschaltet, bis ein Admin unter **Einstellungen > Richtlinien > Modelle** den Schalter **Modell-Endpunkte für API-Schlüssel** einschaltet; [Modelle](https://docs.tale.dev/de/platform/admin/governance/content-models#model-endpoints) beschreibt ihn. Danach dürfen Inhaber, Admins und Entwickler sie über ihre Rolle aufrufen. Jedes andere Mitglied braucht die Kompetenz **Modelle über die API aufrufen**, die ein Admin unter [Kompetenzen](https://docs.tale.dev/de/platform/admin/governance/competences) zuweist. `GET /api/v1/me` antwortet mit `capabilities.modelApi: true`, sobald dein Schlüssel sie aufrufen darf.

**Einstellungen > API > Modelle** bündelt, was deine Tools brauchen: beide Basis-URLs, den Organisations-Slug, die Modelle, die du aufrufen kannst, mit einer Kopierschaltfläche für jede ID, und Konfigurationen zum Kopieren für opencode, Claude Code und das OpenAI-SDK für Python. Solange deine Organisation die Endpunkte nicht eingeschaltet hat, zeigt der Tab **Die Modell-Endpunkte sind für deine Organisation nicht aktiviert**; Inhaber und Admins finden dort **Modellzugriff öffnen**.

<Frame caption="Einstellungen > API > Modelle — die Basis-URLs, der Organisations-Slug und die Modelle, die du aufrufen kannst.">

![Der Tab Modelle unter Einstellungen > API mit den OpenAI- und Anthropic-kompatiblen Basis-URLs, dem Authorization-Header für einen API-Schlüssel, dem Organisations-Slug northlight-labs und fünf Modell-IDs mit je einem Kopierknopf.](https://docs.tale.dev/images/develop/settings-api-models.webp)

</Frame>

### Verbindungsdaten

| Angabe | Wert |
| --- | --- |
| OpenAI-kompatible Basis-URL | `https://<host>/api/v1/openai`; die OpenAI-SDKs und opencode hängen `/chat/completions` an |
| Anthropic-kompatible Basis-URL | `https://<host>/api/v1/anthropic`; die Anthropic-SDKs und Claude Code hängen `/v1/messages` an |
| Schlüssel | Dein persönlicher API-Schlüssel als `Authorization: Bearer <key>`. Tale lehnt den Header `x-api-key` mit `401` ab; ein Anthropic-Client muss den Schlüssel deshalb als Auth-Token senden |
| Organisation | `X-Organization-Slug: <slug>`, nötig, wenn du mehreren Organisationen angehörst |
| Modell | `<providerSlug>/<modelId>`: der Slug des Anbieters, ein Schrägstrich und die ID des Modells im Katalog dieses Anbieters, etwa `openrouter/anthropic/claude-sonnet-4.6` oder `deepseek/deepseek-v4-flash` |

Dieselbe ID gilt an beiden Endpunkten. Prüfe den Schlüssel und liste die IDs, die du aufrufen darfst; setze dabei deinen Host und deinen Slug statt `tale.example.com` und `acme` ein:

```bash
curl https://tale.example.com/api/v1/openai/models \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: acme"
```

Die Antwort ist eine Modellliste im OpenAI-Format: `owned_by` ist der Slug des Anbieters, `created` ist immer `0`. Sie sieht etwa so aus, mit den IDs, die deine Organisation dir anbietet:

```json
{
  "object": "list",
  "data": [
    { "id": "openrouter/anthropic/claude-sonnet-4.6", "object": "model", "created": 0, "owned_by": "openrouter" },
    { "id": "deepseek/deepseek-v4-flash", "object": "model", "created": 0, "owned_by": "deepseek" }
  ]
}
```

Die Liste enthält die Chatmodelle deiner Organisation, die Anbieter-Zugangsdaten vom Typ **API-Schlüssel** oder **Umgebungsvariable** bereitstellen, eingeschränkt durch die erlaubten Modelle der jeweiligen Zugangsdaten und durch deinen Modellzugriff. Modelle, die über Abonnement-Zugangsdaten laufen, fehlen darin, ebenso Modelle eines Anbieters, dessen Endpunkt je Zugangsdaten-Eintrag festgelegt wird, etwa Azure, und Modelle, die Tools nur über die Responses-API von OpenAI aufrufen, etwa GPT-6.1 Sol, denn diese Endpunkte leiten sie nicht weiter. `GET /api/v1/models` nennt für jedes dieser Modelle Kontextfenster, Fähigkeiten und Preise, unter demselben `providerSlug` und derselben `id`.

### opencode auf Tale ausrichten

Trag Tale als Anbieter in deine globale `opencode.json` oder in die des Projekts ein. opencode erreicht Tale über sein OpenAI-kompatibles Paket und liest den Schlüssel aus `TALE_API_KEY`. Führe unter `models` jedes Modell, das du wählen willst, mit seiner ID auf; `model` legt den Standard fest, als `tale/` gefolgt von dieser ID.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "tale": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Tale",
      "options": {
        "baseURL": "https://tale.example.com/api/v1/openai",
        "apiKey": "{env:TALE_API_KEY}",
        "headers": { "X-Organization-Slug": "acme" }
      },
      "models": {
        "openrouter/anthropic/claude-sonnet-4.6": { "name": "Claude Sonnet 4.6" }
      }
    }
  },
  "model": "tale/openrouter/anthropic/claude-sonnet-4.6"
}
```

Der Block `provider` kann in derselben Datei neben dem Block `mcp` aus der [MCP-Konfiguration](https://docs.tale.dev/de/develop/use-tale-from-your-editor#opencode) stehen. Starte opencode aus einer Shell, in der `TALE_API_KEY` gesetzt ist.

### Claude Code auf Tale ausrichten

Claude Code liest seinen Modellanbieter aus Umgebungsvariablen. Setze sie in der Shell, aus der du es startest:

```bash
export ANTHROPIC_BASE_URL="https://tale.example.com/api/v1/anthropic"
export ANTHROPIC_AUTH_TOKEN="$TALE_API_KEY"
export ANTHROPIC_CUSTOM_HEADERS="X-Organization-Slug: acme"
export ANTHROPIC_MODEL="openrouter/anthropic/claude-sonnet-4.6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="openrouter/anthropic/claude-haiku-4.5"
unset ANTHROPIC_API_KEY
claude
```

`ANTHROPIC_AUTH_TOKEN` sendet den Schlüssel als Bearer-Token. Lass `ANTHROPIC_API_KEY` ungesetzt: Claude Code würde ihn als `x-api-key` senden, und diesen Header lehnt Tale ab. `ANTHROPIC_DEFAULT_HAIKU_MODEL` ist das Modell, das Claude Code für Hintergrundaufgaben nutzt; beide Modellvariablen müssen IDs aus deiner Liste nennen. Das Tool WebSearch von Claude Code lässt die Suche vom Modellanbieter selbst ausführen, deshalb lehnt Tale solche Anfragen ab. Die Tools, die Claude Code auf deinem Rechner ausführt, funktionieren wie gewohnt.

### Die Modelle aus einem Skript aufrufen

Das OpenAI-SDK für Python braucht eine andere Basis-URL und den Organisations-Header. Das Beispiel liest den Schlüssel aus `TALE_API_KEY`, fragt einmal eine vollständige Antwort ab und streamt dann eine zweite:

```python
import os

from openai import OpenAI

client = OpenAI(
    base_url="https://tale.example.com/api/v1/openai",
    api_key=os.environ["TALE_API_KEY"],
    default_headers={"X-Organization-Slug": "acme"},
)
MODEL = "openrouter/anthropic/claude-sonnet-4.6"

reply = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "Was bedeutet der Cron-Ausdruck 0 3 * * 1?"}],
)
print(reply.choices[0].message.content)

stream = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "Schreib eine Commit-Nachricht für eine Tippfehlerkorrektur."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
print()
```

Tools, `tool_calls` und Bilder funktionieren wie bei OpenAI, und `model` in der Antwort ist die ID, die du gesendet hast. Ein Stream endet mit `data: [DONE]`; den abschließenden Chunk mit dem Verbrauch erhältst du nur, wenn du `stream_options={"include_usage": True}` übergibst.

Das Anthropic-SDK für Python nimmt den Schlüssel als Auth-Token. Führe es mit ungesetztem `ANTHROPIC_API_KEY` aus, denn das SDK würde den Wert dieser Variable als `x-api-key` senden, und diesen Header lehnt Tale ab:

```python
import os

import anthropic

client = anthropic.Anthropic(
    base_url="https://tale.example.com/api/v1/anthropic",
    auth_token=os.environ["TALE_API_KEY"],
    default_headers={"X-Organization-Slug": "acme"},
)

message = client.messages.create(
    model="openrouter/anthropic/claude-sonnet-4.6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Erkläre den Fehler ECONNRESET in einem Absatz."}],
)
print(message.content[0].text)
```

### Was Tale bei jedem Aufruf prüft

Jeder Aufruf wird wie eine Chat-Anfrage geprüft, und zwar für die Person, deren Schlüssel ihn gesendet hat:

- **Schalter und Recht.** Die Organisation hat die Endpunkte eingeschaltet, und deine Rolle oder Kompetenz erlaubt dir den Aufruf.
- **Das Modell.** Es muss auf deiner Liste stehen, und der Modellzugriff der Organisation muss es dir zum Zeitpunkt des Aufrufs erlauben. Die erlaubten Modelle der Anbieter-Zugangsdaten gelten ebenfalls.
- **Was das Modell lesen kann.** Bilder verlangen ein Modell, das Bilder lesen kann, Tools ein Modell, das Tools annimmt. Bilder kommen als OpenAI-Teile `image_url` mit einer `data:`- oder `https:`-URL oder als Anthropic-Blöcke `image` in Base64 oder mit einer `https:`-URL, auch in Tool-Ergebnissen. Dokumente kommen als OpenAI-Teile `file` oder als Anthropic-Blöcke `document`.
- **Die Eingabe-Guardrails.** Inhaltssicherheit, PII-Schutz und Moderationsanbieter der Organisation lesen jeden Text der Anfrage, bevor Tale sie weitergibt: System- und Entwickleranweisungen, deine Turns und die des Assistenten, Tool-Aufrufe, Tool-Ergebnisse und Tool-Definitionen sowie Dokumente, die als Text mitkommen. Blockieren lehnt die Anfrage ab, Maskieren schickt dem Modell den maskierten Text. Nicht gefiltert werden die Antworten des Modells sowie Bilder und Dokumente, die kein Text sind. Einzelheiten stehen unter [Guardrails](https://docs.tale.dev/de/platform/admin/governance/guardrails#model-endpoints).
- **Die Budgets.** Vor dem Aufruf ermittelt Tale den ungünstigsten Fall, den geschätzten Prompt plus die höchstmögliche Ausgabe zum Katalogpreis des Modells. Passt er nicht in das, was unter einer Budgetgrenze für dich, deine Teams, die Organisation oder den Schlüssel noch übrig ist, lehnt Tale den Aufruf mit `429 BUDGET_EXCEEDED` ab; sonst reserviert es ihn gegen diese Grenzen, solange der Aufruf läuft. Ein kleineres `max_tokens` passt eher. Danach verbucht Tale die vom Modell-Gateway gemessenen Kosten und die gemeldeten Tokens unter deinem Namen und dem Schlüssel. Brichst du einen Aufruf ab, während Tale ihn noch prüft, leitet Tale ihn nicht weiter und verbucht ihn nicht. Brichst du ihn ab, nachdem er weitergeleitet wurde, bricht Tale auch die Anfrage an den Anbieter ab, und der Aufruf wird trotzdem verbucht: mindestens mit seinem Prompt und der Ausgabe, die dich schon erreicht hatte, zum Katalogpreis des Modells. Jeder Aufruf zählt als eine Anfrage und erscheint in der Nutzungsanalyse als **Direkter API-Aufruf**.
- **Acht Aufrufe gleichzeitig.** Du und jeder deiner Schlüssel dürfen acht Aufrufe gleichzeitig laufen haben. Einen neunten lehnt Tale mit `429 MODEL_API_CONCURRENCY_EXCEEDED` und einem `Retry-After` von zwei Sekunden ab.

Deine Tools sehen nie einen Anbieterschlüssel. Tale leitet jeden Aufruf über sein Modell-Gateway weiter, mit einem Schlüssel, der nur für diese eine Anfrage und dieses eine Modell erzeugt wird. Widerrufst du deinen API-Schlüssel unter **Einstellungen > API > REST**, endet sein Zugriff mit der nächsten Anfrage; eine Antwort, die bereits gestreamt wird, läuft zu Ende.

### Was die Endpunkte nicht bedienen

- **Tools, die der Modellanbieter selbst ausführt.** `web_search_options` von OpenAI und jedes Tool, dessen Typ nicht `function` oder `custom` ist, sowie Websuche, Web-Abruf, Codeausführung und MCP-Toolsets von Anthropic samt den Feldern `mcp_servers` und `container` lehnt Tale mit `400 MODEL_API_VENDOR_TOOL_UNSUPPORTED` ab, weil es sie weder messen noch protokollieren könnte. Deine eigenen Tools werden weitergereicht und kommen als `tool_calls` oder `tool_use` zurück, auch die Client-Tools `bash`, `text_editor`, `computer` und `memory` von Anthropic.
- **Audioeingaben.** Anfragen mit Teilen vom Typ `input_audio` lehnt Tale ab.
- **Anfragen, die Tale nicht abrechnen oder in deiner Organisation halten kann.** Mehr als acht Antworten pro Anfrage (`n`), Dateien im Konto des Anbieters (eine OpenAI-`file_id`, eine Anthropic-Quelle vom Typ `file`), ein `service_tier` außer `auto` oder `default` (`auto` oder `standard_only` bei Anthropic), Audioausgabe und `store: true` lehnt Tale mit `400 INVALID_BODY` ab.
- **Andere Routen.** `count_tokens` und alle anderen Routen von Anthropic bedient Tale nicht, ebenso wenig OpenAI-Routen jenseits von Chat Completions und der Modellliste, etwa Embeddings, Responses oder Bildgenerierung.
- **Assistent und Tools von Tale.** Dafür nutzt du [die REST-Chat-API](https://docs.tale.dev/de/develop/use-tale-from-your-editor#die-rest-chat-api-aus-einem-skript-nutzen) oder [den MCP-Endpoint](https://docs.tale.dev/de/develop/use-tale-from-your-editor#opencode-oder-claude-code-verbinden).

### Einen abgelehnten Aufruf beheben

Jede Ablehnung kommt im Fehlerformat der Schnittstelle, die du aufgerufen hast, und dein SDK meldet sie wie einen Fehler von OpenAI oder Anthropic. Das Feld `code` enthält den stabilen Code von Tale; die [API-Referenz](https://docs.tale.dev/de/develop/api-reference#model-endpoints) führt alle auf.

| Status und Code | Was du tun kannst |
| --- | --- |
| `401 UNAUTHORIZED` | Sende den Schlüssel als `Authorization: Bearer`, nie als `x-api-key`. Setze für Claude Code `ANTHROPIC_AUTH_TOKEN` und entferne `ANTHROPIC_API_KEY`; übergib den Schlüssel bei den Anthropic-SDKs als `auth_token` oder `authToken`. Auch ein widerrufener oder abgelaufener Schlüssel führt zu `401`. |
| `400 ORG_SLUG_REQUIRED` | Du gehörst mehreren Organisationen an. Sende `X-Organization-Slug` mit. |
| `403 MODEL_API_DISABLED` | Die Organisation hat die Endpunkte nicht eingeschaltet. Wende dich an einen Admin. |
| `403 MODEL_API_FORBIDDEN` | Deine Rolle darf sie nicht aufrufen. Frag einen Admin nach der Kompetenz **Modelle über die API aufrufen**. |
| `404 MODEL_API_MODEL_UNKNOWN` | Die ID steht nicht auf deiner Liste. Kopiere eine aus `GET /api/v1/openai/models` oder dem Tab **Modelle**, samt Slug des Anbieters. |
| `403 MODEL_API_MODEL_FORBIDDEN` | Der Modellzugriff sperrt dieses Modell für dich. Wähle ein anderes Modell oder wende dich an einen Admin. |
| `400 MODEL_API_VISION_UNSUPPORTED`, `400 MODEL_API_TOOLS_UNSUPPORTED` | Wähle ein Modell, das Bilder liest oder Tools annimmt, oder sende die Anfrage ohne sie. |
| `400 MODEL_API_VENDOR_TOOL_UNSUPPORTED` | Entferne das Tool, das der Modellanbieter selbst ausführen würde, etwa eine Websuche. In Claude Code löst das Tool WebSearch diese Ablehnung aus. |
| `400 MODEL_API_GUARDRAIL_BLOCKED` | Eine Guardrail hat den System-Prompt oder eine Nachricht abgelehnt, und beim Modell kam nichts an. Formuliere um oder frag einen Admin nach der Regel. |
| `403 MODEL_API_GUARDRAIL_UNSUPPORTED` | Der PII-Schutz der Organisation tokenisiert, und das können die Modell-Endpunkte nicht umsetzen. Ein Admin kann ihn auf Maskieren oder Blockieren umstellen. |
| `429 RATE_LIMITED` | Du hast mehr Anfragen gesendet, als das gemeinsame Kontingent deiner API-Schlüssel erlaubt. Warte die Zeit aus `Retry-After` ab; siehe [Ratenlimits](https://docs.tale.dev/de/develop/rate-limits). |
| `429 BUDGET_EXCEEDED` | Eine Budgetgrenze ist erreicht. `Retry-After` nennt die Zeit bis zum Zurücksetzen, und die Antwort trägt `x-should-retry: false`, damit die SDKs es nicht selbst erneut versuchen. Warte oder lass einen Admin die Grenze anheben. |
| `503 MODEL_API_UNAVAILABLE`, `503 MODEL_API_GUARDRAIL_UNAVAILABLE` | Ein Dienst, den der Aufruf braucht, ist nicht verfügbar, etwa das Modell-Gateway oder der Moderationsanbieter. Versuche es später erneut; hält der Fehler an, soll ein Admin die Anbieter-Zugangsdaten oder den Moderationsanbieter prüfen. |
| `MODEL_API_UPSTREAM_ERROR` | Der Modellanbieter hat den Aufruf abgelehnt, und die Meldung stammt von ihm. `400`, `413`, `422`, `429`, `503` und `529` behalten ihren Status; jede andere Ablehnung kommt als `502` an. |

## Die REST-Chat-API aus einem Skript nutzen

Über die REST-Chat-API erreicht ein Skript denselben Assistenten, den Mitglieder im Chat der App verwenden. Das ist kein reiner Modellaufruf: Jeder Turn läuft über den eingebauten Assistenten. Er durchsucht das Wissen deiner Organisation, wenn die Frage es verlangt, und verweist Wünsche nach Dokumenten oder anderen Arbeitsergebnissen an Aufgaben. Die API arbeitet asynchron. Ein Senden antwortet mit `202` und der ID der Antwort, danach fragst du den Status ab, bis der Turn abgeschlossen ist.

Die Beispiele teilen sich eine Hilfsfunktion, die bei jeder Anfrage den Schlüssel und den Organisations-Header mitschickt. Speichere sie als `tale-api.sh`:

```bash
# tale-api.sh: aus deiner Shell oder aus einem Skript mit source laden
: "${TALE_URL:?TALE_URL auf den Tale-Ursprung ohne /api/v1 setzen}"
: "${TALE_API_KEY:?TALE_API_KEY setzen}"
: "${TALE_ORG_SLUG:?TALE_ORG_SLUG setzen}"
tale_api() {
  curl --fail-with-body -sS \
    -H "Authorization: Bearer $TALE_API_KEY" \
    -H "X-Organization-Slug: $TALE_ORG_SLUG" \
    -H 'Content-Type: application/json' "$@"
}
```

Lade sie in deine Shell, prüfe den Schlüssel und liste die Modelle, die du aufrufen kannst. Die Beispiele brauchen curl und `jq`.

```bash
source ./tale-api.sh

# Für wen der Schlüssel handelt und in welcher Organisation
tale_api "$TALE_URL/api/v1/me" | jq '{email: .user.email, organization: .organization.slug, role: .organization.role}'

# Die Modelle, die du nennen darfst: id und providerSlug
tale_api "$TALE_URL/api/v1/models" | jq -r '.models[] | "\(.id)\t\(.providerSlug)"'
```

Exportiere `MODEL_ID` und `PROVIDER` nach einer Zeile dieser Liste. Das Gespräch ist ein Skript, `ask-tale.sh`, das neben der Hilfsfunktion liegt und mit `bash ask-tale.sh` läuft. Es legt einen persönlichen Thread an, stellt eine Frage, wartet, bis der Turn abgeschlossen ist, und gibt den Text der Antwort aus. `set -euo pipefail` bricht beim ersten fehlgeschlagenen Aufruf ab, sodass das Skript nie mit einer leeren ID weiterläuft.

```bash
#!/usr/bin/env bash
set -euo pipefail
source "$(dirname "$0")/tale-api.sh"
: "${MODEL_ID:?MODEL_ID auf eine id aus /models setzen}"
: "${PROVIDER:?PROVIDER auf den zugehörigen providerSlug setzen}"

THREAD_ID=$(tale_api -X POST "$TALE_URL/api/v1/threads" -d '{"title":"Skript-Hilfe"}' | jq -er '.id')

BODY=$(jq -n --arg model "$MODEL_ID" --arg provider "$PROVIDER" \
  '{content: "Was sagt unser Runbook zum Wechsel der Datenbankpasswörter?", model: $model, providerSlug: $provider}')
MESSAGE_ID=$(tale_api -X POST "$TALE_URL/api/v1/threads/$THREAD_ID/messages" -d "$BODY" | jq -er '.messageId')

# Alle drei Sekunden abfragen, bis zu zehn Minuten, bis der Turn abgeschlossen ist
STATUS=queued
for _ in $(seq 200); do
  STATUS=$(tale_api "$TALE_URL/api/v1/threads/$THREAD_ID/generation" | jq -r '.status')
  [ "$STATUS" = idle ] && break
  sleep 3
done
if [ "$STATUS" != idle ]; then
  echo "Keine Antwort innerhalb von zehn Minuten; der Turn wird gestoppt." >&2
  tale_api -X DELETE "$TALE_URL/api/v1/threads/$THREAD_ID/generation" > /dev/null
  exit 1
fi

# Die Antwort lesen, die das Senden genannt hat, und prüfen, wie sie endete
REPLY=$(tale_api "$TALE_URL/api/v1/threads/$THREAD_ID/messages/$MESSAGE_ID")
if [ "$(jq -r '.status' <<< "$REPLY")" != complete ]; then
  jq -r '"Turn \(.status): \(.errorCode // "") \(.error // "")"' <<< "$REPLY" >&2
  exit 1
fi
if [ "$(jq -r '.finishReason // ""' <<< "$REPLY")" = length ]; then
  echo "Die Antwort hat ihre Ausgabegrenze erreicht und ist womöglich abgeschnitten." >&2
fi
jq -r '[.parts[] | select(.type == "text") | .text] | join("")' <<< "$REPLY"
```

Solange das Senden auf einen Worker wartet, kann `GET .../messages/$MESSAGE_ID` noch mit `404 MESSAGE_NOT_FOUND` antworten. Das Skript liest die Antwort deshalb erst, wenn der Thread ruht. Einen Turn, der nach zehn Minuten nicht abgeschlossen ist, stoppt es mit `DELETE .../generation`. Schick Folgefragen an dieselbe `THREAD_ID`, damit der Gesprächskontext erhalten bleibt. Das Senden nimmt nur Text an und wird mit `409 CHAT_TURN_IN_PROGRESS` abgelehnt, solange der vorige Turn des Threads noch läuft.

Braucht ein Skript die passenden Textstellen statt einer Antwort, liefert `POST /api/v1/knowledge/search` sie ohne den Assistenten; siehe [Die Dateien eines Projekts durchsuchen](https://docs.tale.dev/de/develop/api-reference#die-dateien-eines-projekts-durchsuchen). [Tale aus einem Skript aufrufen](https://docs.tale.dev/de/tutorials/developer/call-tale-from-a-script) baut dasselbe Gespräch in Python mit Fehlerbehandlung auf, und [Eine Nachricht senden, dann den Turn pollen](https://docs.tale.dev/de/develop/api-reference#eine-nachricht-senden-dann-den-turn-pollen) beschreibt Wiederholungen, Token-Grenzen und Fehler.

## Die Tools von Tale in opencode oder Claude Code nutzen {#opencode-oder-claude-code-verbinden}

Der [MCP-Endpoint](https://docs.tale.dev/de/develop/mcp-endpoint) von Tale, `/api/v1/mcp`, stellt einem Editor-Agenten die Tools von Tale bereit. Für die Arbeit an Skripten ist `get_knowledge` am nützlichsten: Es ruft Textstellen aus den Dokumenten und gecrawlten Webseiten deiner Organisation ab. Dazu kommen die Automatisierungs-Tools, mit denen du Automatisierungen validierst, testest, speicherst, bereitstellst und ausführst und ihre Läufe liest. Speichern, Bereitstellen, das Setzen oder Löschen eines Triggers, das Abbrechen eines Laufs und Live-Läufe verlangen die Entwickler-Berechtigung. Ein Chat- oder Skill-Tool gibt es dort nicht. Um die Skills deiner Organisation in einen lokalen Skill-Ordner zu übernehmen, liest du sie mit `GET /api/v1/skills`, wie in [Skill-Pakete speichern und abgleichen](https://docs.tale.dev/de/develop/api-reference#skill-pakete-speichern-und-abgleichen) beschrieben.

Das Sprachmodell ist auf diesem Weg das Modell, das in deinem Editor eingerichtet ist. Tale authentifiziert die Tool-Aufrufe und prüft sie gegen deine Rechte. Die Prompts, dein Code und jede Textstelle, die ein Tale-Tool zurückgibt, gehen aber an den Modellanbieter dieses Editors. Ist das ein anderer Dienst, gelten Budgets, Verbrauchserfassung und Modellzugriffsregeln von Tale für seine Modellaufrufe nicht; kläre vor dem Verbinden, ob deine Organisation ihr Wissen an diesen Anbieter geben darf. Nutzt der Editor [die Modell-Endpunkte](https://docs.tale.dev/de/develop/use-tale-from-your-editor#model-endpoints) als Anbieter, gehen die Textstellen nur an Modelle, die deine Organisation freigegeben hat, und jeder Modellaufruf wird geprüft, wie dort beschrieben.

Der Endpunkt authentifiziert mit dem API-Schlüssel im Header und kennt keine OAuth-Anmeldung. Schalte die OAuth-Erkennung eines Clients ab, wo er diese Option anbietet.

### opencode

Trag einen Remote-Server in deine globale opencode-Konfiguration `~/.config/opencode/opencode.json` oder in eine `opencode.json` im Projekt ein. Mit `{env:TALE_API_KEY}` liest opencode den Schlüssel aus deiner Umgebung, sodass die Datei das Geheimnis nie enthält. Ersetze Host und Slug durch deine eigenen Werte.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tale": {
      "type": "remote",
      "url": "https://your-host.example.com/api/v1/mcp",
      "oauth": false,
      "timeout": 60000,
      "headers": {
        "Authorization": "Bearer {env:TALE_API_KEY}",
        "X-Organization-Slug": "your-org-slug"
      }
    }
  }
}
```

`timeout` hebt die Vorgabe von opencode für MCP-Anfragen an, fünf Sekunden. Eine Wissenssuche unter Last oder ein Aufruf von `run_deployed`, der bis zu 30 Sekunden wartet, kann länger dauern. Starte opencode aus einer Shell, in der `TALE_API_KEY` gesetzt ist. `opencode mcp list` zeigt, ob der Server eingerichtet ist. opencode stellt den Tools den Servernamen voran, etwa `tale_get_knowledge`.

### Claude Code

Registriere den Endpunkt als HTTP-Server. Der folgende Befehl speichert den eingesetzten Schlüssel in deiner privaten Claude-Code-Konfiguration für das aktuelle Projekt:

```bash
claude mcp add --transport http tale "$TALE_URL/api/v1/mcp" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG"
```

Willst du den Server über eine eingecheckte `.mcp.json` mit dem Team teilen, verweise auf den Schlüssel als Umgebungsvariable, damit jede Person ihren eigenen einsetzt:

```json
{
  "mcpServers": {
    "tale": {
      "type": "http",
      "url": "https://your-host.example.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${TALE_API_KEY}",
        "X-Organization-Slug": "your-org-slug"
      }
    }
  }
}
```

`claude mcp list` zeigt, ob Claude Code den Server erreicht.

## Skripte von einem Projektagenten bearbeiten lassen

Soll die Bearbeitung in Tale geschehen, in einer Sandbox und mit Prüfung durch eine Person, übergib das Skript einem [Projektagenten](https://docs.tale.dev/de/platform/projects/project-agents). Tale führt dann eine Coding-Laufzeit wie OpenCode in einer Sandbox aus, mit dem Modell, das für den Agenten eingerichtet ist. Der Lauf zählt gegen die Budgets des Mitglieds, das ihn gestartet hat, und wird dieser Person zugeordnet. Einen Lauf, den du per REST startest, verbucht Tale bei dir, nicht beim API-Schlüssel. Die bearbeiteten Dateien kommen als Ergebnisse der Aufgabe zurück, und die Aufgabe wartet auf die Prüfung durch eine Person. [Eine Agent-Laufzeit wählen](https://docs.tale.dev/de/platform/agents/harnesses) vergleicht die Laufzeiten. OpenCode läuft nur über das Modell-Gateway von Tale und erhält daher nie einen Anbieterschlüssel.

Um den Agenten anzulegen, brauchst du Bearbeitungsrechte im Projekt, also mindestens die Rolle Redakteur; die Aufgabe anlegen und den Agenten darauf starten kann danach jeder, der das Projekt öffnen kann. Die Organisation braucht ein Modell, das die Laufzeit nutzen kann, und freie Sandbox-Kapazität. In der App öffnest du den Tab **Agenten** des Projekts, wählst **Neuer Agent**, stellst OpenCode als Agent-Laufzeit und ein Modell ein, legst dann eine Aufgabe mit dem Skript als Anhang an, weist sie dem Agenten zu und startest ihn.

Derselbe Ablauf funktioniert per REST aus dem Terminal, mit `tale-api.sh` aus dem Chat-Beispiel. Prüfe zuerst, ob diese Installation OpenCode für Projektagenten ausführt:

```bash
tale_api "$TALE_URL/api/v1/models" | jq -r '.harnesses[] | "\(.harness)\t\(.label)"'
```

Speichere dann das folgende Skript als `hand-to-agent.sh` neben der Hilfsfunktion und starte es mit `bash hand-to-agent.sh`. Es verwendet den Agenten Skript-Editor des Projekts wieder oder legt ihn beim ersten Lauf an, denn Agentennamen sind in einem Projekt ohne Rücksicht auf Groß- und Kleinschreibung eindeutig. Danach reicht es das Skript als Aufgabe ein und setzt den Agenten mit einem Kommentar, der ihn erwähnt, an die Arbeit.

```bash
#!/usr/bin/env bash
set -euo pipefail
source "$(dirname "$0")/tale-api.sh"
: "${PROJECT_ID:?PROJECT_ID auf ein Projekt setzen, das du bearbeiten darfst}"
: "${MODEL_ID:?MODEL_ID auf ein Modell setzen, das die Laufzeit nutzen kann}"
: "${PROVIDER:?PROVIDER auf den zugehörigen providerSlug setzen}"
AGENT_NAME="Skript-Editor"

AGENT_ID=$(tale_api "$TALE_URL/api/v1/projects/$PROJECT_ID/agents" \
  | jq -r --arg name "$AGENT_NAME" 'first(.agents[] | select((.name | ascii_downcase) == ($name | ascii_downcase)) | .id) // ""')
if [ -z "$AGENT_ID" ]; then
  AGENT_ID=$(tale_api -X POST "$TALE_URL/api/v1/projects/$PROJECT_ID/agents" \
    -d "$(jq -n --arg name "$AGENT_NAME" --arg model "$MODEL_ID" --arg provider "$PROVIDER" '{name: $name, harness: "opencode", model: $model, modelProvider: $provider, skills: [], connectors: [], instructions: "Bearbeite das Skript aus der Aufgabenbeschreibung. Gib das geänderte Skript als Datei zurück und führe jede Änderung in deinem Bericht auf."}')" \
    | jq -er '.agent.id')
fi

TASK_ID=$(tale_api -X POST "$TALE_URL/api/v1/projects/$PROJECT_ID/tasks" \
  -d "$(jq -n --rawfile script backup.ps1 '{externalSystem: "terminal", externalId: "backup-ps1-hardening", title: "backup.ps1 absichern", description: ("Ergänze Fehlerbehandlung und einen Testlauf-Schalter in diesem PowerShell-Skript:\n\n" + $script)}')" \
  | jq -er '.task.id')

tale_api -X POST "$TALE_URL/api/v1/projects/$PROJECT_ID/tasks/$TASK_ID/comments" \
  -d "$(jq -n --arg agent "$AGENT_ID" '{body: ("@" + $agent + " bitte übernimm diese Aufgabe.")}')" > /dev/null
echo "TASK_ID=$TASK_ID"
```

`externalSystem` und `externalId` machen die Aufgabe idempotent: Dasselbe Paar liefert beim nächsten Senden die bestehende Aufgabe. Eine Beschreibung fasst bis zu 20.000 Zeichen. Ein längeres Skript lädst du ins Projekt hoch, wie in [Eine Datei in zwei Schritten hochladen](https://docs.tale.dev/de/develop/api-reference#eine-datei-in-zwei-schritten-hochladen) beschrieben. Ein Agent reagiert auf seine ID und auf seinen Namen in Kleinbuchstaben, bei dem Leerzeichen durch Punkte ersetzt oder entfernt sind. `@skript-editor` funktioniert daher ebenfalls.

Die Erwähnung weist dem Agenten die Aufgabe zu und startet einen Lauf; die Aufgabe wechselt auf `in_progress`. Kann eine Erwähnung keinen Lauf starten, bleibt sie ein gewöhnlicher Kommentar ohne Fehlermeldung, etwa wenn du die Aufgabe nicht ändern darfst, die Aufgaben-Automatisierung ausgeschaltet ist oder ein anderer Lauf die Aufgabe bereits belegt. Setze `TASK_ID` auf den Wert, den das Skript ausgegeben hat, prüfe die Aufgabe und lies den Bericht des Agenten, sobald sie `in_review` erreicht:

```bash
tale_api "$TALE_URL/api/v1/projects/$PROJECT_ID/tasks/$TASK_ID" | jq -r '.task.status'
tale_api "$TALE_URL/api/v1/projects/$PROJECT_ID/tasks/$TASK_ID/comments?limit=20" \
  | jq -r '.comments[] | select(.authorType == "agent") | .body'
```

Prüfe die bearbeiteten Dateien in den Ergebnissen der Aufgabe in der App, bevor du die Aufgabe freigibst. Sollen noch Änderungen folgen, schreib einen weiteren Kommentar, der den Agenten erwähnt.

## Was sich seit Tale 0.3 geändert hat {#was-aus-dem-openai-kompatiblen-endpunkt-wurde}

Von 0.2.10 bis 0.3 bot Tale eine OpenAI-kompatible Schicht: `POST /api/v1/chat/completions`, `POST /api/v1/images/generations` und ein `GET /api/v1/models` im OpenAI-Format, dessen Feld `model` einen Agenten nennen konnte. Mit Tale 0.4 wurde die Plattform ohne diese Schicht neu aufgebaut. Für Modellaufrufe treten jetzt die [Modell-Endpunkte](https://docs.tale.dev/de/develop/use-tale-from-your-editor#model-endpoints) an ihre Stelle, mit Unterschieden, die ein Client für 0.3 beachten muss:

- Die Basis-URL ist `/api/v1/openai`, für einen Anthropic-Client `/api/v1/anthropic`, nicht `/api/v1`. Ein OpenAI-SDK, das auf `/api/v1` zeigt, erhält für Chat Completions weiterhin `404 NOT_FOUND`, und `GET /api/v1/models` liefert die eigene Liste von Tale mit Modellen und Agent-Laufzeiten, nicht das OpenAI-Format.
- `model` nennt ein Modell als `<providerSlug>/<modelId>`, nie einen Agenten. Für den eingebauten Assistenten nutzt du die REST-Chat-API, für die Arbeit eines Agenten einen Projektagenten.
- Bildgenerierung wird nicht bedient.
- Die Endpunkte sind ausgeschaltet, bis ein Admin sie einschaltet, und jeder Aufruf durchläuft Modellzugriff, Eingabe-Guardrails und Budgets.

[Bereitstellung aktualisieren und wiederherstellen](https://docs.tale.dev/de/self-hosted/operate/upgrades#03-04-die-openai-kompatible-api-entfaellt) nennt die Entfernung für Betreiber, die von 0.3 umsteigen.

# WebDAV-API
Source: https://docs.tale.dev/de/develop/webdav-api

Über WebDAV kann ein Dateiclient Ordner auflisten, Dateien lesen und schreiben sowie Bearbeitungssperren setzen. Der Endpunkt stellt die Dokumentenzentrale der Organisation bereit; Projektdateien gehören nicht zu diesem Verzeichnisbaum. Für Finder, Datei-Explorer und andere fertige Clients nutze die [WebDAV-Einrichtung](https://docs.tale.dev/de/platform/connectors/webdav).

Diese Referenz richtet sich an Entwickler von Clients. Prüfe zuerst einen authentifizierten Verzeichnisabruf und danach einen kleinen Upload. Eine Antwort mit `207` bestätigt den Zugriff; erst identische heruntergeladene Dateiinhalte bestätigen auch den Speicherpfad.

## URL-Schema

| Pfad | Zugriff | Inhalt |
| --- | --- | --- |
| `/dav/<orgSlug>/documents/<path>` | Lesen und Schreiben | Aktive Dateien und Ordner der Dokumentenzentrale |
| `/dav/<orgSlug>/.trash/<path>` | Nur Lesen | Dokumente im Papierkorb |
| `/dav/<orgSlug>/` | Nur Lesen | Die beiden Bereiche oben |

Kodiere jedes Pfadsegment einzeln. Der Parser normalisiert Unicode auf NFC und entfernt Leerraum am Anfang und Ende. Leere Namen, `.` und `..`, `/`, `\`, Steuerzeichen und Namen mit mehr als 255 UTF-16-Codeeinheiten sind unzulässig. Das ist eine Zeichenlängenprüfung, keine Grenze von 255 Bytes. Für Organisations-Slugs gilt `[a-zA-Z0-9_-]{1,64}`. Ein Segment `.` oder `..` in der Anfragezeile, roh oder prozentkodiert (`%2e%2e`, `.%2e`), wird vor dem Routing mit `404` abgewiesen und nie gegen den übergeordneten Ordner aufgelöst. Ein roher Backslash zählt bei dieser Prüfung als Segmenttrenner (`a\..\x` wird wie `a/../x` gelesen); ein kodierter (`%5C`) ist ein gewöhnliches, abgewiesenes Namenszeichen.

Verwende für Ordner einen abschließenden Schrägstrich, für Dateien keinen. Verzeichnisantworten enthalten kanonische URLs. Übernimm bei vorhandenen Einträgen den zurückgegebenen `href`, statt ihn aus dem Anzeigenamen abzuleiten. Das ist besonders bei gleichnamigen Dokumenten im selben Ordner wichtig.

## Authentifizierung

Erzeuge in **Einstellungen > API > WebDAV** ein App-Passwort mit einem Konto, das auf die Entwicklereinstellungen zugreifen darf. Das vollständige Passwort erscheint einmal. Gib jedem Client eine eigene Bezeichnung, damit du seinen Zugriff einzeln widerrufen kannst.

| Zugangsdaten | Wert |
| --- | --- |
| HTTP-Verfahren | Basic |
| Benutzername | Deine Konto-E-Mail; der Server akzeptiert jeden nicht leeren Benutzernamen |
| Passwort | Das erzeugte WebDAV-App-Passwort |
| Organisation | Der Slug in der URL; die Mitgliedschaft wird bei jedem Zugriff geprüft |

Das App-Passwort identifiziert den Benutzer. Kontopasswörter und REST-API-Schlüssel werden nicht akzeptiert. Auch mit einem gültigen Passwort brauchst du eine aktuelle Mitgliedschaft in der Organisation; andernfalls folgt `403`. Nur `OPTIONS` ist ohne Anmeldung möglich.

### Einen Verzeichnisabruf prüfen

Setze unten die URL deiner Installation und deine E-Mail ein. Jeder Befehl mit `curl --user` fragt das App-Passwort interaktiv ab. So steht es weder im Befehl noch im Shell-Verlauf.

```bash
export TALE_DAV_URL="https://your-host.example.com/dav/acme/documents"
export TALE_DAV_USER="you@example.com"

curl --user "$TALE_DAV_USER" --request PROPFIND \
  --header 'Depth: 1' "$TALE_DAV_URL/"
```

Erwartet wird `207 Multi-Status` mit XML für den Ordner und seine direkten Einträge. Auch ein leerer Ordner hat einen eigenen Antwortblock. Parse XML als XML; ein `207` bedeutet nicht, dass jeder enthaltene Einzelstatus erfolgreich ist.

### Schreiben und Herunterladen prüfen

Wähle einen neuen Ordnernamen, damit du nichts überschreibst. Die Befehle erstellen einen Ordner, laden eine Textdatei hoch und rufen sie wieder ab:

```bash
curl --user "$TALE_DAV_USER" --request MKCOL "$TALE_DAV_URL/Client%20test/"
printf 'Hello from WebDAV.\n' > webdav-test.txt
curl --user "$TALE_DAV_USER" --upload-file webdav-test.txt \
  --header 'Content-Type: text/plain' "$TALE_DAV_URL/Client%20test/webdav-test.txt"
curl --user "$TALE_DAV_USER" "$TALE_DAV_URL/Client%20test/webdav-test.txt"
```

Erwartet werden `201` für den neuen Ordner, `201` für die neue Datei und der Text `Hello from WebDAV.` beim Abruf. Ein Upload auf eine vorhandene Datei ersetzt den Inhalt und liefert `204`. Die Datei erscheint auch ohne zusätzlichen Abgleich in der Dokumentenzentrale.

## Methoden

Außer `OPTIONS` verlangen alle Methoden das App-Passwort.

| Methode | Zweck | Erfolgreiche Antwort |
| --- | --- | --- |
| `OPTIONS` | Fähigkeiten und erlaubte Methoden des Ziels abfragen | `200`, `DAV: 1, 2`, `Allow` |
| `PROPFIND` | Eigenschaften lesen; `Depth: 0` nur für das Ziel, `Depth: 1` einschließlich direkter Einträge | `207` mit XML |
| `PROPPATCH` | Eigenschaftsänderungen übermitteln; Einschränkungen siehe unten | `207` mit Status je Eigenschaft |
| `GET`, `HEAD` | Datei herunterladen oder Header lesen | `200`; bedingte und Bereichsanfragen können andere Status liefern |
| `PUT` | Datei erstellen oder ersetzen | `201` neu, `204` ersetzt |
| `DELETE` | Dokumente in den Papierkorb verschieben; bei Ordnern rekursiv, Ordnerdatensätze entfernen | `204` |
| `MKCOL` | Ordner unter einem vorhandenen übergeordneten Ordner erstellen | `201` |
| `MOVE` | Dokument oder Ordner umbenennen oder verschieben | `201` neues Ziel, `204` ersetzt |
| `COPY` | Datei oder Ordnerbaum serverseitig kopieren; Dateikopien teilen gespeicherte Bytes | `201` neues Ziel, `204` ersetzt |
| `LOCK` | Schreibsperre anfordern oder verlängern | `200` mit Sperrtoken |
| `UNLOCK` | Eigene Sperre freigeben | `204` |

Ein `GET` auf einen Ordner liefert `405`; nutze `PROPFIND`. Ohne `Depth` gilt `1`, während `Depth: infinity` mit `403` abgelehnt wird. `MKCOL` benötigt einen leeren Body. Für `PUT` ist `Content-Length` erforderlich: Verwende eine Datei bekannter Größe statt Chunked Transfer.

`MOVE` und `COPY` nutzen `Destination` und berücksichtigen `Overwrite: T/F` sowie `If`. Das Ziel muss auf demselben Host und in derselben Organisation liegen. Fehlt der übergeordnete Zielordner, folgt `409`; bei `Overwrite: F` und vorhandenem Ziel folgt `412`. Dokumente werden atomar verschoben, bei Ordnern ändert sich die Zuordnung zum übergeordneten Ordner. Destruktive Vorgänge berücksichtigen außerdem Aufbewahrungssperren und Einschränkungen kontrollierter Dokumente.

`Allow` beschreibt das jeweilige Ziel: Der Dokumentenbaum nennt alle Methoden oben, eine Datei im Papierkorb `OPTIONS, GET, HEAD, PROPFIND`, der Papierkorb und das Organisationsverzeichnis `OPTIONS, PROPFIND`. Bei noch nicht auswertbaren Pfaden wird für die Erkennung die vollständige Methodenliste ausgegeben. Windows erhält zusätzlich `MS-Author-Via: DAV` und `Microsoft-Server-WebDAV-Extensions: 1`.

## Eigenschaften

| DAV-Eigenschaft | Bedeutung |
| --- | --- |
| `resourcetype` | `<collection/>` bei Ordnern, leer bei Dateien |
| `displayname` | Ordnername oder Dokumenttitel |
| `getlastmodified` | RFC-1123-Zeitstempel; Änderungszeit der Quelle, ersatzweise Erstellungszeit |
| `creationdate` | Erstellungszeit nach ISO 8601 |
| `getcontenttype` | MIME-Typ der Datei |
| `getcontentlength` | Dateigröße in Bytes |
| `getetag` | Derselbe Validator wie bei `GET` und `HEAD` |
| `supportedlock` | Unterstützung exklusiver Schreibsperren |
| `lockdiscovery` | Angaben zu aktiven Sperren, sofern verfügbar |

Dateieigenschaften gelten nicht für Ordner. Ein ETag enthält den Inhaltshash in Anführungszeichen, falls vorhanden. Sonst ist es ein schwacher Validator aus Größe und Änderungszeit, etwa `W/"42-1789373842855"`. Bewahre Anführungszeichen und `W/` unverändert. Ersetze den Wert nicht durch die Dokument-ID und leite aus einem schwachen Validator keine Bytegleichheit ab. `GET` unterstützt bedingte Anfragen und Bytebereiche.

<Warning>

Eigene Eigenschaften werden nicht gespeichert. Enthält `PROPPATCH` nur sogenannte Dead Properties, meldet der Server aus Kompatibilitätsgründen jeweils `200`; beim nächsten Lesen sind diese Werte trotzdem nicht vorhanden. Eine geschützte Live Property erhält `403`, Dead Properties derselben Anfrage erhalten dann `424 Failed Dependency`. Speichere darin keine fachlichen Metadaten.

</Warning>

## Sperrsemantik

Nutze eine exklusive Schreibsperre und bewahre das Token `opaquelocktoken:<uuid>` auf. Der Server kündigt exklusive Sperren an. Der Parser akzeptiert zwar einen gemeinsamen Geltungsbereich, die Datenbank erlaubt aber nur eine aktive Sperre je Ressource. Plane deshalb keine gemeinsame Bearbeitung mit Shared Locks.

| Aktion des Clients | Erforderliche Anfrage |
| --- | --- |
| Anfordern | `LOCK` mit XML für eine Schreibsperre und `Timeout: Second-N` |
| Unter Sperre schreiben | `If: (<opaquelocktoken:...>)` mitsenden |
| Verlängern | `LOCK` mit leerem Body und demselben `If`-Token |
| Freigeben | Als Eigentümer `UNLOCK` mit `Lock-Token: <opaquelocktoken:...>` senden |

Die Dauer wird auf 1–3600 Sekunden begrenzt. Verlängere die Sperre vor Ablauf, wenn die Bearbeitung länger dauert. Ein fehlendes Token bei einem geschützten Schreibzugriff führt zu `423`; ein falsches Token oder ein unbekanntes Token beim Verlängern zu `412`. Sperren können Unterverzeichnisse einschließen, sodass auch eine Sperre im übergeordneten Ordner den Zugriff verhindert.

Die Sperren liegen in Postgres. Abgelaufene Einträge schützen eine Ressource auch vor ihrer verzögerten Bereinigung nicht mehr. Beim Widerrufen eines App-Passworts werden seine Sperren sofort entfernt. Das hilft auch nach einem Client-Absturz, trennt aber alle Verbindungen mit diesem Passwort.

## Statuscodes

| Status | Bedeutung und nächster Schritt |
| --- | --- |
| `200`, `201`, `204` | Lesen, Erstellen oder Ändern erfolgreich; siehe Methodentabelle |
| `207` | Jeden Ressourcen- und Eigenschaftsstatus im XML prüfen |
| `400` | Fehlerhafte Header `Destination`, `If`, `Lock-Token` oder `Timeout` korrigieren |
| `401` | Gültiges, nicht widerrufenes App-Passwort über Basic mitsenden |
| `403` | Mitgliedschaft, schreibgeschützten Bereich, Aufbewahrungs-/Dokumentregeln, Tiefe, Eigentümer und Ziel prüfen |
| `404` | Zurückgegebenen `href`, Organisations-Slug und Existenz prüfen |
| `405` | `Allow` prüfen; Ordner lassen sich nicht als Dateien abrufen oder überschreiben |
| `409` | Übergeordneten Zielordner zuerst erstellen |
| `411` | `Content-Length` bei `PUT` mitsenden |
| `412` | Ressource oder Sperre neu lesen; `If`, `If-Match`, `If-None-Match` und `Overwrite` prüfen |
| `413` | Datei/XML verkleinern oder Uploadgrenze mit dem Betreiber prüfen |
| `415` | Leeren `MKCOL`-Body senden; erweitertes MKCOL wird nicht unterstützt |
| `423` | Passendes Sperrtoken beschaffen oder Freigabe/Ablauf abwarten |
| `502` | Abweichenden Zielhost und Verbindung zum Objektspeicher prüfen |
| `503` | Nicht benötigte Sperren dieses Passworts freigeben und `Retry-After` beachten |
| `507` | Den Ordnerbaum in kleineren Teilen bearbeiten |

Wiederhole nicht jede abgelehnte Anfrage automatisch. Ein fehlender Ordner oder falsche Zugangsdaten müssen korrigiert werden; bei einer Sperre ist die Abstimmung mit dem anderen Bearbeiter nötig.

## Compliance

Der Endpunkt gibt `DAV: 1, 2` aus. Maßgeblich sind die hier beschriebenen Methoden und Einschränkungen; die Angabe verspricht nicht jede optionale WebDAV-Funktion. Insbesondere werden eigene Eigenschaften nicht gespeichert und gemeinsame Bearbeitungssperren nicht unterstützt. Erweiterungen für Kalender, Kontakte, Suche und ACLs sind nicht vorhanden.

Die Syntax beschreibt [RFC 4918](https://www.rfc-editor.org/rfc/rfc4918). DAV-Konformitätsklasse 3 bezeichnet die Konformität mit einer Protokollrevision, nicht Kalender- oder Kontakterweiterungen.

## Limits

| Grenze | Wert oder Verhalten |
| --- | --- |
| Rekursives Auflisten | `Depth: infinity` wird abgelehnt; Ebene für Ebene lesen |
| Sperrdauer | 1–3600 Sekunden |
| Aktive Sperren | 200 je App-Passwort |
| Uploadgröße | Standardmäßig 5 GB; `WEBDAV_MAX_PUT_BYTES` setzt die Bytegrenze |
| XML-Bodies | 64 KiB für `PROPFIND`, `PROPPATCH`, `MKCOL` und `LOCK` |
| App-Passwörter | Bis zu 50 aktive je Benutzer in einer Organisation |
| Nutzungszeitstempel | Höchstens einmal pro Minute und Passwort aktualisiert |

Uploads werden mit Flusskontrolle an den Objektspeicher weitergegeben. Der Server braucht die Größe vor dem Anlegen der Uploadanfrage; Chunked Uploads erhalten `411`. Ordneroperationen haben begrenzte Traversierungsbudgets und können `507` liefern. Teile große Bäume auf, statt denselben zu großen Vorgang ständig zu wiederholen.

## Netzwerk-Voraussetzungen

Das Backend bedient `/dav/*`; der Plattform-Proxy macht den Pfad unter demselben öffentlichen Host wie Tale erreichbar. Lokal leitet Vite `/dav` von Port 3000 an das Backend weiter. Clients können damit die normale lokale Anwendungsadresse verwenden. Ein eigener WebDAV-Dienst ist nicht nötig.

Ein Verzeichnisabruf kann erfolgreich sein, während Downloads oder Uploads scheitern: Verzeichnisse benötigen die Datenbank, Dateiinhalte zusätzlich den Objektspeicher. Prüfe nach Proxy- oder Speicheränderungen beide Wege. Halte das Größenlimit des Proxys mit `WEBDAV_MAX_PUT_BYTES` konsistent.

## Sicherheit

Nutze für entfernte Verbindungen HTTPS. Basic sendet das App-Passwort bei jeder Anfrage; Base64 ist eine Kodierung, keine Verschlüsselung. Unverschlüsseltes HTTP eignet sich nur für einen kontrollierten Test auf localhost. Hinterlege Zugangsdaten über den Passwortdialog des Clients oder den Schlüsselbund des Betriebssystems, niemals in einer URL wie `https://user:password@host/`.

Das Backend speichert HMAC-SHA256-Hashes und ein vierstelliges Suchpräfix. Der Hashvergleich läuft in konstanter Zeit. Die Startkonfiguration leitet `WEBDAV_APP_PASSWORD_HMAC_KEY` aus `INSTANCE_SECRET` ab, sofern kein ausdrücklicher Wert gesetzt ist. Bewahre diese Geheimnisse stabil und gesichert auf: Ein anderer HMAC-Schlüssel macht bestehende Passwörter ungültig.

Die Passwortliste zeigt Bezeichnung, Präfix, Erstellungszeit und letzte Nutzung. Damit kannst du das Passwort eines verlorenen Geräts erkennen und widerrufen. Die letzte Nutzung ist ein gedrosselt aktualisierter Zeitstempel, kein vollständiges Protokoll aller Anfragen.

## Wo das hinpasst

Nutze [REST](https://docs.tale.dev/de/develop/api-reference) für projektbezogene Importe, ausdrückliche IDs und Suche. WebDAV eignet sich für Dateiclients der Dokumentenzentrale, die Pfade und Sperren erwarten. Beide arbeiten mit Tale-Dokumenten; WebDAV stellt aber weder den Dateibaum eines Projekts noch sämtliche REST-Vorgänge bereit.

# Webhooks
Source: https://docs.tale.dev/de/develop/webhooks

Über einen Webhook startet ein externes System eine bereitgestellte Automatisierung, indem es an eine geheime URL sendet. Das eignet sich für Bestellereignisse, Formularübermittlungen und andere Benachrichtigungen mit festem Ziel. `202` bestätigt die Annahme und liefert eine Lauf-ID, aber noch keinen abgeschlossenen Lauf.

Für die erste Einrichtung nutze das [Webhook-Tutorial](https://docs.tale.dev/de/tutorials/developer/trigger-automation-via-webhook). Diese Referenz beschreibt Zustellung, Geltungsbereich, Token-Verwaltung und Wiederholungen.

## Ein Trigger, durchgespielt

### Eine bereitgestellte Automatisierung vorbereiten

Speichere eine Automatisierung, deren Tests bestehen, und stelle sie bereit. Binde im Editor einen Webhook oder sende mit einem berechtigten API-Schlüssel `PUT /api/v1/automations/{name}/triggers` und `{"kind":"webhook"}`. Kopiere das neu erzeugte Token sofort; es wird nur einmal ausgegeben.

Wähle die URL passend zum Geltungsbereich:

| Gewünschter Lauf | URL | Voraussetzung |
| --- | --- | --- |
| Projektlauf | `/api/projects/{id}/automations/webhook/{token}` | Aktives Projekt in der Organisation des Tokens, mit installierter Automatisierung |
| Organisationslauf | `/api/automations/webhook/{token}` | Automatisierung ohne Projektbindungen |

Eine projektgebundene Automatisierung lehnt die globale URL mit `409 AUTOMATION_PROJECT_SCOPE_REQUIRED` ab. Hänge keinen Query-Parameter `projectId` an: Beide URLs liefern dafür `400 INVALID_QUERY`. Ein Feld im Anbieter-Body ist Eingabe, keine Projektauswahl.

### Eine Zustellung senden

Hinterlege die vollständige geheime URL über die sichere Konfiguration des Senders in `TALE_WEBHOOK_URL`. Die folgende Anfrage verwendet eine stabile ID für ein fachliches Ereignis:

```bash
curl --fail-with-body --request POST "$TALE_WEBHOOK_URL" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-12345-paid' \
  --data '{"orderId":"12345","status":"paid"}'
```

Die Annahme liefert HTTP `202` mit der Form `{"runId":"..."}`. Speichere die Lauf-ID zusammen mit der Zustellungs-ID des Senders. Tale übergibt den Body in dieser Hülle:

```json
{
  "trigger": "webhook",
  "payload": { "orderId": "12345", "status": "paid" }
}
```

Lies die Bestellung über `input.payload.orderId`. Ein deklariertes `inputs`-Schema muss diese Hülle beschreiben. Ein Body ohne gültiges JSON wird als Text in `payload` übergeben. Die Grenze beträgt 256 KiB (262.144 Bytes), während des Empfangs gezählt; größere Anfragen erhalten `413`.

### Das Ergebnis verfolgen

| Geltungsbereich | Authentifizierte Abfrageroute |
| --- | --- |
| Projekt | `GET /api/v1/projects/{id}/runs/{runId}` |
| Organisation | `GET /api/v1/runs/{runId}` |

Frage mit einem API-Schlüssel ab, dessen Inhaber den Bereich lesen darf, oder öffne den Lauf in Tale. Das Webhook-Token erlaubt Zustellungen, aber keine REST-Ergebnisabfragen. Melde den Vorgang erst als erfolgreich, wenn der Lauf einen entsprechenden Endstatus erreicht hat.

### Antworten auf Zustellungen auswerten

| Status | Code/Ergebnis | Nächster Schritt |
| --- | --- | --- |
| `202` | `runId` | Angenommen; Lauf verfolgen |
| `202` | `runId`, `duplicate: true` | Bereits angenommen; ursprünglichen Lauf verfolgen, kein neuer Lauf |
| `400` | `INVALID_QUERY` | `projectId` aus dem Query-String entfernen |
| `400` | `AUTOMATION_INPUT_INVALID` | Hülle und Schema anhand von `data.issues` korrigieren |
| `403` | `AUTOMATION_PROJECT_FORBIDDEN` | Aktives Projekt, richtige Organisation und Installation prüfen |
| `404` | Unbekanntes, deaktiviertes oder falsch geschriebenes Token; auch jede Methode außer POST | Gespeicherte URL und Triggerstatus prüfen |
| `409` | `AUTOMATION_NOT_DEPLOYED` | Version mit erfolgreichen Tests bereitstellen |
| `409` | `AUTOMATION_PROJECT_SCOPE_REQUIRED` | URL des Installationsprojekts verwenden |
| `409` | `AUTOMATION_DELIVERY_SCOPE_MISMATCH` | Geltungsbereich der ursprünglichen Zustellungs-ID prüfen |
| `413` | Body zu groß | Nutzdaten auf unter 256 KiB reduzieren |
| `429` | Sender- oder Triggerbudget erschöpft | Mindestens `Retry-After` abwarten |

Abgelehnte Eingaben erstellen keinen Lauf. Projektfehler unterscheiden absichtlich nicht zwischen fehlendem, archiviertem oder nicht passend installiertem Projekt und nennen keinen Automatisierungsnamen. `GET`, `HEAD` und `OPTIONS` erhalten dieselbe `404` wie ein ungültiges Token, ohne `Allow`-Header.

## Das Token ist die Berechtigung

Das Geheimnis in der URL berechtigt zur Zustellung. Dieser Endpunkt prüft keine HMAC-Signatur des Anbieters und verwendet keinen `Authorization`-Header. Die URL gehört nicht in öffentliche Fehlermeldungen, gemeinsam genutzte Logs oder Screenshots. Tale speichert ihren Hash und vergleicht in konstanter Zeit; Klartext wird nur beim Erzeugen ausgegeben.

| Änderung | Auswirkung auf das Token |
| --- | --- |
| Webhook per `PUT` mit `rotateToken: true` | Neues Token einmalig ausgegeben; alte URL sofort ungültig |
| Trigger löschen/lösen | Token widerrufen; Versionen und Laufhistorie bleiben |
| Webhook durch Zeitplan/Ereignis ersetzen | Token widerrufen; Antwort enthält `revoked: "webhook"` |
| Danach erneut einen Webhook binden | Neues Token; das ursprüngliche kehrt nicht zurück |
| `enabled: false` setzen | URL mit `404` ausgesetzt, Token bleibt erhalten |
| Wieder aktivieren, auch durch späteres `PUT` ohne `enabled` | Dieselbe ausgesetzte URL wird wieder aktiv |

<Warning>

Rotiere oder entferne den Trigger nach einem Leak. Deaktivieren setzt den Zugriff nur vorübergehend aus. Stimme eine Rotation mit dem Sender ab und ersetze dessen gespeicherte URL, bevor die Zustellung weitergeht.

</Warning>

Werte bei skriptgesteuerten Triggeränderungen `revoked` aus. So unterbricht ein geänderter Triggertyp nicht unbemerkt einen Partner, der weiter die alte URL nutzt.

## Idempotenz und Wiederholungen

Die Deduplizierung gilt je Trigger und Projekt in der URL. Dieselbe Zustellungs-ID kann in jedem Installationsprojekt einen Lauf starten. Tale prüft Projektaktivität und Installation auch vor der Rückgabe eines gespeicherten Duplikats.

| Identität | Zeitfenster | Was gleich bleiben muss |
| --- | --- | --- |
| Header mit Zustellungs-ID | 24 Stunden | ID-Wert und Geltungsbereich; ein anderer Body zählt trotzdem als dieselbe Zustellung |
| Ohne Zustellungs-ID | 2 Minuten | Bytegleicher Body und dieselbe URL |

Bei Headern gewinnt der erste vorhandene Eintrag dieser Prioritätsfolge:

```text
Idempotency-Key
X-Idempotency-Key
webhook-id
X-GitHub-Delivery
X-Gitlab-Event-UUID
X-Shopify-Webhook-Id
Linear-Delivery
X-Atlassian-Webhook-Identifier
X-Request-UUID
I-Twilio-Idempotency-Token
X-Webhook-Id
```

Die Headernamen sind Alternativen, keine getrennten Namensräume. Eine Anbieter-ID unter `Idempotency-Key` bleibt dieselbe Identität. Ohne ID verändern schon andere JSON-Leerzeichen die Bytes und können eine neue Zustellung erzeugen. Nutze nach Möglichkeit eine ausdrückliche, stabile Ereignis-ID.

Wiederholst du die Beispielanfrage innerhalb von 24 Stunden, erhältst du die ursprüngliche `runId` mit `duplicate: true`. Eine fehlgeschlagene Automatisierung wird dadurch nicht erneut ausgeführt. Entscheide gezielt, wie du den fehlgeschlagenen Lauf behebst, statt beliebig die Zustellungs-ID zu ändern.

Wiederhole Netzwerkfehler und vorübergehende `5xx`-Antworten mit begrenzten, exponentiell wachsenden Wartezeiten. Beachte bei `429` den Header `Retry-After`. Behalte die ID bei, wenn eine Antwort verloren gegangen sein könnte. Andere `4xx`-Ursachen musst du zuerst beheben. Die Deduplizierung verhindert zusätzliche Läufe innerhalb ihres Fensters, garantiert aber keine genau einmal angewendeten Auswirkungen in externen Diensten.

## Budgets

| Budget | Auffüllung | Kurzzeitmaximum | Belastet |
| --- | --- | --- | --- |
| Sender-IP laut vertrauenswürdigen Proxys | 120/Minute | 240 | Vor der Token-Prüfung |
| Verifizierter Trigger | 20/Minute | 40 | Bei der Zulassung der Zustellung |

Jedes Budget kann `429` mit `Retry-After` in ganzen Sekunden und der normalen Fehlerhülle auslösen. Das Token berechtigt zum Triggerzugriff; es gibt aber keine zusätzliche Senderkonto-Identität für ein eigenes Budget. Nutze die [Ratenlimit-Referenz](https://docs.tale.dev/de/develop/rate-limits) und behalte beim Warten dieselbe Zustellungs-ID.

## Webhook oder API-Schlüssel wählen

Verwende einen Webhook für Sender mit fester Ereignis-URL. Nutze einen API-Schlüssel, wenn dein Client zusätzlich Automatisierungen finden, Projekte auswählen oder Ergebnisse lesen muss. [Trigger](https://docs.tale.dev/de/platform/automations/triggers) erklärt die Einrichtung in der App; die [API-Referenz](https://docs.tale.dev/de/develop/api-reference) beschreibt authentifizierte Starts und Abfragen.

# Einen Arbeitsbereich fürs Team einrichten
Source: https://docs.tale.dev/de/get-started/admins

Ein nutzbarer Arbeitsbereich braucht eine Organisation, einen funktionierenden Modellanbieter und Konten mit passenden Rechten. Richte diese Grundlagen ein und ergänze danach die Kontrollen für eure geplante Arbeit.

## Was du brauchst

Melde dich auf der richtigen Instanz als Inhaber oder Admin an. Die Ersteinrichtung erstellt das erste Konto und die Organisation. Siehst du deine Organisation bereits im Dashboard, öffne ihre Einstellungen, statt eine weitere anzulegen.

Halte die Anbieter-Zugangsdaten im Passwortmanager bereit. Der Anbieter muss das gewünschte Modell und die vorgesehenen Aufgaben unterstützen. [KI-Anbieter](https://docs.tale.dev/de/platform/admin/providers) erklärt Zugangsdaten, Kataloge und Agentenlaufzeiten.

## Einen Anbieter verbinden und Chat testen

<Steps>

<Step title="Zugangsdaten hinzufügen">

Öffne **Einstellungen > KI-Anbieter**, wähle **Zugangsdaten hinzufügen** und dann den Anbieter. Fülle die Felder seiner Anmeldemethode aus und speichere. Wähle einen Namen, an dem andere Admins den Verwendungszweck erkennen.

<Frame caption="Verbundene Zugangsdaten stellen die Modelle des Anbieters im Arbeitsbereich bereit.">

![Die Einstellungen für KI-Anbieter zeigen die verbundenen Anbieter-Zugangsdaten.](https://docs.tale.dev/images/get-started/settings-providers.webp)

</Frame>

</Step>

<Step title="Das Modell in einem neuen Chat prüfen">

Öffne **Start**, wähle **Neuer Chat** und dann ein verfügbares Modell. Sende einen eigenständigen Prompt wie „Schreibe eine Checkliste mit drei Punkten für eine Besprechung“. Warte auf die vollständige Antwort. Gespeicherte Zugangsdaten allein belegen noch keinen Zugriff auf das gewählte Modell.

Bleibt die Modellauswahl leer oder lehnt der Anbieter die Anfrage ab, folge der Fehlersuche unter [KI-Anbieter](https://docs.tale.dev/de/platform/admin/providers).

</Step>

</Steps>

## Personen mit passenden Rechten hinzufügen

Öffne **Einstellungen > Mitglieder** und wähle **Mitglied hinzufügen**. Für ein neues Konto legst du im Formular ein erstes Passwort fest. Ein vorhandenes Konto behält seine Zugangsdaten. Dieser Ablauf versendet keine Einladung per E-Mail. [Mitglieder und Rollen](https://docs.tale.dev/de/platform/admin/members-and-roles) erklärt die Felder und die sichere Übergabe der ersten Zugangsdaten.

<Frame caption="Prüfe die Rolle jedes Mitglieds, bevor du den Zugang übergibst.">

![Die Mitgliederseite zeigt die Personen der Organisation und ihre zugewiesenen Rollen.](https://docs.tale.dev/images/get-started/settings-organization-members.webp)

</Frame>

Wähle die Rolle nach der Aufgabe: Mitglieder nutzen den Arbeitsbereich, Bearbeiter pflegen gemeinsame Inhalte, Entwickler arbeiten an Integrationen und Automatisierungen, Admins verwalten die Organisation. Bei Grenzfällen hilft die genaue Berechtigungstabelle. Teams und Projektfreigaben bestimmen zusätzlich, auf welche Projektarbeit eine Person zugreifen kann.

## Den ersten Teamablauf prüfen

Bitte ein Teammitglied, sich mit dem eigenen Konto anzumelden, eine Nachricht zu senden und das benötigte Projekt zu öffnen. Prüfe gemeinsame Quellen ebenfalls mit diesem Konto. Tests nur als Inhaber können fehlende Rechte oder zu weitgehenden Zugriff verdecken.

<Tip>

Beginne mit einem typischen Projekt und wenigen Quelldokumenten. Prüfe, ob das Team die Arbeit findet und die vorgesehenen Konten auf die Dateien zugreifen können, bevor du eine große Bibliothek importierst.

</Tip>

## Betriebsregeln festlegen

Prüfe je nach Bedarf [Richtlinien und Limits](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits), [Audit-Logs](https://docs.tale.dev/de/platform/admin/governance/audit-logs) und [SSO](https://docs.tale.dev/de/platform/admin/enterprise-sso). Lege fest, wer Zugangsdaten pflegt, Rechte kontrolliert und fehlgeschlagene Aufträge bearbeitet. Im Eigenbetrieb braucht ihr außerdem einen getesteten Ablauf für [Sicherung und Wiederherstellung](https://docs.tale.dev/de/self-hosted/operate/backups-and-restore).

# Deine erste API-Anfrage
Source: https://docs.tale.dev/de/get-started/developers

Prüfe zu Beginn einer Integration drei Dinge: Der Schlüssel authentifiziert sich, die Anfrage erreicht die richtige Organisation und dort sind die benötigten Ressourcen verfügbar. Diese Anleitung führt dich mit curl durch diese Prüfungen. Du brauchst eine laufende Instanz und die Berechtigung zum Erstellen von API-Schlüsseln, üblicherweise als Entwickler, Admin oder Inhaber.

## Einen Schlüssel für die Integration erstellen

Öffne **Einstellungen > API > REST** und wähle **API-Schlüssel erstellen**. Vergib einen zweckbezogenen Namen, wähle eine Ablaufzeit und dann **Schlüssel erstellen**. Kopiere den Wert sofort; Tale zeigt das Geheimnis nur einmal.

<Frame caption="Verwende pro Integration einen erkennbaren Schlüssel, den du unabhängig ersetzen oder widerrufen kannst.">

![Im Dialog zum Erstellen eines API-Schlüssels legst du vor der Erstellung einen Namen und die Gültigkeitsdauer fest.](https://docs.tale.dev/images/get-started/settings-api-keys.webp)

</Frame>

Lade das Geheimnis aus einem Secret-Manager oder einer privaten Shell-Umgebung in `TALE_API_KEY`. Setze `TALE_BASE_URL` auf deine Instanz, etwa `https://your-host.example.com`. Hänge noch kein `/api/v1` an; die folgenden Befehle ergänzen den Pfad.

## Konto und Organisation bestimmen

Rufe `/me` ohne Organisationsheader auf. Bei einer Mitgliedschaft erhältst du die Identität des Schlüssels und die Organisation. Bei mehreren Mitgliedschaften antwortet der Endpunkt mit `400 ORG_SLUG_REQUIRED` und listet die Auswahl in `data.organizations` auf:

```bash
curl --fail-with-body --silent --show-error "$TALE_BASE_URL/api/v1/me" \
  -H "Authorization: Bearer $TALE_API_KEY"
```

Setze `TALE_ORG_SLUG` auf den gewählten Slug und wiederhole `/me` mit diesem Geltungsbereich. Die Dashboard-URL enthält eine Organisations-ID; verwende sie nicht als Slug. Bei `400` beendet sich curl im ersten Aufruf mit Code 22, gibt den JSON-Inhalt aber trotzdem aus.

```bash
curl --fail-with-body --silent --show-error "$TALE_BASE_URL/api/v1/me" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG"
```

Prüfe in der erfolgreichen Antwort das Konto, die Organisation, die Berechtigungen und `key.expiresAt`, bevor du fortfährst.

Der Schlüssel verwendet die aktuellen Mitgliedschaften und Rechte seines Inhabers. Mehrere Schlüssel eines Kontos erzeugen keine unabhängigen Rollen oder Anfragelimits. Plane den Austausch vor Ablauf; `/api/v1` verwaltet API-Schlüssel nicht für dich.

## Ein verfügbares Modell finden

Gib beim Auflisten der Modelle die Organisation ausdrücklich an:

```bash
curl --fail-with-body --silent --show-error "$TALE_BASE_URL/api/v1/models" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG"
```

<Check>

Eine `200`-Antwort mit dem Array `models` bestätigt diese authentifizierte Anfrage im Organisationskontext. Ein leeres Array bestätigt den Zugriff auf den Endpunkt, aber noch nicht die Bereitschaft für eine Modellantwort.

</Check>

Verwende die `id` eines Modells in Chatanfragen und zusätzlich `providerSlug`, wenn mehrere Anbieter diese ID führen. Ein gelistetes Modell kann dem Anbieterkonto wegen Guthaben oder Tarif trotzdem nicht zur Verfügung stehen. Bitte bei einer leeren Liste einen Admin, Zugangsdaten und Modellzugriff zu prüfen.

## Den ersten Fehler beheben

| Antwort | Nächste Aktion |
| --- | --- |
| `401` | Prüfe Bearer-Schlüssel, Ablaufzeit und Widerruf. |
| `400` mit `ORG_SLUG_REQUIRED` | Wähle einen Slug aus `data.organizations` in dieser Fehlermeldung und sende `X-Organization-Slug`. |
| `404` mit `ORG_SLUG_INVALID` | Der Header benennt gar keine Organisation — ein Tippfehler, oder die Organisations-ID aus der Dashboard-URL wurde als Slug eingesetzt. Sende den Slug aus `data.organizations`. |
| `403` mit `ORG_FORBIDDEN` | Die Organisation existiert, aber der Schlüsselbesitzer ist dort kein Mitglied. Wähle einen Slug aus `data.organizations`. |
| `403` | Prüfe die für die Aktion nötige Berechtigung. |
| `429` | Warte gemäß `Retry-After`; lies [Ratenlimits](https://docs.tale.dev/de/develop/rate-limits). |

Meldet curl vor einer JSON-Antwort einen TLS- oder Netzwerkfehler, prüfe Host und Zertifikat. Schalte die Zertifikatsprüfung in Produktivskripten nicht ab.

## Die nächste Aufgabe wählen

| Du möchtest… | Lies weiter bei |
| --- | --- |
| Eine fertige Assistentenantwort ausgeben | [Tale aus einem Skript aufrufen](https://docs.tale.dev/de/tutorials/developer/call-tale-from-a-script). |
| Eine Automation aus einem anderen System starten | [Eine Automation per Webhook auslösen](https://docs.tale.dev/de/tutorials/developer/trigger-automation-via-webhook). |
| Einen MCP-Client verbinden | [MCP-Endpunkt](https://docs.tale.dev/de/develop/mcp-endpoint). |
| Tale aus opencode, Claude Code oder einem Shell-Skript nutzen | [Tale aus deinem Editor oder einem Skript nutzen](https://docs.tale.dev/de/develop/use-tale-from-your-editor). |
| Mit Projektdateien, Aufgaben oder Läufen arbeiten | [API-Referenz](https://docs.tale.dev/de/develop/api-reference). |

Verwende für projektbezogene Arbeit Routen unter `/api/v1/projects/{id}/...`. Die Projekt-ID gehört in den Pfad, der Organisations-Slug in die Kopfzeile. Halte beide Werte in der Integrationskonfiguration ausdrücklich fest.

# Einen Projektagenten erstellen und testen
Source: https://docs.tale.dev/de/get-started/editors

Erstelle einen Projektagenten für eine wiederkehrende Aufgabe, etwa das Prüfen von Dokumenten oder das Erstellen eines betrieblichen Berichts. Du legst Anweisungen, Laufzeit, Modell und Werkzeuge fest und gibst ihm dann eine Aufgabe mit einem prüfbaren Ergebnis. Diese Anleitung zeigt den Ablauf am Prüfen eines Launch-Briefings. Solange ein Projekt keinen eigenen Agenten hat, können seine Aufgaben an den [Standard-Agenten](https://docs.tale.dev/de/platform/projects/project-agents#standard-agent) der Organisation gehen.

## Was du brauchst

Du brauchst Bearbeitungsrechte im Projekt, einen geeigneten Modellanbieter und eine verfügbare Agentenlaufzeit samt benötigter Infrastruktur. Ein funktionierender Chat prüft den Chat-Zugriff des Anbieters. Er belegt nicht, dass Agentenlaufzeit oder Sandbox bereitstehen. Bitte einen Admin, die [Agentenlaufzeiten](https://docs.tale.dev/de/platform/agents/harnesses) zu prüfen, wenn keine verfügbar ist.

Erstelle oder öffne zuerst ein Projekt. [Projekte nutzen](https://docs.tale.dev/de/tutorials/member/use-projects) erklärt Freigaben und Wissensquellen.

## Einen klaren Auftrag geben

<Steps>

<Step title="Einen Agenten im Projekt erstellen">

Öffne den Tab **Agenten** und wähle **Neuer Agent**. Benenne ihn nach seiner Aufgabe, etwa „Launch-Prüfer“. Wähle unter **Agent-Laufzeit** und **Modell** die passende Kombination, die dein Arbeitsbereich unterstützt. Gibt es mehrere Anbietereinträge für dasselbe Modell, wähle auch den vorgesehenen Anbieter.

<Frame caption="Projektagenten verbinden eine benannte Aufgabe mit Laufzeit und Modell.">

![Der Agenten-Tab des Projekts zeigt Agenten mit ihrer konfigurierten Laufzeit und ihrem Modell.](https://docs.tale.dev/images/platform/project-agents-models.webp)

</Frame>

</Step>

<Step title="Prüfbare Anweisungen formulieren">

Beschreibe unter **Anweisungen** die Aufgabe, die Quellen, das Ausgabeformat und die Grenzen. Zum Beispiel:

> Prüfe das an die Aufgabe angehängte Launch-Briefing. Liste fehlende Entscheidungen, unklare Zuständigkeiten und Widersprüche auf. Zitiere zu jedem Befund die betreffende Stelle. Ändere keine Dateien und kontaktiere keine externen Dienste. Fehlt das Briefing, frage danach.

Gewähre nur die **Skills, Connectors & Tools** und **Secrets**, die diese Aufgabe braucht. Speichere mit **Agent erstellen**. Nach dem ersten Ergebnis kannst du den Auftrag überarbeiten.

</Step>

<Step title="Eine konkrete Aufgabe zuweisen und starten">

Erstelle eine Aufgabe mit klarer Beschreibung und den nötigen Eingabedateien. Weise den Agenten zu und wähle dann **Agent starten**. Zuweisen und Starten sind getrennte Aktionen. Beobachte während der Ausführung Status und Aktivität der Aufgabe.

Kann der Agent nicht starten, lies zuerst die angezeigte Ursache. Fehlende Anbieter, nicht verfügbare Laufzeiten, Richtlinien und fehlende Eingaben erfordern unterschiedliche Lösungen.

</Step>

</Steps>

## Das Ergebnis prüfen

Lies den Aufgabenkommentar des Agenten und mögliche Ausgabedateien. Vergleiche sie mit dem Auftrag: Wurde die richtige Quelle geprüft, ist jeder Befund belegt und blieb der Agent im vorgegebenen Rahmen? Eine abgeschlossene Ausführung bedeutet noch kein richtiges Ergebnis.

Halte Prüfung und Abschluss bewusst fest. Gib über die Aufgabenfunktionen Rückmeldung, fordere bei Bedarf einen weiteren Durchlauf an und schließe akzeptierte Arbeit ab. [Projektaufgaben](https://docs.tale.dev/de/platform/projects/tasks) erklärt Status und Prüferfeld.

<Tip>

Teste neben einer normalen Aufgabe auch fehlende Eingaben. Ein Agent, der nach einem fehlenden Briefing fragt, hilft mehr als einer, der dessen Inhalt erfindet.

</Tip>

## Schrittweise verfeinern

Verbessere die Anweisung, die zum schlechten Ergebnis geführt hat, und teste eine vergleichbare Aufgabe. Ergänze Werkzeuge nur bei Bedarf. Prüfe vor externen Schreibaktionen das [Genehmigungsverhalten](https://docs.tale.dev/de/platform/approvals/concepts). Ein längeres Beispiel findest du unter [Dein erster Agent von Anfang bis Ende](https://docs.tale.dev/de/tutorials/editor/first-agent-end-to-end).

Sobald du das Ergebnis einer Aufgabe verlässlich beurteilen kannst, setze denselben Agenten für ähnliche Arbeit ein. Braucht der Prozess geplante Ausführungen, feste Phasen oder Genehmigungen für Connector-Aktionen, bilde diese Anforderungen in einer [Automatisierung](https://docs.tale.dev/de/platform/automations/concepts) ab.

# Tale im Team nutzen
Source: https://docs.tale.dev/de/get-started/members

Deine tägliche Arbeit in Tale beginnt mit einem Gespräch oder einem Projekt. Diese Anleitung hilft dir, den passenden Ort für eine Frage, ein Dokument und gemeinsame Arbeit zu finden.

## Deinen Zugriff kennen

Du brauchst ein angemeldetes Konto und einen funktionierenden [ersten Chat](https://docs.tale.dev/de/get-started/quickstart). Rolle und Projektzugriff legen fest, was du lesen oder ändern darfst. Mitglieder können chatten und in zugänglichen Projekten arbeiten. Organisationsweite Wissensquellen zu bearbeiten erfordert die Rolle Bearbeiter oder höher; für Projektarbeit gelten die Zugriffsregeln des Projekts. Fehlt ein Bedienelement, prüfe [Mitglieder und Rollen](https://docs.tale.dev/de/platform/admin/members-and-roles).

## Eine Frage mit ausreichend Kontext stellen

Öffne **Start** und wähle **Neuer Chat**. Beschreibe die Aufgabe, gib die nötigen Informationen mit und nenne das gewünschte Ergebnisformat. Füge etwa Besprechungsnotizen ein und bitte um Entscheidungen, Zuständige und offene Fragen.

Lies die Antwort, bevor du sie verwendest. Enthält sie eine Quellenangabe, öffne die Quelle und prüfe, ob sie die Aussage belegt. Eine flüssige Antwort beweist nicht, dass das richtige Dokument verwendet wurde. [Wirksam chatten](https://docs.tale.dev/de/tutorials/member/chat-effectively) zeigt, wie du mit Anschlussfragen weiterkommst.

## Informationen passend ablegen

| Du möchtest… | Verwende… |
| --- | --- |
| Eine Datei in diesem Gespräch besprechen | Einen [Chat-Anhang](https://docs.tale.dev/de/platform/chat/attachments) |
| Quellenmaterial beim Projekt behalten | Den [Wissen-Tab des Projekts](https://docs.tale.dev/de/platform/projects/manage-files) |
| Freigegebenes Material als Organisationswissen bereitstellen | [Wissensdokumente](https://docs.tale.dev/de/platform/knowledge/documents) |
| Einen kurzen wiederverwendbaren Artikel pflegen | Einen [Wissenseintrag](https://docs.tale.dev/de/platform/knowledge/knowledge-entries) |

Lege vor dem Hochladen fest, wer die Informationen nutzen soll. Organisationswissen und Projektdateien haben unterschiedliche Zugriffsgrenzen. Hochladen und Suchbarkeit sind getrennte Schritte. Warte auf die Indexierung, bevor du den Abruf testest.

<Frame caption="Die Dokumentliste zeigt hochgeladene Dateien und ihren Indexierungsstatus. Die Ansicht ist auf hochgeladene, indexierte Dateien gefiltert.">

![Die Dokumenttabelle zeigt Quelldateien mit ihrem Indexierungsstatus.](https://docs.tale.dev/images/get-started/documents-list.webp)

</Frame>

Kannst du eine gemeinsame Quelle nicht hinzufügen, bitte eine Person mit Bearbeitungsrechten darum. Nenne die Zielgruppe und den vorgesehenen Ablageort.

## In einem Projekt arbeiten

Wähle im Bereich **Start** unter **Projekte** ein Projekt, auf das du zugreifen kannst. Unter **Aufgaben** siehst du die Arbeit, unter **Wissen** die Projektdateien und unter **Chats** die Gespräche. Projektchats bleiben persönlich, bis du sie mit dem Projekt teilst.

<Frame caption="Das Board gruppiert Arbeit nach Status; eine Karte öffnet die Aufgabendetails.">

![Ein Projektboard ordnet Aufgaben den Spalten Backlog, Zu erledigen, In Bearbeitung, In Prüfung, Erledigt und Abgebrochen zu.](https://docs.tale.dev/images/platform/projects-task-board.webp)

</Frame>

Öffne eine Aufgabe und lies Beschreibung, Zuweisung und Diskussion. In jedem Projekt, das du öffnen kannst, erstellst du Aufgaben und änderst die, die du erstellt hast oder die dir zugewiesen sind, etwa um die Arbeit einem Agenten des Projekts zu übergeben oder, in einem Projekt ohne eigene Agenten, dem [Standard-Agenten](https://docs.tale.dev/de/platform/projects/project-agents#standard-agent) der Organisation. [Projektaufgaben verwalten](https://docs.tale.dev/de/platform/projects/tasks) erklärt die tägliche Aufgabenarbeit; [Projekte nutzen](https://docs.tale.dev/de/tutorials/member/use-projects) führt durch ein vollständiges Beispiel.

## Zur Arbeit zurückkehren

Jeder Bereich öffnet seine eigene erste Seite – egal, was du dort zuletzt getan hast. Am Computer ist **Start** die Ausnahme: Dort öffnet sich der Chat, den du zuletzt gelesen hast, und wählst du **Start** erneut, beginnt ein neuer Chat. Die [Navigationsanleitung](https://docs.tale.dev/de/platform#navigation) erklärt die Bedienelemente am Computer und auf dem Smartphone.

**Start** zeigt deine Chats zusammen mit den offenen Aufgaben, die dir zugewiesen sind oder auf dein Review warten. Mit **Chats** oder **Aufgaben** über der Liste siehst du nur eine der beiden Arten. Ist die Seitenleiste ausgeblendet, holt **Seitenleiste einblenden** am Anfang der Kopfzeile sie zurück. Beginne für ein neues Thema einen neuen Chat und teile Projektgespräche bewusst, wenn andere sie benötigen.

Sprache und Erscheinungsbild findest du unter **Konto verwalten**. Die [Einstellungen](https://docs.tale.dev/de/platform/member/preferences) erklären weitere Kontofunktionen und wo sie wirken.

# Deine erste Nachricht senden
Source: https://docs.tale.dev/de/get-started/quickstart

Beginne hier, wenn du Zugang zu einem Tale-Arbeitsbereich hast und deine erste Antwort erhalten möchtest. Du sendest einen kurzen Prompt, liest die Antwort und findest das Gespräch anschließend wieder.

## Was du brauchst

Du brauchst die Adresse deiner Instanz, ein Konto und einen Arbeitsbereich mit verbundenem KI-Anbieter. Bitte die zuständige Person um Zugang. Eine eigene Instanz richtest du mit dem [Schnellstart für den Eigenbetrieb](https://docs.tale.dev/de/self-hosted/install/quickstart) ein. Für eine verwaltete Instanz gibt es den [Cloud-Einstieg](https://docs.tale.dev/de/cloud/onboarding).

Mit deinem Konto meldest du dich an. Die Organisation ist der Arbeitsbereich für Mitglieder, Projekte und Konfiguration deines Teams. Deine Rolle legt fest, welche Aktionen du dort ausführen darfst.

## Ein Gespräch beginnen

<Steps>

<Step title="Anmelden und einen Chat beginnen">

Öffne deine Instanz und melde dich mit der vom Admin vorgesehenen Methode an. Gehörst du mehreren Organisationen an, wähle den passenden Arbeitsbereich. Öffne **Start** und wähle dann **Neuer Chat**, den Stift oben in der Liste von **Start**.

</Step>

<Step title="Modell prüfen und Prompt schreiben">

Über die Modellauswahl unter dem Nachrichtenfeld siehst du die verfügbaren Modelle. Dort kann **Auto** stehen. Wähle ein bestimmtes Modell, wenn du selbst festlegen möchtest, welches antwortet. Das Angebot hängt von den verbundenen Anbietern und Zugriffsregeln deines Arbeitsbereichs ab.

<Frame caption="Nachrichtenfeld und Modellauswahl liegen im selben Eingabebereich.">

![Der Chat-Eingabebereich enthält das Nachrichtenfeld, die Modellauswahl, die Anhangfunktionen und die Schaltfläche zum Senden.](https://docs.tale.dev/images/platform/chat-composer.webp)

</Frame>

Teste zuerst eine Anfrage ohne weitere Quellen: „Schreibe eine Checkliste mit drei Punkten zur Vorbereitung einer Teamsitzung. Verwende pro Punkt einen Satz.“ Dafür brauchst du weder hochgeladene Dokumente noch verbundene Werkzeuge.

</Step>

<Step title="Senden und Antwort lesen">

Wähle **Nachricht senden** oder drücke Enter. Deine Nachricht erscheint im Gespräch, danach folgt die Antwort des Assistenten. Vor der Antwort kann ein Denkhinweis erscheinen. Warte bis zum Ende, bevor du das Ergebnis beurteilst.

Prüfe, ob Länge und Format stimmen. Stelle eine Anschlussfrage, etwa: „Ergänze, wer den jeweiligen Punkt vorbereiten sollte.“ Im selben Gespräch bleiben die vorherigen Nachrichten als Kontext erhalten.

</Step>

</Steps>

## Den Chat wiederfinden

**Start** führt das Gespräch unter **Heute** auf; wähle es dort aus, um es wieder zu öffnen. Ein neuer Chat beginnt ein separates Gespräch und eignet sich für einen Themenwechsel. [Chat-Grundlagen](https://docs.tale.dev/de/platform/chat/basics) erklärt Namen, Verlauf und Antwortfunktionen.

<Tip>

Nenne Ziel, benötigte Informationen und Ausgabeformat. „Fasse diese Notizen als Entscheidungen und offene Fragen zusammen“ beschreibt die Aufgabe genauer als „Hilf mir damit“.

</Tip>

## Wenn keine Antwort kommt

| Was du siehst | Was du tun kannst |
| --- | --- |
| Die Anmeldung funktioniert nicht | Prüfe Instanzadresse und Anmeldemethode mit deinem Admin. |
| Es sind keine Modelle verfügbar | Bitte einen Admin, [KI-Anbieter](https://docs.tale.dev/de/platform/admin/providers) und deinen Modellzugriff zu prüfen. |
| Ein Anbieter- oder Modellfehler erscheint | Teste ein anderes verfügbares Modell und gib den angezeigten Fehler an den Admin weiter. |
| Eine Nutzungsgrenze wurde erreicht | Bitte den Admin, die betreffende [Richtlinie](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits) zu prüfen. |
| Die Antwort verwendet deine Dokumente nicht | Der erste Prompt enthielt keine Quelle. Ergänze sie über [Chat-Anhänge](https://docs.tale.dev/de/platform/chat/attachments) oder [Wissen](https://docs.tale.dev/de/platform/knowledge/overview). |

Lies weiter mit [Tale im Team nutzen](https://docs.tale.dev/de/get-started/members) oder [wirksame Prompts schreiben](https://docs.tale.dev/de/tutorials/member/chat-effectively).

<Video src="https://docs.tale.dev/videos/de/tutorials/ep1-welcome/ep1-welcome.de.mp4" poster="https://docs.tale.dev/videos/de/tutorials/ep1-welcome/ep1-welcome.de.webp" captions="https://docs.tale.dev/videos/de/tutorials/ep1-welcome/ep1-welcome.de.vtt" lang="de" title="Episode 1 — Willkommen bei Tale" caption="Episode 1 — Willkommen bei Tale (3:25)">

</Video>

# Tale-Dokumentation
Source: https://docs.tale.dev/de

Finde dich in Tale zurecht, gib einem Agenten seine erste Aufgabe oder baue auf der Plattform auf. Mit einem bestehenden Konto kannst du [deine erste Nachricht senden](https://docs.tale.dev/de/get-started/quickstart). Wenn du Tale selbst betreiben möchtest, [installiere deinen eigenen Arbeitsbereich](https://docs.tale.dev/de/self-hosted/install/quickstart).

## Von der Aufgabe zum Ergebnis

1. [Beschreibe die Arbeit](https://docs.tale.dev/de/platform/projects/tasks). Gib der Aufgabe ein Ziel, Quelldateien und ein klares Ergebnis.
2. [Gib die Aufgabe einem Agenten](https://docs.tale.dev/de/get-started/editors). Wähle Anweisungen und Werkzeuge und starte dann die Arbeit.
3. [Prüfe das Ergebnis](https://docs.tale.dev/de/platform/projects/task-automation). Prüfe Bericht und Dateien. Gib das Ergebnis frei oder fordere Änderungen an.

Jede Anleitung erklärt die nötigen Zugriffsrechte und Voraussetzungen. Ein funktionierender Chat beweist noch nicht, dass Agentenlaufzeit und Sandbox bereit sind.

## Was möchtest du tun?

<CardGroup cols="2">

<Card title="Einen Projektagenten erstellen und testen" icon="bot" href="https://docs.tale.dev/de/get-started/editors">

Richte einen Agenten mit einer klaren Aufgabe ein, lass ihn eine Projektaufgabe bearbeiten und prüfe sein erstes Ergebnis.

</Card>

<Card title="Mit deinem Team arbeiten" icon="users" href="https://docs.tale.dev/de/get-started/members">

Finde deine Gespräche, arbeite mit Quellen und öffne ein Projekt.

</Card>

<Card title="Einen Arbeitsbereich einrichten" icon="shield" href="https://docs.tale.dev/de/get-started/admins">

Verbinde einen Anbieter, lade Personen ein und lege ihre Zugriffsrechte fest.

</Card>

<Card title="Ein anderes System anbinden" icon="code" href="https://docs.tale.dev/de/get-started/developers">

Sende deine erste API-Anfrage und prüfe die Antwort.

</Card>

</CardGroup>

## Beim Ausprobieren lernen

Arbeite eine vollständige Aufgabe mit Beispieleingaben und Prüfschritten durch. Prüfe zuerst die Voraussetzungen oder [sieh dir alle Tutorials an](https://docs.tale.dev/de/tutorials/overview).

<CardGroup cols="3">

<Card title="Arbeit in einem Projekt organisieren" icon="folder" href="https://docs.tale.dev/de/tutorials/member/use-projects">

Führe eine Aufgabe, Quelldateien und Projektanweisungen zusammen.

</Card>

<Card title="Deinen ersten Agenten starten" icon="bot" href="https://docs.tale.dev/de/tutorials/editor/first-agent-end-to-end">

Starte eine delegierte Aufgabe und prüfe den Bericht und die gelieferten Dateien.

</Card>

<Card title="Einen Workflow mit Freigaben bauen" icon="check-check" href="https://docs.tale.dev/de/tutorials/editor/workflow-with-approvals">

Prüfe eine Aktion, bevor der Workflow sie ausführt.

</Card>

</CardGroup>

## Die passende Referenz finden

- [Plattformanleitungen](https://docs.tale.dev/de/platform) erklären Bedienelemente, Berechtigungen, erwartetes Verhalten und Fehlersuche.
- Die [API-Referenz](https://docs.tale.dev/de/develop/api-reference) beschreibt den Vertrag für die Anbindung anderer Systeme.
- [Selbst gehostetes Tale](https://docs.tale.dev/de/self-hosted) behandelt Installation, Konfiguration, Sicherungen und Upgrades.
- [Tale Cloud](https://docs.tale.dev/de/cloud) erklärt verwaltetes Hosting und Zuständigkeiten im Betrieb.

Die Produktanleitungen gelten für Cloud-Instanzen und selbst gehostete Instanzen. Screenshots zeigen die englische Oberfläche; deutsche und französische Seiten verwenden die Bezeichnungen ihrer jeweiligen Sprache.

# Projektagenten verwalten und prüfen
Source: https://docs.tale.dev/de/platform/admin/agents

Verwalte einen Agenten über sein Projekt und die Ressourcen der Organisation. Es gibt keine zusätzliche organisationsweite Agentenliste zum Konfigurieren. Öffne das Projekt im Bereich **Start** unter **Projekte** und wähle dann **Agenten**, um seine Agenten zu prüfen oder zu bearbeiten.

## Die Bearbeitungsrechte klären

Wer das Projekt lesen darf, sieht seine Agenten. Personen mit Bearbeitungszugriff können sie im aktiven Projekt erstellen, ändern und löschen. Archivierte Projekte bleiben lesbar. Prüfe [Mitgliederrollen](https://docs.tale.dev/de/platform/admin/members-and-roles) und [Team-Zugriff](https://docs.tale.dev/de/platform/admin/teams), wenn eine Person unerwartet Zugriff hat oder ihr der Zugriff fehlt.

Ein Agent gehört genau einem Projekt. Seine ID und der Zugriff auf ein zweites Projekt erlauben einer Integration nicht, ihn als Agenten dieses zweiten Projekts zu verwenden. Pro Projekt sind bis zu 50 Agenten möglich, mit jeweils eindeutigen Namen.

## Vor dem Start die Ressourcen prüfen

Öffne den Bearbeitungsdialog des Agenten und prüfe das Zusammenspiel der Einstellungen, nicht nur das Modell:

| Prüfung | Warum sie nötig ist | Wo du ein Problem klärst |
| --- | --- | --- |
| Harness, Modell und Provider | Die Zugangsdaten müssen diesen Ausführungsweg unterstützen. | [KI-Provider](https://docs.tale.dev/de/platform/admin/providers). |
| Skills und ihre Freigabe | Der Team-Zugriff des Projekts bestimmt die verfügbaren Bundles. | [Skill-Bibliothek](https://docs.tale.dev/de/platform/workspace/skills) und Projektzugriff. |
| Connectors und Plattform-Tools | Sie erlauben Dienste und unterstützte Datenoperationen. | [Connector-Zugangsdaten](https://docs.tale.dev/de/platform/admin/connectors) und Ausstattung des Agenten. |
| Secrets | Die laufende Sitzung kann die zugeordneten Werte lesen. | **Secrets** im Agentendialog, für Inhaber und Admins. |
| Sandbox-Kapazität und Ausgaben | Die Arbeit braucht eine verfügbare Umgebung und ein zulässiges Budget. | [Sandboxes](https://docs.tale.dev/de/platform/admin/sandboxes) und [Richtlinien und Limits](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits). |

Für einen Review-Agenten können Repository-Lesezugriff und Werkzeuge zum Berichten genügen. Ein freigegebenes Schreib-Tool darf seine Operationen innerhalb der Zugriffsregeln ausführen. Eine dauerhafte Anweisung, zuerst nachzufragen, ersetzt nicht das Entfernen einer unnötigen Berechtigung.

## Secret-Änderungen gezielt vornehmen

Nur Inhaber und Admins dürfen Secret-Zuordnungen ändern. Ein Editor kann andere Felder bearbeiten und die vorhandenen Zuordnungen erhalten. Secret-Werte liegen verschlüsselt im Speicher der Organisation und werden nicht mit der Agentenkonfiguration zurückgegeben. Der laufende Agent erhält jedoch die ihm zugeordneten Werte.

Verwende eng begrenzte und austauschbare Zugangsdaten. Mehrere Agenten oder Automatisierungs-Nodes können denselben Secret-Namen nutzen. Austausch oder Löschung des Werts betrifft dann jeden künftigen Lauf, der darauf verweist. Prüfe diese Verwendungen vorher.

## API-Clients nach denselben Regeln prüfen

Die öffentliche API liest und schreibt dieselbe Agentenliste und prüft den Projektzugriff des Schlüsselinhabers. Jede Operation enthält eine Projekt-ID. Eine Aktualisierung übergibt die vollständige Konfiguration einschließlich der Secret-Zuordnungen, die erhalten bleiben sollen. Fehlende Zuordnungen bedeuten ihre Entfernung und benötigen deshalb administrative Rechte.

Das [API-Beispiel für Projektagenten](https://docs.tale.dev/de/develop/api-reference#agenten-eines-projekts-verwalten) beschreibt die Integration. Öffne nach einer Änderung den Agenten erneut und prüfe das gespeicherte Modell, die Ausstattung und die Zuordnungen. Gib ihm danach eine kleine Aufgabe mit einem von Menschen prüfbaren Ergebnis. [Projektagenten](https://docs.tale.dev/de/platform/projects/project-agents) führt durch diesen Ablauf.

# API-Schlüssel
Source: https://docs.tale.dev/de/platform/admin/api-keys

Erstelle einen API-Schlüssel, wenn ein Skript oder Dienst die REST-API von Tale aufrufen soll. Ein Schlüssel gehört der Person, die ihn erstellt hat, nicht der Organisation, auf deren Einstellungsseite er entstand: Er handelt im Namen dieser Person, verwendet ihre aktuellen Rechte und gilt in jeder Organisation, der sie angehört. Eine REST-Anfrage nennt die angesprochene Organisation im Header `X-Organization-Slug`; gehört der Inhaber nur einer Organisation an, darf er entfallen. Inhaber, Admins und Entwickler verwalten ihre Schlüssel unter **Einstellungen > API > REST**, ebenso ein Mitglied, dem ein Admin eine Kompetenz zugewiesen hat, die mit einem Schlüssel genutzt wird: **Modelle über die API aufrufen**, **Benachrichtigungen exportieren** oder **Für ein anderes Mitglied handeln**. Allen anderen verweigert Tale einen neuen Schlüssel mit `403 API_KEY_CREATE_FORBIDDEN`.

<Frame caption="Einstellungen > API > REST — wo Schlüssel erstellt, rotiert und widerrufen werden.">

![Im Dialog zum Erstellen eines API-Schlüssels legst du vor der Erstellung einen Namen und die Gültigkeitsdauer fest.](https://docs.tale.dev/images/get-started/settings-api-keys.webp)

</Frame>

## Einen Schlüssel erstellen

1. Wähle **API-Schlüssel erstellen**.
2. Gib unter **Schlüsselname** einen Namen ein, der den aufrufenden Dienst erkennen lässt, etwa `Abrechnungssynchronisation` oder `Dokumentimport`.
3. Wähle die **Ablaufzeit**: 7, 30 oder 90 Tage, ein Jahr oder nie. Voreingestellt sind 30 Tage.
4. Erstelle den Schlüssel und kopiere den geheimen Wert in den vorgesehenen sicheren Schlüsselspeicher des Dienstes, bevor du die Bestätigung schließt.

Der vollständige Wert wird nur einmal angezeigt. Später siehst du in der Tabelle nur ein maskiertes Fragment, das Erstellungsdatum und die letzte Nutzung. Die Liste enthält deine Schlüssel, nicht die anderer Mitglieder.

<Warning>

Wer einen Schlüssel besitzt, kann mit den Rechten seines Inhabers handeln. Halte ihn aus Quellcode, Chatnachrichten, Screenshots und Protokollen heraus. Nutze ein Konto mit genau den Zugriffsrechten, die die Integration braucht.

</Warning>

## Den Aufruf prüfen

Führe die authentifizierte Anfrage aus dem [API-Schnellstart](https://docs.tale.dev/de/get-started/developers) aus. Prüfe die zurückgegebene Identität und Organisation, bevor du Daten schreibst oder importierst. Kontrolliere anschließend **Zuletzt verwendet** in der Schlüsseltabelle.

Eine erfolgreiche Anmeldung erlaubt nicht automatisch den Zugriff auf jede Ressource. Projektfreigaben und die aktuelle Rolle des Schlüsselinhabers gelten weiterhin. Unterscheide anhand der API-Fehlermeldung zwischen einem abgelaufenen oder widerrufenen Schlüssel und fehlenden Ressourcenrechten.

## Ohne Unterbrechung rotieren

1. Erstelle vor Ablauf des alten Schlüssels einen Ersatz.
2. Aktualisiere den sicheren Schlüsselspeicher des aufrufenden Dienstes. Starte ihn neu oder lade seine Konfiguration neu, falls erforderlich.
3. Prüfe eine authentifizierte Anfrage mit dem neuen Schlüssel.
4. Widerrufe den alten Schlüssel erst, wenn alle abhängigen Aufrufer umgestellt sind.

Tale rotiert Schlüssel nicht automatisch. Erstellen und Widerrufen erfolgen in dieser Oberfläche, nicht über `/api/v1`. Ein Aufrufer kann Name und Ablaufzeit seines Schlüssels mit `GET /api/v1/me` auslesen und die verantwortliche Person rechtzeitig benachrichtigen.

## Einen Schlüssel widerrufen

Öffne das Zeilenmenü, wähle **Schlüssel widerrufen** und bestätige. Weitere Anfragen können sich mit diesem Schlüssel nicht mehr authentifizieren, auch Aufrufe der Modell-Endpunkte; eine Antwort, die bereits gestreamt wird, läuft zu Ende. Der Widerruf ist endgültig. Erstelle einen neuen Schlüssel, falls du den falschen widerrufen hast. Das Erstellen und das Widerrufen eines Schlüssels hinterlassen je einen Eintrag im Audit-Log unter **Einstellungen > Richtlinien > Protokolle**, und zwar in jeder Organisation, der du angehörst.

Ein altes Datum unter **Zuletzt verwendet** reicht allein nicht als Grund zum Widerruf. Ein monatlicher Auftrag oder ein Wiederherstellungsverfahren kann längere Zeit ungenutzt bleiben. Prüfe zuerst den Dienst, den der Name bezeichnet.

## Rechte und Limits verstehen

Rollenänderungen gelten bei folgenden Anfragen auch für bestehende Schlüssel. Wird die Mitgliedschaft des Inhabers deaktiviert, endet sein Zugriff. Der Schlüssel behält nicht die Rolle vom Erstellungszeitpunkt. Verlierst du die Rolle oder Kompetenz, mit der du Schlüssel erstellen durftest, bleiben deine bestehenden Schlüssel erhalten: **Einstellungen > API > REST** listet sie weiter, damit du sie widerrufen kannst, bietet aber keinen neuen an.

Gib einer Integration nur den Zugriff, den sie braucht. Ein Dienst, der Benachrichtigungen spiegelt, benötigt zum Beispiel kein Admin-Konto: Ein Admin kann einem gewöhnlichen Mitglied die Berechtigung `tale:notifications.export` erteilen. Sie erlaubt diesen Export, aber keines der übrigen Rechte der Admin-Rolle, gilt nur in der Organisation, kann ablaufen und endet, wenn das Mitglied entfernt wird. Weise sie unter [Kompetenzen](https://docs.tale.dev/de/platform/admin/governance/competences) zu. Dort erhält auch eine Integration, die Antworten und Prüfentscheidungen von Personen weiterreicht, auf dieselbe Weise `tale:rest.act-as`; [Export ohne Admin-Rolle delegieren](https://docs.tale.dev/de/develop/api-reference#export-ohne-admin-rolle-delegieren) beschreibt die API-Seite.

REST-Ratenlimits gelten für den authentifizierten Schlüsselinhaber. Mehrere Schlüssel derselben Person erhalten keine getrennten Kontingente. Siehe [Ratenlimits](https://docs.tale.dev/de/develop/rate-limits). Eine [Budgetregel](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits) kann zusätzlich begrenzen, was mit einem einzelnen Schlüssel authentifizierte Anfragen ausgeben dürfen: Ihre Nutzung wird dem Schlüssel angerechnet, und ein Senden oder ein Modellaufruf über der Grenze wird mit `429 BUDGET_EXCEEDED` abgelehnt. Auch Automatisierungsläufe, die mit dem Schlüssel gestartet wurden, zählen für ihn, zusätzlich zu den persönlichen Grenzen des Mitglieds, für das der Schlüssel handelt. [So wird die Nutzung gezählt](https://docs.tale.dev/de/platform/admin/governance/usage-attribution) beschreibt die Regel vollständig.

Ein Schlüssel kann außerdem die Modelle der Organisation aus Tools wie opencode oder Claude Code aufrufen, über die [Modell-Endpunkte](https://docs.tale.dev/de/develop/use-tale-from-your-editor#model-endpoints), sobald ein Admin sie unter [Modelle](https://docs.tale.dev/de/platform/admin/governance/content-models#model-endpoints) eingeschaltet hat. Die Person, der er gehört, muss Inhaber, Admin oder Entwickler sein oder die Kompetenz **Modelle über die API aufrufen** haben. Diese Aufrufe zählen wie seine Chatnachrichten für die Budgetregeln des Schlüssels und erscheinen in der Nutzungsanalyse als **Direkter API-Aufruf**, unter der Person und dem Schlüssel.

API-Schlüssel authentifizieren Software, die Tale aufruft. [Connector-Zugangsdaten](https://docs.tale.dev/de/platform/admin/connectors) dienen der Gegenrichtung: Damit ruft Tale einen externen Dienst auf. [Tale aus deinem Editor oder einem Skript nutzen](https://docs.tale.dev/de/develop/use-tale-from-your-editor) zeigt, wo ein Schlüssel in opencode, Claude Code und einem Shell-Skript hingehört.

# Branding
Source: https://docs.tale.dev/de/platform/admin/branding

Unter **Einstellungen > Branding** gibst du einer Organisation ihr eigenes Logo, Tab-Symbole und eine Akzentfarbe. Inhaber und Admins dürfen diese Einstellungen ändern. Sie gelten für die gerade geöffnete Organisation. Prüfe deshalb den Organisationsnamen, bevor du die gemeinsame Darstellung anpasst.

<Frame caption="Einstellungen > Branding — die Logo-, Favicon- und Farb-Steuerungen neben einer Live-Vorschau der Sidebar.">

![Die Branding-Einstellungsseite mit Logo- und Favicon-Uploads, einem Feld für die Akzentfarbe und einem Live-Vorschaubereich rechts.](https://docs.tale.dev/images/platform/settings-branding.webp)

</Frame>

## Die Bilder vorbereiten

| Einstellung | Vorbereitung |
| --- | --- |
| **Logo** | Ein Zeichen, das in der Seitenleiste klein lesbar bleibt und auf hellen wie dunklen Flächen funktioniert. SVG ist bevorzugt; Rasterbilder sollten mindestens 64 × 64 Pixel groß sein. |
| **Favicon** | Ein kleines, wiedererkennbares Tab-Symbol. Du kannst eine helle und eine dunkle Variante hinterlegen. |
| **Akzentfarbe** | Die Hex-Farbe deiner Marke und eine Sichtprüfung in beiden Designs. Tale leitet die angezeigte Palette für das aktuelle Design ab. |

Ohne Logo dient der Organisationsname als Textmarke. Diesen Namen änderst du unter **Einstellungen > Organisation**. Auf der Branding-Seite gibt es kein separates Feld für einen Anwendungsnamen.

## Logo oder Favicon hochladen

Wähle im jeweiligen Uploadfeld das Bild aus. Das Hochladen oder Entfernen eines Bildes wirkt sofort und wartet nicht auf Speichern. Nach erfolgreichem Abschluss werden Vorschau und Organisationsdarstellung aktualisiert.

Wenn kein eigenes Favicon hinterlegt ist, kann Tale eines aus dem hochgeladenen Logo ableiten. Verwende ein eigenes Symbol, wenn das vollständige Logo in Tab-Größe schwer zu erkennen ist. Prüfe nach dem Upload das Tab-Symbol und die Seitenleiste auch im anderen Design.

<Note>

Verwerfen im Seitenkopf setzt ausstehende Formularänderungen zurück. Ein bereits hochgeladenes oder entferntes Bild wird dadurch nicht wiederhergestellt.

</Note>

## Die Akzentfarbe ändern

Bearbeite **Akzentfarbe** und prüfe die Vorschau. Mit **Speichern** im Seitenkopf übernimmst du die Änderung; **Verwerfen** stellt den gespeicherten Wert wieder her. Das Farbfeld zeigt den Wert für das aktuelle Design. Eine abgeleitete Farbe im dunklen Design kann deshalb vom gespeicherten Wert für das helle Design abweichen. Die Vorschau zeigt die Farbe so, wie sie nach dem Speichern aussieht. Im dunklen Design kann sie deshalb vom Wert im Farbfeld abweichen. Das Speichern einer Änderung sowie das Hochladen oder Entfernen eines Bildes hinterlassen je einen Eintrag im Audit-Log unter **Einstellungen > Richtlinien > Protokolle**.

Schaltflächen behalten deine Farbe so genau, wie es die Lesbarkeit zulässt. Andere Markierungen in der Akzentfarbe verwenden deine Farbe nur, wenn sie auf der Seite als Text lesbar ist. Ist sie das nicht, nimmt Tale einen dunkleren Ton davon, im dunklen Design einen helleren. Zu diesen Markierungen gehören ein Link, eine Erwähnung, ein Quellenverweis, der ausgewählte Navigationseintrag, ein Punkt für Ungelesenes, der Fokusrahmen, ein eingeschalteter Schalter und ein Fortschrittsbalken. Eine mittlere Farbe kann deshalb auf einem Link oder Schalter etwas anders wirken als auf einer Schaltfläche.

Lade die Seite nach dem Speichern neu und prüfe einen ausgewählten Navigationseintrag, eine Schaltfläche und den Tastaturfokus. Eine Farbe, die als große Fläche gut aussieht, ist in einem kleinen Bedienelement nicht unbedingt gut erkennbar.

## Die Darstellung prüfen

Das Branding gilt innerhalb des jeweiligen Arbeitsbereichs. Beim Wechsel der Organisation wird deren Darstellung geladen. Anmeldeseiten erscheinen vor der Organisationsauswahl und verwenden das Standard-Branding der Plattform.

Zeigt der Browser noch ein altes Tab-Symbol, lade die Seite neu und prüfe die Favicon-Felder. Ein eigenes Favicon hat Vorrang vor der Ableitung aus dem Logo. Verwende **Zurücksetzen** nur, wenn du das konfigurierte Branding der Organisation entfernen möchtest, und lies vorher die Bestätigung. Die Bestätigung wirkt sofort: Die Bilder werden gelöscht und die geleerte Akzentfarbe wird gespeichert – ein weiteres **Speichern** ist nicht nötig, und es bleibt nichts ungespeichert.

# Neuigkeiten
Source: https://docs.tale.dev/de/platform/admin/changelog

Unter **Neuigkeiten** findest du Versionshinweise für die Tale-Plattform. Jedes angemeldete Mitglied kann sie lesen. Eine Administratorrolle ist nicht erforderlich.

## Versionshinweise öffnen

Öffne **Neuigkeiten** im Benutzermenü oder wähle **Anzeigen** in einer Update-Benachrichtigung. Damit bestätigst du das Update; die Markierung für ungelesene Neuigkeiten verschwindet. Die Seite zeigt die relevanten Versionen oder weist darauf hin, dass du auf dem aktuellen Stand bist.

Klappe einen Eintrag auf, um Version, Datum, Titel und Hinweise zu lesen. Prüfe besonders Änderungen an den Aufgaben deines Teams. Die verlinkten Produktleitfäden enthalten die jeweils aktuellen Anweisungen.

## Ältere oder fehlende Hinweise finden

Nutze den Link zu älteren Versionen auf GitHub, wenn die gesuchte Änderung außerhalb des angezeigten Bereichs liegt. Die Ansicht lädt öffentliche Versionsinformationen von GitHub und speichert sie zwischen. Ohne Netzwerkzugriff können noch nicht geladene Hinweise fehlen.

Für eine noch nicht veröffentlichte Version gibt es möglicherweise keinen passenden Eintrag. Prüfe die verlinkte Versionshistorie. Eine leere Ansicht beweist nicht, dass sich nichts geändert hat.

## Versionen und Organisationsaktivität unterscheiden

Versionshinweise beschreiben Änderungen an Tale selbst. Wer Organisationseinstellungen oder Inhalte geändert hat, untersuchst du dagegen in den [Audit-Protokollen](https://docs.tale.dev/de/platform/admin/governance/audit-logs).

Wenn du eine Bereitstellung betreibst, nutze den [Update-Leitfaden](https://docs.tale.dev/de/self-hosted/operate/upgrades) für das Vorgehen. Lies anschließend die Versionshinweise auf Änderungen durch, die dein Team kennen sollte.

# Connector-Zugangsdaten
Source: https://docs.tale.dev/de/platform/admin/connectors

Hinterlege Connector-Zugangsdaten, damit Tale Dienste wie Postfächer, Dateiablagen oder Aufgabenverwaltung verwenden kann. Inhaber, Admins und Entwickler verwalten sie unter **Einstellungen > Connectors**. Wähle den benötigten Dienst und das passende Konto. Der [Connector-Katalog](https://docs.tale.dev/de/platform/connectors/overview) erklärt die verfügbaren Aktionen.

## Ein Konto verbinden

1. Wähle **Zugangsdaten hinzufügen** und den Connector. Bereits konfigurierte Connectors stehen zuerst und können weitere Zugangsdaten erhalten.
2. Prüfe das Feld **Name**. Es enthält bereits den Namen des Connectors. Heißen andere Zugangsdaten dieses Connectors schon so, hängt Tale eine Zahl an: `GitHub`, dann `GitHub 2`. Ein Name wie `Support-Postfach` oder `EU-Shop` ist beim Erstellen von Automatisierungen leichter zu erkennen. Eine OAuth-Verbindung hat kein Namensfeld. Tale benennt sie nach derselben Regel, sobald du den Zugriff erteilt hast (ein zweiter Slack-Workspace erhält den Namen des Workspace), und mit **Zugangsdaten bearbeiten** kannst du sie umbenennen.
3. Fülle die angebotene Authentifizierungsmethode aus. Bei OAuth wählst du **Verbinden** und erteilst den Zugriff beim Anbieter. Jedes **Verbinden** legt neue Zugangsdaten für das freigegebene Konto an und ersetzt nie bestehende. Melde dich beim Anbieter deshalb mit dem Konto an, das du hinzufügen willst.
4. Schließe das Formular ab und prüfe den neuen Eintrag mit Connector, Konto oder Instanz und Status.

Slack verbindet pro Workspace genau einen Satz Zugangsdaten. Gibst du einen bereits verbundenen Workspace erneut frei, erneuert Tale dessen Zugangsdaten, statt weitere anzulegen.

Der Connector bestimmt die Felder. Verwende die tatsächlichen Zugangsdaten des Dienstkontos, keinen Tale-API-Schlüssel.

| Methode | Benötigte Angaben |
| --- | --- |
| API-Schlüssel | Der vom Dienst ausgegebene Schlüssel, etwa für Tavily oder Shopify. Jev decisions braucht einen OpenRouter-API-Schlüssel. |
| Token | Ein Dienst-Token, etwa ein persönlicher GitHub-Zugangstoken, ein Discord-Bot-Token oder ein GlitchTip-API-Token mit `project:read` und `event:read`. |
| Benutzername und Passwort | Das vom Dienst erwartete Paar, etwa Anmeldung und App-Passwort oder eine anbieterspezifische ID mit Token. |
| OAuth | Die Freigabe im Browser beim Anbieter. Tale speichert die zurückgegebene Berechtigung. |

Manche Connectors benötigen zusätzlich die Adresse der Instanz. Für Confluence ist das die Basisadresse der Atlassian-Site. Für GlitchTip ist das der Ursprung der Instanz, etwa `https://app.glitchtip.com`; eine selbst gehostete Instanz muss zusätzlich durch die Host-Richtlinie des Connectors erlaubt sein. Für Shopify verwendest du die `myshopify.com`-Adresse des Shops, nicht die öffentliche Shop-Domain.

## Einen Standard wählen

Die Tabelle zeigt eine Zeile je Zugangsdaten-Eintrag und aktualisiert sich ohne Neuladen, solange sie geöffnet ist: Was andere Admins hinzufügen, ändern oder löschen, siehst du sofort. **Standard** kennzeichnet den Eintrag für Aktionen ohne ausdrückliche Auswahl. Mit **Zum Standard machen** im Zeilenmenü änderst du ihn. Pro Connector ist ein Standard möglich.

Ein Connector mit mehreren Einträgen, aber ohne Standard funktioniert weiterhin für Aufrufer, die Zugangsdaten benennen. Ohne einen solchen Namen braucht der Aufruf einen Standard. Benenne Konten eindeutig, bevor du sie in Automatisierungen verwendest, damit später erkennbar bleibt, welches Konto gemeint ist.

Postfachsynchronisation und Eingangssichtung können alle aktiven Zugangsdaten eines Postfach-Connectors prüfen. Ein zweites Postfach muss dafür nicht zuerst Standard werden. Beim Verfassen einer neuen E-Mail listet das Feld **Postfach** jedes Postfach mit seinem Namen auf; die E-Mail wird über das gewählte Postfach versendet. Auch Antworten in dieser Konversation werden über dieses Postfach versendet, ebenso ein erneuter Versuch nach einem fehlgeschlagenen Versand.

## Ein Geheimnis rotieren oder Zugriff pausieren

Nutze die Ersetzen-Aktion der jeweiligen Methode, etwa **API-Schlüssel ersetzen** oder **Token ersetzen**. Der neue Wert ersetzt das gespeicherte Geheimnis. Name, Standardauswahl und Verweise bleiben erhalten. Prüfe anschließend eine passende Dienstaktion.

**Deaktivieren** pausiert den Eintrag und behält seine Konfiguration; **Aktivieren** stellt den Zugriff wieder her. Über **Zugangsdaten bearbeiten** änderst du andere unterstützte Angaben wie Namen oder Instanzadresse.

<Warning>

Das Löschen von Zugangsdaten entzieht abhängigen Automatisierungen und Agenten den Zugriff. Stelle die Aufrufer vorher um. Löschst du den Standard eines Connectors, wird sein ältester verbleibender aktiver Eintrag zum Standard; die Bestätigung nennt diesen Eintrag, bevor du löschst. Ein deaktivierter Eintrag oder einer, der neu verbunden werden muss, übernimmt nie. Bleibt kein aktiver Eintrag übrig, hat der Connector keinen Standard, bis du einen wählst. Ein gelöschter Eintrag lässt sich nicht durch erneutes Öffnen wiederherstellen.

</Warning>

## Eine OAuth-App vorbereiten

Unter **OAuth-Apps** am Seitenende konfigurieren Inhaber und Admins die Anbieter-Apps, über die Mitglieder den Zugriff freigeben. Eine organisationsspezifische App hat Vorrang vor der Bereitstellungs-App. Fehlen beide, kann der Connector keine Anmeldung starten. Die Seite zeigt den fehlenden Einrichtungsstand an.

Wähle **Einrichten**, gib Client-ID und Geheimnis des Anbieters ein und registriere dort exakt die im Dialog gezeigten Weiterleitungsadressen. Microsoft-Apps benötigen gegebenenfalls auch die Verzeichnis- oder Mandanten-ID. Bei späteren Änderungen lässt du ein gespeichertes Geheimnis leer, um es beizubehalten.

Die Google-Drive-App unterstützt auch den Wissensdatenbank-Import. Der OneDrive-/SharePoint-Eintrag dient diesem Import und keinem eigenen Connector. Die Slack-App richtet der Bereitstellungsbetreiber ein. Lies den jeweiligen [Connector-Leitfaden](https://docs.tale.dev/de/platform/connectors/overview), bevor du Anbieterrechte vergibst.

Bei OneDrive/SharePoint kann **Entra-ID-App aus SSO übernehmen** eine bestehende SSO-Registrierung in die Importkonfiguration kopieren. Das ist eine einmalige Kopie. Kopiere nach einer Rotation des SSO-Geheimnisses erneut und prüfe Weiterleitungsadresse sowie delegierte Rechte in der Bestätigung.

## Eine Verbindung reparieren

**Neu verbinden nötig** bedeutet, dass die gespeicherte OAuth-Berechtigung nicht mehr erneuert werden kann. Wähle im Menü dieser Zeile **Neu verbinden** und gib dasselbe Konto erneut frei. Tale erneuert genau diese Zugangsdaten: Name, Standard und Verweise bleiben erhalten, alle anderen Zugangsdaten bleiben unverändert. Bewusst deaktivierte Zugangsdaten aktiviert **Neu verbinden** nicht wieder; dafür gibt es **Aktivieren**.

Werden die Zugangsdaten entfernt, bevor die Freigabe abgeschlossen ist, oder erlaubt dir deine Rolle das Verwalten von Zugangsdaten nicht mehr, speichert Tale nichts und nennt den Grund. Gib bei Slack den Workspace frei, den die Zugangsdaten bereits verbinden. Einen anderen Workspace lehnt Tale ab; verbinde ihn stattdessen über **Zugangsdaten hinzufügen**.

Kann die Verbindung nicht starten, prüfe die OAuth-App. Lehnt der Anbieter die Rückkehr zu Tale ab, vergleiche die registrierte Weiterleitungsadresse mit der exakt in Tale gezeigten Adresse. Scheitert nach der Verbindung eine Aktion, prüfe die Kontorechte und den benötigten Berechtigungsumfang.

Für Dienste ohne mitgelieferten Connector siehe [MCP und eigene Integrationen](https://docs.tale.dev/de/platform/connectors/mcp-servers). Beliebige ausgehende MCP-Server werden nicht auf dieser Zugangsdaten-Seite registriert.

# Enterprise-SSO und Bereitstellung
Source: https://docs.tale.dev/de/platform/admin/enterprise-sso

Mit Enterprise-SSO melden sich Mitglieder über deinen Identitätsanbieter (IdP) an. Über SCIM kann er Mitglieder anlegen, aktualisieren und deaktivieren, ohne auf deren Anmeldung zu warten. Jede Organisation hat eine Verbindung. Als Admin oder Inhaber kannst du unter **Einstellungen > Enterprise-SSO** die Anmeldung, die Bereitstellung oder beides aktivieren.

## Bevor du beginnst

Du brauchst die Berechtigung, beim IdP eine Anwendung zu registrieren, deren Client-Zugangsdaten oder SAML-Metadaten sowie die öffentliche Tale-Adresse deiner Mitglieder. Lass während der Tests eine funktionierende Admin-Sitzung offen, damit du die Verbindung bei einem Anmeldefehler korrigieren kannst.

Trage unter **Anzeigename** einen Namen ein, den Mitglieder erkennen. Haben mehrere Organisationen der Installation SSO aktiviert, erscheint er in der Organisationsauswahl auf der öffentlichen Anmeldeseite. Verwende dafür keine vertraulichen oder rein internen Angaben.

<Frame caption="Wähle zuerst das Protokoll. Tale zeigt die passenden Felder und die Callback-Adresse für deinen Identitätsanbieter.">

![Enterprise-SSO-Einstellungen mit Microsoft Entra ID, Weiterleitungs-URL sowie Feldern für Issuer und Client-Zugangsdaten.](https://docs.tale.dev/images/platform/settings-enterprise-sso.webp)

</Frame>

## Das Protokoll wählen

| Protokoll | Wann es passt | Was du vorbereitest |
| --- | --- | --- |
| **Microsoft Entra ID** | Deine Organisation nutzt Entra; die optionale Team-Synchronisierung verwendet Microsoft Graph. | Tenant-spezifische Issuer-URL, Client-ID, Client-Secret. |
| **Generisches OIDC** | Dein Anbieter unterstützt OpenID-Connect-Discovery. | Issuer-URL, Client-ID, Client-Secret. |
| **OAuth2** | Dein Anbieter hat kein OIDC-Discovery-Dokument. | Client-Zugangsdaten und URLs für Autorisierung, Token und Userinfo. |
| **SAML 2.0** | Dein IdP verwendet SAML-Assertions. | IdP-Metadaten oder Entity-ID, Anmelde-URL und Signaturzertifikat. |

## Einen OIDC- oder OAuth2-Anbieter verbinden

1. Wähle das Protokoll in Tale und öffne den **Einrichtungsleitfaden**, um die Callback-URL zu finden.
2. Registriere beim IdP eine Webanwendung. Kopiere die Callback-URL exakt, einschließlich Schema, Host und Pfad. Registriere auch jede zusätzliche Callback-URL, die Tale für weitere Deployment-Domains anzeigt.
3. Trage Client-ID und Client-Secret in Tale ein. Bei OIDC gibst du die Issuer-URL an; Tale ermittelt die Endpunkte. Bei OAuth2 trägst du die drei Endpunkt-URLs selbst ein.
4. Prüfe **Scopes** und **Erweitert**. Fordere die Identitäts-Claims an, die deine Bereitstellungsregeln brauchen. Ordne abweichende Claim-Namen bei Bedarf zu. Claim-Pfade können Punkte enthalten, etwa `realm_access.roles`.
5. Wähle **Verbindung testen**, behebe mögliche Fehler und wähle oben **Speichern**. Teste danach eine echte Anmeldung wie unten beschrieben.

Verwende für Entra eine Tenant-spezifische Issuer-URL wie `https://login.microsoftonline.com/{tenant-id}/v2.0`, registriere den Callback als Web-Weiterleitungs-URI und kopiere den Wert des Client-Secrets statt seiner ID. Microsoft erklärt die Einrichtung in der [Anleitung zur App-Registrierung](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app). Die Gruppen-Team-Synchronisierung braucht die Microsoft-Graph-Berechtigung `GroupMember.Read.All` und Admin-Zustimmung. App-Rollen, die du in der App-Registrierung definierst und in der Unternehmensanwendung Benutzern oder Gruppen zuweist, stehen im Anmeldetoken. Eine **App-Rolle**-Regel passt daher auf den **Wert** (Value) der Rolle, etwa `Administrator`, und braucht keine Graph-Berechtigung.

Wähle für Google **Generisches OIDC** mit dem Issuer `https://accounts.google.com`; siehe Googles [OpenID-Connect-Einrichtung](https://developers.google.com/identity/openid-connect/openid-connect). Googles Standard-OIDC liefert keine Gruppenmitgliedschaften. Eine Google-Anmeldung allein ermöglicht deshalb keine Gruppen-Team-Synchronisierung.

<Note>
Der Microsoft-365-Dateiimport hat einen eigenen Zustimmungsablauf im Wissensbereich. Füge `Files.Read` oder `Sites.Read.All` nicht zu den SSO-Scopes hinzu, wenn Mitglieder sich nur anmelden sollen. Richte den Import über [OAuth-Apps für Konnektoren](/de/platform/admin/connectors) ein.
</Note>

## Einen SAML-Anbieter verbinden

1. Wähle **SAML 2.0**. Übernimm **SP-Metadaten-URL** und **ACS-URL (Antwort)** in die SAML-Anwendung deines IdP. Verwende die Service-Provider-Metadaten für Entity-ID/Audience und die E-Mail-Adresse als Name-ID-Format.
2. Importiere unter **IdP-Metadaten importieren** die Metadaten-URL des IdP oder wähle **XML hochladen**. Prüfe die übernommenen Werte für Entity-ID, Anmelde-URL und Signaturzertifikat. Du kannst sie auch manuell eintragen.
3. Ordne unter **Erweitert** E-Mail, Name und Gruppen zu, falls der IdP andere Attributnamen nutzt. Lass **Signierte Assertions verlangen** aktiviert.
4. Speichere die Verbindung und teste eine Anmeldung über den IdP.

Verschlüsselt dein IdP Assertions, ergänze unter **Erweitert** ein passendes **SP-Zertifikat (PEM)** und **Privater SP-Schlüssel (PEM)**. Das Zertifikat erscheint in den SP-Metadaten; der private Schlüssel wird als Secret gespeichert und nicht erneut angezeigt. Richte die Verschlüsselung im IdP ein, bevor du **Verschlüsselte Assertions verlangen** aktivierst. Tale akzeptiert diese Einstellung nur mit einem Entschlüsselungsschlüssel und weist danach unverschlüsselte Assertions ab.

SAML kann vom IdP oder von Tale aus gestartet werden. Wenn du in Tale beginnst, schließe die Anmeldung im selben Browser ab. So kann der Callback das zu Beginn angelegte Cookie prüfen.

## Rollen und Teams bei der Anmeldung zuweisen

| Einstellung | Was sie steuert |
| --- | --- |
| **Standardrolle** | Rolle für neu angelegte Mitglieder, wenn keine Rollenregel passt; anfangs Mitglied. |
| **Rollen automatisch vom IdP zuweisen** | Ordnet Gruppen, App-Rollen, Jobtitel oder Claims Tale-Rollen zu. Prüfe vor dem Aktivieren, wer eine Admin-Regel erfüllen könnte. |
| **IdP-Gruppen mit Teams synchronisieren** | Erstellt Teams oder fügt Mitglieder bei der Anmeldung anhand ihrer Gruppen hinzu. |
| **Gruppen ausschließen** | Kommagetrennte Gruppennamen, die die Team-Synchronisierung auslässt. |

Rollenregeln werden von oben nach unten geprüft, und die erste passende Regel bestimmt die Rolle. Passt jemand auf mehrere Regeln – etwa mit den App-Rollen `Administrator` und `Employee` –, gilt die Rolle der Regel, die weiter oben steht, und nicht automatisch die mit den meisten Rechten. Stell die Regeln mit den meisten Rechten deshalb nach oben: Zieh eine Regel an ihrem Griff oder nutze ihre Pfeile **Nach oben** und **Nach unten**, und speichere dann.

Verschwinden Gruppen, entfernt die Synchronisierung die zuvor von ihr vergebenen Mitgliedschaften. Von ihr erstellte Teams löscht sie, sobald diese leer sind. Manuell oder über SCIM angelegte Mitgliedschaften bleiben erhalten; ausgeschlossene Gruppen bleiben unberührt. Die manuelle Verwaltung beschreibt [Teams](https://docs.tale.dev/de/platform/admin/teams).

## Mitglieder über SCIM bereitstellen

1. Wähle unter **SCIM-Bereitstellung** die Aktion **Token generieren** und kopiere das Token sofort. Es wird nur einmal angezeigt.
2. Hinterlege das Token als Bearer-Zugangsdaten und die angezeigte **SCIM-Basis-URL** in der Bereitstellungskonfiguration deines IdP.
3. Stelle einen Testbenutzer und eine Testgruppe bereit. Prüfe, ob Mitglied und Team in Tale erscheinen, und teste Aktualisierung und Deaktivierung, bevor du weitere Personen einbeziehst.

SCIM-Users werden zu Mitgliedern, Groups zu Teams. Eine Deaktivierung (`active: false`) sperrt den Zugang des Mitglieds; die Reaktivierung stellt seine vorherige Rolle wieder her. Das Löschen eines SCIM-Users entfernt seine Organisationsmitgliedschaft, erhält aber sein Konto. Bei erneuter Bereitstellung gilt die Standardrolle der Verbindung.

Der Inhaber lässt sich über SCIM weder deaktivieren noch entfernen. Gruppen dürfen nur Mitglieder dieser Organisation enthalten. Eine Änderung des Benutzernamens wird abgelehnt, wenn die neue E-Mail-Adresse schon vergeben ist oder das Konto mehreren Organisationen angehört. So bleibt seine gemeinsame Anmeldeidentität geschützt.

## Mitglieder über einen Authentifizierungsproxy anmelden

Eine Anwendung, die ihre Nutzer bereits authentifiziert, kann sie über ihren Reverse-Proxy in diese Organisation weiterreichen, sodass Mitglieder das Anmeldeformular von Tale nie sehen. Die Karte **Vertrauenswürdige Header** auf derselben Seite enthält den Schalter, die Rollen-Obergrenze und die Schlüssel, die der Proxy vorlegt.

1. Schalte **Anmeldungen über einen vertrauenswürdigen Proxy annehmen** ein und wähle die **Höchste Rolle, die ein Proxy zuweisen darf**. Der Rollen-Header wird auf diese Rolle begrenzt; Inhaber lässt sich nie zuweisen. Bei jeder Anmeldung folgt der Sitz des Mitglieds der zugewiesenen Rolle; ein Inhaber-Sitz ändert sich nie.
2. Wähle **Schlüssel erstellen**, benenne ihn nach dem Proxy, der ihn erhält, und kopiere den Schlüssel sofort, denn er wird nur einmal angezeigt. Eine Organisation hält höchstens 10 gültige Schlüssel.
3. Richte den Proxy so ein, dass er Anmeldungen an die **Übergabe-URL** sendet, mit dem Schlüssel im Schlüssel-Header und den Identitäts-Headern unter **Header-Namen**. Ein Mitglied, das über den Proxy kommt, wird mit der ersten Anfrage der App angemeldet und sieht nie eine Anmeldeseite; die App bietet ihm keine Abmeldung an, da der Proxy diese Sitzung besitzt. Dass der Proxy `/log-in` auf dieselbe Adresse leitet, bleibt möglich.

Sollen die Seiten in der Seite der Anwendung selbst erscheinen, schalte unter **Einbettung** die Option **Einbettung in einem Frame erlauben** ein und trage die Herkunft der Seite unter **Erlaubte Herkünfte** ein; Tale lässt diese Herkunft dann als Frame-Vorfahren zu. Ein Frame trägt die angemeldete Sitzung nur, wenn die umgebende Seite zur selben Site wie Tale gehört.

Der Schlüssel bestimmt die Organisation: Ein Mitglied wird angemeldet, eine Adresse, die Tale noch nie gesehen hat, wird zum neuen Mitglied mit der zugewiesenen Rolle, und ein bestehendes Konto aus einer anderen Organisation wird abgewiesen. Schaltest du den Schalter aus, wird jeder Schlüssel abgewiesen, ohne dass einer widerrufen wird. **Widerrufen** stempelt einen Schlüssel, sodass der Proxy niemanden mehr anmelden kann; bereits gestartete Sitzungen bleiben angemeldet. Die [Authentifizierungskonfiguration](https://docs.tale.dev/de/self-hosted/configuration/authentication) des Betreibers beschreibt Header-Namen und Anforderungen an den Proxy.

## Prüfen und Fehler beheben

Öffne eine separate Browsersitzung und wähle **Weiter mit SSO**. Die Organisationsauswahl erscheint nur, wenn mehrere Organisationen der Installation SSO aktiviert haben; wähle dort die Organisation anhand ihres Anzeigenamens. Andernfalls öffnet die Schaltfläche direkt den Identitätsanbieter der einen aktivierten Organisation, und eine in das E-Mail-Feld eingetragene Adresse wird nur als Anmeldehinweis weitergegeben – Tale leitet nicht nach E-Mail-Domain weiter. Melde dich an und prüfe Rolle und Teammitgliedschaften. **Verbindung testen** prüft die Verbindungsdaten, aber nicht, ob eine echte Person die vorgesehenen Zugriffsrechte erhält.

| Symptom | Was du prüfst |
| --- | --- |
| Abweichende Weiterleitung, etwa `AADSTS50011` | Vergleiche den registrierten Callback exakt mit Tales URL: Domain, Schema, Pfad und abschließender Schrägstrich. |
| Verbindungstest schlägt fehl | Prüfe Issuer/Endpunkte, Client-ID, Wert und Ablaufdatum des Secrets sowie nötige Zustimmungen beim Anbieter. |
| Fehler bei der Browserbindung | Starte die Anmeldung im selben Browser neu und erlaube die bei Weiterleitungen benötigten Cookies. |
| Falsche Rolle oder fehlendes Team | Prüfe die tatsächlichen IdP-Claims, die Rollenregeln und ihre Reihenfolge, Ausschlüsse und Gruppenberechtigungen. Eine **App-Rolle**-Regel passt auf den Wert der App-Rolle, nicht auf ihren Anzeigenamen oder ihre ID. |
| SCIM kann sich nicht verbinden | Prüfe Basis-URL, Bearer-Token und ob die Bereitstellung aktiviert ist. |
| Die Proxy-Anmeldung wird abgelehnt | Prüfe, ob die Karte eingeschaltet ist, der Schlüssel nicht widerrufen wurde und der Proxy E-Mail-Header und Schlüssel bei der Übergabe-Anfrage sendet. |
| Fehlende Callback-URL oder Server-Konfigurationswarnung | Bitte den Betreiber, die [Authentifizierungskonfiguration](https://docs.tale.dev/de/self-hosted/configuration/authentication) zu prüfen. |

**Anmeldung deaktivieren** stoppt neue SSO-Anmeldungen; aktive Sitzungen bleiben bestehen. **Entfernen** löscht die Verbindungskonfiguration samt Zugangsdaten. Sorge vor beiden Aktionen für eine andere funktionierende Anmeldemethode.

# Audit-Logs
Source: https://docs.tale.dev/de/platform/admin/governance/audit-logs

Öffne als Admin oder Inhaber **Einstellungen > Richtlinien > Protokolle**, um protokollierte Aktionen deiner Organisation zu untersuchen. Suche zuerst das Ereignis und den Zeitpunkt. Prüfe danach Akteur, Ziel, Ergebnis und vorhandene Änderungsdetails.

## Eine Änderung finden

1. Wähle **Audit-Protokolle** und öffne **Filter**.
2. Wähle die passende Kategorie, etwa Mitgliedsänderungen, Sicherheit oder Daten.
3. Finde das Ereignis anhand von Zeitpunkt, Aktion und Ziel. Öffne die Zeile für die Details.
4. Prüfe den Status: Ein abgelehnter oder fehlgeschlagener Versuch belegt nicht, dass die Änderung erfolgreich war.

Aktiver Tab und Kategorie stehen in der URL. Du kannst die Ansicht deshalb als Lesezeichen speichern. Der Zugriff hängt weiterhin von deinen Organisationsberechtigungen ab.

<Frame caption="Richtlinien > Protokolle: der Tab Audit-Protokolle, eingegrenzt auf die Kategorie Mitglied. Alle löschen entfernt den Filter.">

![Die Seite Protokolle mit dem Tab Audit-Protokolle, gefiltert auf die Kategorie Mitglied: elf Ereignisse, in denen Alex Rivera Mitglieder hinzugefügt, drei Teams erstellt und jedem Team ein Mitglied zugeordnet hat, jede Zeile mit Ressource, Ziel, Kategorie und dem Status Success.](https://docs.tale.dev/images/platform/governance-audit-logs.webp)

</Frame>

## Ein Ereignis lesen

| Feld | Worauf du achtest |
| --- | --- |
| Zeitstempel | Wann Tale die Aktion protokolliert hat. |
| Aktion | Welcher Vorgang versucht oder abgeschlossen wurde. Manche neueren Aktionen erscheinen mit ihrem technischen Namen. |
| Benutzer | Welche Person oder welcher Systemakteur verantwortlich war. |
| Ressource und Ziel | Um welche Art von Eintrag und welchen konkreten Datensatz es geht. |
| Kategorie | Welche Gruppe der Filter verwendet. |
| Status | Erfolg, Fehler oder abgelehnt. |
| Detailansicht | Vorhandener vorheriger/neuer Zustand, geänderte Felder, Metadaten und Fehlerdetails. Nicht jedes Ereignis enthält alle Angaben. |

Nutze das Protokoll als Nachweis der darin erfassten Ereignisse. Es enthält keine vollständige Kopie aller Gespräche, Anbieterantworten oder Aktivitäten externer Dienste.

## Den richtigen Tab wählen

**Audit-Protokolle** enthält einzelne Ereignisse; die Tabelle lädt beim Scrollen weitere, und die Fußzeile nennt, wie viele Ereignisse bisher geladen sind – eine Zahl ist erst dann die gesamte Historie, wenn die Fußzeile das sagt. Die Ansicht für Anmeldesperren hilft bei blockierten Anmeldungen. Aktivitätslogs fassen Vorgänge und Ergebnisse über einen Zeitraum zusammen: Der im **Filter** gewählte Zeitraum (7, 30 oder 90 Tage) steht über den Summen, und jede Zahl auf dem Tab bezieht sich nur auf diesen Zeitraum. Fehlerlogs konzentrieren sich auf Fehler und lassen sich nach Kategorie eingrenzen.

Kann sich ein Mitglied nicht anmelden, beginne mit den Anmeldesperren und der [Anleitung zur Kontosicherheit](https://docs.tale.dev/de/platform/admin/two-factor-authentication). Wurde eine Konfiguration unerwartet geändert, prüfe das Audit-Ereignis und seine Details.

## Ergebnisse exportieren

Setze den Kategoriefilter, öffne **Exportieren** und wähle CSV oder JSON. CSV liefert flache Spalten für Tabellenprogramme, darunter UTC-Zeitstempel, Akteur- und Ressourcenkennungen, Status und Fehler. JSON enthält die ausführlicheren Ereignisobjekte samt vorhandenen Änderungsdaten und Integritätshashes.

Exporte berücksichtigen den Kategoriefilter und enthalten höchstens 10.000 Zeilen, beginnend mit den neuesten. Sie werden auf dem Server erzeugt und über einen vorübergehend gültigen Link heruntergeladen. Ein gefilterter oder begrenzter Export ist eine Auswahl von Nachweisen, nicht zwangsläufig die gesamte Historie oder eine vollständige Hash-Kette.

## Aufbewahrung und Integrität

Wähle im Bereich der Kettenintegrität **Jetzt prüfen**, um die gespeicherte Audit-Kette zu kontrollieren. Der Bereich zeigt den Status und die letzte automatische Prüfung. Wird eine Unterbrechung gemeldet, sichere die Details und untersuche sie mit dem Betreiber, bevor du dich auf diesen Teil der Historie verlässt.

Eine erfolgreiche Prüfung gilt für die aufbewahrten Datensätze, die sie untersucht hat. Sie belegt keinen unabhängig signierten Ursprung der Historie. Die [Integritätsanleitung für den Betrieb](https://docs.tale.dev/de/self-hosted/operate/security/audit-log-integrity) erklärt die Prüfungen und ihre Grenzen.

Die Hash-Verkettung hilft, Veränderungen gespeicherter Datensätze zu erkennen. Sie beweist nicht, dass jede mögliche Aktion protokolliert wurde. Die Audit-Aufbewahrung ist unter [Richtlinien und Limits](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits) einstellbar. Prüfe die aktive Richtlinie und Deployment-Grenzen, statt eine feste Dauer anzunehmen. Wiederherstellbare Audit-Einträge können im [Papierkorb](https://docs.tale.dev/de/platform/admin/governance/trash) erscheinen. Endgültige Bereinigung begrenzt die verfügbare Historie.

Die geplante Aufbewahrungsbereinigung hält hier jeden ihrer Läufe als Systemereignisse der Kategorie **Daten** fest: wann der Lauf begonnen hat, wie viele Datensätze er je Kategorie gelöscht hat und ob er abgeschlossen wurde oder fehlgeschlagen ist.

# Kompetenzen
Source: https://docs.tale.dev/de/platform/admin/governance/competences

Als Admin oder Inhaber führst du unter **Einstellungen > Richtlinien > Kompetenzen** das Kompetenzregister deiner Organisation. Eine Kompetenz ist eines von zwei Dingen:

- Eine **Plattform-Berechtigung** erlaubt einem Mitglied eine einzelne, eng begrenzte Aktion, für die sonst eine höhere Rolle nötig wäre. Weise sie dem Konto hinter einer Integration zu, statt es zum Admin zu machen. Als Admin könnte es auch Mitglieder, Single Sign-on und Passwörter verwalten.
- Eine **Qualifikation** ist ein Name, den die Freigaberichtlinie deiner Organisation von der Person verlangen kann, die eine Prüfung freigibt.

Eine Zuweisung gilt nur in dieser Organisation. Tale protokolliert jede Zuweisung und jeden Widerruf im Audit-Log, und wer aus der Organisation entfernt wird, verliert seine Zuweisungen.

## Plattform-Berechtigungen

| Berechtigung                                                     | Was sie erlaubt                                                                                                                                                                                      |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Benachrichtigungen exportieren** (`tale:notifications.export`) | Die Benachrichtigungen, die ein anderes Mitglied sieht, über die REST-API lesen, damit eine andere Anwendung sie spiegeln kann.                                                                      |
| **Für ein anderes Mitglied handeln** (`tale:rest.act-as`)        | Bei einem API-Aufruf das Mitglied nennen, für das eine Frage beantwortet oder eine Prüfung entschieden wird. Zeitleiste der Aufgabe und Audit-Log zeigen dann diese Person statt des API-Schlüssels. |
| **Skills für die Organisation veröffentlichen** (`tale:skills.publish`) | Einen Skill mit der ganzen Organisation teilen, auch wenn die [Richtlinie zur Skill-Freigabe](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits#skill-sharing) das Redakteuren oder Admins vorbehält. |
| **Modelle über die API aufrufen** (`tale:models.api`) | Die Modelle der Organisation mit einem persönlichen API-Schlüssel aus eigenen Tools aufrufen, über die [Modell-Endpunkte](https://docs.tale.dev/de/develop/use-tale-from-your-editor#model-endpoints), sobald die Organisation sie eingeschaltet hat. Öffnet außerdem **Einstellungen > API** mit den Tabs **REST** und **Modelle**, um den Schlüssel zu erstellen und die Einrichtung nachzulesen. |

Inhaber und Admins haben alle vier über ihre Rolle; Entwickler haben über ihre Rolle zusätzlich **Modelle über die API aufrufen**. Jedes andere Mitglied braucht die Zuweisung hier, zum Beispiel ein Entwickler-Konto, dessen API-Schlüssel eine Integration für einen Export verwendet. Ohne sie beantwortet die REST-API einen Export oder einen `actor` mit `403 ROLE_FORBIDDEN`, und die Modell-Endpunkte antworten mit `403 MODEL_API_FORBIDDEN`. Die [API-Referenz](https://docs.tale.dev/de/develop/api-reference#das-mitglied-benennen-fuer-das-gehandelt-wird) beschreibt die Anfragen mit Export und `actor`.

**Benachrichtigungen exportieren**, **Für ein anderes Mitglied handeln** und **Modelle über die API aufrufen** werden mit einem persönlichen API-Schlüssel genutzt; wer eine davon hat, kann deshalb auch unter **Einstellungen > API > REST** einen erstellen. Der Schlüssel handelt mit der eigenen Rolle; die Kompetenz fügt nur ihr eigenes Recht hinzu.

**Skills für die Organisation veröffentlichen** zählt nur, solange die Richtlinie zur Skill-Freigabe organisationsweite Skills vorbehält. Bei **Redakteure und höher** haben Redakteure und Entwickler dieses Recht schon über ihre Rolle. Ohne es kann ein Mitglied Skills nur mit seinen eigenen Teams teilen; Skill-Editor, Uploads und REST-API lehnen einen organisationsweiten Skill mit `403 SKILL_PUBLISH_FORBIDDEN` ab.

**Modelle über die API aufrufen** wirkt erst, wenn die Organisation die Modell-Endpunkte unter [Modelle](https://docs.tale.dev/de/platform/admin/governance/content-models#model-endpoints) eingeschaltet hat. Ein Mitglied mit dieser Kompetenz öffnet **Einstellungen > API** mit den Tabs **REST** und **Modelle**, um einen persönlichen Schlüssel zu erstellen und die Einrichtung zu kopieren; die Tabs **MCP** und **WebDAV** bleiben Inhabern, Admins und Entwicklern vorbehalten. Wird die Zuweisung widerrufen, lehnt Tale den nächsten Modellaufruf des Mitglieds ab.

## Eine Kompetenz zuweisen

1. Wähle **Kompetenz zuweisen**.
2. Wähle das **Mitglied**.
3. Wähle die **Kompetenz**: eine Plattform-Berechtigung oder **Qualifikation**. Gib bei einer Qualifikation unter **Name der Qualifikation** den Namen ein, den deine Freigaberichtlinie verwendet. Namen, die mit `tale:` beginnen, sind für Plattform-Berechtigungen reserviert.
4. Lege unter **Läuft ab** fest, wann sie endet: **Nie**, **In 30 Tagen**, **In 90 Tagen** oder **In 1 Jahr**.
5. Halte bei Bedarf unter **Nachweis** fest, warum das Mitglied sie hat, etwa ein Zertifikat, ein Ticket oder das System, dem sie dient. Der Nachweis bleibt im Register.
6. Wähle **Zuweisen**.

Die Zuweisung gilt ab der nächsten Anfrage des Mitglieds; eine Integration muss nicht neu starten. Ein Mitglied hat jede Kompetenz nur einmal gleichzeitig. Um Ablauf oder Nachweis zu ändern, widerrufe die Zuweisung und weise sie erneut zu. Hat das Mitglied die Kompetenz bereits, sagt der Dialog das und weist nichts zu.

## Eine Kompetenz widerrufen

Wähle in der Zeile **Widerrufen** und bestätige mit **Widerrufen**. Das Mitglied verliert die Kompetenz sofort. Die Zuweisung bleibt als Verlauf im Register, mit dem Status **Widerrufen** und dem Datum des Widerrufs. Zeige auf das Datum, um zu sehen, wer sie widerrufen hat.

## Das Register lesen

Die Liste zeigt zuerst die Zuweisungen mit dem Status **Aktiv**. Mit **Filter > Status** nimmst du **Abgelaufen** und **Widerrufen** hinzu, mit **Alle löschen** siehst du alle Zuweisungen.

| Status         | Bedeutung                                                                                                                                              |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Aktiv**      | Das Mitglied hat die Kompetenz. Die Zeile darunter zeigt das Ablaufdatum oder **Kein Ablauf**.                                                         |
| **Abgelaufen** | Das Ablaufdatum unter dem Status ist vorbei. Weise die Kompetenz erneut zu, wenn das Mitglied sie weiter braucht.                                      |
| **Widerrufen** | Ein Admin oder Inhaber hat sie widerrufen, oder nach ihrem Ablauf hat eine neue Zuweisung sie ersetzt. Unter dem Status steht das Datum des Widerrufs. |

Wer aus der Organisation entfernt wird, verliert jede aktive Zuweisung — Berechtigungen wie Qualifikationen –, sodass ein erneut hinzugefügtes Mitglied ohne sie startet. Eine widerrufene Zuweisung an jemanden, der die Organisation verlassen hat, zeigt **Ehemaliges Mitglied**. Das Register listet alle aktiven und abgelaufenen Zuweisungen sowie als Verlauf die 1000 zuletzt widerrufenen.

<Tip>

Eine Integration kann ihren eigenen Schlüssel mit `GET /api/v1/me` prüfen: `capabilities.actAs`, `capabilities.notificationExport`, `capabilities.skillPublish` und `capabilities.modelApi` sagen, ob der Schlüssel die jeweilige Berechtigung nutzen darf, über seine Rolle oder eine Zuweisung; `capabilities.modelApi` verlangt außerdem eingeschaltete Modell-Endpunkte.

</Tip>

# Modelle
Source: https://docs.tale.dev/de/platform/admin/governance/content-models

Als Admin oder Inhaber legst du unter **Einstellungen > Richtlinien > Modelle** fest, mit welchen Modellen Mitglieder starten und welche sie verwenden dürfen. Standardwerte lenken die Auswahl; Zugriffsregeln setzen Grenzen. Richte zuerst die [Anbieter-Zugangsdaten](https://docs.tale.dev/de/platform/admin/providers) ein, damit die gewünschten Modelle verfügbar sind.

## Ein Standardmodell festlegen

1. Wähle unter **Standardmodelle** die Aktion **Regel hinzufügen**.
2. Wähle den Standardbereich als Grundlage, eine Rolle oder ein Team. Gib bei Bedarf das Ziel an.
3. Wähle Anbieter und Modell, dann **Bestätigen**. Speichere die ausstehenden Seitenänderungen in der Kopfzeile.
4. Starte als Mitglied der Zielgruppe einen Chat mit der Modellauswahl **Auto** und prüfe das tatsächlich verwendete Modell.

Der Standard greift, wenn kein Modell ausdrücklich gewählt wurde. Eine Teamregel hat Vorrang vor einer Rollenregel, danach gilt der allgemeine Standard; gehört jemand mehreren Teams mit einer Regel an, gewinnt die erste passende Teamregel in der Tabelle (siehe [So werden Regeln kombiniert](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits#how-rules-combine)). Ein Standard verhindert nicht, dass jemand ein anderes erlaubtes Modell wählt.

## Den Modellzugriff begrenzen

Wähle unter **Modellzugriff** den Modus und ergänze Regeln für Personen, Teams, Rollen oder den Standardbereich.

| Modus | Wirkung einer passenden Regel |
| --- | --- |
| Allowlist | Nur aufgeführte erlaubte Modelle dürfen verwendet werden; ein gesperrtes Modell bleibt abgelehnt. |
| Blocklist | Modelle sind erlaubt, solange sie nicht als gesperrt aufgeführt sind. |

Zuerst gelten Personenregeln, danach Teamregeln, Rollenregeln und der Standard. Mehrere passende Teamregeln kombinieren ihre Listen. Eine ausdrückliche Sperre hat für das Modell weiterhin Vorrang. Passt keine Regel, schränkt die Richtlinie diese Person nicht ein. Lege eine Standardregel an, wenn du alle abdecken willst.

Bei Chats wird der Zugriff bei der Modellnutzung geprüft, auch bei ausdrücklich gewählten oder festgelegten Modellen. Ein Standardmodell muss die Prüfung ebenfalls bestehen. Wird es abgelehnt, kann die automatische Auswahl auf ein erlaubtes Modell ausweichen. Der Editor warnt bei widersprüchlichen Standard- und Zugriffsregeln. Löse den Widerspruch, damit der gewünschte Standard tatsächlich verwendet wird.

<Tip>
Prüfe nach einer Änderung beide Fälle: Ein erlaubtes Modell soll funktionieren, ein gesperrtes für das betroffene Mitglied abgelehnt werden. Ein Test nur als Admin belegt keine rollenspezifische Regel.
</Tip>

### API-Schlüsseln die Modelle der Organisation öffnen {#model-endpoints}

Mit **Modell-Endpunkte für API-Schlüssel** nutzen Personen die Modelle, die diese Richtlinie erlaubt, aus ihren eigenen Tools, etwa opencode, Claude Code oder Skripten mit den SDKs von OpenAI oder Anthropic, mit einem persönlichen API-Schlüssel über OpenAI- und Anthropic-kompatible Endpunkte. Standardmäßig ist das ausgeschaltet. Aktiviere den Schalter **Modell-Endpunkte für API-Schlüssel**; die Änderung wird sofort gespeichert.

- **Wer aufrufen darf.** Inhaber, Admins und Entwickler über ihre Rolle. Jedes andere Mitglied nur mit der Kompetenz **Modelle über die API aufrufen**, die du unter [Kompetenzen](https://docs.tale.dev/de/platform/admin/governance/competences) zuweist.
- **Welche Modelle.** Die Chatmodelle, die deine Anbieter-Zugangsdaten mit API-Schlüssel oder Umgebungsvariable bereitstellen, eingeschränkt durch die erlaubten Modelle der jeweiligen Zugangsdaten. Die Zugriffsregeln oben gelten für jeden Aufruf, und zwar für die Person, deren Schlüssel ihn gesendet hat. Der Schalter wirkt unabhängig von **Modellzugriffsrichtlinie aktivieren**: Ist diese Richtlinie aus, grenzen nur die erlaubten Modelle der Zugangsdaten die Liste ein.
- **Was jeder Aufruf durchläuft.** Die Budgets unter [Richtlinien und Limits](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits) und die Eingabe-Guardrails unter [Guardrails](https://docs.tale.dev/de/platform/admin/governance/guardrails#model-endpoints). Die Antworten der Modelle werden nicht gefiltert.
- **Wo er erscheint.** Jeder Aufruf wird unter der Person und dem Schlüssel verbucht, in der [Nutzungsanalyse](https://docs.tale.dev/de/platform/admin/governance/usage-analytics) als **Direkter API-Aufruf**.

<Frame caption="Richtlinien > Modelle — Modell-Endpunkte für API-Schlüssel, eingeschaltet.">

![Der Bereich Modell-Endpunkte für API-Schlüssel auf der Seite Modelle mit eingeschaltetem Schalter; er erklärt, dass Inhaber, Admins, Entwickler und Mitglieder mit der Kompetenz Modelle über die API aufrufen die Modelle der Organisation aus ihren eigenen Tools nutzen dürfen.](https://docs.tale.dev/images/platform/governance-model-endpoints.webp)

</Frame>

Schaltest du den Schalter aus, lehnt Tale den nächsten Aufruf mit `403 MODEL_API_DISABLED` ab. [Tale aus deinem Editor oder einem Skript nutzen](https://docs.tale.dev/de/develop/use-tale-from-your-editor#model-endpoints) zeigt Mitgliedern, wie sie ihre Tools verbinden.

## Das Modell zum Lesen von Bildern wählen

Ein reiner Textagent braucht Hilfe beim Lesen von Bildern, etwa Screenshots oder gescannten Seiten. Der Bereich für das Vision-Modell legt fest, welches Modell das Bild für den Agenten beschreibt. Kann das eigene Agentenmodell Bilder lesen, liest es sie selbst; das Vision-Modell bedient weiterhin die Bildwerkzeuge, die Skripte und Coding-Agenten in ihrer Sandbox aufrufen, etwa die Stapeltranskription gescannter Seiten. Jeder verwaltete Agent erhält deshalb eines, sobald ein erreichbares Modell existiert.

Lass die Bildlesemodellauswahl auf automatisch, um dem verfügbaren Anbieterkatalog zu folgen. Tale bevorzugt ein empfohlenes Vision-Modell und wählt sonst eine erreichbare günstige Option. Der Text unter der Auswahl nennt das aktuelle Modell und den Grund.

Lege ein Modell fest, wenn du eine stabile Auswahl brauchst. Die Auswahl bietet Modelle an, die Bilder lesen können. Ist das festgelegte Modell später nicht mehr verfügbar, stelle seinen Anbieterzugang wieder her oder wähle ausdrücklich **Automatisch** und speichere. Tale wechselt ein festgelegtes Modell nicht stillschweigend. Prüfe die aktuelle Wahl nach dem Austausch von Zugangsdaten oder Änderungen der Modellverfügbarkeit.

## Agenten Bilder erstellen lassen {#let-agents-generate-images}

Mit der **Bildgenerierung** können [Projektagenten](https://docs.tale.dev/de/platform/projects/project-agents) bei ihren Aufgaben und Agent-Knoten in [Automatisierungen](https://docs.tale.dev/de/platform/automations/concepts) Bilder erstellen, etwa ein Titelbild für einen Bericht oder ein Motiv für eine Kampagne. Die Funktion bleibt aus, bis du sie einschaltest. Im Chat entstehen nie Bilder: Wer eines braucht, weist eine Aufgabe einem Projektagenten zu.

1. Schalte **Agenten Bilder erstellen lassen** ein. Der Schalter speichert sofort.
2. Lass **Bildmodell** auf **Automatisch** oder wähle ein Modell und speichere die offenen Änderungen der Seite in der Kopfzeile.
3. Prüfe die Zeile unter der Auswahl. Sie nennt das Modell, mit dem Agenten Bilder erstellen.

<Frame caption="Richtlinien > Modelle — die Bildgenerierung ist eingeschaltet, mit einem fest gewählten Bildmodell.">

![Der Bereich Bildgenerierung mit eingeschaltetem Schalter, dem Bildmodell OpenRouter · google/gemini-2.5-flash-image in der Auswahl und der Zeile darunter, die das Modell nennt, mit dem Agenten gerade Bilder erstellen.](https://docs.tale.dev/images/platform/governance-image-generation.webp)

</Frame>

**Automatisch** nimmt das erste Modell einer kurzen Empfehlungsliste, das deine Anbieter-Zugangsdaten erreichen: Gemini 2.5 Flash Image, GPT Image 1 Mini, GPT Image 1 und danach FLUX.2 Pro. Dabei berücksichtigt Tale Zugangsdaten für OpenRouter und OpenAI. Die Auswahl listet jedes Bildmodell, das deine Zugangsdaten bedienen können, auch die anderer kompatibler Anbieter. Ein ausgewähltes Modell bleibt fest, bis du es änderst. Ist es nicht mehr verfügbar, meldet Tale das und wechselt nicht zu einem anderen Modell. Schaltest du die Bildgenerierung aus, bleibt das gewählte Modell für das nächste Einschalten erhalten.

Solange die Bildgenerierung eingeschaltet und ein Modell verfügbar ist, bekommt jeder Agent, der in einer Laufzeit mit MCP-Kanal von Tale zu arbeiten beginnt, ein Tool für Bilder. Agenten in anderen Laufzeiten und alle Agenten bei ausgeschalteter Bildgenerierung sehen dieses Tool gar nicht; welche Laufzeiten den Kanal haben, zeigt [Eine Agent-Laufzeit wählen](https://docs.tale.dev/de/platform/agents/harnesses). Schaltest du die Funktion aus, lehnt Tale auch die nächste Bildanfrage eines Agenten ab, der gerade läuft. Ein Agent legt seine Bilder bei seinen Dateien ab: Die Bilder einer Aufgabe erscheinen unter ihren Ergebnisdateien, die eines Automatisierungsschritts in dessen Ausgabe.

Bilder gibt es in drei Formen: quadratisch, im Querformat 3:2 und im Hochformat 2:3. Fragt ein Agent nach einer anderen Form, etwa einem Banner in 16:9, bekommt er die Form mit derselben Ausrichtung. Die genaue Größe in Pixeln bestimmt das Bildmodell, und das Tool für Bilder nennt dem Agenten die Größe jedes Bilds, das es gespeichert hat.

Jedes Bild wird deiner Organisation berechnet und zählt wie der übrige Lauf für die Person, die ihn gestartet hat. Ein Zug eines Agenten erstellt höchstens 16 Bilder, eine Anfrage nach der anderen, und seine Bilder zehren vom selben Rahmen wie die Modellnutzung des Zugs: Die Kosten jedes Bilds gehen von dem ab, was das Modell noch ausgeben darf, und ist der Rahmen aufgebraucht, lehnt Tale das nächste Bild ab. Ein Budgetlimit, das für diese Person gilt, lehnt das Bild ab, bevor das Bildmodell aufgerufen wird. Lege Kosten- oder Anfragelimits für Bilder unter [Richtlinien und Limits](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits) fest; [So wird Nutzung gezählt](https://docs.tale.dev/de/platform/admin/governance/usage-attribution) erklärt, für wen ein Bild zählt. Die Richtliniendatei und eigene Bild-Endpunkte beschreibt die [Anbieter-Referenz für Self-Hosting](https://docs.tale.dev/de/self-hosted/configuration/providers#configure-image-generation).

## Einen Standard-Agenten bereitstellen {#standard-agent}

Agenten zu einem Projekt hinzufügen können nur Redakteure und höhere Rollen. Damit auch ein Projekt ohne Agenten Arbeit an einen Agenten übergeben kann, bietet Tale dort den **Standard-Agenten** der Organisation an: Jeder, der das Projekt öffnen kann, kann ihm eine Aufgabe geben, auch Mitglieder. Er ist von Anfang an eingeschaltet.

<Frame caption="Richtlinien > Modelle — der Standard-Agent, eingeschaltet, mit automatisch gewählter Agent-Laufzeit und automatisch gewähltem Modell.">

![Der Abschnitt zum Standard-Agenten: Der Schalter ist eingeschaltet, Agent-Laufzeit und Modell stehen auf automatisch, das Feld für Anweisungen ist leer und verweist auf die eingebauten Anweisungen. Die letzte Zeile sagt, dass er für dich mit Claude Code und Claude Haiku 4.5 läuft.](https://docs.tale.dev/images/platform/governance-standard-agent.webp)

</Frame>

- **Wo er erscheint.** In einem Projekt ohne Agenten bietet **Zuständig** die Option **Standard-Agent** an, und [Aufgabe aus Chat erstellen](https://docs.tale.dev/de/platform/chat/basics#create-task-from-chat) trägt ihn für dich ein. Tale richtet ihn in einem Projekt ein, sobald jemand ihn dort wählt oder die Aufgabe eines Chats an dieses Projekt übergibt. Danach führt ihn der Tab **Agenten** des Projekts mit dem Abzeichen **Standard**; [Der Standard-Agent](https://docs.tale.dev/de/platform/projects/project-agents#standard-agent) erklärt, wie er sich dort verhält.
- **Womit er läuft.** Stehen **Agent-Laufzeit** und **Modell** auf **Automatisch**, wählt Tale ein empfohlenes Modell, das die Person, die die Aufgabe startet, nach deinen Regeln für den [Modellzugriff](https://docs.tale.dev/de/platform/admin/governance/content-models#den-modellzugriff-begrenzen) nutzen darf. Es läuft mit Claude Code oder mit der Agent-Laufzeit, an die ein Abo-Modell gebunden ist. Die Zeile am Ende des Abschnitts nennt, womit er für dich läuft. Wähle eine Agent-Laufzeit oder ein Modell, um sie für alle festzulegen, und speichere dann die offenen Änderungen der Seite in der Kopfzeile.
- **Was er weiß.** Seine eingebauten Anweisungen sagen ihm: Er tut, was die Aufgabe verlangt, mit ihren Dateien und Kommentaren. Ein verlangtes Dokument, eine Präsentation, eine Tabelle oder ein PDF liefert er als Ergebnis der Aufgabe. Er schreibt in der Sprache der Aufgabe und fragt in einem Kommentar nach, wenn die Aufgabe unklar ist. Text unter **Anweisungen** ersetzt diese Anweisungen.
- **Was er nutzen darf.** Die Dokument-Skills `docx`, `pptx`, `xlsx` und `pdf`, die dem Projekt zur Verfügung stehen, aber keine Connectors, Plattformoperationen oder Secrets, wie ein Redakteur sie anderen Agenten zuteilen kann.

Jeder Lauf startet mit den Einstellungen, die in diesem Moment gelten; ein laufender Agent behält die, mit denen er gestartet ist. Ein gewähltes Modell bleibt in Kraft, auch wenn es nicht mehr verfügbar ist, und ebenso eines, das der Modellzugriff einer Person nicht erlaubt: Der Standard-Agent startet dann für sie nicht und sagt, warum, und Tale wechselt nicht zu einem anderen Modell. Wähle ein anderes Modell oder **Automatisch** und speichere. Kann kein Modell, das eine Person nutzen darf, ihn ausführen, startet er für sie ebenfalls nicht: Füge unter [KI-Anbieter](https://docs.tale.dev/de/platform/admin/providers) einen Zugang hinzu oder prüfe ihren Modellzugriff.

Schalte **Standard-Agenten bereitstellen** aus, damit Tale ihn nicht mehr anbietet. Die Änderung speichert sofort und behält deine Auswahl. Projekte ohne Agenten bieten dann keinen Agenten an, und Aufgaben, die schon einem Standard-Agenten gehören, starten erst wieder, wenn du ihn einschaltest. Die Richtliniendatei beschreibt die [Anbieter-Referenz für Self-Hosting](https://docs.tale.dev/de/self-hosted/configuration/providers#configure-the-standard-agent).

## Das Modell für Audiotranskription auswählen

**Modell für Audiotranskription** steuert die serverseitige Transkription von Audio- und Videoanhängen, die Audiospur von Videolinks ohne nutzbare Untertitel sowie Diktate in Browsern ohne eigene Spracherkennung. Die Spracherkennung des Browsers nutzt ihren eigenen Dienst und hat Vorrang, wenn sie unterstützt wird.

<Frame caption="Die Audiotranskription hat eine eigene organisationsweite Auswahl: automatisch oder ein festgelegtes Modell.">

![Der Abschnitt für Audiotranskription zeigt die automatische Auswahl und nennt das aktuelle Modell für die serverseitige Transkription.](https://docs.tale.dev/images/platform/governance-content-models.webp)

</Frame>

Mit einem aktiven Standardzugang für OpenRouter stehen hier auch dessen Modelle zur Spracherkennung zur Auswahl. Tale findet sie im OpenRouter-Katalog. Prüfe, ob das gewünschte Transkriptionsmodell für den Zugang erlaubt ist. Nutze dann **Automatisch** oder wähle das Modell ausdrücklich aus.

1. Lass **Modell zur Audiotranskription** auf **Automatisch**, damit Tale ein verfügbares kompatibles Modell auswählt, oder wähle einen bestimmten Anbieter und ein Modell.
2. Speichere die ausstehenden Änderungen im Seitenkopf. Bis dahin ist die Auswahl ein Entwurf. Verwirf ihn, um die gespeicherte Einstellung beizubehalten.
3. Prüfe das aktuelle Modell unter der Auswahl. Teste eine kurze Aufnahme, bevor du mit dieser Einrichtung eine längere Datei hochlädst.

Ein Modellwechsel gilt für neue Transkriptionen; bereits verarbeitete Anhänge behalten ihr vorhandenes Transkript. Lädst du dieselben Bytes erneut hoch, wird die fertige Transkription für dasselbe Ziel wiederverwendet. Bei einem anderen Zielanbieter oder Zielmodell wird die Aufnahme erneut transkribiert.

Ein ausdrücklich ausgewähltes Modell bleibt festgelegt. Wird es nicht mehr verfügbar, zeigt Tale das an und wechselt nicht zu einem anderen Modell. Wähle ein anderes verfügbares Modell oder **Automatisch** und speichere. Ist kein kompatibles Modell verfügbar, richte unter [KI-Anbieter](https://docs.tale.dev/de/platform/admin/providers) einen aktiven Zugang ein und prüfe die dafür erlaubten Modelle. Kann Tale die Konfiguration vorübergehend nicht prüfen, versuche es erneut, statt deshalb ein anderes Modell auszuwählen.

Verhindert eine nicht verfügbare Servertranskription den Versuch, zu diktieren oder Audio oder Video anzuhängen, erklärt ein schließbarer Dialog das Problem. Je nach Zugriffsrechten erhalten Mitglieder einen Link zu den Einstellungen oder den Hinweis, einen Admin zu kontaktieren. Vorübergehend fehlgeschlagene Verfügbarkeitsprüfungen lassen sich wiederholen. Zur Auswahl über die Bereitstellungskonfiguration und zu eigenen Audioendpunkten siehe die [Anbieterreferenz für Self-Hosting](https://docs.tale.dev/de/self-hosted/configuration/providers#audiotranskription-konfigurieren).

## Eine unerwartete Auswahl erklären

Prüfe Rollen und Teams der Person, die ausdrückliche Chatauswahl, den passenden Standard, die Zugriffsregel und die Modellliste der Anbieter-Zugangsdaten. Ein Katalogeintrag beweist nicht, dass die Organisation nutzbare Zugangsdaten dafür besitzt. Kosten- und Tokenlimits gelten weiterhin über [Richtlinien und Limits](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits).

# Anfragen betroffener Personen
Source: https://docs.tale.dev/de/platform/admin/governance/data-subject-requests

Als Admin oder Inhaber bearbeitest du unter **Einstellungen > Richtlinien > Anfragen betroffener Personen** Löschanfragen. Tale verfolgt die Anfrage, ihre Freigabe und Wartezeit sowie das Ergebnis der Löschung. Prüfe vor der Einreichung Identität und passenden Umfang nach dem Verfahren deiner Organisation.

<Frame caption="Richtlinien > Anfragen betroffener Personen — die Richtlinie für Löschanfragen (Karenzzeit, Doppelfreigabe, Tageslimit) über der Liste der Anfrage-Belege mit Anfrage einreichen.">

![Die Einstellungsseite Anfragen betroffener Personen zeigt das Karenzzeit, den Schalter für die Vier-Augen-Freigabe und die Tageslimit-Felder über einer Tabelle der Löschungs-Anfragen mit einer offenen Anfrage — betroffene Person Jordan Blake, Begründungs-Code Einwilligung widerrufen, noch 24 Stunden bis zur Ausführung und 29 Tage SLA-Frist —, daneben die Schaltfläche Anfrage einreichen.](https://docs.tale.dev/images/platform/governance-data-subject-requests.webp)

</Frame>

## Eine Anfrage einreichen

1. Wähle **Anfrage einreichen** und suche die **Person** nach Name oder E-Mail. Prüfe, ob du das richtige Konto ausgewählt hast.
2. Wähle den **Rechtsgrund** und schreibe unter **Begründung**, worum es geht. Verweise auf deinen internen Fall.
3. Gib exakt `ERASE` ein und wähle **Anfrage einreichen**.
4. Öffne den Beleg und prüfe Status, Frist und die nächste erforderliche Aktion.

Die Löschung entfernt betroffene Daten endgültig; sie verschiebt sie nicht in den Papierkorb. Der Beleg erfasst Kategorien und Anzahlen, darunter Chats, Dokumente und Uploads, Einstellungen, Feedback, Benachrichtigungen, Nutzung und das Bereinigen von Personenkennungen im Audit-Protokoll. Die Löschung entfernt außerdem die getrennten Sandbox-Arbeitsbereiche der [Agentenläufe, die die Person gestartet hat](https://docs.tale.dev/de/platform/projects/tasks#agentenlaeufe-die-ein-mitglied-startet), auch wenn darin noch Arbeit läuft; der Beleg zählt sie unter **Sandbox-Arbeitsbereiche**. Ein Arbeitsbereich zählt erst, wenn der Sandbox-Dienst seine Dateien gelöscht hat, was bei einem großen eine Weile dauern kann. Bis dahin, oder solange das Löschen wiederholt fehlschlägt, lautet der Beleg **Teilweise** und nennt `sandboxWorkspaces` unter den fehlgeschlagenen Durchläufen; wähle später **Erneut versuchen**, und die Löschung wird abgeschlossen, sobald die Dateien entfernt sind. Unter Kubernetes zählt ein Arbeitsbereich, sobald sein Volume an den Storage-Provisioner des Clusters übergeben ist; mit einer StorageClass, deren `reclaimPolicy` `Retain` ist, bleiben die Dateien des Volumes, bis ein Operator das Volume entfernt, obwohl der Beleg den Arbeitsbereich zählt. Ein Sandbox-Dienst oder Gerät, das noch nicht auf diese Version aktualisiert ist, kann die Löschung nicht bestätigen; der Beleg bleibt dann **Teilweise**, bis es aktualisiert ist.

Aufgaben, die die Person als **Reviewer** nennen, verlieren diese Zuweisung. Eine Prüfanfrage, die noch auf sie wartet, geht an die erste berechtigte Person der Ersatzfolge: den Ersteller der Aufgabe oder des Projekts. Diese Person wird benachrichtigt. Bei einer archivierten Aufgabe geht die Prüfanfrage ohne Benachrichtigung weiter. Prüfentscheidungen, die die Person bereits getroffen hat, bleiben ohne ihren Namen erhalten.

## Vorher die Richtlinie prüfen

| Einstellung | Wirkung |
| --- | --- |
| **Karenzzeit (Stunden)** | Wartezeit von 0–72 Stunden vor der Ausführung. Admins können währenddessen abbrechen. Null erlaubt die sofortige Ausführung, sobald alle anderen Voraussetzungen erfüllt sind. |
| **Doppelfreigabe erforderlich** | Ein anderer Admin muss zustimmen, bevor die Karenzzeit beginnt. Die einreichende Person kann nicht selbst freigeben. |
| **Tägliches Limit pro Admin** | Begrenzt jeden Admin auf 1–50 Einreichungen pro Tag. |

Nur der Inhaber kann diese Richtlinie ändern. Strengere Schutzmaßnahmen gelten sofort. Lockerungen werden 24 Stunden vorgemerkt, damit jeder Admin sie abbrechen kann. Prüfe die wirksamen Einstellungen und Hinweise auf ausstehende Änderungen, bevor du mit einem neuen Wert planst.

## Den Beleg verfolgen

| Zustand | Nächster Schritt |
| --- | --- |
| Ausstehend / wartet auf Freigabe | Prüfe, ob ein zweiter Admin zustimmen oder die Karenzzeit enden muss. Brich ab oder lehne ab, wenn die Anfrage nicht ausgeführt werden soll. |
| Läuft | Warte auf die Kategorieergebnisse und reiche keine doppelte Anfrage ein. |
| Abgeschlossen | Prüfe die Anzahlen und bewahre den Beleg bei deinem Fall auf. |
| Teilweise | Untersuche übersprungene Kategorien und Fehler. Behebe die Ursache vor einem neuen Versuch. |
| Blockiert | Prüfe den [Legal Hold](https://docs.tale.dev/de/platform/admin/governance/legal-hold). Betroffene Daten bleiben geschützt. Der Beleg nennt den noch geltenden Legal Hold; nach dessen Aufhebung sagt er das, und die Löschung geht erst weiter, wenn du **Erneut versuchen** wählst. |
| Fehlgeschlagen | Lies die Fehlerdetails. Nutze **Erneut versuchen**, wenn verfügbar. Bei einem Watchdog-Timeout kann eine neue Anfrage nötig sein. |
| Abgebrochen | Dieser Beleg plant keine weitere Ausführung. Reiche bei Bedarf eine neue Anfrage ein. |

Ein offener Beleg kann eine zweite Anfrage für dieselbe Person verhindern. Arbeite mit diesem Beleg weiter. War die Anfrage schon bei der Einreichung blockiert, muss ein neuer Versuch erneut die aktuelle Freigabe- und Wartezeitregel erfüllen. Ein Beleg, der auf Freigabe wartet, behält die bei der Einreichung festgehaltene Freigabepflicht: Schaltest du das Vier-Augen-Prinzip später aus, gibt ihn das nicht frei.

## Die Frist verwalten

Die Liste zeigt die erfasste Frist und mögliche Überschreitungen. Nutze **Frist verlängern** für eine begründete Verlängerung, solange die Aktion verfügbar ist. Die Anwendung erlaubt eine Verlängerung vor Ablauf der ursprünglichen Frist und protokolliert Grund und Admin.

Die Frist unterstützt die Nachverfolgung. Deine Organisation bleibt für die Prüfung und die Kommunikation mit der Person verantwortlich. Ein abgeschlossener Tale-Beleg bestätigt für sich allein keine Löschung in unabhängigen externen Systemen oder Backups.

## Das Ergebnis prüfen

Öffne die Kategorieanzahlen, Fehler und Audit-Zeitleiste des Belegs. Eine abgeschlossene Aktion, eine gesperrte Kategorie und ein fehlgeschlagener Durchlauf haben unterschiedliche Ergebnisse. Halte diese Unterschiede im Fall fest. Zugehörige Admin-Ereignisse findest du in den [Audit-Logs](https://docs.tale.dev/de/platform/admin/governance/audit-logs).

# Feedback-Analyse
Source: https://docs.tale.dev/de/platform/admin/governance/feedback-analytics

Als Admin oder Inhaber prüfst du unter **Einstellungen > Metriken > Feedback** die Rückmeldungen aus dem Chat. Bewertungen zeigen, was Mitglieder hilfreich fanden. Ihre Kommentare erklären die Gründe.

## Das passende Feedback finden

Wähle einen Zeitraum und grenze danach nach Feedbacktyp, Assistent oder Modell ein. Verfügbar sind 1, 7, 30 und 90 Tage sowie der gesamte Zeitraum; die erste Ansicht zeigt 7 Tage. Wählst du einen Assistenten oder ein Modell in einer Aufschlüsselung, wird die Ansicht gefiltert. Entferne Filterchips, um sie wieder zu erweitern. Tale ordnet jede Bewertung anhand der bewerteten Antwort selbst zu: dem Modell und Anbieter, die geantwortet haben, und dem Assistenten, unter dem die Unterhaltung läuft. Gemeint ist der Assistent, unter dem die Unterhaltung zum Zeitpunkt der Bewertung läuft, nicht unbedingt der, der die Antwort geschrieben hat: Nach einem Assistentenwechsel zählt eine Bewertung einer früheren Antwort für den neuen Assistenten. Eine Antwort in einem einfachen Chat ohne Assistenten erscheint als **Nicht zugeordnet**.

Mit **Nur Kommentare** konzentrierst du dich auf schriftliche Erläuterungen. Prüfe bei einer leeren Ansicht zuerst Zeitraum und Filter. Feedback ist freiwillig: Eine unbewertete Antwort ist weder eine positive noch eine negative Stimme.

## Die Signale unterscheiden

| Signal | Was es aussagt |
| --- | --- |
| Daumen hoch/runter | Ob ein Mitglied eine bestimmte Antwort hilfreich fand. Ein optionaler Kommentar liefert Kontext. |
| Arena-Urteil | Welche Antwort in einem konkreten Paar bevorzugt wurde oder ob beide gleich gut beziehungsweise schlecht waren. Ein Urteil über zwei Kopien desselben Modells zählt unter **Gleiches Modell**, getrennt von den Urteilen und der Paarungstabelle. |

Mitglieder können Bewertungen ändern oder zurückziehen. Das Dashboard zeigt den aktuellen Stand, keine dauerhafte Zählung aller Klicks. Im [Arena-Modus](https://docs.tale.dev/de/platform/chat/arena-mode) erfährst du, wie Mitglieder zwei Antworten vergleichen.

## Ergebnisse fair vergleichen

Lies die Anzahl der Bewertungen zusammen mit dem Anteil hilfreicher Antworten. Eine einzelne positive Stimme sagt weniger aus als wiederholtes Feedback zu den tatsächlich bearbeiteten Aufgaben. Vergleiche ähnliche Zeiträume und Aufgaben, bevor du eine Veränderung einem Modell oder einer Assistentenkonfiguration zuschreibst.

Finde die Veränderung in den Tabellen nach Assistent und Modell, ihren Zeitpunkt im Verlauf und die Gründe in den aktuellen Feedback-Kommentaren. Vergleiche bei Arena-Ergebnissen dieselbe Modellpaarung. Ein Sieg gegen ein Modell belegt keinen Vorteil gegenüber allen anderen.

<Tip>
Ziehe die [Nutzungsanalyse](/de/platform/admin/governance/usage-analytics) hinzu. Ein Modell kann pro Anfrage günstiger sein und trotzdem mehr Versuche brauchen, bis eine brauchbare Antwort entsteht.
</Tip>

## Teilergebnisse verstehen

Große Zeitfenster können die Auswertungsgrenze von 50.000 Einträgen erreichen. Zeigt Tale einen Hinweis auf Teilergebnisse, verkürze den Zeitraum, bevor du Schlüsse ziehst. Auch Aufbewahrung und Löschung bestimmen, welche Bewertungen und Kommentare noch verfügbar sind. Diese Ansicht ist kein dauerhaftes Feedback-Archiv.

# Schutzregeln
Source: https://docs.tale.dev/de/platform/admin/governance/guardrails

Als Admin oder Inhaber steuerst du unter **Einstellungen > Richtlinien > Guardrails**, wie Chattexte vor und nach einem Modellaufruf geprüft werden. Aktivierte Schichten laufen in dieser Reihenfolge: Inhaltssicherheit, Erkennung personenbezogener Daten und externe Moderation. Beginne mit einer klaren Regel und prüfe ihre Wirkung, bevor du sie ausweitest.

<Frame caption="Richtlinien > Guardrails — die drei Status-Karten der Filterebenen (Inhaltssicherheit, PII-Erkennung, Moderationsanbieter) über dem Log der letzten Ereignisse.">

![Die Einstellungsseite Guardrails zeigt drei Status-Karten — Inhaltssicherheit an mit zwei Kategorien für Ein- und Ausgabe, PII-Erkennung an im Maskierungsmodus, Moderations-Anbieter nicht konfiguriert — über dem Feed der letzten Ereignisse, der noch keine meldet, und den benutzerdefinierten Anweisungen der Organisation.](https://docs.tale.dev/images/platform/governance-guardrails.webp)

</Frame>

## Eine Inhaltsregel hinzufügen

1. Lege im Bereich der Inhaltssicherheit fest, ob Benutzereingaben, Modellausgaben oder beide geprüft werden.
2. Wähle die Aktion zum Hinzufügen einer Kategorie, vergib eine erkennbare Bezeichnung und wähle den Modus.
3. Füge die zu erkennenden Wörter oder Ausdrücke einzeln pro Zeile hinzu. Du kannst eine Textliste importieren; prüfe sie vor dem Anwenden.
4. Speichere die Kategorie, aktiviere die gewünschte Kategorie und Schicht und speichere die ausstehenden Seitenänderungen.
5. Teste mit erfundenem Text, der einen Treffer enthält, und mit normalem Text, der passieren soll. Prüfe die aktuellen Ereignisse und das sichtbare Ergebnis im Chat.

| Modus | Was bei einem Treffer passiert |
| --- | --- |
| Markieren | Protokolliert den Treffer und lässt die Nachricht durch. Hilfreich beim Abstimmen einer Regel. |
| Maskieren | Ersetzt den Treffer durch den eingestellten Platzhalter. |
| Blockieren | Lehnt die Nachricht ab. |

Treffen mehrere Kategorien zu, hat Blockieren Vorrang vor Maskieren und Markieren. Die Wortsuche ignoriert Groß- und Kleinschreibung. Prüfe wichtige Sprachvarianten und Fehlalarme. Ein erfolgreicher Test belegt keine vollständige Abdeckung.

## Personenbezogene Daten schützen

Der PII-Schutz erkennt konfigurierte Muster wie E-Mail-Adressen, Telefonnummern und Kennungen. Wähle passende eingebaute Typen und eigene Muster, danach das gewünschte Verhalten.

Maskieren entfernt erkannte Werte aus dem weitergegebenen Text. Im Chat speichert und zeigt Tale auch den maskierten Text als Nachricht; der ursprüngliche Wortlaut bleibt nicht erhalten. Blockieren lehnt einen Treffer ab. Tokenisierung ersetzt die Werte für das Modell durch nummerierte Tokens und stellt sie in der Antwort wieder her. Sie kann die Verarbeitung mit weniger offengelegten Daten unterstützen, verspricht aber keine Antwort ohne personenbezogene Daten.

Eine eingebaute Kennung, die nur aus Ziffern besteht, etwa eine schwedische Passnummer oder eine ukrainische Steuernummer, wird nur neben einem Wort erkannt, das sie benennt, zum Beispiel `passnummer` oder `ІПН`. Bestellnummern, kompakte Datumsangaben und Build-Nummern bleiben unverändert. Jede Erkennung unter **Aktuelle Ereignisse** nennt das ausgelöste Muster, etwa `se-passport`.

Teste die tatsächlich verwendeten Formate mit erfundenen Werten. Muster können ungewöhnliche Formate übersehen oder normalen Text fälschlich markieren. Prüfe Eingabe und Ausgabe getrennt.

## Externe Moderation ergänzen

Die Moderationsschicht sendet Text an einen konfigurierten Klassifikator, etwa OpenAI, Azure, Perspective oder einen eigenen Endpunkt. Richte Zugangsdaten, Kategorien und Aktionen ein und wähle, welche Richtung geprüft werden soll.

Lege das Verhalten bei Nichterreichbarkeit fest: Fail-open lässt die Nachricht durch, Fail-closed lehnt sie ab. Prüfe Anbieterfehler und Ereignisse einer geöffneten Schutzschaltung bei unerwarteten Ablehnungen oder ungefilterten Nachrichten. Diese Schicht ergänzt einen weiteren Dienst, der den Text verarbeitet. Verwende den für deine Organisation freigegebenen Anbieter und Endpunkt.

## Organisationsanweisungen festlegen

Benutzerdefinierte Organisationsanweisungen werden vor den Anweisungen des Chat-Assistenten und vor den eigenen Anweisungen jedes Agenten eingefügt: bei Projekt-Agenten, die Aufgaben bearbeiten, und bei Agent-Knoten in Automatisierungen. Mitglieder können diese Organisationsrichtlinie nicht bearbeiten. Nutze sie für gemeinsames Verhalten und Begriffe. Für unabhängig durchzusetzende Einschränkungen verwendest du Zugriffsregeln und Filter, statt dich auf die Befolgung von Textanweisungen zu verlassen.

## Guardrails an den Modell-Endpunkten {#model-endpoints}

Schaltet deine Organisation die [Modell-Endpunkte für API-Schlüssel](https://docs.tale.dev/de/platform/admin/governance/content-models#model-endpoints) ein, prüft die Eingabeseite dieser Guardrails auch jede Anfrage an sie. Inhaltssicherheit, PII-Schutz und Moderationsanbieter lesen jeden Text der Anfrage, bevor Tale sie an das Modell weitergibt: System- und Entwickleranweisungen, die Turns der Person und des Assistenten, Tool-Aufrufe, Tool-Ergebnisse und Tool-Definitionen sowie Dokumente, die als Text mitkommen. Alle davon schreibt der Aufrufer, deshalb ist keiner vertrauenswürdiger als ein anderer:

- Blockieren lehnt die Anfrage mit `400 MODEL_API_GUARDRAIL_BLOCKED` ab, und beim Modell kommt nichts an.
- Maskieren ersetzt den Treffer, und das Modell erhält den maskierten Text.
- Tokenisierung lässt sich nicht umsetzen, weil Tale die Antwort des Modells unverändert weiterreicht und die Werte nicht darin wiederherstellen kann. Solange der PII-Schutz im Modus **Tokenisieren** aktiv ist, lehnt Tale jede Anfrage mit `403 MODEL_API_GUARDRAIL_UNSUPPORTED` ab; wähle **Maskieren** oder **Blockieren**, wenn Mitglieder die Modell-Endpunkte nutzen.
- Fällt ein Moderationsanbieter unter Fail-closed aus, lehnt Tale die Anfrage mit `503 MODEL_API_GUARDRAIL_UNAVAILABLE` ab, ebenso wenn Tale eine Guardrail-Einstellung nicht lesen kann.
- Solange eine Guardrail aktiv ist, lehnt Tale eine Anfrage mit mehr als 2 MB Text mit `413 MODEL_API_TEXT_TOO_LARGE` ab.

Die Ausgabe wird dort nicht gefiltert: Regeln für die **Modell-Ausgabe** greifen nicht, und die Antworten des Modells, gestreamt oder nicht, passieren ungeprüft, ebenso Bilder und Dokumente, die kein Text sind. Benutzerdefinierte Anweisungen fügt Tale ebenfalls nicht hinzu; das Modell erhält die Anfrage so, wie das Tool des Aufrufers sie gesendet hat. Erkennungen erscheinen wie Chat-Erkennungen unter **Aktuelle Ereignisse**, jeweils erfasst unter `model-api:` gefolgt von Tales eigener Kennung der Anfrage, daneben die `X-Request-Id`, die der Aufrufer erhalten hat. Da Tools bei jeder Anfrage das ganze Gespräch erneut senden, übernimmt Tale für einen Text, den es vor wenigen Minuten geprüft hat, das damalige Ergebnis und erfasst eine Erkennung nur einmal statt bei jedem erneuten Senden.

## Prüfen und abstimmen

Die aktuellen Ereignisse zeigen die letzten 50 Erkennungen, Blockierungen und Anbieterfehler. Filtere nach Schicht oder Ergebnis und prüfe Kategorie, Richtung und Zeitpunkt. Der erkannte Originaltext wird in diesen Ereignissen nicht gespeichert. Eine Zeile erklärt den Treffer, ohne seinen sensiblen Inhalt wiederzugeben.

Ist eine Regel zu weit gefasst, passe Kategorie oder Muster an und wiederhole die Tests. Fehlt ein Treffer, prüfe, ob Schicht, Kategorie und gewünschte Richtung aktiv sind. Wie lange Ereignisse erhalten bleiben, hängt von der Kategorie **Chat-Filter-Ereignisse** der [Aufbewahrungsrichtlinie](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits) ab. Standardmäßig ist sie aus, und Ereignisse bleiben erhalten, bis ein Admin sie aktiviert. Ist sie aktiv, löscht die geplante Bereinigung Ereignisse, die älter sind als ihr Zeitraum plus die Schonfrist für Löschungen, bis zu 50.000 pro Nacht; ein größerer Rückstand, etwa Ereignisse aus Monaten beim ersten Aktivieren, wird über mehrere Nächte abgebaut. Die letzten Ereignisse und die Guardrail-Zahlen unter **Einstellungen > Metriken > Chat-Zustand** zeigen nur die noch aufbewahrten Ereignisse: Sind Zeitraum und Schonfrist zusammen kürzer als 30 Tage, bleibt der ältere Teil einer 30-Tage-Ansicht leer.

Ein [Legal Hold](https://docs.tale.dev/de/platform/admin/governance/legal-hold) schützt Ereignisse vor der Bereinigung: Eine Organisationssperre bewahrt alle Ereignisse, eine Mitgliedssperre die Ereignisse aus den Chats dieses Mitglieds. Ein Ereignis, dessen Chat schon vor der Sperre endgültig gelöscht wurde, hat keinen Besitzer mehr, den die Sperre schützen könnte, und bleibt nicht erhalten.

# Legal Hold
Source: https://docs.tale.dev/de/platform/admin/governance/legal-hold

Ein Legal Hold bewahrt die betroffenen Daten, solange ein Fall offen ist. Admins und Inhaber verwalten diese Aufbewahrungssperren unter **Einstellungen > Richtlinien > Legal Hold**. Setze die Sperre, solange die Daten noch vorhanden sind: Bereits endgültig gelöschte Datensätze holt sie nicht zurück.

<Frame caption="Richtlinien > Legal Hold — die Tabelle der aktiven Holds mit der Aktion Legal Hold setzen über der Warteschlange mit Vier-Augen-Prüfung der Freigabeanträge.">

![Die Einstellungsseite Legal Hold zeigt einen aktiven Hold — Typ Benutzer auf marta.vogel, gesetzt von Alex Rivera zum Sachverhalt Northstar contract — neben der Schaltfläche Legal Hold setzen, darunter die Warteschlangen Ausstehende Genehmigung und Genehmigt, die beide Keine Freigabeanträge melden.](https://docs.tale.dev/images/platform/governance-legal-hold.webp)

</Frame>

## Eine Sperre setzen

1. Wähle **Legal Hold setzen**.
2. Wähle das Ziel: eine Person als Verwahrer oder die gesamte Organisation. Wähle für eine Person das richtige Mitglied aus.
3. Begründe die Sperre so, dass ein anderer Admin versteht, was erhalten bleiben muss. Verknüpfe sie bei Bedarf mit einem Fall.
4. Bestätige und prüfe Ziel und Begründung in der Liste aktiver Sperren.

Eine gesetzte Sperre gilt sofort. Betroffene Daten sind vor Aufbewahrungsbereinigung und Löschung geschützt. Löschversuche werden abgelehnt. Bestimme den passenden Umfang anhand des Beweissicherungsprozesses deiner Organisation.

## Sperren nach Fall ordnen

Mit **Fall anlegen** bündelst du zusammengehörige Sperren unter einem Namen und Aktenzeichen. Die Zahl verknüpfter Sperren hilft zu prüfen, ob die vorgesehenen Personen abgedeckt sind.

Wenn du einen Fall schließt, werden Freigabeanträge für seine Sperren gestellt. Die Sperren enden dadurch nicht sofort. Jeder Antrag braucht weiterhin die folgende Prüfung.

## Eine Sperre freigeben

1. Wähle bei der aktiven Sperre **Freigabe beantragen** und begründe, warum die Aufbewahrung nicht mehr nötig ist.
2. Ein anderer Admin prüft den Antrag und wählt **Genehmigen** oder **Ablehnen**. Die antragstellende Person kann ihre eigene Freigabe nicht genehmigen.
3. Prüfe nach der Genehmigung die angezeigte Wartezeit in den Freigabeanträgen. Bis sie endet, bleibt die Sperre wirksam.
4. Prüfe das abgeschlossene Ergebnis im Freigabeverlauf und die verbleibenden Sperren in der aktiven Liste.

Für das Setzen genügt ein Admin. Die Freigabe braucht das Vier-Augen-Prinzip und eine Wartezeit. Eine Genehmigung bedeutet deshalb noch keine abgeschlossene Freigabe.

## Blockierte Löschungen verstehen

Eine Sperre kann Löschanfragen für die Person, das Löschen betroffener Chats oder Dokumente und das Löschen eines Ordners mit gesperrten Dateien verhindern. Jede aktive Organisations- oder Mitgliedssperre verhindert außerdem das Löschen der gesamten Organisation.

Scheitert eine Löschung, prüfe die zuständige Sperre, statt die Aktion zu wiederholen. Die Freigabe einer Sperre hebt keine andere überlappende Sperre auf. Nach der Freigabe kann die geltende Aufbewahrungs- oder Löschverarbeitung fortfahren. Ein Löschbeleg, den die Sperre blockiert hat, läuft nicht von selbst weiter: Öffne ihn unter Anfragen betroffener Personen und wähle **Erneut versuchen**.

## Zugehörige Anfragen prüfen

Unter [Anfragen betroffener Personen](https://docs.tale.dev/de/platform/admin/governance/data-subject-requests) findest du durch Sperren blockierte Löschbelege. In den [Audit-Logs](https://docs.tale.dev/de/platform/admin/governance/audit-logs) untersuchst du protokollierte Sperraktionen. Die [Aufbewahrungsrichtlinie](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits) steuert die normale Bereinigung, sobald die Sperre nicht mehr greift.

# Betriebsmetriken
Source: https://docs.tale.dev/de/platform/admin/governance/operations-metrics

Neben [Nutzung](https://docs.tale.dev/de/platform/admin/governance/usage-analytics) und [Feedback](https://docs.tale.dev/de/platform/admin/governance/feedback-analytics) findest du als Admin oder Inhaber unter **Einstellungen > Metriken** vier weitere Übersichten. **Chat-Zustand** zeigt, ob Antworten des Assistenten fehlschlagen oder blockiert werden, **Harness-Runden**, ob Agenten ihre Arbeit in der Sandbox abschließen, **Automatisierungen**, wie Live-Läufe enden, und **Projekte**, wie sich die Aufgaben eines Projekts bewegen. Jede Übersicht berechnet ihre Werte für den gewählten Zeitraum aus den Einträgen, die Tale noch aufbewahrt.

<Frame caption="Einstellungen > Metriken > Chat-Zustand: Zähler und Quoten, das tägliche Ergebnisdiagramm und die Aufschlüsselung nach Agent und Modell.">

![Die Übersicht Chat-Zustand für die letzten sieben Tage meldet sieben Assistenten-Antworten mit 0 % Fehlerrate, 0 % Blockierquote und keinen Guardrail-Ereignissen, einen Balken mit sieben erfolgreichen Antworten am aktuellen Tag und eine Aufschlüsselung, die jede Antwort einfachen Chats zuordnet und sie auf zwei Modelle verteilt.](https://docs.tale.dev/images/platform/metrics-chat-health.webp)

</Frame>

## Den Chat-Zustand prüfen

Öffne **Chat-Zustand**, wenn Mitglieder fehlgeschlagene oder verweigerte Antworten melden. Wähle unter **Filter** 1, 7 oder 30 Tage; die Seite öffnet mit 7 Tagen.

Die Karten zählen die **Assistenten-Antworten** im Zeitraum. **Fehlerrate** ist der Anteil dieser Antworten, die mit einem Fehler endeten, **Blockierquote** der Anteil, den Tale verweigert hat, etwa weil eine Schutzregel die Nachricht blockiert hat. **Guardrail-Ereignisse** zählt die Erkennungen im Zeitraum und wie viele davon eine Nachricht blockiert haben.

**Antworten im Zeitverlauf** teilt die Antworten jedes Tages in **Erfolgreich**, **Fehler** und **Blockiert** auf. So siehst du, wann ein Problem begonnen hat. **Aufschlüsselung** zeigt den Anteil jedes Agenten und jedes Modells; eine Antwort in einem einfachen Chat ohne Agent zählt als **Nicht zugeordnet**.

Unter **Fehler** gruppiert **Nach Fehlertyp** die Fehlschläge, zum Beispiel **Ratenlimit**, **Modell nicht gefunden**, **Guthaben aufgebraucht** oder **Nutzungslimit erreicht**. **Letzte Fehler** listet die jüngsten mit Modell und Agent auf. Der Typ verrät, was du als Nächstes prüfst: die Zugangsdaten eines Anbieters oder sein Kontingent unter [KI-Anbieter](https://docs.tale.dev/de/platform/admin/providers), die Verfügbarkeit eines Modells unter [Modelle](https://docs.tale.dev/de/platform/admin/governance/content-models) oder eine Budgetregel unter [Richtlinien und Limits](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits).

**Guardrails** schlüsselt die Ereignisse nach Art und nach Filter auf und zeigt Erkennungen, Blockierungen und Filterfehler pro Tag. Diese Ereignisse stammen von den Filtern unter [Schutzregeln](https://docs.tale.dev/de/platform/admin/governance/guardrails) und umfassen nur, was die Aufbewahrung noch behält.

## Harness-Runden beobachten

Eine Harness-Runde ist ein Arbeitsschritt, den ein Harness wie Claude Code oder Codex in der Sandbox ausführt: ein [Projektagent](https://docs.tale.dev/de/platform/projects/project-agents), der an einer Aufgabe arbeitet, oder ein Agent-Schritt in einer Automatisierung. **Harness-Runden** zeigt, ob diese Runden zu Ende kommen. Wähle 7, 30 oder 90 Tage; die Seite öffnet mit 30 Tagen.

Die Karten zeigen **Runden gesamt**, die **Erfolgsquote**, die **Timeout-Quote**, die **Dauer p95**, innerhalb derer 95 % der Runden fertig wurden, und unter **Von Nutzer gestoppt** die Runden, die jemand angehalten hat. **Nach Harness** führt Runden, Erfolgsquote und Timeouts für jeden Harness auf. Steigt die Timeout-Quote, siehst du dort, von welchem Harness sie kommt. [Eine Agent-Laufzeit wählen](https://docs.tale.dev/de/platform/agents/harnesses) erklärt, wie jeder Harness arbeitet, und [Sandbox-Kapazität verwalten](https://docs.tale.dev/de/platform/admin/sandboxes), wo ihre Kapazität festgelegt wird.

## Automatisierungsläufe verfolgen

**Automatisierungen** zählt die Live-Läufe der Automatisierungen deiner Organisation. Testläufe erscheinen im Tab **Läufe** der jeweiligen Automatisierung, aber nicht hier. Wähle 7, 30 oder 90 Tage; die Seite öffnet mit 30 Tagen. Jede Karte vergleicht ihren Wert mit dem gleich langen Zeitraum davor.

**Erfolgsquote** ist der Anteil der abgeschlossenen Läufe, die erfolgreich waren: Fehlgeschlagene und gestoppte Läufe zählen dagegen, eingereihte, laufende und wartende Läufe zählen noch nicht. **Ø Dauer** mittelt über die abgeschlossenen Läufe, **Fehlgeschlagene Läufe** zählt die Fehlschläge. **Läufe im Zeitverlauf** zeigt die Zahl der Läufe pro Tag, **Status-Verteilung** das Ergebnis aller Läufe im Zeitraum und **Top-Automatisierungen** die zehn Automatisierungen mit den meisten Läufen, jeweils mit Erfolgsquote, durchschnittlicher Dauer, Fehlschlägen und letztem Lauf. Öffne den Tab **Läufe** einer fehlschlagenden Automatisierung, um die fehlgeschlagene Node zu finden; [Automatisierungsläufe prüfen und Fehler beheben](https://docs.tale.dev/de/platform/automations/execution-logs) führt dich durch.

## Den Fortschritt eines Projekts prüfen

**Projekte** zeigt jeweils ein Projekt: Wähle es unter **Projekt auswählen**. Hat die Organisation nur ein Projekt, ist es schon gewählt. Wähle 7, 30 oder 90 Tage; die Seite öffnet mit 30 Tagen.

| Kennzahl | Was sie misst |
| --- | --- |
| **Abgeschlossen** | Aufgaben, die im Zeitraum **Erledigt** erreicht haben, getrennt nach ihrer aktuellen Zuweisung: Aufgaben, die einem Agenten zugewiesen sind, und alle übrigen. |
| **Ø Durchlaufzeit** | Die durchschnittliche Zeit vom ersten Wechsel einer Aufgabe nach **In Bearbeitung** bis **Erledigt**. Eine Aufgabe, die **In Bearbeitung** übersprungen hat, hat keine Durchlaufzeit. |
| **Eingriffsquote** | In der Prüfung angeforderte Änderungen plus Eskalationen (Fragen, die Agent-Schritte in Automatisierungen an Menschen gerichtet haben), bezogen auf die im Zeitraum gestarteten Agentenläufe. |
| **Ausgaben** | Die Kosten der Agentenläufe des Projekts, mit der Zahl der gestarteten und der fehlgeschlagenen Läufe. |

Die Diagramme darunter zeigen die offenen Aufgaben nach Status am Ende jedes Tages, die täglich erstellten und abgeschlossenen Aufgaben, den Verlauf der Durchlaufzeit, die Abschlüsse jedes Tages, aufgeteilt in **Agenten** und **Menschen**, sowie die täglichen Ausgaben. Diese Aufteilung richtet sich wie die unter **Abgeschlossen** danach, wem eine Aufgabe jetzt zugewiesen ist, nicht danach, wer sie abgeschlossen hat. Eine Aufgabe, die einem Agenten zugewiesen ist, zählt für die Agenten, obwohl ein Mensch sie auf **Erledigt** gesetzt hat; eine Aufgabe, die einer Person, einer Automatisierung oder niemandem zugewiesen ist, zählt für die Menschen. Das gilt auch für vergangene Tage: Wird eine Aufgabe später einem Agenten zugewiesen oder verliert sie ihren Agenten, etwa weil er gelöscht wurde, wechselt ihr Abschluss auf die andere Seite. Eine Aufgabe, die direkt als **Erledigt** oder **Abgebrochen** erstellt wird, erhält den Abschlusszeitpunkt bei der Erstellung. Für den täglichen Abschlussdurchsatz zählen jedoch nur Statuswechsel-Ereignisse; die direkte Erstellung wird daher nicht als Abschluss-Ereignis gezählt.

Steigt die Eingriffsquote bei gleichbleibender Zahl von Läufen, schicken Menschen mehr Arbeit zurück oder stellen Agenten mehr Fragen. Eskalationen stammen von Agent-Schritten in Automatisierungen, die am Projekt arbeiten, und jede zählt an dem Tag, an dem sie entsteht, auch wenn niemand antwortet. Geht es um zurückgeschickte Arbeit, lies die Aufgaben in der Prüfung, bevor du die Anweisungen eines Agenten unter [Projektagenten](https://docs.tale.dev/de/platform/projects/project-agents) änderst; geht es um Fragen, lies die Läufe der Automatisierung, die sie gestellt hat, wie [Automatisierungsläufe prüfen und Fehler beheben](https://docs.tale.dev/de/platform/automations/execution-logs) es beschreibt.

## Die Werte richtig lesen

- Jede Übersicht rechnet mit den Einträgen, die Tale aufbewahrt. Aufbewahrungsregeln und Löschungen verkürzen den Verlauf: Ein leerer Zeitraum kann heißen, dass die Einträge fehlen, nicht dass nichts geschehen ist.
- Ein betriebsamer Zeitraum kann mehr enthalten, als ein Durchgang liest: Chat-Zustand, Harness-Runden, Automatisierungen und Projekte zählen jeweils höchstens die 5.000 jüngsten Einträge einer Art im Zeitraum. Zeigt Tale einen Hinweis auf aktuelle Aktivität, grenze den Zeitraum ein, bevor du Schlüsse ziehst.
- Kosten sind in der Anwendung erfasste Nutzung, keine Rechnung eines Anbieters; die [Nutzungsanalyse](https://docs.tale.dev/de/platform/admin/governance/usage-analytics) erklärt den Unterschied.

# Richtlinien und Limits
Source: https://docs.tale.dev/de/platform/admin/governance/policies-and-limits

Als Admin oder Inhaber steuerst du unter **Einstellungen > Richtlinien > Richtlinien & Limits** Ressourcenverbrauch und Datenverarbeitung. Wähle den Bereich für dein Anliegen: Ausgaben, Uploads, Aufbewahrung, Funktionsverfügbarkeit, den Hinweis im Chat, das Teilen von Skills mit der ganzen Organisation oder die Zuständigkeit für eingehende Konversationen.

<Frame caption="Richtlinien > Richtlinien & Limits — die Tabelle der Budget-Regeln über der Upload-Richtlinie und den Aufbewahrungs-Kontrollen.">

![Die Einstellungsseite Richtlinien und Limits zeigt drei monatliche Budget-Regeln — eine für die gesamte Organisation, eine als Standard für alle Benutzer und eine für die Rolle Entwickler, jede mit Obergrenzen für Tokens, Kosten und Anfragen — über den Feldern der Upload-Richtlinie für erlaubte Dateitypen, Größen und Volumen.](https://docs.tale.dev/images/platform/governance-policies-limits.webp)

</Frame>

## Ein Ausgabenbudget hinzufügen

1. Wähle unter **Budgetregeln** die Aktion **Regel hinzufügen**.
2. Wähle Bereich und Ziel. Nutze eine Rolle für eine Gruppe wie Redakteure, ein Team für gemeinsame Arbeit, eine Person für ein individuelles Limit, einen API-Schlüssel für einzelne Zugangsdaten oder die Organisation für eine gemeinsame Obergrenze. Die Liste der API-Schlüssel enthält jeden aktiven Schlüssel eines Mitglieds der Organisation mit dem Namen seiner Inhaberin oder seines Inhabers. So begrenzt du das Skript oder Coding-Tool einer einzelnen Person.
3. Wähle einen täglichen, wöchentlichen oder monatlichen Zeitraum. Setze mindestens ein positives Token-, Kosten- oder Anfragelimit. Kosten gibst du in USD an; ein leeres Feld begrenzt diese Größe durch die Regel nicht.
4. Setze bei Bedarf **Warnschwelle (%)** zwischen 0 und 100, um vor Erreichen des Limits zu warnen.
5. Wähle **Bestätigen**, speichere die ausstehenden Seitenänderungen und prüfe Bereich, Ziel, Zeitraum und Limits der gespeicherten Regel.

Eine monatliche Rollenregel könnte Redakteuren beispielsweise ein persönliches Ausgabenlimit von 50 USD geben, während eine Organisationsregel die gemeinsamen Ausgaben auf 500 USD begrenzt. Das sind Beispielbeträge, keine empfohlenen Standardwerte.

Eine Regel bleibt in der Tabelle, auch wenn ihr API-Schlüssel nicht mehr funktioniert. **Ziel** nennt weiterhin den Schlüssel und seine Inhaberin oder seinen Inhaber. Der Status lautet **Abgelaufen**, solange der abgelaufene Schlüssel noch gespeichert ist, **Deaktiviert**, **Widerrufen**, wenn diese Organisation den Widerruf protokolliert hat, oder **Ehemaliges Mitglied**, wenn die Person die Organisation verlassen hat. **Nicht verfügbar** bedeutet, dass der Schlüssel bekannt ist, aber ohne protokollierten Grund nicht mehr gespeichert ist; das kann nach der Bereinigung abgelaufener Schlüssel passieren. **Unbekannter Schlüssel** kennzeichnet einen Schlüssel, zu dem diese Organisation keine Angaben hat. Entferne eine solche Regel, oder bearbeite sie und wähle einen aktiven Schlüssel.

Budgets gelten für neue kostenpflichtige Arbeit, einschließlich Chat, Sprachausgabe, verwalteter Agentenläufe, der Bilder, die Agenten erstellen, und der Aufrufe der Modell-Endpunkte. Tale prüft jede Chat-Anfrage, bevor sie läuft — eine gesendete Nachricht, eine neu erzeugte oder bearbeitete Antwort, beide Seiten eines Modellvergleichs, eine Nachricht, die auf einen Anhang wartet, und ein Senden über die REST-API — und lehnt sie ab, sobald eine zutreffende Grenze erreicht ist. Die Ablehnung nennt die Grenze und wann sie zurückgesetzt wird. Antworten, die noch geschrieben werden, halten fest, was sie verbrauchen können, damit gleichzeitig gesendete Anfragen eine fast erreichte Grenze nicht gemeinsam überschreiten. Die Bildanfrage eines Agenten wird ebenso geprüft, bevor das Bildmodell aufgerufen wird: Solange ihre Bilder entstehen, hält sie geschätzte Kosten fest, und die Prüfung zählt auch mit, was der eigene Lauf des Agenten noch für sein Modell ausgeben kann. Jedes Bild zählt als eine Anfrage. Die Bildgenerierung braucht Kosten- oder Anfragelimits, weil ihre Nutzung nicht in Text-Tokens gemessen wird. Ein Tokenlimit zählt Eingabe- und Ausgabetokens, und zur Eingabe gehört auch der Teil eines Prompts, den ein Anbieter aus seinem Cache gelesen oder dort abgelegt hat. Dieser Teil wird anders berechnet als die übrige Eingabe, deshalb kann ein Agent, der einen langen Prompt wiederverwendet, ein Tokenlimit erreichen, während seine Kosten niedrig bleiben. Untersuche Warnungen in der [Nutzungsanalyse](https://docs.tale.dev/de/platform/admin/governance/usage-analytics).

## Verstehen, welche Grenzen gelten

Persönliche Limits werden für jede Größe aus der spezifischsten Regel ermittelt, die sie festlegt: zuerst Person, dann Team, Rolle und Standard. Gehört jemand mehreren Teams mit einer Regel an, gilt für die Person die strengste dieser Grenzen. Organisationslimits gelten zusätzlich. Ein Teambudget begrenzt auch die gemeinsame Nutzung der aktuellen Teammitglieder, selbst wenn ein Mitglied eine spezifischere persönliche Regel hat: Die Nutzung eines neuen Mitglieds im laufenden Zeitraum zählt sofort, die eines ausgetretenen Mitglieds nicht mehr. API-Schlüssellimits begrenzen unabhängig die mit diesem Schlüssel authentifizierten Anfragen, deren Nutzung dem Schlüssel angerechnet wird, nicht andere Arbeit in der Oberfläche.

Verwaltete Agentenläufe zählen für die Person, die sie gestartet hat. Ein Lauf, den du aus einer Aufgabe, einem Kommentar, über die REST-API oder den MCP-Endpoint startest, verbraucht deine persönlichen und Team-Grenzen; ein mit einem API-Schlüssel gestarteter Lauf zählt zusätzlich für diesen Schlüssel. Läufe, die ein Zeitplan, ein Webhook oder ein Ereignis gestartet hat, haben keine Person dahinter: Für sie gelten nur die Organisationslimits, und die [Nutzungsanalyse](https://docs.tale.dev/de/platform/admin/governance/usage-analytics) führt sie unter **Automatisierungen (Trigger)**. [So wird die Nutzung gezählt](https://docs.tale.dev/de/platform/admin/governance/usage-attribution) erklärt die Regel für jede Art von Arbeit.

Ein Aufruf der [Modell-Endpunkte](https://docs.tale.dev/de/develop/use-tale-from-your-editor#model-endpoints) wird wie eine Chat-Anfrage geprüft. Bevor er läuft, ermittelt Tale den ungünstigsten Fall, den geschätzten Prompt plus die höchstmögliche Ausgabe zum Katalogpreis des Modells, und lehnt ihn mit `429 BUDGET_EXCEEDED` ab, wenn dieser Fall nicht in das passt, was unter einer Grenze für den Schlüsselinhaber oder den Schlüssel noch übrig ist. Solange der Aufruf läuft, ist dieser Fall gegen diese Grenzen reserviert. Danach werden die vom Modell-Gateway gemessenen Kosten unter der Person und dem Schlüssel verbucht, und jeder Aufruf zählt als eine Anfrage.

Wird eine Anfrage unerwartet abgelehnt, prüfe alle passenden Grenzen und Zeiträume. Ein höheres persönliches Limit hebt keine Organisations-, Team- oder API-Schlüsselgrenze auf.

Mitglieder sehen ihren eigenen Stand unter [Einstellungen > Nutzung](https://docs.tale.dev/de/platform/member/preferences#usage-limits). Dort steht jede persönliche, Team- und Organisationsgrenze, die für sie gilt, mit aktueller Nutzung und nächstem Zurücksetzen. Die Regeln selbst sehen sie dort nicht.

### So werden Regeln kombiniert {#how-rules-combine}

Jede Richtlinie auf dieser Seite und unter [Inhalte & Modelle](https://docs.tale.dev/de/platform/admin/governance/content-models) liest ihre Regeln auf dieselbe Weise. Der spezifischste Bereich gewinnt: eine Personenregel vor einer Teamregel, eine Teamregel vor einer Rollenregel, eine Rollenregel vor dem Standard. Gehört eine Person mehreren Teams mit einer Regel an, werden die Teamregeln nach ihrer Art kombiniert:

- Eine Grenze, etwa ein Budget oder eine Obergrenze für das Kontextfenster, ergibt den strengsten Wert. Der Beitritt zu einem großzügigen Team hebt niemandes Grenze an.
- Eine Erlaubnisliste, etwa der Modellzugriff, ergibt die Vereinigung der erlaubten Modelle; eine Sperre in einer der Regeln gilt für dieses Modell weiterhin.
- Eine einzelne Auswahl, etwa das Standardmodell, folgt der Reihenfolge der Regeln in der Tabelle: Die erste passende Teamregel gewinnt.

## Uploads steuern

Die Uploadrichtlinie legt erlaubte und gesperrte Dateiendungen, erlaubte MIME-Typen, die maximale Dateigröße in MB und das Gesamtvolumen pro Person in GB fest. Wähle die benötigten Typen und teste nach dem Speichern eine erlaubte und eine abgelehnte Datei.

Dateiendung, Inhaltstyp und Größe sind getrennte Prüfungen. Vergleiche bei einem Fehler alle drei mit der Richtlinie. Prüfe den schon belegten Speicher der Person, wenn einzelne Dateien passen, weitere Uploads aber scheitern.

## Aufbewahrung und Wiederherstellung festlegen

Wähle im Bereich der Aufbewahrungsrichtlinie **Bearbeiten** und richte die benötigten Kategorien ein. Die Übersicht zeigt wirksame Werte, deaktivierte Kategorien und die Bereinigung temporärer Dateien. Eine deaktivierte geplante Aufbewahrung verhindert keine ausdrückliche Löschung oder Löschanfrage.

Prüfe vor einer Änderung die Mindest- und Höchstgrenzen des Deployments. Änderungen mit Prüfung oder Wartezeit erscheinen als Vorschläge oder vorgemerkte Änderungen. Lies ihren Wirksamkeitszeitpunkt, statt von einer sofortigen Anwendung auszugehen.

Die Schonfrist für Löschungen ist das Wiederherstellungsfenster unterstützter vorläufig gelöschter Datensätze. Ein positiver Wert lässt Zeit für die Wiederherstellung im [Papierkorb](https://docs.tale.dev/de/platform/admin/governance/trash); null erlaubt die sofortige endgültige Bereinigung. Nicht jede Kategorie lässt sich wiederherstellen. Ein [Legal Hold](https://docs.tale.dev/de/platform/admin/governance/legal-hold) schützt betroffene Daten vor Bereinigung.

Für selbst gehostete Deployments beschreibt die [Aufbewahrungskonfiguration](https://docs.tale.dev/de/self-hosted/configuration/retention) Betreiberkontrollen und Unterschiede zwischen Kategorien. Leite aus einer deaktivierten Richtlinie oder einem angezeigten Zeitraum allein keine Archivgarantie ab.

## Funktionskontrollen prüfen

Funktionskontrollen umfassen bereichsspezifische Kontextlimits und den organisationsweiten Schalter für Sprachausgabe. Ein Kontextlimit bestimmt, wie viel Kontext eine KI-Antwort erreicht. Es ist etwas anderes als ein Ausgabenbudget. Ein Limit unter 200.000 Token gilt auch für Agentenläufe mit Claude Code, und zwar das Limit der Person, die den Lauf gestartet hat: Der Agent fasst seine Konversation zusammen, bevor sie über das Limit hinauswächst. Ein Limit unter 100.000 Token behandelt Claude Code wie 100.000. Ist die Sprachausgabe ausgeschaltet, können Mitglieder sie weder über eigene Standardwerte noch einzelne Konversationen aktivieren.

Der Standardschalter für benutzerdefinierte Anweisungen legt die Organisationsvorgabe für die persönlichen Anweisungen der Mitglieder fest: Solange er aktiv ist, gelten die benutzerdefinierten Anweisungen jedes Mitglieds für seine Chatantworten, es sei denn, das Mitglied hat die Funktion unter **Einstellungen > Personalisierung** selbst ausgeschaltet. Verbindliche Organisationsanweisungen stehen separat unter [Guardrails](https://docs.tale.dev/de/platform/admin/governance/guardrails).

## Einen Vertraulichkeitshinweis im Chat anzeigen

**Vertraulichkeitshinweis** blendet für alle Mitglieder deiner Organisation eine kurze Zeile unter dem Nachrichtenfeld im Chat ein, etwa die Erinnerung, keine sensiblen Daten zu teilen. Der Hinweis bleibt aus, bis du ihn einschaltest.

1. Schalte **Vertraulichkeitshinweis** ein. Mitglieder sehen den Hinweis sofort im Chat, in ihrer Sprache; geöffnete Chats aktualisieren sich ohne Neuladen.
2. Gib bei Bedarf in den Sprach-Tabs **English**, **Deutsch** und **Français** eigene Texte mit jeweils höchstens 280 Zeichen ein. Speichere danach die ausstehenden Seitenänderungen.

<Frame caption="Richtlinien > Richtlinien & Limits — der Vertraulichkeitshinweis ist eingeschaltet, mit englischem Text, deutscher Übersetzung und noch nicht übersetztem Französisch.">

![Der Bereich Vertraulichkeitshinweis mit eingeschaltetem Schalter und gewähltem Tab English: Der Hinweis fordert dazu auf, keine Kundennamen, Vertragswerte oder Codenamen unveröffentlichter Projekte in den Chat einzufügen; der Tab Français ist als nicht übersetzt markiert.](https://docs.tale.dev/images/platform/governance-confidentiality-notice.webp)

</Frame>

Mitglieder sehen den Text in ihrer Sprache. Ein Tab mit der Markierung **nicht übersetzt** hat keinen eigenen Text: Mitglieder mit dieser Sprache sehen deinen englischen Text oder, wenn auch dieser fehlt, den Standardhinweis, und das leere Feld zeigt diesen Text als Vorschau. Ein roter Punkt markiert eine Sprache mit zu langem Text; Speichern ist erst wieder möglich, wenn du ihn kürzt. Schaltest du den Hinweis aus, bleiben deine Texte für das nächste Einschalten erhalten.

Der Hinweis ist nur eine Erinnerung. Er prüft, blockiert oder verändert keine Nachrichten. Um auf sensible Inhalte zu reagieren, richte [Guardrails](https://docs.tale.dev/de/platform/admin/governance/guardrails) ein.

## Festlegen, wer Skills mit allen teilt {#skill-sharing}

Standardmäßig kann jedes Mitglied einen Skill mit der ganzen Organisation teilen. Mit **Skill-Freigabe** behältst du das weniger Personen vor: Wähle unter **Skills mit der Organisation teilen**, wer das darf, und speichere die offenen Änderungen der Seite.

- **Alle Mitglieder** behält die Voreinstellung bei.
- **Redakteure und höher** lässt Redakteure, Entwickler, Admins und Inhaber zu, also die Rollen, die Agenten ausstatten.
- **Nur Inhaber und Admins** lässt nur Inhaber und Admins zu.

<Frame caption="Richtlinien > Richtlinien & Limits — die Skill-Freigabe legt fest, wer einen Skill mit der ganzen Organisation teilen darf.">

![Der Bereich Skill-Freigabe mit Skills mit der Organisation teilen auf Alle Mitglieder und dem Hinweis, dass Inhaber und Admins das immer dürfen und ein weiteres Mitglied unter Kompetenzen Skills für die Organisation veröffentlichen erhalten kann.](https://docs.tale.dev/images/platform/governance-skill-sharing.webp)

</Frame>

Inhaber und Admins dürfen immer mit allen teilen. Soll eine weitere Person das ohne höhere Rolle dürfen, weise ihr unter [Kompetenzen](https://docs.tale.dev/de/platform/admin/governance/competences) **Skills für die Organisation veröffentlichen** zu.

Alle anderen können weiterhin Skills erstellen und mit ihren eigenen Teams teilen. Sie können keinen Skill für die ganze Organisation anlegen, keinen eigenen auf **Organisation** erweitern und keinen organisationsweiten Skill direkt ändern. Einen eigenen Skill können sie auf ihre Teams einschränken, auch zusammen mit anderen Änderungen im selben Speichervorgang, oder löschen. Die Regel gilt im Skill-Editor, für Zip- und Ordner-Uploads, für Automatisierungspakete mit Skills und für die REST-API. Jede Ablehnung erscheint in den [Audit-Logs](https://docs.tale.dev/de/platform/admin/governance/audit-logs) als **Veröffentlichen eines Skills abgelehnt**.

Eine strengere Einstellung schränkt keine Skills ein, die bereits mit der Organisation geteilt sind. Um sie zu prüfen, öffne **Einstellungen > Skills**, wähle **Filter > Sichtbarkeit > Organisation** und sieh dir die Spalte **Erstellt von** an. Schränke die Skills ein, die nicht mehr für alle bestimmt sind, oder lösche sie.

<Note>

Ein verwaltetes Konfigurations-Release installiert seine Skills als das Mitglied, das es ausrollt. Stelle vor einer strengeren Einstellung sicher, dass dieses Mitglied über seine Rolle oder die Kompetenz weiterhin mit allen teilen darf. Sonst wird das nächste Release mit einem organisationsweiten Skill abgelehnt.

</Note>

## Konversations-Routing

Mit dem **Konversations-Routing** ordnest du neue Konversationen danach zu, wo sie eingehen. Füge eine Regel hinzu, fülle ihre Felder aus und speichere:

- **Eingang über**: **Beliebiges Postfach**, ein bestimmtes Postfach mit seinem Namen oder eine API-App. Eine API-App erscheint, sobald sie eine Konversation synchronisiert hat.
- **Gesendet an**: die Adresse, an die die Konversation gesendet wurde. Sie ist bei **Beliebiges Postfach** Pflicht, bei einem bestimmten Postfach optional und entfällt bei einer API-App. Die Adressprüfung ignoriert Groß- und Kleinschreibung.
- **Zuweisen an**: ein Team, eine Person oder beides.

Eine Regel für `support@example.com` erfasst auch Post mit Zusatz wie `support+rechnung@example.com`; eine Regel für die Adresse mit Zusatz hat für diese Adresse Vorrang. Treffen mehrere Regeln zu, gilt die genaueste: zuerst ein Postfach mit genau dieser Adresse, dann ein Postfach mit der Grundadresse, dann eine Adresse in beliebigem Postfach, zuletzt ein Postfach allein.

Bei Teamzuordnung sehen die Teammitglieder die Konversation, bei Personenzuordnung diese Person. Sind beide gesetzt, genügt eine der Zuordnungen für den Zugriff. Nicht zugewiesene Konversationen sortieren Admins und Inhaber ein.

Regeln greifen beim Eintreffen einer neuen Konversation. Sie ändern keine bestehende Zuordnung, wenn eine Antwort hinzugefügt wird. Verweist eine Regel auf eine gelöschte Person, ein gelöschtes Team oder ein entferntes Postfach, kommt die Konversation trotzdem ohne diese Routing-Zuordnung an. Teste mit einer neuen Nachricht und prüfe die entstandene Zuständigkeit.

## Anmeldelimits separat einrichten

Passwortanforderungen, Anmeldeversuchslimits, Sitzungs-Inaktivitätslimit und [Zwei-Faktor-Richtlinie](https://docs.tale.dev/de/platform/admin/two-factor-authentication) stehen unter **Einstellungen > Richtlinien > Sicherheit**. Ein Organisations-Inaktivitätslimit kann die Deployment-Grenze verschärfen. Bei Trusted-Header-Authentifizierung stimme das Sitzungsende mit Proxy oder Identitätsanbieter ab, da diese das Mitglied erneut authentifizieren können.

# Papierkorb
Source: https://docs.tale.dev/de/platform/admin/governance/trash

Als Admin oder Inhaber kannst du unter **Einstellungen > Richtlinien > Papierkorb** Datensätze wiederherstellen, die nach einer vorläufigen Löschung noch gespeichert sind. Endgültig gelöschte Daten lassen sich hier nicht zurückholen. Nicht jede Löschung in Tale führt über den Papierkorb.

## Einen Datensatz wiederherstellen

1. Öffne den Papierkorb und grenze die Liste mit **Filter > Kategorie** ein. Ohne Filter siehst du alle unterstützten Typen.
2. Prüfe Name, Eigentümer, Typ und Löschzeitpunkt. Damit unterscheidest du ähnlich benannte Datensätze. Ein Chat erscheint unter seinem Titel; die in einem [Arena](https://docs.tale.dev/de/platform/chat/arena-mode)-Vergleich verworfene Antwort behält den Titel ihres Chats.
3. Wähle in der Zeile **Wiederherstellen** und lies die Bestätigung.
4. Gib bei einem durch Aufbewahrung abgelaufenen Datensatz exakt `restore` ein. Bestätige und suche den Datensatz anschließend an seinem ursprünglichen Ort, etwa in der Chatliste oder im Wissensbereich.

Die wiederhergestellte Zeile verschwindet aus dem Papierkorb. Tale protokolliert die Wiederherstellung im Audit-Log. Ist die Zeile nicht mehr verfügbar, aktualisiere die Liste: Die Bereinigung könnte sie bereits endgültig gelöscht haben.

## Den Status verstehen

| Status | Bedeutung |
| --- | --- |
| **Verworfen** | Der Datensatz wurde vorläufig gelöscht und lässt sich noch wiederherstellen. |
| **Abgelaufen** | Die Aufbewahrungsrichtlinie hat den Datensatz ablaufen lassen. Eine Wiederherstellung übergeht diese Richtlinie und verlangt deshalb die Eingabe `restore`. |

**Abgelaufen** bedeutet nicht, dass die Wiederherstellungsfrist schon vorbei ist. Die Aufbewahrung markiert Datensätze zu Beginn der Schonfrist als abgelaufen. Nach deren Ende folgt die endgültige Bereinigung.

Der Kategoriefilter listet die Datensatztypen, die über den Papierkorb laufen: Chats, Dokumente, temporäre Dateien, Nachrichten-Feedback, Kontakte und externe Konversationen. Die früheren Versionen eines Chats reisen mit ihm: Sie werden zusammen mit dem Chat verworfen und wiederhergestellt und erscheinen nie als eigene Zeilen. Andere Daten wie Automatisierungsläufe, Nutzungsdaten, Audit-Einträge und Chat-Filterereignisse werden direkt oder zusammen mit übergeordneten Datensätzen gelöscht und haben hier keine Wiederherstellungsaktion.

## Die Wiederherstellungsfrist prüfen

Die Aufbewahrungsrichtlinie der Organisation legt die Schonfrist fest. Bei einer positiven Frist bleiben unterstützte abgelaufene Datensätze bis zur Bereinigung wiederherstellbar. Null erlaubt die sofortige endgültige Bereinigung. Prüfe die aktive Richtlinie unter [Richtlinien und Limits](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits), statt von einer festen Anzahl Tage auszugehen.

Ein leerer Papierkorb bedeutet, dass es in dieser Ansicht keine wiederherstellbaren Datensätze gibt. Er beweist nicht, dass nie etwas gelöscht wurde. Entferne Kategoriefilter, bevor du einen Datensatz als fehlend einstufst.

Ein fehlgeschlagener Abruf erscheint im Papierkorb nie als leer. Lässt sich die Liste nicht laden, erscheint statt der Tabelle eine Meldung mit **Erneut versuchen**, nie der leere Zustand. Sind bereits Datensätze aufgeführt, aber die nächsten oder eine Aktualisierung lassen sich nicht laden, sagt ein Hinweis über der Liste das und bietet **Erneut versuchen** an. Die Zählung unter der Liste behauptet dann nicht mehr, alle Datensätze zu zeigen.

## Aufbewahrungssperren berücksichtigen

Ein [Legal Hold](https://docs.tale.dev/de/platform/admin/governance/legal-hold) schützt betroffene Daten vor Löschung durch Aufbewahrung oder Löschanfragen. Er bewahrt noch vorhandene Daten, kann aber endgültig gelöschte Daten nicht zurückholen. Prüfe Sperren und Aufbewahrungshistorie, wenn du klärst, warum ein Datensatz im Papierkorb gelandet ist oder dort fehlt.

# Nutzungsanalyse
Source: https://docs.tale.dev/de/platform/admin/governance/usage-analytics

Öffne als Admin oder Inhaber **Einstellungen > Metriken > Nutzung**, um zu sehen, welche Aufgaben KI-Ressourcen verbrauchen. Wähle zuerst den Zeitraum und untersuche dann die Aufschlüsselungen, um veränderte Kosten oder Mengen zu erklären.

<Frame caption="Einstellungen > Metriken > Nutzung: Summen, Token-Diagramm und die meistgenutzten Assistenten der letzten 30 Tage.">

![Die Seite Nutzungs-Metriken für die letzten 30 Tage meldet 14 Anfragen, 448 Tokens, erfasste Kosten von 0,00 US-Dollar und eine aktive Person. Das Token-Diagramm hat nur für den aktuellen Tag einen Balken, aufgeteilt in Eingabe und Ausgabe; darunter listet die Tabelle der Top-Assistenten den Assistenten und die Titelerstellung für Chats.](https://docs.tale.dev/images/platform/metrics-usage.webp)

</Frame>

## Einen Nutzungsanstieg untersuchen

1. Öffne **Filter** und wähle unter **Zeitraum** 7, 30 oder 90 Tage. Die erste Ansicht zeigt 30 Tage.
2. Vergleiche Anfragen, Tokens, Kosten und aktive Benutzer. Mehr Anfragen haben andere Ursachen als längere Antworten.
3. Wähle im Filtermenü die Messgröße und zeitliche Auflösung des Diagramms, um den Beginn der Veränderung zu erkennen.
4. Prüfe die Tabellen für Assistenten, Modelle und Nutzung pro Person. Wähle eine Assistenten- oder Modellaufschlüsselung, um die Ansicht einzugrenzen. Entferne den Filterchip, um wieder mehr zu sehen.

Unter den Assistentennamen können auch Hilfsaufgaben wie die Erzeugung von Chattiteln stehen. Die Zahl der Anfragen entspricht daher nicht immer der Zahl gesendeter Nachrichten. Für die Sprachausgabe gibt es eine eigene Tabelle der Sprachmodelle.

**Nutzung pro Benutzer** ordnet jede Anfrage einer Person zu: dem Mitglied, das die Chatnachricht gesendet oder den Agentenlauf gestartet hat, auch über die REST-API oder den MCP-Endpoint. Läufe, die ein Zeitplan, ein Webhook oder ein Ereignis gestartet hat, haben keine Person dahinter. Ihre Nutzung erscheint als eine Zeile mit dem Namen **Automatisierungen (Trigger)**, die nicht als aktiver Benutzer zählt. In der Assistententabelle stehen ein Projekt-Agent und eine Automatisierung jeweils unter ihrem Namen. [So wird die Nutzung gezählt](https://docs.tale.dev/de/platform/admin/governance/usage-attribution) erklärt die Regel für jede Art von Arbeit.

## Kosten zusammen mit Tokens lesen

Das Dashboard verwendet erfasste Nutzungs- und Verbrauchsdaten. Eingabe- und Ausgabetokens sind getrennt. Dienste wie die Sprachausgabe oder die Bildgenerierung können andere Abrechnungseinheiten haben. Die Tokenzahl allein erklärt deshalb nicht alle Kosten. Zu den Eingabetokens zählt auch der Teil eines Prompts, den ein Anbieter aus seinem Cache gelesen oder dort abgelegt hat. Dieser Teil wird anders berechnet als die übrige Eingabe, deshalb kann ein Lauf, der einen langen Prompt wiederverwendet, viele Eingabetokens bei geringen Kosten zeigen.

Ein Bild, das ein Agent erstellt hat, erscheint unter seinem Bildmodell in **Top-Modelle** und unter dem Agenten oder der Automatisierung in **Top-Assistenten**, mit einer Anfrage pro Bild und ohne Tokens. Als Kosten gilt der Betrag, den OpenRouter gemeldet hat, bei OpenAI der Listenpreis der Bild-Tokens, die OpenAI gemeldet hat. Eine Anfrage, die der Anbieter berechnet hat, ohne ein brauchbares Bild zu liefern, zählt ebenso.

Lies die Kosten als erfasste Anwendungsnutzung, nicht als Rechnung deines Anbieters. Preise, Abos, Guthaben und nicht erfasste Aufrufe können den Vergleich beeinflussen. Eine angezeigte Null beweist nicht, dass der Anbieter nichts berechnet hat.

## Auf eine Budgetwarnung reagieren

Wähle für die Untersuchung denselben Zeitraum und die betroffene Aufgabe. Finde die Person, den Assistenten oder das Modell hinter dem Anstieg. Entscheide dann, ob du den Ablauf änderst, ein anderes Modell wählst oder unter [Richtlinien und Limits](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits) eine Obergrenze anpasst.

Prüfe die [Feedback-Analyse](https://docs.tale.dev/de/platform/admin/governance/feedback-analytics), bevor du ein Modell allein wegen der Kosten wechselst. Geringere Ausgaben helfen nur, wenn die Ergebnisse die Aufgabe weiterhin erfüllen.

## Fehlende Historie verstehen

Die Diagramme zeigen die Nutzungsdaten, die Tale noch aufbewahrt. Organisations- und Deployment-Einstellungen bestimmen, wie weit die Historie reicht; eine allgemeine Garantie von 365 Tagen gibt es nicht. Prüfe Zeitraum, Filter und Aufbewahrung des Nutzungsprotokolls, wenn erwartete Aktivität fehlt.

Lassen sich die Metriken nicht laden, sagt die Seite das und bietet **Erneut versuchen** an, statt Nullen oder leere Tabellen zu zeigen. Zeitraum und Filter bleiben, wie du sie gewählt hast. Schlägt eine Aktualisierung fehl, bleiben die bereits angezeigten Zahlen stehen, mit dem Hinweis, dass sie womöglich veraltet sind. Scheitert **Erneut versuchen** immer wieder, bitte den Bereitstellungsbetreiber zu prüfen, ob die Dienste von Tale laufen.

# So wird die Nutzung gezählt
Source: https://docs.tale.dev/de/platform/admin/governance/usage-attribution

Jede KI-Anfrage, die Tale für deine Organisation stellt, wird einmal erfasst, einer Person zugeordnet und an den [Budgetregeln](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits) gemessen, die für diese Person gelten. Diese Seite erklärt, wer diese Person bei jeder Art von Arbeit ist, gegen welche Limits die Arbeit zählt und wo du sie in der [Nutzungsanalyse](https://docs.tale.dev/de/platform/admin/governance/usage-analytics) findest. Mitglieder sehen ihren eigenen Anteil unter [Einstellungen > Nutzung](https://docs.tale.dev/de/platform/member/preferences#usage-limits).

## Was als Nutzung zählt

Tale erfasst eine Anfrage, sobald ein Modell oder ein gemessener Dienst für deine Organisation läuft: eine Chatantwort, auch eine neu erzeugte oder bearbeitete und beide Seiten eines Modellvergleichs; der kurze Modellaufruf, der einem neuen Chat seinen Titel gibt; ein Zug eines verwalteten Agenten, der an einer Aufgabe oder in einer Automatisierung arbeitet; ein Bild, das ein solcher Agent erstellt; Sprachausgabe; die Transkription einer hochgeladenen Aufnahme; ein gemessener Connector-Aufruf; und ein Aufruf der Modell-Endpunkte mit einem API-Schlüssel. Jeder Eintrag enthält die verbrauchten Tokens oder Einheiten und die Kosten, die zu diesem Zeitpunkt aus dem Listenpreis des Anbieters geschätzt wurden; bei einem Aufruf der Modell-Endpunkte sind es die Kosten, die das Modell-Gateway gemessen hat.

## Wem eine Anfrage angerechnet wird

Die Regel ist überall dieselbe: Eine Anfrage zählt für die Person, die die Arbeit angestoßen hat. Der Weg, über den sie kam, etwa die App, die REST-API, der MCP-Endpoint oder die Modell-Endpunkte, ändert daran nichts.

| Arbeit | Zählt für | Zählt zusätzlich für | Erscheint in der Nutzungsanalyse als |
| --- | --- | --- | --- |
| Eine Chatantwort oder der Titel eines neuen Chats | Das Mitglied, das die Nachricht gesendet hat | Den API-Schlüssel, wenn die Nachricht über die REST-API kam | Der verwendete Assistent; ein Titel unter `thread-title` |
| Ein Agentenlauf zu einer Aufgabe | Das Mitglied, das den Lauf aus der Aufgabe gestartet hat oder mit einem Kommentar oder einer Aufgabenbeschreibung, die den Agenten erwähnt; bei einem Lauf, den ein anderer Agent oder ein Automatisierungsschritt gestartet hat, das Mitglied, für das der Lauf dieses Agenten oder dieser Automatisierung zählt | — | Der Name des Agenten unter **Top-Assistenten** |
| Ein Automatisierungslauf, den jemand gestartet hat | Das Mitglied, das ihn aus der Laufliste, dem Builder, einem Chat, einer Aufgabe, über die REST-API oder den MCP-Endpoint gestartet hat | Den API-Schlüssel, wenn der Lauf mit einem gestartet wurde | Der Name der Automatisierung unter **Top-Assistenten** |
| Ein Automatisierungslauf, den ein Trigger gestartet hat | Niemanden: Hinter einem Zeitplan, einem Webhook oder einem Ereignis steht keine Person | — | Die Zeile **Automatisierungen (Trigger)** unter **Nutzung pro Benutzer** |
| Ein Lauf eines Projektagenten, den ein Zeitplan begonnen hat, oder einer, den ein anderer Agent aus einem solchen Lauf heraus gestartet hat | Niemanden, wie beim Lauf, den der Zeitplan selbst gestartet hat | — | Die Zeile **Automatisierungen (Trigger)** unter **Nutzung pro Benutzer** und der Name des Agenten unter **Top-Assistenten** |
| Ein Bild, das ein Agent erstellt | Die Person, für die der Lauf des Agenten zählt: wer ihn gestartet hat, bei einem Trigger-Lauf niemand | Den API-Schlüssel, wenn der Lauf mit einem gestartet wurde | Der Name des Agenten oder der Automatisierung unter **Top-Assistenten** und das Bildmodell unter **Top-Modelle** |
| Sprachausgabe oder eine Transkription | Das Mitglied, das sie angefordert hat | — | **Sprachausgabe** oder **Transkription** unter **Top-Assistenten**; Sprachausgabe zusätzlich unter **Top-Sprachmodelle** |
| Ein gemessener Connector-Aufruf | Das Mitglied, dessen Anfrage den Aufruf ausgelöst hat | — | Der Assistent, der ihn gemacht hat, oder **Connector** |
| Ein Aufruf der [Modell-Endpunkte](https://docs.tale.dev/de/develop/use-tale-from-your-editor#model-endpoints) | Das Mitglied, dessen API-Schlüssel ihn gesendet hat | Den API-Schlüssel | **Direkter API-Aufruf** unter **Top-Assistenten** |

Ein erneuter Versuch eines Agentenlaufs führt den Lauf fort, den sein Starter angestoßen hat; seine Nutzung bleibt deshalb bei dieser Person. Handelt eine Integration mit einem API-Schlüssel für ein anderes Mitglied, zählt der Lauf für dieses Mitglied, und das Limit des Schlüssels zählt ihn ebenfalls.

## Welche Limits gelten

- **Persönliche, Team- und Rollenlimits** binden die Person, der eine Anfrage angerechnet wird. Ein Lauf, den ein Zeitplan, ein Webhook oder ein Ereignis gestartet hat, hat keine solche Person und wird an keinem davon gemessen.
- **Organisationslimits** binden jede Anfrage, auch die Läufe eines Triggers.
- **API-Schlüssellimits** binden die Anfragen, die mit diesem Schlüssel authentifiziert wurden: die damit gesendeten Chatnachrichten, die damit gestellten Aufrufe der Modell-Endpunkte und die damit gestarteten Läufe.

Ist ein Limit erreicht, lehnt Tale die nächste Anfrage vor der Ausführung ab und nennt das Limit. Ein Zug eines verwalteten Agenten wird beim Start abgelehnt; ein bereits laufender Zug behält den Rahmen, den er bekommen hat. Ein Bild, das der Agent während seines Zugs anfordert, wird eigens geprüft, bevor das Bildmodell aufgerufen wird: Ist ein Limit erreicht, lehnt Tale das Bild ab, und der Zug läuft weiter. Das Bild zehrt außerdem vom Rahmen des Zugs, der es angefordert hat. [So werden Regeln kombiniert](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits#how-rules-combine) beschreibt den Fall, dass mehrere Regeln für eine Person gelten.

## Drei Situationen, die du kennen solltest

**Ein Teammitglied erwähnt deinen Agenten in einem Aufgabenkommentar oder in einer Aufgabenbeschreibung.** Der gesendete Kommentar oder die gespeicherte Beschreibung startet einen Lauf, und dieser zählt für das Teammitglied, von dem der Text stammt, nicht für dich als Ersteller des Agenten.

**Eine geplante Automatisierung gibt jede Nacht Geld aus.** Ihre Läufe erscheinen in der Zeile **Automatisierungen (Trigger)**. Sie erhöhen weder die persönliche Nutzung von jemandem noch die Zahl der aktiven Benutzer, und nur die Organisationslimits können sie stoppen. Lege ein Kosten- oder Anfragelimit für die Organisation fest, wenn du eine Obergrenze dafür brauchst.

**Eine Integration nutzt einen API-Schlüssel im Namen eines Mitglieds.** Die persönlichen und Team-Limits des Mitglieds sehen den Lauf, und das Limit des Schlüssels ebenfalls. Zwei Obergrenzen gelten, und die strengere lehnt zuerst ab.

## Was Mitglieder sehen

**Einstellungen > Nutzung** zeigt jedes Limit, das für das angemeldete Mitglied gilt, mit dem aktuellen Verbrauch: die gesendeten Chats, die angeforderten Sprachausgaben, die Aufrufe der Modell-Endpunkte und die gestarteten Agentenläufe, egal auf welchem Weg sie gestartet wurden. Geteilte Team- und Organisationslimits stehen ebenfalls dort, weil sie vor einem persönlichen Limit erreicht sein können.

# Mitglieder und Rollen
Source: https://docs.tale.dev/de/platform/admin/members-and-roles

Unter **Einstellungen > Mitglieder** fügst du Personen hinzu und wählst die passende Rolle für ihre Arbeit. Die Rolle bestimmt erlaubte Aktionen. Projektzugriff, Teams und Zuweisungen von Konversationen bestimmen, welche Ressourcen jemand erreichen kann.

<Video src="https://docs.tale.dev/videos/de/tutorials/ep8-people/ep8-people.de.mp4" poster="https://docs.tale.dev/videos/de/tutorials/ep8-people/ep8-people.de.webp" captions="https://docs.tale.dev/videos/de/tutorials/ep8-people/ep8-people.de.vtt" lang="de" title="Episode 8 — Menschen, Rollen & Teams" caption="Episode 8 — Menschen, Rollen & Teams (2:35)">

</Video>

<Frame caption="Einstellungen > Mitglieder — jeder Account und die Rolle, die ihn begrenzt.">

![Die Einstellungsseite Mitglieder, die den Inhaber des Workspace und vier weitere Personen mit je einem Rollen-Badge listet, neben der Schaltfläche Mitglied hinzufügen.](https://docs.tale.dev/images/get-started/settings-organization-members.webp)

</Frame>

## Eine Person hinzufügen

Zum Verwalten von Mitgliedern brauchst du ein Konto mit der Rolle Inhaber oder Admin.

1. Öffne **Einstellungen > Mitglieder** und wähle **Mitglied hinzufügen**.
2. Gib die **E-Mail**-Adresse ein. Das Feld **Name** ist optional.
3. Wähle eine **Rolle**. Für die tägliche Nutzung eignet sich Mitglied; die Tabelle unten zeigt, wann mehr Rechte sinnvoll sind.
4. Lege für ein neues Tale-Konto ein **Passwort** fest, das die angezeigten Anforderungen erfüllt. Gehört die Adresse bereits zu einem Konto, verwendet Tale dessen Zugangsdaten und blendet das Passwortfeld aus.
5. Wähle **Mitglied hinzufügen**. Sichere bei einem neuen Konto die Zugangsdaten aus der Bestätigung, bevor du sie schließt. Gib sie über den dafür vorgesehenen Kanal deiner Organisation weiter.

Die Person erscheint in der Mitgliederliste. Tale verschickt in diesem Ablauf weder eine Einladung noch eine E-Mail zum Zurücksetzen des Passworts: Dass du jemanden hinzufügst, ist die Bestätigung der Adresse. Das Konto funktioniert deshalb sofort überall — auch in Anwendungen, bei denen man sich mit dem Tale-Konto anmeldet. Ist die Adresse bereits Mitglied dieser Organisation, zeigt das Formular einen Hinweis und legt keinen zweiten Eintrag an.

<Tip>

Ordne die Person nach dem Hinzufügen den benötigten Teams zu. Eine Rolle allein gewährt weder den Projektzugriff eines Teams noch Zugang zu dessen Konversationen.

</Tip>

## Eine Rolle wählen

| Rolle | Typische Aufgaben | Organisationsverwaltung |
| --- | --- | --- |
| **Inhaber** | Alle Produkt- und Verwaltungsaufgaben | Darf auch die Inhaberschaft übertragen und die Organisation löschen, wobei ihre Sandboxes samt Dateien mitgelöscht werden; beim Löschen musst du zuerst den Namen der Organisation eintippen, bevor die Schaltfläche aktiv wird. |
| **Admin** | Personen, Dienste, Richtlinien und die Arbeit des Teams verwalten | Voller Zugriff auf Organisationseinstellungen; keine Übertragung der Inhaberschaft. |
| **Entwickler** | Agenten, Automatisierungen und Integrationen erstellen | Technische Einstellungen wie Anbieter, Connectors und API-Zugriff; keine Mitgliederverwaltung. |
| **Redakteur** | Inhalte pflegen und die tägliche Arbeit bearbeiten | Inhalte bearbeiten; kein Zugriff auf **Automatisierungen**; Connector-Ressourcen nur lesen. |
| **Mitglied** | Chat nutzen, freigegebene Ressourcen lesen und Projektaufgaben erstellen, die eigenen auch mit Projektagenten bearbeiten | Keine Organisationsverwaltung; darf Nachrichtenfeedback abgeben. |
| **Deaktiviert** | Kein aktiver Zugriff | Der Mitgliedschaftseintrag bleibt bestehen, ohne Rechte zu gewähren. |

**Automatisierungen** sehen nur Inhaber, Admins und Entwickler, in der Navigation wie in Projekten; alle anderen sehen über einen Link zu einer Automatisierung **Zugriff verweigert**.

Wer weder Inhaber noch Admin ist, kann **Einstellungen > Mitglieder** nicht öffnen und sieht die eigene Rolle unter [**Einstellungen > Konto > Deine Rolle**](https://docs.tale.dev/de/platform/member/preferences#role).

Für Projektaufgaben gilt eine eigene Regel: Wer ein Projekt öffnen kann, erstellt darin Aufgaben und ändert die eigenen, also die selbst erstellten und die zugewiesenen. Redakteure und höhere Rollen ändern jede Aufgabe. Einstellungen, Agenten und Dateien des Projekts bleiben bei den Redakteuren. [Aufgaben auf dem Projektboard verwalten](https://docs.tale.dev/de/platform/projects/tasks#wer-aufgaben-erstellen-und-aendern-darf) zählt auf, was Mitglieder mit ihren eigenen Aufgaben tun können.

Die Rolle beschreibt Befugnisse, nicht die Sichtbarkeit jedes Datensatzes. Konversationen folgen ihrer Zuweisung: Eine Person sieht Arbeit, die ihr oder ihren Teams zugewiesen ist. Nicht zugewiesene Konversationen bleiben Inhabern und Admins zur Sichtung vorbehalten. Siehe [Konversationen zuweisen](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits#konversations-routing).

Nur Inhaber und Admins können Audit-Protokolle lesen. Aktionen anderer Rollen können trotzdem Einträge erzeugen. Einen Eintrag auszulösen berechtigt nicht dazu, das Protokoll zu öffnen.

## Rolle ändern oder Passwort zurücksetzen

Öffne das Zeilenmenü der Person, wähle **Bearbeiten** und ändere die **Rolle**. Wähle **Speichern** und prüfe anschließend die Rolle in der Liste. Um ein deaktiviertes Mitglied wieder freizuschalten, wählst du ausdrücklich die gewünschte Rolle.

Im Dialog kannst du auch den Anzeigenamen ändern. Die E-Mail-Adresse ist schreibgeschützt. Für ein neues Passwort aktivierst du **Passwort aktualisieren**, gibst ein Passwort gemäß den angezeigten Anforderungen ein und speicherst. Prüfe die Identität der Person nach dem Verfahren deiner Organisation, bevor du ihr Konto zurücksetzt.

Deine eigene Rolle lässt sich über dieses Menü nicht ändern. Inhaber lässt sich nicht im Rollenfeld vergeben, und der letzte Administrator darf nicht herabgestuft werden. Auch bestehende Inhaber und der Ersteller der Organisation haben geschützte Rollen. Prüfe bei einer Ablehnung das betroffene Konto, bevor du eine andere Rolle versuchst.

## Inhaberschaft übertragen

Als Inhaber kannst du im Zeilenmenü eines anderen Mitglieds **Inhaberschaft übertragen** wählen. Lies die Bestätigung sorgfältig: Die gewählte Person wird Inhaber, du selbst wirst Admin. Verwende diese Aktion für eine Übergabe der Verantwortung, nicht für eine normale Rollenänderung.

## Zugriff entziehen oder wiederherstellen

Wähle **Deaktiviert**, wenn der Zugriff enden, die Mitgliedschaft aber bestehen bleiben soll. **Löschen** im Zeilenmenü entfernt die Mitgliedschaft aus dieser Organisation und löscht dabei auch die getrennten Sandbox-Arbeitsbereiche der [Agentenläufe, die die Person gestartet hat](https://docs.tale.dev/de/platform/projects/tasks#agentenlaeufe-die-ein-mitglied-startet), samt Dateien; mit **Deaktiviert** bleiben diese Arbeitsbereiche erhalten. Prüfe vorher geteilte Arbeit und Teamverantwortungen. Eine Mitgliedschaft zu entfernen ist keine [Löschanfrage einer betroffenen Person](https://docs.tale.dev/de/platform/admin/governance/data-subject-requests).

Hat ein Mitglied seinen Authenticator oder Passkey verloren, öffne **Bearbeiten** und nutze die jeweiligen Sicherheitsfunktionen. [Zwei-Faktor-Authentifizierung](https://docs.tale.dev/de/platform/admin/two-factor-authentication) erklärt Wiederherstellung, Zurücksetzen und die Folgen für aktive Sitzungen.

# Administration
Source: https://docs.tale.dev/de/platform/admin/overview

In den Organisationseinstellungen legst du fest, wer Tale nutzen darf, welche Dienste verfügbar sind und wie die Organisation mit Arbeit und Daten umgeht. Beginne mit der Aufgabe, die gerade ansteht. Nicht jeder Bereich muss eingerichtet sein, bevor dein Team loslegen kann.

<Video src="https://docs.tale.dev/videos/de/tutorials/ep9-governance/ep9-governance.de.mp4" poster="https://docs.tale.dev/videos/de/tutorials/ep9-governance/ep9-governance.de.webp" captions="https://docs.tale.dev/videos/de/tutorials/ep9-governance/ep9-governance.de.vtt" lang="de" title="Episode 9 — Richtlinien, Kosten & Vertrauen" caption="Episode 9 — Richtlinien, Kosten & Vertrauen (3:31)">

</Video>

## Eine Organisation einrichten

1. [Füge Mitglieder hinzu und wähle ihre Rollen](https://docs.tale.dev/de/platform/admin/members-and-roles). Vergib die Rechte, die ihre Arbeit erfordert.
2. [Erstelle Teams](https://docs.tale.dev/de/platform/admin/teams), wenn mehrere Personen denselben Zugang zu Projekten oder Konversationen brauchen.
3. [Verbinde einen KI-Anbieter](https://docs.tale.dev/de/platform/admin/providers), damit Chats und Agenten Modelle verwenden können.
4. [Hinterlege Zugangsdaten für Connectors](https://docs.tale.dev/de/platform/admin/connectors), deren Dienste deine Workflows benötigen.

Inhaber und Admins verwalten die Organisationseinstellungen. Entwickler erreichen die technischen Einstellungen für Integrationen, können aber keine Mitglieder verwalten und nicht den gesamten Richtlinienbereich öffnen. Persönliche Kontoeinstellungen sind davon getrennt.

## Die passende Einstellung finden

| Du möchtest… | Öffne… |
| --- | --- |
| Standardmodelle festlegen oder die Modellauswahl begrenzen | [Modelle](https://docs.tale.dev/de/platform/admin/governance/content-models) |
| Nutzung, Uploads oder Aufbewahrung begrenzen | [Richtlinien und Limits](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits) |
| Nachrichten filtern und organisationsweite Anweisungen festlegen | [Schutzregeln](https://docs.tale.dev/de/platform/admin/governance/guardrails) |
| Aktionen oder Ausgaben untersuchen | [Audit-Protokolle](https://docs.tale.dev/de/platform/admin/governance/audit-logs) oder [Nutzungsmetriken](https://docs.tale.dev/de/platform/admin/governance/usage-analytics) |
| Fehlschlagende Chat-Antworten, Agenten-Runden oder Automatisierungsläufe finden | [Betriebsmetriken](https://docs.tale.dev/de/platform/admin/governance/operations-metrics) |
| Aufbewahrte Daten wiederherstellen oder vor dem Löschen schützen | [Papierkorb](https://docs.tale.dev/de/platform/admin/governance/trash) oder [Aufbewahrungssperre](https://docs.tale.dev/de/platform/admin/governance/legal-hold) |
| Eine Löschanfrage bearbeiten | [Betroffenenanfragen](https://docs.tale.dev/de/platform/admin/governance/data-subject-requests) |

## Anmeldung, Integrationen und Darstellung

Richte [Enterprise SSO](https://docs.tale.dev/de/platform/admin/enterprise-sso) für deinen Identitätsanbieter und [Zwei-Faktor-Authentifizierung](https://docs.tale.dev/de/platform/admin/two-factor-authentication) zum Schutz der Konten ein. [API-Schlüssel](https://docs.tale.dev/de/platform/admin/api-keys) ermöglichen Software den Zugriff auf Tale.

Unter [Branding](https://docs.tale.dev/de/platform/admin/branding) änderst du Logo und Farben der Organisation. [Sandboxes](https://docs.tale.dev/de/platform/admin/sandboxes) zeigt Ausführungskapazität und Limits für die einzelnen Aufgabenarten; mit [Sandbox-Geräten](https://docs.tale.dev/de/platform/admin/sandbox-devices) laufen die Sandboxes deiner Organisation auf eigenen Rechnern. Wie ein Projekt-Agent diese Ressourcen nutzen darf, erklärt [Agenten aus Administrationssicht](https://docs.tale.dev/de/platform/admin/agents).

Nach einem Update zeigt dir [Was gibt es Neues?](https://docs.tale.dev/de/platform/admin/changelog), welche Änderungen für dein Team relevant sind.

# KI-Anbieter
Source: https://docs.tale.dev/de/platform/admin/providers

Verbinde einen KI-Anbieter, bevor Tale Chats oder Agenten ausführen soll. Unter **Einstellungen > KI-Anbieter** verwalten Inhaber, Admins und Entwickler die Zugangsdaten ihrer Organisation. Der Anbieter bestimmt Verbindung und unterstützte Anmeldung; ein Zugangsdaten-Eintrag stellt den Zugriff deiner Organisation darauf bereit.

<Frame caption="Jede Zeile steht für einen Zugangsdaten-Eintrag. Standard kennzeichnet den Eintrag für Aufrufe ohne ausdrückliche Auswahl.">

![Die Seite für KI-Anbieter zeigt einen Zugangsdaten-Eintrag mit Anbieter, Authentifizierungsmethode und Standard-Kennzeichnung.](https://docs.tale.dev/images/get-started/settings-providers.webp)

</Frame>

## Die ersten Zugangsdaten hinzufügen

1. Wähle **Zugangsdaten hinzufügen** und den Anbieter. Bereits konfigurierte Anbieter stehen zuerst. Du kannst sie erneut wählen, um weitere Zugangsdaten anzulegen.
2. Wähle eine **Authentifizierungsmethode**, falls der Anbieter mehrere unterstützt.
3. Prüfe das Feld **Name**. Es enthält bereits den Namen des Anbieters. Heißen andere Zugangsdaten dieses Anbieters schon so, hängt Tale eine Zahl an: `OpenRouter`, dann `OpenRouter 2`. Mit einem Namen, der den Zweck erkennen lässt, etwa `Produktionsschlüssel` oder `Finanzteam`, hältst du mehrere Zugangsdaten desselben Anbieters auseinander. Fülle die Pflichtfelder der Methode aus.
4. Prüfe die Liste **Erlaubte Modelle**. Hat der Anbieter einen Katalog, erlaubt eine leere Liste dessen Modelle. Ohne Katalog sind ausdrückliche Modell-IDs erforderlich.
5. Wähle **Hinzufügen**. Prüfe den neuen Eintrag und setze ihn als Standard für den Anbieter, wenn gewöhnliche Anfragen ihn verwenden sollen.

Teste Zugangsdaten vom Typ **API-Schlüssel** oder **Umgebungsvariable** mit einer kurzen Chatnachricht an das gewünschte Modell. Das Modell muss über aktive Zugangsdaten erreichbar und durch die Modellzugriffsregeln der Organisation erlaubt sein. Abonnement-Zugangsdaten prüfst du wie unten beschrieben mit einem Aufgaben- oder Automatisierungsagenten. Gespeicherte Zugangsdaten allein belegen noch keinen funktionierenden Aufruf.

## Die Anmeldemethode wählen

| Methode | Benötigte Angaben | Einsatz |
| --- | --- | --- |
| **API-Schlüssel** | Der geheime Schlüssel des Anbieters | Gewöhnlicher, nutzungsabhängig abgerechneter API-Zugriff. Der gespeicherte Wert ist verschlüsselt und später nur maskiert sichtbar. |
| **Umgebungsvariable** | Der Name einer Bereitstellungsvariable | Ein Betreiber verwaltet das Geheimnis außerhalb der Oberfläche. Der Name muss mit `TALE_PROVIDER_KEY_` beginnen. |
| **Abo-Schlüssel** | Ein unterstütztes Abonnement-Geheimnis des Anbieters | Ausführung über die unterstützte Agent-Laufzeit des Anbieters in Aufgaben und Automatisierungen, nie im Chat. |
| **Abo-Broker** | Broker-Endpunkt und Konfiguration seiner Token-Antwort | Die Bereitstellung bezieht nutzbare Abonnement-Tokens von einem Broker, für die Agent-Laufzeit des Anbieters in Aufgaben und Automatisierungen, nie im Chat. |

Es erscheinen nur Methoden, die der ausgewählte Anbieter unterstützt. Ein Variablenverweis legt die Variable nicht an. Der Betreiber muss sie gemäß der [Anbieterkonfiguration](https://docs.tale.dev/de/self-hosted/configuration/providers) bereitstellen.

## Abos in Aufgaben nutzen, nicht im Chat

Zugangsdaten vom Typ **Abo-Schlüssel** oder **Abo-Broker** funktionieren nur in der Agent-Laufzeit, an die sie gebunden sind: Claude Code für ein Anthropic-Abonnement und für die Coding-Pläne von Moonshot und Z.ai, Codex für ein ChatGPT-Abonnement, Gemini CLI für Gemini und Hermes für Nous Portal. Die Anbieter erlauben Abo-Tokens nicht in anderen Anwendungen, und Anthropic weist sie bei jedem Client außer Claude Code ab. Der Chat ruft die API des Anbieters direkt aus Tale auf und kann deshalb keine Abo-Zugangsdaten verwenden.

Tale führt ein Abo deshalb in Aufgaben und Automatisierungen aus, wo seine Laufzeit in einer Sandbox arbeitet. Der Chat bietet nur Modelle an, die Zugangsdaten vom Typ **API-Schlüssel** oder **Umgebungsvariable** bereitstellen. Die App weist an drei Stellen darauf hin: Das Formular zum Hinzufügen zeigt **Nur für Aufgaben und Automatisierungen**, sobald du eine Abo-Methode wählst, jede Abo-Zeile in der Tabelle der Zugangsdaten trägt denselben Hinweis, und die Modellliste im Chat nennt die Abos, die sie auslässt.

Um mit einem Modell zu chatten, das du über ein Abo erreichst, füge für denselben Anbieter Zugangsdaten per API-Schlüssel oder Umgebungsvariable hinzu oder verbinde einen Anbieter wie OpenRouter, der das Modell bereitstellt.

## Einen Abo-Broker verbinden

Abo-Broker unterstützen Anthropic-Abonnements über Claude Code und OpenAI-ChatGPT-Abonnements über Codex. Diese Zugangsdaten dienen Agenten für Aufgaben und Automatisierungen. Chats benötigen Zugangsdaten für den direkten API-Zugriff, aus den [oben genannten Gründen](https://docs.tale.dev/de/platform/admin/providers#abos-in-aufgaben-nutzen-nicht-im-chat).

| Anbieter und Laufzeit | Zielvariable |
| --- | --- |
| Anthropic · Claude Code | `CLAUDE_CODE_OAUTH_TOKEN` |
| OpenAI · Codex | `TALE_SUBSCRIPTION_TOKEN` |

Wähle beim Hinzufügen der Zugangsdaten **Abo-Broker** und lass dir Endpunkt und Anmeldeangaben vom Betreiber geben. Der Endpunkt muss ausschließlich Tokens des gewählten Anbieters liefern. Beim Tale AI Gateway ist das `/api/tokens/anthropic` oder `/api/tokens/openai`.

Trage unter **Pfad zum Token-Array** den Wert `$.tokens` ein, unter **Token-Feld** den Wert `access_token` und unter **Ziel-Umgebungsvariable** den Wert aus der Tabelle. Verwende unter **Erweitert** das **Status-Feld** `status`, den **Wert für aktiv** `active` und das **Ablauf-Feld** `expires_at`, und lass **Sicherheitsabstand zum Ablauf (ms)** beim Standardwert. Das Gateway hält ein Konto, dessen Token bald erneuert wird, selbst zurück, solange ein anderes Konto die Arbeit übernehmen kann; Tale nutzt es trotzdem, wenn kein anderes verfügbares Konto den Durchlauf übernehmen kann, etwa während die anderen nach Erreichen eines Rate-Limits pausieren. Bei anderen Brokern können die Pfade abweichen. OpenAI-Pools müssen zusätzlich für jedes nutzbare Token die `account_id` des Anbieters liefern. Die brokerinterne `id` ist eine separate Kontokennung.

Begrenze bei OpenAI **Erlaubte Modelle** auf Modell-IDs, die dein ChatGPT-Abonnement unterstützt. Der OpenAI-API-Katalog kann Modelle enthalten, die dieses Abonnement nicht nutzen kann.

Um ein GPT-6-Modell über das ChatGPT-Abonnement zu nutzen, speicherst du zuerst die OpenAI-Broker-Zugangsdaten. Wähle dann bei einem [Projektagenten](https://docs.tale.dev/de/platform/projects/project-agents) unter **Agent-Laufzeit** den Eintrag **Codex**. Suche unter **Modell** nach der Modell-ID, etwa `gpt-6.1-sol`, und wähle den Eintrag mit **OpenAI · Abo**. [Die GPT-6-Modelle nutzen](https://docs.tale.dev/de/platform/admin/providers#die-gpt-6-modelle-nutzen) erklärt, wo jedes Modell sonst läuft.

Mit **Token-Auswahl** bestimmst du, wie neue Agentendurchläufe verteilt werden:

- **Zufällig** ist vorausgewählt. Bei jeder Auswahl haben alle nutzbaren Konten die gleiche Wahrscheinlichkeit.
- **Erstes nutzbares** nimmt immer das erste nutzbare Konto in der Reihenfolge des Brokers. Damit legst du eine bevorzugte Reihenfolge fest; die Arbeit wird dadurch nicht verteilt.
- **Round-Robin** wählt das nutzbare Konto, dessen letzte Auswahl am längsten zurückliegt. Alle Backend-Prozesse teilen sich den Auswahlverlauf für diese Organisation und diese Zugangsdaten, auch bei gleichzeitigen Anfragen. Eine andere Antwortreihenfolge und Backend-Neustarts erhalten diesen Verlauf. Stabile Kontokennungen des Brokers erhalten ihn auch bei Tokenwechseln. So werden Auswahlen verteilt, nicht zwingend der Tokenverbrauch oder die Anzahl laufender Agenten.

Speichere die Zugangsdaten und starte eine kurze Aufgabe oder Automatisierung mit dem passenden Anbieter und der passenden Agent-Laufzeit. Prüfe, ob der Agent eine Antwort abschließt. Ist kein Konto nutzbar, sollte der Betreiber Autorisierung, Token-Ablauf und geplante Token-Erneuerungen sowie das gemeldete Kontingent prüfen. Die [Broker-Konfigurationsreferenz](https://docs.tale.dev/de/self-hosted/configuration/providers#einen-abo-broker-verbinden) erklärt optionale Kontometadaten, Standardwerte und Abhilfe.

## Die GPT-6-Modelle nutzen

Der OpenAI-Katalog enthält GPT-6 Astra (`gpt-6-astra`), GPT-6 Sol (`gpt-6-sol`), GPT-6 Luna (`gpt-6-luna`) und GPT-6.1 Sol (`gpt-6.1-sol`).

- Der **Chat** bietet alle vier über OpenAI-Zugangsdaten vom Typ **API-Schlüssel** oder **Umgebungsvariable** an, auch in der automatischen Modellauswahl. Astra und GPT-6.1 Sol rufen Tools nur über die Responses-API von OpenAI auf, deshalb spricht Tale sie über diese API an. GPT-6 Sol und Luna nehmen die Tools des Chats nur mit ausgeschaltetem Reasoning an, deshalb bietet die Auswahl für sie keine Stufen für **Denkaufwand** an.
- **Projektagenten und Automatisierungen** führen Astra und GPT-6.1 Sol nur auf **Codex** aus, der Laufzeit, die die Responses-API spricht, mit Zugangsdaten per API-Schlüssel, Umgebungsvariable oder ChatGPT-Abo. Für andere Laufzeiten bietet die Modellauswahl sie nicht an.

## Azure oder einen eigenen Endpunkt einrichten

Azure OpenAI benötigt eine **Endpoint-URL**, gewöhnlich `https://<resource>.openai.azure.com/openai/v1`. Jeder Zugangsdaten-Eintrag gehört zu dieser Ressource. Azure verwendet die dort konfigurierten Bereitstellungsnamen als Modell-IDs. Trage diese Namen in die Liste **Erlaubte Modelle** ein. Ohne Katalog stellt eine leere Liste keine Modelle bereit.

Verwende dokumentierte Endpunkte und Modellkennungen des Anbieters. Ein Anzeigename auf einer Produktseite muss nicht der von der API akzeptierten Kennung entsprechen.

## Einen eigenen Anbieter definieren

Eine Organisation kann einen Endpunkt anbinden, den der mitgelieferte Katalog nicht kennt: einen eigenen Modellserver wie vLLM oder Ollama oder ein internes Gateway, das die OpenAI- oder Anthropic-API spricht. Wähle **Zugangsdaten hinzufügen** und dann **Eigener Anbieter**, den Eintrag unterhalb des Katalogs:

1. Gib einen **Anbietername** ein. Er benennt den Anbieter und diese Zugangsdaten; die Kennung des Anbieters wird daraus abgeleitet.
2. Wähle das **API-Format**, das der Endpunkt spricht, und trage seine **Basis-URL** ein, also die API-Wurzel, an die die Plattform ihre Pfade anhängt. Ein öffentlicher Host braucht `https`.
3. Behalte unter **Modelle** die Option **Vom Endpunkt ermitteln**, damit die `/models`-Liste des Servers mit diesem Schlüssel gelesen wird, oder wähle **Modell-IDs eingeben** und trage die genauen IDs unter **Erlaubte Modelle** ein, wenn der Endpunkt seine Modelle nicht auflisten kann.
4. Trage den **API-Schlüssel** (oder die Umgebungsvariable) ein und wähle **Hinzufügen**.

Die Zeile der Zugangsdaten zeigt den Anbieter jetzt mit der Kennzeichnung **Eigener**, und der Anbieter erscheint mit derselben Kennzeichnung im Katalog von **Zugangsdaten hinzufügen**; wählst du ihn dort, legst du weitere Zugangsdaten für ihn an. Eine private oder Loopback-Adresse braucht zusätzlich die Freigabe privater Hosts in der Bereitstellung; die setzt ein Betreiber, das Speichern der Zugangsdaten allein gibt sie nicht frei. Lass den Betreiber Erreichbarkeit und Netzwerkrichtlinie vorbereiten und folge dann [Einen lokalen Modellserver verbinden](https://docs.tale.dev/de/tutorials/admin/connect-local-provider). Sollen Coding-Agenten den Anbieter nutzen, prüfe zusätzlich eine Agentensitzung: Deren Modellverkehr läuft über ein eigenes Gateway, das ebenfalls Netzwerkzugriff und Zertifikatsvertrauen braucht.

Im Menü der Zeile liest **Modelle prüfen** die Modellliste des Endpunkts erneut mit diesem Schlüssel, **Zugangsdaten bearbeiten** ändert neben dem Namen auch Basis-URL, API-Format und Modellquelle, und **Löschen** entfernt die Zugangsdaten. Beim Bearbeiten ändert **Speichern** Anbieter und Zugangsdaten gemeinsam: Ein bereits vergebener Name oder ein veralteter Stand wird abgelehnt, bevor sich eines davon ändert. Hat jemand den Anbieter oder diese Zugangsdaten gespeichert, nachdem du den Dialog geöffnet hast, wird dein Speichern abgelehnt, statt die andere Änderung zu überschreiben; öffne den Dialog erneut, um den aktuellen Stand zu laden. Mit den letzten Zugangsdaten eines Anbieters verschwindet auch der Anbieter selbst; der Dialog sagt das vorher. Jede gespeicherte Version der Definition bleibt im Konfigurationsverlauf der Organisation erhalten. Was das Formular nicht abdeckt, etwa ein Endpunkt für Coding-Agenten, wird in der Definitionsdatei gesetzt, die der [Leitfaden zur Anbieterkonfiguration](https://docs.tale.dev/de/self-hosted/configuration/providers) beschreibt.

Bricht die Verbindung beim **Speichern** ab, kann das Ergebnis unklar sein. Lade die Seite neu und prüfe Anbieter und Zugangsdaten, bevor du es erneut versuchst. Ein Verbindungsfehler bedeutet nicht, dass die Änderungen zurückgenommen wurden.

## Standard und Modellzugriff festlegen

Wähle **Zum Standard machen** im Zeilenmenü. Pro Anbieter gibt es einen Standard. Die Auswahl eines anderen Eintrags verschiebt die Kennzeichnung. Deaktivierte Zugangsdaten können kein Standard sein. Ohne Standard muss ein Aufrufer den gewünschten Eintrag ausdrücklich benennen.

Die Liste **Erlaubte Modelle** eines Eintrags begrenzt nur diese Zugangsdaten. Unter [Modelle](https://docs.tale.dev/de/platform/admin/governance/content-models) legst du anbieterübergreifend Standardmodelle und Zugriffsregeln für Personen, Teams und Rollen fest. Beide Einschränkungen gelten. Eine erweiterte Liste umgeht die andere nicht.

**Agent-Laufzeiten** unter der Tabelle ist schreibgeschützt. Dort siehst du verfügbare Modelle und Abonnements je Laufzeit. Um diese Konfiguration zu ändern, bearbeitest du die Zugangsdaten darüber.

## Fehlende oder nicht funktionierende Modelle prüfen

- Fehlt ein Anbieterstandard, wähle die vorgesehenen aktiven Zugangsdaten und setze sie als Standard.
- Konnte der Katalog nicht geladen werden, nutze **Kataloge aktualisieren** und prüfe das Ergebnis für den Anbieter. Live-Kataloge werden zwischengespeichert; mitgelieferte Kataloge ändern sich mit der Plattform.
- Fehlt ein Modell, prüfe die Allowlist und die Modellzugriffsregeln der Organisation. Ohne Katalog müssen die Modell-IDs exakt stimmen.
- Wird eine Anfrage abgelehnt, prüfe Aktivierung, Anbieterzugriff, Endpunkt und Kontingent beim Anbieter, bevor du Modellregeln änderst.

## Zugangsdaten rotieren oder stilllegen

Nutze die Ersetzen-Aktion im Zeilenmenü, um ein Geheimnis zu rotieren und Namen sowie Verweise zu behalten. **Deaktivieren** pausiert den Eintrag, ohne seine Konfiguration zu entfernen; **Aktivieren** schaltet ihn wieder frei. Prüfe den Ersatz mit dem vorgesehenen Modell.

<Warning>

Das Löschen eines Eintrags entzieht abhängigen Aufrufern den Zugriff. Stelle sie vorher um. Wenn du den Standard löschst, wähle einen neuen, damit Aufrufe ohne ausdrückliche Auswahl weiterhin Zugangsdaten finden. Zugangsdaten, die das Embedding-Modell der Wissenssuche verwendet — die unter **Einstellungen > Datenresidenz > Embedding-Modell** gewählten oder der letzte aktive Standard dieses Anbieters — lassen sich nicht löschen: Der Löschdialog nennt die Abhängigkeit, und Tale lehnt das Löschen ab. Wähle zuerst andere Zugangsdaten für das Embedding-Modell.

</Warning>

# Sandboxes auf eigenen Geräten ausführen
Source: https://docs.tale.dev/de/platform/admin/sandbox-devices

Ein Gerät ist ein Rechner, den du mit deiner Organisation verbindest, damit ihre Sandboxes dort laufen statt auf dem Tale-Server: eine freie Workstation, ein Build-Server oder ein Mac, der Kapazität übrig hat. Inhaber und Admins fügen Geräte unter **Einstellungen > Sandboxes** hinzu und entfernen sie. Entwickler sehen die Liste.

## Prüfen, was der Rechner braucht

- Linux auf x86_64 oder arm64 oder macOS auf Apple Silicon oder Intel.
- Docker: Docker Engine unter Linux, unter macOS Docker Desktop, OrbStack oder Colima. Fehlt Docker, bietet die Tale CLI an, es zu installieren.
- Ausgehendes HTTPS zu deiner Tale-Seite. Das Gerät baut die Verbindung zu Tale selbst auf; nichts muss den Rechner von außen erreichen, deshalb funktioniert es auch hinter einem Router oder einer Firewall.
- Speicherplatz für die Sandbox-Images, einige Gigabyte, und für die Arbeitsbereiche, die es aufnehmen wird.

Standardmäßig führt ein Gerät je zwei CPUs und je 4 GiB Arbeitsspeicher, die Docker nutzen kann, eine Sandbox aus, höchstens 16 gleichzeitig, denn jede Agenten-Sandbox erhält 2 CPUs und 4 GiB. Beim Verbinden kannst du eine andere Zahl wählen.

Diese Zahl ist eine Obergrenze. Vor dem Start prüft das Gerät zusätzlich den verfügbaren Arbeitsspeicher des Hosts und den freien Speicherplatz für Arbeitsbereiche. Ein freier Platz allein reicht deshalb nicht immer für eine weitere Sandbox.

<Warning>

Ein Gerät erledigt die Arbeit deiner Organisation. Die Arbeitsbereiche der Agenten, die Dateien, die sie verarbeiten, und die kurzlebigen Zugangsdaten einer Aufgabe laufen über diesen Rechner, und wer darauf Administratorrechte hat, kann sie lesen. Verbinde nur Rechner, die du kontrollierst und denen du so vertraust wie dem Tale-Server. Umgekehrt bestimmt die Tale-Seite, was auf dem Gerät läuft, auch die Updates, die es selbst installiert: Verbinde einen Rechner nur mit einer Tale-Seite, der du ihn anvertraust.

</Warning>

## Ein Gerät hinzufügen

<Steps>

<Step title="Befehl kopieren">

Öffne **Einstellungen > Sandboxes** und wähle im Bereich **Geräte** die Schaltfläche **Gerät hinzufügen**. Wähle unter **Installieren und verbinden** die Schaltfläche **Befehl kopieren**.

Der Befehl funktioniert einmal und nur innerhalb einer Stunde. Er enthält ein Einmal-Token, das der Rechner gegen eigene Zugangsdaten eintauscht.

<Frame caption="Gerät hinzufügen: der Befehl zum Installieren und Verbinden und der kürzere für einen Rechner, auf dem die CLI schon installiert ist. Das Token im Bild ist ein Platzhalter.">

![Der Dialog Gerät hinzufügen mit dem Befehl unter Installieren und verbinden, der die Tale CLI installiert und tale sandbox connect mit der Adresse der Bereitstellung und einem Einmal-Token ausführt, der Schaltfläche Befehl kopieren, den Voraussetzungen, dem Hinweis, dass der Befehl einmal innerhalb einer Stunde funktioniert, dem kürzeren Befehl für einen Rechner mit installierter CLI und dem Status, der auf die Verbindung des Geräts wartet.](https://docs.tale.dev/images/platform/sandbox-add-device.webp)

</Frame>

</Step>

<Step title="Auf dem Rechner ausführen">

Füge den Befehl in ein Terminal auf dem Rechner ein und führe ihn aus. Er installiert die Tale CLI und verbindet den Rechner:

```text
Connecting this machine to https://your-org.tale.dev as "studio-mac"…
Starting the sandbox device (Tale 0.5.60). The first start downloads the sandbox images, which can take a few minutes…
```

Ist die Tale CLI auf dem Rechner schon installiert, führe den kürzeren Befehl unter **Tale CLI schon installiert? Führe stattdessen das aus** aus.

</Step>

<Step title="Prüfen, ob es online ist">

Sobald der Rechner Tale erreicht, zeigt der Dialog **studio-mac ist verbunden.**, und das Gerät erscheint in der Liste **Geräte** als **Online**. Wähle **Fertig**.

</Step>

</Steps>

Das Gerät läuft nach einem Neustart des Rechners weiter, sofern Docker mitstartet. Wird Tale aktualisiert, bringt sich das Gerät selbst auf dasselbe Release.

## Verstehen, wo Sandboxes laufen

Neue Arbeitsbereiche für Agenten und Automatisierungen starten auf einem verbundenen Gerät mit freiem Platz. Hat keines Platz, starten sie auf dem Tale-Server. Ein Arbeitsbereich bleibt mit seinen Dateien auf dem Rechner, auf dem er gestartet ist; ein Agent, der schon einen Arbeitsbereich auf dem Server hat, nutzt diesen also weiter. Seiten, die beim Crawlen von Websites gerendert werden, bleiben immer auf dem Server.

Haben mehrere Geräte Platz, berücksichtigt Tale sowohl freie Plätze als auch den gemessenen verfügbaren Arbeitsspeicher. Lehnt ein Gerät den Start wegen fehlender Kapazität ab, kann ein anderes Gerät oder der Server übernehmen. Geht die Antwort verloren oder meldet das Gerät einen Serverfehler, bleiben Wiederholungen auf diesem Gerät: Es könnte den Arbeitsbereich bereits angelegt haben.

Sobald deine Organisation ein Gerät hat, zeigt die Liste **Arbeitsbereiche**, wo jeder Arbeitsbereich läuft: **Auf dem Server** oder auf einem Gerät mit dessen Namen. Solange ein Gerät offline ist, schlägt Arbeit, die einen seiner Arbeitsbereiche braucht, mit der Meldung fehl, dass das Gerät nicht verbunden ist. Starte sie erneut, sobald das Gerät wieder online ist; Arbeitsbereiche wechseln nie von selbst auf einen anderen Rechner.

Sandboxes auf einem Gerät erreichen das Internet über die eigene Verbindung des Rechners, und zwar über denselben Egress-Proxy wie auf dem Server. Der Proxy sperrt Adressen privater Netze, deshalb erreichen die Sandboxes keine anderen Rechner in deinem lokalen Netz.

Verbundene Geräte heben außerdem die Obergrenze für die [Arbeitslimits](https://docs.tale.dev/de/platform/admin/sandboxes#ein-arbeitslimit-aendern) deiner Organisation: Deren Summe darf die Kapazität der Bereitstellung plus die Sandboxes deiner Geräte nutzen.

## Die Geräteliste lesen

| Spalte | Was sie zeigt |
| --- | --- |
| **Gerät** | Der Name, mit dem sich der Rechner verbunden hat, und sein Betriebssystem. |
| **Status** | **Online**, **Wird aktualisiert**, **Update nötig**, **Update fehlgeschlagen** oder **Offline**. |
| **Sandboxes** | Die gerade laufenden Sandboxes und wie viele das Gerät gleichzeitig ausführt. |
| **Rechner** | CPUs und Arbeitsspeicher, die Docker auf dem Rechner nutzen kann. |
| **Version** | Das Tale-Release, mit dem das Gerät läuft. |
| **Zuletzt gesehen** | **Jetzt**, solange es verbunden ist, sonst der letzte Kontakt. |

Ein Gerät mit einem anderen Release als der Server übernimmt keine neuen Sandboxes, bis es aktualisiert ist. **Update nötig** heißt, dass sich das Gerät nicht selbst aktualisiert; **Update fehlgeschlagen** heißt, dass sein letztes automatisches Update nicht geklappt hat. Führe in beiden Fällen `tale sandbox update` auf dem Rechner aus.

## Ein Gerät vom Rechner aus betreuen

Führe diese Befehle auf dem Gerät selbst aus:

| Befehl | Was er tut |
| --- | --- |
| `tale sandbox status` | Zeigt die Verbindung, die Organisation, das Release und die gerade laufenden Sandboxes. |
| `tale sandbox logs --follow` | Verfolgt das Log des Geräts. |
| `tale sandbox update` | Bringt das Gerät sofort auf das Release des Servers, mit den aktuellen Adressen des Servers für seine Sandboxes. |
| `tale sandbox disconnect` | Entfernt das Gerät aus seiner Organisation, stoppt seine Sandboxes und löscht ihre Arbeitsbereiche vom Rechner. Mit `--keep-data` bleiben die Arbeitsbereiche erhalten. |

## Ein Gerät entfernen

Öffne in der Liste **Geräte** das Zeilenmenü des Geräts, wähle **Entfernen** und bestätige. Das Gerät führt ab sofort keine Sandboxes mehr für deine Organisation aus. Seine Arbeitsbereiche bleiben auf dem Rechner, sind von Tale aus aber nicht mehr erreichbar; ihre Agenten starten beim nächsten Lauf mit neuen Arbeitsbereichen.

Um auch den Rechner aufzuräumen, führe dort `tale sandbox disconnect` aus.

## Ein Gerät reparieren, das sich nicht verbindet

- **Der Befehl ist abgelaufen oder wurde schon verwendet.** Wähle erneut **Gerät hinzufügen**, um einen neuen Befehl zu erhalten.
- **Das Gerät ist gestartet, hat den Server aber noch nicht erreicht.** Führe auf dem Rechner `tale sandbox logs --follow` aus und prüfe, ob er HTTPS-Verbindungen zu deiner Tale-Seite aufbauen kann, auch über einen Proxy dazwischen.
- **Die Verbindung scheitert mit einem Zertifikatsfehler.** Der Rechner muss dem TLS-Zertifikat deiner Tale-Seite vertrauen. Eine Bereitstellung mit selbstsigniertem Zertifikat kann keine Geräte aufnehmen.
- **Gerät hinzufügen ist nicht verfügbar, und der Bereich sagt, dass der Sandbox-Dienst keine Geräte annimmt.** Die Bereitstellung läuft ohne ihren Geräte-Hub. Bei einer selbst gehosteten Bereitstellung schaltet ihn der Betreiber ein, wie unter [Sandbox-Geräte](https://docs.tale.dev/de/self-hosted/configuration/environment-reference#sandbox-devices) beschrieben.

# Sandbox-Kapazität verwalten
Source: https://docs.tale.dev/de/platform/admin/sandboxes

Öffne **Einstellungen > Sandboxes**, wenn Agenten oder Website-Scans keine Ausführungsumgebung erhalten. Die Seite trennt die Arbeitsgrenzen deiner Organisation von der tatsächlichen Infrastruktur des Deployments. Inhaber und Admins dürfen Limits ändern und festlegen, wann ungenutzte Arbeitsbereiche gelöscht werden. Entwickler sehen Limits und zusammengefasste Kapazität, aber keine privaten Workspace-Details.

## Das relevante Limit erkennen

| Arbeitsart | Standard | Was einen Platz belegt |
| --- | --- | --- |
| Projektagenten-Sitzungen | 2 | Ein startender oder arbeitender Agenten-Workspace, den der Agent für seine Aufgaben wiederverwendet. |
| Workflow-Sitzungen | 2 | Die Sandbox eines Workflow-Laufs. Gleichzeitige Läufe belegen getrennte Plätze. |
| Render-Sitzungen | 2 | Eine vorübergehende Sandbox zum Rendern von Seiten bei Website-Scans. |

Die Werte begrenzen gleichzeitige Arbeit, nicht die Anzahl der Aufgaben oder die Ausgaben. Ein Agent kann mehrere Aufgaben in seinem einen Workspace bearbeiten. Die Limits reservieren keine Infrastruktur: Alle Organisationen teilen sich die Deployment-Kapazität.

<Frame caption="Die Summe der drei Arbeitslimits passt sich automatisch an. Sie darf die Kapazität der Bereitstellung nicht überschreiten.">

![Der Abschnitt Organisationslimits zeigt drei bearbeitbare Sitzungslimits und ihre berechnete Summe im Verhältnis zur Kapazität der Bereitstellung.](https://docs.tale.dev/images/platform/settings-sandboxes.webp)

</Frame>

## Ein Arbeitslimit ändern

1. Prüfe die belegten Plätze der Arbeitsart und die Infrastrukturwerte darunter.
2. Gib beim passenden Limit eine ganze Zahl von 1 bis 500 ein. Die angezeigte Gesamtzahl berechnet die Summe aller drei Felder neu.
3. Halte die Summe innerhalb der Deployment-Kapazität und wähle **Speichern** im Kopfbereich. **Verwerfen** stellt die gespeicherten Werte wieder her.
4. Öffne die Seite erneut, prüfe die gespeicherten Limits und beobachte, ob neue Arbeit einen Platz erhält.

Die Standardwerte ergeben zusammen 6. Bei einer Deployment-Kapazität von 8 ist eine Summe von 8 erlaubt, 9 wird abgelehnt. Der Server prüft die Kapazität beim Speichern erneut. Der aktuelle Wert kann deshalb von der ersten Beobachtung abweichen. Die verbundenen [Geräte](https://docs.tale.dev/de/platform/admin/sandbox-devices) deiner Organisation erhöhen die Obergrenze um die Sandboxes, die sie ausführen: Mit einem Gerät, das 4 ausführt, darf die Summe 12 erreichen.

Eine Senkung betrifft künftige Starts und unterbricht keine laufende Arbeit. Sind Infrastrukturwerte nicht verfügbar, bleiben Senkungen möglich; Erhöhungen brauchen einen aktuellen Kapazitätswert. Hat der Betreiber die Kapazität unter deine bisherige Summe gesenkt, reduziere die Limits vor dem nächsten Speichern. Lassen sich bereits die Organisationsbelegungen nicht laden, bleiben die Felder gesperrt, statt bearbeitbare Standardwerte anzuzeigen.

## Die Infrastrukturwerte lesen

<Frame caption="Sandboxes der Bereitstellung zeigt die gemeinsame Belegung und Kapazität. Sandboxes deiner Organisation zählt auch Umgebungen im Leerlauf, die zur Wiederverwendung bereitstehen.">

![Die Infrastrukturkapazität zeigt die Sandbox-Anzahl aller Organisationen im Verhältnis zur Gesamtkapazität, die Sandbox-Anzahl der eigenen Organisation sowie gemessene CPU- und Speicherwerte.](https://docs.tale.dev/images/platform/sandbox-infrastructure-capacity.webp)

</Frame>

| Messwert | Bedeutung |
| --- | --- |
| Sandboxes des Deployments | Laufende und startende Umgebungen aller Organisationen im Verhältnis zur gemeinsamen Kapazität. Kubernetes betrachtet den Namespace. |
| Sandboxes deiner Organisation | Laufende und startende Umgebungen dieser Organisation, einschließlich bereitgehaltener inaktiver Umgebungen. Das ist eine Anzahl, kein weiteres Limit. |
| CPU-Auslastung des Hosts | Kürzlich genutzte und gesamte CPU-Kerne, einschließlich anderer Dienste auf dem Host. |
| Arbeitsspeicher des Hosts | Genutzter und gesamter Speicher, einschließlich anderer Dienste und unter Berücksichtigung freigebbaren Caches. |

Die Werte aktualisieren sich alle 15 Sekunden. Mit **Aktualisieren** forderst du eine neue Beobachtung an. Prüfe den Zeitstempel. Die CPU-Auslastung ist die Differenz zweier Messungen; die erste Beobachtung nach einer längeren Pause dauert etwa eine Sekunde länger. Entfernte Hosts liefern gegebenenfalls nur Gesamtwerte. Namespace-Zugriff unter Kubernetes liefert keine Host-Messungen. Nicht verfügbare Werte sind unbekannt, nicht null.

## Belegte und inaktive Workspaces unterscheiden

Inhaber und Admins können **Arbeitsbereiche** prüfen. Jede Zeile nennt den zugehörigen Agenten oder Workflow-Lauf, Laufzeitstatus, Belegungsstatus und laufende Aufgaben. Die Zustände beantworten unterschiedliche Fragen: Ein Container kann für die Wiederverwendung weiterlaufen, obwohl er seinen Organisationsplatz bereits freigegeben hat. Der Arbeitsbereich eines Projekt-Agenten bleibt auch im Leerlauf aufgeführt, als **Gestoppt** mit **Kontingent freigegeben**, bis du ihn löschst oder Tale ihn löscht: wenn ihn niemand [während der von deiner Organisation festgelegten Anzahl Tage](https://docs.tale.dev/de/platform/admin/sandboxes#delete-unused-workspaces-automatically) genutzt hat oder wenn [sein Agent, sein Projekt oder das zugehörige Mitglied entfernt wird](https://docs.tale.dev/de/platform/admin/sandboxes#explain-why-a-workspace-disappeared). Wurde der Agent selbst gelöscht, steht in der Zeile **Gelöschter Agent**, bis Tale den Arbeitsbereich gelöscht hat. Der Arbeitsbereich eines Workflow-Laufs wird kurz nach dem Ende des Laufs zurückgefordert.

Die Ausgaben enthalten die gemessenen Kosten abgeschlossener Durchläufe. Ein noch laufender Durchlauf wird nach seinem Ende eingerechnet. Vorübergehende Crawler-Umgebungen zählen zur Kapazität, auch ohne eigene dauerhafte Workspace-Zeile.

Ist die Deployment-Kapazität voll, kann Tale eine nicht angeheftete, inaktive Umgebung zurückfordern, deren Belegung freigegeben ist und die bestätigt, dass keine Arbeit mehr läuft. Die dauerhaften Workspace-Dateien bleiben für den nächsten Start erhalten. Beschäftigte, angeheftete oder nicht erreichbare Umgebungen kommen nicht infrage. Ohne geeigneten Kandidaten braucht neue Arbeit freie Kapazität. Eine Umgebung, deren Aufgabe oder Lauf beendet ist, stoppt nach einigen Minuten im Leerlauf, sodass ihr Platz bald nach dem Ende der Arbeit frei wird. Eine Agent-Umgebung, in der Docker läuft, behält ihre volle Leerlaufzeit, damit der nächste Durchgang ihre Images nicht erneut laden muss.

## Einen bestehenden Arbeitsbereich verwalten

Inhaber und Admins finden im Zeilenmenü diese Aktionen:

| Aktion | Wirkung |
| --- | --- |
| **Aufgabe stoppen** | Bricht alle laufenden Vorgänge dieses Arbeitsbereichs ab. Prüfe zuerst die Aufgabenliste; ein Agent kann mehrere Aufgaben bearbeiten. |
| **Anpinnen** / **Lösen** | Nimmt den Arbeitsbereich von der automatischen Inaktivitäts- und Ablaufbereinigung und vom Löschen wegen Nichtnutzung aus oder stellt die normale Bereinigung wieder her. Eine angeheftete Belegung kann weiter Kapazität beanspruchen. Verschwindet die Umgebung eines angehefteten Arbeitsbereichs, etwa nach einem Neustart des Hosts, startet Tale sie mit den Workspace-Dateien neu; der Arbeitsbereich bleibt angeheftet. |
| **Löschen** | Fragt nach Bestätigung und entfernt dann Sandbox und Workspace-Dateien im Hintergrund: Zuerst wird die Anheftung gelöst und laufende Arbeit abgebrochen. Bis der Arbeitsbereich entfernt ist, steht in seiner Zeile **Wird gelöscht**, und du kannst die Seite währenddessen weiter nutzen. Kann Tale ihn auch nach mehreren Versuchen nicht entfernen, bleibt der Arbeitsbereich ohne Anheftung in der Liste und zeigt **Nicht gelöscht**; wähle dann erneut **Löschen**, um ihn vollständig zu entfernen. Solange die Zeile **Wird gelöscht** zeigt, startet in diesem Arbeitsbereich nichts Neues: Der Lauf eines Agenten wartet und zeigt **Wartet auf einen Sandbox-Platz**, und ein Schritt eines Workflow-Laufs, der den Arbeitsbereich braucht, schlägt sofort mit dem Grund fehl, ohne zu warten oder es erneut zu versuchen, denn die Dateien seiner früheren Schritte werden gelöscht. Ist die Zeile verschwunden, erzeugt der nächste Start eine neue Umgebung; zeigt sie stattdessen **Nicht gelöscht**, geht die wartende Arbeit mit den alten Dateien weiter. |

Tale speichert Änderungen am Anheftstatus dauerhaft und wiederholt die Übertragung, wenn die Laufzeit sie nicht bestätigt, auch nach einem Worker-Neustart oder Geräteausfall. Jeder Versuch überträgt den zuletzt gewünschten Wert an dieselbe Session-Instanz. Wiederholtes Lösen verlängert deren Ablaufzeit nicht.

Stoppe die Aufgabe, wenn die Arbeit enden, ihre Dateien aber bleiben sollen. Sichere vor dem Löschen benötigte Ergebnisse und lies die Bestätigung. Automatische Rückgewinnung inaktiver Kapazität bewahrt Workspace-Dateien; ausdrückliches und automatisches Löschen entfernen sie.

## Ungenutzte Arbeitsbereiche automatisch löschen {#delete-unused-workspaces-automatically}

Ein Projekt-Agent bewahrt seine Dateien zwischen den Läufen in Arbeitsbereichen auf: in einem, den er für alle seine Aufgaben wiederverwendet, und in einem getrennten für jedes Mitglied, das [seine Läufe startet](https://docs.tale.dev/de/platform/projects/tasks#agentenlaeufe-die-ein-mitglied-startet). Tale löscht einen Arbeitsbereich, den niemand während der von deiner Organisation festgelegten Anzahl Tage genutzt hat; **Löschen** entfernt einen Arbeitsbereich weiterhin sofort. Inhaber und Admins legen diese Regel unter **Bereinigung der Arbeitsbereiche** fest, direkt über der Liste **Arbeitsbereiche**. Entwickler sehen diesen Abschnitt nicht.

<Frame caption="Ist Ungenutzte Arbeitsbereiche löschen eingeschaltet, löscht Tale einen Arbeitsbereich, den niemand während der festgelegten Anzahl Tage genutzt hat. Angepinnte Arbeitsbereiche bleiben erhalten.">

![Der Abschnitt Bereinigung der Arbeitsbereiche zeigt den eingeschalteten Schalter Ungenutzte Arbeitsbereiche löschen und den Wert 30 bei Tage ohne Nutzung, jeweils mit einer Erklärung ihrer Wirkung.](https://docs.tale.dev/images/platform/sandbox-workspace-cleanup.webp)

</Frame>

1. Lass **Ungenutzte Arbeitsbereiche löschen** eingeschaltet, wie es voreingestellt ist. Solange der Schalter aus ist, löscht Tale keinen Arbeitsbereich wegen Nichtnutzung.
2. Gib bei **Tage ohne Nutzung** eine ganze Zahl von 1 bis 3650 ein; voreingestellt sind 30. Die Tage zählen ab dem Zeitpunkt, an dem der Agent zuletzt im Arbeitsbereich gearbeitet hat, oder ab dem Lösen seiner Anheftung.
3. Wähle **Speichern** im Kopfbereich. **Verwerfen** stellt die gespeicherten Werte wieder her.

Nach einer Änderung wird nie ein Arbeitsbereich vorzeitig gelöscht. Schaltest du das Löschen ein oder verkürzt du den Zeitraum, wird kein Arbeitsbereich wegen Nichtnutzung gelöscht, bevor seit der Änderung die volle Anzahl Tage vergangen ist. Dieselbe Wartezeit folgt auf das Update, das die Einstellung eingeführt hat. Ein längerer Zeitraum startet die Wartezeit nicht neu, Aus- und erneutes Einschalten dagegen schon.

In der Liste **Arbeitsbereiche** zeigt ein gestoppter Agenten-Arbeitsbereich unter seinem Status, wann er gelöscht wird: **Wird am … gelöscht, falls weiterhin ungenutzt**. Ein neuer Lauf im Arbeitsbereich startet die Zählung neu. Ein angepinnter Arbeitsbereich oder einer, den ein [Legal Hold](https://docs.tale.dev/de/platform/admin/governance/legal-hold) bewahrt, zeigt kein Datum und wird nie wegen Nichtnutzung gelöscht.

## Klären, warum ein Arbeitsbereich verschwunden ist {#explain-why-a-workspace-disappeared}

Neben ungenutzten Arbeitsbereichen löscht Tale einen Arbeitsbereich auch, sobald entfernt wird, wozu er gehört, unabhängig von der Bereinigungseinstellung:

- Das Löschen eines Projekt-Agenten löscht alle seine Arbeitsbereiche, auch die der Mitglieder. Das Löschen eines Projekts tut dasselbe für jeden Agenten darin.
- [Entfernst du ein Mitglied](https://docs.tale.dev/de/platform/admin/members-and-roles#zugriff-entziehen-oder-wiederherstellen) aus der Organisation, werden seine eigenen Arbeitsbereiche mit allen Agenten gelöscht. Setzt du es stattdessen auf **Deaktiviert**, bleiben sie erhalten.
- [Die Löschung der Daten einer Person](https://docs.tale.dev/de/platform/admin/governance/data-subject-requests) entfernt ihre eigenen Arbeitsbereiche, ohne auf laufende Arbeit darin zu warten.
- Das Löschen der Organisation entfernt alle ihre Sandboxes samt Dateien, widerruft die dafür ausgegebenen Gateway-Schlüssel, trennt ihre [Geräte](https://docs.tale.dev/de/platform/admin/sandbox-devices) und löscht die für sie angelegten Build- und Paket-Caches.

Das geschieht innerhalb von etwa einer Minute oder, falls im Arbeitsbereich noch eine Aufgabe läuft, nach deren Ende. Auch ein angepinnter Arbeitsbereich wird dann gelöscht, doch ein [Legal Hold](https://docs.tale.dev/de/platform/admin/governance/legal-hold) bewahrt jeden Arbeitsbereich, den er abdeckt: Eine Sperre der Organisation bewahrt alle, eine Sperre für eine Person deren eigene Arbeitsbereiche. Eine stündliche Bereinigung löscht außerdem Überreste, die niemandem mehr gehören, etwa den Arbeitsbereich eines Workflow-Laufs, der nie zurückgefordert wurde.

Jeden Arbeitsbereich, den Tale von selbst löscht, aus einem dieser Gründe oder wegen Nichtnutzung, verzeichnet das [Audit-Log](https://docs.tale.dev/de/platform/admin/governance/audit-logs) unter **Einstellungen > Richtlinien > Protokolle** als **Sandbox-Arbeitsbereich gelöscht**. Das ist ein Systemereignis der Kategorie **Daten**, dessen Metadaten den Grund nennen: `agent_deleted`, `member_removed`, `member_erased`, `unused` oder `orphaned`. Das Ereignis wird erfasst, sobald Tale bestätigt hat, dass die Dateien des Arbeitsbereichs gelöscht sind, was bei einem großen Arbeitsbereich eine Weile dauern kann. Unter Kubernetes wird es erfasst, sobald das Volume des Arbeitsbereichs an den Storage-Provisioner des Clusters übergeben ist, der es gemäß der `reclaimPolicy` seiner StorageClass löscht; die Metadaten nennen, was geschehen ist (`deletion`: `done` oder `handed_off`). Schlägt das Löschen der Dateien fehl, erscheint das Ereignis mit dem Status **Fehlgeschlagen**, und das Löschen wird erneut versucht, bis die Dateien entfernt sind. Ein Sandbox-Dienst oder Gerät, das noch nicht auf diese Version aktualisiert ist, kann keine Löschung bestätigen: Tale erfasst für seine Arbeitsbereiche kein Ereignis und versucht es weiter, bis es aktualisiert ist. Ein Überbleibsel, das niemandem mehr gehört, kann ohne Ereignis enden: Werden seine Dateien noch gelöscht, wenn die stündliche Bereinigung weitergeht, löscht der Sandbox-Dienst sie zu Ende, doch Tale prüft sie nicht noch einmal.

## Einen blockierten Start klären

Ein Start ohne freien Platz wartet. Sind die Limits deiner Organisation belegt oder ist das Deployment voll oder knapp an Arbeitsspeicher, startet die Arbeit von selbst, sobald Platz frei wird, und du musst nichts tun. Bei Speicherplatz ist das anders: Wird ungenutzte Arbeit angehalten, wird keiner frei, denn ein angehaltener Arbeitsbereich behält seine Dateien. Tale entfernt Build-Caches, die keine Sitzung nutzt, sofern es welche gibt; reicht das nicht, wartet der Start, bis Arbeitsbereiche gelöscht werden, etwa solche, die du löschst, weil du sie nicht mehr brauchst, oder bis der Betreiber Speicherplatz freigibt. Ist das Deployment selbst voll, geht sein Platz an die Arbeit, die am längsten wartet, egal aus welcher Organisation, und jeder wartende Start erfährt, wann er an der Reihe ist:

- Ein Aufgabenlauf wartet in der Warteschlange. Er wird erneut versucht, sobald eine Sitzung endet, in deiner Organisation oder in einer anderen auf demselben Deployment. Ist das Deployment voll, wird er auch versucht, wenn er an der Reihe ist. Zusätzlich versucht Tale alle zwei Minuten einige wartende Läufe jeder Organisation, die am längsten wartenden zuerst.
- Der Agent-Schritt einer Automatisierung versucht es erneut, ohne seine Wiederholungen zu verbrauchen: wenn er an der Reihe ist, falls das Deployment voll ist, sonst nach einer Pause, die länger wird, solange der Schritt weiter wartet, bis zu etwa zwei Minuten. Der Lauf zeigt währenddessen **Wartet auf einen Sandbox-Platz**. Findet er zwei Stunden lang keinen Platz, schlägt der Lauf mit diesem Grund fehl. Ein Arbeitsbereich, den ein Administrator löscht, ist kein fehlender Platz: Der Schritt schlägt dann sofort fehl, wie oben bei **Löschen** beschrieben.
- Das Crawling wartet, bis es an der Reihe ist, und setzt dann mit dem nächsten Stapel fort.

Erhöhe ein Arbeitslimit nur, wenn seine Plätze belegt sind und die neue Summe in die gemeinsame Kapazität passt. Ist das Deployment voll, schafft ein höheres Organisationslimit keine Infrastruktur. Für eigene Kapazität [verbindest du ein Gerät](https://docs.tale.dev/de/platform/admin/sandbox-devices): Neue Arbeitsbereiche starten dann darauf. Andernfalls lass den Betreiber Kapazität und Host-Ressourcen prüfen. Ein freier Containerplatz garantiert noch nicht genügend CPU, Arbeitsspeicher oder Speicherplatz.

Bei Zugangs- oder Modellproblemen hilft [KI-Provider](https://docs.tale.dev/de/platform/admin/providers), bei Ausgabengrenzen [Richtlinien und Limits](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits). Self-Hosted-Betreiber finden die Deployment-Einstellung in der [Umgebungsreferenz](https://docs.tale.dev/de/self-hosted/configuration/environment-reference#sandbox-infrastructure).

# Teams
Source: https://docs.tale.dev/de/platform/admin/teams

Ein Team ist eine Markierung an der Arbeit, kein Ort, in den du wechselst. Ein Dokument, ein Ordner oder ein Projekt trägt die Teams, die es sehen dürfen, und eine Konversation kann in der Warteschlange eines Teams warten. Die Rolle bestimmt, was jemand tun darf; die Teams entscheiden, welche eingeschränkte Arbeit die Person erreicht. Inhaber und Admins verwalten Teams unter **Einstellungen > Teams**.

<Frame caption="Einstellungen > Teams — jedes Team der Organisation mit seiner Mitgliederzahl, neben der Aktion Team erstellen.">

![Die Teams-Einstellungsseite listet drei Teams — Customer success, Growth und Platform engineering —, jedes mit einem Mitglied und dem Zeitpunkt, an dem es hinzugefügt wurde, neben der Schaltfläche Team erstellen.](https://docs.tale.dev/images/platform/settings-teams.webp)

</Frame>

## Ein Team erstellen

1. Wähle **Team erstellen** und fülle das Feld **Teamname** aus, etwa `Kundensupport`.
2. Wähle die Mitglieder der Organisation aus, die dazugehören sollen. Wenn du niemanden auswählst, fügt Tale dich selbst hinzu.
3. Wähle **Team erstellen**. Prüfe den neuen Eintrag und die Mitgliederzahl in der Liste.

Wähle einen Namen, den andere überall wiedererkennen, wo Teams erscheinen: in der Reichweite eines Dokuments oder Projekts, als Warteschlange im Posteingang, in einem Listenfilter. Das Formular erlaubt bis zu 80 Zeichen. Ein Name ist innerhalb der Organisation eindeutig: Einen Namen, den ein anderes Team bereits verwendet – unabhängig von Groß- und Kleinschreibung oder Leerzeichen –, lehnt Tale ab. Ein neues Team erhält nicht automatisch bestehende Arbeit. Wähle es bei den Dokumenten, Projekten und Konversationen aus, die es abdecken soll.

## Mitglieder oder Namen ändern

Öffne die Zeile eines Teams, um seine Mitglieder zu sehen. Das Zeilenmenü bietet **Anzeigen**, **Bearbeiten** und **Löschen**. Unter **Bearbeiten** änderst du Namen oder Mitgliedschaft. Speichere und prüfe anschließend die Mitgliederzahl.

Ein Team behält mindestens ein Mitglied. Um das letzte zu entfernen, lösche stattdessen das Team.

Eine Person kann mehreren Teams angehören. Ihr Zugriff kann über weitere Teams oder eine direkte Zuweisung bestehen bleiben. Das Entfernen aus einem Team entzieht daher nicht zwangsläufig jeden Zugriff auf eine Ressource. Prüfe die übrigen Zugangswege, wenn du Rechte entziehen möchtest.

Benachrichtigungen folgen derselben Regel. Wer ein Projekt nicht mehr öffnen kann, erhält zu dessen Aufgaben keine neuen Benachrichtigungen oder E-Mails mehr, auch nicht zu Aufgaben, die die Person verfolgt. Was sie bereits erfahren hat, bleibt in ihren Benachrichtigungen. Erhält sie wieder Zugriff, wird sie zu den Aufgaben, die sie verfolgt, wieder benachrichtigt.

Ein Team, das dein Identity Provider bereitstellt, trägt in der Liste die Markierung **Synchronisiert**. Name und Mitglieder gehören dem Anbieter: Der Bearbeitungsdialog zeigt sie nur an, weil der nächste Abgleich eine lokale Änderung zurücksetzen würde. Löschen kannst du ein solches Team trotzdem; der Anbieter kann es erneut anlegen.

<Tip>

Benenne ein bestehendes Team um, wenn sich sein Zweck ändert, dieselben Personen aber ihren Zugang behalten sollen. Löschen und Neuanlegen erzeugt ein anderes Team und verändert bestehende Ressourcenzuweisungen.

</Tip>

## Was ein Team entscheidet

Für jede teamgebundene Ressource gilt dieselbe Regel. Eine Ressource ohne Team sehen alle in der Organisation. Eine Ressource mit Teams sehen die Mitglieder eines dieser Teams. Inhaber und Admins sehen in beiden Fällen alles; ein Team ist deshalb kein Mittel, um Arbeit vor der Administration zu verbergen.

| Ressource | Bedeutung des Teams |
| --- | --- |
| Projekte | **Reichweite** unter **Allgemein** nennt die Teams, die das Projekt öffnen können; leer bedeutet die ganze Organisation. |
| Dokumente und Ordner | Ein Dokument oder Ordner trägt die Teams, die es lesen dürfen. Was in einem Team-Ordner abgelegt wird, übernimmt dessen Teams und kann kein Team außerhalb davon nennen. |
| Skills | Teamsichtbarkeit stellt einen Skill den ausgewählten Teams bereit. |
| Konversationen | Die Teamzuweisung legt die Konversation in die Warteschlange dieses Teams. |

Wenn du Arbeit auf Teams beschränkst, kannst du nur Teams wählen, denen du selbst angehörst; Inhaber und Admins wählen jedes Team der Organisation. Eine Teammitgliedschaft erlaubt keine Aktionen, die die Rolle verbietet: Ein Redakteur und ein Mitglied im selben Team können unterschiedliche Bearbeitungsrechte haben.

Mitglieder sehen ihre eigenen Teams unter **Einstellungen > Konto > Deine Teams** und in der Zeile **Teams** des Profilmenüs. Um eine Liste auf bestimmte Arbeit einzugrenzen, bietet jede Liste einen Filter **Teams** mit **Organisationsweit**, **Meine Teams** und jedem Team nach Namen; der Posteingang nutzt stattdessen den Filter **Zuständig**, der Personen wie Teams aufführt. Siehe [Konto verwalten](https://docs.tale.dev/de/platform/member/preferences#teams).

Bei eingehenden Konversationen können [Routing-Regeln](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits#konversations-routing) das Team bereits beim Eingang auswählen. Ohne Personen- oder Teamzuweisung bleibt die Konversation bei der Administration zur Sichtung.

## Ein Team geordnet auflösen

Wähle **Löschen** im Zeilenmenü. Die Bestätigung zählt die Mitglieder des Teams, die Projekte, Ordner und Dokumente, zu deren Reichweite es gehört, und die Konversationen in seiner Warteschlange. Sie nennt außerdem, wie viele dieser Elemente kein weiteres Team haben und für alle in der Organisation sichtbar werden. Weise Arbeit, deren Zugriff eingeschränkt bleiben muss, vor dem Bestätigen neu zu.

<Warning>

Das Löschen eines Teams lässt sich nicht rückgängig machen. Jedes Projekt, jeder Ordner und jedes Dokument verliert das Team und behält seine übrigen Teams. Ein Element, dessen einziges Team es war, wird organisationsweit sichtbar. Dadurch können mehr Personen Zugriff erhalten.

</Warning>

Das Team, seine Mitgliedschaften, seine Einträge an jeder Ressource und eine Verknüpfung zum Identity Provider verschwinden in einem Schritt; ein halb gelöschtes Team kann nicht zurückbleiben. Eine Konversation verliert ihre Teamzuweisung. Ist auch keine Person zugewiesen, kehrt sie zur Sichtung durch die Administration zurück. Auch Dateiimporte verlieren diesen Teambezug. Die Konten der Teammitglieder werden nicht gelöscht.

Bei Teams aus [Enterprise SSO oder SCIM](https://docs.tale.dev/de/platform/admin/enterprise-sso) gelten zusätzlich die Bereitstellungsregeln des Identitätsanbieters. Prüfe diese Quelle, bevor du eine lokale Änderung vornimmst, die dauerhaft gelten soll.

# Zwei-Faktor-Authentifizierung
Source: https://docs.tale.dev/de/platform/admin/two-factor-authentication

Sichere dein Konto mit einer Authenticator-App oder einem Passkey. Mitglieder richten ihre Anmeldemethoden unter **Einstellungen > Konto** ein. Admins können einen zweiten Faktor verlangen und Mitgliedern helfen, wieder Zugang zu bekommen.

## Eine Anmeldemethode wählen

| Methode | Was du brauchst | So meldest du dich an |
| --- | --- | --- |
| Authenticator-App | Ein Tale-Passwort und eine App für zeitbasierte Codes (TOTP) | Gib dein Passwort und danach den sechsstelligen Code aus der App ein. |
| Passkey | Ein geeignetes Gerät oder einen Sicherheitsschlüssel | Bestätige die Browserabfrage mit deinem Gerät oder Schlüssel. Das geht auch nach der Anmeldung mit Passwort. |
| Backup-Code | Einen gespeicherten Code aus der Authenticator-Einrichtung | Verwende ihn einmal anstelle des Authenticator-Codes, wenn du die App nicht nutzen kannst. |

Ein Passkey erfüllt Tales Zwei-Faktor-Richtlinie auch ohne eingerichteten Authenticator. Bei Konten, die sich ausschließlich per SSO anmelden, fehlt die Authenticator-Einrichtung: Sie setzt ein Tale-Passwort voraus. Die SSO-Ausnahme deiner Organisation bestimmt, ob du einen Tale-Passkey brauchst.

<Frame caption="Unter Einstellungen > Konto findest du dein Passwort, die Zwei-Faktor-Authentifizierung und deine Passkeys. Hier richtest du den Authenticator ein oder registrierst einen weiteren Passkey.">

![Die Kontoeinstellungen mit den Abschnitten Passwort, Zwei-Faktor-Authentifizierung und Passkeys; unter Passkeys ist ein Passkey namens „Work laptop“ aufgeführt.](https://docs.tale.dev/images/platform/settings-account-security.webp)

</Frame>

## Einen Authenticator einrichten

1. Öffne **Einstellungen > Konto**, gehe zu **Zwei-Faktor-Authentifizierung** und wähle **Zwei-Faktor aktivieren**.
2. Gib dein aktuelles Tale-Passwort ein und wähle **Bestätigen**. Ein falsches Passwort zählt wie eine fehlgeschlagene Anmeldung zur vorübergehenden Sperre.
3. Scanne den QR-Code mit deiner Authenticator-App. Falls das nicht geht, gib den angezeigten Einrichtungsschlüssel manuell in der App ein.
4. Gib den aktuellen sechsstelligen Code unter **Bestätigungscode** ein und wähle **Prüfen und aktivieren**.
5. Lade die Backup-Codes herunter oder kopiere sie, bevor du **Fertig** wählst. Tale zeigt sie später nicht noch einmal an.

Auf der Kontoseite steht jetzt, dass Zwei-Faktor-Authentifizierung aktiv ist. Bei der nächsten Anmeldung mit Passwort gibst du einen Code aus demselben Authenticator-Eintrag ein.

<Tip>
Bewahre Backup-Codes so auf, dass du sie auch ohne dein Anmeldegerät erreichst, etwa in einem Passwortmanager auf einem weiteren vertrauenswürdigen Gerät.
</Tip>

## Einen Passkey hinzufügen

1. Öffne **Einstellungen > Konto**, gehe zu **Passkeys** und wähle **Passkey hinzufügen**.
2. Liegt deine Anmeldung mehr als einen Tag zurück, fragt Tale zuerst nach deinem Passwort. Gib es unter **Passwort** ein und wähle **Bestätigen**. Ein falsches Passwort zählt wie eine fehlgeschlagene Anmeldung zur vorübergehenden Sperre.
3. Trage unter **Passkey-Name** einen Namen ein, den du wiedererkennst, etwa `Arbeitslaptop`.
4. Lass **Authenticator-Typ** auf **Beliebig (empfohlen)**, damit der Browser alle verfügbaren Möglichkeiten anbietet. Alternativ wählst du den eingebauten Authenticator oder einen Sicherheitsschlüssel beziehungsweise ein Smartphone.
5. Wähle **Passkey hinzufügen** und bestätige die Browserabfrage.

Der Passkey erscheint in deiner Kontoliste. Wähle auf der Anmeldeseite **Mit einem Passkey anmelden**. Nach einer Passwortanmeldung kannst du auf der Bestätigungsseite auch **Stattdessen einen Passkey verwenden** wählen.

Um einen Passkey nicht mehr zu verwenden, wähle bei ihm **Entfernen** und bestätige. War er dein einziger zweiter Faktor und verlangt deine Organisation einen, musst du einen neuen einrichten.

## Zugang wiederherstellen und Codes ersetzen

Wähle auf der Bestätigungsseite **Stattdessen einen Backup-Code verwenden** und gib einen gespeicherten Code ein. Jeder Code funktioniert einmal. Brauchst du danach neue Codes, öffne **Einstellungen > Konto** und wähle **Backup-Codes neu erzeugen**. Bestätige dein Passwort und sichere die neuen Codes. Dadurch werden alle bisherigen Codes ungültig, auch unbenutzte.

Wird ein Code abgelehnt, prüfe den Authenticator-Eintrag für dieses Tale-Konto, verwende den aktuellen Code und kontrolliere die Geräteuhr. Wiederholte Fehlversuche können die Bestätigung vorübergehend sperren. Folge dann der angezeigten Meldung, statt weitere Codes einzureichen.

Hast du weder Authenticator noch Passkey oder Backup-Code zur Hand, wende dich an einen Admin deiner Organisation. Schicke ihm weder dein Passwort noch den Einrichtungsschlüssel oder übrige Codes.

## Einen zweiten Faktor für die Organisation verlangen

Admins richten die Richtlinie unter **Einstellungen > Richtlinien > Sicherheit** ein. Lege vorher einen Kontakt für Zugangsprobleme fest und gib den Mitgliedern Zeit, eine Methode einzurichten.

<Frame caption="Die Sicherheitseinstellungen enthalten Passwort-, Anmelde- und Zwei-Faktor-Richtlinien. Scrolle für die Einrichtungspflicht zu Zwei-Faktor-Authentifizierung.">

![Sicherheitseinstellungen mit Anmeldelimits und Passwortanforderungen oberhalb der Zwei-Faktor-Richtlinie.](https://docs.tale.dev/images/platform/governance-security-monitoring.webp)

</Frame>

| Einstellung | Wirkung |
| --- | --- |
| **Zwei-Faktor-Authentifizierung verlangen** | Aktiviert die Pflicht nach einer Bestätigung. Ein registrierter Passkey oder Authenticator erfüllt sie. |
| **Übergangsfrist (Tage)** | Zeit für die Einrichtung ab der ersten Anmeldung des Mitglieds unter dieser Richtlinie. Null verlangt sie sofort. |
| **Nur-SSO-Benutzer ausnehmen** | Mitglieder ohne Tale-Passwort verlassen sich auf die Anmeldung ihres Identitätsanbieters. |

Während der Übergangsfrist sehen Mitglieder eine Erinnerung. Danach sperrt Tale den Organisationszugang, bis sie eine Methode einrichten: Die Einrichtungsseite fragt nach ihrem Passwort, um einen Authenticator einzurichten, oder bietet **Stattdessen einen Passkey registrieren** an. Wer schon länger als einen Tag angemeldet ist, bestätigt vor der Passkey-Abfrage sein Passwort. Wer sich nur per SSO anmeldet, wählt zuerst **Erneut anmelden**. Deinen eigenen Authenticator zu deaktivieren, hebt die Richtlinie nicht auf.

## Einem ausgesperrten Mitglied helfen

Prüfe zuerst die Identität der Person nach dem Wiederherstellungsprozess deiner Organisation. Öffne dann **Einstellungen > Mitglieder**, bearbeite das Mitglied und wähle **Zwei-Faktor zurücksetzen**. Die Bestätigung entfernt die Authenticator-Einrichtung und beendet alle aktiven Sitzungen. Die Person kann sich erneut anmelden und einen neuen Authenticator einrichten. Gilt die Pflicht, muss sie die Einrichtung abschließen, bevor sie weiterarbeiten kann.

Ist ein Passkey verloren gegangen, entferne stattdessen diesen Eintrag im Abschnitt **Passkeys** des Mitglieddialogs. Auch das beendet alle Sitzungen des Mitglieds. Die Wiederherstellungsaktionen findest du in den [Audit-Logs](https://docs.tale.dev/de/platform/admin/governance/audit-logs).

# Projektagenten verstehen
Source: https://docs.tale.dev/de/platform/agents/concepts

Ein Projektagent bearbeitet Aufgaben in einem bestimmten Projekt. Du legst fest, wie er arbeitet und worauf er zugreifen darf, und gibst ihm eine Aufgabe mit einem prüfbaren Ergebnis. In seiner Sandbox kann er Dateien bearbeiten und Befehle ausführen. Der [festgelegte Prüfer](https://docs.tale.dev/de/platform/projects/tasks#review-default), eine Person oder ein unabhängiger Projektagent, prüft das Ergebnis vor dem Abschluss der Aufgabe. Neue Prüfungen, die menschliche Unabhängigkeit oder Kompetenznachweise voraussetzen, gehen in die menschliche Prüferkette; eine bereits einem Agenten zugewiesene Prüfung muss ausdrücklich an eine berechtigte Person übertragen werden.

## Die passende Arbeitsform wählen

| Arbeitsform | Geeignete Arbeit | Was du festlegst |
| --- | --- | --- |
| Chat | Fragen stellen, Wissen abrufen oder einen Text entwerfen. | Nachricht, Modell und gegebenenfalls Projektkontext. |
| Projektagent | Ein Repository prüfen, Dateien erstellen oder eine Aufgabe über mehrere Durchläufe bearbeiten. | Einen wiederverwendbaren Agenten im Projekt. |
| Automatisierung | Festgelegte Schritte ausführen, auf Ereignisse reagieren oder zwischen Aktionen eine Freigabe einholen. | Einen versionierten Workflow und seine Eingaben. |

Auch ein Projektchat verwendet den eingebauten Chat-Assistenten. Die Wahl eines Projekts im Chat aktiviert keinen Projektagenten. Eine Agent-Node in einer Automatisierung hat wiederum ihre eigene Konfiguration.

## Eine klare Verantwortung festlegen

Beginne mit einer Verantwortung, deren Ergebnis du beurteilen kannst, etwa: „Prüfe Änderungen auf Regressionen und belege deine Befunde.“ Das gehört in die dauerhaften Anweisungen des Agenten. Das konkrete Repository, Dateien, Abnahmekriterien und einen Termin beschreibst du in der jeweiligen Aufgabe.

Ein Agent gehört genau einem Projekt. Wer das Projekt lesen darf, sieht seine Agenten; wer es bearbeiten darf, kann sie im aktiven Projekt verwalten. Namen müssen innerhalb des Projekts eindeutig sein. Bis zu 50 Agenten sind möglich. Ein anderes Projekt braucht eine eigene Konfiguration, auch bei gleichem Namen und gleichen Anweisungen. Ein Projekt ohne eigene Agenten steht trotzdem nicht ohne da: Sofern ein Admin ihn nicht ausgeschaltet hat, übernimmt der [Standard-Agent](https://docs.tale.dev/de/platform/projects/project-agents#standard-agent) der Organisation seine Aufgaben, mit Einstellungen, die ein Admin für die ganze Organisation wählt.

## Die Konfiguration verstehen

| Bestandteil | Was er bestimmt | Beispiel für deine Entscheidung |
| --- | --- | --- |
| Harness | Das Coding-Programm, das die Sitzung in einer Sandbox ausführt. | Wähle eine Laufzeit, die zum verfügbaren Zugang passt. |
| Modell und Provider | Das aufgerufene Modell und den bereitstellenden Provider. | Wähle eine für die Arbeit freigegebene Kombination. |
| Anweisungen | Wiederverwendbare Verantwortung und Arbeitsregeln, bis zu 20.000 Zeichen. | Verlange Belege und einen Bericht über durchgeführte Prüfungen. |
| Skills | Anweisungs-Bundles und ergänzende Dateien. | Ordne die Review-Checkliste des Teams zu. |
| Connectors und Tools | Verbundene Dienste und erlaubte Plattformoperationen. | Vergib Repository-Zugriff und nur die benötigten Aufgaben-Tools. |
| Secrets | Benannte Zugangsdaten der Organisation für die laufende Sitzung. | Nutze ein eng begrenztes Token für einen Dienst ohne Connector. |

Die Listen für Skills, Connectors, Tools und Secret-Namen erlauben jeweils bis zu 25 Einträge. Ein freigegebenes Schreib-Tool darf im Rahmen seiner Zugriffsregeln Daten ändern. Eine Anweisung zu vorsichtigem Vorgehen entzieht diese Berechtigung nicht. Nur Inhaber oder Admins dürfen Secret-Zuordnungen ändern.

```mermaid
flowchart LR
    P[Projektaufgabe und Abnahmekriterien] --> A[Konfigurierter Agent]
    H[Harness und Modell] --> A
    I[Dauerhafte Anweisungen] --> A
    E[Skills, Connectors, Tools und Secrets] --> A
    A --> R[Bericht und Dateien zur Prüfung]
```

## Vor der Zuweisung die Voraussetzungen prüfen

Die Provider-Zugangsdaten müssen zur gewählten Laufzeit und zum Modell passen. Außerdem muss Sandbox-Kapazität verfügbar sein. Eine erfolgreiche Chat-Antwort belegt diese Voraussetzungen nicht. Beschreibe in der Aufgabe das erwartete Ergebnis und füge das zu prüfende Material hinzu.

Sind diese Entscheidungen getroffen, [erstelle einen Projektagenten](https://docs.tale.dev/de/platform/projects/project-agents). Die [Aufgaben-Automatisierung](https://docs.tale.dev/de/platform/projects/task-automation) erklärt Start, Steuerung und Prüfung seiner Arbeit.

# Eine Agent-Laufzeit wählen
Source: https://docs.tale.dev/de/platform/agents/harnesses

Ein Harness ist das Coding-Programm, das die Sitzung eines Agenten in einer Sandbox ausführt. Es fragt das Modell nach nächsten Schritten, liest und schreibt Dateien, führt Befehle aus und liefert einen Bericht. Du wählst es für Projektagenten oder eine `agent`-Node einer Automatisierung. Die normale Modellauswahl im Chat wählt keinen Harness.

## Laufzeit wählen und Zugriff prüfen

Öffne im Tab **Agenten** eines Projekts einen Agenten und wähle die **Agent-Laufzeit**. Bei einer Agent-Node heißt das Feld **Harness**. Wähle danach Modell und Provider. Unter **Einstellungen > KI-Anbieter** zeigt **Agent-Laufzeiten**, welche Ausführungswege der Organisation derzeit zur Verfügung stehen.

Die Laufzeit braucht passende Zugangsdaten und [Sandbox-Kapazität](https://docs.tale.dev/de/platform/admin/sandboxes). Ein funktionierendes Chat-Modell genügt nicht. Fehlt die Laufzeit oder bietet sie keine Modelle an, prüfe ihren Status und die Provider-Zugangsdaten, bevor du den Aufgabenauftrag änderst. Ein Modell, das Tools nur über die Responses-API von OpenAI aufruft, etwa GPT-6 Astra oder GPT-6.1 Sol, läuft nur auf Codex; für andere Laufzeiten bietet die Modellauswahl es deshalb nicht an.

## Unterstützte Laufzeiten vergleichen

„Verwaltet“ bedeutet, dass die Laufzeit Tale über das Modell-Gateway aufruft. „Direkt“ bedeutet, dass die Sitzung Zugangsdaten für die Werkzeuge des Providers erhält. Die mitgelieferten Definitionen unterstützen die folgenden Kombinationen; tatsächlich verfügbar ist, was Deployment und Zugangsdaten erlauben.

| Harness | Zugangsweg | Neue Anweisungen im laufenden Prozess | MCP-Kanal von Tale |
| --- | --- | --- | --- |
| Claude Code | Verwaltet oder direkt | Ja | Ja |
| Codex | Verwaltet oder direkt | Nein | Ja |
| Cursor | Nur direkt | Nein | Nein |
| Gemini CLI | Verwaltet oder direkt | Nein | Ja |
| Hermes | Verwaltet oder direkt | Nein | Nein |
| OpenClaw | Verwaltet oder direkt | Nein | Ja |
| OpenCode | Nur verwaltet | Nein | Ja |
| Pi | Verwaltet oder direkt | Nein | Nein |
| Qwen Code | Verwaltet oder direkt | Nein | Ja |

**Claude Code (compact prompt)** ist eine zusätzliche Wahl für klar abgegrenzte Workflows mit vollständigen Aufgabenanweisungen. Die Variante kürzt die eingebauten Anweisungen und einige Werkzeugbeschreibungen. Werkzeuge, Hooks, MCP und die von Tale ergänzten Hinweise bleiben erhalten. Prüfe Ergebnisse und Laufzeit mit deinem Modell, bevor du die Variante einsetzt; ein kürzerer Prompt garantiert keinen schnelleren Durchlauf. Mit **Claude Code** verwendest du beim nächsten neuen Durchlauf wieder den vollständigen Prompt. Ein auf Claude Code beschränktes Provider-Abonnement unterstützt die kompakte Variante nicht automatisch.

Kommentiere eine Projektaufgabe und erwähne ihren Agenten, um die Arbeit zu lenken. Claude Code erhält den Hinweis beim nächsten Werkzeugübergang. Bei den anderen Laufzeiten beendet Tale den aktuellen Prozess und setzt dieselbe Unterhaltung mit dem Kommentar in einem neuen Prozess fort. Deshalb kann ein laufender Prozess nach einer neuen Anweisung neu starten.

Gemini CLI ist die Ausnahme: Tale setzt eine seiner Unterhaltungen nie fort. Ein späterer Kommentar, ein automatischer neuer Versuch oder die Antwort auf eine Frage des Agenten beginnt eine neue Unterhaltung im selben Arbeitsbereich, in der die Aufgabenbeschreibung und die bisherigen Runden erneut mitgegeben werden, weil die Laufzeit eine Unterhaltung mit einem Werkzeugaufruf nicht wiederaufnehmen kann. Dateien und Ausgaben bleiben erhalten; nur die Unterhaltung beginnt von vorn.

## Zugangsdaten und Kosten verstehen

Bei einem gespeicherten API-Schlüssel oder einer Deployment-Umgebungsvariable stellt Tale einen sitzungsgebundenen Gateway-Schlüssel bereit. Der ursprüngliche Modell-Provider-Schlüssel bleibt bei der Plattform. Gateway-Aufrufe werden gemessen und unterliegen den geltenden Ausgabenregeln. Bereits an andere laufende Durchläufe vergebene Beträge werden berücksichtigt.

Provider-Abonnements verwenden ihren unterstützten Harness und erhalten den Abonnement-Zugang in der Sitzungsumgebung. Sie dienen weder als normale Chat-Zugangsdaten noch für inkompatible Harnesses, weil die Anbieter Abo-Tokens nur in ihrer eigenen Laufzeit erlauben; mehr dazu unter [KI-Anbieter](https://docs.tale.dev/de/platform/admin/providers#abos-in-aufgaben-nutzen-nicht-im-chat). Ihre direkten Aufrufe umgehen die Kostenmessung und Ausgabengrenzen des Tale-Gateways. Prüfe die Nutzung beim Abonnement-Provider.

Diese Regeln für Modellzugänge bedeuten nicht, dass die Sandbox keinerlei Geheimnisse enthält. Ausdrücklich vergebene **Secrets** sowie ein Token für einen zugeordneten GitHub-Zugang können darin verfügbar sein. Vergib nur den für die Aufgabe nötigen Zugriff.

## Dateien und verbundene Werkzeuge verstehen

Ein Projektagent verwendet seinen dauerhaften Workspace über mehrere Aufgaben hinweg. Aufgabenanhänge liegen schreibgeschützt unter `/agent/inputs/<task>/attachments/`. Dateien aus `/agent/output/<task>/` werden am Ende des Durchlaufs als **Ergebnisdateien** an die Aufgabe angehängt. Agent-Nodes sammeln ihre Ausgabe aus `/agent/output/`.

Zugeordnete Skill-Bundles liegen als Dateien vor und werden in den Laufanweisungen genannt. Prüfe ihre Anweisungen und Skripte vor der Freigabe. [Skills für Agenten](https://docs.tale.dev/de/platform/agents/skills) erklärt Bereitstellung und Sichtbarkeit.

Jede Laufzeit findet außerdem den integrierten Skill `visual-aspect-analyzer` unter ihren eigenen Skills, ohne dass du ihn zuordnen musst. Er steuert einen echten Browser über eine fertige UI-Änderung und meldet Layoutverschiebungen, Flackern und andere visuelle Regressionen. Ein gleichnamiger Skill in den Ordnern `.claude/skills` und `.agents/skills` des Repositorys im Workspace ersetzt ihn in jeder Laufzeit, die Skills aus einem Repository liest.

Der Connector-Broker hält gewöhnliche Connector-Zugangsdaten bei Tale und gibt Aktionsergebnisse zurück. Er bietet Agenten Leseaktionen an und lehnt Schreibaktionen über diesen Weg ab. Verwende für einen kontrollierten Connector-Schreibvorgang eine entsprechende Automatisierungs-Node. GitHub-Werkzeuge und ausdrücklich vergebene Secrets haben eigene Zugangswege. Die Lesebeschränkung des Brokers verbietet deshalb nicht allgemein Schreibzugriffe aus der Shell.

Agenten mit dem MCP-Kanal von Tale können außerdem abfragen, welches Tale-Release die Plattform meldet. Neben den Plattform-Tools, die dem Agenten vergeben wurden, liefert `workspace_status` den Wert `platform.version`: die Release-Nummer, die der Build des antwortenden Backends trägt, zum Beispiel `0.5.64` für das Release mit dem Tag `v0.5.64`. Für diesen Wert liest das Backend nichts aus der Anfrage. Ein Build ohne Release-Nummer, etwa ein Entwicklungsbuild, liefert stattdessen `null` mit einem kurzen Hinweis. Behandle den Wert als Kennzeichnung, nicht als Nachweis, denn jeder Build kann eine Release-Nummer tragen. Er beschreibt zudem nur dieses Backend und zeigt nicht, ob der Rest des Deployments funktioniert. Wie es um die Dienste des Deployments steht, zeigt die [Statusseite](https://docs.tale.dev/de/develop/status-page).

Ausgehender Netzwerkzugriff erlaubt normalerweise Paketinstallationen und das Klonen von Repositorys, blockiert aber private Adressen und Cloud-Metadatenziele. Betreiber können die erlaubten Hosts weiter begrenzen. Prüfe bei einem unerreichbaren Dienst die Netzwerkregeln, statt unmittelbar falsche Zugangsdaten anzunehmen.

Die integrierten Dokument-Skills `docx`, `pptx`, `xlsx` und `pdf` finden die Bibliotheken, die sie aufrufen, in der Sandbox bereits installiert vor. Ein Agent, dem sie zugeordnet sind, erstellt und liest Word-, PowerPoint-, Excel- und PDF-Dateien deshalb auch dort, wo Paketinstallationen gesperrt sind. Ihre Anweisungen enthalten weiterhin Installationsbefehle wie `npm install -g docx`; ist die Registry gesperrt, schlägt dieser Schritt fehl, die vorinstallierte Bibliothek bleibt aber verfügbar. Texterkennung (OCR) für gescannte PDFs ist nicht enthalten.

## Das Ergebnis prüfen

Die Laufzeit entscheidet, wann ihr Durchlauf fertig ist; Tale sammelt Bericht und Ausgabe. Lies beides, bevor du die Aufgabe abschließt. Prüfe, welche Tests tatsächlich liefen und welche Dienste in der Sandbox fehlten. [Aufgaben-Automatisierung](https://docs.tale.dev/de/platform/projects/task-automation) erklärt die Prüfung von Projektarbeit; [Ausführungsprotokolle](https://docs.tale.dev/de/platform/automations/execution-logs) erklärt Ergebnisse einer Agent-Node.

Kann die Laufzeit gar nicht starten — eine Konfiguration, die sie ablehnt, ein Zustandsverzeichnis, das sie nicht findet —, schlägt der Lauf sofort fehl, und seine Begründung zitiert die letzten Zeilen, die die Laufzeit geschrieben hat: Die Ursache wird benannt, nicht nur ein Exit-Code. Ein solcher Lauf wird nicht automatisch wiederholt; behebe die Ursache und wiederhole ihn dann.

# Agenten mit Skills ausrüsten
Source: https://docs.tale.dev/de/platform/agents/skills

Rüste einen Agenten mit einem Skill aus, wenn er ein wiederverwendbares Vorgehen oder Referenzmaterial aus der [Skill-Bibliothek](https://docs.tale.dev/de/platform/workspace/skills) der Organisation braucht. Die Bibliothek speichert das Bundle; die Ausrüstung des Agenten bestimmt, welche Bundles seinen Läufen zur Verfügung stehen.

## Einen Skill für die Aufgabe wählen

Ein hilfreicher Skill erklärt, wann er gebraucht wird, wie die Arbeit abläuft und woran ein gutes Ergebnis erkennbar ist. Rüste zum Beispiel den Agenten für Release Notes mit dem passenden Skill aus. Gib ihm einige Änderungen und prüfe, ob sein Ergebnis dem erwarteten Format entspricht.

Das Bundle enthält `SKILL.md` und kann Referenzen, Dateien oder Skripte mitbringen. Beim Import werden diese Dateien nicht ausgeführt. Nach dem Ausrüsten können die Anweisungen jedoch einen Coding-Agenten mit Shell oder anderen Werkzeugen dazu anleiten, ein enthaltenes Skript auszuführen. Prüfe daher das gesamte Bundle vor der Verwendung. Ein Skill bildet keine zusätzliche Berechtigungsgrenze.

## Einen Projekt-Agenten ausrüsten

Öffne den [Projekt-Agenten](https://docs.tale.dev/de/platform/projects/project-agents) und wähle die benötigten Skills in seiner Ausrüstung. Die Liste richtet sich nach dem Zugriff des Projekts, auch wenn du persönlich mehr Skills lesen kannst:

| Projektzugriff | Verfügbare Skills |
| --- | --- |
| Organisationsweites Projekt | Organisationsweite Skills |
| Mit Teams geteiltes Projekt | Organisationsweite Skills sowie Team-Skills, die mit mindestens einem Team des Projekts geteilt sind |

Alte private Skills können nicht für einen Projekt-Agenten ausgewählt werden. Dieselbe Zugriffsregel wird beim Start einer Aufgabe geprüft. Die Auswahl eines Skills gewährt dem Projekt keinen dauerhaften Zugriff darauf.

Bei einem neuen Projekt-Agenten sind die Dokument-Skills `docx`, `pptx`, `xlsx` und `pdf` vorausgewählt, sofern das Projekt auf sie zugreifen kann. Entferne die Häkchen bei Skills, die die Aufgabe nicht braucht.

Jeder Skill in der Liste nennt seinen Ersteller: ein Mitglied, **Mitgeliefert** für die Skills, mit denen deine Organisation startet, oder **Konfigurations-Release** mit dem Mitglied, dessen Upload ihn installiert hat. Prüfe bei einem unbekannten Skill, woher er stammt, bevor du einen Agenten damit ausrüstest.

## Skills in einer Automation verwenden

Die Agent-Knoten einer Automation geben an, welche Skills sie brauchen. Ein an ein Projekt gebundener Lauf nutzt dessen Zugriff. Ein Lauf auf Organisationsebene kann nur organisationsweite Skills verwenden. Deine persönliche Mitgliedschaft in weiteren Teams erweitert diesen Zugriff nicht.

Beim Einrichten der Sandbox stellt Tale die ausgerüsteten Bundles als Dateien bereit. Der Agent erhält zu jedem Skill einen Beschreibungsauszug von bis zu 300 Zeichen und den Pfad zu seinen `SKILL.md`-Anweisungen. Der Auszug hilft bei der Auswahl für eine frei formulierte Aufgabe; er ist ein Auswahlhinweis, keine auszuführende Anweisung. Ergänzende Dateien liegen neben den Anweisungen.

Bei einem Skill mit `disable-model-invocation` weist die Liste den Agenten an, den Skill erst zu verwenden, wenn die Aufgabe ihn ausdrücklich nennt. Das ist eine Anweisung, keine technische Zugriffssperre. Wähle die Ausrüstung gezielt und nenne das Vorgehen, wenn es darauf ankommt. Dass ein Skill verfügbar ist, belegt noch nicht, dass das Ergebnis seinen Anweisungen folgt.

## Fehlende oder geänderte Skills prüfen

Löschst du einen Skill, wird er bei jedem Agenten abgelegt, der ihn ausgerüstet hatte; das Audit-Protokoll hält fest, bei welchen. Ist ein benötigter Skill nicht mehr mit dem Ausführungsbereich geteilt, schlägt die Bereitstellung fehl und nennt den nicht verfügbaren Skill; der Lauf wird nicht automatisch wiederholt, weil eine Wiederholung daran nichts ändert. Im Dialog des Agenten erscheint der Skill als nicht verfügbar, damit du ihn abwählen kannst — alle anderen Einstellungen des Agenten lassen sich weiterhin speichern. Stelle den vorgesehenen Zugriff wieder her oder entferne die veraltete Ausrüstung, bevor du es erneut versuchst.

Änderungen an einem geteilten Bundle wirken sich auf spätere Bereitstellungen aus. Prüfe Ersetzungen und teste den Agenten nach größeren Änderungen mit einer bekannten Eingabe. Verlasse dich nicht darauf, dass ein gleichnamiger Skill im Repository das ausgerüstete Bundle überschreibt.

## Skills oder Agent-Anweisungen wählen

| In einen Skill gehört, was… | In die Agent-Anweisungen gehört, was… |
| --- | --- |
| mehrere Agenten als gemeinsames Vorgehen nutzen. | die Rolle oder den Stil dieses Agenten festlegt. |
| Referenzdateien oder Skripte benötigt. | eine kurze, beständige Regel für diesen Agenten ist. |
| zentral gepflegt werden soll. | erklärt, wie dieser Agent seine ausgerüsteten Skills verwenden soll. |

Die [Anleitung zur Skill-Bibliothek](https://docs.tale.dev/de/platform/workspace/skills) erklärt, wie du Bundles erstellst, importierst, bearbeitest und teilst.

# Freigaben für Aktionen verstehen
Source: https://docs.tale.dev/de/platform/approvals/concepts

Mit einer Freigabe prüfst du einen geplanten Connector-Schreibzugriff, bevor er ausgeführt wird. Eine Automation kann zum Beispiel eine E-Mail vorbereiten und dann warten, bis du Empfänger und Inhalt vor dem Versand geprüft hast.

## Wann ein Schreibzugriff wartet

Ein Live-Lauf pausiert, sobald er einen Connector-Schreibzugriff erreicht, für den die Richtlinie der Organisation eine Freigabe verlangt. Standardmäßig brauchen Schreibzugriffe auf externe Systeme eine Freigabe; Schreibzugriffe über interne, durch die Plattform authentifizierte Connectors nicht. Die Organisation kann diese Regel für einen Connector oder eine einzelne Aktion ändern. Mehr dazu unter [Freigaben konfigurieren](https://docs.tale.dev/de/platform/approvals/configure).

Lesezugriffe verlangen keine Freigabe. Ein **Testlauf** nutzt simulierte Connectors: Er führt den externen Schreibzugriff nicht aus und zeigt dessen Live-Freigabekarte nicht. Ein bestandener Test belegt nicht, dass die geplante Live-Aktion angemessen ist.

## Die geplante Aktion prüfen

Öffne die [Laufliste](https://docs.tale.dev/de/platform/automations/execution-logs) der Automation und wähle den Lauf mit dem Status **Wartet**. Die Freigabekarte nennt die Aktion, etwa `imap-smtp.send`, und den anfragenden Knoten. **Der Schritt würde aufrufen mit** zeigt die genauen Eingaben.

Vergleiche Ziel, Empfänger, Inhalt und Kennungen mit der beabsichtigten Aufgabe. Prüfe auch sensible Angaben in den Eingaben, bevor du entscheidest:

- **Freigeben** erlaubt die Ausführung dieser Aktion, sobald der Lauf fortgesetzt wird.
- **Ablehnen** verhindert die Aktion; der Schritt und der Lauf schlagen fehl.

Auf der Karte kannst du die Aktion nicht bearbeiten. Ist eine Eingabe falsch, lehne sie ab, korrigiere den Workflow oder seine Eingaben und starte einen neuen Lauf.

<Note>

Organisationsmitglieder können über Connector-Aktionen entscheiden. Diese Karten werden keiner bestimmten prüfenden Person oder Gruppe zugewiesen; die Entscheidung erfolgt in den Laufdetails, die nur Inhaber, Admins und Entwickler öffnen. Bearbeitet der Lauf eine Aufgabe, erscheint seine Karte auch in der Aufgabe, und dort entscheidet jede Person, die die Aufgabe öffnen kann. Für andere Prüfverfahren können strengere Berechtigungen gelten.

</Note>

## Das Ergebnis prüfen

Eine Freigabe erlaubt die Ausführung, garantiert aber nicht, dass der Connector erfolgreich ist. Prüfe nach der Fortsetzung den Laufstatus, das Knotenergebnis und die Auswirkungen. Ein abgelehnter Lauf nennt die Ablehnung als Fehlergrund. Das [Audit-Protokoll](https://docs.tale.dev/de/platform/admin/governance/audit-logs) hält die Entscheidung und die handelnde Person fest.

Eine ausstehende Freigabe bleibt offen, wenn die Richtlinie gelockert wird. Dieselbe Aktion im selben Lauf behält ihre gespeicherte Entscheidung; ein neuer Lauf wird erneut bewertet. Ein beendeter oder abgebrochener Lauf kann eine noch offene Freigabe nicht mehr für seinen Schreibzugriff nutzen.

## Freigabe und Rückfrage unterscheiden

Ein Agent-Knoten kann auch pausieren, weil er Informationen von einer Person braucht. Deine Antwort liefert eine Eingabe; sie gibt keinen Connector-Schreibzugriff frei. [Freigaben in Workflows](https://docs.tale.dev/de/platform/automations/approvals-in-workflows) erklärt beide Abläufe. Für Aufgabenprüfungen, kontrollierte Dokumente und Löschanträge gelten eigene [Prüfregeln](https://docs.tale.dev/de/platform/approvals/configure).

# Festlegen, welche Aktionen eine Freigabe brauchen
Source: https://docs.tale.dev/de/platform/approvals/configure

Eine Freigaberichtlinie bestimmt, welche Connector-Schreibzugriffe in einem Live-Lauf auf eine Person warten müssen. Prüfe externe Aktionen vor der Bereitstellung, besonders wenn ein Workflow Nachrichten sendet oder andere Systeme verändert. [Freigaben verstehen](https://docs.tale.dev/de/platform/approvals/concepts) erklärt die Entscheidungskarte.

## Das Standardverhalten verstehen

Lesezugriffe brauchen keine Operationsfreigabe. Schreibzugriffe auf externe Systeme warten standardmäßig auf eine Freigabe, etwa E-Mail-Versand, Slack-Nachrichten, neue GitHub-Issues oder WebDAV-Schreibzugriffe. Interne Aktionen wie das Ändern einer Aufgabe oder Speichern eines Dokuments in Tale fragen standardmäßig nicht.

Auch erlaubte Aktionen unterliegen den jeweiligen Zugriffsregeln. Eine fehlende Freigabekarte beweist nicht, dass eine Aktion nur liest. Es kann sich um einen internen oder ausdrücklich automatisch freigegebenen Schreibzugriff handeln.

## Eine Richtlinienänderung veranlassen

In den Connector-Einstellungen gibt es keinen Freigabeschalter pro Aktion. Die Organisationsrichtlinie kann Freigaben für einen Connector oder eine einzelne Aktion verlangen oder ausnehmen. Eine aktionsbezogene Regel hat Vorrang vor der Regel des gesamten Connectors.

Bitte die für dein Deployment zuständige Person, die [Freigaberichtlinie](https://docs.tale.dev/de/self-hosted/configuration/approvals) anzupassen. Nenne die genaue Operation, den Grund für eine Freigabepflicht oder automatische Ausführung und den betroffenen Workflow. Auch Cloud-Admins stimmen dies mit der zuständigen Betriebsstelle ab.

Eine bereits wartende Operation behält ihre offene Freigabe nach der Richtlinienänderung. Entscheide diese Karte ausdrücklich. Eine Lockerung gibt sie nicht automatisch frei.

## Einen Workflow vor dem Live-Betrieb prüfen

1. Prüfe bei jedem Connector-Knoten, ob er liest oder schreibt.
2. Kläre, welche Schreibzugriffe die wirksame Organisationsrichtlinie automatisch freigibt.
3. Nutze **Testlauf**, um Ein- und Ausgabe mit Mocks zu prüfen.
4. Prüfe in einem kontrollierten Live-Lauf die Operation und ihre genauen Eingaben auf jeder offenen Karte, bevor du entscheidest.

Ein Mock-Test beweist nicht, dass im Live-Lauf eine Freigabe erscheint. Mock-Connectors verändern keine externen Systeme und fragen nicht nach Freigaben.

## Andere menschliche Entscheidungen unterscheiden

| Entscheidung | Zugehörige Regeln |
| --- | --- |
| Ein Agentenergebnis annehmen | [Aufgaben automatisieren](https://docs.tale.dev/de/platform/projects/task-automation). Eine Person verschiebt das Ergebnis von In Prüfung nach Erledigt. |
| Eine gelenkte Dokumentversion freigeben | [Dokumente](https://docs.tale.dev/de/platform/knowledge/documents). Der benannte Reviewer entscheidet über die eingefrorene Version. |
| Eine Löschanfrage genehmigen | [Anfragen betroffener Personen](https://docs.tale.dev/de/platform/admin/governance/data-subject-requests). Ein zweiter Admin gibt die nötige Freigabe. |
| Die Frage eines Agentenknotens beantworten | [Freigaben in Workflows](https://docs.tale.dev/de/platform/automations/approvals-in-workflows). Dem Lauf fehlt eine Information zum Fortsetzen. |

Für diese Entscheidungen gelten eigene Regeln. Die Connector-Freigaberichtlinie schaltet sie nicht ab. Der Chat verwendet nur lesende Abrufwerkzeuge und erzeugt keine Operationsfreigaben.

# Auf einen wartenden Workflow reagieren
Source: https://docs.tale.dev/de/platform/automations/approvals-in-workflows

Ein Lauf kann auf eine Entscheidung vor einem Connector-Schreibzugriff warten oder auf Informationen, die ein Agent zum Fortfahren braucht. In den Laufdetails siehst du, welche Antwort nötig ist. Ein wartender Lauf ist noch nicht abgeschlossen, auch wenn vorherige Knoten erfolgreich waren.

## Den wartenden Lauf finden

Öffne die Automation und ihre [Ausführungsprotokolle](https://docs.tale.dev/de/platform/automations/execution-logs). Wähle den Lauf mit dem Status **Wartet**. Prüfe Version und Eingaben, damit du die richtige Ausführung beurteilst.

Eine Freigabekarte nennt eine Connector-Aktion und zeigt ihre geplanten Eingaben. Eine Rückfrage des Agenten verlangt dagegen eine Antwort, als Auswahl oder Freitext. Beides ist getrennt: Mit einer Antwort gibst du keinen späteren Schreibzugriff frei.

## Einen Schreibzugriff freigeben oder ablehnen

Lies die Aktion und die Angaben unter **Der Schritt würde aufrufen mit** genau. Prüfe Empfänger oder Ziel, den Inhalt und alle Kennungen, die bestimmen, was geändert wird.

Wähle **Freigeben**, um die Aktion zu erlauben. Der Lauf wird fortgesetzt und versucht den Schreibzugriff; kontrolliere danach Knotenergebnis und Auswirkungen. Wähle **Ablehnen**, wenn die Anfrage falsch ist oder nicht ausgeführt werden soll. Die Ablehnung verhindert diese Aktion und lässt den Lauf fehlschlagen.

Auch wenn etwas schiefgeht, zeigt die Karte, wo der Lauf steht. Lässt sich die Freigabe nicht laden, sagt die Karte das und bietet **Erneut versuchen** an; der Lauf wartet weiter, bis jemand entscheidet. Wurde deine Entscheidung nicht gespeichert, meldet die Karte das und behält **Freigeben** und **Ablehnen**, damit du noch einmal wählen kannst. Hat jemand anderes zuerst entschieden, zeigt die Karte die gespeicherte Entscheidung.

Ein Live-Lauf prüft vor der Freigabeanfrage, ob der Connector ein nutzbares Credential hat: Ist keines konfiguriert, schlägt der Knoten mit diesem Grund fehl, statt auf eine Entscheidung zu warten.

Auf der Freigabekarte kannst du keine Parameter ändern. Lehne eine falsche Anfrage ab, korrigiere den Workflow oder seine Eingaben und teste die Änderung vor einem neuen Live-Lauf. Änderungen an der Freigaberichtlinie geben eine bereits offene Karte nicht frei. [Freigabekonzepte](https://docs.tale.dev/de/platform/approvals/concepts) erklärt den Ablauf; die [Konfiguration der Freigaberichtlinie](https://docs.tale.dev/de/self-hosted/configuration/approvals) beschreibt die Regeln für den Betrieb.

## Eine Rückfrage des Agenten beantworten

Nutzt ein Agent-Knoten `ask_human`, zeigen die Laufdetails **Der Agent braucht deine Antwort, um weiterzumachen**. Beantworte vorgegebene Auswahlfragen direkt auf der Karte. Bei einer offenen Frage schreibst du unter **Deine Antwort** einen Text und klickst auf **Antwort senden & fortsetzen**.

Gib die fehlende Information möglichst konkret an. Fragt der Agent nach einem Dokument, nenne das Dokument oder seine Kennung, statt ihn nur zum Fortfahren aufzufordern. Der wartende Knoten wird mit deiner Antwort fortgesetzt. Später kann der Lauf eine weitere Antwort oder eine Freigabe benötigen. Inhaber, Admins und Entwickler antworten in den Laufdetails. Bearbeitet der Lauf eine Aufgabe, erscheint die Rückfrage auch in der Aufgabe, und dort antwortet jede Person, die die Aufgabe öffnen kann.

## Den Workflow korrigieren und testen

Eine Workflow-Definition zu ändern ist ein anderer Vorgang als auf ihren laufenden Durchgang zu reagieren. Speichere eine korrigierte Version im [Workflow-Editor](https://docs.tale.dev/de/platform/automations/editor), teste sie mit simulierten Connectors und schalte sie anschließend für den Live-Betrieb frei. Das Speichern einer Version ändert keinen Aufruf, der bereits auf Freigabe wartet.

<Frame caption="Bearbeite den Workflow auf der Zeichenfläche; prüfe wartende Ausführungen in ihren Laufdetails.">

![Der Workflow-Editor zeigt den Automationsgraphen und einen Bereich zum Konfigurieren des ausgewählten Knotens.](https://docs.tale.dev/images/platform/automation-editor-canvas.webp)

</Frame>

Ein Test mit simulierten Connectors führt keine externen Schreibzugriffe aus und verlangt dafür keine Live-Freigaben. Ein praktisches Beispiel findest du unter [Einen Workflow mit Freigaben erstellen](https://docs.tale.dev/de/tutorials/editor/workflow-with-approvals). Prüfe nach einer Live-Entscheidung das Laufergebnis und das [Audit-Protokoll](https://docs.tale.dev/de/platform/admin/governance/audit-logs): Die Erlaubnis zur Ausführung und eine erfolgreiche Ausführung sind unterschiedliche Ergebnisse.

# Den Weg zur Automation wählen
Source: https://docs.tale.dev/de/platform/automations/assistant

Bearbeite eine Automation direkt auf ihrer Arbeitsfläche oder verbinde einen externen Assistenten über MCP mit den Werkzeugen von Tale. Beide Wege speichern Versionen desselben Workflows und nutzen dieselben Prüf- und Bereitstellungsregeln. Zum Erstellen und Bereitstellen brauchst du Entwicklerrechte.

## Eine Änderung im visuellen Editor vornehmen

Öffne **Automatisierungen** und wähle den Workflow. Klicke auf einen Knoten, um Eingaben, Modell, Code oder andere Einstellungen zu prüfen. Speichere die Änderung mit einer Versionsnachricht, führe einen Test aus und stelle nach bestandenen Prüfungen die gewünschte Version bereit.

<Frame caption="Ein ausgewählter Knoten zeigt seine Konfiguration neben dem Workflow-Graphen.">

![Der Automation-Editor zeigt den Workflow-Graphen und die Eingabefelder des ausgewählten Knotens in einer Seitenleiste.](https://docs.tale.dev/images/platform/automation-editor-canvas.webp)

</Frame>

[Der Workflow-Editor](https://docs.tale.dev/de/platform/automations/editor) erklärt diese Schritte, die Prüfung eines Laufs und die Rückkehr zu einer früheren Version. Die Arbeitsfläche enthält keinen Chat-Assistenten.

## Einen externen Assistenten über MCP nutzen

Richte deinen Client mit dem Endpunkt unter **Einstellungen > API > MCP** und einem passenden Organisations-API-Schlüssel ein. Beschreibe Eingaben, gewünschte Ausgabe und die Systeme, die der Workflow verändern darf. Lass den Client vorhandene Automationen und Funktionen prüfen, bevor er eine weitere erstellt.

Der [MCP-Endpunkt](https://docs.tale.dev/de/develop/mcp-endpoint) bietet Tools für Dokumentation, Validierung, Speichern, Testen und Bereitstellen. Prüfe den entstandenen Workflow und die Testergebnisse vor der Bereitstellung. Ein Speichervorgang erstellt eine Version, schaltet sie aber nicht live.

## Entscheidungen während eines Laufs unterscheiden

Ein Agentenknoten arbeitet während eines Automation-Laufs. Er ist nicht der Client, mit dem du den Workflow schreibst. Ebenso genehmigt eine [Freigabe](https://docs.tale.dev/de/platform/approvals/concepts) eine ausstehende Operation während der Ausführung und keine vorgeschlagene Änderung an der Workflow-Definition.

Nutze [den Editor](https://docs.tale.dev/de/platform/automations/editor) für direkte Änderungen oder [MCP](https://docs.tale.dev/de/develop/mcp-endpoint) für deinen eigenen Client. Beginne mit [einer vorhandenen Automation](https://docs.tale.dev/de/platform/automations/catalog), wenn bereits eine passende verfügbar ist.

# Mitgelieferte Automatisierungen
Source: https://docs.tale.dev/de/platform/automations/builtin

Tale enthält zehn Automatisierungspakete: drei für die Postfach-Synchronisierung, drei für Zusammenfassungen, zwei für die GitHub-Prüfung sowie Issue-Importe für GitHub und GlitchTip. Jedes beginnt mit Version 1 und **Nicht live**. Die Issue-Importer laufen manuell; die anderen Pakete enthalten Zeitpläne. Prüfe Eingaben, Modell, Verbindungen und Schreibvorgänge, bevor ein Inhaber, Admin oder Entwickler eine Version live schaltet.

<Frame caption="Der Automatisierungskatalog zeigt Paketnamen, Versionszahlen und Live-Status.">

![Der Automatisierungskatalog listet GitHub- und Mail-Pakete mit einer Version und dem Status Nicht live.](https://docs.tale.dev/images/platform/automations-catalog.webp)

</Frame>

## Mit einem Paket beginnen

Öffne **Automatisierungen**, wähle ein Paket und prüfe seine Nodes im [Workflow-Editor](https://docs.tale.dev/de/platform/automations/editor). Der benötigte Connector muss verbunden sein, und das Modell jeder `llm`-Node muss eines sein, das deine Organisation bedient — die Pakete nennen ein Modell, das deine Anbieter womöglich nicht anbieten; die Validierung warnt beim Speichern davor. Wähle vor einem Live-Lauf im Feld **Modell** der Node ein bedientes Modell. Ein Testlauf verwendet simulierte Antworten. Er prüft den Ablauf, belegt aber keinen Zugriff auf dein echtes Postfach oder Repository.

Die Pakete werden beim Anlegen der Organisation hinzugefügt. Ändert sich ein mitgeliefertes Paket, bleiben deine bestehenden Versionen erhalten; nur der mitgelieferte Name und die Beschreibung werden aktualisiert. Ein gelöschtes Paket bleibt gelöscht. Eigene Änderungen ergeben neue Versionen, die du getrennt live schaltest.

## E-Mails in die Inbox synchronisieren

Diese Workflows übernehmen alle fünf Minuten neue Nachrichten in Konversationen. Jeder stellt die Ansicht **Inbox** bereit: Nach dem Live-Schalten erscheint sie im Bereich [Start](https://docs.tale.dev/de/platform#home), und das Formular zum Verfassen bietet das verbundene Postfach an. Vorher hat **Start** keine Ansicht **Inbox**. Ein Link zur Inbox zeigt dann einen Hinweis zur Einrichtung: Für Inhaber, Admins und Entwickler verweist er auf **Automatisierungen**; alle anderen erfahren, dass jemand mit einer dieser Rollen eine E-Mail-Automatisierung live schalten muss.

| Automatisierung | Benötigter Connector | Zeitplan |
| --- | --- | --- |
| Gmail-E-Mails synchronisieren | Gmail | Alle 5 Minuten |
| Outlook-E-Mails synchronisieren | Outlook | Alle 5 Minuten |
| E-Mails über SMTP/IMAP synchronisieren | IMAP/SMTP | Alle 5 Minuten |

Ein Durchlauf liest nur den Posteingangsordner des Postfachs. Die eigenen Antworten des Postfachs unterscheidet er von denen der Kundin oder des Kunden an der Postfachadresse, die der erste Durchlauf vom verbundenen Konto erfährt und als Absenderadresse an der Verbindung behält; bei IMAP stammt sie aus dem Login.

Verbinde zuerst das passende Postfach. Prüfe nach dem ersten Live-Lauf das [Ausführungsprotokoll](https://docs.tale.dev/de/platform/automations/execution-logs) und ob die erwarteten Nachrichten im Bereich **Start** in der Ansicht **Inbox** erscheinen.

Anhänge werden mit ihrer Nachricht gespeichert, du öffnest und lädst sie also direkt in der Konversation herunter. Aus Gmail übernimmt Tale jeden Anhang nur bis 3,5 MB: Ein größerer erscheint weiterhin mit Name und Größe, öffnen kannst du ihn aber nur in Gmail.

## Die Inbox sichten

Diese Workflows arbeiten alle sechs Stunden auf der **Inbox**, die die Synchronisierungs-Automatisierungen füllen. Jeder liest die offenen Konversationen seines Mail-Connectors, deren neueste Nachricht von der Kundin oder dem Kunden stammt und die seit dem Eintreffen dieser Nachricht noch kein Durchlauf beurteilt hat – höchstens 25 pro Lauf, sofern du `limit` nicht erhöhst, und nie mehr als 100. Das Modell entscheidet für jeden Thread, ob eine Person antworten muss und wie dringend es ist.

Was ein Lauf verändert:

- Das Urteil wird samt Begründung am Thread festgehalten, sodass der nächste Lauf den Thread erst wieder ansieht, wenn sich die Kundin oder der Kunde erneut meldet.
- Die **Priorität** des Threads wird auf das Urteil des Modells gesetzt – aber nur, wenn noch niemand eine gesetzt hat. Eine von einer Person gewählte Priorität bleibt bestehen.
- Wo eine Antwort fällig ist, entwirft ein zweiter Modellaufruf eine und legt sie als **Antwortvorschlag** an den Thread: eine Karte über dem Editor, getrennt von allem, was eine Person selbst getippt hat. **In den Editor übernehmen** gibt den Text zum Anpassen und Senden in den Editor; **Verwerfen** lässt ihn fallen, und der Thread bekommt erst wieder einen Vorschlag, wenn sich die Kundin oder der Kunde erneut meldet. Die Automatisierung sendet nichts. Ein Thread, der bereits einen Vorschlag trägt, behält ihn.

Die Ausgabe des Laufs zeigt, was gelesen wurde, die Zusammenfassung des Modells, die Threads, die eine Antwort brauchen, mit ihren Inbox-Links, und die abgelegten Entwürfe. Ein Lauf, bei dem nichts wartet, ruft kein Modell auf. Stelle zuerst die passende Synchronisierungs-Automatisierung bereit; ohne synchronisierte Konversationen gibt es nichts zu sichten.

| Automatisierung | Benötigter Connector | Zeitplan |
| --- | --- | --- |
| Gmail-Posteingang sichten | Gmail | Alle 6 Stunden |
| Outlook-Posteingang sichten | Outlook | Alle 6 Stunden |
| IMAP-Posteingang sichten | IMAP/SMTP | Alle 6 Stunden |

## Issues importieren und synchronisieren

**GitHub-Issues importieren** und **GlitchTip-Issues importieren** verwenden dasselbe Formular, um Issues als Aufgaben anzulegen. Sie beginnen ohne Zeitplan. Die Importe lesen die Quelle und schreiben Tale-Aufgaben. Sie kommentieren, schließen oder verändern keine Issues in der Quelle und starten keinen Agenten.

1. Verbinde die Quelle unter **Einstellungen > Connectors** und wähle die Standard-Zugangsdaten. GitHub benötigt Repository-Zugriff mit Leserechten für Issues. GlitchTip benötigt die Instanz-URL und ein Token mit `project:read` und `event:read`. Ein Token nur für die Projekteinrichtung kann keine Issues lesen. Selbst gehostete Instanzen müssen durch die Host-Richtlinie des Connectors erlaubt sein.
2. Öffne den Importer und wähle **Testlauf**. Wähle das **Tale-Projekt** und gib den GitHub-Inhaber samt Repository oder die Organisations- und Projektkennung von GlitchTip ein. Optionale Labels oder eine GlitchTip-Suche grenzen die Suche nach neuen Issues ein. **Maximale Anzahl an Issues** erlaubt 1–500; der Standard ist 100.
3. Prüfe das Testergebnis, schalte die Version live und wähle **Live ausführen** mit demselben Ziel und denselben Filtern. Ein Testlauf verwendet Beispieldaten und erstellt keine Aufgaben. Erst ein Live-Durchlauf prüft die tatsächliche Verbindung.
4. Öffne **Läufe** und wähle den Durchlauf. **Importierte Aufgaben** verlinkt die zugehörigen Tale-Aufgaben. Wenn ein weiterer Stapel verbleibt, übernimmt **Import fortsetzen** Quelle, Ziel und Fortsetzungsposition für den nächsten Durchlauf. Um stattdessen jedes Issue nach Zeitplan zu importieren, merkt sich eine Automatisierung diese Position zwischen ihren Terminen: siehe [Jedes Issue nach Zeitplan importieren](https://docs.tale.dev/de/platform/automations/triggers#jedes-issue-nach-zeitplan-importieren).

Jede Synchronisierung sucht neue Issues und aktualisiert bis zu 500 verknüpfte Issues, beginnend mit den am längsten nicht geprüften. Das gilt auch für verknüpfte Issues, die nicht mehr zum Suchfilter passen. Wiederhole den Durchlauf, um große Bestände aktuell zu halten. GitHub-Pull-Requests sind ausgeschlossen. Wiederholungen verwenden innerhalb eines Tale-Projekts dieselbe Quellidentität. Wird ein Repository oder Projekt umbenannt, ändert sich der Link zur Quelle, ohne eine zweite Aufgabe anzulegen. Auch nach dem Verschieben in ein anderes Repository oder Quellprojekt bleiben Issues verknüpft und werden über die bisherigen Importe aktualisiert, sofern die Verbindung auf den neuen Ort zugreifen kann.

Die Quellenkarte einer Aufgabe zeigt den aktuellen Titel, die Beschreibung und den Status der Quelle getrennt an. Beim Import kürzt Tale Titel über 200 UTF-16-Codeeinheiten und Beschreibungen über 20.000 (die meisten Emojis zählen doppelt) in der Aufgabe auf diese Länge und beendet sie mit „…“; die Quellenkarte und das verknüpfte Issue behalten den vollständigen Text. Wird ein Issue geschlossen oder behoben, bleiben Status, Titel, Beschreibung, Zuweisung und Priorität der Tale-Aufgabe erhalten. Ist ein Issue nicht mehr erreichbar, bleiben seine zuletzt bekannten Angaben sichtbar. Authentifizierungsfehler und Ratenbegrenzungen lassen den Durchlauf fehlschlagen, statt das Issue als gelöscht zu kennzeichnen. Prüfe und erledige die Arbeit weiterhin in Tale.

## GitHub-Arbeit prüfen

**GitHub-Issues sichten** liest offene Issues, bewertet ihre Umsetzbarkeit und Priorität und liefert eine sortierte Auswahl mit Begründungen. Der Workflow schreibt nichts nach GitHub und erstellt keine Projektaufgaben. Standardmäßig verarbeitet er höchstens 50 Issues pro Lauf.

**GitHub-Pull-Requests prüfen** liest die Diffs offener Pull Requests und veröffentlicht die Ergebnisse als Review-Kommentare. Standardmäßig verarbeitet er höchstens 10 Pull Requests pro Lauf. Er genehmigt keinen Pull Request und führt ihn nicht zusammen. Prüfe vor einem Live-Lauf das Ziel-Repository: Ein erneuter Lauf kann weitere Kommentare hinzufügen.

| Automatisierung | Benötigter Connector | Mitgelieferter Zeitplan | Schreibvorgänge |
| --- | --- | --- | --- |
| GitHub-Issues sichten | GitHub | Täglich um 07:00 UTC | Keine; lies die Ausgabe des Laufs |
| GitHub-Pull-Requests prüfen | GitHub | Alle 30 Minuten | Ein Review-Kommentar pro verarbeitetem Pull Request |

Beide Workflows benötigen `owner` und `repo`. Gib beim **Testlauf** unter **Eingabe für den Lauf (JSON)** die Werte deines Repositorys ein:

```json
{
  "owner": "deine-organisation",
  "repo": "dein-repository",
  "limit": 5
}
```

<Note>

Die mitgelieferten GitHub-Zeitpläne liefern weder `owner` noch `repo`. Das Live-Schalten allein macht diese geplanten Läufe deshalb nicht ausführbar. Ein Zeitplan sendet nur `trigger` und `firedAt`; die erforderliche Repository-Eingabe fehlt damit, und der Start wird abgelehnt. Starte manuell mit den benötigten Eingaben oder passe Schema und Repository-Konfiguration an, bevor du geplante Läufe aktivierst. Ein abgelehnter geplanter Start erscheint am [Trigger](https://docs.tale.dev/de/platform/automations/triggers) als `start_refused`.

</Note>

Lies vor dem Live-Schalten die aufgelöste Eingabe und Ausgabe des Testlaufs. Prüfe für einen Live-Lauf zusätzlich die Connector-Berechtigungen und nötige Freigaben. Die [Ausführungsprotokolle](https://docs.tale.dev/de/platform/automations/execution-logs) erklären Wartezustände, Fehler und protokollierte Schreibvorgänge.

# Automatisierungen erstellen oder importieren
Source: https://docs.tale.dev/de/platform/automations/catalog

Unter **Automatisierungen** findest du die Workflows deiner Organisation. Nur Inhaber, Admins und Entwickler sehen diesen Bereich und verwalten seine Automatisierungen. Prüfe zuerst, ob eine [mitgelieferte Automatisierung](https://docs.tale.dev/de/platform/automations/builtin) zur Aufgabe passt. Andernfalls erstellst du einen Entwurf und testest ihn, bevor du ihn live schaltest.

Du kannst nach Name oder Slug suchen. Gib zum Beispiel `Triage` ein, um die mitgelieferten Triage-Workflows zu vergleichen.

<Frame caption="Die nach Triage gefilterte Liste zeigt vier mitgelieferte Beispiele mit Versionsanzahl und Bereitstellungsstatus.">

![Vier gefilterte Triage-Automatisierungen für GitHub, Gmail, IMAP und Outlook mit Versionen, Bereitstellungsstatus und der Schaltfläche zum Erstellen einer Automatisierung.](https://docs.tale.dev/images/platform/automations-catalog.webp)

</Frame>

## Einen Ausgangspunkt wählen

Jede Zeile zeigt Name, Projektzuordnungen, Versionsanzahl und Live-Version oder **Nicht live**. Öffne sie im Tab **Editor**, um den Ablauf zu prüfen. Unter **Allgemein** findest du Trigger und Projekte: Unter **Projekte** legst du fest, welche Boards die Automatisierung nutzen können. Ohne Projektzuordnung steht sie der Organisation zur Verfügung. **Projekte** bietet nur Projekte an, die du öffnen kannst. Zuordnungen zu Projekten, die du nicht siehst, bleiben beim Speichern erhalten. Eine Automatisierung, die nur solchen Projekten zugeordnet ist, erscheint nicht in deiner Liste. Die Auswahl **Version** rechts neben den Tabs zeigt den gespeicherten Verlauf, unter **Läufe** die letzten Ausführungen.

Das Menü **Automatisierung erstellen** bietet zwei Wege:

| Auswahl | Geeignet, wenn … | Danach |
| --- | --- | --- |
| **Leer (Trigger + Agent)** | du den Ablauf selbst konfigurieren möchtest. | Lege Name, Modell, Anweisungen und Ausstattung fest und wähle dann, wann der Agent läuft. Nach dem Erstellen öffnet sich der Editor für weitere Änderungen. |
| **Paket hochladen** | eine Workflow-Datei oder ein wiederverwendbares Pack vorliegt. | Tale prüft die Dateien und speichert eine Entwurfsversion. |

Mitgelieferte Automatisierungen werden beim Erstellen der Organisation eingerichtet. Für den automatischen Einsatz brauchen sie dennoch ihre Konfiguration und eine Live-Version. Der [Workflow-Editor](https://docs.tale.dev/de/platform/automations/editor) führt durch Eingaben, Test, Ergebnisprüfung und Live-Schaltung.

## Ein Paket importieren

Ein Pack enthält die erforderliche `workflow.yml`, optional das Manifest `automation.yml` und bei Bedarf Skill-Bundles:

```text
review-invoices/
├── workflow.yml
├── automation.yml
└── skills/
    └── invoice-rules/
        ├── SKILL.md
        └── references/
            └── checklist-rules.md
```

<Steps>

<Step title="Dateien auswählen">

Wähle **Automatisierung erstellen > Paket hochladen**. Lade Workflow und optionales Manifest einzeln hoch oder wähle genau eine `.zip` mit dem Pack. Für mitgelieferte Skills brauchst du die ZIP-Datei. Markdown-Notizen außerhalb von `skills/`, versteckte Dateien und Build-Reste wie `node_modules/` und `__pycache__/` werden ignoriert.

</Step>

<Step title="Ziel festlegen">

Wähle unter **Installieren in** die **Organisation** oder ein bestehendes Projekt. Ein Manifest mit `scope: project` verlangt ein Projekt. Importierst du eine bestehende Automatisierung in ein weiteres Projekt, kommt diese Zuordnung hinzu; frühere bleiben erhalten. Unter **Projekte** im Tab **Allgemein** der Automatisierung kannst du später alle Zuordnungen bearbeiten.

<Frame caption="Paket hochladen — die Dateien oder eine Zip, und wo die Automatisierung installiert wird.">

![Der Dialog zum Paket-Upload mit seiner Ablagezone und dem Auswahlfeld Installieren in, gesetzt auf Organisation.](https://docs.tale.dev/images/platform/automations-upload-dialog.webp)

</Frame>

</Step>

<Step title="Prüfen und speichern">

Wähle **Paket hochladen** und behebe gemeldete Fehler im Workflow, Manifest oder Skill. Erst nach erfolgreicher Prüfung werden Automatisierung und mitgelieferte Skills geschrieben. Ein erneuter Import derselben Automatisierung ergänzt eine Entwurfsversion; die bisherige Historie bleibt erhalten.

</Step>

<Step title="Vor der Live-Schaltung prüfen">

Mit **Später** öffnest und testest du den Entwurf anschließend im Editor. Der Erfolgsdialog bietet auch an, die angezeigte Version direkt live zu schalten. Der Upload allein ändert die Live-Version nicht. Richte benötigte Zugangsdaten ein und prüfe die Skills vor der Freigabe für den Betrieb.

</Step>

</Steps>

Die ZIP-Datei darf komprimiert und entpackt jeweils höchstens 20 MiB enthalten: maximal 500 Dateien, 2 MiB je Datei und 20 Skill-Bundles. Entferne bei einer Größenüberschreitung erzeugte Artefakte und trenne unabhängige Inhalte in eigene Skills. Stärkere Komprimierung behebt ein zu großes entpacktes Paket nicht.

## Konflikte bei Skills klären

Die `skills`-Liste im Manifest muss zu den Ordnern unter `skills/` passen. Nicht deklarierte Ordner und deklarierte, aber fehlende Bundles führen zur Ablehnung. Jedes Bundle braucht gültige Metadaten in `SKILL.md`; `name` muss dem Ordnernamen entsprechen. Mitgelieferte Skills folgen den Regeln der Skill-Bibliothek: Ein neuer Skill gehört der Person, die das Paket hochlädt. Ein ersetzter behält seinen Eigentümer; hatte er keinen, gehört er danach der hochladenden Person. Neue oder geänderte Teamlisten dürfen nur Teams enthalten, mit denen diese Person teilen darf. Bestehende Listen dürfen unverändert bleiben. Tale prüft die Zielgruppen aller mitgelieferten Skills, bevor es einen davon installiert.

```yaml
# automation.yml
name: Review invoices
skills:
  - invoice-rules
```

Neue Bundles werden in die [Skill-Bibliothek](https://docs.tale.dev/de/platform/workspace/skills) der Organisation aufgenommen. Identische bleiben unverändert. Bei anderem Inhalt hält der Upload an und nennt die betroffenen Slugs. Prüfe sie, bevor du das Ersetzen bestätigst: Das Paket ersetzt diese gemeinsam genutzten Bundles. Die bisherige `SKILL.md` bleibt im jeweiligen Verlauf. Vor der Bestätigung wird weder die Automatisierung noch ein Skill geschrieben.

Ein Workflow darf außerdem Bibliotheks-Skills verwenden, die nicht im Paket liegen. Fehlt einer, meldet der Upload eine Warnung. Installiere ein zugängliches Bundle, bevor du den Agenten startest, der es benötigt. Ein gespeicherter Entwurf bestätigt nicht, dass alle Abhängigkeiten bereitstehen.

## Ein Projekt über Paketformulare einrichten

Ein Manifest kann Formulare vorgeben, die bei der Auswahl seiner Aufgabenvorlage erscheinen. Die Werte gehören zum Projekt. So verwenden zwei Projekte denselben Ablauf mit unterschiedlichen Richtlinien.

```yaml
# automation.yml
settings:
  folder: Setup
  forms:
    - file: validation-policy.yaml
      title: Validation policy
      required: true
      fields:
        - key: method
          label: Validation profile
          type: select
          default: strict_rules
          options:
            - value: strict_rules
              label: Strict checklist
```

Ist das Projekt noch nicht eingerichtet, erscheinen Pflichtformulare vor den Aufgabenfeldern. **Speichern und weiter** schreibt die Formulare und setzt die Aufgabenerstellung fort. Später öffnet **Einstellungen** sie als Tabs. Ein Punkt markiert ungespeicherte Änderungen; **Speichern** schreibt alle geänderten Formulare. Beim Schließen mit offenen Änderungen fragt Tale nach.

Speichern ersetzt die flache YAML-Datei des Formulars, etwa `Setup/validation-policy.yaml`. Vorhandene Werte werden übernommen, auch aus einer manuell hochgeladenen Datei. Feldtypen sind `text`, `number`, `boolean` und `select`; gespeichert werden Zeichenketten. Textfelder können ein `pattern` vorgeben. Eintragsbezogene `i18n`-Blöcke übersetzen Titel, Beschriftungen, Hilfe und Optionen. Verschachtelte Daten und Listen gehören in separate Dateien, die der Workflow zusätzlich liest.

## Referenzdateien über ein Upload-Formular bereitstellen

Ein Upload-Formular verwaltet Dateien direkt, statt YAML zu erzeugen:

```yaml
settings:
  folder: Setup
  forms:
    - kind: uploads
      title: Reference documents
      subdir: reference
      accept: ['.pdf', '.json']
      match: '\.(pdf|json)$'
      requireFolder: true
```

`subdir` bestimmt einen Unterordner des Einstellungsordners. `accept` begrenzt die angebotenen Dateiendungen; `match` filtert die angezeigten Namen ohne Beachtung der Großschreibung und lehnt nicht passende Uploads ab. Bei `requireFolder: true` wählst oder erstellst du zuerst einen Unterordner, beispielsweise je Berichtszeitraum.

Uploads gelten sofort und haben kein **Speichern**. Sie blockieren die Aufgabenerstellung nicht. Läufe lesen den aktuellen Ordnerinhalt. Vervollständige deshalb die Referenzen, bevor du darauf angewiesene Arbeit startest.

## Die erwarteten Ergebnisse benennen

Das Manifest kann Dateien für den Bereich **Ergebnis** der Aufgabe festlegen. Sie erscheinen in der angegebenen Reihenfolge; andere Anhänge und Arbeitsdateien bleiben unter **Dateien**.

```yaml
subjects:
  task:
    outcome:
      files:
        - return.xml
        - report.md
        - name: audit-summary.md
          optional: true
```

Eine erforderliche Datei erscheint bis zu ihrer Ablage durch einen Lauf als **Noch nicht bereit**. Eine optionale Datei wird erst angezeigt, wenn sie existiert. Muster unterstützen `*` und `?`, etwa `return-*.xml`. Ohne Vorgaben zeigt das Ergebnis alle von Läufen abgelegten Dateien, neueste zuerst. Eine kurze ausdrückliche Liste hilft, den Abschlussbericht von Arbeitsunterlagen zu unterscheiden.

## Vor folgenreichen Freigaben nachfragen

**Freigeben** schließt die Aufgabe mit einem Klick. Bedeutet die Freigabe mehr als das Schließen der Aufgabe, deklariere diese Folge, etwa wenn eine Integration die Freigabe einem Kunden als Einreichung meldet. **Freigeben** fragt dann zuerst nach und zeigt deinen Satz:

```yaml
subjects:
  task:
    review:
      requestChanges: true
      approve:
        confirm: Approving tells the client this return has been filed with the tax authority. Approve only after you have filed it.
        i18n:
          de:
            confirm: Mit der Freigabe erfährt der Kunde, dass diese Abrechnung bei der Steuerverwaltung eingereicht ist. Gib sie erst frei, wenn du sie eingereicht hast.
```

Ohne `approve` bleibt **Freigeben** ein Schließen mit einem Klick. Übersetze den Satz unter `i18n`; eine Sprache ohne eigenen Satz nutzt ihre Basissprache, danach den englischen.

# Automatisierungskonzepte
Source: https://docs.tale.dev/de/platform/automations/concepts

Nutze eine Automatisierung für Arbeit mit einem wiederholbaren Ablauf. Der Workflow beschreibt die Schritte; gespeicherte Versionen erhalten jede Fassung, die Bereitstellung wählt die Version für Live-Läufe und ein Trigger kann sie nach Zeitplan oder Ereignis starten. Jeder Lauf zeigt Eingabe, Ergebnisse und Aktionen.

Lieber erst zusehen? Episode 5 öffnet die Triage-Automatisierung von vorne bis hinten und entscheidet eine Freigabekarte vor der Kamera, mit Untertiteln — aufgenommen auf der früheren Version, wo die Karte im Chat saß; in dieser Version sitzt sie auf der Detailseite des Laufs.

<Video src="https://docs.tale.dev/videos/de/tutorials/ep5-automations/ep5-automations.de.mp4" poster="https://docs.tale.dev/videos/de/tutorials/ep5-automations/ep5-automations.de.webp" captions="https://docs.tale.dev/videos/de/tutorials/ep5-automations/ep5-automations.de.vtt" lang="de" title="Episode 5 — Automatisierungen & Freigaben" caption="Episode 5 — Automatisierungen & Freigaben (3:11)">

</Video>

## Das Workflow-Dokument

Der `name` identifiziert die Automatisierung. Verwende kleingeschriebene Segmente mit Bindestrichen; `/` fasst verwandte Automatisierungen in Ordnern zusammen, etwa `billing/dunning-reminder`. Das erste Segment darf kein reservierter Seitenname sein: `asks`, `builder`, `catalog`, `listing`, `metrics`, `runs`, `serving-preview` oder `upload`.

Das Dokument enthält außerdem eine `description`, ein JSON-Schema `inputs` für die Eingabe eines Laufs, die ausführenden `nodes` und einen `output`-Ausdruck für das Ergebnis. Seine `tests` beschreiben Beispiele und erwartete Ergebnisse, die vor der Bereitstellung geprüft werden.

```yaml
name: billing/dunning-reminder
description: Einen Kunden an eine überfällige Rechnung erinnern.
inputs:
  type: object
  properties:
    invoiceId: { type: string }
  required: [invoiceId]
nodes:
  - id: invoice
    type: transform
    input:
      id: '{{ input.invoiceId }}'
    code: 'return { id: input.id, daysLate: 14 };'
  - id: message
    type: llm
    model: openai/gpt-4o-mini
    prompt: 'Schreibe eine höfliche Erinnerung zu Rechnung {{ nodes.invoice.output.id }}.'
output:
  text: '{{ nodes.message.output.text }}'
tests:
  - name: erzeugt eine Erinnerung
    input: { invoiceId: 'inv-1' }
```

Der `ui`-Block speichert die Positionen auf dem Canvas. Verschieben ändert die Anordnung, nicht die Ausführung einer Node.

### Kanten entstehen, sie werden nicht deklariert

Es gibt keine Kantenliste. Eine Node liest eine andere, indem sie sie referenziert — `{{ nodes.invoice.output.id }}` —, und genau diese Referenz _ist_ die Kante, die der Canvas zeichnet. Die Reihenfolge ergibt sich aus einer topologischen Sortierung über diese abgeleiteten Kanten. Deshalb verschwindet mit einer gelöschten Referenz auch ein Pfeil, und deshalb weist die Plattform zwei Nodes zurück, die einander lesen.

Templates nutzen eine einzige `{{ }}`-Grammatik aus JavaScript-Ausdrücken über `input`, `nodes.<id>.output` und, innerhalb einer iterierenden Node, `item` und `index`.

### Die Ablaufsteuerung sitzt an der Node

Verzweigen und Wiederholen sind Felder an einer Node statt eigener Schritttypen. Der Canvas zeigt sie deshalb als Badges an genau der Box, die sie betreffen.

| Feld                         | Wirkung                                                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------- |
| `when`                       | Die Node läuft nur, wenn der Ausdruck wahr ist; abhängige Nodes werden mit übersprungen |
| `elseOf`                     | Läuft genau dann, wenn die genannte Node durch ihr eigenes `when` übersprungen wurde    |
| `forEach`                    | Läuft einmal pro Element einer Sammlung, mit `item` und `index` im Zugriff              |
| `repeatUntil` / `maxRepeats` | Wiederholt, bis der Ausdruck wahr ist, mit Deckel (Standard 5, Maximum 20)              |
| `onError`                    | `fail` bricht den Lauf ab; `continue` notiert den Fehler und überspringt Abhängige      |

### Node-Typen

Vier Typen sind eingebaut, und jede Connector-Aktion sowie jede Plattformfunktion — Wissenssuche, Dokumentoperationen — reiht sich in dieselbe Tabelle daneben ein.

**`transform`** führt reines JavaScript aus, um Daten umzuformen. Ohne Netzwerk und ohne Imports: Der Rumpf liest die aufgelöste `input` der Node und muss einen Wert zurückgeben.

**`llm`** ruft ein Sprachmodell mit einem Prompt-Template auf. `model` ist Pflicht und immer ausdrücklich — eine Automatisierung wählt nie eines für dich (das Auto der Chat-Eingabezeile ist eine reine Chat-Sache). Die Ausgabe ist `{text}` oder das Objekt in Form des Schemas, wenn die Node ein `outputSchema` deklariert.

**`agent`** führt einen Agent-Turn eines Coding-Agents (Claude Code, Codex und die übrigen Harnesses) in der Sandbox aus. Er liest bereitgestellte `files`, nutzt `skills`, vermittelte `connectors`, gewährte Plattform-`tools` und eingespielte `secrets` und gibt `{text, files, status}` zurück; `model` ist Pflicht. Hat ein Admin die [Bildgenerierung](https://docs.tale.dev/de/platform/admin/governance/content-models#let-agents-generate-images) eingeschaltet, kann er auch Bilder erstellen, die unter seinen `files` zurückkommen. Greif zu `llm`, wenn eine einmalige Completion reicht, und zu `agent` nur, wenn der Schritt Werkzeuge, Dateien oder mehrere Turns braucht — eine live geschaltete Agent-Node läuft als asynchroner Turn, sitzt daher auf der obersten Ebene statt in einer `subautomation` und iteriert nicht mit `forEach`.

**`subautomation`** führt eine andere gespeicherte Automatisierung als einzelne Node aus; ihr Feld `automation` benennt `"name"` oder `"name@version"`. Ohne Version läuft die live geschaltete, und die Verschachtelung endet bei drei Ebenen.

### Strukturierte und unstrukturierte Ausgabe

Eine **strukturierte** Ausgabe hat benannte Felder, die du über `nodes.<id>.output.<field>` referenzierst. Eine **unstrukturierte** Ausgabe enthält freien Text. Verwende dafür `nodes.<id>.output.text` in einem Textausdruck; behandle die Ausgabe nicht wie ein Objekt mit weiteren Feldern.

Ein Werkzeug ohne Ausgabeschema liefert unstrukturierte Ausgabe. Soll daraus strukturierte Eingabe für weitere Schritte entstehen, nutze eine `llm`-Node mit `outputSchema`. Die Validierung nennt bei einem Fehler die ungültige Referenz und die zulässigen Felder oder Kontexte. Korrigiere die Referenz, bevor du erneut speicherst.

## Versionen ändern sich nie

Speichern legt eine neue Version an, statt die vorige zu überschreiben. Die Nummerierung beginnt für jede Automatisierung bei 1; jede Version enthält die Änderungsnotiz ihres Autors. Der Workflow einer vorhandenen Version bleibt unverändert.

Ein laufender Workflow behält die Version, mit der er gestartet wurde. Spätere Bearbeitungen ändern seine Schritte nicht. Öffne bei der Prüfung eines älteren Laufs dessen aufgezeichnete Version, um Eingabe und Ablauf zu vergleichen. Unveränderlichkeit ist keine unbegrenzte Aufbewahrung: Beim Löschen einer Automatisierung oder ihrer Historie können die Datensätze entfernt werden.

## Live-Schalten ist ein eigener Schritt

Genau eine Version pro Automatisierung ist live, und diese Version führen die Trigger aus. Eine Version live zu schalten oder auf eine ältere zurückzugehen ist ein einzelner Schritt, der keine Historie umschreibt — die Versionsliste bleibt exakt, wie sie war, und nur der Zeiger wandert. Eine Automatisierung darf auch gar nichts live haben und rein als Entwurf existieren.

Eine Version mit einem fehlgeschlagenen Test lässt sich nicht live schalten; eine Version, deren Tests bestanden sind oder die gar keine Tests hat, schon. Tests liegen im Dokument: Jeder hat einen Namen, eine Eingabe und Erwartungen an die Ausgabe sowie an die Auswirkungen, die der Lauf erzeugen soll. Ob die Tests einer Version bestanden waren, wird beim Speichern festgehalten — das Live-Schalten liest diese festgehaltene Tatsache, statt die Suite erneut laufen zu lassen.

<Note>

Ein Live-Lauf braucht eine bereitgestellte Version. Einen gespeicherten Entwurf kannst du vorher mit **Testlauf** prüfen.

</Note>

## Was einen Lauf startet

Eine gespeicherte Version kannst du manuell testen; die bereitgestellte Version lässt sich live ausführen. Für automatische Starts richtest du eine von drei Trigger-Arten ein: einen Zeitplan mit Cron-Ausdruck und IANA-Zeitzone, eine durch ein Token geschützte Webhook-URL oder ein benanntes Plattformereignis.

Der Trigger gehört zum Namen der Automatisierung. Bei einer neuen Bereitstellung bleiben Konfiguration und Webhook-URL erhalten; nachfolgende Starts verwenden die neu bereitgestellte Version. Deaktiviere den Trigger, um automatische Starts zu pausieren. [Workflow-Trigger](https://docs.tale.dev/de/platform/automations/triggers) erklärt Zeitsteuerung, Anmeldung und die Eingabe jeder Trigger-Art.

## Was ein Lauf festhält

Ein Lauf speichert Status (`queued`, `running`, `waiting`, `success`, `failed` oder `cancelled`), Modus, Auslöser, Eingabe, Ausgabe und einen Checkpoint für jede abgeschlossene Node. Die Ablaufspur zeigt die vom Ausführungssystem versuchten Schritte.

Gibt die Verarbeitung vorübergehend ab, setzt derselbe Lauf anhand seiner Checkpoints fort, ohne abgeschlossene Nodes erneut auszuführen. Die Liste der Auswirkungen erfasst Connector-Schreibaktionen. Sie ist kein vollständiges Verzeichnis der Änderungen durch eine Sandbox oder direkte Werkzeuge. Für die Laufhistorie gelten weiterhin Löschung und Aufbewahrungseinstellungen.

Im Modus **Test** werden externe Aktionen simuliert. **Live** kann sie tatsächlich ausführen und benötigt zum Starten Entwicklerrechte. Unter [Ausführungsprotokolle](https://docs.tale.dev/de/platform/automations/execution-logs) erfährst du, wie du gespeicherte Version, aufgelöste Eingaben, Fehler und protokollierte Auswirkungen prüfst.

## Wo ein Mensch entscheidet

Eine erforderliche Freigabe hält den Lauf vor einer geschützten Schreibaktion im Status `waiting` an. Die Freigabe erlaubt den Ausführungsversuch, garantiert aber keinen Erfolg. Ablehnen verhindert die Aktion und lässt den Lauf fehlschlagen. Eine Frage pausiert ebenfalls, verlangt jedoch Informationen statt einer Erlaubnis.

Der Status `waiting` kann auch bedeuten, dass ein Agent noch arbeitet, dass ein Agent-Schritt für seinen Start auf einen Sandbox-Platz wartet oder dass eine Node ihre Bedingung wiederholt prüft. Lies deshalb `waitingFor`: `approval` und `ask` brauchen eine Person; `agent`, `room` und `repeat` setzen normalerweise automatisch fort. [Freigaben in Workflows](https://docs.tale.dev/de/platform/automations/approvals-in-workflows) erklärt, wie du die menschlichen Anfragen prüfst und beantwortest.

## Chat, Aufgabe oder Automatisierung wählen

| Bedarf | Nutze |
| --- | --- |
| Eine Frage stellen und die Antwort besprechen | Chat |
| Ein geprüftes Ergebnis mit Zuständigkeit erstellen | Eine Projektaufgabe, bei Bedarf einem Agenten zugewiesen |
| Abhängige Schritte ausführen oder auf Zeitplan, Webhook oder Ereignis reagieren | Eine Automatisierung |

Prüfe vor dem Erstellen die [mitgelieferten Automatisierungen](https://docs.tale.dev/de/platform/automations/builtin). Ein Webhook startet eine Automatisierung; er ist keine eigene Art von Projektagent.

## Das Modell in die Praxis bringen

Workflow, Versionen, Bereitstellung und Trigger sind getrennte Bestandteile einer Automatisierung. Folge dem [Workflow-Editor](https://docs.tale.dev/de/platform/automations/editor), um eine Änderung zu testen und live zu schalten. Die [Ausführungsprotokolle](https://docs.tale.dev/de/platform/automations/execution-logs) zeigen, was ein Lauf getan hat.

# Der Workflow-Editor
Source: https://docs.tale.dev/de/platform/automations/editor

Im Workflow-Editor änderst du den Ablauf einer Automatisierung und wählst die gespeicherte Version für Live-Läufe. Änderungen brauchen Entwickler-, Admin- oder Inhaberrechte. Speichern, Testen und Bereitstellen sind getrennte Schritte: Die Arbeit an einem Entwurf lässt die bereitgestellte Version bestehen.

Öffne **Automatisierungen** und wähle einen Eintrag. Er öffnet sich im Tab **Editor**. Für einen neuen Ablauf beginne mit [Automatisierungen erstellen oder importieren](https://docs.tale.dev/de/platform/automations/catalog).

| Tab | Wofür du ihn nutzt |
| --- | --- |
| **Editor** | Den Workflow ändern, eine gespeicherte Version testen und die Live-Version wählen. |
| **Allgemein** | Festlegen, was die Automatisierung startet und welche Projekte sie nutzen können. |
| **Läufe** | Die letzten Ausführungen prüfen und den vollständigen Datensatz eines Laufs öffnen. |

Die Auswahl **Version** bleibt auf Desktop und Smartphone rechts neben den Tabs Editor, Allgemein und Läufe. Sie zeigt Versionsnachrichten, Datum, Testergebnisse und die Live-Markierung. Wähle eine Zeile, um diese Version zu öffnen. Am Desktop stehen die Laufaktionen neben den Tabs, zusammen mit **Speichern** und **Verwerfen**; unter **Allgemein** stehen dort nur **Speichern** und **Verwerfen**. Ein Punkt an einem Tab kennzeichnet dessen ungespeicherte Änderungen. Beim Verlassen des Tabs oder einem Versionswechsel fragt Tale, wie du damit fortfahren möchtest.

Auf dem Smartphone startet eine geöffnete Automatisierung mit kompakter Navigation. Die Arbeitsfläche des Editors nutzt die verfügbare Höhe. Lauf- und Bereitstellungsaktionen befinden sich innerhalb der Arbeitsfläche neben den Zoom-Steuerelementen. Wenn du einen Knoten auswählst, öffnen sich seine Felder — mit Speichern und Verwerfen — in einem Bereich am unteren Bildschirmrand.

<Frame caption="Wähle auf einem breiten Bildschirm einen Knoten, um seine Felder neben dem Canvas zu prüfen.">

![Der Workflow-Editor zeigt verbundene Knoten und die Felder des ausgewählten Knotens neben dem Canvas.](https://docs.tale.dev/images/platform/automation-editor-canvas.webp)

</Frame>

Zum Wechseln musst du nicht zur Liste zurück: Klick im Navigationspfad auf den Namen der aktuellen Automatisierung. Das Menü zeigt alle Automatisierungen der Organisation, auch nach einem Wechsel in ein anderes Projekt. Nur eine Automatisierung, die ausschließlich Projekten zugeordnet ist, die du nicht öffnen kannst, fehlt darin. Oben stehen Automatisierungen ohne Projektzuordnung, darunter die mit Projektzuordnung. Eine waagerechte Linie trennt die beiden Gruppen. Such nach Name oder Slug und wähle einen Eintrag. Der aktuelle Tab bleibt geöffnet. Aus einem Laufdetail gelangst du zur Liste **Läufe** der anderen Automatisierung. Eine ausgewählte Versionsnummer wird nicht übernommen: Im **Editor** erscheint deren neueste gespeicherte Version.

## Den Canvas lesen

Jeder Kasten ist ein Knoten. Seine Beschriftung nennt Schritt und Typ; **Liest** zeigt verwendete Ausgaben anderer Knoten. Pfeile entstehen aus Referenzen wie `{{ nodes.draft.output.text }}`. Ändere die Referenz, um eine Abhängigkeit zu ändern. Das Zeichnen eines Pfeils erstellt keine Abhängigkeit.

Kennzeichnungen zeigen Bedingungen und Schleifen wie `when`, `else of`, `for each`, `repeat until` und `continue on error`. Eine Zykluswarnung bedeutet, dass mehrere Knoten voneinander abhängen. Entferne die kreisförmige Referenz, bevor du eine ausführbare Version speicherst.

## Einen Knoten bearbeiten

Wähle einen Kasten, um seine Felder zu öffnen. Auf einem breiten Bildschirm erscheint der Bereich neben dem Canvas; ohne ausgewählten Knoten nutzt der Canvas die ganze Breite. Auf schmaleren Bildschirmen öffnen sich die Felder in einem Dialog über dem Canvas. Ein `transform` hat **Code**, ein `llm` Felder für Prompt, Modell und Ausgabeschema. Ein `agent` ergänzt Harness und Ausstattung. Die **Modell**-Auswahl einer `llm`- oder `agent`-Node listet die Modelle, die die verbundenen Anbieter deiner Organisation bedienen; ein nicht aufgeführtes Modell lässt sich eingeben, doch die Validierung warnt, dass ein Live-Lauf an dieser Node fehlschlägt, bis sein Anbieter verbunden ist. **Eingabe** enthält JSON-Werte und Referenzen für diesen Knoten. Unvollständiges JSON wird gemeldet und ändert den Knoten nicht.

Öffne **Ablaufsteuerung** für Bedingungen und Wiederholungen. Hat der Knoten welche, ist der Abschnitt schon offen. Mit **Schließen** kehrst du zum Canvas zurück. Auf einem breiten Bildschirm schließt sich der Bereich auch, wenn du auf den leeren Canvas klickst oder Escape außerhalb eines Textfelds drückst. Trigger und Projekteinstellungen der Automatisierung findest du im Tab **Allgemein**. [Automatisierungsgrundlagen](https://docs.tale.dev/de/platform/automations/concepts) erklärt Knotentypen und Ausdrücke.

## Eine Version speichern und testen

1. Ändere die nötigen Felder und klicke auf **Speichern**.
2. Erkläre die Änderung in der **Versionsnachricht** und wähle **Version speichern**. Eine neue Version entsteht; frühere Fassungen bleiben erhalten. Hat jemand während deiner Bearbeitung eine andere Version gespeichert, lehnt Tale das Speichern ab und fragt nach: **Meine Änderungen verwerfen und neu laden** zeigt die neuere Version, **Trotzdem speichern** legt deine Version darüber an — die neuere bleibt im Versionsverlauf, die aktuelle Version ist dann aber deine.
3. Klicke auf **Testlauf**. Hat der Workflow ein Eingabeschema, fülle im Dialog **Eingabe für den Lauf (JSON)** aus. Öffne **Eingabeschema**, um Pflichtfelder und Typen zu prüfen. Ungültiges JSON oder unpassende Werte verhindern den Start.
4. Starte den Test, wechsle zum Tab **Läufe** und öffne seinen Eintrag. Vergleiche aufgelöste Eingabe, Ausgabe und geplante Aktionen mit dem erwarteten Ergebnis.

Braucht ein Workflow `owner` und `repo`, könnte seine Eingabe so aussehen:

```json
{
  "owner": "your-organization",
  "repo": "your-repository"
}
```

Maßgeblich ist das tatsächliche Schema des Workflows. Ein Zahlenfeld braucht eine JSON-Zahl, keinen Text in Anführungszeichen. Prüfe auch den Projektumfang, wenn ein Projektwähler angeboten wird.

**Testlauf** führt die gewählte gespeicherte Version mit deterministischen Mocks aus. Er sendet keine E-Mails und ändert keine externen Datensätze. Ein Entwurf lässt sich vor der Bereitstellung testen. Ein erfolgreicher Mock prüft keine echten Zugangsdaten oder externen Dienste.

<Frame caption="Hat der Workflow Eingaben, gib JSON an und prüfe sein Schema vor dem Teststart.">

![Der Testlauf-Dialog zeigt JSON-Werte für owner und repo und das aufgeklappte Eingabeschema.](https://docs.tale.dev/images/platform/automation-run-input.webp)

</Frame>

## Bereitstellen und live ausführen

Wähle die getestete Fassung unter **Version** und klicke auf die Schaltfläche daneben, die diese Version nennt, etwa **v3 live schalten**. Die Kennzeichnung **Live** markiert die bereitgestellte Version. Sind die gespeicherten Tests einer Version fehlgeschlagen, lässt sie sich nicht bereitstellen. Behebe die Ursache und speichere eine neue Version.

**Live ausführen** startet die bereitgestellte Version, auch wenn du eine andere ansiehst. Die Bestätigung zeigt den Umfang und bei Bedarf **Eingabe für den Lauf (JSON)** für genau diese Version. Prüfe beides vor dem Bestätigen. Live-Läufe können verbundene Systeme verändern und auf eine [Freigabe](https://docs.tale.dev/de/platform/approvals/concepts) warten.

Ein Trigger nutzt ebenfalls die bereitgestellte Version. Richte ihn ein, wenn wiederholte oder extern ausgelöste Läufe gewünscht sind; siehe [Automatisierungstrigger](https://docs.tale.dev/de/platform/automations/triggers).

## Ein Ergebnis untersuchen

**Letzten Lauf anzeigen** legt Laufzustände über den Canvas. Wähle einen Knoten für die Angaben zu diesem Lauf: aufgelöste Eingabe, Ausgabe und Effekte. Häufig findest du so eine falsche Referenz. Vergleiche die Eingabe des fehlgeschlagenen Knotens mit der Ausgabe seiner Quelle.

Wechsle zu **Läufe** und öffne den vollständigen Datensatz. Die Tabs bleiben sichtbar; **Läufe** ist aktiv. Mit **Editor** kehrst du zum Workflow zurück. Prüfe Test- oder Live-Modus und bereits ausgeführte Aktionen, bevor du erneut startest. [Ausführungsprotokolle](https://docs.tale.dev/de/platform/automations/execution-logs) erklärt Wartezustände, Fehler, automatische Wiederholungen und Abbruch.

## Zu einer früheren Version zurückkehren oder löschen

Öffne für eine Rückkehr **Version** rechts neben den Tabs, lies die Versionsnachrichten und wähle eine frühere Fassung. Die Zeile öffnet den **Editor** mit dieser Version. Klicke dort auf die Schaltfläche, die sie live schaltet, etwa **v2 live schalten**. Künftige Starts verwenden sie; der Versionsverlauf bleibt erhalten. Eine Nachricht wie „Vorherige Empfängerzuordnung wiederherstellen“ macht die Entscheidung nachvollziehbar.

Zum Löschen gehe zur Liste zurück, öffne das Zeilenmenü und wähle **Löschen**. Lies die Bestätigung mit dem Namen der Automatisierung. Versionen, Bereitstellung, Trigger und Projektzuordnungen werden entfernt. Ein offener Lauf blockiert das Löschen; beende ihn oder warte seinen Abschluss ab. Frühere Läufe unterliegen weiter der Aufbewahrung. Bereits ausgeführte Aktionen werden durch das Löschen nicht rückgängig gemacht.

# Automatisierungsläufe prüfen und Fehler beheben
Source: https://docs.tale.dev/de/platform/automations/execution-logs

Öffne eine Automatisierung, wechsle zum Tab **Läufe** und wähle einen Eintrag. Prüfe zuerst Status, Version und Modus, dann die betroffene Node. Ein erfolgreicher Testlauf belegt den simulierten Ablauf. Er beweist nicht, dass ein echtes externes Konto dieselbe Aktion akzeptiert.

<Frame caption="Ein abgeschlossener Testlauf: Status, Modus, Version, Starter und Zeiten über dem Workflow, mit dem Ergebnis jeder Node.">

![Die Seite eines Testlaufs von Triage GitHub issues, markiert mit Succeeded, Test und v1 und von dir gestartet, mit Start- und Endzeit über dem Workflow-Graphen, in dem die Nodes issues, open issues, score und report jeweils Ran zeigen; unter dem Graphen beginnt die Liste der Auswirkungen des Laufs.](https://docs.tale.dev/images/platform/automation-run-detail.webp)

</Frame>

## Den Laufstatus lesen

Der Tab **Läufe** zeigt die letzten 50 Läufe, die du sehen kannst, neueste zuerst. Läufe der Organisation selbst sehen Inhaber, Admins und Entwickler. Einen Lauf in einem Projekt und die Frage, auf die er wartet, sehen nur diejenigen von ihnen, die dieses Projekt öffnen können. Jede Zeile nennt Version, Zeitpunkt, Modus und Auslöser oder eine Fehler- beziehungsweise Wartebegründung. Im Detail siehst du Workflow, Node-Ergebnisse und Laufzeiten. Ein nicht abgeschlossener Lauf hat keinen Endzeitpunkt. Die Tabs bleiben beim Prüfen eines Laufs sichtbar. Mit **Läufe** kehrst du zur Liste zurück, mit **Editor** zum Bearbeiten des Workflows.

| Status | Bedeutung | Nächster Schritt |
| --- | --- | --- |
| **In der Warteschlange** | Angenommen, wartet auf die Ausführung. | Warte und prüfe bei ausbleibendem Fortschritt die Kapazität. |
| **Läuft** | Der Ablauf wird verarbeitet. | Beobachte den Fortschritt der Nodes. |
| **Wartet** | Entscheidung, Antwort, Agentenarbeit oder Abfragebedingung steht aus. | Lies, worauf der Lauf wartet. |
| **Erfolgreich** | Erreichte Nodes sind abgeschlossen und die Ausgabe liegt vor. | Prüfe Ausgabe und Auswirkungen. |
| **Fehlgeschlagen** | Der Lauf endete mit einem unbehandelten Fehler. | Öffne die betroffene Node und lies ihren Fehler. |
| **Gestoppt** | Der Lauf wurde abgebrochen. | Prüfe bereits ausgeführte Arbeit vor einem Neustart. |

Eine ausstehende Freigabe oder Frage braucht eine Person. Ein arbeitender Agent oder eine wiederholte Abfrage kann ohne Eingriff fortfahren. Eine Entscheidung oder Antwort kann auch abgelehnt werden oder ablaufen. Entscheide anhand der Begründung, nicht allein nach **Wartet**. [Freigaben in Workflows](https://docs.tale.dev/de/platform/automations/approvals-in-workflows) erklärt die Entscheidungsfelder.

## Die betroffene Node untersuchen

Wähle eine Node auf dem Canvas des Laufs. **Aufgelöste Eingabe** zeigt die Werte nach der Vorlagenauswertung, **Ausgabe** das Ergebnis des Schritts. So unterscheidest du einen falschen Verweis von einem Dienstausfall.

Node-Zustände sind unter anderem **Gelaufen**, **Übersprungen**, **Fehlgeschlagen**, **Nie erreicht**, **Noch nicht erreicht** und bei einem gestoppten Lauf **Hier gestoppt** für die Node, an der der Lauf beim Stoppen stand. Eine Node kann wegen einer falschen Bedingung, einer Abhängigkeit, eines anderen Zweigs oder einer Weiterlaufregel übersprungen werden. Das ist nicht immer ein Fehler.

Beispielsweise kann eine Erinnerungs-Node den Kundennamen, aber eine leere Rechnungs-ID erhalten. Prüfe die Ausgabe davor. Verwendet der Datensatz inzwischen ein anderes Feld, korrigiere den Verweis statt der Mail-Zugangsdaten. Prüfe danach die aufgelöste Eingabe in einem neuen Testlauf.

Anwendungen erhalten über die [Lauf-API](https://docs.tale.dev/de/develop/api-reference) zusätzlich `failureCode`, wenn die Ursache eines fehlgeschlagenen Laufs klassifiziert wurde. `approval_rejected` bedeutet etwa, dass eine Person die Aktion abgelehnt hat; bei `llm_output_invalid` entsprach die Modellantwort nicht der geforderten Struktur. Ältere Fehler können ohne Code vorliegen. Der Code hilft bei der Untersuchung, belegt aber weder die Unbedenklichkeit noch den Erfolg eines neuen Versuchs.

## Bereits erfolgte Änderungen prüfen

Die Auswirkungen protokollieren Connector-Schreibvorgänge mit Node, Connector und Eingabe. Tests verwenden festgelegte Ersatzantworten; Live-Aktionen können externe Systeme ändern. Fehlen protokollierte Auswirkungen, zeigt der Lauf das ausdrücklich an.

Lies diese Liste vor einer Wiederholung. Ein späterer Fehler macht eine frühere Nachricht oder Änderung nicht rückgängig. Ist die Zustellung entscheidend, prüfe auch den empfangenden Dienst. Die Auswirkungen bleiben beim Lauf, bis Löschung oder Aufbewahrungsregeln den Datensatz entfernen. Sie sind kein eigenständiges dauerhaftes Archiv. Wird die Automatisierung gelöscht, bleiben ihre Läufe: Die Laufseite öffnet weiterhin, mit dem Löschdatum markiert und aus der Aufzeichnung des Laufs gezeichnet, bis die Aufbewahrung sie entfernt.

## Fortsetzung und automatische Wiederholungen verstehen

Der Ablauf speichert abgeschlossene Nodes als Checkpoints und setzt danach fort. Geht eine Fortsetzung verloren, kann der nicht abgeschlossene Lauf nach einer Wartefrist wieder aufgenommen werden. Ein separater neuer Lauf besitzt eigene Checkpoints und kann Schreibvorgänge wiederholen. Neu starten ist deshalb etwas anderes als den bestehenden Lauf fortzusetzen.

Ein geeigneter Agentenfehler erlaubt nach dem ersten Versuch bis zu drei automatische Wiederholungen. Frühere Checkpoints bleiben erhalten; der Kopfbereich zeigt den Wiederholungszähler. Arbeitet ein Versuch mindestens fünfzehn Minuten, wird dieses Wiederholungsbudget erneuert. Abonnement-Pools können für einen neuen Versuch ein anderes Konto wählen. Hat ein Abo-Broker das Konto erneuert, während der Schritt arbeitete, und lehnt der Anbieter deshalb das alte Token ab, läuft die Wiederholung mit einem neuen Token weiter, ohne eine der drei Wiederholungen zu verbrauchen; eine dritte solche Unterbrechung in Folge zählt wie jeder andere Fehler. Konnte der Schritt nicht starten, weil alle Konten des Pools nach Erreichen eines Rate-Limits pausierten, beginnt die Wiederholung, sobald das erste Konto wieder verfügbar ist, spätestens eine Minute später, und setzt die Konversation fort, die der abgelehnte Versuch fortsetzen sollte. Diese Wartezeit verbraucht eine der drei Wiederholungen, außer der abgelehnte Versuch wiederholte selbst einen Fehler durch ein Rate-Limit. Hatte der fehlgeschlagene Versuch seine Konversation bereits angekündigt, setzt die Wiederholung genau diese Konversation über dem erhaltenen Arbeitsbereich fort – der Agent macht dort weiter, wo der Abbruch ihn traf, statt von vorn zu überlegen; ein Versuch, der vorher starb oder dessen Sandbox-Sitzung verschwunden ist, beginnt neu. Ein Schritt mit Gemini CLI beginnt immer neu, weil diese Laufzeit eine Konversation mit einem Werkzeugaufruf nicht wiederaufnehmen kann; [Eine Agent-Laufzeit wählen](https://docs.tale.dev/de/platform/agents/harnesses) erklärt die Ausnahme.

Ein Agentenschritt schlägt auch fehl, wenn sein Modell überhaupt nichts liefert: keinen Text, keinen Tool-Aufruf und keine erzeugten Tokens. So kann ein Modellserver antworten, der mitten in der Antwort ausfällt. Der Lauf meldet dann auf Englisch „The model returned an empty answer, so the agent did nothing this turn.“ Auch dieser Fehler erhält diese Wiederholungen. Hat das Modell nur Tools verwendet oder erzeugte Tokens ohne sichtbaren Text gemeldet, etwa für Denkschritte, gilt das als Antwort. Der Schritt scheitert dann nicht aus diesem Grund.

Ein ausgeschöpftes Ausführungszeitfenster, eine abgelaufene Frage oder eine Ablehnung wegen des Budgets erhält diese Wiederholungen nicht. Jeder Versuch verbraucht eigene Ressourcen; frühere Kosten entfallen nicht. Kann ein erneuter Versuch die Ursache nicht beheben, stoppe den Lauf und korrigiere die Abhängigkeit vor dem Neustart.

## Stoppen oder den Workflow korrigieren

Wähle bei einem nicht abgeschlossenen Lauf **Lauf stoppen**, wenn du ihn abbrechen möchtest, und bestätige. Der Abbruch verhindert weitere Arbeit an den Ausführungsgrenzen des Ablaufs. Bereits erfolgte Änderungen werden nicht zurückgesetzt. Endet der Lauf, bevor der Abbruch ihn erreicht, bleibt sein abgeschlossenes Ergebnis erhalten.

Korrigiere einen Dokumentfehler im Editor an der betroffenen Eingabe oder Node und speichere eine Version mit aussagekräftiger Nachricht. Teste mit typischen Eingaben und prüfe Werte und Ausgabe, nicht nur den Erfolgsstatus. Schalte die geprüfte Version live. Zeitpläne und Webhooks verwenden danach diese Version; der ältere fehlgeschlagene Lauf dokumentiert weiterhin die alte.

Ist gar kein Lauf entstanden, prüfe den [Trigger](https://docs.tale.dev/de/platform/automations/triggers). Ein deaktivierter Trigger, eine fehlende Live-Version oder abgelehnte Eingaben können den Start verhindert haben.

# Automatisierungen automatisch starten
Source: https://docs.tale.dev/de/platform/automations/triggers

Im Abschnitt **Trigger** im Tab **Allgemein** einer Automatisierung legst du fest, wann sie selbstständig startet. Jeder Trigger führt die Live-Version im Live-Modus aus. Teste den Workflow vorher mit der tatsächlich gelieferten Eingabestruktur und prüfe seine externen Aktionen.

<Frame caption="Der Tab Allgemein eines mitgelieferten Pakets: Sein Zeitplan-Trigger ist eingeschaltet, startet aber nichts, solange keine Version bereitgestellt ist.">

![Der Tab Allgemein von Triage the Gmail inbox mit einem eingeschalteten Trigger vom Typ Schedule, dem Cron-Ausdruck 0 */6 * * *, beschrieben als alle sechs Stunden und ohne Start, bevor eine Version bereitgestellt ist, der Zeitzone UTC und darunter einer leeren Projektauswahl.](https://docs.tale.dev/images/platform/automation-general-trigger.webp)

</Frame>

## Den Auslöser wählen

| Trigger-Typ | Geeignet für | Eingabe des Laufs |
| --- | --- | --- |
| **Zeitplan** | Wiederkehrende Arbeit zu einer Ortszeit oder in festen Abständen. | `{ trigger: "schedule", firedAt: <epoch ms> }` |
| **Webhook** | Zustellungen eines anderen Systems. | `{ trigger: "webhook", payload: … }` |
| **Plattform-Ereignis** | Ein benanntes Ereignis innerhalb der Organisation. | `{ trigger: "event", event: "…", payload: … }` |

Eine Automatisierung hat jeweils einen konfigurierten Trigger. Ein anderer Typ ersetzt die bisherige Bindung. Ersetzt du einen Webhook, wird seine URL sofort ungültig. Ein später angelegter Webhook stellt diese Zugangsdaten nicht wieder her.

API- und MCP-Clients können auch ohne Trigger starten. API-Schlüssel und Projektberechtigungen autorisieren den Aufruf; der Client übergibt die Workflow-Eingabe direkt. Näheres steht in der [API-Referenz](https://docs.tale.dev/de/develop/api-reference).

## Einen Zeitplan einrichten

<Steps>

<Step title="Trigger-Einstellungen öffnen">

Öffne die Automatisierung und darin den Tab **Allgemein**. Ohne Bindung steht im Abschnitt **Trigger**, dass die Automatisierung nur von Hand oder über die API läuft; wähle **Trigger hinzufügen** und dann unter **Trigger-Typ** den **Zeitplan**. Ein neuer Trigger ist zunächst nicht **Aktiv** — lass ihn ausgeschaltet, solange der Workflow noch nicht selbstständig starten soll.

</Step>

<Step title="Zeitpunkt eingeben">

Fülle **Cron** aus und wähle die **Zeitzone**. Die fünf Cron-Felder bedeuten Minute, Stunde, Tag des Monats, Monat und Wochentag. Nutze eine IANA-Zeitzone wie `Europe/Zurich`, wenn die örtliche Geschäftszeit zählt. Ohne Angabe gilt UTC.

</Step>

<Step title="Prüfen und speichern">

Prüfe den nächsten angezeigten Zeitpunkt: Es ist die Minute, in der der Zeitplan tatsächlich startet, auch über eine Zeitumstellung hinweg. Klick dann neben den Tabs auf **Speichern**. Kontrolliere, ob die Live-Version die oben gezeigte Zeitplan-Eingabe akzeptiert. Schalte den fertigen Trigger mit **Aktiv** ein und speichere erneut. Den nächsten gestarteten Lauf findest du unter **Läufe**.

</Step>

</Steps>

```text
*/15 * * * *     alle fünfzehn Minuten
0 9 * * 1-5      werktags um 09:00 Uhr
0 6 1 * *        am Monatsersten um 06:00 Uhr
30 8 1 * 1       am Monatsersten und jeden Montag um 08:30 Uhr
```

Die Felder erlauben `*`, Zahlen, Bereiche, Schrittweiten und kommagetrennte Listen. 0 und 7 stehen beide für Sonntag. Sind Monatstag und Wochentag eingeschränkt, genügt eine Übereinstimmung. Das letzte Beispiel läuft daher montags und am ersten Tag jedes Monats.

Die Ortszeit folgt den Sommerzeitregeln der Zeitzone. Ein Zürcher Zeitplan für 09:00 Uhr bleibt örtlich bei 09:00 Uhr. Die Auflösung beträgt eine Minute. Während eines Ausfalls verpasste Termine werden nicht nachgeholt; der nächste reguläre Termin setzt den Betrieb fort. Unmögliche Kalenderdaten werden beim Speichern abgelehnt.

## Einen Webhook empfangen

Wähle **Webhook** und speichere, um die Zugangsdaten zu erzeugen. Kopiere die vollständige URL, sobald sie erscheint. Der Token wird einmal gezeigt und nur als Hash gespeichert. Der Abschnitt bietet eine Organisations-URL und ein Muster für Projekt-URLs. Nutze für ein aktives Projekt mit installierter Automatisierung die Projekt-URL. Eine Automatisierung mit Projektzuordnung kann nicht über die reine Organisations-URL starten.

Sende eine kleine Nutzlast an die URL. JSON landet als `payload` innerhalb der Eingabe, nicht unmittelbar auf deren oberster Ebene. Andere Anfrageinhalte werden als Text weitergereicht. Die Grenze liegt bei 256 KiB; große Dokumente lädst du separat hoch. Eine angenommene Anfrage liefert die Lauf-ID, ohne auf das Ende zu warten.

Die gesendete Nutzlast `{ "invoiceId": "inv-1" }` erreicht den Workflow beispielsweise so:

```json
{
  "trigger": "webhook",
  "payload": { "invoiceId": "inv-1" }
}
```

Verwende eine Zustellungs-ID, etwa `Idempotency-Key` oder einen unterstützten Header des Absenders. Dieselbe ID liefert innerhalb von 24 Stunden den ursprünglichen Lauf zurück. Ohne ID gilt ein identischer Inhalt an derselben URL innerhalb von zwei Minuten als Duplikat. Vergib unterschiedliche IDs, wenn identische Inhalte getrennte Arbeit bedeuten. [Webhooks](https://docs.tale.dev/de/develop/webhooks) beschreibt Header, Projektpfade, Fehler und Antwortformate.

<Warning>

Die URL berechtigt zum Start. Bewahre sie wie Zugangsdaten auf und gib sie nur dem sendenden System. **Token rotieren** erzeugt einen Ersatz und macht die alte URL ungültig. Entfernen oder Ersetzen des Triggers widerruft sie ebenfalls. Aktualisiere den Absender nach einer Rotation.

</Warning>

## Auf ein Plattform-Ereignis reagieren

Wähle **Plattform-Ereignis** und unter **Ereignisname** das Ereignis. Speichere und aktiviere den fertigen Trigger. Das Eingabeschema muss die Struktur mit `trigger`, `event` und `payload` aus der Tabelle akzeptieren. Von Automatisierungsläufen ausgelöste Ereignisse starten keine Trigger. So erzeugt ein Workflow durch seine eigenen Änderungen keine endlose Startschleife.

Erwartet ein Workflow Pflichtfelder wie `owner` und `repo` auf oberster Ebene, passen Zeitplan-Metadaten oder eine eingepackte Webhook-Nutzlast nicht unverändert dazu. Passe Schema und Verweise an oder starte per API mit diesen Feldern. Die Trigger-Einstellungen bieten keine frei definierbaren gespeicherten Eingabefelder.

## Einen Projektagenten nach Zeitplan starten

Ein Zeitplan kann einen der bestehenden Agenten eines Projekts an die Arbeit schicken: für eine Daueraufgabe, über die der Agent bei jedem Termin berichtet, oder für wiederkehrende Arbeit, die du sonst von Hand starten würdest. Installiere die Automatisierung im Projekt der Aufgabe, füge einen Schritt `task.start_agent` hinzu, der die Aufgabe nennt, und gib der Automatisierung einen Zeitplan. Jeder Termin startet den Agenten, der für die Aufgabe zuständig ist, oder weist die Aufgabe zuerst dem Agenten zu, den `agentId` nennt; dieser muss zum selben Projekt gehören. `feedback` ist die Nachricht, auf die der Lauf als Erstes eingeht, etwa die Angabe des Termins, für den er läuft:

```yaml
nodes:
  - id: start
    type: task.start_agent
    input:
      taskId: <ID der Aufgabe>
      moveToInProgress: false
      feedback: 'Scheduled occurrence {{ input.firedAt }}.'
```

Der Schritt liefert den gestarteten Lauf zurück, und die Zeitleiste der Aufgabe führt diesen Lauf als **Automatisierung** mit einem Link zum Automatisierungslauf. Startet der Schritt nichts, ist er trotzdem erfolgreich und nennt den Grund. So bleibt der Termin festgehalten, statt für später eingereiht zu werden:

| Antwort | Bedeutung |
| --- | --- |
| `started: true` | Der Lauf des Agenten wurde gestartet; `runId` nennt ihn. |
| `already_running` | Der vorherige Lauf der Aufgabe arbeitet noch und trägt die Arbeit weiter. Es startet nichts Neues, und der Termin wartet nicht darauf, dass dieser Lauf endet. |
| `in_review` | Mit `moveToInProgress: false` wartet die Karte auf ihren erfassten Prüfer, eine Person oder einen Agenten. Es wird nichts zugewiesen oder gestartet, und die Prüfung behält diesen Empfänger. |
| `closed` | Mit `moveToInProgress: false` steht die Karte auf **Erledigt** oder **Abgebrochen** (`taskStatus`). Es wird nichts zugewiesen oder gestartet. |
| `agent_busy` | Der Agent arbeitet an einer anderen Aufgabe (`busyTaskId`). Ein Agent bearbeitet in seinem Arbeitsbereich jeweils nur eine Aufgabe. |
| `blocked` | Eine Aufgabe, von der diese abhängt, ist noch offen (`blockedBy`). |
| `paused` | Die Aufgabe hat in der letzten Stunde schon drei Starts durch Automatisierungen und Agenten erhalten, gewöhnliche automatische Wiederholungen eingerechnet. Eine Broker-Wartezeit unmittelbar nach einem HTTP-429-Fehler desselben Agenten erhöht die Zahl nicht; aufeinanderfolgende Wartezeiten zählen weiterhin. `retryAfter` gibt an, wann die Stundengrenze einen weiteren Start zulässt; die übrigen Startprüfungen gelten weiterhin. |

Ein Lauf, den ein Zeitplan startet, arbeitet in niemandes Auftrag. Er nutzt die konfigurierten Anweisungen, Secrets und Tools des Agenten, und seine Kosten zählen als Automatisierungskosten gegen die Limits der Organisation. Connector-Aktionen, die er über die Plattform ausführen lässt, erfolgen in niemandes Namen und werden deshalb abgelehnt. Diese Befugnis behält er nur, solange der Zeitplan im Projekt handeln darf: Schaltest du den Zeitplan aus, entfernst du ihn oder deinstallierst du die Automatisierung aus dem Projekt, unterbleibt der nächste Start, ein noch nicht angelaufener Lauf schlägt fehl, und ein bereits arbeitender Lauf verliert die Tools seines Arbeitsbereichs. Startet eine Person die Automatisierung selbst, arbeitet der Lauf stattdessen in ihrem Auftrag, solange sie das Projekt bearbeiten darf. Ein Lauf, den ein Webhook oder ein Plattform-Ereignis gestartet hat, kann keine Agenten starten, und eine Automatisierung, die nicht im Projekt der Aufgabe installiert ist, erreicht dessen Agenten nicht.

`moveToInProgress` entscheidet, was mit der Karte geschieht. Standardmäßig wandert sie nach **In Bearbeitung**, und das Ergebnis wartet unter **In Prüfung** auf seinen [festgelegten Prüfer](https://docs.tale.dev/de/platform/projects/tasks#review-default), wie nach **Agent starten**; eine Prüfung, die zur früheren Arbeit noch offen ist, wird zurückgezogen, nie genehmigt. Mit `false` bleibt die Karte, wo sie ist, und der Lauf verlangt keine Prüfung; das passt zu einer Daueraufgabe unter **Zu erledigen**. Der Lauf behält diese Wahl bis zum Ende: Wenn er fertig ist, kommen sein Bericht und seine Dateien wie gewohnt an, und die Karte wird weder verschoben noch zur Prüfung geschickt, auch wenn sie inzwischen jemand nach **In Bearbeitung** verschoben hat. Ein solcher Start läuft nur unter offener Arbeit (**Backlog**, **Zu erledigen** oder **In Bearbeitung**): Eine Karte, die unter **In Prüfung** wartet, antwortet `in_review`, eine abgeschlossene `closed`. So stellt die Karte nie frühere Arbeit zur Beurteilung oder als erledigt dar, während darunter neue Arbeit läuft.

Bei dafür geeigneten Fehlern kann der Lauf automatisch wiederholt werden, solange Status und Zuweisung der Aufgabe unverändert bleiben und seit dem Start keine neue Status-, Zuweisungs-, Archivierungs- oder Prüfentscheidung getroffen wurde. Auch wenn du einen Wert änderst und danach zurücksetzt, endet diese Wiederholung; Kommentare beenden sie nicht. Die Grenzen für Wiederholungen, die Berechtigungen des Zeitplans und die Prüfungen des Arbeitsbereichs gelten weiterhin. Ein späterer Termin kann neue Arbeit starten, sobald die Voraussetzungen erfüllt sind.

### Jedes Issue nach Zeitplan importieren

Ein Issue-Import liest pro Lauf höchstens einen Stapel mit bis zu 500 Issues und meldet, wo der nächste Stapel beginnt. Eine Person setzt ihn mit **Import fortsetzen** fort; ein Zeitplan merkt sich die Position stattdessen zwischen seinen Terminen. So importiert jeder Termin einen Stapel ab der Stelle, an der der vorherige aufgehört hat, bis alle offenen Issues gelesen sind, und der Termin danach beginnt den nächsten Durchgang. Lies die Position mit `task.get_import_cursor`, gib sie an den Import weiter und speichere dessen `nextCursor` mit `task.save_import_cursor`:

```yaml
nodes:
  - id: position
    type: task.get_import_cursor
    onError: continue
    input: { projectId: <the project's ID>, externalSystem: github, source: owner/repo }
  - id: issues
    type: subautomation
    automation: github-import-issues
    onError: continue
    input:
      projectId: <the project's ID>
      owner: owner
      repo: repo
      limit: 500
      cursor: '{{ nodes.position.output.cursor }}'
  - id: progress
    type: task.save_import_cursor
    onError: continue
    input:
      projectId: <the project's ID>
      externalSystem: github
      source: owner/repo
      revision: '{{ nodes.position.output.revision }}'
      next: '{{ nodes.issues.output.nextCursor ?? "" }}'
```

`source` ist dein Name für die Liste; Automatisierungen, die dieselbe Quelle nennen, teilen sich einen Durchgang. Das Lesen liefert außerdem `revision`, das Vergleichsmerkmal der Position, und das Speichern gibt es zurück: Die Position rückt nur vor, solange sie noch auf dieser Revision steht. Jeder gespeicherte Stapel, jeder Abschluss eines Durchgangs und jeder Neubeginn setzt eine neue Revision, und keine Revision wiederholt sich, auch wenn der Cursor-Text es tut. Ein fehlgeschlagener Import speichert nichts, also wiederholt der nächste Termin denselben Stapel. Ein Speichern mit einer früheren Revision wird abgelehnt (`conflict`) und schreibt nichts, ob es von einem überlappenden Lauf stammt, von einem Lauf, der sich über das Ende seines Durchgangs hinaus verspätet hat, oder von einem Lauf, der noch eine Position von vor einem Neubeginn hält. Nach drei Lesevorgängen einer Position ohne Speichern beginnt der nächste den Durchgang neu (`restarted`), statt eine Position zu wiederholen, die die Quelle immer wieder ablehnt, etwa nach der Umbenennung des Repositorys. Das Speichern meldet `batch` und `drained`, die ein Beleg angeben kann. Jeder Lauf aktualisiert außerdem bis zu 500 früher importierte Issues, die am längsten ungeprüften zuerst, sodass eine große Sammlung über mehrere Termine aktualisiert wird.

## Einen ausgebliebenen Start untersuchen

Prüfe zuerst **Aktiv**, die Live-Version und den letzten Auslösezeitpunkt. Lies anschließend einen gegebenenfalls protokollierten Grund:

| Grund oder Symptom | Was du prüfst |
| --- | --- |
| `not_deployed` | Schalte eine getestete Version live. Ein gespeicherter Entwurf reicht nicht. |
| `start_refused` | Vergleiche das Eingabeschema der Live-Version mit der Trigger-Struktur und behebe den gemeldeten Start- oder Validierungsfehler. |
| `unusable_cron` | Korrigiere Ausdruck oder Zeitzone und speichere erneut. Andere Zeitpläne laufen währenddessen weiter. |
| `paused_after_failures` | Der Zeitplan hat sich nach wiederholten Fehlern selbst ausgeschaltet. Siehe [Wenn sich ein Zeitplan selbst pausiert](https://docs.tale.dev/de/platform/automations/triggers#wenn-sich-ein-zeitplan-selbst-pausiert). |
| Webhook-Zugang abgelehnt | Prüfe aktuelle URL und Aktivierung. Unbekannte und deaktivierte Tokens liefern absichtlich dieselbe Ablehnung. |
| Lauf vorhanden, aber nicht beendet | Öffne die [Ausführungsprotokolle](https://docs.tale.dev/de/platform/automations/execution-logs). Der Start gelang; das Problem liegt im Lauf. |

Der letzte Auslösezeitpunkt ändert sich erst bei einem tatsächlichen Start. Ein fälliger Trigger, der nicht starten kann, protokolliert stattdessen den ausgelassenen Start. So erkennst du den Unterschied zu einem gestarteten Workflow, der später scheitert.

## Wenn sich ein Zeitplan selbst pausiert

Scheitern die Läufe eines Zeitplans bei jedem Termin auf dieselbe Weise, würde er sonst endlos weiter fehlschlagen. Tale zählt deshalb die Läufe eines Triggers, die an einem Fehler scheitern, den ein erneuter Versuch nicht behebt: am eigenen Code der Automatisierung (`node_error`), an einem Connector (`connector_error`), an einer Modellantwort, die nicht zu ihrem Schema passt (`llm_output_invalid`), oder am Modellanbieter der Organisation (`auth_error`, `missing_api_key`, `credit_exhausted`, `model_not_found`). Ein erfolgreicher Lauf setzt die Zählung zurück. Andere Fehler, etwa ein Ratenlimit oder ein nicht erreichbarer Anbieter, zählen nicht mit und setzen die Zählung auch nicht zurück. Hat sich ein Zeitplan bereits selbst pausiert, behält er die Zählung, die zur Pause geführt hat, auch wenn ein Lauf, der zu diesem Zeitpunkt noch lief, danach erfolgreich endet. Erst das Speichern des Triggers setzt die Zählung zurück.

Nach fünf solchen Fehlern in Folge schaltet der Zeitplan **Aktiv** aus und protokolliert `paused_after_failures`. Der Abschnitt **Trigger** zeigt dann die Pause, Code und Zeitpunkt des letzten Fehlers sowie **Lauf ansehen**, das diesen Lauf öffnet. Scheitern Läufe, während der Zeitplan noch aktiv ist, zeigt der Abschnitt, wie viele nacheinander fehlgeschlagen sind. Inhaber und Admins erhalten eine Benachrichtigung über die Glocke, per E-Mail zusätzlich, wenn die Organisation ein verbundenes Postfach hat; das Audit-Log hält die Pause fest. Unter **Einstellungen > Benachrichtigungen** können sie diese Hinweise mit **Automatisierungs-Warnungen** abschalten.

Öffne den fehlgeschlagenen Lauf, lies den Fehler und behebe ihn in der Automatisierung oder in ihrer Verbindung. Schalte danach **Aktiv** ein und speichere. Jedes Speichern des Triggers beginnt die Zählung neu, ob es den Zeitplan wieder einschaltet oder ausgeschaltet lässt, und markiert die Hinweise als gelesen.

Webhook- und Plattform-Ereignis-Trigger zählen Fehler genauso, werden aber nie pausiert. Ihre Läufe bringen eine Zustellung oder ein Ereignis mit, das ein pausierter Trigger verwerfen würde.

## Den Trigger pausieren oder ersetzen

Schalte **Aktiv** aus und speichere. Konfiguration und Laufhistorie bleiben erhalten; erneutes Einschalten setzt die Starts fort. **Trigger entfernen** löscht die Bindung und macht bei einem Webhook dessen URL unbrauchbar.

Trigger gehören zum Namen der Automatisierung, nicht zu einer Version. Live-Schaltung und Rollback behalten Zeitplan oder URL bei und ändern die Version künftiger Läufe. Eine Trigger-Änderung erzeugt keine Workflow-Version. Prüfe die Einstellungen daher auch bei einer Live-Schaltung, die erwartete Eingaben verändert.

# Modelle in der Arena vergleichen
Source: https://docs.tale.dev/de/platform/chat/arena-mode

Mit **Arena-Modus** vergleichst du zwei Modelle anhand derselben Nachricht. Beide Seiten verwenden den Chat-Assistenten und denselben Ausgangskontext. Wähle eine Frage, deren Antwort du beurteilen kannst: Eine persönliche Vorliebe belegt noch keine sachliche Richtigkeit.

## Einen Vergleich starten

Öffne einen privaten Chat, dann das **+**-Menü im Eingabebereich und wähle **Arena-Modus**. Geteilte Chats können nicht in die Arena wechseln. Wähle unter **Modell A** und **Modell B** die Modelle und sende deine Nachricht. Du darfst dasselbe Modell zweimal wählen, um Unterschiede zwischen Antworten zu untersuchen, oder zwei verschiedene Modelle vergleichen.

Für einen ersten Vergleich eignen sich eine kurze Quelle und ein präziser Auftrag, etwa: „Liste die drei Entscheidungen aus diesen Besprechungsnotizen auf und belege jede mit dem passenden Satz.“ Quelle, Anweisungen und gewünschtes Format bleiben für beide Seiten gleich.

<Frame caption="Dasselbe Prompt, von zwei Modellen beantwortet, mit der Bewertungszeile darunter.">

![Der Arena-Modus mit einem Prompt für eine Launch-Checkliste, beantwortet in zwei Spalten — links liefert Claude Haiku 4.5 eine nummerierte Liste aus fünf Schritten, rechts gruppiert Claude Sonnet 4.6 dieselbe Arbeit unter Überschriften und ergänzt die Risiken, die eine Erwähnung wert sind — über den Bewertungs-Knöpfen A ist besser, B ist besser, Unentschieden und Beide schlecht.](https://docs.tale.dev/images/platform/chat-arena-split.webp)

</Frame>

Jede Antwort erscheint in einer eigenen Spalte. Die Nachricht wird für beide Spalten gemeinsam zugelassen: Ein Nutzungslimit, das sie stoppt, stoppt sie für beide Seiten und nie nur für eine Spalte. Warte mit der Bewertung, bis beide abgeschlossen sind. Während eine Seite noch antwortet, bleiben die Bewertungsbuttons gesperrt. Auch die Wartezeit gehört zum Vergleich. Schlägt eine Seite fehl, zeigt ihre Spalte den Fehler, und die Runde lässt sich nicht bewerten: Die vier Bewertungsbuttons bleiben gesperrt, bis beide Spalten eine fertige Antwort enthalten, während **Ohne Bewertung beenden** verfügbar bleibt. Lies den Fehler, bevor du das Ergebnis als Qualitätsurteil wertest.

## Die Antworten beurteilen

Prüfe die Fakten anhand der Quelle, die Einhaltung der Anweisungen, fehlende wesentliche Details und den Bearbeitungsaufwand vor der Verwendung. Eine längere oder selbstbewusst formulierte Antwort ist nicht automatisch besser.

| Bewertung | Wann sie passt | Der Chat geht weiter mit |
| --- | --- | --- |
| **A ist besser** | A ist hilfreicher oder genauer. | Spalte A. |
| **B ist besser** | B ist hilfreicher oder genauer. | Spalte B; der Eingabebereich wechselt zu Modell B. |
| **Unentschieden** | Beide erfüllen den Auftrag gleich gut. | Spalte A. |
| **Beide schlecht** | Keine Antwort ist brauchbar. | Spalte A. |
| **Ohne Bewertung beenden** | Du möchtest den Vergleich nicht bewerten. | Spalte A, ohne Bewertung. |

Jede Auswahl beendet den Vergleich mit zwei Spalten. Die nächste Nachricht geht an den verbleibenden Chat. Aktiviere die Arena für einen neuen Vergleich erneut; bei einem Unentschieden bleiben nicht beide Spalten aktiv.

Die Antwort der anderen Spalte wird verworfen und landet im [Papierkorb](https://docs.tale.dev/de/platform/admin/governance/trash) der Organisation. Dort kann ein Administrator sie bis zum Ende der Schonfrist als eigenen Chat wiederherstellen. Sie erscheint nicht mehr in deiner Chatliste oder in der Suche, und ein Link darauf meldet, dass der Chat nicht verfügbar ist.

## Gespeichertes Feedback finden

Wenn beide Modelle geantwortet haben, fließt die Bewertung in die [Feedback-Analyse](https://docs.tale.dev/de/platform/admin/governance/feedback-analytics) der Organisation ein. Administratoren können dort die Arena-Bewertungen und Modellvergleiche prüfen. Eine Runde, in der nur eine Spalte geantwortet hat, wird nie gespeichert: Die Bewertung wird abgelehnt, sodass die Analyse nur Vergleiche zweier fertiger Antworten enthält. **Ohne Bewertung beenden** erzeugt keine Bewertung.

Vergleiche mehrere typische Aufgaben, bevor du ein Modell beurteilst. Ein Ergebnis für kurze Zusammenfassungen sagt wenig über Code oder lange Dokumente aus. Organisationsweite Vorlieben enthalten außerdem Aufgaben anderer Personen.

## Einen blockierten Vergleich klären

Fehlt ein Modell, prüfe mit dem [Modellkatalog](https://docs.tale.dev/de/platform/models) Provider und Zugriffsregeln. Sind die Bewertungsbuttons noch gesperrt, müssen zuerst beide Antworten enden, oder prüfe, ob beide Spalten eine fertige Antwort zeigen: Eine Seite, die fehlgeschlagen ist oder nie geantwortet hat, lässt nichts zu vergleichen. Beende dann ohne Bewertung, behebe die Ursache und sende die Nachricht erneut. Ein fehlgeschlagener Aufruf kann an Zugangsdaten, Verfügbarkeit oder Richtlinien liegen. Entscheide anhand der angezeigten Begründung, was vor einem neuen Versuch zu korrigieren ist.

# Fragen zu Dateien und Bildern stellen
Source: https://docs.tale.dev/de/platform/chat/attachments

Hänge eine Datei an, wenn sie für das aktuelle Gespräch gebraucht wird. Der Assistent erhält Bilder, ruft Text aus unterstützten Dokumenten ab und liest Transkripte von Aufnahmen. Sollen mehrere Chats dieselben Dateien nutzen, lade sie in ein [Projekt](https://docs.tale.dev/de/platform/projects/manage-files) oder die [Wissensbibliothek](https://docs.tale.dev/de/platform/knowledge/documents) hoch.

## Einen Anhang hinzufügen

Öffne das `+`-Menü neben dem Nachrichtenfeld und wähle **Fotos & Dateien hinzufügen**. Du kannst Dateien auch auf das Nachrichtenfeld ziehen oder einen Screenshot hineinkopieren. Eine Nachricht kann bis zu zehn Dateien enthalten.

Bilder erscheinen als Vorschaubilder, andere Dateien als benannte Chips mit Verarbeitungsstatus. Prüfe die Dateinamen vor dem Senden. Entferne einen vorbereiteten Anhang über dessen Entfernen-Schaltfläche, wenn er nicht zur Nachricht gehören soll.

Nach dem Senden ändert **Nachricht bearbeiten** den Text in einer neuen Version des Gesprächs und behält die ursprünglichen Anhänge bei. Du musst sie nicht erneut hochladen.

<Frame caption="Ein vorbereitetes Dokument zeigt seinen Namen und, sobald es verarbeitet und sendebereit ist, seine Größe.">

![Über dem Nachrichtenfeld steht ein angehängtes Dokument mit seiner Dateigröße und einer Schaltfläche zum Entfernen.](https://docs.tale.dev/images/platform/chat-document-attachment.webp)

</Frame>

Formuliere, wonach der Assistent suchen soll, etwa: „Lies die Gesprächsnotiz und liste Entscheidungen, Verantwortliche und fehlende Fristen auf.“ Eine Datei allein erklärt noch nicht, was du damit vorhast.

Wenn du Audio oder Video anhängen möchtest, prüft Tale, ob die Organisation ein verfügbares Transkriptionsmodell hat. Verhindert die Prüfung den Upload, erklärt ein Dialog das Problem und zeigt die für dich verfügbaren Schritte zur Behebung. Diese Dateien werden vor der Übertragung abgewiesen; andere unterstützte Dateien aus derselben Auswahl lassen sich weiterhin hochladen. Schließe den Dialog, um weiterzuschreiben, öffne den Einstellungslink, wenn du Zugriff hast, oder bitte einen Admin, die [Modelle](https://docs.tale.dev/de/platform/admin/governance/content-models) zu prüfen.

## Verstehen, was beim Modell ankommt

| Anhang | Verwendeter Inhalt | Darauf achten |
| --- | --- | --- |
| Bild oder eingefügter Screenshot | Das Bild selbst, sofern das Modell Bilder verarbeiten kann. | Wähle ein bildfähiges Modell und achte auf lesbaren Text. |
| PDF, modernes Office-Dokument oder unterstützte Textdatei | Text, den der Assistent über seine Abrufwerkzeuge lesen kann. | Warte auf die Verarbeitung und prüfe den Leseschritt in der Antwort. |
| Audio- oder Videodatei | Ein Texttranskript. | Ein Admin muss die Transkription einrichten. Prüfe Namen, Zahlen und Fachbegriffe anhand der Aufnahme. |
| Alte Office-Datei ohne Textextraktor | Den Dateinamen, ohne durchsuchbaren Dokumenttext. | Speichere sie als `.docx`, `.xlsx` oder `.pptx` und hänge diese Kopie an. |

Unterstützter Upload und Textextraktion sind zwei verschiedene Dinge. Eine sichtbare Datei im Chat bedeutet nicht automatisch, dass der Assistent ihren Inhalt lesen kann.

## Während der Verarbeitung senden

Sind Dokumente oder Aufnahmen beim Senden noch in Verarbeitung, stellt Tale die Nachricht zurück und sendet sie, sobald die Dateien bereit sind. Die wartende Nachricht erscheint über dem Eingabefeld. Brich sie dort ab, wenn du die Frage ändern möchtest; ihr Text kehrt ins Feld zurück.

Füge einen kopierten, unterstützten Videolink in das Nachrichtenfeld ein, um einen Anhang zu erstellen. Eine von Hand eingegebene URL bleibt gewöhnlicher Nachrichtentext. Tale lädt zuerst Untertitel. Sind keine verfügbar, transkribiert es die Audiospur und stellt dem Assistenten den Text bereit. Sprechen laut Untertiteln zwei Personen gleichzeitig, behält das Transkript die Worte beider. Das Einfügen eines Links bleibt auch ohne Transkriptionsmodell möglich, da nutzbare Untertitel kein solches Modell benötigen. Fügst du einen Link vor dem Senden in einem bestehenden Chat erneut ein, verwendet der Chat den Anhang wieder, den er dafür schon hat, auch wenn du den Link zwischendurch in einem anderen Chat eingefügt hast; jeder Chat behält seinen eigenen. Ein fehlgeschlagener oder entfernter Anhang wird nicht wiederverwendet, ebenso wenig einer, der vor mehr als einem Tag hinzugefügt wurde. Schlägt der Link fehl, versuche es erneut oder entferne ihn vor dem Senden. Kann Tale einen Link nicht entfernen, erscheint sein Chip wieder und eine Meldung nennt den Grund. Der Link bleibt angehängt, bis das Entfernen gelingt.

Ein Modellwechsel gilt für neue Transkriptionen; bereits verarbeitete Anhänge behalten ihr vorhandenes Transkript. Lädst du dieselben Bytes erneut hoch, wird die fertige Transkription für dasselbe Ziel wiederverwendet. Bei einem anderen Zielanbieter oder Zielmodell wird die Aufnahme erneut transkribiert.

## Den richtigen Ablageort wählen

Chat-Anhänge gehören zu diesem Gespräch. Sie landen nicht automatisch in der Wissensbibliothek und sind nicht in anderen Chats verfügbar. Beim Wechsel des Gesprächs werden vorbereitete Anhänge entfernt. Prüfe deshalb die Chips erneut, wenn du den Chat wechselst.

Eine neu erzeugte Antwort verwendet die gespeicherten Anhänge der ursprünglichen Nachricht. Soll der Assistent eine andere Dateiversion lesen, sende die neue Datei und benenne ausdrücklich die gewünschte Version.

<Tip>

Lege ein Briefing oder eine Richtlinie für wiederkehrende Fragen einmal im passenden Projekt ab. Starte weitere Chats dort, statt jedes Mal eine neue Kopie hochzuladen.

</Tip>

## Probleme mit Anhängen beheben

| Beobachtung | Maßnahme |
| --- | --- |
| Das gewählte Modell kann das Bild nicht lesen | Wähle ein bildfähiges Modell. Auto berücksichtigt passende Bildmodelle. Sind keine verfügbar, bitte einen Admin um die Einrichtung. |
| Die Verarbeitung schlägt fehl | Versuche den Upload erneut. Scheitert auch eine kleine unterstützte Datei, sollte ein Admin je nach Fehlermeldung Speicher, Indexierung oder Transkription prüfen. |
| Der Assistent kennt den Namen, aber nicht den Inhalt | Prüfe Format und Verarbeitungsstatus. Wandle alte Dateien in ein unterstütztes modernes Format um. |
| Die Antwort erfindet Details aus einer Aufnahme | Vergleiche das Transkript mit der Aufnahme und liefere den korrigierten Abschnitt nach. |
| Eine wartende Nachricht wird nicht gesendet | Prüfe den Status aller Anhänge einschließlich Videolinks. Entferne fehlerhafte Einträge oder versuche sie erneut. |
| Ein entfernter Videolink erscheint wieder | Tale konnte ihn nicht entfernen; die eingeblendete Meldung nennt den Grund. Der Link bleibt angehängt. Entferne ihn erneut, sobald die Ursache behoben ist, etwa wenn deine Verbindung wieder steht oder nachdem du dich neu angemeldet hast. |

Unter [Fragen im Chat stellen](https://docs.tale.dev/de/platform/chat/basics) erfährst du, wie du Quellen prüfst und das Gespräch fortsetzt.

# Fragen im Chat stellen
Source: https://docs.tale.dev/de/platform/chat/basics

Nutze den Chat, um Fragen zu stellen, ein Dokument zu verstehen oder Informationen in Tale zu recherchieren. Der Assistent kann zugängliches Wissen durchsuchen und öffentliche Seiten lesen. Beginne mit einer konkreten Frage und grenze die Antwort anschließend mit Rückfragen ein.

<Frame caption="Der Chat hält deine Frage, die Schritte des Assistenten und seine Antwort zusammen.">

![Ein Chat zu Onboarding-Rückmeldungen zeigt die Frage und eine Antwort mit drei Themen in einer Tabelle.](https://docs.tale.dev/images/platform/chat-thread-reply.webp)

</Frame>

## Die erste Nachricht senden

Öffne **Start**. Am Computer öffnet sich dabei der Chat, den du zuletzt gelesen hast, falls es einen gibt. Für ein neues Thema wählst du **Neuer Chat** oben in der Liste von **Start** oder klickst am Computer erneut auf **Start**, während der Bereich aktiv ist. Schreibe in das Nachrichtenfeld. Mit **Enter** sendest du, mit **Shift+Enter** fügst du einen Zeilenumbruch ein. Ein vorgeschlagener Gesprächseinstieg funktioniert wie eine eigene erste Frage. Ergänze Quelle, Thema und die Art der Antwort, die du brauchst.

Zum Beispiel: „Finde die Onboarding-Rückmeldungen und fasse die drei häufigsten Probleme zusammen. Nenne die Dokumente als Quellen und trenne gemeldete Probleme von deinen Vorschlägen.“

Hat deine Organisation einen Vertraulichkeitshinweis eingeschaltet, steht er unter dem Nachrichtenfeld und erinnert dich daran, was du im Chat nicht teilen solltest.

Während die Antwort erscheint, wird aus der Sende- eine Stopp-Schaltfläche. Beim Stoppen bleibt der bereits empfangene Text erhalten, auch wenn er mitten im Satz endet. Stelle eine Rückfrage, um dein Anliegen zu präzisieren oder fehlende Details anzufordern.

## Ein Modell gezielt auswählen

Sind mehrere nutzbare Modelle verfügbar, startet die Auswahl mit **Auto**. Auto wählt für jede Nachricht ein Modell aus dem verfügbaren Angebot deiner Organisation. Organisationsregeln können ein Standardmodell festlegen oder die Auswahl einschränken. In den Antwortdetails siehst du, welches Modell tatsächlich geantwortet hat.

Wähle ein bestimmtes Modell, wenn du Antworten vergleichen möchtest oder weißt, welches Modell zur Arbeit passt. Die Auswahl bleibt bestehen, bis du sie änderst – auch der Anbieter, der das Modell bereitstellt, wenn zwei Anbieter dasselbe Modell anbieten. Unterstützt das Modell einen einstellbaren Denkaufwand, erscheint auch diese Einstellung. Mehr Denkaufwand kann länger dauern und ersetzt keine Prüfung der Antwort.

<Frame caption="Die Modellauswahl steht neben dem Anhangsmenü und den Sprachfunktionen.">

![Das Nachrichtenfeld zeigt das Plus-Menü, die Modellauswahl Auto, ein Mikrofon und die Sende-Schaltfläche.](https://docs.tale.dev/images/platform/chat-composer.webp)

</Frame>

Sind keine Modelle verfügbar, bitte einen Admin, aktive Zugangsdaten und den Modellzugriff zu prüfen. Der Chat bietet nur Modelle an, die Zugangsdaten per API-Schlüssel oder Umgebungsvariable bereitstellen: Ein Abo läuft nur in Aufgaben und Automatisierungen, und die Modellliste nennt die Abos, die sie auslässt. Unter [Modelle](https://docs.tale.dev/de/platform/models) steht, wie der Katalog entsteht.

## Die passenden Quellen bereitstellen

Wähle den Ort des Chats, bevor du Fragen zu Dateien stellst:

| Ort der Frage | Abrufbare Dateien |
| --- | --- |
| Allgemeiner Chat der Organisation | Zugängliche Dokumente der Wissensbibliothek und die Anhänge dieses Chats. |
| Chat in einem Projekt | Dateien dieses Projekts, zugängliche Dokumente der Wissensbibliothek und eigene Chat-Anhänge. |
| Link zu einem geteilten Chat | Eine schreibgeschützte Momentaufnahme; dort lassen sich keine Rückfragen stellen. |

Ein Projektchat erhält außerdem die festen Projektanweisungen. Tale erzwingt den Dateizugriff: Die Aufforderung, ein anderes Projekt zu lesen, erweitert die Berechtigung nicht. Dateien im Papierkorb oder mit abgelaufener Aufbewahrung sind nicht durchsuchbar.

Nutze [Anhänge](https://docs.tale.dev/de/platform/chat/attachments) für dieses Gespräch, [Projektdateien](https://docs.tale.dev/de/platform/projects/manage-files) für wiederkehrende Projektarbeit und [Wissen](https://docs.tale.dev/de/platform/knowledge/overview) für gemeinsame Referenzquellen. Der Assistent ruft Inhalte nach Bedarf ab. Ein hochgeladenes Dokument wurde deshalb nicht automatisch für jede Antwort gelesen.

Für Fragen zu Tale selbst musst du nichts hochladen: Der Assistent schlägt in der öffentlichen Dokumentation auf docs.tale.dev nach, bevor er erklärt, wie eine Ansicht oder Einstellung funktioniert. Kann der Server docs.tale.dev nicht erreichen, etwa bei einer selbst gehosteten Installation ohne Internetzugang, zeigt der Ablauf einen fehlgeschlagenen Leseschritt, und die Antwort stützt sich nicht auf die Dokumentation. Die Dokumentation beschreibt die neueste Version; der Assistent weist darauf hin, wenn dein Arbeitsbereich davon abweichen kann.

## Die verwendeten Quellen prüfen

Über der Antwort zeigt der Ablauf die Such- und Leseschritte. Bei einem fehlgeschlagenen Schritt erfährst du, was nicht gelesen werden konnte. Das hilft bei unvollständigen Antworten. Klappe die Denkansicht auf, sofern vorhanden, aber prüfe Tatsachen anhand der Quellen und nicht anhand einer überzeugenden Erklärung.

Unter **Quellen** stehen die geladenen Dokumente und Seiten. Öffne eine Quelle und prüfe, ob sie die jeweilige Aussage stützt. Eine Quellenangabe zeigt verwendetes Material, garantiert aber keine richtige Schlussfolgerung. Ohne Abrufschritt kann eine Antwort auf dem Vorwissen des Modells beruhen.

Der Assistent durchsucht unter anderem Dokumente, Wissenseinträge, Websites, Kontakte, Produkte, zugängliche Aufgaben und die Inbox-Konversationen, die du sehen darfst. Dabei findet er auch den Text der E-Mails, die in diesen Konversationen eingegangen sind, und den ihrer Anhänge. Eine Aufgabe lässt sich über ihren Schlüssel nennen, etwa `DOCS-12`, wie das Board ihn anzeigt. Er kann Details zu einem Ergebnis abrufen und öffentliche Webseiten lesen. Code ausführen, verbundene Systeme ändern, Bilder erzeugen, Dateiergebnisse erstellen oder [Skills](https://docs.tale.dev/de/platform/workspace/skills) nutzen gehört nicht zum Chat. Lege dafür eine [Projektaufgabe](https://docs.tale.dev/de/platform/projects/tasks) an. Jeder, der das Projekt öffnen kann, kann sie anlegen und einem der Agenten des Projekts übergeben; [Aus einem Chat eine Aufgabe machen](https://docs.tale.dev/de/platform/chat/basics#create-task-from-chat) zeigt, wie du sie direkt aus dem Gespräch anlegst. Ein Projektagent, der an der Aufgabe arbeitet, kann Bilder erstellen, wenn ein Admin die [Bildgenerierung](https://docs.tale.dev/de/platform/admin/governance/content-models#let-agents-generate-images) eingeschaltet hat.

## Aus einem Chat eine Aufgabe machen {#create-task-from-chat}

Endet ein Gespräch in Arbeit, die eine Datei braucht, etwa eine Präsentation, einen Bericht oder eine Tabelle, übergib sie einem Projekt-Agenten. Wähle im Kopf des Gesprächs **Aufgabe erstellen**; auf einem schmalen Bildschirm findest du **Aufgabe aus Chat erstellen** im Menü **⋯**. Liegt der Chat in einem Projekt, entsteht die Aufgabe dort. Sonst wählst du zuerst das Projekt: Unter **Mit Agent** stehen die Projekte, die du öffnen kannst und die Agenten haben, samt ihrer Anzahl. Ein Projekt ohne eigene Agenten steht dort mit **Standard-Agent**: Seine Aufgabe geht an den [Standard-Agenten](https://docs.tale.dev/de/platform/projects/project-agents#standard-agent) der Organisation. Kann der Standard-Agent für dich nicht laufen, etwa weil ein Admin ihn ausgeschaltet hat, stehen solche Projekte stattdessen unter **Noch ohne Agent**, jeweils mit dem Hinweis, wer einen hinzufügen kann.

Der Aufgabendialog öffnet sich mit deiner letzten Anfrage als Beschreibung, einem Link zurück zum Chat und den Dateien, die du im Gespräch angehängt hast. Hat das Projekt genau einen Agenten oder nutzt es den Standard-Agenten, ist er unter **Zuständig** schon eingetragen; sonst wählst du einen. Passe alles nach Bedarf an und wähle dann **Erstellen und Agent starten**: Die Aufgabe entsteht, und der Agent beginnt sofort damit. **Nur erstellen** legt sie an, ohne den Agenten zu starten; das holst du später mit **Agent starten** in der Aufgabe nach.

<Frame caption="Aufgabe erstellen öffnet den Aufgabendialog mit der Anfrage, einem Link zurück zum Chat und dem Agenten, der sie übernimmt.">

![Der Dialog zum Erstellen einer Aufgabe enthält als Titel und Beschreibung „Plan the quarterly business review agenda for Friday“, unter der Anfrage einen Link mit der Beschriftung From the chat, Content editor als zuständigen Agenten und die Schaltflächen Create only und Create and start agent.](https://docs.tale.dev/images/platform/chat-create-task.webp)

</Frame>

Danach steht die Aufgabe über dem Nachrichtenfeld des Chats, mit dem, was sie gerade tut: **Der Agent arbeitet**, **Wartet auf einen Sandbox-Platz**, **Wird erneut versucht…**, **Bereit zur Prüfung** mit der Zahl der gelieferten Dateien oder **Der Agent konnte sie nicht fertigstellen**. **Öffnen** führt dich zur Aufgabe. Du wirst außerdem benachrichtigt, wenn sie zur Prüfung bereit ist und wenn der Agent nicht fertig wird; [Wenn der Agent nicht fertig wird](https://docs.tale.dev/de/platform/projects/task-automation#wenn-der-agent-nicht-fertig-wird) erklärt, wie es weitergeht.

<Frame caption="Die Aufgabe, die ein Chat übergeben hat, zeigt ihren Fortschritt über dem Nachrichtenfeld.">

![Über dem Nachrichtenfeld nennt eine Zeile die Aufgabe „Plan the quarterly business review agenda for Friday“ mit Ready for review · Website relaunch und einem Link Open.](https://docs.tale.dev/images/platform/chat-task-tray.webp)

</Frame>

Bittest du den Assistenten um eine solche Datei, beantwortet er, was in eine Antwort passt, und führt dich dann für deine eigenen Projekte durch diese Schritte, mit den Beschriftungen, die du siehst.

Bietet kein Projekt, das du öffnen kannst, einen Agenten an? Dann kann der Standard-Agent für dich nicht laufen: Ein Admin hat ihn vielleicht unter [Richtlinien > Modelle](https://docs.tale.dev/de/platform/admin/governance/content-models#standard-agent) ausgeschaltet, oder kein Modell, das du nutzen darfst, kann ihn ausführen. Frag einen Admin danach, oder bitte einen Redakteur oder Admin, im Tab **Agenten** des Projekts einen Agenten hinzuzufügen. Als Redakteur kannst du auch direkt in der Aufgabe einen hinzufügen: Wähle unter **Zuständig** **Agent erstellen …**.

Dateien kommen nur aus deinem eigenen Gespräch mit. Eine Aufgabe nimmt nur die Uploads der Person an, die sie erstellt; eine Aufgabe aus einem Chat, den jemand in ein Projekt geteilt hat, beginnt deshalb ohne sie.

## Ein Gespräch fortsetzen oder aufbewahren

Über die Antwortleiste kopierst du Text, gibst Feedback, öffnest Details oder zweigst das Gespräch an dieser Stelle ab. Mit einer Abzweigung probierst du eine andere Richtung aus und behältst den bisherigen Austausch.

Frühere Chats findest du im Bereich [Start](https://docs.tale.dev/de/platform#home); die Ansicht **Chats** über der Liste zeigt nur deine Chats. Pinne häufig benötigte Chats, gib ihnen erkennbare Titel oder verschiebe sie in ein Projekt, wenn das Thema längerfristig wird: Zieh sie auf das Projekt oder wähle **In Projekt verschieben…** in ihrem Menü. [Geteilte Chats](https://docs.tale.dev/de/platform/chat/shared-threads) erklärt die schreibgeschützte Freigabe für Kollegen.

Sehr lange Gespräche können das Kontextfenster des Modells überschreiten. Tale zeigt einen Hinweis, wenn ältere Nachrichten nicht mehr mitgegeben werden. Wiederhole wichtige Anforderungen oder beginne einen neuen Chat mit den benötigten Quellen, statt die vollständige Historie vorauszusetzen.

## Eine unvollständige Antwort verbessern

| Problem | Nächster Schritt |
| --- | --- |
| Die Antwort bleibt zu allgemein | Stelle eine Frage, benenne die Zielgruppe und gib Länge oder Format vor. |
| Eine Datei wurde nicht verwendet | Prüfe Projektzuordnung, Indexierungsstatus und Abrufschritte. Nenne die Datei ausdrücklich. |
| Die Suche meldet eine nicht verfügbare Quelle | Bitte einen Admin, den genannten Dienst oder die Embedding-Konfiguration zu prüfen. Ein leeres Ergebnis beweist nicht, dass die Information fehlt. |
| Eine Antwort endet mit einem Fehler | Lies die Fehlermeldung, prüfe das gewählte Modell und versuche es nach Behebung erneut. Tale wechselt nicht still den Anbieter. |
| Eine Antwort bleibt leer | Der Hinweis an ihrer Stelle nennt den Grund: Das Modell hat nichts geliefert, es hat sein Limit für Ausgabe-Tokens vor dem Schreiben aufgebraucht, oder der Inhaltsfilter des Anbieters hat die Antwort zurückgehalten. Wähle **Erneut versuchen**, oder verringere vorher den Denkaufwand, kürze die Anfrage oder wähle ein anderes Modell. |

Ein angeleitetes Beispiel mit Quellenprüfung findest du unter [Bessere Fragen im Chat](https://docs.tale.dev/de/tutorials/member/chat-effectively).

# Chat
Source: https://docs.tale.dev/de/platform/chat/overview

Im Chat kannst du schnell etwas zu einem Dokument fragen, ein Thema verstehen oder eine Antwort durch Rückfragen präzisieren. Der Assistent kann zugängliches Wissen durchsuchen und bei Bedarf öffentliche Seiten abrufen. Prüfe die Quellen, bevor du dich auf eine Tatsachenaussage verlässt, besonders bei veränderlichen Informationen.

<Frame caption="Frage und Antwort bleiben zusammen. So kannst du deinen Auftrag präzisieren, ohne neu anzufangen.">

![Ein Chat zeigt eine Frage zum Onboarding-Feedback und eine Antwort mit einer Tabelle der Themen.](https://docs.tale.dev/images/platform/chat-thread-reply.webp)

</Frame>

## Mit einer nützlichen Frage beginnen

Öffne **Start**, wähle **Neuer Chat**, schreibe ins Nachrichtenfeld und sende die Nachricht. Ein Gesprächsvorschlag hilft beim Einstieg. Nenne das gewünschte Ergebnis und die passende Quelle: „Liste anhand des Onboarding-Leitfadens die Schritte auf, die ein neuer Kunde erledigen muss. Belege sie mit dem Leitfaden.“

Sind mehrere nutzbare Modelle verfügbar, kann die Modellauswahl mit **Auto** beginnen. Wähle ein benanntes Modell, wenn du selbst festlegen möchtest, welches verfügbare Modell antwortet. Bei unterstützten Modellen lässt sich auch der Denkaufwand einstellen. Hänge für eine konkrete Frage eine Datei an oder nutze einen Projektchat für wiederkehrende Unterlagen.

<Frame caption="Die Gesprächsvorschläge bieten erste Fragen an. Im Nachrichtenfeld kannst du eine eigene stellen.">

![Ein neuer Chat zeigt die Begrüßung, vier Gesprächsvorschläge und das Nachrichtenfeld.](https://docs.tale.dev/images/platform/chat-starters-empty.webp)

</Frame>

## Den passenden Arbeitsbereich wählen

| Du möchtest | Beginne hier |
| --- | --- |
| Fragen stellen, Angaben vergleichen oder eine Antwort klären | **Chat** |
| Dieselben Dateien und Anweisungen in mehreren Gesprächen nutzen | **Projektchat** |
| Ein Ergebnis mit Zuständigkeit und Prüfung erstellen lassen | **Aufgabe** im Projekt |
| Einen wiederholbaren Ablauf nach Zeitplan oder Ereignis ausführen | **Automatisierung** |

Chat dient Gesprächen und der Informationssuche. Für umfangreichere Ergebnisse kann der Assistent auf eine Aufgabe verweisen. Dort arbeitet ein Agent in einer Sandbox und eine Person prüft das Ergebnis. Siehe [Aufgaben](https://docs.tale.dev/de/platform/projects/tasks) und [Automatisierungen](https://docs.tale.dev/de/platform/automations/concepts).

## Das Gespräch gut nutzen

<CardGroup cols="2">

<Card title="Chat-Grundlagen" icon="message-circle" href="https://docs.tale.dev/de/platform/chat/basics">
Senden, ein Modell wählen, Quellen lesen und ein Gespräch später fortsetzen.
</Card>

<Card title="Dateien anhängen" icon="paperclip" href="https://docs.tale.dev/de/platform/chat/attachments">
Ein Dokument oder Bild hinzufügen und Upload- und Indexierungszustände verstehen.
</Card>

<Card title="Modelle in Arena vergleichen" icon="swords" href="https://docs.tale.dev/de/platform/chat/arena-mode">
Zwei Antworten auf dieselbe Frage vergleichen und die passendere behalten.
</Card>

<Card title="Die Stimme nutzen" icon="mic" href="https://docs.tale.dev/de/platform/chat/voice-mode">
Eine Nachricht diktieren oder eine Antwort anhören und die nötige Provider-Einrichtung kennen.
</Card>

<Card title="Einen Chat teilen" icon="share-2" href="https://docs.tale.dev/de/platform/chat/shared-threads">
Eine schreibgeschützte Momentaufnahme für die Organisation bereitstellen und die Freigabe beenden.
</Card>

<Card title="Mit einer echten Quelle üben" icon="book-open" href="https://docs.tale.dev/de/tutorials/member/chat-effectively">
Eine gezielte Frage stellen, ihre Quelle prüfen und sinnvoll nachfragen.
</Card>

</CardGroup>

# Einen Chat mit der Organisation teilen
Source: https://docs.tale.dev/de/platform/chat/shared-threads

Teile einen Chat, wenn Kollegen die Frage und Antwort lesen sollen, ohne dein Gespräch fortzusetzen. Der Link veröffentlicht eine Momentaufnahme für angemeldete Mitglieder deiner Organisation. Er ist nicht öffentlich und aktualisiert sich nicht automatisch, wenn du weiterchattest.

## Die Momentaufnahme erstellen

1. Öffne das Menü in der Chat-Kopfzeile und wähle **Teilen**.
2. Wähle im Dialog **Chat teilen** die Option **Mit Organisation teilen**.
3. Klicke auf **Freigabelink erstellen**.
4. Prüfe die Momentaufnahme mit **Vorschau** und nutze anschließend **Link kopieren**.

Die Momentaufnahme zeigt den Zweig, den du gerade siehst. Hast du **Nachricht bearbeiten** oder **Erneut versuchen** genutzt, veröffentlicht der Link von jeder bearbeiteten oder neu erzeugten Antwort die Fassung, die auf dem Bildschirm steht. Wechsle vor dem Erstellen des Links mit **Vorheriger Zweig** und **Nächster Zweig** zu der Fassung, die deine Kollegen lesen sollen.

Lies den Verlauf, bevor du den Link weitergibst. Eine Antwort kann Angaben aus einer eingeschränkt zugänglichen Quelle enthalten. Mit der Freigabe wird ihr Text für Organisationsmitglieder mit dem Link lesbar.

<Frame caption="Empfänger lesen die Momentaufnahme mit Angaben zur Freigabe. Ein Nachrichtenfeld gibt es dort nicht.">

![Ein schreibgeschützter geteilter Chat zeigt den Verlauf sowie den Namen der teilenden Person und das Freigabedatum.](https://docs.tale.dev/images/platform/chat-shared-view.webp)

</Frame>

## Eine spätere Antwort einbeziehen

Neue Nachrichten bleiben außerhalb der veröffentlichten Momentaufnahme. Öffne erneut **Teilen** und wähle **Neuere Nachrichten einbeziehen**, wenn derselbe Link den neueren Austausch zeigen soll. Die Momentaufnahme wird dabei erneut von dem Zweig genommen, den du gerade siehst. Wechsle also zuerst zu der Fassung, die du veröffentlichen möchtest. Prüfe die aktualisierte Fassung noch einmal in der Vorschau.

Wer das Thema fortsetzen möchte, beginnt einen eigenen Chat. Die Momentaufnahme macht aus deinem Chat kein gemeinsam bearbeitetes Gespräch und gewährt nicht automatisch Zugriff auf alle genannten Quellen.

## Die Freigabe beenden

Wähle **Privat lassen** im Freigabedialog oder **Teilen beenden** im Menü des Chats in der Liste von **Start**. Der Link ist danach nicht mehr verfügbar. Auch das Löschen des ursprünglichen Chats beendet seine Freigabe.

Kann der Dialog den Freigabestatus nicht laden, ist keine der beiden Optionen ausgewählt, und ein Hinweis sagt, dass der Chat möglicherweise noch geteilt ist. Wähle **Erneut versuchen**. Sobald der Status angezeigt wird, kannst du **Privat lassen** wählen. Ein bestehender Link funktioniert bis dahin weiter.

Nach dem Beenden lässt sich der Chat über diesen Link nicht mehr öffnen. Bereits kopierten Text kannst du damit nicht zurückholen. Prüfe den Inhalt deshalb vor der ersten Freigabe.

## Stattdessen mit einem Projekt teilen

Für die laufende Zusammenarbeit nutze **Mit Projekt teilen** an einem Chat in einem [Projekt](https://docs.tale.dev/de/platform/projects/concepts). Unter **Chats** trennt das Projekt persönliche Gespräche von den geteilten. Der Projektzugriff allein gibt deine persönlichen Chats nicht automatisch frei.

Arena-Vergleiche lassen sich nicht teilen, solange sie Arena-Chats sind. Beende zuerst den Vergleich und teile dann das Gespräch, das du behältst. Siehe [Arena-Modus](https://docs.tale.dev/de/platform/chat/arena-mode).

# Sprachmodus
Source: https://docs.tale.dev/de/platform/chat/voice-mode

Mit Diktat sprichst du eine Nachricht ein, statt sie zu tippen. Die Sprachausgabe liest eine Antwort des Assistenten vor. Beides lässt sich getrennt nutzen: Ein Diktat braucht keine vorgelesene Antwort, und zum Zuhören ist kein Mikrofonzugriff nötig.

## Diktieren und die Nachricht prüfen

1. Klicke am Mikrofon des Nachrichtenfelds auf **Diktat starten**.
2. Erlaube bei Nachfrage den Mikrofonzugriff im Browser und sprich deutlich.
3. Klicke auf **Diktat stoppen**. Wird serverseitig transkribiert, warte auf den Abschluss.
4. Lies und korrigiere den Text im Nachrichtenfeld, besonders Namen, Zahlen und Termine. Sende ihn, wenn er stimmt.

Das Diktat ergänzt Text im Nachrichtenfeld; es sendet die Nachricht nicht automatisch. Das Senden beendet ein laufendes Diktat. Das Chat-Modell erhält den Text, den du abschickst.

Tale nutzt zuerst die Spracherkennung des Browsers, sofern verfügbar. Andernfalls kann es die Aufnahme über das Transkriptionsmodell der Organisation verarbeiten. Die Browser-Spracherkennung kann einen Dienst des Browseranbieters nutzen. Gehe deshalb nicht von Offline-Verfügbarkeit aus.

Für den Serverweg braucht der Browser Aufnahmeunterstützung über MediaRecorder, Mikrofonzugriff und ein verfügbares Transkriptionsmodell der Organisation. Ein Admin wählt das **Modell für Audiotranskription** unter [Einstellungen > Governance > Modelle](https://docs.tale.dev/de/platform/admin/governance/content-models). Diese Einstellung gilt auch für Audio- und Videoanhänge. Sie ändert den Erkennungsdienst des Browsers nicht: Unterstütztes Browserdiktat bleibt nutzbar, wenn das Servermodell der Organisation nicht verfügbar ist.

Versuchst du ein Serverdiktat zu starten und ist das Transkriptionsmodell nicht verfügbar, erklärt ein Dialog das Problem. Öffne den Einstellungslink, wenn du Zugriff hast, wiederhole eine vorübergehend fehlgeschlagene Verfügbarkeitsprüfung oder bitte einen Admin um Hilfe. Du kannst den Dialog schließen und weiter tippen.

## Eine Antwort anhören

Aktiviere **Sprachmodus** im Nachrichtenfeld, um Antworten im aktuellen Chat anzuhören. Ein Text-to-Speech-Modell erzeugt Audio aus der Antwort. Mit der Wiedergabeaktion an der Antwort kannst du stoppen oder erneut abspielen. Der geschriebene Text bleibt zum Nachprüfen verfügbar.

Eine Organisationsrichtlinie kann die Sprachausgabe ausblenden. Eine deaktivierte Aktion kann auch bedeuten, dass kein geeignetes Sprachmodell verfügbar ist. Ein Administrator prüft die [KI-Provider](https://docs.tale.dev/de/platform/admin/providers). Die Wahl eines anderen Chat-Modells richtet keinen Sprachprovider ein.

Die Einstellung in einem vorhandenen Chat gilt für dieses Gespräch. In einem neuen Chat wird damit auch der Standard für spätere Chats gesetzt. Projektagenten haben keine eigene Stimmeneinstellung.

## Probleme mit Sprache beheben

| Symptom | Was du prüfen kannst |
| --- | --- |
| Das Mikrofon startet nicht | Mikrofonberechtigung des Browsers, gewähltes Eingabegerät und mögliche Nutzung durch eine andere App. |
| Eine Meldung sagt, Diktat sei nicht verfügbar | Der Browser erreicht seinen Sprachdienst nicht: Verbindung, Proxy oder Inhaltsblocker prüfen, dann erneut versuchen. |
| Wörter fehlen oder stimmen nicht | Hintergrundgeräusche verringern und den Text vor dem Senden korrigieren. |
| Die Server-Transkription schlägt fehl | Erneut versuchen, solange die fehlgeschlagene Aufnahme verfügbar ist, oder verwerfen und tippen. |
| Die Antwort ist bereit, aber stumm | Lautstärke und Wiedergabeerlaubnis des Browsers prüfen, dann die Antwort abspielen. |
| Eine Konfigurationsmeldung erscheint | Einen Administrator Sprachmodell und Zugangsdaten prüfen lassen. |

Eine fehlgeschlagene Server-Transkription hält die Aufnahme zur Wiederholung im Speicher der aktuellen Seite. Beim Verlassen oder Neuladen kann sie verloren gehen. Sie ist kein gespeicherter Audioanhang. Nutze [Anhänge](https://docs.tale.dev/de/platform/chat/attachments), wenn du eine vorhandene Aufnahme hochladen möchtest.

## Den Weg der Audiodaten verstehen

Beim Browserdiktat verarbeitet der Sprachdienst des Browsers die Aufnahme. Der alternative Serverweg sendet sie zur Transkription mit dem konfigurierten Provider an Tale. Dieser Diktatweg legt sie nicht als Dokument ab. Sobald du den Text sendest, gehört er zum Chatverlauf.

Die Sprachausgabe sendet den Antworttext an den eingerichteten Sprachprovider und streamt das Audio zur Wiedergabe. Enthält die Antwort Informationen aus einer beschränkt zugänglichen Quelle, gehören auch diese zum Sprachauftrag. Administratoren sollten Sprachdienste passend zu den [Anforderungen an die Datenresidenz](https://docs.tale.dev/de/cloud/data-residency) wählen.

# Einen externen Client über MCP verbinden
Source: https://docs.tale.dev/de/platform/connectors/mcp-servers

Über den MCP-Endpunkt verbindet sich ein externer Coding-Assistent oder anderer MCP-Client mit deiner Organisation in Tale. Er kann verfügbare Funktionen finden, Automationen erstellen und Läufe prüfen. Der Zugriff folgt dem Organisations-API-Schlüssel und den Berechtigungen seines Inhabers.

## Den Endpunkt finden

Öffne **Einstellungen > API > MCP**. Die Seite zeigt die Endpunkt-URL, den Organisations-Slug, die verfügbaren Tool-Gruppen und eine kopierbare Anfrage zum Verbindungstest. Falls du noch keinen passenden Schlüssel hast, erstelle ihn unter **Einstellungen > API**.

<Frame caption="Die MCP-Einstellungen zeigen Endpunkt, Organisationskontext und verfügbare Tools.">

![Die MCP-Seite zeigt eine Endpunkt-URL mit /api/v1/mcp, einen Organisations-Slug, Tool-Gruppen und eine Beispielanfrage zum Verbindungstest.](https://docs.tale.dev/images/platform/settings-mcp-endpoint.webp)

</Frame>

Unter [MCP-Endpunkt](https://docs.tale.dev/de/develop/mcp-endpoint) stehen Client-Konfiguration, Authentifizierung und benötigte Berechtigungen. Hinterlege den Schlüssel in der Zugangsdatenverwaltung des Clients, nicht in einem Prompt oder geteilten Dokument.

## Die Verbindungsrichtung wählen

Der MCP-Endpunkt von Tale nimmt Verbindungen externer Clients an. In Tale gibt es kein Einstellungsformular, um einen externen MCP-Server als Ausstattung eines Projektagenten zu registrieren.

Soll ein Agent innerhalb von Tale einen anderen Dienst verwenden, prüfe den [Connector-Katalog](https://docs.tale.dev/de/platform/connectors/overview). Gibt es keinen passenden Connector, kann ein [Projektagent](https://docs.tale.dev/de/platform/projects/project-agents) den Dienst mit einem passend begrenzten Secret aus seiner Sandbox aufrufen. Der laufende Agent erhält dabei Zugriff auf das Secret. Begrenze seine Rechte deshalb auf die konkrete Aufgabe.

## Den Zugriff vor dem Erstellen prüfen

Beginne mit der Testanfrage auf der MCP-Seite und prüfe, ob der Client die Tools auflisten kann. Lies vor einem Schreibzugriff, welche Berechtigung das Tool verlangt. Eine Automation zu speichern und bereitzustellen sind getrennte Schritte. Eine Client-Verbindung umgeht weder die Freigabe zur Bereitstellung noch Genehmigungsregeln.

[API-Schlüssel](https://docs.tale.dev/de/platform/admin/api-keys) erklärt Austausch und Widerruf. Unter [Automationen verstehen](https://docs.tale.dev/de/platform/automations/concepts) findest du den Ablauf zum Speichern, Testen und Bereitstellen.

# Tale mit externen Diensten verbinden
Source: https://docs.tale.dev/de/platform/connectors/overview

Nutze einen Connector, wenn Tale Daten in einem externen Dienst lesen oder ändern soll. Der Connector definiert die unterstützten Aktionen. Mit den Zugangsdaten greift Tale auf das gewählte Konto zu. Entwickler, Admins und Inhaber verwalten sie unter **Einstellungen > Connectors**.

<Video src="https://docs.tale.dev/videos/de/tutorials/ep7-connectors/ep7-connectors.de.mp4" poster="https://docs.tale.dev/videos/de/tutorials/ep7-connectors/ep7-connectors.de.webp" captions="https://docs.tale.dev/videos/de/tutorials/ep7-connectors/ep7-connectors.de.vtt" lang="de" title="Episode 7 — Connectors & die Außenwelt" caption="Episode 7 — Connectors & die Außenwelt (2:52)">

</Video>

## Die Verbindung nach der Aufgabe wählen

| Connector | Typischer Einsatz | Anmeldung |
| --- | --- | --- |
| Confluence | Confluence-Cloud-Seiten ins Wissen importieren. | Benutzername mit Passwort oder Token. |
| Discord | Mit Nachrichten und Kanälen arbeiten. | Token. |
| GitHub | Repositorys, Issues und Pull Requests lesen oder verwalten. | Token. |
| GlitchTip | Issues eines Projekts lesen, damit der GlitchTip-Import daraus Aufgaben anlegt. | Token und eine Instanz-URL. |
| Gmail | E-Mails lesen, senden und organisieren. | OAuth. |
| Google Drive | Dateien ins Wissen importieren. | OAuth. |
| IMAP / SMTP Mailbox | E-Mails über einen eigenen Maildienst lesen oder senden. | Benutzername und Passwort. |
| Jev decisions | Typisierte Fragen zu den Daten eines Workflows mit kalibrierten Wahrscheinlichkeiten beantworten, damit der Workflow entscheiden kann, ob er handelt. | API-Schlüssel (ein OpenRouter-Schlüssel). |
| Microsoft Outlook | Mit E-Mails, Kalendern und Kontakten arbeiten. | OAuth. |
| Shopify | Mit Produkten, Kunden und Bestellungen arbeiten. | API-Schlüssel. |
| Slack | Mit Nachrichten und Kanälen arbeiten. | OAuth. |
| Tavily | Im Web suchen und Seiten auslesen. | API-Schlüssel. |
| Microsoft Teams | Mit Nachrichten und Kanälen arbeiten. | OAuth. |
| Twilio | SMS senden und Sprachanrufe starten. | Benutzername mit Passwort oder Token. |
| WebDAV Files | WebDAV-Dateien der Organisation lesen, schreiben und auflisten. | Benutzername und Passwort. |

Die Karten des installierten Katalogs zeigen die aktuellen Aktionen und Anmeldemethoden. Diese Definitionen kommen mit der Plattform. Ein weiteres Konto installiert keinen beliebigen neuen Connector-Code.

Wissensimporte verwenden die [Dokumentenindexierung](https://docs.tale.dev/de/platform/knowledge/documents). OneDrive und SharePoint nutzen den Import unter **Wissen > Dokumente** mit persönlicher Zustimmung statt eines separaten Organisations-Connectors. Soll dein Gerät Tale-Dokumente als Laufwerk öffnen, ist die Richtung umgekehrt: Dafür dient [WebDAV](https://docs.tale.dev/de/platform/connectors/webdav).

## Das gewünschte Konto hinzufügen

Wähle **Zugangsdaten hinzufügen**, suche den Dienst und öffne seine Karte. Bereits eingerichtete Connectors erscheinen zuerst. Trotzdem kannst du für denselben Dienst ein weiteres Konto hinzufügen. Das Formular fragt nach der vom Connector unterstützten Anmeldung.

<Frame caption="Zugangsdaten hinzufügen öffnet den Katalog — die mitgelieferten Connectoren, die mit vorhandenen Zugangsdaten zuerst.">

![Der Dialog Zugangsdaten hinzufügen über der Tabelle unter Einstellungen > Connectors, mit den mitgelieferten Connectoren als Karten samt Kategorien und Aktionszahl, einem Suchfeld oben und dem bereits eingerichteten Connector Tavily am Anfang der Liste.](https://docs.tale.dev/images/platform/connectors-add-credential.webp)

</Frame>

Das Feld **Name** enthält zunächst den Namen des Connectors. Fügst du für denselben Dienst mehrere Konten hinzu, ersetze ihn durch einen zweckbezogenen Namen, etwa `Support-Postfach` oder `Release-Bot`. Verwende Zugangsdaten des externen Diensts, keinen Tale-API-Schlüssel. Melde dich bei OAuth mit dem Konto beim Provider an, das du hinzufügen willst, und schließe die Zustimmung ab. Jede Verbindung legt neue Zugangsdaten an, benannt nach dem Connector und durchnummeriert (`Gmail`, dann `Gmail 2`); Slack führt pro Workspace genau einen Satz. Benenne neue Zugangsdaten um, damit die Konten unterscheidbar bleiben. Kann der Vorgang nicht starten, muss gegebenenfalls ein Administrator zuerst die OAuth-App einrichten.

Confluence, GlitchTip und Shopify brauchen pro Eintrag eine **Instanz-URL**. Verwende den Ursprung der Atlassian-Site, den Ursprung der GlitchTip-Instanz wie `https://app.glitchtip.com` oder die `myshopify.com`-Adresse des Shops, keine beliebige Unterseite oder Kundendomain. Eine selbst gehostete GlitchTip-Instanz muss zusätzlich durch die Host-Richtlinie des Connectors erlaubt sein. [Connector-Zugangsdaten](https://docs.tale.dev/de/platform/admin/connectors) erklärt Felder, erneute Autorisierung und Schlüsselaustausch.

## Das Konto für eine Aktion bestimmen

Eine Aktion verwendet den ausdrücklich genannten Eintrag oder, ohne Angabe, den Standard des Connectors. Nur ein Eintrag pro Connector kann Standard sein. Ohne Standard schlägt ein Aufruf ohne Namen fehl, selbst wenn andere Zugangsdaten vorhanden sind. Löschst du den Standard, wird der älteste verbleibende aktive Eintrag dieses Connectors zum Standard; die Löschbestätigung nennt ihn vorher.

Zwei Support-Postfächer sind beispielsweise zwei Einträge. Vergib unterscheidbare Namen und prüfe die aufgelöste Eingabe eines Workflows vor dem Live-Lauf. Der Standard wird verwendet, wenn die Aktion keinen bestimmten Eintrag nennt. Postfachoperationen, die alle aktiven Konten auslesen, sind ein eigener Fall.

Das Deaktivieren erhält die Konfiguration, verhindert aber ihre Nutzung. Der Austausch eines Secrets erneuert den Zugang hinter bestehenden Verweisen. Prüfe abhängige Workflows, bevor du einen Eintrag deaktivierst, löschst oder den Standard änderst.

## Lesen und Schreiben unterscheiden

Automatisierungen verwenden Connector-Aktionen als Workflow-Nodes. Jede Aktion definiert Eingabeschema, Ausgabe und Lese- oder Schreibwirkung. GlitchTip und Jev decisions lesen nur: Der GlitchTip-Import legt Tale-Aufgaben an und ändert nie das ursprüngliche Issue, und eine Jev-Entscheidung beantwortet jede Frage mit ihren Wahrscheinlichkeiten, ohne etwas zu schreiben. Jede Entscheidung wird dem OpenRouter-Konto berechnet, dessen Schlüssel die Zugangsdaten enthalten. Testläufe simulieren die Antworten. Ein Live-Schreibvorgang kann Nachrichten senden oder externe Daten ändern und unterliegt der Freigaberichtlinie der Organisation.

Projektagenten mit konfigurierten Connectors erhalten deren unterstützte Leseaktionen über Tales Connector-Broker. Er hält diese Zugangsdaten außerhalb der Sandbox und gibt Ergebnisse zurück. Connector-Schreibaktionen lehnt er ab. Direkte GitHub-Werkzeuge und explizite Agent-Secrets nutzen andere Wege und brauchen eine eigene Prüfung.

Ein neuer Zugang erweitert nicht beliebig die Tools des gewöhnlichen Chat-Assistenten. Nutze [Automatisierungen](https://docs.tale.dev/de/platform/automations/editor) für einen definierten Connector-Ablauf und [Projektagenten](https://docs.tale.dev/de/platform/projects/project-agents) für Sandbox-Arbeit.

## Wenn der Dienst fehlt

Ein Projektagent kann aus seiner Sandbox auf einen Dienst zugreifen, wenn sein Harness dafür geeignete Werkzeuge und ein ausdrücklich freigegebenes Secret erhält. Eine `transform`-Node formt nur Daten um und ruft keine externe API auf. Prüfe Berechtigungen und erwartete Auswirkungen vor einer direkten Integration.

Soll die externe Anwendung Tale aufrufen, nutze die [REST-API](https://docs.tale.dev/de/develop/api-reference) oder den [MCP-Endpunkt](https://docs.tale.dev/de/develop/mcp-endpoint). [MCP und eigene Integrationen](https://docs.tale.dev/de/platform/connectors/mcp-servers) erklärt diese Unterscheidung.

# Tale-Dokumente über WebDAV öffnen
Source: https://docs.tale.dev/de/platform/connectors/webdav

Mit WebDAV öffnet und bearbeitet ein kompatibler Datei-Client Tale-Dokumente wie einen entfernten Ordner. Änderungen betreffen denselben Speicher wie **Wissen > Dokumente**. Dateien aus dem Wissensbereich einzelner Projekte sind nicht Teil dieses Laufwerks.

## Die Verbindungsdaten abrufen

Öffne **Einstellungen > API > WebDAV**. Inhaber, Admins und Entwickler können eigene Gerätezugänge erzeugen. Kopiere die angezeigte URL einschließlich Organisations-Slug und `/documents/`. Baue sie nicht aus einer Organisations-ID zusammen und verwende keine Adresse einer anderen Organisation.

<Frame caption="Einstellungen > API > WebDAV — oben die vorbefüllten Verbindungsdaten, darunter der App-Passwort-Generator.">

![Die WebDAV-Einstellungen zeigen Verbindungs-URL und Benutzername über drei App-Passwörtern. Retired design workstation ist widerrufen; Design workstation und MacBook Pro sind aktiv und bieten die Aktion zum Widerrufen.](https://docs.tale.dev/images/platform/settings-webdav.webp)

</Frame>

Verwende deine Tale-E-Mail-Adresse als Benutzernamen und ein App-Passwort als Passwort. Das normale Kontopasswort funktioniert für WebDAV nicht. Verbinde dich bei einem bereitgestellten Dienst über HTTPS. Schreibe Zugangsdaten weder in URLs noch in die Befehlshistorie.

## Ein Passwort pro Gerät erzeugen

1. Wähle **Erzeugen** und gib unter **Bezeichnung** einen Namen wie `Design-Laptop` ein.
2. Erzeuge das Passwort und kopiere es vor dem Schließen. Der vollständige Wert erscheint nur einmal.
3. Speichere es in der Zugangsdatenverwaltung des Clients und wähle **Ich habe es gespeichert**.

Die Liste enthält Bezeichnung, Präfix und Nutzungsdaten, kein wiederherstellbares Passwort. Bei Verlust erzeugst du einen Ersatz und widerrufst das alte Passwort, nachdem der Client umgestellt ist. Getrennte Passwörter erlauben den Entzug eines einzelnen Gerätezugangs.

## Den Client einrichten

<Tabs>

<Tab title="macOS Finder">

Öffne im Finder mit **⌘K** die Verbindung zu einem Server. Füge die WebDAV-URL ein und melde dich mit E-Mail-Adresse und App-Passwort an. Öffne den verbundenen Ordner und prüfe ein bekanntes Dokument, bevor du Dateien hineinkopierst. Speichere den Zugang nur auf einem vertrauenswürdigen Gerät.

</Tab>

<Tab title="Windows">

Verbinde im Datei-Explorer ein Netzlaufwerk mit der HTTPS-WebDAV-Adresse und den erzeugten Zugangsdaten. Der Windows-Dienst WebClient muss verfügbar sein. Kläre Verbindungs- oder Größenprobleme anhand von Microsofts [WebDAV-Anforderungen und Limits](https://learn.microsoft.com/en-us/iis/publish/using-webdav/using-the-webdav-redirector) mit der IT oder nutze einen eigenen WebDAV-Client. Behalte HTTPS bei.

</Tab>

<Tab title="Linux">

Ein Dateimanager mit WebDAV-Unterstützung verwendet den angezeigten Host und Pfad. GNOME Files nutzt `davs://` für sicheres WebDAV, KDE Dolphin `webdavs://`. Trennt der Dialog Server und Ordner, trage den Host als Server und `/dav/<orgSlug>/documents/` als Ordner ein, mit HTTPS und dem passenden Port.

</Tab>

<Tab title="iPhone und iPad">

Wähle einen Client, der WebDAV ausdrücklich unterstützt, und ein eigenes App-Passwort für das Gerät. Für gelegentlichen Zugriff eignet sich auch Tales Dokumentenseite im Browser. Der allgemeine Serverdialog der Dateien-App ist kein gesicherter WebDAV-Einstieg. Direkte WebDAV-Uploads aus Pages, Numbers und Keynote werden [nicht mehr unterstützt](https://support.apple.com/en-us/101948).

</Tab>

<Tab title="rclone">

Starte `rclone config` und lege einen WebDAV-Zugang mit Tales URL, deiner E-Mail-Adresse und dem App-Passwort an. Wähle `other` als Anbieter und gib das Passwort interaktiv ein. Die [WebDAV-Anleitung von rclone](https://rclone.org/webdav/) erklärt Auflisten und Kopieren. Beginne mit einem kleinen Testordner.

</Tab>

</Tabs>

## Eine kleine Übertragung prüfen

Öffne oder lade ein Dokument herunter, das du auch in Tale lesen kannst. Darfst du schreiben, lade eine kleine Textdatei mit eindeutigem Namen in einen Testordner hoch. Prüfe Name und Inhalt unter **Wissen > Dokumente** und danach den Indexierungsstatus, bevor du sie in der Suche erwartest.

WebDAV-Uploads folgen den Dokumentberechtigungen und Indexierungsregeln; ihre Quelle wird als `webdav` erfasst. Eine abgeschlossene Übertragung bedeutet nicht, dass die Indexierung fertig ist. Fehlt eine Projektdatei im Laufwerk, öffne stattdessen den Wissensbereich dieses Projekts.

## Sperren und gelöschte Dateien handhaben

Ein kompatibler Editor kann eine Datei während der Bearbeitung sperren. Ein konkurrierender Schreibzugriff erhält **423 Locked**. Beende die andere Bearbeitung, statt wiederholt zu überschreiben. Der Widerruf eines App-Passworts löst auch seine Dateisperren.

Unter `.trash/` liegen vorläufig gelöschte Dokumente schreibgeschützt. Lade eine noch gespeicherte Datei bei Bedarf zur Prüfung herunter und stelle sie über Tale wieder her. Endgültig entfernte Dateien lassen sich dort nicht zurückholen. Eine Datei, die du über WebDAV hochlädst, überschreibst, kopierst oder löschst, hinterlässt in deinem Namen einen Eintrag im Audit-Log unter **Einstellungen > Richtlinien > Protokolle**; eine Löschung erscheint dort als in den Papierkorb verschobenes Dokument.

## Einen Zugang widerrufen oder reparieren

Wähle an der Passwortzeile **Widerrufen** und bestätige. Künftige Anfragen damit werden abgelehnt; andere App-Passwörter bleiben nutzbar. Der Widerruf ist nicht umkehrbar. Stelle den Client bei Bedarf auf ein neues Passwort um. Das Erzeugen und das Widerrufen eines App-Passworts hinterlassen je einen Eintrag im Audit-Log unter **Einstellungen > Richtlinien > Protokolle**.

Bei wiederholten Anmeldeaufforderungen prüfe die genaue URL, Organisationsmitgliedschaft und einen möglichen Widerruf. Eine fehlende Berechtigung nach der Anmeldung unterscheidet sich von einem falschen Passwort. Die [WebDAV-API-Referenz](https://docs.tale.dev/de/develop/webdav-api) erklärt Statuscodes und Protokolldiagnose. Für Software mit REST-Zugriff dienen stattdessen [API-Schlüssel](https://docs.tale.dev/de/platform/admin/api-keys).

# Entwickler
Source: https://docs.tale.dev/de/platform/developer/overview

Als Entwickler richtest du technische Verbindungen und Automatisierungen für die Arbeit deines Teams ein. Neben Inhaltsbearbeitung hast du Zugriff auf technische Einstellungen wie Provider, Connectors und API-Zugangsdaten. Die Mitgliederverwaltung bleibt bei Inhabern und Admins.

## Eine Verbindung oder einen Ablauf wählen

<CardGroup cols="2">

<Card title="Einen API-Schlüssel erstellen" icon="key" href="https://docs.tale.dev/de/platform/admin/api-keys">

Erlaube einem Skript oder Dienst Tale-Aufrufe und plane Austausch und Widerruf ein.

</Card>

<Card title="Einen MCP-Client verbinden" icon="network" href="https://docs.tale.dev/de/develop/mcp-endpoint">

Lass einen externen Client die von Tale angebotenen Tools finden und nutzen.

</Card>

<Card title="Einen externen Dienst verbinden" icon="plug" href="https://docs.tale.dev/de/platform/admin/connectors">

Hinterlege Zugangsdaten, wähle den Standard und erneuere abgelaufene Autorisierungen.

</Card>

<Card title="Eine Automatisierung erstellen" icon="workflow" href="https://docs.tale.dev/de/platform/automations/catalog">

Beginne mit einem leeren Workflow oder importiere ein Paket. Teste und veröffentliche anschließend eine Version.

</Card>

</CardGroup>

## Von der konkreten Verbindung ausgehen

Für eingehende Anfragen beginne mit der [API-Referenz](https://docs.tale.dev/de/develop/api-reference) oder [Webhooks](https://docs.tale.dev/de/develop/webhooks). Soll ein Agent ein anderes System aufrufen, nutze nach Möglichkeit einen unterstützten Connector. Direkte Zugangsdaten in der Sandbox brauchen einen bewusst begrenzten Zugriff. [Projektagenten](https://docs.tale.dev/de/platform/projects/project-agents) erklärt die Ausstattung. Deployment-Dateien und Umgebungsvariablen gehören in die [Self-hosted-Konfiguration](https://docs.tale.dev/de/self-hosted/configuration/environment-reference).

# Redakteur
Source: https://docs.tale.dev/de/platform/editor/overview

Als Redakteur hältst du gemeinsame Informationen brauchbar: Dokumente hochladen, Wissenseinträge korrigieren und Datensätze pflegen. In Projekten kannst du innerhalb deines Bearbeitungszugriffs arbeiten. Beginne mit einer Quelle und einer Frage, die sie beantworten soll. Erweitere die Sammlung, wenn sich weiterer Bedarf zeigt.

## Eine Inhaltsaufgabe wählen

<CardGroup cols="2">

<Card title="Wissen pflegen" icon="library" href="https://docs.tale.dev/de/platform/knowledge/overview">

Wähle Dateien, kurze Informationen, Websites oder strukturierte Datensätze.

</Card>

<Card title="Ein Projekt einrichten" icon="folder-open" href="https://docs.tale.dev/de/tutorials/member/use-projects">

Halte Dateien und Anweisungen zusammen und frage im Projektchat nach.

</Card>

<Card title="Arbeit als Aufgaben verfolgen" icon="list-checks" href="https://docs.tale.dev/de/platform/projects/tasks">

Dokumentiere Abnahmekriterien, Zuständigkeit, Fortschritt und Prüfung.

</Card>

<Card title="Wiederverwendbare Anweisungen pflegen" icon="list-plus" href="https://docs.tale.dev/de/platform/workspace/skills">

Erstelle und teile Skills für Agenten, die eine wiederholbare Methode brauchen.

</Card>

</CardGroup>

## Wann ein Entwickler nötig ist

Die Rolle Redakteur erlaubt weder das Erstellen von Workflows noch die Verwaltung von Connectoren; diese Ressourcen sind schreibgeschützt. Ein Entwickler, Admin oder Inhaber übernimmt Automatisierungsänderungen und technische Zugangsdaten. Für Projektagenten sind außerdem Projekt-Bearbeitungszugriff sowie funktionierende Provider und Sandboxes nötig. Prüfe [Mitglieder und Rollen](https://docs.tale.dev/de/platform/admin/members-and-roles), bevor du mit einer Anleitung für zusätzliche Berechtigungen beginnst.

# Plattform
Source: https://docs.tale.dev/de/platform

Diese Anleitungen helfen dir bei der Arbeit in Tale, in der Cloud und im eigenen Deployment. Beginne mit einer Frage in einem Chat, halte wiederkehrende Arbeit in einem Projekt zusammen oder öffne die passende Funktionsanleitung, wenn du eine Einstellung ändern möchtest.

## Zwischen Bereichen wechseln {#navigation}

Am Computer zeigt die Navigationsleiste am linken Rand die Bereiche als Symbole: **Start**, **Wissen** und **Automatisierungen**. Am unteren Ende der Leiste liegen **Einstellungen**, deine Benachrichtigungen und dein Profilmenü. Zeigst du auf ein Symbol, erscheint sein Name. Auf dem Smartphone findest du **Start**, **Wissen**, **Automatisierungen** und **Einstellungen** in der Tab-Leiste am unteren Bildschirmrand. **Automatisierungen** sehen nur Inhaber, Admins und Entwickler, weil sie Automatisierungen bauen; Mitglieder und Redakteure sehen den Bereich nicht.

Auf dem Smartphone schwebt die Navigation als abgerundete Leiste über der Seite. Inhalte scrollen dahinter weiter; Nachrichtenfelder und Seitenaktionen bleiben darüber erreichbar. Sobald sich die Bildschirmtastatur öffnet, wird die Leiste ausgeblendet. Schließt du die Tastatur, erscheint sie wieder.

Beim Scrollen nach unten wird die Leiste kleiner, rückt etwas nach unten und zeigt nur noch die Symbole. Scrollst du nach oben, erscheinen die Leiste in voller Größe und die Beschriftungen wieder. Alle Bereiche bleiben in beiden Größen erreichbar.

Ein Bereich öffnet immer seine eigene erste Seite – egal, was du dort zuletzt getan hast. Dieselbe Auswahl führt dich also jedes Mal an dieselbe Stelle. Ein Beispiel: Öffne in einer Automatisierung den Tab **Läufe**, wechsle zu **Start** und wähle dann **Automatisierungen**. Du landest in der Liste der Automatisierungen, nicht auf dem Tab, den du verlassen hast. Am Computer macht nur **Start** dort weiter, wo du aufgehört hast, und öffnet den Chat, den du zuletzt gelesen hast – oder einen neuen Chat, falls es noch keinen gibt. Wählst du **Start** erneut, während du schon dort bist, beginnt ein neuer Chat. Dasselbe erreichst du mit **⌥⌘N** auf dem Mac oder **Alt+Ctrl+N** unter Windows und Linux.

Die **Einstellungen** führen ihre Seiten in einer Seitenleiste neben der Seite auf, und die Kopfzeile nennt die geöffnete Seite; auf dem Smartphone beginnen sie mit einer Liste ihrer Seiten. **Wissen** zeigt seine Seiten als Tabs unter der Kopfzeile.

| Du möchtest … | So gehst du vor |
| --- | --- |
| Einen anderen Bereich öffnen | Wähle den Bereich in der Navigationsleiste oder auf dem Smartphone in der Tab-Leiste. |
| Einen neuen Chat beginnen | Am Computer wählst du **Neuer Chat** im Bereich **Start** oder wählst **Start** erneut, während du bereits dort bist. Auf dem Smartphone öffnest du **Start**, wählst **Chats** und dann **Neuer Chat**. |
| Ein Projekt öffnen | Am Computer wählst du das Projekt im Bereich **Start** unter **Projekte**. Auf dem Smartphone wählst du das Projekt und dann **Projekt öffnen**. |
| Zur Projektliste zurückkehren | Wähle **Alle Projekte** im Bereich **Start** oder klicke oben im Projekt auf den Navigationspfad **Projekte**. |
| Zur Dokumentenliste zurückkehren | Wähle **Wissen**. |

Lesezeichen und geteilte Links zu einem bestimmten Projekt, einer Aufgabe oder einem Dokument öffnen weiterhin dieses Ziel.

### Deine Arbeit in Start finden {#home}

**Start** bündelt deine Chats, Aufgaben, Projekte und Kundenkonversationen. Am Computer bleibt die Seitenleiste von **Start** neben jedem Chat, jeder Aufgabe, jedem Projekt und jeder Inbox-Seite stehen. Auf dem Smartphone öffnet **Start** dieselbe Liste als eigenen Bildschirm. Öffnest du von dort einen Chat, eine Aufgabe oder eine Konversation, hat die Seite nur eine Kopfzeile mit einem Zurück-Pfeil zur Liste, dem Titel und den Aktionen. Dein Profilmenü bleibt oben auf dem Bildschirm **Start** und in den **Einstellungen** erreichbar.

Am Computer kannst du den rechten Rand der Seitenleiste von **Start** ziehen, um ihre Breite anzupassen. Du kannst die Trennlinie auch mit Tab fokussieren und die linke oder rechte Pfeiltaste drücken. Dein Browser merkt sich die Breite für diese Organisation.

Oben in der Seitenleiste legst du mit **Alle**, **Chats**, **Aufgaben** und **Inbox** fest, was die Liste zeigt. Daneben startest du mit **Neuer Chat**, dem Stift, einen Chat; der Tooltip der Schaltfläche zeigt das Tastenkürzel. **Inbox** erscheint nur, wenn deine Organisation eine Inbox hat: eine live geschaltete Automatisierung, die E-Mails synchronisiert, oder eine API-App, die bereits eine Konversation synchronisiert hat.

**Projekte** listet alle Projekte, die du öffnen kannst. Wähle ein Projekt, um seine Seite mit dem Aufgaben-Board, **Allgemein**, **Chats**, **Wissen** und **Agenten** zu öffnen. Die beiden Symbole neben der Überschrift **Projekte** sind **Alle Projekte**, das die vollständige Projektliste öffnet, und **Neues Projekt**. Ziehst du einen Chat auf ein Projekt, legst du ihn dort ab. Das Menü eines Projekts bietet **Neuer Chat** und **Projekt anheften**.

Unter den Projekten ordnet eine einzige Liste deine Arbeit nach **Angeheftet**, **Heute**, **Gestern**, **Letzte 7 Tage** und **Früher**:

- Deine Chats.
- Die offenen Aufgaben, die dir zugewiesen sind oder auf dein Review warten, aus allen Projekten, die du lesen darfst.
- In **Alle** außerdem die offenen Inbox-Konversationen, die du sehen darfst.

Eine leere Ansicht **Aufgaben** bietet **Alle Projekte**, das die Projektliste öffnet. Am Computer bietet auch eine leere Ansicht **Alle** oder **Chats** **Neuer Chat** an. Lassen sich deine Chats, Aufgaben oder Konversationen nicht laden, behält die Liste, was geladen wurde, und sagt, was fehlt, statt eine leere Ansicht zu zeigen. **Erneut versuchen** lädt es noch einmal.

Auf dem Smartphone unterscheidet sich die Liste in drei Punkten:

- **Neuer Chat** steht oben in der Ansicht **Chats**, nicht in der Kopfzeile. **Neues Projekt** gibt es dort nicht, und das Menü eines Projekts bietet **Projekt öffnen** und **Projekt anheften**.
- Wählst du unter **Projekte** ein Projekt, zeigen **Alle**, **Chats** und **Aufgaben** nur die Chats dieses Projekts und deine offenen Aufgaben darin. Die ausgewählte Projektzeile ist hervorgehoben. Die Einschränkung bleibt bestehen, wenn du zwischen diesen Ansichten wechselst. Wähle die Projektzeile erneut, um den Filter aufzuheben. **Inbox** wird nie nach Projekt eingeschränkt.
- **Alle Projekte** ist ein beschrifteter Link neben der Überschrift **Projekte**, kein Symbol.

Jede Zeile beginnt mit einer Sprechblase, einem farbigen Kreis für den Status der Aufgabe oder den Initialen des Kontakts. Es folgen der Titel mit der Zeit seit der letzten Änderung und darunter eine Zeile Kontext: bei einem Chat sein Projekt, bei einer Aufgabe Kennung und Status wie `WEB-2` **In Prüfung** oder **Wartet auf dein Review**, bei einer Konversation der Kontakt mit seiner letzten Nachricht. Ein Punkt in der Akzentfarbe markiert ungelesene Chats und Konversationen sowie Aufgaben, die auf dein Review warten. Ein Stift mit **Entwurf** am Anfang der Kontextzeile zeigt dir, wo du Text geschrieben, aber noch nicht gesendet hast – bei einem Chat, einer Aufgabe oder einer Konversation, nur nicht beim gerade geöffneten Eintrag. Entwürfe bleiben in dem Browser, in dem du sie geschrieben hast. Das Menü eines Chats bietet **Chat anheften**, **Als gelesen markieren** oder **Als ungelesen markieren**, **Umbenennen**, **In Projekt verschieben…**, **Teilen**, bei einem geteilten Chat **Teilen beenden**, **Archivieren** und **Löschen**. Archivierte Chats wandern unter **Archiviert** ans Ende der Liste.

Die Ansicht **Inbox** zeigt die Konversationen eines Status. Im Statusmenü wählst du **Offen**, **Geschlossen**, **Spam** oder **Archiviert**. Dazu kommen **Neue E-Mail**, ein Suchfeld und die Schaltfläche **Filter** für **Zuständig**, **Lesestatus** und **Kanal**. Willst du mehrere Konversationen auf einmal bearbeiten, zeige auf die Initialen einer Konversation und setze das Häkchen, das dort erscheint. Die Leiste über der Liste bietet dann für offene Konversationen **Nachrichten senden**, **Schließen** und **Als Spam markieren**, für geschlossene und Spam-Konversationen **Erneut öffnen**, außerdem **Archivieren** oder **Dearchivieren** und **Auswahl aufheben**.

Das Kästchen am Anfang der Leiste wählt die ganze Liste aus. Solange nur einige Konversationen ein Häkchen haben, zeigt es einen Strich. Setzt du dann das Häkchen, sind alle Konversationen ausgewählt, die die Liste zeigt; was eine Suche oder ein Filter ausblendet, bleibt außen vor. Bei mehr als 200 ausgewählten Konversationen läuft die Aktion in mehreren Schritten, die die Inbox mitzählt. Die anschließende Meldung nennt, wie viele Konversationen geändert wurden und bei wie vielen es nicht geklappt hat, und gibt den Grund für den ersten Fehlschlag an, wenn einer bekannt ist. Diese bleiben ausgewählt, sodass du es erneut versuchen kannst. Lässt sich die Liste nicht laden, erscheint statt einer leeren Liste **Konversationen konnten nicht geladen werden** mit **Erneut versuchen**.

<Frame caption="Die Ansicht Inbox neben einer geöffneten Konversation: Statusmenü, Neue E-Mail, Suche und Filter über den Konversationen, jede mit Initialen und letzter Nachricht.">

![Start in der Ansicht Inbox mit drei offenen Konversationen — Copy of the August invoice von Léa Martin, Annual discount on the team plan von Hannah Weber und Seat pricing for read-only members von Daniel Okafor — neben der geöffneten Konversation mit Hannah Weber, die ihre zwei Nachrichten, die Antwort des Teams dazwischen und das Nachrichtenfeld zeigt.](https://docs.tale.dev/images/platform/home-inbox.webp)

</Frame>

Ein Chat, eine Aufgabe oder eine Konversation öffnet sich unter einer Kopfzeile mit Symbol, Titel, einer Zeile Kontext und den passenden Aktionen. **Seitenleiste ausblenden** am Anfang dieser Kopfzeile blendet die Seitenleiste von **Start** aus und schafft Platz; **Seitenleiste einblenden** holt sie zurück. Der Tooltip der Schaltfläche zeigt das Tastenkürzel. Auch die Seite eines Projekts bietet diese Schaltfläche am Anfang ihrer Kopfzeile. Bei einer Konversation steht **Link kopieren** an erster Stelle der Aktionen und kopiert einen Link, über den deine Kollegen dieselbe Konversation öffnen. Inhaber und Admins weisen die Konversation in der Kopfzeile einer Person, einem Team oder beiden zu. Wählst du die zugewiesene Person oder das Team erneut, wird diese Zuweisung aufgehoben, ebenso mit **Zuweisung aufheben** und **Team entfernen** am Ende der Liste; die andere Zuweisung bleibt bestehen.

Bilder erscheinen direkt in der E-Mail. Bilder, die auf den Servern des Absenders liegen, lädt Tale für dich, sodass der Absender weder deine IP-Adresse sieht noch erfährt, wann du die Nachricht liest. Ein Bild über 10 MB oder im SVG-Format erscheint nicht.

### Tastenkürzel {#shortcuts}

Am Computer bewegst du dich auch mit der Tastatur durch **Start** und öffnest die Suche:

| Mac | Windows oder Linux | Wirkung |
| --- | --- | --- |
| **⌥⌘N** | **Alt+Ctrl+N** | Beginnt von jeder Seite aus einen neuen Chat. |
| **⌘K** | **Ctrl+K** | Öffnet von jeder Seite aus die Suche, wie die Lupe in der Navigationsleiste. |
| **⌘\\** | **Ctrl+\\** | Blendet die Seitenleiste von **Start** bei einem Chat, einer Aufgabe oder einer geöffneten Konversation aus oder ein. |
| **⌥↑** oder **⌥↓** | **Alt+↑** oder **Alt+↓** | Öffnet den vorherigen oder nächsten Eintrag der aktuellen Ansicht, auch bei ausgeblendeter Seitenleiste. |
| **↑** oder **↓** | **↑** oder **↓** | Springt zur Zeile darüber oder darunter, sobald eine Zeile der Seitenleiste den Tastaturfokus hat. |

Ist aus der Liste nichts geöffnet, öffnet **⌥↓** (**Alt+↓**) ihren ersten Eintrag und **⌥↑** (**Alt+↑**) ihren letzten. In einem Textfeld behalten diese Tasten ihre gewohnte Funktion. Hat eine Zeile den Tastaturfokus, springen die Tasten **Pos1** und **Ende** zur ersten und letzten Zeile ihrer Liste, und **Enter** öffnet die fokussierte Zeile.

## Eine Funktion wählen

<CardGroup cols="2">

<Card title="Chat" icon="message-circle" href="https://docs.tale.dev/de/platform/chat/overview">

Fragen stellen, Dateien anhängen, Quellen prüfen, Modelle vergleichen und Gespräche teilen.

</Card>

<Card title="Projekte" icon="folder-open" href="https://docs.tale.dev/de/platform/projects/overview">

Dateien, Anweisungen, persönliche und geteilte Chats sowie Aufgaben zusammenhalten.

</Card>

<Card title="Agenten" icon="bot" href="https://docs.tale.dev/de/platform/agents/concepts">

Agenten mit passendem Harness, Modell und Ausstattung für Projektaufgaben einrichten.

</Card>

<Card title="Automatisierungen" icon="workflow" href="https://docs.tale.dev/de/platform/automations/concepts">

Einen wiederholbaren Ablauf erstellen, testen, bereitstellen und seine Läufe prüfen.

</Card>

<Card title="Wissen" icon="library" href="https://docs.tale.dev/de/platform/knowledge/overview">

Dokumente, kurze Informationen, öffentliche Websites, Kontakte und Produkte pflegen.

</Card>

<Card title="Freigaben" icon="check-check" href="https://docs.tale.dev/de/platform/approvals/concepts">

Eine vorgeschlagene Aktion der Automatisierung prüfen, bevor du sie zulässt.

</Card>

<Card title="Skill-Bibliothek" icon="list-plus" href="https://docs.tale.dev/de/platform/workspace/skills">

Wiederverwendbare Anweisungen erstellen und mit Teams oder der Organisation teilen.

</Card>

<Card title="Modelle" icon="cpu" href="https://docs.tale.dev/de/platform/models">

Fähigkeiten, Verfügbarkeit und Auswahl von Modellen verstehen.

</Card>

<Card title="Connectors" icon="plug" href="https://docs.tale.dev/de/platform/connectors/overview">

Externe Dienste verbinden und verfügbare Aktionen für Agenten und Automatisierungen kennen.

</Card>

</CardGroup>

## Deinen Einstieg finden

Deine Rolle bestimmt die verfügbaren Aktionen. Teams und Projektzugriff bestimmen, welche Inhalte du erreichen kannst. Wähle den Einstieg, der zu deiner Arbeit passt. Fehlende Aktionen kann ein Administrator erklären.

<CardGroup cols="2">

<Card title="Mitglied" icon="user" href="https://docs.tale.dev/de/platform/member/overview">

Fragen stellen, gemeinsames Wissen lesen und persönliche Einstellungen verwalten.

</Card>

<Card title="Redakteur" icon="pencil-ruler" href="https://docs.tale.dev/de/platform/editor/overview">

Gemeinsame Inhalte pflegen und in bearbeitbaren Projekten arbeiten.

</Card>

<Card title="Entwickler" icon="terminal" href="https://docs.tale.dev/de/platform/developer/overview">

Automatisierungen erstellen und Code, Clients sowie externe Dienste verbinden.

</Card>

<Card title="Admin" icon="shield" href="https://docs.tale.dev/de/platform/admin/overview">

Personen, Provider, Infrastruktur und Organisationsrichtlinien einrichten.

</Card>

</CardGroup>

# Websites zum Wissen hinzufügen
Source: https://docs.tale.dev/de/platform/knowledge/crawling

Füge eine Website hinzu, wenn dein Team Fragen zu öffentlichen, veränderlichen Inhalten stellen möchte. Tale ruft die ausgewählten Seiten ab und indexiert ihren lesbaren Text für die Wissenssuche. Zum Verwalten brauchst du Redakteurrechte oder höher. Seiten hinter einer Anmeldung benötigen einen anderen Importweg, etwa [Dokumente](https://docs.tale.dev/de/platform/knowledge/documents).

## Eine Website oder einzelne Seiten hinzufügen

Öffne **Wissen > Websites** und klicke auf **Website hinzufügen**. Wähle vor der Adresse den Quelltyp:

| Quelltyp | Wann er passt | Eingabe |
| --- | --- | --- |
| **Gesamte Website** | Du möchtest Inhalte innerhalb einer Domain entdecken lassen | Eine **Domain**, etwa `example.com` |
| **URL-Liste** | Du brauchst bestimmte Seiten oder öffentliche Dokumente | Eine Adresse pro Zeile unter **URLs** |

Bei einer ganzen Website wird aus einer URL nur der Hostname verwendet. Ein eingefügter Pfad beschränkt den Crawl nicht auf diesen Pfad. Nutze dafür die URL-Liste. Eine `http://`-Adresse wird abgewiesen, weil der Crawler nur über HTTPS holt, und ein Punkt am Ende fällt weg. Schreibweisen mit und ohne `www` zählen als dieselbe Website; beide hinzuzufügen führt zu einer Duplikatmeldung.

Wähle das **Scan-Intervall** und **Speichern**. Standard sind sechs Stunden; die Auswahl reicht von einer Stunde bis zu dreißig Tagen. Der Scheduler übernimmt neue Quellen. Das Speichern bedeutet nicht, dass bereits alle Seiten abgerufen und indexiert wurden.

<Frame caption="Für eine ganze Website genügen Domain und Scan-Intervall. Für eine bestimmte Seitenauswahl nutze die URL-Liste.">

![Der Dialog Website hinzufügen zeigt Domain und Scan-Intervall mit sechs Stunden als Standard.](https://docs.tale.dev/images/platform/websites-add-dialog.webp)

</Frame>

## Die Seiten im Chat durchsuchbar machen

Beim Crawlen wird der Text einer Seite gespeichert. Chat und Wissenssuche erreichen ihn erst, wenn deine Organisation ein funktionierendes Embedding-Modell hat, denn jede Suche wandelt die Frage zuerst in einen Vektor um. Ohne Modell kann eine Quelle **Aktiv** anzeigen und alle Seiten indexiert haben, während der Assistent antwortet, die Suche in Webseiten sei nicht eingerichtet.

**Wissen > Websites** zeigt dann den Hinweis **Der Chat kann diese Websites noch nicht durchsuchen**; ein Administrator sieht an seiner Stelle unter Umständen das Banner **Wissenssuche ist aus**, über jeder Seite. Ein Administrator legt das Modell unter **Einstellungen > Datenresidenz** fest; Einzelheiten für Betreiber stehen unter [Datenresidenz](https://docs.tale.dev/de/self-hosted/configuration/data-residency). Sobald ein Modell gespeichert ist, scannt Tale jede Quelle erneut, die ohne Modell gecrawlt wurde oder deren letzter Scan fehlgeschlagen ist. Du musst sie nicht neu hinzufügen.

## Eine URL-Liste gezielt halten

Eine URL-Liste ruft nur die angegebenen Adressen ab und folgt keinen weiteren Links. Sie darf Seiten mehrerer Websites enthalten. Tale fasst sie zu einer Quelle pro Website zusammen. Eine gelistete `http://`-Adresse wird angenommen und als `https://` abgerufen — anders als eine `http://`-Domain im Modus für ganze Websites, die abgewiesen wird; eine Seite, die nur unverschlüsselt antwortet, bleibt in beiden Fällen unerreichbar. Eine weitere Liste für eine vorhandene URL-Listenquelle ergänzt Adressen, ohne bestehende zu entfernen, und aktualisiert ihr Scan-Intervall.

Nutze vollständige öffentliche URLs. Verlinkte PDF- und moderne Office-Dateien lassen sich indexieren, wenn sie lesbaren Text enthalten. Einen Download, den der Server unter einem generischen oder veralteten Typ ausliefert (`application/octet-stream`, `application/vnd.ms-excel` bei einem `.xlsx`-Export), erkennt der Crawler an Dateiname und Inhalt. Bilder und Scans ohne extrahierbaren Text werden dadurch nicht durchsuchbar.

## Entdeckung und Aktualisierung verstehen

Bei einer ganzen Website nutzt der Crawler Startseite und veröffentlichte Sitemaps, einschließlich Sitemap-Indizes und in `robots.txt` angegebener Sitemaps. Fehlen brauchbare Sitemaps, folgt er Links innerhalb der Domain von der Startseite aus. Seiten, die weder in Sitemaps noch über erreichbare Links vorkommen, können fehlen. Nutze eine URL-Liste, wenn bestimmte Seiten enthalten sein müssen.

Scans arbeiten schrittweise: Unveränderte Inhalte werden übersprungen, geänderte erneut indexiert, neue Seiten hinzugefügt und entfernte aus dem Index genommen — ebenso Seiten, die die `robots.txt` inzwischen verbietet. Eine Seite, die auf eine andere Adresse derselben Website weiterleitet, wird nur einmal indexiert: unter der Adresse, auf der sie landet. Die Seitenzähler der Zeile folgen dem Scan, während Seiten landen, nach dem Entdecken und nach jedem gespeicherten Batch, die Tabelle bewegt sich also, während ein Scan läuft. Eine URL-Liste aktualisiert ihre feste Auswahl nach demselben Zeitplan. Nach erfolgreicher Indexierung ist keine gesonderte Veröffentlichung nötig.

Der Crawler besucht die Seiten ohne Anmeldung. Eine URL macht private Inhalte nicht zugänglich. Bei jeder Anfrage stellt er sich als `TaleBot/<version> (+https://docs.tale.dev/platform/knowledge/crawling)` vor, sodass eine `robots.txt`-Gruppe ihn beim Namen nennen kann — `User-agent: TaleBot` —, um allein ihn zu erlauben, zu drosseln oder abzuweisen.

Der Crawler hält sich an die `Disallow`-Regeln der `robots.txt` für den Agenten `*` auf jedem Weg, über den eine URL hereinkommen kann — die Sitemaps, der Linklauf und die Links, die eine gerenderte JavaScript-Seite preisgibt — und noch einmal vor jedem Abruf: Eine Seite, die eine Regel abdeckt, wird nie geholt, und eine Seite, die eine später hinzugekommene Regel abdeckt, verlässt den Index beim nächsten Scan. Ausdrücklich angegebene URLs filtern die Regeln nicht: Eine gelistete Adresse ist deine Anweisung. Liefert ein Abruf den HTTP-Header `X-Robots-Tag: noindex` oder `none` oder trägt die Seite ein HTML-Tag `<meta name="robots" content="noindex">`, wird der Inhalt nicht indexiert — auch bei einer URL-Liste —, und was ein früherer Scan von der Seite gespeichert hat, fällt weg. Diese Regeln sind Höflichkeit, kein Zugriffsschutz: Wenn du die Quellwebsite verwaltest, verlass dich nicht auf den Crawler als Zugangskontrolle.

Verwende HTTPS am Standardport und registriere einen Hostnamen: Adressen mit einem abweichenden Port wie `:8001` und nackte IP-Adressen werden abgewiesen — der Crawler wählt über den Hostnamen und prüft das Zertifikat dagegen. Private Adressen und Weiterleitungen in private Netze sind gesperrt, sofern der Betreiber solche internen Quellen nicht ausdrücklich für seine Installation freigegeben hat.

## Die Crawl-Grenzen berücksichtigen

| Grenze | Auswirkung auf die Abdeckung |
| --- | --- |
| 10.000 erfasste URLs je Website | Bei größeren Websites können Seiten unentdeckt bleiben. Nutze eine gezielte URL-Liste für die benötigten Inhalte. |
| Drei Minuten für die Seitensuche, höchstens 50 Sitemap-Abrufe | Große oder langsame Sitemap-Sammlungen werden möglicherweise nicht vollständig erfasst. |
| 100 MiB (`KNOWLEDGE_CRAWL_DOCUMENT_MAX_BYTES`) und 30 Sekunden je Inhaltsabruf | Zu große Downloads und langsame Antworten schlagen fehl (`timeout` für das Download- und das 20-Sekunden-Darstellungsbudget); ebenso eine Seite hinter mehr als fünf Weiterleitungen (`redirect_limit_exceeded`). |
| Fünf Minuten Verarbeitungsbudget je Abschnitt, bis zu 200 Fortsetzungen | Lange Scans laufen abschnittsweise weiter. Ein bereits begonnener Abruf oder Darstellungsvorgang kann das Abschnittsbudget überschreiten; daraus ergibt sich keine garantierte Gesamtdauer. |
| Fünf aufeinanderfolgende Fehler bei einer automatisch entdeckten URL | Der Crawler plant diese URL sieben Tage lang nicht mehr ein und probiert sie danach einmal erneut. Ein Fehler der Sandbox selbst, in der die Seiten dargestellt werden, zählt nicht: Lehnt ihr Egress-Proxy die Verbindung ab oder antwortet ihr Browser nicht mehr, endet der Scan mit dieser Ursache an der Quelle, und der nächste Scan versucht jede Seite erneut. Ausdrücklich gelistete URLs werden bei jedem Scan erneut berücksichtigt, und eine gelistete Seite, die die Website mit 404 beantwortet, bleibt mit dieser Antwort in der Liste. |

Du kannst weder eine eigene Seitenobergrenze noch Pfadfilter festlegen oder einen laufenden Scan per Schaltfläche stoppen. Eine URL-Liste begrenzt die angefragte Auswahl; die genannten Grenzen gelten weiterhin.

## Die indexierten Inhalte prüfen

Die Tabelle zeigt **Status**, die Seitenzahl unter **Indexiert**, **Gescannt** und **Intervall**. Öffne die Quellzeile, um die Seitenliste, Wort- und Chunk-Anzahl sowie den letzten Abruf zu prüfen. Klappe eine Seite auf, um die gespeicherten Textabschnitte zu lesen. Bei einem fehlgeschlagenen Abruf stehen dort Ursache und Anzahl aufeinanderfolgender Fehler. Eine Seite, die der Crawler bewusst auslässt — die Quelle wünscht keine Indexierung, der Inhaltstyp liefert keinen lesbaren Text, oder eine Weiterleitung führt von der Website weg — steht als **Übersprungen** mit ihrer Ursache in der Liste und zählt nicht als fehlgeschlagen.

| Status | Bedeutung |
| --- | --- |
| **Wird gescannt** | Ein Scan läuft; eine gerade hinzugefügte Quelle beginnt hier. |
| **Aktiv** | Ein Scan ist erfolgreich abgeschlossen. Prüfe die einzelnen Seiten für die Abdeckung. |
| **Fehler** | Der Scan ist fehlgeschlagen oder nach den Abrufversuchen sind keine Inhalte gespeichert. Öffne die Quelle für die Ursache. |
| **Lösche…** | Die Quelle wird entfernt. |

Ein Scan, der gerade lief, als Tale neu gestartet, aktualisiert oder ohne Vorwarnung beendet wurde, läuft innerhalb weniger Minuten von selbst weiter, und zwar mit den Seiten, die er noch nicht erreicht hatte. Seiten, die den Browser brauchen, können bis zu einer Viertelstunde später folgen. Die Quelle zeigt währenddessen **Wird gescannt**.

Um außerhalb des Intervalls zu scannen, öffne das Zeilenmenü der Quelle oder ihre Details und wähle **Jetzt scannen**. Das hilft, wenn sich die Website geändert hat oder ein Scan fehlgeschlagen ist; ein fehlgeschlagener Scan wird sonst innerhalb von zwei Stunden von selbst wiederholt. Die Aktion steht zur Verfügung, solange die Quelle weder gescannt noch gelöscht wird.

Die Seitenansicht bietet auch eine Suche im indexierten Inhalt. Suche nach einer auffälligen Formulierung der Seite, bevor du dich im Chat darauf verlässt. Stelle anschließend eine konkrete Frage und prüfe den Quellenbeleg.

## Eine fehlende Seite untersuchen

Prüfe zuerst Adresse, Quelltyp und letzte Scan-Zeit. Öffne danach die Quelle, schalte die Seitenliste auf **Fehlgeschlagen** oder **Übersprungen** und lies die Fehlermeldung der betroffenen Seite.

| Gemeldetes Problem | Prüfung oder Abhilfe |
| --- | --- |
| Zertifikat nicht vertrauenswürdig | Der Website-Betreiber muss ein abgelaufenes, selbst signiertes, zum falschen Host gehörendes oder anderweitig nicht vertrauenswürdiges TLS-Zertifikat korrigieren. Weitere Scans beheben es nicht. |
| Private Adresse, unzulässige Weiterleitung oder ungültige URL | Nutze die vorgesehene öffentliche HTTPS-Adresse. Frage bei Bedarf deinen Betreiber nach zugelassenen internen Quellen. |
| HTTP-Fehler, Netzwerkfehler oder Zeitüberschreitung | Öffne die Originalseite und prüfe ihre Erreichbarkeit. Nach der Reparatur kann ein späterer Scan wieder erfolgreich sein. |
| Antwort zu groß | Veröffentliche ein kleineres Dokument oder teile die Quelle auf. Die Abrufgrenze beträgt 100 MiB, sofern dein Betreiber `KNOWLEDGE_CRAWL_DOCUMENT_MAX_BYTES` nicht anders gesetzt hat. |
| Quelle untersagt die Indexierung | Die Antwort enthält `X-Robots-Tag: noindex` oder `none`, oder die Seite trägt `<meta name="robots" content="noindex">`. Der Website-Verantwortliche muss diese Vorgabe ändern, bevor Tale den Inhalt indexieren kann. |
| Nicht unterstützter Inhalt oder kein lesbarer Text | JSON-/XML-Endpunkte, Binärdownloads, Bilder oder Scans liefern möglicherweise keinen verwertbaren Seitentext. Stelle eine HTML-Seite oder ein unterstütztes Dokument mit extrahierbarem Text bereit. |
| Darstellung oder Textextraktion fehlgeschlagen | Prüfe, ob die öffentliche Seite lädt und sich das Originaldokument öffnen lässt. Repariere oder exportiere eine beschädigte Quelle erneut. |
| Der Assistent meldet, die Suche in Webseiten sei nicht eingerichtet | Die Organisation hat kein funktionierendes Embedding-Modell. Ein Administrator legt es unter **Einstellungen > Datenresidenz** fest; danach scannt Tale die betroffenen Quellen erneut. |
| **Fehler** mit „Das Embedding-Modell konnte die Seiten nicht verarbeiten.“ | Der Embedding-Anbieter hat die Anfrage abgelehnt oder konnte sie nicht bedienen: abgelehnte Zugangsdaten, aufgebrauchtes Guthaben, ein Ratenlimit, das über alle Wiederholungen anhielt, oder ein Ausfall. Die Details der Quelle sagen, was davon zutrifft, mit der Antwort des Anbieters darunter. Ein Administrator repariert das Modell unter **Einstellungen > Datenresidenz** oder die Zugangsdaten unter **Einstellungen > KI-Anbieter**; beim Speichern werden die betroffenen Quellen erneut gescannt. Nach einem Ausfall beim Anbieter wählst du **Jetzt scannen**, sobald er wieder erreichbar ist. |
| **Fehler** mit „Der Scan ist nicht gelaufen.“ | Der Browser des Crawlers konnte nicht starten, deshalb wurde keine Seite dargestellt; sein Bericht steht in den Details der Quelle unter **Technische Details**. An der Adresse liegt es nicht: Lass deinen Betreiber den Sandbox-Dienst prüfen und wähle danach **Jetzt scannen**. |

Ein späterer erfolgreicher Abruf entfernt den vorherigen Fehler. Nach einer fehlgeschlagenen Aktualisierung kann die früher indexierte Fassung weiterhin verfügbar sein: **Aktiv** und die Anzahl indexierter Seiten belegen nicht, dass jede Seite aktuell ist. Vergleiche gespeicherte Textabschnitte und Abrufdatum mit dem Original, bevor du dich auf eine kürzliche Änderung verlässt.

Zeigt die Quelle **Pausiert**, haben wiederholte Verbindungsfehler zur Wissensdatenbank die Scans angehalten. Lass einen Administrator die Verbindung unter **Einstellungen > Datenresidenz** korrigieren und wähle danach **Scans fortsetzen**.

# Dokumente
Source: https://docs.tale.dev/de/platform/knowledge/documents

Unter **Wissen > Dokumente** gehören Dateien in die gemeinsame Bibliothek: Richtlinien, Anleitungen, Berichte und Belege. Mitglieder lesen Dokumente innerhalb ihrer Zugriffsrechte. Redakteure und höhere Rollen können sie hochladen und verwalten. Material für ein einzelnes Projekt gehört auf dessen [Wissen-Tab](https://docs.tale.dev/de/platform/projects/manage-files).

<Frame caption="Die Dokumentliste verbindet Originaldatei, Herkunft, Indexierungsstatus und Team-Zugriff. Die Ansicht ist auf hochgeladene, indexierte Dateien gefiltert.">

![Der Dokumente-Tab zeigt gemeinsame Dateien mit Größe, Quelle, RAG-Status und Team-Spalten.](https://docs.tale.dev/images/get-started/documents-list.webp)

</Frame>

## Vom Gerät hochladen

1. Öffne **Wissen > Dokumente** und den gewünschten Zielordner. Lege bei Bedarf mit **Neuer Ordner** einen an.
2. Wähle **Dokumente hochladen > Von deinem Gerät** und die Dateien.
3. Warte auf den Abschluss des Uploads und suche die Zeilen in der Tabelle.
4. Öffne ein Dokument, um Vorschau und Details zu prüfen. Kontrolliere den **RAG-Status**, bevor du den Assistenten nach seinem Inhalt fragst.

Wähle einen aussagekräftigen Dateinamen. Ein Datum oder eine Revision hilft, Quellen auseinanderzuhalten. Eine weitere Datei mit demselben Namen wird als eigenes Dokument angelegt; sie ersetzt die vorhandene nicht.

## Upload und Suchbarkeit unterscheiden

Eine gespeicherte Datei ist nicht automatisch durchsuchbar. Tale muss zuerst ihren Text auslesen können, um sie für die Wissenssuche zu indexieren.

| Format | Was du erwarten kannst |
| --- | --- |
| PDF mit eingebettetem Text, `.docx`, `.xlsx`, `.pptx`, `.odt`, CSV, reiner Text | Textextraktion und Indexierung werden unterstützt. Prüfe das Ergebnis für die konkrete Datei. |
| Ältere Office-Formate `.doc`, `.xls`, `.ppt` | Speichern und Herunterladen sind möglich. Konvertiere sie zur Indexierung in ein modernes Format. |
| Bilder wie JPG, PNG, GIF, WEBP | Speichern und Herunterladen sind möglich. Der Wissensindex liest daraus keinen Text aus. |
| Microsoft-Loop-Dateien (`.loop`) aus Microsoft 365 | Importieren und Herunterladen sind möglich. Tale kann ihren Text nicht auslesen, daher erhalten sie den Status **Nicht unterstützt**. |
| Gescanntes PDF ohne lesbaren Text | Stelle eine Fassung mit OCR oder Text bereit, wenn der Inhalt durchsuchbar sein soll. |

Wiederholtes Indexieren macht ein nicht unterstütztes Format nicht durchsuchbar. Für Fragen zu einem Bild siehe [Chat-Anhänge](https://docs.tale.dev/de/platform/chat/attachments): Ein verfügbares Bildmodell kann es dort direkt lesen.

## Den Indexierungsstatus lesen

| Status | Bedeutung und nächster Schritt |
| --- | --- |
| **In Warteschlange** | Wartet auf einen freien Indexierungsplatz. Eine ausgelastete Bibliothek verarbeitet Dateien nach und nach. |
| **Wird indexiert** | Der Text wird für die Suche vorbereitet. Warte mit der Prüfung der Quelle. |
| **Indexiert** | Die Indexierung ist abgeschlossen. Stelle eine konkrete Frage und öffne den Quellenbeleg. |
| **Neuindexierung nötig** | Der Index ist veraltet. Nutze **Indexierung erneut versuchen** neben der Statusanzeige. |
| **Fehlgeschlagen** | Lies den Fehler, behebe die Ursache und versuche es erneut. |
| **Nicht unterstützt** | Dieser Dateiinhalt lässt sich nicht indexieren: etwa bei einem ungeeigneten Format, leerem oder unlesbarem Text oder einer beschädigten PDF-Datei. Öffne die Statusanzeige für die Ursache. |
| **Nicht indexiert** | Es liegt kein abgeschlossener Index vor. Prüfe die Datei und starte die Indexierung, wenn angeboten. |

Unterbrochene Vorgänge werden im Hintergrund wieder aufgenommen oder melden einen Fehler mit Wiederholungsoption. Bleibt der Status stehen, gib einem Administrator Dokumentname und Fehlermeldung. Er kann Indexierungsdienste und Embedding-Konfiguration prüfen. Fehlgeschlagene und nicht unterstützte Dateien belegen weiterhin Speicher, bis du sie entfernst.

## Ein Indexierungsproblem beheben

Klicke auf **Fehlgeschlagen** oder **Nicht unterstützt**, um die Erklärung zu lesen. Entscheidend für die Abhilfe ist die Ursache, nicht allein die Dateiendung.

| Ursache | Nächster Schritt |
| --- | --- |
| Nicht unterstütztes Format oder Bild | Konvertiere die Quelle in ein unterstütztes Dokument mit lesbarem Text. Ein Bild-Upload allein führt keine OCR für die Wissenssuche aus. |
| Leerer Text oder gescannte PDF-Datei ohne Textebene | Ergänze den fehlenden Inhalt oder stelle eine OCR-verarbeitete Fassung bereit. Nur Leerzeichen und Zeilenumbrüche zählen ebenfalls als leer. |
| Binärdaten mit einer Textdateiendung | Exportiere lesbaren Text, möglichst in UTF-8. Das Umbenennen einer Binärdatei in `.txt` konvertiert sie nicht. |
| PDF-Datei lässt sich nicht auslesen | Prüfe, ob sich das Original öffnen lässt. Entferne einen Kennwortschutz, soweit erlaubt, oder exportiere eine neue PDF-Datei. Bei beschädigten Office-Dateien kann stattdessen ein allgemeiner Indexierungsfehler erscheinen; prüfe das Original vor weiteren Versuchen. |
| Ein Zugangsschlüssel oder eine Datenschutzregel blockiert die Indexierung | Entferne die Zugangsdaten aus der Quelle oder lass einen Administrator die gemeldete Richtlinie prüfen. Lade danach das korrigierte Material hoch oder versuche es nach der Konfigurationskorrektur erneut. |
| Embedding-Modell fehlt oder der Anbieter lehnt das Konto ab | Ein Administrator muss das Modell unter **Einstellungen > Datenresidenz** konfigurieren oder Schlüssel, Modellzugriff, Tarif beziehungsweise Guthaben beim Anbieter korrigieren. Versuche es danach erneut. |
| Zugangsdaten für das Embedding fehlen oder sind unbrauchbar | Die Zugangsdaten, die das Embedding-Modell verwendet, wurden gelöscht oder deaktiviert, der Anbieter hat keinen Standard mehr (**Einstellungen > Datenresidenz** zeigt **Zugangsdaten fehlen**), oder ihr Geheimnis lässt sich nicht lesen: Es wurde mit einem früheren Verschlüsselungsschlüssel gespeichert, oder die Zugangsdaten verweisen auf eine Umgebungsvariable, die der Server nicht setzt. Ein Administrator legt die Zugangsdaten unter **Einstellungen > KI-Anbieter** an oder repariert sie oder wählt andere für das Embedding-Modell. Jede dieser Speicherungen stellt die betroffenen Dokumente wieder in die Warteschlange. Wurde der Fehler auf dem Server selbst behoben, etwa durch das Setzen der Umgebungsvariable, nutze **Indexierung erneut versuchen**. |
| Vorübergehender Fehler beim Anbieter oder Indexierungsdienst | Hintergrundaufträge wiederholen vorübergehende Fehler. Bleibt der Fehler bestehen, gib einem Administrator Dokumentname und Meldung. Nach der Reparatur nutze **Indexierung erneut versuchen**. |
| Suchindex wird neu aufgebaut oder Reparatur fehlgeschlagen | Der Neuaufbau kann automatisch abschließen. Scheitert die Reparatur, muss der Betreiber die Wissensdatenbank reparieren oder wiederherstellen, bevor ein neuer Versuch hilft. |

Bei **Nicht unterstützt** gibt es keine Wiederholungsaktion: Dieselben Dateiinhalte würden wieder scheitern. Auch bei **Fehlgeschlagen** kann zuerst eine Änderung an Quelle oder Konfiguration nötig sein. Anwendungen unterscheiden die Fälle anhand von `indexing.errorCode`; die [API-Referenz](https://docs.tale.dev/de/develop/api-reference) führt die stabilen Codes auf.

<Frame caption="Der Statusdialog erklärt, dass dieses Dokument keinen indexierbaren Text enthält. Ergänze lesbaren Inhalt vor dem erneuten Upload.">

![Der englische Statusdialog meldet ein leeres Dokument oder einen Scan ohne Textebene und empfiehlt eine lesbare Textversion.](https://docs.tale.dev/images/platform/document-indexing-unsupported.webp)

</Frame>

## Wenn die Dokumente nicht geladen werden

**Dokumente** listet Ordner und Dokumente aus zwei getrennten Abrufen auf. Lassen sich die Dokumente nicht laden, gibt Tale die Ordner nicht als den ganzen Inhalt aus:

- Die Ordner bleiben in der Liste, und du kannst sie weiter öffnen. Ein Hinweis über der Tabelle sagt, dass die Dokumente nicht geladen werden konnten, und bietet **Erneut versuchen** an. Das wiederholt den Abruf, ohne dass du die Seite neu laden musst.
- Die Anzahl unter der Tabelle sagt, dass nur die ersten Einträge angezeigt werden und der Rest nicht geladen werden konnte. Eine Suche umfasst nur, was aufgelistet ist.
- Waren bereits Dokumente zu sehen, als eine Aktualisierung fehlschlug, bleiben sie stehen, und der Hinweis sagt, dass die Liste unvollständig oder veraltet sein kann.
- Während du es erneut versuchst, bleiben die Zeilen sichtbar, und deine Suche, deine Filter und ein geöffneter Dialog bleiben erhalten.
- Lässt sich gar nichts laden, zeigt die Tabelle statt des leeren Zustands den Fehler mit **Erneut versuchen**.

Ein Ordner, der wirklich keine Dokumente enthält, zeigt seine Unterordner ohne Hinweis. Scheitert **Erneut versuchen** immer wieder, bitte einen Administrator zu prüfen, ob die Dienste von Tale laufen.

## Festlegen, wer das Dokument lesen kann

Bibliotheksdokumente sind standardmäßig **Organisationsweit** zugänglich. Begrenze den Zugriff über **Team zuweisen** im Zeilenmenü auf die gewählten Teams: Die Mitglieder eines dieser Teams können das Dokument lesen, Inhaber und Admins immer. Sofern du nicht Inhaber oder Admin bist, kannst du nur Teams wählen, denen du selbst angehörst. Ein Dokument in einem Team-Ordner übernimmt die Teams des Ordners und kann kein Team außerhalb davon nennen; wird ein Dokument in einen solchen Ordner verschoben, gelten die Teams des Ordners. Diese Beschränkungen gelten auch bei der Wissenssuche. Ein Agent kann unzugängliche Dokumente nicht über die Suche sichtbar machen.

Auf der obersten Bibliotheksebene siehst du Ordner und Dokumente, die keinem Ordner zugeordnet sind. Öffne einen Ordner, um seinen Inhalt zu sehen. Ein dort abgelegtes Dokument erscheint nicht zusätzlich als Dateizeile auf der obersten Ebene.

Ordner gliedern die Bibliothek; umbenennen kannst du einen Ordner mit **Umbenennen** in seinem Zeilenmenü. Ein synchronisierter Ordner, die Ordner darin und die Ordner, die ihn enthalten, behalten ihre Namen, denn jede Synchronisierung baut diesen Pfad neu auf. Prüfe den Zugriff in der Zelle **Teams** und die Herkunft in der Spalte **Quelle**. Der Filter **Teams** grenzt die Liste auf **Organisationsweit** zugängliche Einträge, auf **Meine Teams** (alles, was eines deiner Teams sehen darf) oder auf ein Team nach Namen ein; die Auswahl steht in der Seitenadresse, sodass sich eine gefilterte Liste als Lesezeichen speichern lässt. Projektdateien haben einen eigenen Zugriffsbereich und erscheinen nicht hier. Der [Wissensüberblick](https://docs.tale.dev/de/platform/knowledge/overview) hilft bei der Wahl des Ablageorts.

## Aus Microsoft 365 oder Google Drive importieren

Wähle **Von Microsoft 365** oder **Von Google Drive** unter **Dokumente hochladen**. Verbinde beim ersten Mal dein Konto und erlaube den Import. Meldet Tale eine fehlende Einrichtung, muss ein Administrator den Dienst unter [Connectoren](https://docs.tale.dev/de/platform/admin/connectors) konfigurieren.

Wähle Dateien oder Ordner und anschließend den Importmodus:

| Modus | Ergebnis |
| --- | --- |
| **Einmaliger Import** | Kopiert die Auswahl einmal und erhält die Ordnerstruktur. Spätere Änderungen an der Quelle ändern die Kopie nicht. |
| **Synchronisierungsimport** | Hält die unterstützte Auswahl aktuell. Neue Dateien folgen bei einem späteren Abgleich; Änderungen werden neu indexiert; an der Quelle gelöschte Dateien verschwinden aus dem Abbild. |

In der Bibliothek zeigt die Spalte **Quelle**, woher eine Datei stammt. Eine importierte Datei trägt das Logo von OneDrive, SharePoint oder Google Drive. Kreispfeile neben dem Logo bedeuten, dass ein Synchronisierungsimport die Datei aktuell hält; sie stehen auch beim synchronisierten Ordner selbst. Durchgestrichene Kreispfeile stehen für einen einmaligen Import. Hochgeladene Dateien, von einem Agenten oder einer Automatisierung geschriebene Dateien, Wissenseinträge und API-Importe zeigen jeweils ein eigenes Symbol. Zeigst du auf ein Symbol, erscheint die Quelle als Text.

Ein neuer Ordnerabgleich kann auch einen früheren Import umordnen. Ist dieselbe Quelldatei bereits in Tale vorhanden, übernimmt die Synchronisierung dieses Dokument und verschiebt es in den passenden Sync-Ordner — selbst wenn der Inhalt unverändert ist. Entscheidend ist die Identität der Quelldatei, nicht nur ihr Name. Gibt es keinen Zielordner für den Abgleich, bleibt die bisherige Ablage erhalten.

Bei Microsoft 365 stehen **Mein OneDrive** und **SharePoint-Websites** zur Wahl. Die Synchronisierung unterstützt persönliche OneDrive-Ordner; SharePoint wird einmalig importiert. Wähle bei Google Drive aus Mein Drive. Native Google Docs, Tabellen und Präsentationen werden übersprungen. Exportiere sie zuerst als PDF oder Office-Dateien.

Ist ein Ordner zu groß für eine vollständige Auflistung, lehnt Tale den Import ab. Wähle kleinere Unterordner oder nutze die Synchronisierung, soweit unterstützt. Wird der ausgewählte Quellordner oder die Quelldatei gelöscht, entfernt Tale das Abbild und beendet die Synchronisierung.

Am Ende eines Imports meldet ein Hinweis das Ergebnis. **Import abgeschlossen** zählt die Dateien, die dieser Import übernommen hat, zusammen mit denen, die ein früherer Import schon unverändert übernommen hatte. Konnten nicht alle Dateien importiert werden, erscheint stattdessen eine Warnung wie **3 von 4 Dateien importiert**. Hat die erste fehlgeschlagene Datei einen Grund, den Tale anzeigen kann, etwa eine Datei über der Upload-Grenze, nennt die Warnung diese Datei und den Grund. Konnte keine Datei importiert werden, lautet der Hinweis **Import fehlgeschlagen**. Wenn die Dateiauswahl noch offen ist, importiere erneut, um die fehlgeschlagenen Dateien noch einmal zu versuchen. Bereits importierte Dateien werden übersprungen.

Endet der Zugriff auf dein Microsoft-365- oder Google-Drive-Konto während eines Imports, etwa weil die Verbindung getrennt wurde oder abgelaufen ist, öffnet Tale statt eines Hinweises **Microsoft 365 erneut verbinden** oder **Google Drive erneut verbinden**, solange die Dateiauswahl noch offen ist. Der Dialog sagt, wie viele Dateien bis dahin importiert wurden; diese Dateien bleiben erhalten. Verbinde dein Konto erneut und importiere dann dieselben Dateien oder Ordner noch einmal, um den Rest zu holen. Bereits importierte Dateien werden nicht doppelt importiert.

Wenn du die Dateiauswahl schließt, läuft ein bereits gestarteter Import weiter. Sein Ergebnis erscheint als Hinweis. Eine später geöffnete Dateiauswahl bleibt mit deiner neuen Auswahl erhalten. Ist der Zugriff abgelaufen, öffne den Import erneut, um dein Konto wieder zu verbinden.

Eine Synchronisierung läuft etwa alle 15 Minuten über das Konto des Mitglieds, das sie eingerichtet hat. Eine an der Quelle hinzugefügte Datei erscheint innerhalb dieses Zeitfensters in ihrem Ordner und wird dann wie ein Upload indexiert. Erreicht ein Durchlauf die Quelle nicht, ersetzt die Zelle **Quelle** der Ordnerzeile die Kreispfeile durch ein rotes Warnzeichen mit dem Hinweis **Sync-Fehler** — oder durch einen roten gezogenen Stecker mit dem Hinweis **Neu verbinden**, wenn die Microsoft-365- oder Google-Drive-Verbindung dieses Mitglieds abgelaufen ist. Das Symbol öffnet die Ursache, den Beginn der Fehlschläge und das Konto, über das die Synchronisierung läuft; die bisher synchronisierten Dateien bleiben erhalten. Das Mitglied wird außerdem über die Glocke und per E-Mail benachrichtigt: bei einer abgelaufenen Verbindung sofort, sonst sobald die Synchronisierung eine Stunde lang fehlschlägt. Verbindet es das Konto erneut — der Dialog bietet das diesem Mitglied an —, läuft die Synchronisierung beim nächsten Durchlauf weiter. Jedes Mitglied, das Dokumente importieren darf, kann stattdessen einen neuen Synchronisierungsimport desselben Elements starten und die Synchronisierung über das eigene Konto übernehmen. Der Hinweis verschwindet mit dem nächsten erfolgreichen Durchlauf.

Über **Synchronisierung beenden** im Zeilenmenü bleiben die importierten Dateien erhalten, ohne weiter aktualisiert zu werden. Das Löschen des importierten Elements beendet die Synchronisierung ebenfalls. Die Originale in OneDrive oder Google Drive bleiben unberührt. **Google Drive trennen** im Importdialog widerruft die Verbindung; verbinde dich für weitere Importe erneut.

## Gelenktes Dokument überarbeiten

Nutze ein gelenktes Dokument, wenn die Freigabe mit genau der Datei verknüpft bleiben muss, die der Reviewer gesehen hat. Ersetzt du die Datei im Entwurf, aktualisiert Tale den bestehenden Datensatz; lädst du eine weitere Datei mit demselben Namen hoch, entsteht weiterhin ein separates Dokument.

<Steps>

<Step title="Gelenktes Dokument wählen">

Öffne bei einem normalen Upload das Zeilenmenü und klicke auf **Als gelenktes Dokument führen**. Der Datensatz steht danach auf `v1 · Entwurf`. Ein freigegebenes Dokument bietet **Datei ersetzen** und **Neue Revision**. Nutze **Neue Revision** nur, wenn du den nächsten Entwurf ohne Ersatzdatei brauchst.

</Step>

<Step title="Aktuelle Datei ersetzen">

Öffne das Zeilenmenü eines Entwurfs oder freigegebenen Dokuments und klicke auf **Datei ersetzen**. Wähle eine Datei im selben Format. Ein Entwurf behält seine Revision. Bei einem freigegebenen Dokument erhält Tale die freigegebene Version vN und öffnet Entwurf vN+1 erst, wenn das Ersetzen abgeschlossen ist; brichst du ab oder schlägt der Upload fehl, bleibt vN freigegeben. Ein Legal Hold blockiert beide Wege.

<Frame caption="Der Dialog nimmt genau eine Datei im vorhandenen Format des Datensatzes an.">

![Der Dialog „Datei ersetzen“ für ein gelenktes Textdokument mit einer Dateiauswahl für dasselbe Format und dem Hinweis, dass freigegebene Versionen im Verlauf bleiben.](https://docs.tale.dev/images/platform/controlled-document-replace-file.webp)

</Frame>

</Step>

<Step title="Revision prüfen und einreichen">

Öffne die Dokumentvorschau und prüfe, ob sie die Ersatzdatei zeigt. Öffne dann das Zeilenmenü und klicke auf **Zum Review einreichen**. Die Auswahl bietet nur Mitglieder an, die das Dokument auch öffnen können — eine Projekt-Datei verlangt Bearbeitungszugriff auf das Projekt — und nie dich selbst: Nur der Reviewer, den du benennst, kann freigeben oder Änderungen anfordern, jedes Review ist also ein zweites Augenpaar.

Der Entwurf bleibt während der Entscheidung für genau diese Datei gesperrt; der Reviewer wird über die Glocke und per E-Mail benachrichtigt, und die Entscheidung kommt auf demselben Weg zu dir zurück — eine Änderungsanforderung trägt das Feedback des Reviewers, das der Einreichen-Dialog vor deinem nächsten Anlauf ebenfalls zeigt.

Kann der Reviewer nicht mehr entscheiden — er hat die Organisation verlassen, wurde deaktiviert oder hat den Zugriff auf das Dokument verloren —, öffne das Zeilenmenü und klicke auf **Reviewer wechseln**: Die offene Anfrage geht an das Mitglied, das du benennst, und der Datensatz bleibt für dieselbe Datei gesperrt.

</Step>

</Steps>

## Vor dem Löschen die Inhalte prüfen

**Löschen** entfernt das Dokument und seinen indexierten Inhalt. Die Bestätigung erläutert die Folgen. Sichere eine Kopie, wenn du die Datei später brauchst. Ein erneuter Upload erzeugt ein neues Dokument.

<Warning>

Das Löschen eines Ordners entfernt seine Dateien und Unterordner endgültig. Bei einem synchronisierten Ordner werden auch Sync-Konfiguration und Verlauf entfernt. Die Originale in Microsoft 365 oder Google Drive bleiben unberührt.

</Warning>

Ein gelenktes Dokument mit einer freigegebenen Version ist vor dem Löschen geschützt, auch während der Vorbereitung eines späteren Entwurfs. Das Menü zeigt **Geschütztes gelenktes Dokument**. Ein Ordner mit einem solchen Dokument lässt sich ebenfalls nicht löschen. Auch ein Legal Hold kann Änderungen oder Löschungen sperren. Lass die konkrete Beschränkung von einem Administrator prüfen, statt sie durch doppelte Uploads zu umgehen.

# Wissenseinträge
Source: https://docs.tale.dev/de/platform/knowledge/knowledge-entries

Ein Wissenseintrag eignet sich für kurze Informationen, die dein Team später wiederfinden soll: Supportzeiten, Rückgabefristen oder die Zuständigkeit für einen Prozess. Jeder Eintrag besteht aus Thema und Inhalt. Für eine vollständige Richtlinie oder einen Bericht wähle ein [Dokument](https://docs.tale.dev/de/platform/knowledge/documents); für benannte Felder und genaue Werte nutze [strukturierte Daten](https://docs.tale.dev/de/platform/knowledge/structured-data).

Mitglieder können Einträge lesen. Zum Erstellen, Bearbeiten und Löschen brauchst du die Rolle Redakteur oder höher. Einträge gehören zum gemeinsamen Wissen der Organisation. Persönliche Notizen und Informationen, die nur für ein bestimmtes Projekt gedacht sind, gehören deshalb an einen anderen Ort.

## Eine Information hinzufügen

<Steps>

<Step title="Das Formular öffnen">

Gehe zu **Wissen > Wissenseinträge** und klicke auf **Eintrag hinzufügen**. Fehlt die Aktion, lass einen Administrator deine Rolle prüfen.

</Step>

<Step title="Ein dauerhaftes Thema wählen">

Trage unter **Thema** zum Beispiel `Reaktionszeit des Supports` ein. Wähle einen Namen, der auch nach einer inhaltlichen Änderung passt. Das Thema darf bis zu 120 Zeichen lang sein und muss eindeutig sein. Meldet Tale ein Duplikat, bearbeite den vorhandenen Eintrag.

</Step>

<Step title="Den nötigen Zusammenhang festhalten">

Schreibe unter **Inhalt** die Information, ihren Geltungsbereich und mögliche Bedingungen. Markdown wird unterstützt; bis zu 8.000 Zeichen sind möglich. Zum Beispiel:

```markdown
Der Support strebt eine erste Antwort innerhalb von 45 Minuten während
der Geschäftszeiten an: Montag–Freitag, 09:00–17:00 Uhr MEZ. Das ist ein
Antwortziel, keine Frist zur Problemlösung. Zuständig: Support Operations.
```

Vermeide relative Zeitangaben wie „nächsten Freitag“ und Verweise wie „die Richtlinie oben“. Der Eintrag muss auch für sich allein verständlich sein.

</Step>

<Step title="Speichern und die Indexierung prüfen">

Klicke auf **Speichern**. Der Eintrag erscheint mit Thema, Inhalt, Quelle (**Manuell** für das Formular, **Chat** für eine Information, die der Assistent festgehalten hat, **API** für eine, die eine Integration über REST geschrieben hat), Indexierungsstatus und Änderungszeit in der Tabelle. Öffne ihn, um den gesamten Inhalt zu lesen. Die Indexierung läuft im Hintergrund: Ein gespeicherter Eintrag ist nicht sofort für die Suche bereit.

</Step>

</Steps>

<Frame caption="Prüfe Information und Indexierungsstatus in der Tabelle, bevor du dich in einer Antwort darauf verlässt.">

![Die Tabelle der Wissenseinträge zeigt manuelle Informationen mit Thema, Inhalt, Quelle, Indexierungsstatus und Änderungszeit.](https://docs.tale.dev/images/platform/knowledge-entries-list.webp)

</Frame>

## Eine vorhandene Information korrigieren

Öffne das Zeilenmenü, wähle **Bearbeiten**, ändere den Inhalt und klicke auf **Speichern**. Damit entsteht eine neue aktuelle Fassung; ihr Text wird erneut zur Indexierung vorgemerkt. Pro Thema gibt es einen aktuellen Eintrag. Eine Korrektur am bestehenden Eintrag vermeidet widersprüchliche Antworten.

Öffne nach einer Korrektur die Details und den **Versionsverlauf**. Frühere Fassungen zeigen, was geändert wurde und wann sie ersetzt wurden; sie sind keine zusätzlichen aktuellen Informationen. Bei einem Eintrag, der nie bearbeitet wurde, steht dort, dass es noch keine früheren Versionen gibt. Die **Versions-ID** in den Details gehört zur aktuellen Fassung und ändert sich bei jeder Bearbeitung; das Thema kennzeichnet den Eintrag über alle Versionen hinweg. Anwendungen können Einträge auch über die [REST-API](https://docs.tale.dev/de/develop/api-reference) erstellen und ändern.

<Tip>

Wenn ein Chat eine nützliche Information liefert, prüfe sie anhand der Quelle. Erstelle oder bearbeite den Eintrag anschließend selbst. Chat speichert Informationen nicht automatisch in der Wissensbasis der Organisation.

</Tip>

## Einen veralteten Eintrag entfernen

Wähle **Löschen** im Zeilenmenü und lies die Bestätigung. Dadurch verschwinden der Eintrag und seine früheren Fassungen aus dieser Ansicht; das zugehörige Dokument steht der Wissenssuche nicht mehr zur Verfügung. Sichere den Text vorher, falls du ihn noch brauchst. Für eine Korrektur ist **Bearbeiten** der passende Weg.

## Wenn die Information in einer Antwort fehlt

Prüfe zuerst den aktuellen Eintrag: Ist er gespeichert und fertig indexiert? Benennt die Frage das Thema eindeutig? Ist die Indexierung fehlgeschlagen, behebe die angegebene Ursache und starte sie über die Wiederholungsaktion erneut. Bei anhaltenden Fehlern muss ein Administrator die Embedding-Konfiguration und die Indexierungsdienste prüfen.

Bitte den Assistenten um einen Quellenbeleg, öffne die Quelle und vergleiche sie mit dem Eintrag. Eine plausibel klingende Antwort beweist noch nicht, dass die aktuelle Information verwendet wurde. Die gemeinsamen Indexierungszustände erklärt [Dokumente](https://docs.tale.dev/de/platform/knowledge/documents).

## Wenn die Liste oder der Verlauf nicht lädt

Schlägt das Laden fehl, meldet Tale das dort, wo die Inhalte stehen würden. Ein Fehler erscheint nie als leere Bibliothek oder als Eintrag ohne Verlauf. **Erneut versuchen** wiederholt den Abruf, ohne dass du die Seite neu laden musst:

- Lässt sich kein Eintrag laden, zeigt die Tabelle statt des leeren Zustands den Fehler mit **Erneut versuchen**.
- Sind bereits Einträge zu sehen, bleiben sie stehen, und ein Hinweis über der Tabelle sagt, dass die Liste unvollständig oder veraltet sein kann. Deine Suche und die ausgewählten Zeilen bleiben beim erneuten Versuch erhalten. Konnten weitere Einträge nicht geladen werden, steht das unter der Tabelle, und eine Suche umfasst nur die geladenen Einträge.
- Lässt sich in den Details eines Eintrags der **Versionsverlauf** nicht laden, sagt der Abschnitt das und bietet **Erneut versuchen** an. Der aktuelle Inhalt bleibt lesbar.

Scheitert **Erneut versuchen** immer wieder, bitte einen Administrator zu prüfen, ob die Dienste von Tale laufen.

# Wissen
Source: https://docs.tale.dev/de/platform/knowledge/overview

Wissen ist die gemeinsame Bibliothek deiner Organisation. Dokumente, kurze Informationen, öffentliche Websites, Kontakte und Produkte geben Menschen und Agenten dieselbe Arbeitsgrundlage. Beginne mit den Quellen für eine konkrete Frage. Eine kleine, gepflegte Sammlung ist leichter zu beurteilen als ein ungeprüftes Archiv.

<Video src="https://docs.tale.dev/videos/de/tutorials/ep3-knowledge/ep3-knowledge.de.mp4" poster="https://docs.tale.dev/videos/de/tutorials/ep3-knowledge/ep3-knowledge.de.webp" captions="https://docs.tale.dev/videos/de/tutorials/ep3-knowledge/ep3-knowledge.de.vtt" lang="de" title="Episode 3 — Wissen" caption="Episode 3 — Wissen (3:22)">

</Video>

<Frame caption="Für Dateien beginne unter Dokumente. Für andere Quellen öffne die passende Seite. Die Ansicht ist auf hochgeladene, indexierte Dateien gefiltert.">

![Der Bereich Wissen zeigt die Tabs Dokumente, Wissenseinträge, Websites, Produkte und Kontakte über einer Tabelle gemeinsamer Dateien.](https://docs.tale.dev/images/get-started/documents-list.webp)

</Frame>

## Den passenden Ort wählen

| Du hast | Nutze | Warum |
| --- | --- | --- |
| Eine Richtlinie, Anleitung, Tabelle oder einen Bericht | **Dokumente** | Die Originaldatei bleibt erhalten; aus unterstützten Formaten lassen sich Textstellen abrufen. |
| Eine kurze Information, etwa Supportzeiten | **Wissenseinträge** | Ein dauerhaftes Thema hält eine aktuelle Antwort zusammen. |
| Öffentliche Seiten, die sich regelmäßig ändern | **Websites** | Eine ganze Website oder eine ausgewählte URL-Liste wird nach Zeitplan eingelesen. |
| Personen, Organisationen und ihre Kontaktdaten | **Kontakte** | Namen und weitere Felder bleiben strukturierte Datensätze. |
| Artikel mit Produktangaben | **Produkte** | Die Felder lassen sich gezielt nachschlagen. |
| Referenzdateien für ein bestimmtes Vorhaben | **Wissen** im Projekt | Die Dateien bleiben im Zugriff und Chat-Kontext dieses Projekts. |

Mitglieder können Inhalte innerhalb ihrer Zugriffsrechte lesen. Redakteure und höhere Rollen pflegen die gemeinsame Bibliothek. Öffne eine Zeile oder wähle **Anzeigen** in ihrem Zeilenmenü, um ihre Details zu sehen. Darfst du eine Quelle ändern, findest du im selben Menü die passenden Aktionen wie **Löschen**; Kontakte, Produkte, Websites und Wissenseinträge bieten dort und in ihren Details auch **Bearbeiten**. Der Leitfaden zu [strukturierten Daten](https://docs.tale.dev/de/platform/knowledge/structured-data) hilft, wenn eine Tabelle sowohl Quelldokument als auch Sammlung einzelner Datensätze sein könnte.

## Eine Quelle für Antworten nutzbar machen

Hochladen oder Speichern ist der erste Schritt. Dokumente, Einträge und Webseiten müssen außerdem **indexiert** werden: Tale liest ihren Text aus und bereitet ihn für die Suche vor. Prüfe den Status, bevor du nach neuen Inhalten fragst. Eine Datei kann herunterladbar bleiben, obwohl ihr Format keine Indexierung erlaubt.

Wähle einen eindeutigen Titel und nenne im Inhalt Datum und Geltungsbereich. Korrigiere oder entferne veraltete Vorgaben. Widersprechen sich Quellen, benenne die maßgebliche Fassung und prüfe den Quellenbeleg der Antwort. Zusätzliche Dateien lösen den Widerspruch nicht auf.

<Tip>

Prüfe eine neue Quelle mit einer Frage, deren Antwort du kennst: „Wann ist unser Support erreichbar? Nenne die Quelle.“ Öffne die zitierte Quelle und vergleiche die Antwort. So lässt sich der Nutzen gezielter prüfen als mit einer allgemeinen Zusammenfassung der gesamten Bibliothek.

</Tip>

## Zugriff und Suche verstehen

Im Organisationschat kann der Assistent die gemeinsame Bibliothek innerhalb deiner Berechtigungen durchsuchen. Im Projektchat kommen die Dateien und gespeicherten Anweisungen dieses Projekts hinzu. Dateien anderer Projekte gehören nicht dazu. Projektagenten brauchen die passenden Plattform-Tools in ihrer Ausstattung.

Team-Beschränkungen gelten auch bei der Suche. Eine Datei, die du in einem Arbeitsbereich siehst, kann deshalb im Kontext eines anderen Projekts fehlen. Nutze [Projektdateien](https://docs.tale.dev/de/platform/projects/manage-files) für projektspezifische Inhalte und die Team-Zuordnung von Dokumenten für die gemeinsame Bibliothek.

Scheitern alle Suchanfragen, lass einen Administrator das Embedding-Modell und die Wissensverbindung unter **Einstellungen > Datenresidenz** prüfen. Einzelheiten für Betreiber stehen unter [Datenresidenz](https://docs.tale.dev/de/self-hosted/configuration/data-residency).

## Die Quellen pflegen

<CardGroup cols="2">

<Card title="Dokumente" icon="file-text" href="https://docs.tale.dev/de/platform/knowledge/documents">
Dateien hochladen und importieren, Indexierung prüfen und freigegebene Revisionen verwalten.
</Card>

<Card title="Wissenseinträge" icon="book-open" href="https://docs.tale.dev/de/platform/knowledge/knowledge-entries">
Eine kurze Information festhalten, korrigieren und ihren Versionsverlauf lesen.
</Card>

<Card title="Websites" icon="globe" href="https://docs.tale.dev/de/platform/knowledge/crawling">
Seiten auswählen, das Intervall festlegen und fehlende Inhalte untersuchen.
</Card>

<Card title="Strukturierte Daten" icon="table" href="https://docs.tale.dev/de/platform/knowledge/structured-data">
Datensätze für genaue Felder und Dokumente für ergänzende Erklärungen wählen.
</Card>

</CardGroup>

# Dokumente oder strukturierte Datensätze wählen
Source: https://docs.tale.dev/de/platform/knowledge/structured-data

Nutze Dokumente für Inhalte, die eine Erklärung in ganzen Absätzen brauchen, etwa Verträge oder Gesprächsnotizen. Strukturierte Datensätze eignen sich für Angaben mit festen Feldern, etwa die E-Mail-Adresse eines Kontakts oder eine Produktkennung. Meist brauchst du beides: Der Datensatz hält die Stammdaten fest, die Dokumente liefern die Zusammenhänge.

## Den passenden Ort wählen

| Information | Ablage | Grund |
| --- | --- | --- |
| Richtlinie, Vertrag, Handbuch oder Gesprächsnotiz | **Dokumente** | Tale durchsucht den Text und ruft passende Abschnitte ab. |
| Kurze Information mit eigenem Änderungsverlauf | **Wissenseinträge** | Pro Thema gilt eine aktuelle Version; frühere Versionen bleiben erhalten. |
| Person oder Organisation, mit der du arbeitest | **Kontakte** | Feste Felder bündeln die Angaben in einem bearbeitbaren Datensatz. |
| Produkt und seine Eigenschaften | **Produkte** | Produktangaben stehen in Feldern und verschwinden nicht im Fließtext. |
| Seiten einer öffentlichen Website | **Websites** | Tale erfasst die Seiten und aktualisiert die durchsuchbaren Inhalte regelmäßig. |
| Referenzdateien für ein einzelnes Projekt | **Wissen** im Projekt | Der Projektzugriff bestimmt die Sichtbarkeit; Projektchats können die Dateien abrufen. |

Die Ablage bestimmt, wie Tale Informationen abruft. Ein gefundener Dokumentabschnitt bedeutet nicht, dass die gesamte Datei geprüft wurde. Beim Lesen eines Datensatzes erhält Tale dessen Feldwerte. Ob diese noch aktuell sind und die daraus abgeleitete Antwort stimmt, musst du weiterhin prüfen.

## Datensätze mit Dokumenten ergänzen

Du bereitest zum Beispiel ein Gespräch mit Acme vor. Pflege die Kontaktdaten unter **Kontakte** und lege Vertrag und Gesprächsnotizen unter **Dokumente** oder im Bereich **Wissen** des zugehörigen Projekts ab.

Bitte den Chat-Assistenten, den Kontakt zu Acme zu finden und die offenen Fragen aus den letzten Notizen zusammenzufassen. Prüfe die E-Mail-Adresse im Datensatz und die Entscheidungen in den zitierten Notizen. Liegen die Dateien in einem Projekt, starte auch den Chat dort.

<Tip>

Verwende in Datensätzen und zugehörigen Dateien denselben eindeutigen Firmen- oder Produktnamen. Ergänze Gesprächsnotizen um ein Datum und Richtlinien um eine Revisionskennung, damit aktuelle und ältere Quellen erkennbar bleiben.

</Tip>

## Einen Kontakt anlegen

Zum Pflegen der Organisationsdatensätze brauchst du die Rolle Redakteur oder höher. Öffne **Wissen > Kontakte**, wähle **Kontakt hinzufügen** und anschließend **Manuelle Eingabe**.

1. Trage die **E-Mail**-Adresse des Kontakts ein. Ergänze bei Bedarf **Name** und **Telefon**.
2. Prüfe **Sprache**. Das Feld ist mit `en` vorbelegt; passe es an die Sprache des Kontakts an.
3. Wähle **Speichern**. Der Kontakt erscheint mit seinen Angaben und dem Erstellungsdatum in der Tabelle.

Vor dem Speichern prüft das Formular jedes Feld gegen das, was Tale speichert: **Name** bis 300 Zeichen, **Telefon** bis 50, **Sprache** bis 20 und bei der **E-Mail** höchstens 64 Zeichen vor dem `@`. Ein Wert über einer Grenze wird unter seinem Feld genannt, und gespeichert wird erst, wenn du ihn korrigiert hast.

Um nur die Kontakte einer Sprache zu sehen, wähle über der Kontaktliste **Filter** und unter **Sprache** die gewünschte Sprache. Eine Sprache schließt ihre regionalen Varianten ein: **FR** zeigt Kontakte mit der Sprache `fr`, `fr-CH` oder `fr_CA`. Ein Kontakt ohne Sprache erscheint nur, solange keine Sprache gewählt ist.

Du kannst einen Kontakt auch beim Schreiben anlegen. Wähle im Bereich **Start** in der Ansicht **Inbox** die Schaltfläche **Neue E-Mail** und tippe eine Adresse in **An**: Trägt sie kein Kontakt, bietet die Liste **„…“ als Kontakt hinzufügen** an und öffnet dasselbe Formular mit bereits ausgefüllter **E-Mail**. Nach dem Speichern ist dieser Kontakt der Empfänger – du verlässt die begonnene Nachricht also nie.

Ist die E-Mail-Adresse bereits vorhanden, suche den bestehenden Kontakt und bearbeite ihn über sein Zeilenmenü; aus **Neue E-Mail** heraus wählt Tale den vorhandenen Kontakt für dich aus. Beim Speichern wird nur der Datensatz angelegt; Tale sendet dem Kontakt dabei keine E-Mail.

Kontakte, die dein Team hier erfasst oder importiert hat, bearbeitest oder löschst du einzeln über das Zeilenmenü. Um mehrere auf einmal zu löschen, setze bei ihren Zeilen das Häkchen und wähle **Ausgewählte löschen**. Kontakte aus einer Integration, der API oder einer Konversation gehören ihrer Quelle, die eine Änderung hier überschreiben würde. Deshalb bietet ihr Zeilenmenü weder **Bearbeiten** noch **Löschen**, und ihre Zeilen haben kein Kästchen.

## Ein Produkt anlegen

<Frame caption="Wissen > Produkte: Jedes Produkt ist ein Datensatz mit benannten Feldern für Bestand, Preis, Kategorie und Status.">

![Der Tab Produkte im Bereich Wissen listet drei Produkte: Team training workshop mit 12 Stück Bestand für 950,00 US-Dollar in Services, als Entwurf markiert, sowie Onboarding accelerator für 1.900,00 US-Dollar in Services und Analytics Pro — annual license für 1.188,00 US-Dollar in Licenses, beide aktiv.](https://docs.tale.dev/images/platform/knowledge-products-list.webp)

</Frame>

Öffne **Wissen > Produkte**, wähle **Produkt hinzufügen** und anschließend **Manuelle Eingabe**. Das Formular führt dich durch drei Schritte.

1. Gib im Schritt **Grundlagen** unter **Produktname** einen Namen ein. Ergänze bei Bedarf eine Beschreibung und ein Bild, damit das Produkt eindeutig erkennbar ist. Wähle **Weiter**.
2. Prüfe unter **Preis & Bestand** immer **Preis** und **Währung** zusammen. Trage beispielsweise `12.50` ein und wähle `CHF`. Eine andere Währung rechnet den Betrag nicht um. Ergänze bei Bedarf Bestand und Kategorie und prüfe den **Status**. Ein neues Produkt beginnt als **Entwurf**.
3. Prüfe unter **Überprüfen** die Angaben und wähle **Erstellen**. Die Tabelle zeigt das Produkt mit Preis, Status und Änderungsdatum.

Gespeicherte Produkte bearbeitest du über das Zeilenmenü. Verwende unterscheidbare Produktnamen und kontrolliere Preis und Währung, bevor du den Status änderst.

Wähle **Bild hochladen** oder ziehe eine PNG-, JPEG-, WebP-, GIF- oder SVG-Datei in den Bildbereich. Die Obergrenze liegt bei 5 MiB. Warte auf die Vorschau, bevor du fortfährst. Tale prüft die hochgeladenen Dateiinhalte; lehnt es die Datei ab, nennt die Meldung unter dem Bildfeld den Grund — ein nicht unterstütztes Format, eine Datei über der Obergrenze oder eine SVG-Datei mit Skripten oder Event-Handlern —, damit du weißt, ob eine andere Datei nötig ist.

Das hochgeladene Bild bleibt nach dem Speichern und Neuladen des Produkts verfügbar. Sobald das Produkt gespeichert ist, können andere Organisationsmitglieder mit Produktzugriff das Bild sehen. Die Bildadresse setzt eine angemeldete Sitzung voraus und eignet sich nicht als öffentlicher Freigabelink. Zum Entfernen bearbeitest du das Produkt, wählst **Bild entfernen** und speicherst die Änderung. Wird das Bild entfernt oder ersetzt oder das Produkt gelöscht, wird auch die hochgeladene Datei selbst entfernt, sofern kein anderes Produkt sie noch zeigt.

Wenn du **Oder URL einfügen** wählst, gib eine vollständige öffentliche HTTPS-Adresse ein, die mit `https://` beginnt. Eine unvollständige Adresse nennt das Formular unter dem Feld, bevor du weitergehen kannst. Tale weist unsichere oder nicht zugelassene Hosts ab. Frage einen Administrator, wenn du eine interne Bildquelle brauchst. Für Bilder von externen Adressen gelten die Zugriffsregeln der jeweiligen Quelle.

## Zugriff und Aktualität prüfen

Ein Datensatz oder Dokument hilft nur Personen, die darauf zugreifen dürfen. Prüfe die Team-Zuordnung, wenn jemand einen Eintrag nicht findet. Bei Projektdateien gilt der Projektzugriff statt der Team-Zuordnung der Dokumentbibliothek; siehe [Projektdateien](https://docs.tale.dev/de/platform/projects/manage-files).

Ändert sich eine Angabe, aktualisiere den maßgeblichen Datensatz. Warte nach einer Dokumentänderung auf die abgeschlossene Indexierung, bevor du eine Frage zum neuen Inhalt testest. Website-Inhalte folgen dem eingestellten Scan-Intervall und können deshalb hinter der Live-Seite zurückliegen.

## Mit den vorhandenen Datentypen arbeiten

Der Wissensbereich bietet Kontakte, Produkte und Websites. **Einstellungen > Richtlinien > Modelle** steuert den Zugriff auf KI-Modelle und deren Vorauswahl. Dort legst du keine eigenen Datentypen oder Datenbankfelder an.

Passen die vorhandenen Felder nicht zu deinem Inhalt, halte die Details in einem Dokument fest und ordne den Ablauf dem passenden Datensatz zu. Welche Felder sich programmatisch importieren lassen, steht in der [API-Referenz](https://docs.tale.dev/de/develop/api-reference).

Unter [Dokumente](https://docs.tale.dev/de/platform/knowledge/documents) erfährst du, wie du eine Datei hochlädst und prüfst. [Wissenseinträge](https://docs.tale.dev/de/platform/knowledge/knowledge-entries) erklärt die Pflege einzelner Informationen; [Crawling](https://docs.tale.dev/de/platform/knowledge/crawling) beschreibt die regelmäßige Erfassung öffentlicher Seiten.

# Tale als App installieren
Source: https://docs.tale.dev/de/platform/member/install-as-app

Installiere Tale, wenn du ein eigenes Startsymbol und ein separates App-Fenster möchtest. Verwende dieselbe Tale-Adresse und dasselbe Konto wie im Browser. Die Installation erstellt weder eine weitere Organisation noch eine Kopie deiner Chats in einem neuen Konto.

## Auf einem Computer oder Android installieren

Öffne deine Tale-Instanz in einem unterstützten Browser. Öffne über deinen Namen oder Avatar das Kontomenü und wähle **App installieren**. Bestätige anschließend die Browserabfrage. Tale zeigt diese Aktion, sobald der Browser die Installation anbietet.

Fehlt die Aktion, prüfe das Browsermenü. Chrome bietet auf dem Desktop unter **Streamen, speichern und teilen** die Installation einer Seite als App an. Die Bezeichnungen hängen von Browser und Gerät ab. Die [Chrome-Hilfe zu Web-Apps](https://support.google.com/chrome/answer/9658361?hl=de) erklärt Installation und Verwaltung.

Öffne das neue Symbol und prüfe, ob du die richtige Tale-Instanz erreichst. Melde dich bei Bedarf an und kontrolliere die Organisation im Kontomenü. Browserprofile und installierte Apps können unterschiedliche Anmeldungen verwenden.

## Auf iPhone oder iPad installieren

Unter iOS öffnet **App installieren** im Tale-Kontomenü eine Anleitung. Die eigentliche Installation übernimmt der Browser.

Öffne Tale in Safari, wähle **Teilen > Zum Home-Bildschirm** und bestätige **Hinzufügen**. Wird **Als Web-App öffnen** angeboten, lass die Option für ein separates Fenster aktiviert. Die aktuellen Bedienelemente beschreibt [Apples iPhone-Anleitung](https://support.apple.com/guide/iphone/open-as-web-app-iphea86e5236/ios).

Auch andere iOS-Browser können **Zum Home-Bildschirm** anbieten. Fehlt die Option, öffne dieselbe Adresse in Safari. Nach der Installation können App und Browser getrennte Cookies verwenden. Eine Abmeldung in einem Fenster meldet dich deshalb nicht unbedingt im anderen ab. [WebKit beschreibt dieses Verhalten](https://webkit.org/blog/14787/webkit-features-in-safari-17-2/).

## Was sich durch die Installation ändert

Organisation, Berechtigungen und gespeicherte Inhalte bleiben auf der Tale-Instanz. Die Installation ändert den Start und die Darstellung. Sie installiert kein lokales Modell und macht serverabhängige Aufgaben nicht ohne Verbindung verfügbar.

Benachrichtigungen hängen weiterhin von Browser, Betriebssystem, erteilter Berechtigung und deinen Tale-Einstellungen ab. Eine Installation erteilt noch keine Benachrichtigungsberechtigung. Prüfe diese nach einem Gerätewechsel oder einer Neuinstallation erneut.

## Die installierte App entfernen

Verwende **Deinstallieren** oder **App löschen** im Browser beziehungsweise Betriebssystem. Ein Symbol aus dem macOS-Dock zu entfernen, löscht nur die Verknüpfung. In Chrome nutzt du das Menü der installierten App oder `chrome://apps`. Das Löschen ihrer Browserdaten kann dich zusätzlich abmelden.

Eine Deinstallation löscht weder dein Tale-Konto noch die Organisation oder serverseitig gespeicherte Dokumente. Kontoänderungen beschreibt [Profil und Konto](https://docs.tale.dev/de/platform/member/preferences). Melde dich auf einem gemeinsam genutzten Gerät sowohl in der App als auch in verwendeten Browserfenstern ab.

## Wenn die Installation fehlt

| Beobachtung | Nächster Schritt |
| --- | --- |
| Keine Aktion **App installieren** | Prüfe das Installationsmenü des Browsers und ob die App bereits installiert ist. |
| Keine Option in einem privaten oder verwalteten Browser | Nutze ein normales Fenster oder frage die Geräteverwaltung nach der Installationsrichtlinie. |
| Das Symbol öffnet die falsche Instanz | Prüfe die Adresse im ursprünglichen Browser und installiere die gewünschte Instanz. |
| Die App öffnet sich, lädt aber keine Inhalte | Prüfe Netzwerkzugriff und Erreichbarkeit der Tale-Instanz. |

# Mitglied
Source: https://docs.tale.dev/de/platform/member/overview

Als Mitglied stellst du Fragen im Chat und liest die Wissens- und Projektinhalte, die für dich freigegeben sind. Einrichtung und Team-Mitgliedschaften bestimmen, welche Ressourcen du siehst. Außerdem kannst du Projektaufgaben erstellen und Projektagenten daran arbeiten lassen, deine Kontoeinstellungen pflegen und wiederverwendbare Skills erstellen.

## In den Tag starten

<CardGroup cols="2">

<Card title="Eine hilfreiche Frage stellen" icon="message-circle" href="https://docs.tale.dev/de/tutorials/member/chat-effectively">

Übe mit einer Quelle, prüfe die Fakten und frage gezielt nach.

</Card>

<Card title="Gemeinsames Wissen lesen" icon="library" href="https://docs.tale.dev/de/platform/knowledge/overview">

Finde Dokumente, Informationen und Datensätze und verstehe fehlenden Zugriff.

</Card>

<Card title="Projekte verstehen" icon="folder-open" href="https://docs.tale.dev/de/platform/projects/concepts">

Erfahre, welche Dateien und Gespräche zu einem Projekt gehören und welche Chats persönlich bleiben.

</Card>

<Card title="Dein Konto verwalten" icon="user" href="https://docs.tale.dev/de/platform/member/preferences">

Bearbeite dein Profil, prüfe deine Nutzungslimits und verstehe gespeicherte Einstellungen und Chat-Verwaltung.

</Card>

</CardGroup>

Wechsle über die [Hauptnavigation](https://docs.tale.dev/de/platform#navigation) zwischen deinen Tätigkeiten. Jeder Bereich öffnet seine eigene erste Seite; am Computer öffnet **Start** stattdessen den Chat, den du zuletzt gelesen hast, und wählst du **Start** erneut, beginnt ein neuer Chat. [Start](https://docs.tale.dev/de/platform#home) zeigt außerdem deine Projekte, die offenen Aufgaben, die dir zugewiesen sind oder auf dein Review warten, und die Inbox, sofern deine Organisation eine hat.

## Arbeit an einen Projektagenten übergeben

Brauchst du ein Arbeitsergebnis, etwa eine Zusammenfassung mehrerer Verträge oder ein übersetztes Dokument, öffne ein Projekt, auf das du zugreifen kannst, und erstelle im Tab **Aufgaben** eine Aufgabe. Beschreibe das Ergebnis und woran du es prüfen wirst, hänge die nötigen Dateien an und weise die Aufgabe einem der Agenten des Projekts zu. Mit **Agent starten** legt er los: Er berichtet in den Kommentaren der Aufgabe und setzt sie auf **In Prüfung**. Lies den Bericht, öffne die Ergebnisse und setze die Aufgabe auf **Erledigt**, wenn du das Ergebnis annimmst.

Ändern kannst du die Aufgaben, die du erstellt hast oder die dir zugewiesen sind. Aufgaben anderer kannst du lesen und kommentieren. Die Agenten selbst sowie die Einstellungen und Dateien des Projekts verwalten Redakteure. [Aufgaben auf dem Projektboard verwalten](https://docs.tale.dev/de/platform/projects/tasks#wer-aufgaben-erstellen-und-aendern-darf) und [Eine Aufgabe an einen Agenten delegieren](https://docs.tale.dev/de/platform/projects/task-automation) gehen ins Detail.

## Einer Benachrichtigung folgen

Ein Benachrichtigungslink öffnet die zugehörige Aufgabe, das Dokument oder die Konversation. Musst du dich zuerst anmelden, merkt sich Tale das Ziel und öffnet es nach der Anmeldung. Du brauchst weiterhin Zugriff auf die Organisation und den verlinkten Inhalt. Verbinde dich bei einer privaten Bereitstellung zuerst mit dem dafür vorgesehenen Netzwerk.

## Wenn eine Aktion fehlt

Mitglieder lesen die gemeinsame Bibliothek; Redakteure und höhere Rollen pflegen ihre Inhalte. In einem Projekt änderst du die Aufgaben, die du erstellt hast oder die dir zugewiesen sind; Einstellungen, Agenten und Dateien des Projekts bleiben bei den Redakteuren. Automatisierungen und technische Einrichtung brauchen Entwickler- oder Administratorrechte; Mitglieder und Redakteure sehen **Automatisierungen** deshalb gar nicht. Lass dir den nötigen Zugriff für deine Aufgabe geben. Eine sichtbare Ressource ist nicht automatisch bearbeitbar. [Mitglieder und Rollen](https://docs.tale.dev/de/platform/admin/members-and-roles) erklärt die Unterschiede.

# Konto und persönliche Einstellungen verwalten
Source: https://docs.tale.dev/de/platform/member/preferences

Die Kontoeinstellungen bestimmen, welchen Namen deine Kollegen sehen und wie du dich anmeldest. Im Profilmenü wechselst du außerdem Organisation und Sprache und siehst, zu welchen Teams du gehörst. Dafür brauchst du keine Admin-Rolle.

## Den sichtbaren Namen ändern

Öffne **Einstellungen > Konto**. Ändere unter **Profil** das Feld **Name** und klicke oben auf **Speichern**. Mit **Verwerfen** stellst du den gespeicherten Wert wieder her. Die E-Mail-Adresse ist schreibgeschützt, weil sie dein Konto bei der Anmeldung und für Benachrichtigungen identifiziert.

Dein Name ist für Kollegen sichtbar und darf höchstens 100 Zeichen lang sein. Er ist keine persönliche Anweisung an den Assistenten.

## Die Anmeldung absichern

Unter **Passwort** findest du **Passwort ändern** oder **Passwort festlegen**, falls dein Konto noch keines hat. Beachte die Anforderungen im Dialog. Sie stammen aus der Passwort-Richtlinie deiner Organisation. Gehörst du mehreren Organisationen an, muss dein Passwort die Anforderungen aller dieser Organisationen erfüllen. Eine Passwortänderung beendet deine Sitzungen. Halte das neue Passwort deshalb bereit, bevor du bestätigst. Ein falsches aktuelles Passwort zählt wie eine fehlgeschlagene Anmeldung zur vorübergehenden Sperre.

Richte unter **Zwei-Faktor-Authentifizierung** eine Authenticator-App ein oder ergänze unter **Passkeys** einen Passkey. Bewahre Wiederherstellungscodes an einem Ort auf, den du ohne Tale-Anmeldung erreichst. [Zwei-Faktor-Authentifizierung](https://docs.tale.dev/de/platform/admin/two-factor-authentication) erklärt Einrichtung, Wiederherstellung und Organisationsvorgaben.

## Sprache oder Arbeitsbereich wechseln

Öffne das Profilmenü über deinen Avatar. Unter **Sprache** änderst du die Oberflächensprache. Bist du in mehreren Organisationen, wechselst du mit **Organisation** den Arbeitsbereich. Die Zeile **Teams** nennt deine Teams und öffnet die Kontoseite; sie wechselt nichts, denn ein Team ist kein Arbeitsbereich.

Prüfe den Organisationsnamen, bevor du Einstellungen änderst oder Inhalte hinzufügst.

## Deine Rolle sehen {#role}

Unter **Einstellungen > Konto > Deine Rolle** steht deine Rolle in dieser Organisation, zum Beispiel Redakteur oder Mitglied. Die Rolle bestimmt, was du tun darfst; deine Teams bestimmen, welche Team-Inhalte du siehst. Admins vergeben Rollen unter [Mitglieder und Rollen](https://docs.tale.dev/de/platform/admin/members-and-roles). Mit Single Sign-On kann auch dein Identity-Provider deine Rolle bei jeder Anmeldung festlegen. Inhaber und Admins sehen neben dem Titel des Abschnitts die Schaltfläche **Mitglieder verwalten**.

## Deine Teams sehen {#teams}

Unter **Einstellungen > Konto > Deine Teams** stehen die Teams, zu denen du gehörst. Teams bestimmen, welche Team-Dokumente, Projekte und Posteingangs-Warteschlangen du siehst; was mit der ganzen Organisation geteilt ist, siehst du in jedem Fall. Bist du in keinem Team, sagt der Abschnitt das. Können deine Teams nicht geladen werden, sagt der Abschnitt das, statt zu behaupten, du seist in keinem Team. Wähle **Erneut versuchen**, um sie zu laden. Schlägt eine Aktualisierung fehl, bleiben die angezeigten Teams stehen, und ein Hinweis sagt, dass sie womöglich veraltet sind.

Um eine Liste auf bestimmte Arbeit einzugrenzen, nutze ihren Filter **Teams**: **Organisationsweit** zeigt nur Einträge ohne Team, **Meine Teams** zeigt Einträge, die eines deiner Teams sehen darf, und jedes Team steht mit Namen zur Wahl. Der Posteingang bietet hinter seinem Suchfeld den Filter **Zuständig**, der Personen und Teams gemeinsam aufführt. Ein Filter ändert die Ansicht, erweitert aber nicht deinen Zugriff auf Daten anderer Teams.

Inhaber und Admins verwalten die Mitgliedschaften unter [Teams](https://docs.tale.dev/de/platform/admin/teams); die Schaltfläche **Teams verwalten** im Abschnitt führt sie dorthin.

## Benutzerdefinierte Anweisungen für den Chat-Assistenten festlegen

Öffne **Einstellungen > Personalisierung**. **Benutzerdefinierte Anweisungen** sind feste Anweisungen, die der Chat-Assistent in jeder Antwort an dich befolgt, etwa ein bevorzugter Ton, eine Standard-Programmiersprache oder wie ausführlich du Antworten möchtest. Der Schalter kann dem Organisationsstandard folgen oder deine eigene Wahl speichern; der Hinweis darunter sagt, was gerade gilt. Das Textfeld erscheint, solange die Funktion aktiv ist. Gib deine Anweisungen ein und klicke in der Kopfzeile auf **Speichern**.

<Frame caption="Die Personalisierung enthält deine benutzerdefinierten Anweisungen und den Schalter, der sie aktiviert.">

![Die Seite Personalisierung zeigt den Schalter für benutzerdefinierte Anweisungen und das zugehörige Textfeld.](https://docs.tale.dev/images/platform/settings-preferences.webp)

</Frame>

<Note>

Deine Anweisungen überschreiben weder die verbindlichen Anweisungen der Organisation noch **Allgemein > Anweisungen** eines Projekts; bei einem Widerspruch haben diese Vorrang. Schaltest du die Funktion aus, bleibt der Text für später erhalten, ohne angewendet zu werden.

</Note>

## Nutzungslimits prüfen {#usage-limits}

Unter **Einstellungen > Nutzung** siehst du, wie viel du von den Limits verbraucht hast, die deine Organisation für dich festlegt. Gilt kein Limit für dich, zeigt die Seite das an.

<Frame caption="Unter Einstellungen > Nutzung steht jedes Limit, das für dich gilt, mit Verbrauch und nächstem Zurücksetzen.">

![Die Seite Nutzung zeigt persönliche Monatslimits für Token, Kosten und Anfragen und die geteilten Monatslimits der Organisation, jeweils mit Verbrauchsbalken und Datum des Zurücksetzens. Darunter steht der belegte Speicherplatz im Vergleich zum Limit pro Person. Admins sehen zusätzlich die Schaltfläche Limits verwalten.](https://docs.tale.dev/images/platform/settings-usage.webp)

</Frame>

- **Deine Limits** zählen deine eigenen Chats, Sprachausgaben und Agenten-Läufe, egal auf welchem Weg du sie gestartet hast; [So wird die Nutzung gezählt](https://docs.tale.dev/de/platform/admin/governance/usage-attribution) erklärt, wem ein Lauf angerechnet wird. Ist eines erreicht, kannst du bis zum Zurücksetzen nichts davon neu starten: Eine Nachricht, die du dann sendest, wird mit einem Hinweis auf das Limit abgelehnt und bleibt im Eingabefeld.
- **Geteilte Limits** zählen die Nutzung aller, für die sie gelten, etwa eines Teams, zu dem du gehörst, oder der gesamten Organisation. Sie können deshalb vor deinen eigenen Limits erreicht sein.
- **Speicherplatz** vergleicht die Dateien, die du hochgeladen hast, mit deinem Speicherlimit. Ist es erreicht, werden neue Dokument-Uploads abgelehnt.

Jedes Nutzungslimit zeigt den Verbrauch, das Limit und den Zeitpunkt des Zurücksetzens in deiner Ortszeit. Die Zeiträume richten sich nach UTC: Tageslimits beginnen um Mitternacht neu, Wochenlimits am Montag und Monatslimits am Ersten des Monats. Hat ein Admin eine Warnschwelle festgelegt, färbt sich der Balken orange, sobald deine Nutzung sie erreicht. Warnt ein Banner über dem Eingabefeld vor einem Limit, öffnet **Nutzung anzeigen** diese Seite. Admins sehen zusätzlich **Limits verwalten**, das **Richtlinien > Richtlinien & Limits** öffnet.

## Alte Chats archivieren oder abmelden

Unter **Einstellungen > Konto > Deine Chats** findest du **Alle Chats archivieren** und **Alle Chats löschen** für deine eigenen Chats in der aktuellen Organisation, einschließlich Projekt-Chats. Archiviert werden nur noch nicht archivierte Chats. Das Löschen schließt archivierte Chats ein und verschiebt sie in den Papierkorb, wo du sie innerhalb der Aufbewahrungsfrist wiederherstellen kannst. Chats unter rechtlicher Aufbewahrung bleiben unverändert; Chats mit einer laufenden Antwort können nicht gelöscht werden.

Lies die Bestätigung, bevor du fortfährst. Das Ergebnis zeigt, wie viele Chats geändert wurden und wie viele nicht geändert werden konnten. Verwende das Menü eines einzelnen Chats im Bereich **Start**, wenn du nur dieses Gespräch ordnen möchtest. Archivierte Chats bleiben dort unter **Archiviert** am Ende der Liste; **Dearchivieren** im Menü eines Chats holt ihn zurück.

**Abmelden** im Profilmenü beendet die aktuelle Sitzung und führt zur Anmeldung zurück. Melde dich auf gemeinsam genutzten Geräten nach der Arbeit ab. Für ein eigenes App-Fenster auf deinem Gerät lies [Als App installieren](https://docs.tale.dev/de/platform/member/install-as-app).

Endet deine Sitzung, während Tale geöffnet ist, etwa weil du dich in einem anderen Browser-Tab abgemeldet hast, zeigt eine abgelehnte Anfrage **Deine Sitzung ist beendet. Melde dich erneut an.**, und ein Dokument-Upload schlägt mit demselben Satz fehl, ohne einen erneuten Versuch anzubieten. Öffnest du danach den Tab **Umgebung** eines Projekts, zeigt er stattdessen **Admin-Zugriff erforderlich**. War der Tab schon vorher offen oder öffnest du ihn weniger als fünf Minuten nach dem letzten Laden erneut, zeigt er weiterhin seine Variablen, und beim Speichern erscheint derselbe Satz. **Einstellungen > Datenresidenz** meldet **Du darfst die Datenresidenz dieser Organisation nicht verwalten.** Auf den Seiten deiner Organisation, deren Adresse mit `/dashboard` beginnt, prüft Tale die Sitzung und fragt nach, bevor es die Anmeldeseite öffnet. Dabei verlässt du die aktuelle Seite und ungespeicherte Änderungen können verloren gehen. Wähle **Hier bleiben**, um die Seite geöffnet zu lassen und wichtige Eingaben zu kopieren. Weitere abgelehnte Anfragen öffnen die Bestätigung nicht erneut. Auf anderen Seiten fragt Tale nicht nach: Lade die Seite neu, um dich erneut anzumelden.

Wenn du bereit bist, schließe offene Dialoge und wähle **Anmelden** im Hinweis, der oben auf der Seite über ihrer Kopfzeile stehen bleibt. Bestätige anschließend die Anmeldung. Tale prüft die Sitzung erneut: Hast du dich bereits in einem anderen Tab angemeldet, bleibt die Seite geöffnet. Andernfalls erscheint die Anmeldeseite mit demselben Sitzungshinweis. Nach der Anmeldung kehrst du zur bisherigen Seite zurück. Kopierte Eingaben kannst du erneut einfügen; ungespeicherte Entwürfe werden nicht automatisch wiederhergestellt.

# Ein verfügbares Modell wählen
Source: https://docs.tale.dev/de/platform/models

Die Modellauswahl zeigt, was deine Organisation derzeit nutzen kann, nicht alle Angebote eines Providers. Nutzbare Zugangsdaten, deren Modell-Freigabeliste und die Zugriffsregeln der Organisation bestimmen das Ergebnis. Administratoren verwalten diese unter **Einstellungen > KI-Anbieter** und [Inhalte & Modelle](https://docs.tale.dev/de/platform/admin/governance/content-models).

## Automatisch oder gezielt auswählen

Im Chat wählt **Auto** für jede Nachricht ein Modell anhand ihrer Merkmale, etwa Länge, Code und angehängte Dokumente. Dafür dient eine einfache Heuristik, kein zweiter KI-Aufruf. Die Details einer Antwort zeigen, welches Modell tatsächlich geantwortet hat.

Wähle im Eingabebereich ein bestimmtes Modell, wenn du Ergebnisse vergleichen, die Auswahl kontrollieren oder eine bekannte Aufgabe gezielt bearbeiten möchtest. Diese Auswahl bleibt, bis du sie änderst oder zu Auto zurückkehrst. In der [Arena](https://docs.tale.dev/de/platform/chat/arena-mode) vergleichst du zwei verfügbare Modelle mit derselben Nachricht.

Projektagenten und Modellschritte in Workflows verwenden ihr konfiguriertes Modell. Die Auswahl eines Agenten unterscheidet Einträge verschiedener Provider auch bei gleicher Modell-ID. Mit einem Eintrag legst du die Kombination aus Provider und Modell fest. Ein Modellfehler wird angezeigt; die Antwort kommt nicht stillschweigend von einem anderen Modell.

## Die Herkunft der Liste verstehen

Öffne **Einstellungen > KI-Anbieter**, um den Provider und seine angebotenen Modelle zu prüfen. Die Anzahl beschreibt die vorhandenen Modelldefinitionen. Sie belegt weder Zugangsdaten noch die Berechtigung deiner Organisation, jedes dieser Modelle aufzurufen.

| Quelle | Wie Modelle in den Katalog gelangen | Wann sie sich ändert |
| --- | --- | --- |
| Mitgelieferter Katalog | Die Modelldefinitionen werden mit Tale ausgeliefert. | Bei einem Plattform- oder Katalogupdate. |
| OpenRouter-Katalog | Tale ruft die Liste von OpenRouter ab. | Nach einem Abruf oder einer erzwungenen Aktualisierung. |
| Modell-Endpunkt des Providers | Tale ruft die Modellliste des Providers ab. | Nach einem Abruf oder einer erzwungenen Aktualisierung. |
| Kein Katalog | Modell-IDs stammen aus der Freigabeliste der Zugangsdaten. | Wenn ein Administrator diese Liste ändert. |

Azure OpenAI und Nous Portal verwenden Modell-IDs aus den Zugangsdaten. Trage bei Azure die Deployment-Namen deiner Ressource ein; sie können von öffentlichen Modellnamen abweichen. Bei einem Provider ohne Katalog macht eine leere Freigabeliste kein Modell verfügbar.

## Einen abgerufenen Katalog aktualisieren

Inhaber, Admins und Entwickler wählen **Kataloge aktualisieren** im Kopfbereich der Einstellungen. Lies das Ergebnis je Provider: Es enthält die Modellanzahl oder den Fehler, der den Abruf verhindert hat. Ein fehlgeschlagener Abruf bedeutet nicht, dass der Provider keine Modelle anbietet.

Externe Kataloge werden 24 Stunden zwischengespeichert und bei einer späteren Anfrage aktualisiert, wenn der Cache veraltet ist. Der Button erzwingt einen neuen Versuch. Schlägt ein automatischer Abruf fehl, kann Tale den bisherigen Katalog oder mitgelieferte Modelle weiterverwenden; ein erzwungener Abruf meldet den Fehler. Ein neues Modell muss außerdem die Prüfungen für Zugangsdaten und Richtlinien bestehen. Installationen mit ausschließlich mitgelieferten Katalogen haben keine externen Listen abzurufen.

## Ein fehlendes Modell finden

Prüfe die Grenzen in dieser Reihenfolge. Wenn du die Einstellungen nicht ändern darfst, gib die Informationen an einen Administrator weiter:

1. Prüfe, ob der Provider aktivierte, nutzbare Zugangsdaten hat. Ein Katalogeintrag allein verbindet noch kein Konto.
2. Lies die **Erlaubte Modelle** dieser Zugangsdaten. Bei einem Provider mit Katalog begrenzt sie die Auswahl, ohne Katalog legt sie sie fest.
3. Prüfe die Modellzugriffsregeln für Organisation, Team oder Person unter [Inhalte & Modelle](https://docs.tale.dev/de/platform/admin/governance/content-models).
4. Prüfe bei einem Projektagenten, ob die Zugangsdaten seinen gewählten [Harness](https://docs.tale.dev/de/platform/agents/harnesses) unterstützen. Ein Abonnement kann an eine bestimmte Laufzeit gebunden sein, und ein Modell, das Tools nur über die Responses-API von OpenAI aufruft, etwa GPT-6.1 Sol, wird nur für Codex angeboten.
5. Im Chat erscheint kein Modell, das nur Abo-Zugangsdaten bereitstellen: Ein Abo läuft nur in Aufgaben und Automatisierungen, und die Modellliste im Chat nennt die Abos, die sie auslässt. Füge Zugangsdaten per API-Schlüssel oder Umgebungsvariable hinzu, um mit diesem Modell zu chatten; [KI-Provider](https://docs.tale.dev/de/platform/admin/providers#abos-in-aufgaben-nutzen-nicht-im-chat) erklärt, warum.

Ist das Modell sichtbar, aber der Aufruf schlägt fehl, lies die Begründung. Abgelaufene Zugangsdaten, Provider-Ausfälle, Budgetgrenzen und fehlende Sandbox-Kapazität sind unterschiedliche Probleme. Ein Katalogabruf behebt sie nicht alle. [KI-Provider](https://docs.tale.dev/de/platform/admin/providers) erklärt Zugangsdaten; [Richtlinien und Limits](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits) behandelt Ausgabengrenzen.

# Den Projekt-Backlog sichten
Source: https://docs.tale.dev/de/platform/projects/backlog

Verwende **Backlog** für vorgeschlagene Arbeit, die das Team noch nicht zugesagt hat. Dieser normale Aufgabenstatus steht im Board und in der Liste an erster Stelle. Ein Vorschlag darf bereits zugewiesen sein; dadurch wird er noch nicht zu laufender Arbeit. Ist er dir zugewiesen, erscheint er dennoch mit dem Status **Backlog** unter deinen Aufgaben im Bereich [Start](https://docs.tale.dev/de/platform#home).

## Einen Vorschlag erfassen

Öffne die **Aufgaben** des Projekts und erstelle eine Aufgabe. Wähle im Statusfeld **Backlog**; ohne Änderung beginnt eine neue Aufgabe mit **Zu erledigen**. Beschreibe das gewünschte Ergebnis im Titel und ergänze genug Kontext für die Entscheidung, ob das Team den Vorschlag verfolgen soll.

Zum Beispiel lässt sich „Fehler beim mobilen Checkout prüfen“ besser beurteilen, wenn die betroffene Seite, ein nachvollziehbares Fehlerbild und ein Screenshot beigefügt sind. Lege die Umsetzung erst fest, wenn das Problem verstanden ist.

Auch ein Projektagent mit dem Tool zum Erstellen von Aufgaben kann Vorschläge erfassen. Dieses Tool erlaubt als Anfangsstatus **Backlog** oder **Zu erledigen**, keinen laufenden oder abgeschlossenen Status. Die gleiche Grenze gilt für Automatisierungen, die Aufgaben-Tools des Projekts verwenden.

## Den nächsten Schritt entscheiden

| Entscheidung | Aktion |
| --- | --- |
| Es fehlen Informationen | Behalte **Backlog** und benenne die Lücke in Beschreibung oder Kommentar. |
| Das Team nimmt die Arbeit an | Setze **Zu erledigen** und weise eine Person zu. |
| Die Arbeit hat begonnen | Verschiebe die Aufgabe nach **In Bearbeitung**. |
| Der Vorschlag wird nicht weiterverfolgt | Setze **Abgebrochen**; die Diskussion bleibt erhalten. |

Ändere den Status im Aufgabendetail oder ziehe die Karte in eine andere Board-Spalte. Es gelten die üblichen Aufgabensteuerungen. Der Backlog hat keinen eigenen Ablauf zum Annehmen oder Ablehnen.

## Die Aufgabe einem Agenten übergeben

Wähle einen Agenten desselben Projekts und beschreibe das erwartete Ergebnis, bevor du **Agent starten** wählst. Die Zuweisung ersetzt diesen Start nicht. Die [Aufgaben-Automatisierung](https://docs.tale.dev/de/platform/projects/task-automation) erklärt Voraussetzungen, Fortschritt und Prüfung.

## Die Herkunft der Vorschläge verstehen

Die mitgelieferte Automatisierung **GitHub-Issues sichten** liefert einen nach Priorität sortierten Bericht. Sie erstellt keine Projektaufgaben und füllt den Backlog nicht automatisch. Eine Person oder ein passend ausgestatteter Agent muss aus einem ausgewählten Issue eine Aufgabe machen. Der Bericht gibt damit eine Empfehlung; die Entscheidung über die Aufnahme der Arbeit bleibt ein eigener Schritt.

[Projektaufgaben verwalten](https://docs.tale.dev/de/platform/projects/tasks) erklärt Details, Kommentare, Abhängigkeiten und die weiteren Board-Funktionen.

# Projektgrundlagen
Source: https://docs.tale.dev/de/platform/projects/concepts

Nutze ein Projekt, wenn mehrere Fragen oder Aufgaben auf denselben Unterlagen beruhen. Es vereint Dateien, Anweisungen, Chats, eine Aufgabenübersicht und Aufgabenagenten. Eine einmalige Frage kann in einem gewöhnlichen Chat bleiben. Für eine Veröffentlichung, Kundenübergabe oder laufende Untersuchung ist ein Projekt meist hilfreicher.

## Was das Projekt zusammenhält

| Bereich | Was hier hingehört |
| --- | --- |
| **Allgemein** | Name, Beschreibung, dauerhafte Anweisungen, Freigabe und Standard-Reviewer für Aufgaben. |
| **Chats** | Deine Projektgespräche und ausdrücklich mit dem Projekt geteilte Gespräche. |
| **Wissen** | Referenzdateien in Ordnern, deren Zugriff auf dieses Projekt begrenzt ist. |
| **Aufgaben** | Arbeit mit Zuständigkeit, Status, Kommentaren und einem prüfbaren Ergebnis. |
| **Agenten** | Benannte Agenten, die für Aufgaben eingerichtet sind. |

Ein Projektchat beginnt mit den gespeicherten Projektanweisungen. Er kann die Dateien dieses Projekts und das zugängliche Wissen der Organisation durchsuchen. So haben auch spätere Gespräche eine gemeinsame Grundlage, ohne dass du jedes Mal ein Briefing einfügen musst. Dateien anderer Projekte gehören nicht zu diesem Suchbereich.

<Frame caption="Unter Allgemein stehen Projektanweisungen und Freigabe. Speichere geänderte Felder anschließend.">

![Allgemein im Projekt Website relaunch zeigt Name, Beschreibung, den Editor für Anweisungen, Freigabe sowie Speichern und Verwerfen.](https://docs.tale.dev/images/platform/project-general-tab.webp)

</Frame>

## Eine wiedererkennbare Identität wählen

**Projekt erstellen** fragt nach einem Namen und einem **Projektkürzel**; Beschreibung, Icon und Farbe sind optional. Der Schlüssel wird zum Präfix von Aufgaben-IDs wie `WR-1` und lässt sich nach dem Erstellen nicht mehr ändern. Wähle ein kurzes, dauerhaft passendes Kürzel.

Name, Beschreibung, Icon, Farbe und Anweisungen kannst du später unter **Allgemein** ändern. Mit **Speichern** übernimmst du Feldänderungen, mit **Verwerfen** gibst du sie auf. Eine vollständige Anleitung bietet [Projekte nutzen](https://docs.tale.dev/de/tutorials/member/use-projects).

Halte in den Anweisungen wiederkehrenden Kontext fest: Worum geht es, welche Quellen sind maßgeblich und wie soll der Assistent mit fehlenden Angaben umgehen? Einmalige Aufträge gehören in den Chat oder die Aufgabenbeschreibung. Projektanweisungen sollten kein Protokoll aller bisherigen Entscheidungen werden.

## Prüfen, wer das Projekt öffnen kann

Neue Projekte sind standardmäßig **Organisationsweit** zugänglich. Wähle beim Erstellen unter **Wer es sehen kann** die Teams aus, oder später unter **Reichweite** auf der Seite **Allgemein**. Eine leere Reichweite bedeutet alle in der Organisation; sonst können die Mitglieder eines der genannten Teams das Projekt öffnen, Organisationsadministratoren immer. Sofern du nicht Inhaber oder Admin bist, kannst du nur Teams wählen, denen du selbst angehörst. Entfernst du später ein Team, sehen Mitglieder außerhalb der verbleibenden Teams das Projekt nicht mehr; die Seite lässt dich das bestätigen. Die Freigabe erfolgt über Teams, nicht über einzelne Einladungen. Die Projektliste zeigt die Teams jedes Projekts in der Spalte **Freigabe** und bietet einen Filter **Teams**.

Projektdateien folgen dem Projektzugriff. Sie erscheinen nicht als gewöhnliche Bibliotheksdokumente; umgekehrt macht eine Team-Zuordnung ein Bibliotheksdokument nicht zum Projektanhang. [Dateien verwalten](https://docs.tale.dev/de/platform/projects/manage-files) erklärt das Verschieben und warum das Entfernen aus einem Projekt den Leserkreis erweitern kann.

## Persönliche und geteilte Chats unterscheiden

Ein Chat im Projekt beginnt als dein eigenes Gespräch. Andere Projektmitglieder sehen ihn nicht allein dadurch, dass sie das Projekt öffnen können. **Chats** trennt **Deine Chats** von **Mit Projekt geteilt**. Nutze **Mit Projekt teilen**, wenn das Gespräch für Kollegen bereit ist.

Kollegen öffnen einen geteilten Chat nur lesend: Sie können weder antworten noch eine Nachricht bearbeiten oder eine Antwort bewerten. Wo du eine Nachricht bearbeitet oder eine Antwort neu erzeugt hast, lesen sie die von dir ausgewählte Version, nicht die ersetzte.

Lies die Nachrichten vor der Freigabe durch, auch vertrauliche Angaben, die eine Antwort zitiert. Verschiebst du einen geteilten Chat in ein anderes Projekt oder aus dem Projekt heraus, endet seine Projektfreigabe. Teile ihn bewusst erneut, wenn die neue Zielgruppe ihn lesen soll.

Gehört ein bestehendes Gespräch zu dieser Arbeit, nutze **In Projekt verschieben…** in den Chat-Aktionen oder zieh den Chat im Bereich **Start** auf das Projekt. Organisationsweite Links auf eine Momentaufnahme sind eine eigene Funktion; siehe [Einen Chat teilen](https://docs.tale.dev/de/platform/chat/shared-threads).

## Aus einem Gespräch eine Aufgabe machen

Erstelle eine [Aufgabe](https://docs.tale.dev/de/platform/projects/tasks), wenn eine Entscheidung eine zuständige Person oder ein Ergebnis braucht. Ein Teammitglied kann sie selbst erledigen; ein eingerichteter [Projektagent](https://docs.tale.dev/de/platform/projects/project-agents) kann sie ebenfalls bearbeiten. Schreibe die Abnahmekriterien in die Beschreibung, damit das Ergebnis prüfbar ist.

Archiviere ein abgeschlossenes Projekt, um es aus der aktiven Liste zu nehmen. Ein archiviertes Projekt ist für alle schreibgeschützt: Einstellungen, Aufgaben, Dateien und Agenten lassen sich lesen, aber nicht ändern, bis ein Projekt-Administrator es unter **Allgemein** wiederherstellt. Lies vor dem Löschen die Auswahl für seine Inhalte: Beim Herauslösen bleiben Dateien in der Bibliothek und Chats als persönliche Gespräche erhalten. Beim Mitlöschen werden auch die Inhalte entfernt. Herausgelöste Dateien können einem größeren Kreis zugänglich werden. Entscheide danach, was verfügbar bleiben soll.

# Projektdateien verwalten
Source: https://docs.tale.dev/de/platform/projects/manage-files

Unter **Wissen** im Projekt liegen Dateien, die dessen Chats abrufen können. Lade eine Referenz einmal hoch und verwende sie in mehreren Projektgesprächen. Zum Hinzufügen, Ordnen oder Entfernen brauchst du Bearbeitungszugriff auf das Projekt.

<Frame caption="Die Dateien gehören zum Projekt. Ihre Statusanzeigen zeigen, ob der Chat ihren Text durchsuchen kann.">

![Der Bereich Wissen im Projekt Website relaunch enthält zwei indexierte Dateien sowie Schaltflächen für neue Ordner und Datei- und Ordner-Uploads.](https://docs.tale.dev/images/platform/project-knowledge-files.webp)

</Frame>

## In den passenden Ordner hochladen

1. Öffne das Projekt und wähle **Wissen**.
2. Wähle einen Ordner oder bleibe auf der obersten Ebene.
3. Klicke auf **Datei hinzufügen** oder ziehe Dateien auf die Upload-Fläche.
4. Prüfe, ob jede Datei im gewünschten Ordner erscheint und fertig indexiert wird.

**Neuer Ordner** erstellt einen Ordner auf der obersten Ebene. Mit **Neuer Unterordner** legst du einen Ordner innerhalb eines anderen an. **Ordner hochladen** übernimmt einen Ordner von deinem Gerät und bildet seine Struktur am gewählten Ort nach. Ein Ordner-Upload ist auf 200 Dateien und 200 MB begrenzt. Teile größere Ordner auf und prüfe den Bericht auf übersprungene Dateien.

## Prüfen, ob der Chat die Datei lesen kann

| Status | Bedeutung und Maßnahme |
| --- | --- |
| **In Warteschlange** | Die Datei wartet auf die Verarbeitung. |
| **Wird indexiert…** | Tale bereitet den Text für die Suche vor. |
| **Indexiert** | Der Text ist durchsuchbar. Prüfe eine Antwort anhand der Originaldatei. |
| **Fehlgeschlagen** | Lies verfügbare Fehlerdetails und nutze **Indexierung erneut versuchen**. Wiederholt sich der Fehler, bitte einen Admin um Hilfe. |
| **Nicht unterstützt** | Dieser Inhalt lässt sich nicht indexieren. Stelle lesbaren Text oder ein unterstütztes Format bereit; ein erneuter Versuch mit derselben Datei hilft nicht. |
| **Nicht indexiert** | Die Datei ist gespeichert, aber nicht durchsuchbar. Nutze **Jetzt indexieren**, sofern angeboten, oder wandle ein Format ohne Textextraktor um. |

Eine Integration kann Dateien ohne Indexierung hochladen. Sie bleiben im Dateibaum sichtbar. Eine unterstützte Textdatei lässt sich auf ausdrückliche Nachfrage direkt lesen; in der Textsuche erscheint sie erst nach der Indexierung.

Kommen nicht alle Dateien an, nennt der Bericht des Uploads die übrigen mit Grund: **Übersprungen** sind Dateien, die schon vor dem Hochladen an der Typ- oder Größenprüfung gescheitert sind. **Nicht hinzugefügt** sind Dateien, die Tale abgelehnt hat. Organisationsregeln können Datei- und Speichergrenzen weiter einschränken. Versuche bei einem fehlgeschlagenen Upload zuerst eine kleine unterstützte Datei. Ein Admin kann [Richtlinien und Limits](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits), Speicher und Embedding-Modell prüfen.

## Wenn Dateien oder Ordner nicht laden

Kann der Tab die Dateien oder Ordner des Projekts nicht laden, sagt ein Hinweis über dem Dateibaum, was fehlgeschlagen ist, und bietet **Erneut versuchen** an. Tale zeigt das Projekt wegen eines Ladefehlers nie als leer an:

- Scheitern nur die Ordner, bleiben alle geladenen Dateien aufgeführt. Dateien auf der obersten Ebene stehen an ihrem Platz, Dateien in Ordnern erscheinen unter **Dateien in Ordnern**, bis die Ordner geladen sind.
- Scheitern nur die Dateien, bleiben die Ordner sichtbar, und der Hinweis sagt, dass die Dateien fehlen.
- Scheitert eine Aktualisierung, nachdem der Baum geladen war, behält er seinen Stand, und der Hinweis sagt, dass er veraltet sein kann.

**Erneut versuchen** wiederholt nur den fehlgeschlagenen Abruf; aufgeklappte und ausgewählte Ordner bleiben erhalten. Scheitert es immer wieder, bitte einen Administrator zu prüfen, ob die Dienste von Tale laufen.

## Im Projektchat nach Dateien fragen

Öffne **Chats** in diesem Projekt, starte ein Gespräch und frage nach Dateiname oder Thema. Der Assistent kann Dateien dieses Projekts und zugängliche Dokumente der Wissensbibliothek abrufen. Dateien anderer Projekte erreicht er von hier aus nicht.

Der allgemeine Organisationschat durchsucht keine Projektdateien. Solange sie zum Projekt gehören, stehen sie weder in der Dokumentliste der Organisation noch in deren WebDAV-Bibliothek. Wer sie lesen darf, bestimmt der Projektzugriff. Separate Team-Zuordnungen gibt es bei Projektdateien nicht.

## Gelenkte Dateien mit Prüfverlauf ersetzen

Ein erneuter Upload unter demselben Namen erstellt ein separates Dokument. Ein gleicher Dateiname verknüpft keine Revisionen. Soll eine Freigabe an genau die geprüfte Datei gebunden bleiben, wähle im Zeilenmenü **Als gelenktes Dokument führen**.

Das gelenkte Dokument startet als Entwurf. **Datei ersetzen** aktualisiert einen Entwurf oder öffnet aus einer genehmigten Version den nächsten Entwurf, ohne die genehmigte Version zu verändern. **Zum Review einreichen** friert den Entwurf für den benannten Reviewer ein. [Gelenkte Dokumente](https://docs.tale.dev/de/platform/knowledge/documents) erklärt den gesamten Ablauf und die Regeln für Reviewer.

## In die Wissensbibliothek verschieben oder löschen

**Aus Projekt entfernen** verschiebt die Datei in die Wissensbibliothek der Organisation. Die Datei wird dabei nicht gelöscht.

<Warning>

Durch das Entfernen aus dem Projekt wird die Datei für alle Personen der Organisation sichtbar. Verwende diese Aktion nur, wenn du diesen größeren Personenkreis erreichen möchtest. Lies die Bestätigung vor dem Fortfahren.

</Warning>

Soll die Datei vollständig entfernt werden, nutze **Löschen** im Zeilenmenü und lies die Bestätigung. Das Löschen eines Ordners entfernt auch seine Dateien, Unterordner und Sucheinträge. Über den Dateibaum lassen sich diese Aktionen nicht rückgängig machen. Ein Legal Hold oder geschützte gelenkte Dokumente können das Löschen verhindern.

**Löschen** steht für hochgeladene Dateien und für Dateien bereit, die ein Agent im Projekt angelegt hat, etwa Lesungen oder erzeugte Berichte. Eine über einen Connector synchronisierte Datei bietet im Projekt kein Löschen an, weil die nächste Synchronisierung sie wiederherstellen würde; entferne sie stattdessen an ihrer Quelle.

Wird eine Datei in mehreren unabhängigen Projekten gebraucht, eignet sich möglicherweise eine passend freigegebene Kopie in der [Wissensbibliothek](https://docs.tale.dev/de/platform/knowledge/documents). Vermeide mehrere widersprüchliche Fassungen derselben Richtlinie.

# Projekte
Source: https://docs.tale.dev/de/platform/projects/overview

Ein Projekt vereint Dateien, Anweisungen, Gespräche und Aufgaben für ein Vorhaben. Nutze es, wenn Kontext über einen einzelnen Chat hinaus erhalten bleiben soll oder ein Ergebnis Zuständigkeit und Prüfung braucht. Mit [Projekte nutzen](https://docs.tale.dev/de/tutorials/member/use-projects) erstellst du ein Projekt und stellst eine Frage zu seiner Referenzdatei.

<Video src="https://docs.tale.dev/videos/de/tutorials/ep6-projects/ep6-projects.de.mp4" poster="https://docs.tale.dev/videos/de/tutorials/ep6-projects/ep6-projects.de.webp" captions="https://docs.tale.dev/videos/de/tutorials/ep6-projects/ep6-projects.de.vtt" lang="de" title="Episode 6 — Projekte mit KI" caption="Episode 6 — Projekte mit KI (2:47)">

</Video>

<Frame caption="Die Aufgabenübersicht zeigt Vorschläge, laufende Arbeit und Ergebnisse zur Prüfung nebeneinander.">

![Website relaunch zeigt Aufgabenkarten in Backlog, Zu erledigen, In Bearbeitung, In Prüfung, Erledigt und Abgebrochen.](https://docs.tale.dev/images/platform/projects-task-board.webp)

</Frame>

## Den nächsten Schritt finden

<CardGroup cols="2">

<Card title="Projektzugriff verstehen" icon="compass" href="https://docs.tale.dev/de/platform/projects/concepts">
Erfahre, was das Projekt teilt, welche Chats persönlich bleiben und wie Teams den Zugriff bestimmen.
</Card>

<Card title="Referenzdateien verwalten" icon="folder-open" href="https://docs.tale.dev/de/platform/projects/manage-files">
Lade Dateien hoch, ordne sie, prüfe die Indexierung und verwalte gelenkte Revisionen.
</Card>

<Card title="Aufgaben erstellen und verfolgen" icon="list-checks" href="https://docs.tale.dev/de/platform/projects/tasks">
Lege Zuständigkeit, Prüfung, Termine und Abnahmekriterien fest und verfolge den Fortschritt.
</Card>

<Card title="Einen Projektagenten einrichten" icon="bot" href="https://docs.tale.dev/de/platform/projects/project-agents">
Wähle Harness, Modell, Tools und Anweisungen für einen Agenten, der Aufgaben übernimmt.
</Card>

<Card title="Agentenarbeit starten und prüfen" icon="workflow" href="https://docs.tale.dev/de/platform/projects/task-automation">
Starte eine Aufgabe, prüfe das Ergebnis, fordere Nacharbeit an und behebe fehlgeschlagene Läufe.
</Card>

<Card title="Vorgeschlagene Arbeit sichten" icon="gauge" href="https://docs.tale.dev/de/platform/projects/backlog">
Prüfe Ideen im Backlog, bevor du sie in die geplante Arbeit des Teams übernimmst.
</Card>

</CardGroup>

Alle Projekte, die du öffnen kannst, stehen im Bereich [Start](https://docs.tale.dev/de/platform#home) unter **Projekte**; **Alle Projekte** öffnet dort die vollständige Liste. Ein Projekt öffnet sich mit seinem Aufgaben-Board, und **Allgemein**, **Chats**, **Wissen** und **Agenten** ergänzen die Aufgabenansichten. Für Inhaber, Admins und Entwickler fügt eine zugeordnete Automatisierung **Automatisierungen** hinzu; Projektadministratoren können die **Umgebung** konfigurieren. Installierte Apps können weitere Tabs ergänzen. Für den Einstieg mit Dateien, Chats und Aufgaben sind sie nicht nötig.

# Projektagenten erstellen und verwalten
Source: https://docs.tale.dev/de/platform/projects/project-agents

Erstelle einen Projektagenten, wenn ein wiederverwendbarer Agent die Aufgaben dieses Projekts bearbeiten soll. Er verbindet Coding-Laufzeit, Modell, Anweisungen und erlaubte Ausstattung. Du brauchst Bearbeitungszugriff auf das aktive Projekt. Mitglieder sehen die Agenten des Projekts im Tab **Agenten**, der ihnen sagt, dass sie einen Redakteur oder Admin um einen neuen bitten können. Bis ein Projekt eigene Agenten hat, können seine Aufgaben an den [Standard-Agenten](https://docs.tale.dev/de/platform/projects/project-agents#standard-agent) der Organisation gehen. Secret-Zuordnungen dürfen nur Inhaber und Admins ändern.

## Die erste Aufgabe vorbereiten

Wähle ein kleines Ergebnis, etwa die Prüfung eines Launch-Briefings auf fehlende Freigaben. Der Agent braucht passende [Provider-Zugangsdaten](https://docs.tale.dev/de/platform/admin/providers) und eine verfügbare [Sandbox](https://docs.tale.dev/de/platform/admin/sandboxes). Eine gespeicherte Konfiguration belegt noch keinen erfolgreichen Sandbox-Lauf.

Trenne dauerhafte Anweisungen von der jeweiligen Aufgabe. „Erkenne fehlende Belege und berichte über deine Prüfungen“ gehört zum Agenten. Dokument, Prüfungstermin und Abnahmekriterien gehören zur Aufgabe.

<Frame caption="Der Tab Agenten — die eigenen Agenten des Projekts; jede Zeile nennt Agent-Laufzeit, Provider und Modell.">

![Der Tab Agenten des Projekts Website relaunch mit zwei benannten Agenten — Content editor auf Claude Code und Redirect auditor auf Codex — jede Zeile mit Provider und Modell-ID, neben dem Knopf Neuer Agent.](https://docs.tale.dev/images/platform/project-agents-models.webp)

</Frame>

## Den Agenten konfigurieren

<Steps>

<Step title="Namen und Laufzeit wählen">

Öffne den Tab **Agenten** des Projekts und wähle **Neuer Agent**. Gib unter **Name** einen erkennbaren Namen ein und wähle die **Agent-Laufzeit**, also den Coding-[Harness](https://docs.tale.dev/de/platform/agents/harnesses). Namen sind innerhalb des Projekts eindeutig; bis zu 50 Agenten sind möglich.

Du kannst auch bei einer Aufgabe beginnen: Solange das Projekt keinen Agenten hat, öffnet **Agent erstellen …** unter **Zuständig** den Dialog **Neuer Agent** über der Aufgabe und weist ihr den Agenten zu, den du erstellst.

</Step>

<Step title="Modell und Provider auswählen">

Suche unter **Modell** nach Name oder API-ID. Dasselbe Modell kann pro Provider einmal erscheinen. Lies den Provider des Eintrags, bevor du ihn wählst. Damit legst du diese Kombination für künftige Läufe fest. Abonnementeinträge erscheinen nur bei kompatibler Laufzeit, und ein Modell, das Tools nur über die Responses-API von OpenAI aufruft, etwa GPT-6.1 Sol, erscheint nur bei Codex.

Eine ältere Konfiguration kann ein Modell ohne festgelegten Provider enthalten. Der Dialog zeigt, welcher Provider es derzeit bereitstellen würde oder warum kein Zugang verfügbar ist. Wähle einen Eintrag, wenn du den Provider festlegen möchtest.

</Step>

<Step title="Ausstattung vergeben und Anweisungen schreiben">

Füge unter **Skills, Connectors & Tools** die benötigten Bundles, Dienste und Plattformoperationen hinzu. Bei einem neuen Agenten sind die Dokument-Skills `docx`, `pptx`, `xlsx` und `pdf` vorausgewählt, sofern sie für das Projekt verfügbar sind. Sie enthalten Anleitungen für die Arbeit mit Word-, PowerPoint-, Excel- und PDF-Dateien. Entferne die Häkchen bei Skills, die der Agent nicht braucht. Beim Bearbeiten eines bestehenden Agenten bleibt seine gespeicherte Ausstattung erhalten. Verfügbare Skills folgen dem Team-Zugriff des Projekts, nicht nur deiner persönlichen Sichtbarkeit. Ein fehlender Skill kann deshalb eine andere Freigabe brauchen.

<Frame caption="Das Skills-Menü eines neuen Agenten mit bereits eingeschalteten Dokument-Skills; bei jedem Skill steht, wer ihn erstellt hat.">

![Der Dialog Neuer Agent mit geöffnetem Skills-Menü: docx, pdf, pptx und xlsx sind eingeschaltet und als Mitgeliefert gekennzeichnet, brief-summary und release-notes von Alex Rivera sowie visual-aspect-analyzer bleiben aus.](https://docs.tale.dev/images/platform/project-agent-document-skills.webp)

</Frame>

Beachte **Schreibt Daten**, bevor du ein Plattform-Schreib-Tool vergibst. Es erlaubt echte Operationen innerhalb seiner Zugriffsregeln. Der Connector-Broker bietet Agenten nur Leseaktionen; direkte GitHub-Werkzeuge und ausdrücklich vergebene Secrets haben eigene Zugangswege.

Mit **Aufgabenpriorität und Agentenzuweisung ändern** darf ein Projekt-Agent bestehende Aufgaben priorisieren, einem Agenten desselben Projekts zuweisen oder die Zuweisung aufheben, ohne Arbeit zu starten. Diese Freigabe ist zunächst ausgeschaltet und steht Agent-Nodes in Automatisierungen nicht zur Verfügung. Der Agent muss die Aufgabe zuerst lesen und bei einer Änderung die gelesenen Werte mitgeben. Hat jemand diese Werte inzwischen geändert, wird die gesamte Anfrage abgelehnt; der Agent muss erneut lesen. Ein Wechsel der Zuständigkeit ist nur bei offenen Aufgaben ohne laufende Ausführung, ausstehende Prüfung oder offene Frage möglich. Eine reine Prioritätsänderung lässt diese Übergaben bestehen. Das Tool ändert weder Status noch Prüfer, beantwortet keine Frage an einen Menschen und startet keinen Lauf. Es steht nur einem aktiven Lauf mit projektweiten Rechten zur Verfügung, nicht einem Lauf, den ein Mitglied gestartet hat.

**Aufgabenergebnisse anderer Agenten prüfen** erlaubt einem benannten Reviewer, über ein abgeschlossenes Ergebnis eines anderen Projektagenten zu entscheiden. Die Berechtigung ist anfangs ausgeschaltet und steht Agent-Nodes in Automatisierungen nicht zur Verfügung. Einen Agenten als Reviewer auszuwählen, erteilt weder diese Berechtigung noch startet es einen Lauf. Er prüft von seiner eigenen Aufgabe aus, mit aktuellen projektweiten Rechten und weiterhin erteilter Review-Berechtigung. Die Entscheidung hält Rückmeldung und Belege fest: Eine Freigabe schließt die geprüfte Aufgabe ab, eine Änderungsanforderung stellt sie ohne neuen Lauf auf **Zu erledigen**. Erforderliche menschliche Kompetenzen und Workflow-Genehmigungen bleiben geschützt. [Einen unabhängigen Reviewer einrichten](https://docs.tale.dev/de/platform/projects/task-automation#agent-review) beschreibt den Ablauf.

Mit **Andere Agenten auf Aufgaben starten** kann der Agent einen anderen Agenten dieses Projekts an die Arbeit schicken, etwa als Manager-Agent, der startbereite Arbeit verteilt und einen Agenten weiterarbeiten lässt, nachdem er dessen Frage beantwortet hat. Er nennt dazu eine Aufgabe, optional den Agenten, dem sie zugewiesen werden soll, und eine Nachricht, auf die der gestartete Lauf als Erstes eingeht. Der gestartete Lauf arbeitet im selben Auftrag wie der Lauf des Managers und nennt den Manager als den Agenten, der ihn gestartet hat. Ein so gestarteter Agent kann keine weiteren Agenten starten, ein Lauf, den ein Mitglied gestartet hat, kann gar keine starten, und weder ein Agent, der schon an einer anderen Aufgabe arbeitet, noch eine Aufgabe, die von einer offenen Aufgabe blockiert wird, wird gestartet. Vergib dieses Tool nur an einen Agenten, dessen Anweisungen festlegen, welche Arbeit er verteilen darf. Was ein solcher Lauf darf, beschreibt die [Aufgaben-Automatisierung](https://docs.tale.dev/de/platform/projects/task-automation#arbeit-die-eine-automatisierung-oder-ein-anderer-agent-startet).

Die Connector-Aufrufe eines Laufs erfolgen im Namen des Mitglieds, das ihn gestartet hat, ob mit **Agent starten**, mit **Erneut ausführen**, durch Verschieben nach **In Bearbeitung** oder durch eine Erwähnung des Agenten mit @. Sie nutzen die [Connector-Zugangsdaten](https://docs.tale.dev/de/platform/admin/connectors) der Organisation und werden diesem Mitglied zugeordnet. Verlässt es die Organisation oder wird es deaktiviert, lehnt Tale die Aufrufe ab. Beende den Lauf dann mit **Lauf abbrechen** (oder lass ihn zu Ende laufen) und starte ihn selbst neu, damit er in deinem Namen arbeitet. Startet ein Kommentar den Lauf neu, um ihn zu lenken, wie bei allen Laufzeiten außer Claude Code, erfolgen die Aufrufe ab dann im Namen der Person, die den Kommentar geschrieben hat.

Beschreibe unter **Anweisungen** Verantwortung, Belege und Grenzen. Für den Launch-Prüfer etwa: „Lies das beigefügte Briefing. Berichte über fehlende Freigaben und widersprüchliche Termine mit der zugehörigen Textstelle. Schließe die Aufgabe nicht ab.“

</Step>

<Step title="Prüfen und speichern">

Braucht die Arbeit **Secrets**, ordnet ein Inhaber oder Admin benannte Zugangsdaten der Organisation zu. Der laufende Agent kann ihre Werte lesen. Verwende deshalb eng begrenzte, austauschbare Tokens. Ändert sich ein gemeinsam genutzter Wert, betrifft das auch andere Agenten und Workflow-Nodes mit diesem Namen. Ein Lauf, den ein Mitglied startet, erhält keines dieser Secrets und auch nicht das Token eines zugeordneten GitHub-Zugangs: Arbeit, die sie braucht, muss ein Redakteur oder eine höhere Rolle starten.

Wähle **Agent erstellen**. Prüfe Laufzeit, Provider und Modell der neuen Zeile. Öffne den Agenten erneut, um gespeicherte Ausstattung und Anweisungen zu kontrollieren.

</Step>

</Steps>

## Arbeit zuweisen und starten

Öffne eine Aufgabe desselben Projekts, wähle den Agenten als Zuständigen und klicke auf **Agent starten**. Zuweisung und Ausführung sind getrennte Aktionen. Ergänze Dateien und Abnahmekriterien vor dem Start. Bearbeitungszugriff auf das Projekt brauchst du dafür nicht: Mitglieder lassen einen Agenten an Aufgaben arbeiten, die sie erstellt haben oder die ihnen zugewiesen sind, Redakteure und höhere Rollen an jeder Aufgabe des Projekts. Ein Lauf, den ein Mitglied startet, bleibt bei dieser Aufgabe, ohne die Secrets des Agenten und in einem eigenen Arbeitsbereich; [Agentenläufe, die ein Mitglied startet](https://docs.tale.dev/de/platform/projects/tasks#agentenlaeufe-die-ein-mitglied-startet) zählt auf, was sich ändert.

Der Bericht erscheint als Aufgabenkommentar; gesammelte Dateien werden als Ergebnisse angehängt. Hat ein Admin die [Bildgenerierung](https://docs.tale.dev/de/platform/admin/governance/content-models#let-agents-generate-images) eingeschaltet, kann der Agent für die Aufgabe auch Bilder erstellen. Sie erscheinen bei den Ergebnisdateien und zählen für das Mitglied, das den Lauf gestartet hat. Nach erfolgreicher Agentenarbeit steht die Aufgabe **In Prüfung**, damit der benannte menschliche Reviewer oder unabhängige Reviewer-Agent sie beurteilt. Erwähne den Agenten in einem Kommentar, um die Arbeit zu lenken oder fortzusetzen. Der Harness bestimmt, ob der Hinweis in den laufenden Prozess gelangt oder eine Fortsetzung startet.

Die [Aufgaben-Automatisierung](https://docs.tale.dev/de/platform/projects/task-automation) erklärt Fortschritt, Stoppen und Prüfung. Der gewöhnliche Chat-Assistent bleibt davon getrennt, auch mit Projektkontext.

## Der Standard-Agent {#standard-agent}

Auch ein Projekt ohne eigene Agenten kann Arbeit an einen Agenten übergeben. Sofern ein Admin ihn unter [Richtlinien > Modelle](https://docs.tale.dev/de/platform/admin/governance/content-models#standard-agent) nicht ausgeschaltet hat, bietet **Zuständig** dort die Option **Standard-Agent** an, und zwar allen, die die Aufgabe zuweisen können, auch Mitgliedern. Wählt jemand sie zum ersten Mal, richtet Tale den Agenten im Projekt ein und weist ihm die Aufgabe zu. Danach startest du ihn wie jeden anderen Agenten oder erwähnst ihn in einem Kommentar. Kann er für dich nicht starten, sagt das Kommentarfeld es dir, und dein Kommentar wird als einfache Erwähnung gespeichert.

<Frame caption="Der Tab Agenten eines Projekts, dessen Aufgaben an den Standard-Agenten gehen.">

![Der Tab Agenten des Projekts Customer onboarding portal mit einer Zeile: der Standard-Agent mit dem Abzeichen Standard, Claude Code, OpenRouter, dem Modell anthropic/claude-haiku-4.5 und vier Ausstattungen. Ein Hinweis sagt, dass Tale ihn für dieses Projekt eingerichtet hat und Agent-Laufzeit, Modell und Anweisungen den Einstellungen der Organisation folgen. Die Zeile hat eine Schaltfläche zum Löschen, aber keine zum Bearbeiten.](https://docs.tale.dev/images/platform/project-agents-standard.webp)

</Frame>

Der Tab **Agenten** führt ihn mit dem Abzeichen **Standard**. Niemand bearbeitet ihn: Agent-Laufzeit, Modell und Anweisungen folgen den Einstellungen der Organisation, die Tale bei jedem Start eines Laufs neu liest, und seine Ausstattung sind die Dokument-Skills `docx`, `pptx`, `xlsx` und `pdf`, die das Projekt beim Start eines Laufs nutzen kann. Schaltet ein Admin einen davon ab, fällt er weg, statt den Agenten aufzuhalten. Auf **Automatisch** nutzt jeder Lauf ein Modell, das die Person, die ihn startet, nutzen darf. Er kann also für verschiedene Personen mit verschiedenen Modellen laufen.

Um dem Projekt einen eigenen Agenten zu geben, wähle **Neuer Agent**. Ab dann bietet das Projekt den Standard-Agenten nicht mehr an; der bereits eingerichtete bleibt zuweisbar, bis du ihn löschst. Beim Löschen bleibt der Verlauf seiner Aufgaben erhalten, und solange das Projekt keine Agenten hat, richtet die nächste Aufgabe für den Standard-Agenten ihn wieder ein.

## Einen Agenten ändern oder entfernen

Bearbeite oder lösche den Agenten über sein Zeilenmenü. Der Standard-Agent hat nur **Agent löschen**. Änderungen gelten für spätere Läufe; ein aktiver Lauf behält seine Startkonfiguration. Die Löschung entfernt Agentenzuweisungen von Aufgaben, erhält aber deren Verlauf. Sie löscht außerdem die [Sandbox-Arbeitsbereiche](https://docs.tale.dev/de/platform/admin/sandboxes#explain-why-a-workspace-disappeared) des Agenten samt Dateien, auch die der Mitglieder. Prüfe laufende Arbeit und sichere benötigte Ergebnisse, bevor du den zugehörigen Agenten entfernst.

Scheitert das Erstellen, lies die Begründung: Ein doppelter Name, fehlender Projektzugriff, ein nicht verfügbares Modell und unsichtbare Skills sind unterschiedliche Ursachen. Ein Lauf, der endgültig scheitert, sagt oben in seiner Aufgabe, was schiefging und wer es beheben kann; [Wenn der Agent nicht fertig wird](https://docs.tale.dev/de/platform/projects/task-automation#wenn-der-agent-nicht-fertig-wird) zählt die Fälle auf. Neue Anweisungen beheben diese Voraussetzungen nicht.

# Eine Aufgabe an einen Agenten delegieren
Source: https://docs.tale.dev/de/platform/projects/task-automation

Ein Projektagent bearbeitet eine Aufgabe und legt das Ergebnis zur Prüfung vor. Weise ihm die Arbeit zu, starte den Lauf und halte Rückmeldungen an der Aufgabe fest. Du musst die Aufgabe ändern dürfen: Redakteure und höhere Rollen dürfen das bei jeder Aufgabe im Projekt, Mitglieder bei den Aufgaben, die sie erstellt haben oder die ihnen zugewiesen sind. Außerdem müssen Anbieter, passende Agent-Laufzeit und Sandbox-Kapazität verfügbar sein.

<Frame caption="Agentenarbeit nutzt dasselbe Board wie menschliche Arbeit: Sie startet unter In Bearbeitung und wartet unter In Prüfung auf die Abnahme.">

![Das Aufgabenboard zeigt Arbeit in Backlog, Zu erledigen, In Bearbeitung, In Prüfung, Erledigt und Abgebrochen.](https://docs.tale.dev/images/platform/projects-task-board.webp)

</Frame>

## Die Aufgabe vorbereiten und starten

1. Erstelle eine [Aufgabe](https://docs.tale.dev/de/platform/projects/tasks) mit gewünschtem Ergebnis, Abschlusskriterien und Eingabedateien.
2. Wähle unter **Zuständig** einen [Projektagenten](https://docs.tale.dev/de/platform/projects/project-agents).
3. Wenn du das Projekt bearbeiten darfst, wähle unter **Reviewer** eine Person oder einen unabhängigen Agenten oder belasse es beim **Projektstandard**. Anfangs leitet der Projektstandard Reviews an einen berechtigten Aufgaben- oder Projektersteller. [Zuständigkeit und Prüfung festlegen](https://docs.tale.dev/de/platform/projects/tasks#zustaendigkeit-und-pruefung-festlegen) erklärt die Auswahl, Berechtigungen und offenen Übergaben.
4. Klicke auf **Agent starten** oder verschiebe die Aufgabe nach **In Bearbeitung**. Weist du den Agenten schon beim Erstellen der Aufgabe zu, erledigt **Erstellen und Agent starten** in **Aufgabe erstellen** das im selben Schritt.

Die Zuweisung allein startet keinen Lauf. Eine bereits zugewiesene Aufgabe kann im **Backlog** bleiben, bis das Team ihren Start beschließt. Bis jemand den Agenten startet, zeigt die Aufgabe allen, die ihn starten dürfen, **Agent starten** mit dem Hinweis **Der Agent wartet, bis du ihn startest.** Nach dem Start verwendet der Agent Beschreibung, Kommentare und Eingabedateien in seiner Sandbox. Die Laufanzeige zeigt, ob er wartet oder arbeitet. Ein Lauf, den ein Mitglied startet, bleibt bei seiner Aufgabe und kommt ohne die Secrets des Agenten aus; [Agentenläufe, die ein Mitglied startet](https://docs.tale.dev/de/platform/projects/tasks#agentenlaeufe-die-ein-mitglied-startet) zählt auf, was sich ändert.

Agenten erhalten die Anweisung, Aktualisierungen, Berichte, zugehörige Aufgaben und Rückfragen in der Sprache von Titel und Beschreibung der Aufgabe zu verfassen. Ist daraus keine Sprache erkennbar, verwenden sie die Standardsprache der Organisation für Agenten. Eine Kennung, ein Quartal oder eine automatisch ausgefüllte Titelvorlage legt keine Sprache fest. Ein Wechsel deiner Oberflächensprache ändert die Sprache der Aufgabe nicht; du kannst den Agenten ausdrücklich um einen Sprachwechsel bitten.

Fortschrittskommentare eines Workflows können Übersetzungen für jede unterstützte Oberflächensprache enthalten. Derselbe gespeicherte Kommentar erscheint dann in der jeweils gewählten Sprache. Kommentare ohne Übersetzungen behalten ihren ursprünglichen Text.

## Das Ergebnis lesen und annehmen

Der Agent schreibt seinen Bericht als Aufgabenkommentar und legt erzeugte Dateien als Ergebnisse ab. Danach wechselt die Aufgabe auf **In Prüfung**. Ein menschlicher Reviewer erhält eine Benachrichtigung und bei eingerichtetem E-Mail-Versand auch eine E-Mail. Ein Reviewer-Agent liest das ausstehende Review von seiner eigenen Aufgabe aus; die Zuweisung einer Prüfung startet ihn nicht automatisch.

Bereitgestellte oder übersprungene Dateien führt Tale in einem separaten Systemkommentar in deiner Oberflächensprache auf. Dort steht auch, wenn der Bericht fehlt oder gekürzt wurde. Der Bericht selbst bleibt in der Sprache der Aufgabe.

Bei einer menschlichen Prüfung liest du den Bericht, öffnest die Dateien und vergleichst sie mit den Abschlusskriterien. Setze die Aufgabe erst auf **Erledigt**, wenn du die Arbeit annimmst. Tale hält die Entscheidung fest; der Agent, der das Ergebnis erstellt hat, darf es nicht selbst freigeben.

Ist das Review einer Person zugewiesen, steuert **Reviewer** Benachrichtigung und Prüfwarteschlange, ohne die Entscheidung allein dieser Person vorzubehalten. Andere Personen, die die Aufgabe ändern dürfen, können sie ebenfalls annehmen; die Regeln der Organisation für unabhängige Reviews und Kompetenzen gelten dabei weiterhin. Ein ausstehendes Review eines Agenten muss ausdrücklich an eine berechtigte Person übertragen werden, bevor ein Mensch es freigeben kann. Die Zuständigkeit für die Umsetzung bleibt bei einem Reviewer-Wechsel bestehen; Einzelheiten stehen unter [Zuständigkeit und Prüfung festlegen](https://docs.tale.dev/de/platform/projects/tasks#zustaendigkeit-und-pruefung-festlegen).

Änderst du den **Reviewer**, während die Aufgabe unter **In Prüfung** wartet, überträgst du die gespeicherte Anfrage. Die Benachrichtigung des bisherigen menschlichen Reviewers wird erledigt. Eine neue Person erhält die Anfrage; ein einem Agenten zugewiesenes Review wartet auf diesen Agenten. **Projektstandard** verwendet die aktuelle Auswahl des Projekts. Ändern sich Review oder Ergebnis gleichzeitig, wird die Übergabe abgelehnt. Lies den aktualisierten Stand, bevor du es erneut versuchst.

## Einen unabhängigen Reviewer einrichten {#agent-review}

1. Erstelle einen eigenen [Projektagenten](https://docs.tale.dev/de/platform/projects/project-agents) für Reviews. Erteile ihm unter **Skills, Connectors & Tools** die Berechtigungen **Aufgaben finden**, **Aufgabe lesen** und **Aufgabenergebnisse anderer Agenten prüfen**. Die Review-Berechtigung ist anfangs ausgeschaltet und steht Agent-Nodes in Automatisierungen nicht zur Verfügung.
2. Wähle diesen Agenten als [Standard-Reviewer](https://docs.tale.dev/de/platform/projects/tasks#review-default) des Projekts oder ausdrücklich unter **Reviewer** einer Aufgabe. Eine bereits ausstehende Prüfung überträgst du über die Reviewer-Auswahl der Aufgabe; eine Änderung des Projektstandards allein reicht dafür nicht.
3. Gib dem Reviewer eine eigene Aufgabe und die Anweisung, nur ihm zugewiesene Reviews zu prüfen. Starte diese Aufgabe direkt oder über einen bestehenden [Zeitplan](https://docs.tale.dev/de/platform/automations/triggers#einen-projektagenten-nach-zeitplan-starten). Starte keinen neuen Umsetzungslauf auf der Aufgabe, deren Ergebnis geprüft wird.
4. Verlange, dass der Reviewer die aktuelle Prüfung liest, den tatsächlichen Bericht und die Ergebnisdateien untersucht und konkrete Prüfergebnisse samt Rückmeldung festhält. Die Entscheidung muss sich auf denselben abgeschlossenen Lauf und dieselben Belege beziehen, die er gelesen hat. Ein geändertes Ergebnis muss er erneut lesen und prüfen.

Bei einem gespeicherten Agentenreview listet `task_get.reviewFiles` Anhänge und Ergebnisdateien in Seiten mit jeweils 50 Einträgen. Übergib `reviewFiles.page.continueCursor` als `reviewFileCursor`, um weiterzulesen. Mit `task_review`, `operation: "stage_file"`, dem aktuellen `expected: {approvalId, runId, evidenceRevision}` und einer aufgeführten `fileId` kann der Reviewer eine verfügbare Datei von höchstens 20 MiB in seinen Arbeitsbereich kopieren. Anschließend muss er den zurückgegebenen Pfad öffnen und den Inhalt prüfen: Das Bereitstellen allein belegt keine inhaltliche Prüfung.

Ein `unavailableReason` erklärt, warum eine Datei nicht bereitgestellt werden kann, etwa wegen eines nicht unterstützten Speichers, fehlender oder mehrdeutiger Metadaten, ihrer Größe oder einer geschützten Dokumentzuordnung. Die Zugriffsregeln für Dokumente gelten weiterhin. Bei einer geänderten Quelle oder einem anderen Reviewer ist ein erneutes Lesen nötig. Ändert sich die Berechtigung während der Übertragung, meldet der Vorgang keinen Erfolg. Zuvor berechtigt übertragene Bytes können im Arbeitsbereich bleiben, erlauben aber keine veraltete Entscheidung.

Eine Freigabe verschiebt die geprüfte Aufgabe nach **Erledigt**. Fordert der Reviewer Änderungen an, wird seine Rückmeldung gespeichert und die Aufgabe unter Beibehaltung ihrer Zuweisung nach **Zu erledigen** verschoben. Keine der beiden Entscheidungen startet einen neuen Lauf. Auch eine Agentenerwähnung in dieser Rückmeldung löst keine Arbeit aus: Eine berechtigte Person, ein Manager oder ein Zeitplan muss den nächsten Versuch separat starten. Die Aktivität nennt den Reviewer-Agenten und seine Entscheidung.

Für eine gespeicherte Änderungsanforderung ruft der Manager `task_start_agent` mit `taskId` und `resumeFrom: {kind: "review_repair", approvalId, runId}` auf. Die IDs bezeichnen die abgelehnte Prüfung und den geprüften Umsetzungslauf. Der Server wählt dessen Agenten und übernimmt die gespeicherte Rückmeldung sowie `feedbackCommentId` in den Überarbeitungsauftrag. Zusätzlicher Text in `feedback` muss zusammen mit dieser Rückmeldung und dem vorangestellten Identitätsnachweis in die bestehende Grenze von 10.000 UTF-16-Codeeinheiten passen.

Die Überarbeitung startet nur, solange die Aufgabe **Zu erledigen** ist, demselben Agenten gehört und derselbe abgeschlossene Umsetzungslauf der neueste ist. Eine neuere Prüfung oder eine zwischenzeitliche Änderung an Status, Zuständigkeit oder Archivierung verhindert den Start. Das gilt auch, wenn jemand anschließend den alten Wert wiederherstellt. Bei `stale_repair` ändert sich nichts: Der Manager liest die Aufgabe erneut und verwirft den überholten Auftrag. Er versucht es nie ohne die gekennzeichnete Absicherung. Die Überarbeitung durchläuft den normalen Ablauf und legt nach Abschluss eine neue Prüfung an; `moveToInProgress: false` wird abgelehnt.

Geht die Antwort verloren, darf derselbe Manager-Agent den abgesicherten Aufruf aus einem aktuell berechtigten aktiven Lauf wiederholen, auch bei einer späteren Ausführung. `replayed: true` liefert die ursprüngliche `runId` und `repairReceipt`, behält den ersten auslösenden Lauf bei und startet keine weitere Arbeit. Der Beleg bestätigt einen früheren Start, nicht einen weiterhin aktiven Lauf. Delegationsberechtigung und Projektzugriff werden bei jedem Aufruf erneut geprüft. Für neue Starts gelten weiterhin die Grenzen für gleichzeitig aktive Läufe, beschäftigte Agenten und drei automatisierte Starts je Aufgabe innerhalb einer Stunde. Wiederholte unveränderte Fehler brauchen eine eigene Untersuchungsaufgabe statt unbegrenzter Wiederholungen.

Um eine verlorene Entscheidungsantwort in einer späteren Prüferausführung abzugleichen, liest der Agent `task_get.reviewDecision`. Das Feld enthält den neuesten gültigen nativen Entscheidungsbeleg. Bei einer neueren offenen, menschlichen oder Workflow-Prüfung sowie bei einem nicht verfügbaren Beleg ist es `null`. Vergleiche die Prüfungs- und Lauf-IDs mit dem gespeicherten Auftrag und lies den aktuellen Aufgabenstatus separat. Ein früherer Beleg beschreibt nicht die heutige Spalte; `null` beweist nicht, dass eine Entscheidung ungespeichert blieb. Ein sofortiger identischer `task_review`-Aufruf zur Wiederholung braucht weiterhin denselben aktiven auslösenden Lauf.

Für beide Entscheidungen muss der Reviewer ein anderer Agent sein als der, der das Ergebnis tatsächlich erstellt hat. Er braucht einen aktiven Lauf mit projektweiten Rechten und die weiterhin erteilte Review-Berechtigung; ein von einem Mitglied gestarteter Lauf darf keine Reviews entscheiden. Eine Richtlinie für unabhängige menschliche Prüfung oder erforderliche Kompetenznachweise leitet neue Reviews in die menschliche Prüferkette; ein bereits einem Agenten zugewiesenes Review muss ausdrücklich an eine berechtigte Person übertragen werden. Workflow-Genehmigungen und Fragen an Personen behalten ihre menschlichen Entscheidungsschritte. Lies vor einer Entscheidung `pendingReview.agentReviewBlockedReason`, um aktuelle Probleme mit Quelle, Berechtigung, Identität oder Richtlinie zu erkennen. Gehört GitHub-Arbeit zum Ergebnis, muss der Reviewer den genannten Commit und die Prüfungen selbst kontrollieren: Tale speichert seine Belege, prüft aber weder den aktuellen GitHub-Stand unabhängig noch führt es mit der Review-Entscheidung einen Pull Request zusammen.

## Änderungen anfordern

Beschreibe die nötige Änderung in einem Aufgabenkommentar und **erwähne den zuständigen Agenten mit @**. Die Erwähnung ist eine Anweisung: Ein aktiver Agent kann sie während seines Laufs erhalten. Ein wartender Agent beginnt einen Überarbeitungslauf, der das bisherige Gespräch fortsetzt. Das Ergebnis landet erneut unter **In Prüfung**.

Hast du einen Lauf gestartet, lenken deine Erwähnungen ihn auch dann weiter, wenn die Aufgabe an den Agenten übergegangen ist, etwa weil deine Erwähnung ihm eine Aufgabe übergeben hat, die dir zugewiesen war. Startet die Laufzeit des Agenten neu, um einen Kommentar aufzunehmen, wie es alle Laufzeiten außer Claude Code tun, gehört der Rest des Laufs der Person, die den Kommentar geschrieben hat: Er zählt gegen ihre Limits, und seine Connector-Aufrufe erfolgen in ihrem Namen.

Ein Kommentar ohne Erwähnung hält eine Notiz fest, ohne diese Agentenaktion zu starten. Die Erwähnungsauswahl zeigt an, wenn ein Agent nicht reagieren kann, etwa weil die Aufgabenautomatisierung ausgeschaltet oder pausiert ist oder weil du die Aufgabe zwar kommentieren, aber nicht ändern darfst.

Bei einer Aufgabe mit zuständiger Automatisierung erwähnst du diese Automatisierung für einen weiteren Lauf. Die Erwähnung einer anderen Automatisierung überträgt weder die Zuständigkeit noch startet sie diese. [Automatisierungen](https://docs.tale.dev/de/platform/automations/concepts) erklärt Workflows mit mehreren Schritten.

Eine Aufgabe kann nur einen eingereihten, laufenden oder wartenden Lauf zugleich haben, egal welche Automatisierung ihn gestartet hat. Ein erneuter Start während dieser Zeit verweist auf den vorhandenen Lauf, auch wenn er eine andere Automatisierung nennt. Nach dessen Ende kann ein weiterer Start einen neuen Lauf erzeugen und die Arbeit wiederholen. Prüfe deshalb den aktuellen Lauf und seine Auswirkungen vor einem weiteren Versuch.

## Einen Manager-Agenten die Warteschlange betreuen lassen

Ein Manager-Agent ist ein Projektagent, der laut seinen Anweisungen das ganze Board liest, startbereite Arbeit verteilt und die Routinefragen anderer Agenten beantwortet, damit Personen nur noch sehen, was ihr Eingreifen braucht. Er liest mit **Aufgaben finden** und **Aufgabe lesen**; keines der beiden Tools ändert etwas.

### Die ganze Warteschlange in Durchgängen lesen

**Aufgaben finden** liefert höchstens 50 Aufgaben auf einmal. Solange eine Seite `isDone: false` meldet, bringt ihr `continueCursor`, als `cursor` mit denselben Argumenten zurückgegeben, die nächste Seite; die letzte Seite meldet `isDone: true`. Ein Cursor, der mit anderen Filtern, einer anderen Reihenfolge oder aus dem Lauf eines anderen Projekts zurückkommt, wird abgelehnt, ebenso ein beschädigter: Er wird nie als erste Seite gelesen. Eine Gesamtzahl erscheint nur, wenn eine einzige Seite alle passenden Aufgaben enthält.

Um eine ganze Warteschlange durchzugehen, verwende `order: "created"`. Die Aufgaben kommen dann nach ihrer Erstellung geordnet, die älteste zuerst, und behalten ihren Platz. So nennt ein Durchgang jede Aufgabe höchstens einmal, in dem Zustand, den sie beim Lesen ihrer Seite hat. Die Standardreihenfolge gruppiert die Aufgaben nach Status und behält darin die Reihenfolge der Spalte bei. Eine Aufgabe, die sich bewegt, während der Manager blättert, kann dabei fehlen oder doppelt erscheinen.

Jede aufgeführte Aufgabe enthält `pendingReview: null` oder die gespeicherte `approvalId`, die `runId` des Umsetzungslaufs und den typisierten `reviewer`. Ein Reviewer findet seine Warteschlange mit `status: "in_review"` und seiner Agenten-ID in `reviewerAgentId`. Der Filter gilt für den gespeicherten Review-Empfänger, nicht für den zuständigen Umsetzungsagenten oder den heutigen Projektstandard. Behalte ihn bei jeder Cursor-Anfrage bei. Der Manager liest außerdem alle Aufgaben mit `in_review`, um Reviews gelöschter Agenten zu finden, und prüft anschließend `task_get.pendingReview.agentReviewBlockedReason` für die nötige Korrektur. Agentenreviews bleiben in dieser Aufgabenwarteschlange; die persönliche Review-Liste auf der Startseite ist für menschliche Anfragen.

Ein Durchgang kann länger dauern als ein Lauf. Bevor sein Lauf endet, hält der Manager den Zwischenstand in einem Kommentar auf seiner eigenen Aufgabe fest: den Durchgang, dessen Reihenfolge und Filter, den nächsten `continueCursor` und die zuletzt geprüfte Aufgabe. Sein nächster Lauf findet diesen Kommentar mit **Aufgabe lesen** und macht dort weiter. Ist ein Durchgang zu Ende oder wird sein Cursor abgelehnt, beginnt der nächste auf der ersten Seite. Ein fehlgeschlagener Lesevorgang ist keine leere Warteschlange: Der Manager meldet ihn und hört auf.

### Laufende, beendete und wartende Arbeit unterscheiden

**Aufgabe lesen** nennt Unteraufgaben, Blocker und Kommentare mit ihren IDs und blättert mit `commentCursor` zu älteren Kommentaren zurück. Außerdem listet es die Läufe der Projektagenten auf der Aufgabe, den neuesten zuerst, jeweils mit den ersten 500 Zeichen der Nachricht, die ihr Start mitgab, dazu den Automatisierungslauf der Aufgabe und eine offene Prüfanfrage:

- Ein Lauf mit `live: true` ist eingereiht oder läuft, und bis er endet, startet auf der Aufgabe nichts anderes.
- Ein Lauf, der abgeschlossen, fehlgeschlagen oder abgebrochen ist, ist beendet; `settledAt` nennt den Zeitpunkt.
- `retryPending: true` bedeutet, dass für den neuesten fehlgeschlagenen Lauf noch eine automatische Wiederholung mit verfügbarem Versuchskontingent vorgemerkt ist. Überlass diese Wiederholung Tale. Bei `false` steht für diesen Lauf keine Wiederholung aus; fehlt das Feld auf einer älteren Plattform, ist der Zustand unbekannt. Es nennt weder einen Rücksetzzeitpunkt des Anbieters noch erlaubt es einen Neustart: Lies zuerst Aufgabe, Zuständigkeit, Läufe und Prüfung neu und beachte dann die Wartezeit des Anbieters sowie `retryAfter` einer Startablehnung.
- Ein `workflowRun`, der auf eine Frage (`ask`) oder Genehmigung (`approval`) wartet, wartet auf eine Person. Eine `pendingReview` nennt ihren menschlichen Reviewer oder Reviewer-Agenten. Der Manager überlässt ihm die Entscheidung, sofern er nicht selbst der zugewiesene unabhängige Reviewer mit der nötigen Berechtigung ist.

Transkripte, Fehlertexte und Ergebnisse gehören nicht zur Antwort, ebenso wenig etwas aus einem anderen Projekt.

### Eine Routinefrage beantworten

Eine Routinefrage ist eine Frage, die der Manager aus dem beantworten kann, was das Projekt bereits festhält. Schreib dasselbe Vorgehen in die Anweisungen der arbeitenden Agenten und des Managers:

1. Der arbeitende Agent stellt die Frage als Aufgabenkommentar mit einem festen Fragenschlüssel, seinen Belegen und der Frage. Er nennt in seinem Ergebnis die ID des Kommentars und die ID seines Laufs (**Aufgabe lesen** zeigt diesen Lauf auf seiner Aufgabe als den aktiven) und beendet den Lauf, statt darin zu warten. Erwähnt er den Manager in diesem Kommentar, startet das nichts: Ein Kommentar eines Agenten startet nie einen Agenten.
2. Bei seinem nächsten Durchgang antwortet der Manager nur, solange die Aufgabe noch auf diese Frage wartet: Der fragende Lauf ist der neueste Lauf der Aufgabe und beendet, auf der Aufgabe ist kein Lauf aktiv, und die Aufgabe wartet auf die Prüfung genau dieses Laufs (`pendingReview.runId`). Aus diesem Lesevorgang behält er die ID des Laufs und `pendingReview.approvalId`. Hat jemand die Aufgabe inzwischen weitergebracht, indem sie das Ergebnis angenommen, die Aufgabe abgebrochen oder Änderungen verlangt hat, beantwortet der Manager die Frage nicht mehr, sondern meldet sie.
3. Er schreibt seine Antwort als Kommentar, der die Kommentar-ID der Frage nennt; die Antwort bleibt auf der Aufgabe, was auch immer danach geschieht. Dann setzt er den Agenten mit **Andere Agenten auf Aufgaben starten** fort. Er übergibt `resumeFrom: {runId, approvalId}` mit den beiden IDs, die er behalten hat, dazu eine Nachricht, die mit dem Fragenschlüssel, der ID des Laufs und der Kommentar-ID der Antwort beginnt: **Aufgabe lesen** zeigt später nur die ersten 500 Zeichen der Nachricht eines Starts. Der Start prüft in dem Moment, in dem er geschieht, ob das noch die offene Frage der Aufgabe ist. Nur dann zieht er die offene Prüfanfrage zurück, ohne das Ergebnis anzunehmen, und setzt den Agenten fort.
4. Antwortet der Start mit `stale_question`, wurde die Frage zwischen dem Lesen des Managers und dem Start überholt: Eine Entscheidung liegt vor, es gibt einen neueren Lauf oder eine neuere Prüfanfrage, oder die Zuständigkeit hat sich geändert. Geändert wurde nichts. Der Manager liest die Aufgabe erneut und lässt die überholte Frage fallen. Er startet nicht noch einmal und nie ohne `resumeFrom`.
5. Geht die Rückmeldung des Starts verloren, liest der Manager die Aufgabe erneut, bevor er etwas anderes versucht: Ein neuerer Lauf, dessen Nachricht mit diesem Fragenschlüssel, dieser Lauf-ID und dieser Kommentar-ID der Antwort beginnt, zeigt, dass der Start durchgegangen ist. Wird derselbe Start noch einmal gesendet, antwortet er mit `stale_question` und ändert nichts.

Eine Frage aus einer Daueraufgabe, die ein Zeitplan mit `moveToInProgress: false` startet, wartet auf keine Prüfung. Der Manager schreibt dort nur seine Antwort, und der Lauf beim nächsten Termin des Zeitplans liest sie. Weder der Manager noch sonst jemand startet die Aufgabe vorzeitig, um die Antwort zuzustellen.

Fragen einer Automatisierung und Workflow-Genehmigungen bleiben Sache von Personen. Ein Manager darf ein Review von Projektagentenarbeit nur über den oben beschriebenen unabhängigen Prüfablauf entscheiden, wenn es ihm zugewiesen ist. Das Lesen oder Fortsetzen einer Aufgabe nimmt ihr Ergebnis nicht an.

## Wartende und fehlgeschlagene Läufe behandeln

| Zustand oder Problem | Maßnahme |
| --- | --- |
| Warten auf einen Sandbox-Platz | Die Kapazität der Organisation oder der gemeinsam genutzten Infrastruktur kann ausgeschöpft sein. Warte auf einen Platz oder bitte einen Admin, [Sandboxes](https://docs.tale.dev/de/platform/admin/sandboxes) zu prüfen. |
| Automatischer Wiederholungsversuch | Tale wiederholt einen behebbaren Fehler. Beobachte die Versuchszahl und starte keinen zusätzlichen Lauf. |
| **Der Agent konnte diese Aufgabe nicht fertigstellen** | Es folgt keine automatische Wiederholung. Der Hinweis sagt, was schiefging und wer es beheben kann, und **Details** neben dem Lauf zeigt, was der Lauf selbst gemeldet hat; [Wenn der Agent nicht fertig wird](https://docs.tale.dev/de/platform/projects/task-automation#wenn-der-agent-nicht-fertig-wird) zählt die Fälle auf. Behebe die Ursache und nutze dann **Erneut ausführen**, um das Gespräch fortzusetzen. |
| Neuzuweisung wird verweigert | Brich den aktiven Lauf ab, bevor du neu zuweist. |
| Agenten oder Automatisierungen starten eine Aufgabe immer wieder neu | Eine Aufgabe nimmt innerhalb einer Stunde höchstens drei Starts ihres Agenten durch Automatisierungen und andere Agenten an, gewöhnliche automatische Wiederholungen eingerechnet; die unten beschriebene Ausnahme für die Broker-Wartezeit gilt auch hier. Der nächste Start wird abgelehnt, eine Wiederholung über die Grenze hinaus startet nicht, und die Zeitleiste zeigt **Ausführung abgelehnt: Agenten-Läufe sind auf dieser Aufgabe pausiert**. Starts durch Personen und deren Wiederholungen zählen nie mit. Für Automatisierungsläufe gibt es keine solche Obergrenze: Erwähnen zwei Automatisierungen einander immer wieder, stoppt allein die Ein-Engine-Regel die Schleife. Brich den aktiven Lauf ab und lies die Zeitleiste, bevor eine von beiden wieder starten darf. |
| **Ausführung abgelehnt: Agent arbeitet an einer anderen Aufgabe** | Eine automatische Wiederholung hat zwei Stunden auf ihren Agenten gewartet, der noch an einer anderen Aufgabe arbeitet. Hinter der Ablehnung wartet nichts: Starte die Aufgabe erneut, sobald der Agent frei ist, oder überlass das dem Manager-Agenten oder der Automatisierung, die die Arbeit verteilt. |
| Die Aufgabe lässt sich nicht abschließen | Schließe zuerst ihre offenen Teilaufgaben ab. |

Bei behebbaren Fehlern folgen bis zu drei automatische Wiederholungsversuche, die bis auf die unten beschriebenen Fälle sofort starten. Ein Lauf, der mindestens fünfzehn Minuten Fortschritt macht, erhält ein neues Versuchskontingent. So kann lange Arbeit Unterbrechungen überstehen. Die Richtigkeit des Ergebnisses musst du trotzdem prüfen.

Eine automatische Wiederholung setzt die Arbeit der Person fort, die den Lauf gestartet hat. Sie startet deshalb nur dort, wo diese Person den Lauf jetzt selbst starten könnte: Das Projekt muss noch aktiv sein, und sie muss die Aufgabe weiterhin ändern dürfen. Archiviert ein Admin das Projekt, verlässt die Person die Organisation oder darf sie die Aufgabe nicht mehr ändern, startet keine weitere Wiederholung, und der Lauf bleibt fehlgeschlagen. Das gilt auch für eine Erwähnung, die den Agenten erst nach dem Ende seines Laufs erreicht. Sobald das Projekt wiederhergestellt ist, kann jeder, der die Aufgabe ändern darf, **Erneut ausführen** nutzen.

Ein Agent, der über einen Abo-Broker arbeitet, kann sein Token mitten in der Arbeit verlieren, wenn der Broker das Konto erneuert. Die Wiederholung setzt die Konversation dann mit einem neuen Token fort, ohne den Versuchszähler zu erhöhen: Sie zeigt denselben Stand wie der Lauf, den sie ersetzt. Zeigte dieser keinen oder hatte er mindestens fünfzehn Minuten gearbeitet und damit ein neues Versuchskontingent erhalten, steht dort **Nach einer Token-Erneuerung fortgesetzt**. Nach zwei solchen Unterbrechungen in Folge zählt eine weitere wie jeder andere Fehler.

Ein Lauf kann auch gar nicht erst starten, weil alle Konten seines Abo-Brokers nach Erreichen eines Rate-Limits pausieren. Seine Wiederholung wird dann sofort eingereiht, startet aber erst, sobald das erste Konto wieder verfügbar ist, spätestens eine Minute später. Die Wartezeit verbraucht keinen Versuch, wenn der abgelehnte Lauf unmittelbar auf einen HTTP-429-Fehler desselben Agenten folgt. Diese eine Wartezeit erhöht auch nicht die stündliche Zahl automatisierter Starts der Aufgabe: Der Fehler wegen des Rate-Limits wurde bereits gezählt. Eine weitere Ablehnung wegen der Broker-Wartezeit direkt danach oder eine nach einem anderen Fehler zählt für beide Grenzen.

### Wenn der Agent nicht fertig wird

Scheitert ein Lauf und wiederholt ihn nichts mehr, weil die automatischen Wiederholungen aufgebraucht sind oder eine Wiederholung an der Ursache nichts ändern würde, sagt die Aufgabe das ganz oben: **Der Agent konnte diese Aufgabe nicht fertigstellen**, dazu, was schiefging und wer es beheben kann. **Erneut ausführen** startet den Agenten dort erneut, wenn du die Aufgabe ändern darfst.

| Der Hinweis sagt | Wer handelt |
| --- | --- |
| Ein Nutzungslimit hat den Lauf gestoppt | Ein Admin hebt das Limit an; starte den Agenten danach erneut. |
| Dem Agenten fehlt etwas, das er braucht: sein Modell, einer seiner Skills oder der Agent selbst | Ein Redakteur oder Admin behebt das im Tab **Agenten** des Projekts. |
| Ein Anhang dieser Aufgabe ist nicht mehr im Speicher | Wer die Aufgabe ändern darf, entfernt den Anhang oder lädt ihn erneut hoch; **Details** neben dem Lauf nennt die Datei. Starte den Agenten danach erneut. |
| Der Lauf hat sein Zeitlimit erreicht | Starte den Agenten erneut oder teile die Aufgabe in kleinere auf. |
| Der Lauf hat zu lange auf eine freie Sandbox gewartet | Starte den Agenten erneut, wenn weniger Agenten beschäftigt sind. |
| Das KI-Modell ist ausgefallen, oder der Lauf konnte nicht starten oder wurde unterbrochen | Starte den Agenten erneut. Scheitert er wieder, zeig einem Admin, was der Lauf unter **Details** gemeldet hat. |

Tale benachrichtigt außerdem die Person, die den Lauf gestartet hat, und alle, die die Aufgabe verfolgen: mit der Benachrichtigung **Agenten-Lauf fehlgeschlagen** und, wenn die Organisation ein verbundenes Postfach hat, per E-Mail. Benachrichtigt wird nur, wer das Projekt noch öffnen kann. Startet ein neuer Lauf auf der Aufgabe, gilt die ungelesene Benachrichtigung als gelesen. Unter **Einstellungen > Benachrichtigungen** schaltest du diese Hinweise mit **Agenten-Eskalationen** ab.

## Arbeit, die eine Automatisierung oder ein anderer Agent startet

Ein Projektagent kann auch an die Arbeit gehen, ohne dass jemand auf **Agent starten** klickt: durch eine [geplante Automatisierung](https://docs.tale.dev/de/platform/automations/triggers#einen-projektagenten-nach-zeitplan-starten) oder durch einen anderen Agenten des Projekts, der das Tool **Andere Agenten auf Aufgaben starten** hat, etwa einen Manager-Agenten, der startbereite Arbeit verteilt und Fragen beantwortet. Die Zeitleiste führt einen solchen Lauf als **Automatisierung**, für Inhaber, Admins und Entwickler mit einem Link zum Automatisierungslauf, oder als **delegiert**, gestartet von dem Agenten, der ihn angefordert hat. Der Agent erfährt, wer ihn gestartet hat. Eine mitgegebene Nachricht liest er als Nachricht dieser Automatisierung oder dieses Agenten, nie als Prüfung durch eine Person: Widerspricht sie der Beschreibung oder dem Kommentar einer Person, haben diese Vorrang.

Der Lauf arbeitet im selben Auftrag wie der Lauf, der ihn angefordert hat: im Auftrag der Person, die jenen gestartet hat, oder bei einer Kette, die ein Zeitplan begonnen hat, in niemandes Auftrag; ihre Kosten zählen dann als Automatisierungskosten. Diese Person oder der Zeitplan muss beim Start des Laufs im Projekt handeln dürfen: Verliert die Person die Rolle Redakteur, wird der Zeitplan pausiert oder die Automatisierung aus dem Projekt entfernt, unterbleibt der nächste Start. Ein Agent, den ein anderer Agent gestartet hat, kann keine weiteren Agenten starten, und ein Lauf, den ein Mitglied gestartet hat, kann gar keine starten. Ein solcher Start prüft außerdem, was eine Person übersehen könnte: Eine Aufgabe, die von einer offenen Aufgabe blockiert wird, startet nicht, und ein Agent, der schon an einer anderen Aufgabe arbeitet, wird nicht ein zweites Mal gestartet. Eine automatische Wiederholung eines solchen Laufs hält sich an dieselbe Regel: Solange ihr Agent im selben Arbeitsbereich an einer anderen Aufgabe arbeitet, wartet sie, prüft alle fünf Minuten erneut und startet, sobald der Agent frei ist, ohne einen Versuch zu verbrauchen. Jede Prüfung liest die Aufgabe neu: Wird sie aus **In Bearbeitung** verschoben oder neu zugewiesen, werden sie oder ihr Projekt archiviert oder verliert die Person ihre Rolle, endet das Warten. Ist der Agent zwei Stunden nach dem Fehler noch immer beschäftigt, startet die Wiederholung nicht, und die Zeitleiste zeigt **Ausführung abgelehnt: Agent arbeitet an einer anderen Aufgabe**.

Ein delegierter Lauf legt sein Ergebnis unter **In Prüfung** für den gespeicherten Reviewer ab. Wird die Arbeit an einer dort wartenden Aufgabe wieder aufgenommen, zieht das ihre offene Prüfanfrage zurück, ohne das Ergebnis anzunehmen. Ein Start, der die Karte stehen lässt (`moveToInProgress: false`), wird unter einer Karte, die auf ihre Prüfung wartet, und unter einer erledigten oder abgebrochenen Karte abgelehnt, damit frühere Arbeit nie zur Beurteilung steht, während darunter neue Arbeit läuft. Ein Manager, der die Frage eines Agenten beantwortet, setzt ihn fort und nennt dabei den fragenden Lauf und die Prüfung, auf die er wartet. Die Fortsetzung geschieht nur, solange das noch die offene Frage der Aufgabe ist. Wurde inzwischen entschieden (**Erledigt**, **Abgebrochen** oder eine andere Verschiebung), gibt es einen neueren Lauf oder eine neuere Prüfung oder wurde die Zuständigkeit geändert, antwortet der Agent mit `stale_question`; nichts wird zugewiesen, zurückgezogen, verschoben oder gestartet. Verlangt deine Organisation ein unabhängiges menschliches Review, darf die Person, in deren Auftrag der Lauf arbeitet, sein Ergebnis nicht annehmen.

## Arbeit abbrechen oder pausieren

Mit **Lauf abbrechen** stoppst du den aktiven Agenten. Abbrechen kann den Lauf, wer die Aufgabe ändern darf, und auch die Person, die ihn gestartet hat, selbst wenn die Aufgabe inzwischen beim Agenten liegt. Auch das Verschieben einer laufenden Agentenaufgabe aus **In Bearbeitung** kann den Lauf abbrechen. Lies die Bestätigung vorher. Pro Aufgabe kann nur ein Agentenlauf aktiv sein.

Bei einer Aufgabe mit zuständiger Automatisierung stoppt das Verschieben den Lauf und legt die Aufgabe in einem Schritt dort ab, wohin du sie verschoben hast. Wird die Verschiebung abgelehnt, etwa weil du eine übergeordnete Aufgabe mit noch offenen Teilaufgaben nach **Erledigt** verschiebst, arbeitet der Lauf weiter, und die Aufgabe bleibt in **In Bearbeitung**. **Lauf abbrechen** im Bereich der Automatisierung auf der Aufgabe verschiebt sie nach **Abgebrochen**; offene Teilaufgaben verhindern das ebenso. Willst du den Lauf stoppen und die Aufgabe offen lassen, verschiebe sie stattdessen nach **Zu erledigen**.

Ein Admin kann die Aufgabenautomatisierung für die Organisation ausschalten. Neue Läufe starten dann nicht; bestehende Arbeit endet regulär. Organisationslimits und Budgets gelten weiterhin für jeden Lauf. Siehe [Richtlinien und Limits](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits).

## Die passende Zuständigkeit wählen

Weise einer Person Arbeit zu, die menschliches Urteilsvermögen oder Zugriff außerhalb der Agentenrechte braucht. Nutze einen Projektagenten für eine klar begrenzte Aufgabe mit seinen konfigurierten Dateien und Tools. Eine Automatisierung passt zu festen Abläufen mit mehreren Schritten, Auslösern oder Connector-Freigaben. Mitglieder können nur eine für Aufgaben gebaute Automatisierung wählen, also einen der Einträge unter **Automatisierungen** bei **Zuständig**.

Für den ersten Lauf folge [Deinen ersten Agenten erstellen](https://docs.tale.dev/de/tutorials/editor/first-agent-end-to-end). Halte die Aufgabe so klein, dass du ihr Ergebnis selbst prüfen kannst.

# Aufgaben auf dem Projektboard verwalten
Source: https://docs.tale.dev/de/platform/projects/tasks

Eine Aufgabe hält zusammen, worum es bei einer Arbeit geht: Ziel, Zuständigkeit, Status, Dateien und die Diskussion zum Ergebnis. Nutze das Projektboard sowohl für menschliche Arbeit als auch für Aufgaben, die du einem Agenten überträgst. Wer ein Projekt öffnen kann, kann darin Aufgaben erstellen. [Wer eine Aufgabe ändern darf](https://docs.tale.dev/de/platform/projects/tasks#wer-aufgaben-erstellen-und-aendern-darf), hängt von deiner Rolle ab und davon, ob es deine Aufgabe ist. Das Projekt muss aktiv sein: Ein archiviertes Projekt bleibt schreibgeschützt, bis ein Administrator es wiederherstellt.

<Frame caption="Das Board ordnet Aufgaben nach Status. Unter Liste siehst du dieselben Aufgaben als Zeilen.">

![Das Aufgabenboard des Projekts Website relaunch zeigt Karten in Backlog, Zu erledigen, In Bearbeitung, In Prüfung, Erledigt und Abgebrochen.](https://docs.tale.dev/images/platform/projects-task-board.webp)

</Frame>

## Eine Aufgabe mit klarem Ergebnis erstellen

1. Öffne **Aufgaben** im Projekt und klicke auf **Aufgabe erstellen**.
2. Benenne unter **Titel** das gewünschte Ergebnis, etwa „Launch-Briefing prüfen“.
3. Erkläre in der **Beschreibung**, was benötigt wird und wie das Ergebnis geprüft werden soll. Füge benötigte Dateien als Anhänge hinzu.
4. Wähle bei Bedarf **Status**, **Priorität** und **Zuständig**. Neue Aufgaben starten mit **Zu erledigen**. Für noch nicht beschlossene Vorschläge nutze **Backlog**.
5. Klicke auf **Aufgabe erstellen**. Öffne die neue Karte, um weitere Angaben zu ergänzen. Ist unter **Zuständig** ein Agent eingetragen, legt **Erstellen und Agent starten** die Aufgabe an und startet den Agenten in einem Schritt.

Ein Titel darf bis zu 200 Zeichen lang sein, eine Beschreibung bis zu 20.000; die meisten Emojis zählen doppelt. Eine längere Beschreibung, ob eingefügt oder von einem früheren Import in der Aufgabe hinterlassen, wird nicht gekürzt: Das Feld nennt die Grenze und zählt die Länge, und **Aufgabe erstellen** oder **Speichern** bleibt nicht verfügbar, bis du sie kürzt.

Tale vergibt eine Kennung aus dem Projektkürzel, etwa `WEB-1`. Verwende sie in Verweisen auf die Arbeit, damit ähnlich benannte Aufgaben unterscheidbar bleiben.

Auch ein Gespräch kann eine Aufgabe anstoßen: **Aufgabe erstellen** im Kopf des Chats öffnet denselben Dialog mit deiner Anfrage, den Dateien des Chats und einem Link zurück, und der Chat verfolgt die Aufgabe danach über seinem Nachrichtenfeld. Siehe [Aus einem Chat eine Aufgabe machen](https://docs.tale.dev/de/platform/chat/basics#create-task-from-chat).

Eine Automatisierung, die für Aufgaben gebaut ist, kann in **Aufgabe erstellen** auch eine Vorlage anbieten: Ihr Name steht dann über dem Formular neben **Leere Aufgabe**. Wähle sie, gib den Namen ein, den die Automatisierung verlangt, etwa ein Quartal, und klicke auf **Aufgabe erstellen**; zuständig ist dann die Automatisierung. Gibt es für diesen Namen schon eine Aufgabe, öffnet Tale diese, statt eine zweite anzulegen, und meldet **Für dieses Subjekt existiert bereits eine Aufgabe.** Mitglieder können sie dort lesen und kommentieren, ändern sie aber nur, wenn es ihre eigene ist. Vorlagen, die im Projekt Ordner oder Einstellungsdateien anlegen, stehen nur Redakteuren und höheren Rollen zur Verfügung.

<Tip>

Eine hilfreiche Beschreibung nennt Ausgangsmaterial, gewünschtes Ergebnis und Abschlusskriterium. Zum Beispiel: „Vergleiche den Prüftermin im angehängten Briefing mit den Gesprächsnotizen. Halte Abweichungen in einem Kommentar fest und nenne beide Dateien als Quelle.“

</Tip>

<Frame caption="Die Aufgabendetails stellen Beschreibung, Anhänge, Teilaufgaben und Kommentare neben Zuständigkeit und Status.">

![Die Aufgabe Sign off the launch checklist zeigt den Beschreibungsbereich, Anhänge, Teilaufgaben, Kommentare, Status, Zuständigkeit, Reviewer, Termine, Wiederholung, Labels und Abhängigkeiten.](https://docs.tale.dev/images/platform/project-task-detail.webp)

</Frame>

## Wer Aufgaben erstellen und ändern darf

Wer ein Projekt öffnen kann, kann darin Aufgaben erstellen. Redakteure und höhere Rollen dürfen jede Aufgabe im Projekt ändern. Auf Aufgaben, die sie selbst erstellt haben oder die ihnen zugewiesen sind, können Mitglieder:

- Titel, Beschreibung, Anhänge, Teilaufgaben, Termine, Priorität, Labels und Wiederholung bearbeiten.
- Die Aufgabe sich selbst, einem anderen Mitglied des Projekts, einem seiner Agenten oder einer für Aufgaben gebauten Automatisierung zuweisen.
- Den Agenten starten, lenken oder stoppen, auch mit einer @-Erwähnung in einem Kommentar.
- Den Status ändern und ein Ergebnis annehmen, indem sie die Aufgabe auf **Erledigt** setzen.
- Die Aufgabe archivieren oder wiederherstellen.

Das gilt auch für die Teilaufgaben unter einer solchen Aufgabe, egal wer sie angelegt hat, etwa ein Agent, der die Arbeit aufgeteilt hat. Sie hindern ein Mitglied also nie daran, seine Aufgabe abzuschließen. Um **Reviewer** zu ändern, brauchst du Bearbeitungsrechte für das Projekt, auch auf einer selbst erstellten oder dir zugewiesenen Aufgabe.

Aufgaben anderer können Mitglieder lesen und kommentieren. Erwähnen sie dort einen Agenten, bleibt das eine gewöhnliche Erwähnung, die nichts startet. Eigene Kommentare kann jede Person auf jeder Aufgabe bearbeiten und löschen, die sie lesen darf; Inhaber und Admins können auch Kommentare anderer löschen.

Eine archivierte Aufgabe lässt sich lesen, aber nicht ändern. Bis jemand sie wiederherstellt, kann niemand sie kommentieren, ihre Kommentare bearbeiten oder löschen oder ihre Abhängigkeiten ändern; eine Aufgabe, die sie blockiert, kann sie unter **Blockiert von** trotzdem entfernen. Ein Agentenlauf, der schon an der Aufgabe gearbeitet hat, legt sein Ergebnis dort weiterhin ab.

Gibst du eine Aufgabe, die dir zugewiesen war, an jemand anderen weiter, an eine Person oder einen Agenten, gibst du damit auch das Recht ab, sie zu ändern – es sei denn, du hast sie erstellt. Einen Lauf, den du gestartet hast, behältst du aber in der Hand: Übergibt deine @-Erwähnung die Aufgabe an einen Agenten, kannst du diesen Lauf mit weiteren Erwähnungen lenken und mit **Lauf abbrechen** stoppen, bis er endet.

Eine Abhängigkeit gehört zu der Aufgabe, die durch sie blockiert wird. Mitglieder halten Abhängigkeiten deshalb nur für ihre eigenen Aufgaben fest: unter **Blockiert von** bei einer eigenen Aufgabe oder unter **Blockiert** bei jeder Aufgabe, die sie öffnen können, wobei sie eine eigene Aufgabe als die blockierte wählen. Einstellungen, Agenten, Dateien und der Label-Katalog des Projekts bleiben bei Redakteuren und höheren Rollen; Mitglieder wählen aus den Labels, die das Projekt schon hat. Löschen können nur Inhaber und Admins; alle anderen, die eine Aufgabe ändern dürfen, archivieren sie stattdessen.

Für Automatisierungen gilt eine engere Regel, denn eine Automatisierung handelt in eigenem Namen, mit den Connector-Zugangsdaten der Organisation, und nicht im Namen der Person, die sie startet. Mitglieder können eine Aufgabe nur einer für Aufgaben gebauten Automatisierung übergeben, also einem der Einträge unter **Automatisierungen** bei **Zuständig**, oder der Automatisierung, der die Aufgabe schon gehört. Auch starten oder um Änderungen bitten können Mitglieder nur solche Automatisierungen. Alle anderen bleiben Redakteuren und höheren Rollen vorbehalten.

### Agentenläufe, die ein Mitglied startet

Ein Lauf, den jemand ohne Bearbeitungsrecht für das Projekt startet, etwa ein Mitglied, bleibt bei seiner Aufgabe:

- Seine Plattform-Tools ändern nur diese Aufgabe und die Teilaufgaben darunter: Der Agent legt neue Aufgaben nur als Teilaufgaben dieser Aufgabe an, verwendet nur Labels, die das Projekt schon hat, und kann keine Einträge aus anderen Systemen ins Projekt synchronisieren.
- Er kann keine Dokumente im Projekt speichern. Die Dateien, die er erzeugt, landen trotzdem unter **Ergebnisdateien** an der Aufgabe.
- Der Lauf erhält weder die **Secrets** des Agenten noch das Token eines zugeordneten GitHub-Zugangs. Der Agent erfährt, welche Zugangsdaten zurückgehalten wurden, und soll in seinem Bericht darauf hinweisen, wenn die Arbeit sie braucht; dann muss ein Redakteur oder eine höhere Rolle ihn starten. Die Connectors des Agenten funktionieren weiter und handeln im Namen der Person, die den Lauf gestartet hat.
- Er arbeitet in einem eigenen Arbeitsbereich, der für die Läufe dieser Person mit diesem Agenten bestehen bleibt: Dateien aus Läufen, die Redakteure gestartet haben, liegen dort nicht, und was dieser Lauf hinterlässt, erreicht jene Läufe nie. Spätere Läufe derselben Person mit dem Agenten finden ihn wieder, bis Tale ihn löscht: wenn die Person die Organisation verlässt, wenn der Agent gelöscht wird oder sobald ihn so viele Tage kein Lauf genutzt hat, wie die Organisation unter [**Tage ohne Nutzung**](https://docs.tale.dev/de/platform/admin/sandboxes#delete-unused-workspaces-automatically) festlegt.

Der Lauf kann weiterhin die Aufgaben und das Wissen des Projekts lesen und behält diese Grenzen auch, wenn ein Redakteur ihn später lenkt. Ein Lauf, den ein Redakteur oder eine höhere Rolle startet, hat auf jeder Aufgabe die volle Ausstattung des Agenten. Der Kommentar eines Mitglieds kann das ändern: Startet die Laufzeit des Agenten neu, um den Kommentar aufzunehmen, wie es [alle Laufzeiten außer Claude Code](https://docs.tale.dev/de/platform/agents/harnesses) tun, zählt der Rest des Laufs als Lauf des Mitglieds, mit denselben Grenzen für seine Tools und Zugangsdaten.

## Zuständigkeit und Prüfung festlegen

**Zuständig** bestimmt, wer die Arbeit übernimmt: eine Person, ein Projektagent oder eine im Projekt verfügbare Automatisierung. Unter **Reviewer** wählst du eine Person, einen Projektagenten oder den **Projektstandard** für die Prüfung des Ergebnisses. Diese Auswahl ändern darf nur, wer das Projekt bearbeiten kann. Auch ein menschlicher Reviewer braucht Bearbeitungszugriff. Ein Reviewer-Agent muss zum selben Projekt gehören und ein anderer Agent sein als der, der das Ergebnis erstellt hat.

Einen Agenten zuweisen und seinen Lauf starten sind zwei Entscheidungen. Klicke nach der Zuweisung auf **Agent starten** oder verschiebe die Aufgabe nach **In Bearbeitung**. Lies [Aufgaben automatisieren](https://docs.tale.dev/de/platform/projects/task-automation), bevor du Arbeit mit verbundenen Diensten oder Dateiergebnissen startest.

Hat das Projekt keinen eigenen Agenten, bietet **Zuständig** die Option **Standard-Agent** an, den Agenten der Organisation für solche Projekte. Wählst du sie, richtet Tale den Agenten im Projekt ein und weist ihm die Aufgabe zu; [Der Standard-Agent](https://docs.tale.dev/de/platform/projects/project-agents#standard-agent) erklärt, wie er arbeitet. Redakteure und höhere Rollen können stattdessen **Agent erstellen …** wählen: **Neuer Agent** öffnet sich über der Aufgabe, und der Agent, den du erstellst, wird ihr zugewiesen. Kann der Standard-Agent für sie nicht laufen, etwa weil ein Admin ihn ausgeschaltet hat, erfahren Mitglieder, dass sie einen Redakteur oder Admin bitten können, im Tab **Agenten** des Projekts einen Agenten hinzuzufügen.

<Frame caption="Zuständig bietet in einem Projekt ohne eigene Agenten den Standard-Agenten der Organisation an.">

![Die Liste für Zuständig, bis zum Abschnitt Agenten gescrollt: der Standard-Agent mit der Beschreibung, dass er der Agent der Organisation für Projekte ohne eigene Agenten ist, darunter der Eintrag zum Erstellen eines Agenten und die Fußzeile, dass der Standard-Agent die Aufgaben übernimmt, bis das Projekt eigene Agenten hat.](https://docs.tale.dev/images/platform/project-task-standard-agent.webp)

</Frame>

Ist das Review einer Person zugewiesen, erhält sie die Anfrage, ohne allein über das Ergebnis entscheiden zu dürfen. Auch alle anderen, die die Aufgabe ändern dürfen, können es annehmen: Redakteure und höhere Rollen oder das Mitglied, dem die Aufgabe gehört. Verlangt deine Organisation ein unabhängiges Review, darf die Person, die den geprüften Agentenlauf gestartet hat, sein Ergebnis nicht annehmen; stammt es nicht aus einem Agentenlauf, gilt das für den Ersteller der Aufgabe. Erforderliche menschliche Kompetenzen gelten weiterhin. Ein Review, das einem Agenten zugewiesen ist, braucht dessen Entscheidung oder eine ausdrückliche Übertragung an eine berechtigte Person, bevor ein Mensch es freigeben kann.

Kann die Review-Richtlinie der Organisation nicht gelesen werden oder ist sie ungültig, wird die menschliche Freigabe abgelehnt, auch nach einer Übertragung vom Agenten an eine Person. Ein Organisationsadministrator muss zuerst eine gültige Richtlinienkonfiguration wiederherstellen. Änderungen anzufordern oder ein Review zurückzuziehen funktioniert weiterhin wie bisher.

### Den Standard-Reviewer des Projekts festlegen {#review-default}

Öffne im Tab **Allgemein** den Abschnitt **Aufgabenreviews**, wähle unter **Standard-Reviewer** die gewünschte Option und speichere die Projektänderungen. Anfangs ist **Person** ausgewählt: Zuerst kommt der Aufgabenersteller, dann der Projektersteller zum Zug, sofern die jeweilige Person das Projekt bearbeiten darf. Wähle einen unabhängigen Projektagenten, um ihm neue Reviews zuzuweisen. Das startet den Agenten nicht und erteilt ihm keine Review-Berechtigung; [Einen unabhängigen Reviewer einrichten](https://docs.tale.dev/de/platform/projects/task-automation#agent-review) erklärt die weiteren Schritte.

Aufgaben mit **Projektstandard** übernehmen diese Auswahl, wenn ein neues Review beginnt. Eine ausdrücklich benannte Person oder ein Agent bleibt für die jeweilige Aufgabe ausgewählt. Bereits ausstehende Reviews behalten ihren gespeicherten Reviewer, auch wenn sich der Projektstandard ändert. Hat jemand den Standard während deiner Bearbeitung geändert, verwirf deinen veralteten Entwurf und wähle erneut.

Ein Agent als Standard gilt nur für Ergebnisse aus einem nativen Projektagentenlauf, wenn die Organisation weder eine unabhängige menschliche Prüfung noch Kompetenznachweise verlangt. Reicht eine Person oder Automation Arbeit ohne einen solchen Lauf ein, greift die menschliche Prüferkette. Zum Speichern einer Agentenauswahl braucht der Agent die Review-Berechtigung; eine Aufgabe kann nicht ihren ausführenden Agenten als Reviewer wählen. Ein bereits ausstehendes Review wechselt bei einer geänderten Berechtigung, Zuweisung oder Richtlinie nicht automatisch den Reviewer.

### Ein ausstehendes Review übertragen {#transfer-review}

Öffne die Aufgabe und lies **Aktuelles Review** unter **Reviewer**. Dort steht, wer die ausstehende Prüfung übernommen hat; das kann vom aktuellen Projektstandard abweichen. Wählst du einen anderen Reviewer, überträgst du auch dieses Review, ohne die Zuständigkeit für die Arbeit zu ändern oder einen Lauf zu starten. Mit **Projektstandard** überträgst du es an die aktuelle Standardauswahl des Projekts. Haben sich Reviewer oder Ergebnis seit dem Laden geändert, wird die Übertragung abgelehnt. Prüfe den aktualisierten Stand, bevor du erneut wählst.

Ein Agent darf nur ein abgeschlossenes Ergebnis eines anderen Projektagenten prüfen. Weist du die Aufgabe jemand anderem zu, bleibt der ursprüngliche Agent als Ersteller des Ergebnisses vermerkt; die ausstehende Entscheidung des prüfenden Agenten ist jedoch blockiert. Soll die neue Zuweisung bestehen bleiben, übertrage die Prüfung dieses Ergebnisses ausdrücklich an eine berechtigte Person. Die Prüfrichtlinie der Organisation gilt weiterhin.

Ein laufender Prozess oder eine offene Frage kann die Übertragung an einen Agenten verhindern. Gibt es keinen unterstützten abgeschlossenen Agentenlauf oder verlangt die Richtlinie eine unabhängige menschliche Prüfung oder Kompetenznachweise, wähle eine berechtigte Person. Ist ein Agent nicht verfügbar oder fehlt ihm die Review-Berechtigung, zeigt die Aufgabe den Grund an; die Prüfung geht nicht stillschweigend an dich zurück.

Das aktuelle Review erklärt auch eine unzulässige Selbstprüfung, eine geänderte Zuweisung der Umsetzung und eine nicht lesbare Richtlinie. Behebe die angezeigte Ursache oder übertrage die Prüfung ausdrücklich; das Ergebnis des Laufs bleibt aufgezeichnet. Eine wiederholte Aufgabe behält einen ausdrücklich gewählten Agenten auch dann als Reviewer, wenn er gelöscht wurde oder seine Berechtigung verloren hat. Korrigiere diese Auswahl, statt unbemerkt einen anderen Reviewer zu übernehmen.

## Fortschritt mit dem Status zeigen

Ändere den **Status** in den Aufgabendetails oder ziehe die Karte auf dem **Board** in eine andere Spalte. Die Statusauswahl lässt sich auch mit der Tastatur bedienen.

| Status | Bedeutung |
| --- | --- |
| **Backlog** | Vorgeschlagene Arbeit, die noch nicht beschlossen ist. |
| **Zu erledigen** | Arbeit, die begonnen werden kann. |
| **In Bearbeitung** | Die Arbeit läuft. Bei einer Agentenaufgabe startet der Wechsel hierhin den Lauf. |
| **In Prüfung** | Ein Ergebnis wartet auf seinen menschlichen Reviewer oder Reviewer-Agenten. |
| **Erledigt** | Die abgeschlossene Arbeit wurde angenommen. |
| **Abgebrochen** | Die Arbeit wird nicht weitergeführt. |

Bei Agentenaufgaben kann ein Statuswechsel die Ausführung starten oder abbrechen. Lies deshalb den Aktionshinweis vor dem Verschieben. Ein Agent liefert sein Ergebnis unter **In Prüfung** ab; auf **Erledigt** darf er es nicht selbst setzen.

## Entscheidungen an der Aufgabe festhalten

Öffne die Aufgabe, um Beschreibung, Anhänge, Termine, Labels, Teilaufgaben oder Kommentare zu ergänzen. Halte Fragen, Entscheidungen und Rückmeldungen in Kommentaren fest, die spätere Prüfer nachvollziehen können.

Mit `@` im Kommentarfeld öffnest du die Erwähnungsauswahl. Eine Erwähnung des zuständigen Agenten ist eine Anweisung: Sie kann einen laufenden Agenten steuern oder einen neuen Lauf auslösen, wenn er gerade nicht arbeitet. Ein Kommentar ohne Erwähnung hält die Diskussion fest, ohne diese Agentenaktion anzufordern.

Erwähnungen in der Beschreibung der Aufgabe wirken beim Speichern genauso: Die genannten Personen werden benachrichtigt, und ein genannter Agent wird gesteuert oder startet einen Lauf, wie oben beschrieben. Startet er einen Lauf, wechselt die Aufgabe nach **In Bearbeitung**, egal in welcher Spalte du sie angelegt hast. Bearbeitest du die Beschreibung später, zählen nur die Erwähnungen, die du hinzufügst. Formulierst du den Text um eine bestehende Erwähnung herum um, wird niemand erneut benachrichtigt. Der Agent liest die Beschreibung so, wie sie beim Start seines Laufs lautet. Änderst du sie, solange der Lauf noch wartet, arbeitet er also mit deiner neuen Fassung.

Nutze **Teilaufgaben** für Ergebnisse, die sich einzeln prüfen lassen. Eine Teilaufgabe nennt oben in ihren Details die übergeordnete Aufgabe (**Teil von …**); klicke darauf, um zu ihr zurückzukehren. Solange noch eine Teilaufgabe offen ist, lässt sich die übergeordnete Aufgabe nicht nach **Erledigt** oder **Abgebrochen** verschieben. Alle anderen Status bleiben verfügbar, auch **Zu erledigen**. Unter **Abhängigkeiten** siehst du, welche Aufgaben diese Aufgabe blockieren und welche sie selbst blockiert. Kreisförmige Abhängigkeiten sind nicht zulässig.

Änderst du ein Feld, zeigt die **Aktivität** der Aufgabe seinen Wert davor und danach. Leerst du ein Feld, steht dort, was übrig bleibt, etwa **Kein Fälligkeitsdatum** oder **Nicht zugewiesen**, und nicht bloß der alte Wert. Titel, Beschreibungen, Labels und Dateinamen erscheinen genau so, wie sie geschrieben wurden, auch wenn der Text einem Statusnamen wie `done` entspricht. Status, Prioritäten, Datumsangaben und die Angaben für ein leeres Feld erscheinen in deiner Sprache.

## Wiederkehrende Aufgaben einrichten

Kommt dieselbe Arbeit regelmäßig wieder, etwa ein wöchentlicher Statusbericht, gib der Aufgabe eine Wiederholung. Jedes Mal, wenn du sie abschließt, steht die nächste Aufgabe in **Zu erledigen** bereit, fällig am nächsten Tag, den die Wiederholung vorsieht.

Klicke in den Details der Aufgabe oder im Dialog **Aufgabe erstellen** auf **Wiederholen** direkt unter **Fällig am** und wähle, wie sich die Aufgabe wiederholt. Deine Wahl wird gespeichert, sobald du sie anklickst:

- **Nie**
- **Täglich**
- **Jeden Werktag**, von Montag bis Freitag
- **Wöchentlich am …**, **Monatlich am …** oder **Jährlich am …**: Sie richten sich nach dem Tag des Fälligkeitsdatums. Hat die Aufgabe keines, zählt ihr Startdatum, wenn es noch bevorsteht, sonst der heutige Tag.

<Frame caption="Wähle die Wiederholung in den Aufgabendetails; die Vorschau zeigt die nächsten Fälligkeiten.">

![Das Menü Repeat der Aufgabe Sign off the launch checklist listet Never, Daily, Every weekday, nach dem Fälligkeitsdatum benannte wöchentliche, monatliche und jährliche Optionen, von denen die wöchentliche ausgewählt ist, und Custom, darunter die nächsten Fälligkeiten und die Option, die nächste Aufgabe am Fälligkeitstag zu erstellen.](https://docs.tale.dev/images/platform/project-task-repeat.webp)

</Frame>

**Nächste Fälligkeiten** zeigt, wann die nächsten drei Aufgaben fällig werden. Hat die Aufgabe noch kein Fälligkeitsdatum, bekommt sie eines, sobald du eine Wiederholung wählst: den ersten passenden Tag ab heute oder ab ihrem Startdatum, wenn dieses später liegt. Eine monatliche Wiederholung am 31. fällt in kürzeren Monaten auf den letzten Tag des Monats. Entfernst du das Fälligkeitsdatum einer Aufgabe, die sich schon wiederholt, bleibt die Wiederholung bestehen: Die nächste Aufgabe entsteht dann, wenn du diese abschließt, fällig am ersten passenden Tag danach, und **Wiederholen** weist beim Öffnen darauf hin. Jede Änderung an der Wiederholung gibt der Aufgabe wieder ein Fälligkeitsdatum.

Liegen die Termine außerhalb des unterstützten Datumsbereichs, weist die Vorschau darauf hin. Wähle ein früheres Start- oder Fälligkeitsdatum, bevor du die Wiederholung festlegst.

### Eine eigene Wiederholung festlegen

Für jeden anderen Rhythmus wählst du in derselben Liste **Benutzerdefiniert**. Wähle **Tag**, **Woche**, **Monat** oder **Jahr**, lege fest, wie oft die Aufgabe wiederkommt, und wähle die Wochentage, den Tag im Monat oder das Datum, etwa alle 2 Wochen am Dienstag und Donnerstag. **Nächste Fälligkeiten** passt sich jeder Änderung an. Mit **Speichern** übernimmst du die Wiederholung. **Abbrechen**, **Escape** oder ein Klick außerhalb der Liste verwerfen deine Änderungen; der Pfeil zurück führt zur Liste und behält sie bei.

### Die nächste Aufgabe am Fälligkeitstag erstellen

Normalerweise entsteht die nächste Aufgabe, sobald du diese auf **Erledigt** oder **Abgebrochen** setzt. Soll die Arbeit pünktlich wiederkommen, auch wenn die letzte Runde noch nicht fertig ist, öffne **Wiederholen** bei einer wiederkehrenden Aufgabe, wähle unter den Terminen **Nächste Aufgabe am Fälligkeitstag erstellen** und klicke auf **Speichern**. Die nächste Aufgabe entsteht dann zu Beginn des Fälligkeitstags, um Mitternacht in der Zeitzone der Person, die die Wiederholung eingerichtet hat, auch wenn diese Aufgabe noch offen ist. Ist die Aufgabe schon fällig, erscheint die nächste innerhalb weniger Minuten, und schließt du die Aufgabe vor ihrem Fälligkeitstag ab, entsteht die nächste sofort. In der Aktivität der Aufgabe steht **System** als Urheber. **Wiederholen** zeigt dann ein Kalendersymbol, und der Tooltip des Wiederholungssymbols auf dem **Board** und in der **Liste** endet mit **nächste Aufgabe am Fälligkeitstag**.

Offene Aufgaben halten eine solche Serie nicht mehr auf, deshalb können sie sich stapeln, wenn niemand sie abschließt. Eine Serie hat nie mehr als 10 offene Aufgaben: Die nächste wartet, bis jemand eine davon abschließt. Änderst du die Wiederholung oder wählst erst **Nie** und dann wieder eine Wiederholung, zählen die noch offenen Aufgaben der Serie weiterhin mit.

### Was die nächste Aufgabe mitbringt

Die nächste Aufgabe hat eine eigene Kennung und beginnt in **Zu erledigen**. Sie übernimmt Titel, Beschreibung, Priorität, Labels, Anhänge, Zuständigkeit, Reviewer, die Personen, die die Aufgabe verfolgen, und die Wiederholung. Ihre Teilaufgaben kommen mit, jede wieder in **Zu erledigen** und mit Terminen, die um denselben Schritt verschoben sind, samt den Abhängigkeiten zwischen ihnen. Kommentare, Abhängigkeiten zu anderen Aufgaben, archivierte Teilaufgaben und die Dateien, die ein Agent erzeugt hat, bleiben bei der vorherigen Aufgabe. Personen kommen nur mit, solange sie noch Zugriff haben: die Zuständigkeit, solange sie noch so vergeben werden kann, der Reviewer, solange er das Projekt noch bearbeiten darf, und wer die Aufgabe verfolgt, solange er das Projekt noch sehen kann. Wer die Aufgabe nicht mehr verfolgt, verfolgt auch die nächste nicht, selbst wenn er sie erstellt hat.

Die nächste Aufgabe ist am ersten passenden Tag nach dem Fälligkeitsdatum der vorherigen fällig, und ein Startdatum liegt wieder gleich viele Tage davor. Dieses Fälligkeitsdatum liegt nie in der Vergangenheit: Schließt du eine Aufgabe verspätet ab, ist die nächste heute oder am nächsten passenden Tag fällig. So sammeln sich für verpasste Termine keine überfälligen Aufgaben an.

Unter **Wiederholen** verweist die vorherige Aufgabe auf die nächste, etwa mit **Nächste Aufgabe: WEB-13**. Öffnest du die vorherige Aufgabe wieder und schließt sie erneut ab, entsteht keine zweite. Auf dem **Board** und in der **Liste** kennzeichnet ein Wiederholungssymbol die Aufgabe, die die Serie gerade weiterführt; sein Tooltip nennt die Wiederholung.

### Eine Serie beenden

Schließt du eine wiederkehrende Aufgabe ab, nennt die Meldung **Nächste Aufgabe erstellt** das Fälligkeitsdatum der nächsten und bietet **Wiederholung beenden** an. Dieselbe Schaltfläche bleibt bei der Aufgabe, die die nächste erstellt hat, unter **Wiederholen** neben **Nächste Aufgabe**, solange sich die nächste Aufgabe noch wiederholt. Hat noch niemand die nächste Aufgabe angefasst (sie steht unverändert in **Zu erledigen**, ohne Kommentare und ohne Agentenlauf), wird sie samt ihren Teilaufgaben entfernt. Andernfalls bleibt sie bestehen und wiederholt sich nicht mehr. In beiden Fällen endet die Serie: Bei der Aufgabe, von der aus du sie beendet hast, zeigt **Wiederholen** dann **Nie**, und der Tooltip lautet **Die Serie wurde beendet.** Hast du die Schaltfläche unter **Wiederholen** verwendet, springt der Fokus danach auf **Wiederholen**. Du kannst auch bei der neuesten Aufgabe der Serie **Wiederholen** auf **Nie** stellen.

**Wiederholung beenden** wirkt nur auf Aufgaben, die du ändern darfst: auf die, bei der du es verwendest, und auf die späteren Aufgaben der Serie, die du ebenfalls ändern darfst. Frühere Aufgaben zeigen ihre Wiederholung weiterhin an. Gehört eine spätere Aufgabe inzwischen jemand anderem, etwa weil sie neu zugewiesen wurde, behält sie ihre Wiederholung, und die Serie geht von ihr aus weiter; eine nächste Aufgabe wird dann nicht entfernt.

Löschst du die neueste Aufgabe einer Serie, endet die Serie. Die Aufgabe davor erstellt keine weitere, auch wenn du sie wieder öffnest und erneut abschließt: Sie zeigt kein Wiederholungssymbol, und ihr Feld **Wiederholen** bleibt gesperrt, mit dem Tooltip **Die nächste Aufgabe wurde gelöscht. Diese Aufgabe kann sich nicht noch einmal wiederholen.** Löschst du eine frühere Aufgabe, geht die Serie bei der neuesten weiter.

### Wenn sich die Wiederholung nicht ändern lässt

Zeige auf **Wiederholen** oder setze den Tastaturfokus darauf, um zu lesen, warum das Feld gesperrt ist:

- Hat eine Aufgabe ihre nächste Aufgabe schon erstellt, führt diese die Serie weiter, und die Aufgabe selbst wiederholt sich nicht mehr, auch wenn du sie wieder öffnest. Solange die Serie weitergeht, änderst du die Wiederholung bei der nächsten Aufgabe; **Nächste Aufgabe** öffnet sie. Wurde die Serie beendet oder die nächste Aufgabe gelöscht, zeigt **Wiederholen** das an.
- Jede andere Aufgabe in **Erledigt** oder **Abgebrochen** behält die Wiederholung, mit der sie abgeschlossen wurde. Öffne sie wieder, um die Wiederholung zu ändern.
- Eine Teilaufgabe hat keine eigene Wiederholung. Solange sich die übergeordnete Aufgabe wiederholt, steht bei **Wiederholen** zum Beispiel **Mit WEB-3**, und jede nächste Aufgabe der übergeordneten bringt eine neue Kopie der Teilaufgabe mit. Eine archivierte Teilaufgabe hat kein Feld **Wiederholen**: Sie kommt nicht wieder. Folgt eine Arbeit ihrem eigenen Rhythmus, braucht sie eine eigene Aufgabe.
- Eine Aufgabe, die einer Automatisierung gehört, wiederholt sich nicht. Weist du eine wiederkehrende Aufgabe einer Automatisierung zu, endet ihre Serie.
- Im Dialog **Aufgabe erstellen** zeigt das Feld **Wiederholen** den Wert **Nie**, solange **Status** auf **Erledigt** oder **Abgebrochen** steht oder eine Automatisierung zuständig ist.

## Das Ergebnis vor dem Abschluss prüfen

Vergleiche bei menschlicher Arbeit das Ergebnis mit dem Abschlusskriterium in der Beschreibung. Lies bei Agentenarbeit den Bericht in den Kommentaren und prüfe die erzeugten Dateien. Ein beendeter Lauf zeigt, dass der Agent nicht mehr arbeitet. Ob das Ergebnis angenommen wurde, siehst du an der erfassten Review-Entscheidung.

Setze die Aufgabe auf **Erledigt**, sobald sie die Anforderung erfüllt. Soll ein Agent nacharbeiten, beschreibe die nötige Änderung in einem Kommentar und erwähne ihn darin. [Aufgaben automatisieren](https://docs.tale.dev/de/platform/projects/task-automation) erklärt Wiederholungen, Nacharbeit und Abbruch.

## Deine Aufgaben aus Start öffnen

[Start](https://docs.tale.dev/de/platform#home) listet die offenen Aufgaben, die dir zugewiesen sind oder auf dein Review warten, aus allen Projekten, die du lesen darfst; **Aufgaben** über der Liste zeigt nur sie. Öffnest du dort eine Aufgabe, erscheint sie als eigene Seite neben der Seitenleiste von **Start** und nicht im Dialog des Boards:

- Oben steht der Auftrag als Karte: Beschreibung, Anhänge und Teilaufgaben.
- Darunter folgt die Diskussion wie ein Gespräch, mit den ältesten Einträgen zuerst und nach Tagen gegliedert. Sie verbindet die Kommentare mit dem Verlauf der Aufgabe, etwa Statuswechseln, Zuweisungen und Agentenläufen.
- Das Kommentarfeld steht ganz unten. Zum Senden drückst du **⌘+Enter** oder **Ctrl+Enter** oder klickst auf die runde Senden-Schaltfläche; **Enter** allein beginnt eine neue Zeile. Mit `@` erwähnst du einen Agenten oder eine Person, mit derselben Wirkung wie im Dialog des Boards. Was du noch nicht gesendet hast, bleibt für diese Aufgabe im Feld stehen, hier wie im Dialog des Boards. Solange du woanders arbeitest, zeigt die Zeile der Aufgabe in **Start** den Hinweis **Entwurf**.
- **Details** neben der Diskussion enthält Status, Priorität, Zuständigkeit, Reviewer, Termine, Wiederholung, Labels und Abhängigkeiten, dazu **Verfolgen** und **Archivieren**. Inhaber und Administratoren der Organisation finden dort zusätzlich **Löschen**: Es entfernt die Aufgabe samt Teilaufgaben, Kommentaren und Dateien endgültig und stoppt ihre laufenden Agentenläufe. **Details ausblenden** am Ende der Kopfzeile blendet diesen Bereich aus, **Details einblenden** holt ihn zurück. Ist das Fenster zu schmal für beides nebeneinander, öffnet **Details einblenden** die Details stattdessen in einem Fenster über der Diskussion — von der Seite oder, auf dem Smartphone, vom unteren Bildschirmrand.

**Board** in der Kopfzeile öffnet das Aufgaben-Board des Projekts. Öffnest du eine Aufgabe dort, erscheint sie weiterhin im Dialog des Boards; beide Ansichten bearbeiten dieselbe Aufgabe. **Link kopieren**, das Link-Symbol neben **Board**, kopiert den Link zu dieser Aufgabenseite. Die Kennung der Aufgabe, etwa `WEB-2`, kopierst du mit einem Klick darauf in der Zeile unter dem Titel. Eine kurze Meldung bestätigt jede Kopie.

## Aufgaben finden, die Aufmerksamkeit brauchen

Grenze das Board mit **Filter** ein oder wechsle zur **Liste**, um Zeilen zu überfliegen. Lass Vorschläge im [Backlog](https://docs.tale.dev/de/platform/projects/backlog), bis sie begonnen werden sollen. Nutze Labels für Unterscheidungen, die keinen eigenen Status brauchen.

**Tasks durchsuchen** grenzt das Board zusammen mit **Filter** ein. Jede Aufgabe, die zu beidem passt, erscheint, egal wie viele es sind. Die Suche findet Aufgaben, deren Titel, Beschreibung oder Kennung, etwa `WEB-12`, jedes eingegebene Wort enthält, und Aufgaben mit einem Kommentar, der alle diese Wörter enthält. Das Board fasst bis zu 2.000 Aufgaben. In einem größeren Projekt sagt ein Hinweis, dass nur die ersten 2.000 angezeigt werden; über die Suche erreichst du die übrigen.

Können die Aufgaben nicht geladen werden, sagt das Board das, statt leere Spalten zu zeigen, und deine Suche und deine Filter bleiben, wie sie sind. Wähle **Erneut versuchen**, um sie zu laden. Schlägt eine Aktualisierung fehl, bleiben die angezeigten Aufgaben stehen, und ein Hinweis sagt, dass sie dem zuletzt geladenen Stand entsprechen. Ein Hinweis erscheint auch, wenn die Abhängigkeiten oder die Aktivität der Agenten und Reviews nicht geladen werden können, denn dann sind blockierte Aufgaben, laufende Agenten, offene Fragen und ausstehende Reviews möglicherweise nicht markiert. **Erneut versuchen** in einem Hinweis lädt nur, was fehlgeschlagen ist.

Mit der Tastatur drückst du **Enter** auf **Filter**: Das Panel öffnet sich beim ersten Filter, **Zuständig**. Mit **Enter** klappst du ihn auf, mit **Tab** erreichst du seine Optionen. Die Pfeiltasten wählen eine aus, und das Board folgt sofort. Die **Leertaste** wählt die Option, auf der der Fokus steht, und hebt die Auswahl auf, wenn sie schon gewählt ist. **Tab** führt zum nächsten Filter, und **Escape** schließt das Panel.

In den Ansichten **Board** und **Liste** erreichst du den Aufgabentitel mit **Tab**. Drücke dann **Enter**, um die Aufgabe zu öffnen.

Kannst du die Aufgabe bearbeiten, drückst du auf ihrem Titel die **Leertaste**, um sie aufzunehmen. Verschiebe sie mit den Pfeiltasten und lege sie mit der **Leertaste** wieder ab. **Escape** bricht das Verschieben ab und lässt die Aufgabe, wo sie war. Ein Screenreader nennt die Aufgabe beim Aufnehmen und sagt beim Verschieben ihren Status und ihre Position an.

Prüfe bei einer abgelehnten Änderung zuerst den Zustand der Aufgabe: Ein aktiver Agentenlauf verhindert die Neuzuweisung, offene Teilaufgaben verhindern den Abschluss, und deine Rolle und ob es deine Aufgabe ist, entscheiden darüber, ob du sie überhaupt ändern darfst.

# Skill-Bibliothek
Source: https://docs.tale.dev/de/platform/workspace/skills

Ein Skill beschreibt eine wiederkehrende Arbeitsweise: Release Notes schreiben, ein Briefing prüfen oder ein Dokument nach euren Vorgaben erstellen. Er enthält eine Anweisungsdatei `SKILL.md` und bei Bedarf ergänzende Dateien. Pflege ihn unter **Einstellungen > Skills** an einer Stelle und [statte die passenden Agenten damit aus](https://docs.tale.dev/de/platform/agents/skills).

Skills wirken dort, wo ein Agent die Arbeit erledigt: bei einem [Projekt-Agenten](https://docs.tale.dev/de/platform/projects/project-agents), der eine [Aufgabe](https://docs.tale.dev/de/platform/projects/tasks) bearbeitet, oder bei einem Agent-Knoten in einer [Automatisierung](https://docs.tale.dev/de/platform/automations/concepts). Der Chat beantwortet Fragen und durchsucht euer Wissen; er nutzt keine Skills, führt keinen Code aus und erstellt keine Dateien. Soll ein Dokument mit einem Skill entstehen, weise die Aufgabe einem Agenten zu, der damit ausgerüstet ist. Die Aufgabe kann jeder anlegen, der das Projekt öffnen kann; einen Agenten mit dem Skill auszurüsten, erfordert mindestens die Rolle Redakteur.

Jedes Mitglied kann einen Skill erstellen und seine eigenen bearbeiten. Zum Bearbeiten oder Löschen eines geteilten Skills einer anderen Person brauchst du die Rechte eines Organisationsadministrators. Deine Organisation kann das Teilen mit allen bestimmten Rollen vorbehalten; siehe [Wer mit allen teilen darf](https://docs.tale.dev/de/platform/workspace/skills#who-can-share-with-everyone).

## Einen kleinen Skill erstellen

<Steps>

<Step title="Den Skill benennen und seinen Einsatz erklären">

Öffne **Einstellungen > Skills**, dann **Skill hinzufügen > Leerer Skill**. Gib unter **Name** einen Namen wie `brief-summary` und eine **Beschreibung** ein:

```text
Fasse ein Projektbriefing in Prüftermin, Zuständigkeit und offenen Fragen
zusammen. Nutze den Skill für eine Übergabe oder eine kurze Briefing-Prüfung.
```

Der Name ist eine eindeutige Kurzkennung: Kleinbuchstaben, Ziffern und einzelne Bindestriche, höchstens 64 Zeichen. An der Beschreibung erkennt das Modell, wann der Skill passt. Wähle unter **Sichtbarkeit**, wer den Skill sieht: **Organisation** oder **Teams** mit mindestens einem Team. Klicke auf **Erstellen**, um ihn anzulegen und den Editor zu öffnen.

</Step>

<Step title="Die Anweisungen schreiben">

Beschreibe unter **Anweisungen (Body)** einen kurzen Ablauf und ein überprüfbares Ergebnis. Zum Beispiel:

```markdown
Lies das bereitgestellte Briefing. Erstelle eine Tabelle mit drei Zeilen:
Prüftermin, Zuständigkeit und offene Fragen. Zitiere zu jeder Antwort den
belegenden Satz. Schreibe „Nicht angegeben“, wenn eine Information fehlt.
Leite aus einem Prüftermin keinen Veröffentlichungstermin ab.
```

Ergänze Referenzdateien nur, wenn sie für den Ablauf hilfreich sind. Lege ausführliche Beispiele dort ab und erkläre, wann der Agent sie lesen soll.

</Step>

<Step title="Die Zielgruppe wählen und speichern">

Beim Erstellen ist **Organisation** vorausgewählt, sofern deine Organisation das nicht vorbehält. Ist der Inhalt für einen anderen Kreis bestimmt, ändere das unter **Sichtbarkeit**: **Teams** braucht mindestens ein Team. Ein Icon oder Labels können das Wiederfinden erleichtern. Klicke anschließend auf **Speichern**.

Ein neuer Skill wird keinem Agenten automatisch zugeordnet. Öffne den Agenten des gewünschten Projekts und wähle den Skill in seiner Ausstattung. Starte eine kleine Aufgabe mit bekannten Eingaben und prüfe, ob das Ergebnis den Anweisungen entspricht.

</Step>

</Steps>

<Frame caption="Der Skill-Editor nennt, wer den Skill erstellt hat, und vereint Bundle-Dateien, Beschreibung, Labels und Sichtbarkeit. Darunter beginnen die Anweisungen.">

![Der Editor des Skills docx zeigt den Dateibaum neben Erstellt von Mitgeliefert, Beschreibung, Icon, Labels, die Sichtbarkeit Organisation und die Überschrift Anweisungen.](https://docs.tale.dev/images/platform/skill-library-detail.webp)

</Frame>

## Ein vorhandenes Bundle importieren

Nutze **Skill hinzufügen > Zip hochladen** oder **Ordner hochladen**. Im Stammverzeichnis muss `SKILL.md` liegen. Referenzen, Vorlagen und Skripte dürfen mitgeliefert werden:

```text
brief-summary/
├── SKILL.md
└── references/
    └── example-brief.md
```

Die Vorschau zeigt Metadaten, Freigabe, Lizenz und Dateiliste, bevor **Bundle hochladen** etwas speichert. Prüfe Inhalt und Zielgruppe. Fehlt `visibility`, wird der Skill organisationsweit geteilt. Behält deine Organisation das vor und darfst du nicht veröffentlichen, weist die Vorschau darauf hin und **Bundle hochladen** bleibt gesperrt; ergänze in der `SKILL.md` `visibility: team` und die IDs deiner Teams. Wenn du einen Team-Skill anlegst oder seine Teams änderst, darfst du nur Teams deiner Organisation angeben, ohne Administratorrechte nur deine eigenen. Eine bestehende Teamliste darf unverändert bleiben, auch wenn ein Team inzwischen gelöscht wurde. Ein `owner` in der Datei wird ignoriert: Ein neuer Skill gehört dir. Ein ersetzter behält seinen bisherigen Eigentümer; hatte er keinen, gehört er danach dir. Existiert der Name schon, fragt Tale nach dem Ersetzen. Das betrifft auch Agenten, die diesen Skill verwenden.

<Warning>

Der Import startet keine Aufgabe und führt keine Dateien aus. Sobald du den Skill zuordnest, leiten seine Anweisungen aber einen Coding-Agenten an, der Tools, Zugangsdaten und eine Shell nutzen kann. Prüfe fremde Anweisungen und Skripte vor der Verwendung. Ein Skill bildet keine zusätzliche Berechtigungsgrenze.

</Warning>

## Die Freigabe verstehen

| Sichtbarkeit | Wer ihn lesen kann | Welche Projektagenten ihn nutzen können |
| --- | --- | --- |
| **Organisation** | Alle Mitglieder der Organisation | Agenten aller Projekte |
| **Teams** | Mitglieder der ausgewählten Teams | Agenten in Projekten mit einem passenden Team |

Der Projektzugriff bestimmt die verfügbare Ausstattung, auch wenn du persönlich mehr Skills lesen kannst. Ein organisationsweites Projekt kann organisationsweite Skills nutzen. Ältere private Skills bleiben für ihren Inhaber sichtbar, lassen sich aber keinem Agenten zuordnen. Neue private Skills werden nicht angenommen.

Eine Einschränkung der Sichtbarkeit verlangt eine Bestätigung, weil Agenten dadurch Zugriff verlieren können. Das Löschen hat dieselbe praktische Folge: Ein Lauf, der das fehlende Bundle benötigt, kann es nicht bereitstellen. Prüfe die Verwendung eines geteilten Skills, bevor du ihn einschränkst oder entfernst.

### Wer mit allen teilen darf {#who-can-share-with-everyone}

Standardmäßig kann jedes Mitglied einen Skill mit der ganzen Organisation teilen. Ein Admin kann das unter [Skill-Freigabe](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits#skill-sharing) Redakteuren und höher oder Inhabern und Admins vorbehalten und einzelnen Mitgliedern mit der Kompetenz **Skills für die Organisation veröffentlichen** das Veröffentlichen erlauben. Behält deine Organisation es vor und darfst du nicht veröffentlichen, gilt:

- Unter **Sichtbarkeit** ist **Organisation** nicht wählbar, und ein neuer Skill beginnt mit **Teams**. Mit deinen eigenen Teams kannst du teilen.
- Einen organisationsweiten Skill, den du erstellt hast, kannst du nicht direkt ändern. Schränke ihn auf deine Teams ein, auch zusammen mit anderen Änderungen im selben Speichervorgang, oder lösche ihn.
- Die Upload-Vorschau markiert ein Bundle, das mit der ganzen Organisation geteilt würde, auch eines ohne `visibility`, und **Bundle hochladen** bleibt gesperrt.

Skills, die schon mit der Organisation geteilt waren, bleiben geteilt.

## Sehen, wer einen Skill erstellt und geändert hat

Die Spalte **Erstellt von** nennt das Mitglied, das den jeweiligen Skill erstellt hat. Suche in der Bibliothek nach einem Namen, um alles zu finden, was diese Person geteilt hat. Bei einem Skill ohne festgehaltenen Ersteller, etwa den Dokument-Skills, mit denen deine Organisation startet, steht dort **Mitgeliefert**, bei einem Skill aus einem verwalteten Konfigurations-Release **Konfigurations-Release** mit dem Mitglied, dessen Upload ihn installiert hat. Hat der Ersteller die Organisation verlassen, steht dort **Ehemaliges Mitglied**.

<Frame caption="Einstellungen > Skills — die Spalte Erstellt von nennt das Mitglied, das den Skill geschrieben hat, und kennzeichnet die Dokument-Skills als Mitgeliefert.">

![Die Skill-Bibliothek listet sieben Skills: brief-summary und release-notes, erstellt von Alex Rivera, sowie docx, pdf, pptx, visual-aspect-analyzer und xlsx als Mitgeliefert, alle für die Organisation freigegeben.](https://docs.tale.dev/images/platform/skill-library-list.webp)

</Frame>

Öffne einen Skill, um **Erstellt von** und **Zuletzt bearbeitet von** zu sehen: das Mitglied, dessen Speichern oder Hochladen in Tale die aktuelle Version erzeugt hat. **Zuletzt bearbeitet von** fehlt, wenn seit dem Erstellen niemand den Skill bearbeitet hat oder die Datei seit der letzten Bearbeitung außerhalb von Tale geändert wurde. Auch die Skill-Liste in der [Ausrüstung eines Agenten](https://docs.tale.dev/de/platform/agents/skills) nennt unter jedem Skill seinen Ersteller.

Tale hält das Erstellen, Bearbeiten, Hochladen und Löschen eines Skills sowie jede Änderung seiner Sichtbarkeit oder Teams im Audit-Log fest. Administratoren und Inhaber finden diese Einträge unter **Einstellungen > Richtlinien > Protokolle** in der Kategorie **Skill**.

## Dateireferenz

Eine minimale `SKILL.md` sieht so aus:

```markdown
---
name: brief-summary
description: Fasse ein Projektbriefing zusammen. Nutze dies für Übergaben und Prüfungen.
visibility: org
---

Lies das Briefing. Nenne Prüftermin, Zuständigkeit und offene Fragen.
Zitiere Belege und kennzeichne fehlende Informationen mit „Nicht angegeben“.
```

| Feld | Bedeutung |
| --- | --- |
| `name` | Entspricht dem Ordnernamen. `anthropic` und `claude` sind reserviert. |
| `description` | Wann und warum das Modell den Skill lesen soll; höchstens 1.024 Zeichen. |
| `visibility` / `teams` | `org` oder `team` mit Team-IDs. Die Oberfläche trägt diese Werte ein. |
| `owner` | Die Benutzer-ID des Mitglieds, das den Skill erstellt hat. Tale setzt sie; ein Wert in einer hochgeladenen Datei wird ignoriert. |
| `license` | Die vom Autor angegebenen Nutzungsbedingungen. |
| `recommended-packages` | Empfohlene Abhängigkeiten; der Import installiert sie nicht. |
| `disable-model-invocation` | Bittet um ausdrückliche Verwendung. Diese Metadaten sind eine Anweisung, keine Zugriffsbeschränkung. |
| `icon` / `labels` | Darstellung in der Bibliothek; bis zu acht Labels mit je höchstens 40 Zeichen. |

Unbekannte Frontmatter-Schlüssel bleiben erhalten. Die Frontmatter darf bis zu 16 KB groß sein, die gesamte `SKILL.md` bis zu 512 KB. Häufig gelesene Anweisungen sollten deutlich kürzer bleiben.

## Aktualisieren und Probleme lösen

Öffne eine Zeile, um Beschreibung, Anweisungen, Labels und Sichtbarkeit zu ändern. Unter **Bundle** kannst du ergänzende Dateien prüfen. Agenten sind nicht an eine bestimmte Fassung gebunden: Beim nächsten Bereitstellen wird das aktuelle Bundle verwendet. Teste gemeinsame Änderungen deshalb mit einer typischen Aufgabe.

Unter **Labels** trägst du bis zu acht Labels mit je höchstens 40 Zeichen ein, durch Kommas getrennt. Ist die Liste länger oder ein Label zu lang, sagt dir das Feld, was du entfernen oder kürzen musst, und **Speichern** bleibt gesperrt. Von deiner Eingabe geht dabei nichts verloren. Der Baum unter **Bundle** merkt sich für jeden Skill in deinem Browser, welche Ordner du eingeklappt hast.

Kann Tale einen Skill oder eine seiner Dateien nicht laden, sagt der Dialog das und bietet **Erneut versuchen** an. Schlägt eine Aktualisierung fehl, bleibt der bereits angezeigte Stand stehen, ungespeicherte Änderungen eingeschlossen. Eine entfernte Datei meldet der Dialog als nicht mehr im Bundle, eine leere Datei als leer.

Findet ein Agent den Skill nicht, prüfe seine Ausstattung und die Sichtbarkeit für das Projekt. Tale zeigt ihm einen Beschreibungsauszug von bis zu 300 Zeichen als Auswahlhilfe. Beschreibe deshalb zuerst, wann der Skill passt. Ignoriert er einen zugeordneten Skill, nenne ihn in der Aufgabe und prüfe das Ergebnis anhand seiner Anweisungen. [Skills für Agenten](https://docs.tale.dev/de/platform/agents/skills) erklärt, wie das zugeordnete Bundle bereitgestellt und dem Agenten genannt wird.

Prüfe bei einem Importfehler, ob `SKILL.md` im Stammverzeichnis liegt, gültige Frontmatter enthält und einen gültigen Namen hat. Die Fehlermeldung nennt abgelehnte Pfade oder Größenlimits. Zum Entfernen öffne das Bundle und wähle nach Prüfung der betroffenen Agenten **Skill löschen**.

# Genehmigungsregeln für Automationen festlegen
Source: https://docs.tale.dev/de/self-hosted/configuration/approvals

Genehmigungsregeln bestimmen, ob eine schreibende Connector-Aktion sofort läuft oder auf eine Person wartet. Standardmäßig brauchen Schreibzugriffe auf externe Systeme eine Genehmigung; interne Connectors mit Plattformauthentifizierung dürfen schreiben. Passe diese Grenze je Organisation an ihren Prüfprozess an.

## Richtlinie der Organisation definieren

Speichere die Regeln in `TALE_CONFIG_DIR/<orgSlug>/governance/approval-policy.yml`. Jede Regel nennt genau einen `connector` oder eine vollständige `action` und danach `decision`.

Dieses Beispiel verlangt eine Prüfung für Schreibaktionen des internen Connectors `task` und erlaubt `imap-smtp.send` ohne eigene Genehmigung:

```yaml
rules:
  - connector: task
    decision: require_approval
  - action: imap-smtp.send
    decision: auto_approve
```

<Warning>

`auto_approve` erlaubt die passende Schreibaktion ohne menschliche Prüfung an dieser Stelle. Prüfe Aktion, Zugangsdaten und vorgesehene Empfänger, bevor du einen externen Schreibzugriff wie den E-Mail-Versand freigibst.

</Warning>

Verwende Bezeichner aus dem ausgelieferten Katalog, keine übersetzten Anzeigenamen. Das Aktionsformat lautet `<connector>.<action>`; zulässige Entscheidungen sind `auto_approve` und `require_approval`.

## Überlappende Regeln auswerten

Eine Aktionsregel hat unabhängig von ihrer Position Vorrang vor einer Connector-Regel. Bei gleich spezifischen Treffern gewinnt die letzte Regel. Ohne Treffer verwendet Tale die oben beschriebene Unterscheidung zwischen intern und extern. Führe jedes Ziel möglichst nur einmal auf, damit das Ergebnis ohne Nachverfolgen von Überschreibungen verständlich bleibt.

Die Richtlinie wirkt auf neue Prüfungen. Eine ausstehende Genehmigung bleibt erhalten, wenn du die Regel lockerst; sie wird nicht automatisch erteilt. Die Datei hebt auch keine unabhängigen Prüfungen auf, etwa die Veröffentlichung einer Automation oder den Abschluss einer prüfpflichtigen Aufgabe.

## Wirkung prüfen

Teste die Regel vor dem Produktiveinsatz mit einer isolierten Automation und unkritischen Daten. Prüfe eine passende Aktion und eine, für die der Standard gelten soll. Kontrolliere ausstehende Genehmigung und Ausführungsverlauf im [Genehmigungsablauf](https://docs.tale.dev/de/platform/approvals/configure).

Neue Entscheidungen über Schreibzugriffe lesen die aktuelle Richtlinie und den Organisations-Slug ohne den kurzen Anzeigecache. Ist die Richtlinie ungültig oder ihr Konfigurationsverzeichnis nicht verfügbar, stoppt der Vorgang vor dem Schreiben. Repariere die Konfiguration, bevor du ihn wiederholst. Nur eine fehlende Richtliniendatei in einem verfügbaren Konfigurationsbaum führt zu den Standardregeln. Eine fehlerhafte `.yml`-Datei wird nie durch eine benachbarte `.json` ersetzt. Bereits gespeicherte Freigaben behalten ihre Entscheidung; das gilt sowohl für ausstehende als auch für zuvor genehmigte Vorgänge.

# Authentifizierung einrichten
Source: https://docs.tale.dev/de/self-hosted/configuration/authentication

Tale unterstützt lokale Konten mit E-Mail und Passwort, Unternehmens-SSO je Organisation und Identitäten aus einem vertrauenswürdigen Reverse Proxy. Entscheidend ist, wo dein Team Identitäten verwaltet und wer Konten bereitstellt. Anmeldung und Bereitstellung sind getrennt: SSO authentifiziert eine Person; Einladungen, Bereitstellung bei der Anmeldung oder SCIM regeln die Mitgliedschaft.

## Passende Integration wählen

| Umgebung | Einrichtung | Zentrale Voraussetzung |
| --- | --- | --- |
| Tale verwaltet lokale Konten | Lokale Anmeldung und Einladungen | Stabile Bereitstellungsgeheimnisse und eine erreichbare Instanz-URL. |
| Ein Unternehmens-Identitätsanbieter ist vorhanden | Unternehmens-SSO mit Microsoft Entra ID, generischem OIDC, OAuth2 oder SAML 2.0 | Eine IdP-Anwendung mit exakt passenden Callback- oder Metadaten-URLs. |
| Eine Anwendung oder ein Proxy authentifiziert die Nutzer bereits | Vertrauenswürdige Header je Organisation | Ein Schlüssel aus **Einstellungen > Enterprise-SSO** und ein Proxy, der ihn zusammen mit den Identitäts-Headern mitschickt. |

Unternehmens-SSO und vertrauenswürdige Header werden beide je Organisation eingerichtet. Plane und teste die Identitätszuordnung, bevor du bestehende Konten auf ein anderes Verfahren umstellst.

## Zuerst die öffentliche URL festlegen

Setze `SITE_URL` und eine gegebenenfalls unterstützte Basispfad-Konfiguration auf die tatsächlich verwendete Adresse. Schließe [TLS- und Domain-Einrichtung](https://docs.tale.dev/de/self-hosted/configuration/tls-and-domains) ab, bevor du Weiterleitungsadressen beim Identitätsanbieter registrierst.

Halte `BETTER_AUTH_SECRET` über alle Backend-Prozesse der Instanz hinweg konstant. Verwende das von der Bereitstellung erzeugte Geheimnis oder lade es aus deinem Secret-Manager. Unterschiedliche Werte können die Anmeldung unterbrechen, obwohl der Identitätsanbieter die Person akzeptiert.

## Lokale Konten verwenden

Die lokale Anmeldung speichert Passwort-Hashes in der Anwendungsdatenbank. Die [Ersteinrichtung](https://docs.tale.dev/de/self-hosted/install/first-admin) erstellt den ersten Inhaber; weitere Mitglieder kommen per Einladung hinzu. Richte den E-Mail-Versand ein, wenn Einladung und Passwortwiederherstellung darauf angewiesen sind.

Prüfe mit einem Testkonto Einladung, Anmeldung, Abmeldung und Wiederherstellung. Eine funktionierende Inhabersitzung bestätigt noch nicht, dass neue Mitglieder beitreten können.

Tale verschickt keine Bestätigungsmail. Bestätigt wird eine Adresse deshalb von der Stelle, die das Konto anlegt: der erste Inhaber aus der Ersteinrichtung, eine Person, die eine Administratorin oder ein Administrator unter **Einstellungen > Mitglieder** hinzufügt, und das Konto aus der Bereitstellung gelten als bestätigt und sind sofort nutzbar. Verbundene Anwendungen lesen das als Angabe `email_verified` in der Identität, die Tale ausstellt — neu hinzugefügte Mitglieder können sich dort also sofort anmelden. Konten aus Unternehmens-SSO, SCIM oder vertrauenswürdigen Headern behalten dagegen die Angabe ihres Verzeichnisses.

## Unternehmens-SSO verbinden

Konfiguriere die Organisation unter **Einstellungen > Enterprise-SSO**. Microsoft Entra ID und generisches OIDC lesen die Endpunkte über den Aussteller; OAuth2 verwendet ausdrücklich angegebene Autorisierungs-, Token- und Userinfo-Endpunkte. SAML verwendet Metadaten, eine Assertion-Consumer-URL und Signaturzertifikate.

<Frame caption="Kopiere die URLs aus der laufenden Instanz, damit Domain und Bereitstellungspfad stimmen.">

![Die Seite für Unternehmens-SSO zeigt die Protokollauswahl und die Verbindungsfelder für Microsoft Entra ID.](https://docs.tale.dev/images/platform/settings-enterprise-sso.webp)

</Frame>

Verwende die dort angezeigten Callback- und Metadaten-URLs. Aktuelle native OIDC-Callbacks nutzen `/api/sso/callback`; für vorhandene Registrierungen wird auch `/http_api/api/sso/callback` unterstützt. Die Registrierung beim IdP muss zu der im Ablauf verwendeten URL passen.

[Unternehmens-SSO und Bereitstellung](https://docs.tale.dev/de/platform/admin/enterprise-sso) beschreibt Protokolle, Claim-Zuordnung, Standardrollen, Team-Synchronisierung und SCIM. Teste die Anmeldung in einer separaten Browsersitzung, bevor du deine Administratorsitzung beendest. Eine gelungene Discovery-Prüfung bestätigt weder Claims und Gruppenrechte noch die vollständige Anmeldung.

## Einem Authentifizierungsproxy vertrauen

Eine Anwendung, die ihre Nutzer bereits anmeldet, kann sie über ihren Reverse-Proxy in eine Organisation weiterreichen. Ein Admin schaltet die Funktion unter **Einstellungen > Enterprise-SSO** in der Karte **Vertrauenswürdige Header** ein: Wähle die höchste Rolle, die der Proxy zuweisen darf, erstelle einen Schlüssel und kopiere ihn, denn er wird nur einmal angezeigt. Leite die Anmeldung des Proxys auf `/api/trusted-headers/authenticate`, mit dem Schlüssel im Header `Remote-Internal-Secret` und den Identitäts-Headern `Remote-Email`, `Remote-Name`, `Remote-Role` und `Remote-Teams`. Die [Umgebungsreferenz](https://docs.tale.dev/de/self-hosted/configuration/environment-reference) nennt die Variablen `TRUSTED_*_HEADER` zum Umbenennen dieser Header.

Der Schlüssel bestimmt die Organisation. Ein Mitglied dieser Organisation wird angemeldet; eine Adresse, die die Installation noch nie gesehen hat, wird zum neuen Mitglied mit der zugewiesenen Rolle; ein bestehendes Konto aus einer anderen Organisation wird abgewiesen. Inhaber lässt sich nie zuweisen, und eine Rolle über der Obergrenze der Organisation wird auf diese gesenkt. Bei jeder Anmeldung folgt der Sitz des Mitglieds der zugewiesenen Rolle, sodass **Einstellungen > Mitglieder** zeigt, was der Proxy zugewiesen hat; ein Inhaber-Sitz ändert sich nie. Schaltest du die Karte aus, wird jeder Schlüssel abgewiesen, ohne dass einer widerrufen wird; ein Widerruf beendet die Sitzungen nicht, die der Schlüssel gestartet hat.

<Warning>

Der Proxy muss Identitäts-Header des Clients entfernen, eigene authentifizierte Werte setzen und den Schlüssel nur an die Übergabe-Anfrage anhängen. Wer den Schlüssel besitzt, kann sich als jedes Mitglied anmelden, das der Proxy in dieser Organisation nennt. Behandle ihn wie ein Passwort und rotiere ihn über die Karte.

</Warning>

`Remote-Teams` enthält kommagetrennte Teamnamen, etwa `Finance,Operations`; ein Eintrag im Format `id:name` wie `t-fin:Finance` wird ebenfalls akzeptiert. Teams werden nach Namen zugeordnet und angelegt. Ohne Header bleibt die Teamverwaltung unberührt. Ein vorhandener, aber leerer Header entfernt zuvor von dieser Synchronisierung vergebene Mitgliedschaften. Ungültige Einträge können deshalb synchronisierte Mitgliedschaften entfernen. Manuell vergebene Mitgliedschaften bleiben erhalten.

Wer über den Proxy kommt, wird mit der ersten eigenen Anfrage der App angemeldet: Trägt diese Anfrage den Schlüssel und den Identitäts-Header, aber kein Sitzungs-Cookie, erzeugt das Backend die Sitzung an Ort und Stelle, und die App öffnet sich angemeldet — ohne Anmeldeseite, ohne Weiterleitung. Landet die App dennoch auf ihrer Anmeldeseite (etwa mit einem veralteten Cookie), leitet die Seite den Browser selbst auf die Übergabeadresse weiter, und eine Abweisung kehrt mit ihrem Grund auf diese Seite zurück. Dass der Proxy `/log-in` direkt auf die Übergabeadresse leitet, bleibt möglich; die Adresse antwortet auf Erfolg mit einer Weiterleitung in die App und auf eine Abweisung mit einer Seite samt Statuscode. Da der Proxy die Sitzung besitzt, bietet die App einem so angemeldeten Mitglied keine Abmeldung an; nach einer Abmeldung wegen Inaktivität pausiert die automatische Anmeldung, bis das Mitglied aus dem Hinweis heraus fortfährt.

Soll Tale in der Seite der Anwendung selbst statt in einem Tab erscheinen, trägt ein Admin die Herkunft dieser Seite unter **Einbettung** auf derselben Einstellungsseite ein. Die Seiten von Tale antworten dann mit einer `frame-ancestors`-Richtlinie, die `'self'` und die eingetragenen Herkünfte nennt, statt jeden Frame abzuweisen, und der Header `X-Frame-Options` entfällt. Die Liste gehört einer Organisation, die Anmelde-Shell ist aber ein einziges Dokument für die ganze Installation, sodass eine Herkunft, die irgendeine Organisation zulässt, es laden kann. Der Browser sendet das Sitzungs-Cookie nur dann in einen Frame, wenn die umgebende Seite zur selben Site wie Tale gehört, etwa eine Subdomain des Hosts oder Tale unter der eigenen Domain des Hosts; ein Frame von einer anderen Site zeigt stattdessen die Anmeldeseite.

## Anmeldefehler eingrenzen

| Symptom | Erste Prüfung |
| --- | --- |
| Der IdP lehnt eine Weiterleitung ab | Vergleiche registrierte und angezeigte URL einschließlich Schema, Host und Pfad. |
| Die Weiterleitung endet ohne Anmeldung | Prüfe Erreichbarkeit des Callbacks, Cookies und Claim-Namen. |
| Ein Mitglied erhält die falsche Rolle | Prüfe Standardrolle und Zuordnung anhand seiner tatsächlichen Claims. |
| Synchronisierte Teams verschwinden | Prüfe Gruppen-Claim oder `Remote-Teams`; unterscheide fehlende und leere Werte. |
| Die Header-Anmeldung wird abgelehnt | Prüfe, ob die Karte für die Organisation eingeschaltet ist, ob der Schlüssel noch gültig ist, und die Header-Namen im Proxy. |

Teste Zuordnungsänderungen in einer Staging-Organisation und halte einen geprüften administrativen Wiederherstellungsweg bereit. Änderungen können alle Mitglieder betreffen, deren Identität von dieser Verbindung abhängt.

# Client-Konfigurationen veröffentlichen
Source: https://docs.tale.dev/de/self-hosted/configuration/config-releases

Ein Konfigurations-Release installiert einen geprüften Workflow samt eigenen Skills in einer bestehenden Organisation und einem Projekt. Seine Kennung ist der vollständige Quell-Commit. Nutze diesen Ablauf, wenn die Anwendungslaufzeit bestehen bleibt; für neue Instanzen oder Laufzeitänderungen gelten [verwaltete Bereitstellungen](https://docs.tale.dev/de/self-hosted/install/cli-install).

## Ergebnis jedes Befehls kennen

| Befehl | Vor dem nächsten Schritt prüfen |
| --- | --- |
| `config build` | Manifest und kompilierte Archive aus einer committeten Quellrevision. |
| `config verify --rebuild` | Eine unabhängige Rekonstruktion stimmt mit den geprüften Artefakten überein. |
| `config stage` | Übertragbares Verzeichnis nur mit Bereitstellungsdateien und deren Hash-Inventar. |
| `config deploy` | Workflow und eigene Skills sind installiert, zurückgelesen und in einem dauerhaften Beleg erfasst. |
| `config verify-native` | Lesender Vergleich mit dem derzeit installierten Inhalt. |

Eine **native** ID oder Sitzung gehört hier zur Tale-Zielinstanz. Ein **Beleg** hält ein Bereitstellungsergebnis fest und ersetzt keine Prüfung des aktuellen Servers. Format- und Byteprüfung bestätigen kein fachliches Ergebnis der Automatisierung. Bewahre deshalb fachliche Tests im Kunden-Repository auf.

## Bevor du beginnst

Installiere die [Tale-CLI](https://docs.tale.dev/de/self-hosted/install/cli-install) und lege eine Revision fest, die Paketformat und APIs des Zielservers unterstützt. Konfigurationsbefehle wählen Quelle und Ziel explizit. Sie brauchen weder eine lokale `tale.json` noch einen Docker-Kontext oder ein benachbarten Tale-Quellordner. Der enthaltene Parser und Validator prüfen unterstützte Felder; sie ergänzen keine neueren Serverfunktionen auf einer älteren Instanz.

Du brauchst einen committeten Client-Deskriptor und ein Paket, eine bestehende Organisation und ein Projekt sowie eine berechtigte native Sitzung. Trägt das Paket eigene Skills, verwende die native Benutzer-ID dieser Sitzung als Build-Inhaber. Projekt-, Organisations- und externe Identitäts-IDs sind davon getrennt.

Für eine neue Instanz ohne native IDs nutzt du ein verwaltetes Deployment mit expliziter neuer Identität, symbolischem Projekt und `skillOwner: "operator"`. Es überträgt geprüfte Quellen und kompiliert erst nach dem Nachweis des nativen Betreibers; die eigenständigen Release-Befehle brauchen weiter aufgelöste IDs. Halte die Geschäftskonfiguration im eigenen Client-Quellbaum. Externe Modelleinstellungen gehören in die Deployment-Deklaration.

Die Beispiele verwenden den synthetischen Client `example-team` mit der Automatisierung `document-review`. Übergib das vollständige Sitzungscookie über `TALE_CONFIG_COOKIE` aus deinem Secret Manager. Es gehört weder in Argumente und Quellen noch in Archive, Belege oder Logs.

## Deskriptor und Paket committen

Lege den Deskriptor unter `tale/client.json`, Pakete unter `tale/packs/` und fachliche Tests daneben ab. Bewahre dort auch vorhandene historische Release-Kataloge auf. Pfade im Deskriptor beziehen sich auf dessen Verzeichnis.

Ergänze `.tale/` in der `.gitignore` des Clients, falls der Eintrag fehlt. Standard-Builds halten dort lokale Sperrdaten; Befehle mit explizitem Ausgabeziel koordinieren sich neben ihrer Ausgabe. Die gepflegte Konfiguration liegt in `tale/` ohne Punkt.

```json
{
  "schemaVersion": 1,
  "clientId": "example-team",
  "sourceRepository": "https://github.com/example-team/client-app",
  "automations": [
    {
      "name": "document-review",
      "displayName": "Document review",
      "packPath": "packs/document-review",
      "releasesPath": "releases/document-review",
      "logicalSkillSlugs": ["record-check"],
      "requiredExternalSkills": []
    }
  ]
}
```

`logicalSkillSlugs` nennt die mitgelieferten Skill-Verzeichnisse. `requiredExternalSkills` nennt bereits in Tale installierte Abhängigkeiten: Die CLI prüft ihr Vorhandensein, dieses Release legt ihre Bytes aber nicht fest. Zugangsdaten, Zielhosts und Projekt-IDs gehören in die Deployment-Konfiguration. Committe Deskriptor und Paket; der Compiler liest Git-Objekte statt uncommitteter Änderungen.

## Quell-Commit bauen und prüfen

Setze `CONFIG_REPO` auf den Quellordner, `CONFIG_SOURCE_COMMIT` auf den vollständigen Quell-Commit mit 40 Zeichen und `TALE_NATIVE_USER_ID` auf die native Benutzer-ID. Wähle für `CONFIG_BUILD` ein neues absolutes Ausgabeverzeichnis außerhalb des Checkouts. Diese Befehle bauen das Release und rekonstruieren seine Bytes unabhängig.

```bash
tale --json config build \
  --repo "$CONFIG_REPO" \
  --descriptor tale/client.json \
  --automation document-review \
  --source-commit "$CONFIG_SOURCE_COMMIT" \
  --skill-owner "$TALE_NATIVE_USER_ID" \
  --output "$CONFIG_BUILD"

tale --json config verify \
  --repo "$CONFIG_REPO" \
  --descriptor tale/client.json \
  --automation document-review \
  --manifest "$CONFIG_BUILD/$CONFIG_SOURCE_COMMIT.json" \
  --rebuild
```

Das Standardmanifest nutzt Schema 4/Compiler 3. Es hält `releaseRef` gleich `sourceCommit` sowie Paketbaum, Deskriptor-Hash und vollständiges kompiliertes Inventar fest. Die Ausgabe umfasst das kanonische ZIP, ein ZIP je eigenem Skill und ein ZIP nur für die Workflow-Installation. Eigene Skill-Slugs tragen den vollständigen Quell-SHA; Compiler-Metadaten erhalten ihre logische Identität. Die vollständigen Skill-Bytes enthalten den festgelegten Inhaber. Ein anderer Inhaber erfordert einen neuen Quell-Commit und ein neues Release.

Verlange beim erneuten Build identische Bytes und führe die fachlichen Tests des Clients gegen das entpackte kanonische ZIP aus. Bewahre die geprüften Artefakte auf und übernimm `artifactSha256` als `CONFIG_ARTIFACT_SHA256`. Die native Formatprüfung beweist, dass sich das Paket interpretieren lässt; sie bestätigt keine fachlichen Ergebnisse. Neue quellbasierte Deployments brauchen keinen zusätzlichen Commit mit generierten Release-Dateien.

## Transferverzeichnis vorbereiten

Verwende einen Quellordner, dessen `HEAD` dem `CONFIG_SOURCE_COMMIT` entspricht. Wähle für `CONFIG_STAGE` ein neues absolutes Verzeichnis außerhalb dieses Quellordners. Das optionale `DEPLOYMENT_COMMIT` hält den vollständigen Commit deiner Deployment-Deklaration fest. Lass `--deployment-ref` weg, wenn du keinen solchen Commit führst.

```bash
tale --json config stage \
  --repo "$CONFIG_REPO" \
  --descriptor tale/client.json \
  --automation document-review \
  --config-ref "$CONFIG_SOURCE_COMMIT" \
  --skill-owner "$TALE_NATIVE_USER_ID" \
  --client example-team \
  --deployment-ref "$DEPLOYMENT_COMMIT" \
  --output "$CONFIG_STAGE"
```

Die Vorbereitung baut den committeten Deskriptor samt Paket, prüft die Archive unabhängig und stellt nur zugelassene Deployment-Dateien mit einem gehashten Inventar zusammen. Uncommittete Änderungen fließen nicht ein. Vergleiche den Artefakt-Hash mit dem geprüften Build. Übertrage das Verzeichnis als vollständige Einheit; das native Ziel braucht weder das Client-Checkout noch dessen Git-Zugangsdaten.

Lege Repository-URL und vollständigen Quell-SHA des Clients, CLI-Revision und optional die Deployment-Revision fest. Die Herkunft hängt auch von deinem vertrauenswürdigen Checkout ab: Eine URL im Deskriptor beweist nicht, welcher Remote ein lokales Git-Objekt geliefert hat.

## Bereitstellen und Ergebnis zurücklesen

Setze `TALE_CONFIG_URL`, `TALE_CONFIG_ORIGIN`, `TALE_ORG_ID` und `TALE_PROJECT_ID` auf das freigegebene native Ziel. Halte `CONFIG_RECEIPT` auf dauerhaftem Speicher. Prüfe die vorbereiteten Dateien und gib für einen autorisierten unbeaufsichtigten Lauf `--yes` an. Führe danach eine getrennte Leseprüfung aus. Nutze dieselbe optionale Deployment-Referenz wie bei der Vorbereitung.

```bash
tale --json --yes config deploy \
  --stage "$CONFIG_STAGE" \
  --url "$TALE_CONFIG_URL" \
  --origin "$TALE_CONFIG_ORIGIN" \
  --org "$TALE_ORG_ID" \
  --project "$TALE_PROJECT_ID" \
  --receipt "$CONFIG_RECEIPT" \
  --config-ref "$CONFIG_SOURCE_COMMIT" \
  --source-repository https://github.com/example-team/client-app \
  --artifact-sha256 "$CONFIG_ARTIFACT_SHA256" \
  --deployment-ref "$DEPLOYMENT_COMMIT"

tale --json config verify-native \
  --stage "$CONFIG_STAGE" \
  --url "$TALE_CONFIG_URL" \
  --origin "$TALE_CONFIG_ORIGIN" \
  --org "$TALE_ORG_ID" \
  --project "$TALE_PROJECT_ID" \
  --config-ref "$CONFIG_SOURCE_COMMIT" \
  --source-repository https://github.com/example-team/client-app \
  --artifact-sha256 "$CONFIG_ARTIFACT_SHA256" \
  --deployment-ref "$DEPLOYMENT_COMMIT"
```

Die Ziel-URL bezeichnet den erreichbaren API-Endpunkt; Origin ist die kanonische Browser-Origin, auch bei einer lokalen API hinter einem Proxy. Die angemeldete native Benutzer-ID muss dem festgelegten Skill-Inhaber entsprechen.

Das Deployment erstellt fehlende eigene Skills über den nativen Upload, der nur neue Skills anlegt, und prüft jedes installierte Byte. Vorhandene identische Bytes lassen sich wiederverwenden; abweichende Bytes unter demselben Release-Slug führen zur Ablehnung. Der reine Workflow-Import kann keine Skills schreiben. Vor der Erfolgsmeldung prüft die CLI den bereitgestellten Workflow, Einstellungen, Darstellung, Aufgabenvertrag und Projektbindung.

Führe `verify-native` nach dem Deployment und den Betriebstests aus. Der Befehl importiert nichts und erzeugt weder Version noch Beleg. Auch ein wiederholtes Deployment liest den aktuellen nativen Inhalt, bevor es ein unverändertes Release meldet. Ein gespeicherter Beleg allein beweist keine aktuellen Bytes.

## Eine unterbrochene Bereitstellung wiederaufnehmen

Bewahre das genaue Transferverzeichnis und den Beleg während der Untersuchung auf. Wähle den nächsten Schritt nach dem von der CLI gemeldeten Zustand:

| Zustand | Sicherer nächster Schritt |
| --- | --- |
| Ein vertrauenswürdiger Beleg hält Teilfortschritt fest | Wiederhole mit demselben Verzeichnis, Ziel und Beleg. Identische Skills lassen sich wiederverwenden. |
| Eine passende Version ist bereits bereitgestellt | Lies sie mit `verify-native` zurück. Auch eine erneute Bereitstellung prüft sie vor der Meldung, dass sich nichts geändert hat. |
| Upload-Antwort verloren, nur unveröffentlichte Version sichtbar | Halte an und untersuche. Die native API kann deren vollständigen Aufgabenvertrag vor dem Deployment nicht lesen; die CLI kann ihre Wiederverwendung daher nicht belegen. |
| Release-Skill-Slug mit abweichenden Bytes vorhanden | Sichere die Hinweise und ermittle das widersprechende Release oder die Änderung. Überschreibe nichts, um die Prüfung zu bestehen. |
| Beleg unlesbar oder für ein anderes Ziel | Stelle den richtigen Beleg wieder her oder kläre die Abweichung vor einem neuen Versuch. Erfinde keinen Erfolgsbeleg. |

Koordiniere Bereitstellungen auf dasselbe Ziel. Lokale Sperren hindern weder andere Hosts noch Administratoren daran, native Inhalte zu ändern. Wiederhole nach der Wiederherstellung die Betriebstests des Clients und die unabhängige native Prüfung.

## Ein historisches Release rekonstruieren

Vorhandene semantische Releases bleiben als Kompatibilitätsweg erhalten: `build --config-version` wählt Schema 3/Compiler 2; `stage --config-version` verwendet den committeten Katalog und explizite Katalog-/Ops-Referenzen. Lass ursprüngliche Manifeste und Archive unverändert. Ein Deskriptor kann historische Quellsnapshots mit Prüfsummen für die Offline-Rekonstruktion registrieren; prüfbar sind nur die Felder dieses Formats. Alte geteilte Skills lassen sich nur bei ausdrücklicher Freigabe und bereits identischen Bytes wiederverwenden. Stelle abweichende historische Inhalte über ein neues Release her.

Historische Rekonstruktion braucht zusätzliche Werkzeuge. Schema 1 nutzt Git `archive --mtime`; prüfe, ob dein gewähltes Git die Option unterstützt. Schema 2/Compiler 1 verwendet die Standardbibliothek von Python 3. Schema 3/Compiler 2, Schema 4/Compiler 3 und native Deployments brauchen kein Python.

Bewahre Quellen, fachliche Tests, geprüfte Archive, CLI-Revision, Bereitstellungsreferenzen und Beleg zusammen auf. Sitzungscookies und Zugangsdaten bleiben außerhalb dieser Artefakte im Secret-Manager. [Upgrades](https://docs.tale.dev/de/self-hosted/operate/upgrades) und [Backups und Wiederherstellung](https://docs.tale.dev/de/self-hosted/operate/backups-and-restore) behandeln die umgebende Laufzeit und deren Daten.

# Datenspeicher wählen und umziehen
Source: https://docs.tale.dev/de/self-hosted/configuration/data-residency

Wähle Speicher für drei Datenarten: Anwendungsdatensätze, durchsuchbares Wissen und Originaldateien. Der Umzug einer Art verschiebt die anderen nicht. Speicherorte bestimmen auch nicht, wo ein Modellanbieter oder Konnektor Anfragen verarbeitet. Beziehe diese Ziele in deine Prüfung der Datenresidenz ein.

## Umfang der Änderung wählen

| Speicher | Bereitstellungsweite Einstellung | Organisationsspezifische Einstellung |
| --- | --- | --- |
| Anwendungsdatenbank: Nutzer, Chats, Läufe und Audit-Daten | `DATABASE_URL` | Auf dieser Seite keine eigene Anwendungsdatenbank pro Organisation. |
| Wissensdatenbank: extrahierter Text, Embeddings, Suchindizes und Webinhalte | `KNOWLEDGE_DATABASE_URL` | **Einstellungen > Datenresidenz > Wissensdatenbank** |
| Originaldateien: Dokumente, Anhänge, Audio und erzeugte Medien | `OBJECT_STORE_*` | **Einstellungen > Datenresidenz > Objektspeicher** |

Der mitgelieferte Stack betreibt `tale_app` und `tale_knowledge` als getrennte Datenbanken in einem Postgres-Dienst. Andere Aufbauten können eigene Dienste verwenden. Die vom Deployment erzeugten Umgebungswerte wählen die Standards. Ein allein gestarteter Anwendungsprozess erfindet keine funktionierenden Objektspeicher-Zugangsdaten.

Organisationsänderungen brauchen Admin- oder Owner-Rechte. Ohne eigene Verbindung nutzt Tale den Bereitstellungsstandard und trennt Daten nach Organisation. Eine ungültige konfigurierte Wissensverbindung verursacht einen Fehler, statt unbemerkt eine andere Datenbank zu verwenden.

## Externe Datenbank vorbereiten

Stelle Datenbank und Zugangsdaten vor der Tale-Änderung bereit. Die Anwendungsdatenbank braucht eine Rolle, die ihre Schema-Migrationen anwenden darf. Für Wissen muss `vector` installiert sein; `pg_search` ergänzt den BM25-Teil der Hybridsuche. Mit pgvector allein erhältst du Vektorsuche ohne diesen Stichwortanteil. Tale legt Wissensschemata und Tabellen an, installiert aber keine Erweiterungen auf deiner Datenbank.

Nutze eine direkte oder sitzungskompatible Postgres-Verbindung. Transaction-Pooling verträgt sich nicht mit den verwendeten Sitzungssperren, `LISTEN` und vorbereiteten Anweisungen. Für `sslmode=verify-ca` oder `verify-full` stellst du die nötigen PEM-Stammzertifikate über `POSTGRES_CA_FILE` bereit und mountest die Datei in beiden Backend-Rollen. Prüfe Verbindung und Rechte aus dem Bereitstellungsnetz.

Lege vor der Umschaltung fest, wie vorhandene Anwendungs- oder Wissensdaten ans Ziel kommen, und erstelle abgestimmte Backups. Das Speichern einer Verbindung ändert nur das Ziel nachfolgender Operationen. Alte Zeilen werden nicht kopiert und Dokumente nicht automatisch neu indexiert.

## Bereitstellungsstandards ändern

Ändere `.env` und stelle die betroffenen Backend-Dienste neu bereit oder erstelle sie neu. `docker compose restart` behält die bisherige Umgebung. Ziehen beide Datenbanken aus dem mitgelieferten Dienst aus, bewahre dessen altes Volume bis zur Abnahme der neuen Speicher und des Wiederherstellungsplans auf.

Beim Standard-Objektspeicher gleicht das Backend `default/object-storage/connection.json` und die Geheimnisdatei beim Start mit der Umgebung ab. Das Ergebnis unterscheidet `seeded`, `reconciled`, `skipped` bei fehlenden Zugangsdaten und `ignored` bei einer vom Betreiber verwalteten Datei. Mit `"managedBy": "operator"` übernimmst du die Dateiverwaltung selbst.

Ein anderer Standard-Bucket oder Endpunkt kopiert keine vorhandenen Dateien. Übertrage sie mit Speicherwerkzeugen unter Erhalt von Schlüsseln und benötigten Metadaten. Koordiniere die Umschaltung, bevor du den alten Speicher entfernst. Externe Datenbanken und Buckets liegen außerhalb der Datensicherung durch CLI-Volume-Snapshots. Aktualisiere dabei die Verfahren für [Backups und Wiederherstellung](https://docs.tale.dev/de/self-hosted/operate/backups-and-restore).

## Wissensdatenbank einer Organisation verbinden

1. Öffne **Einstellungen > Datenresidenz** in der Zielorganisation und trage unter **Wissensdatenbank** Host, Port, Datenbank, Benutzer, SSL-Modus und Passwort ein.
2. Wähle **Verbindung testen**. Der Test prüft die Felder zuerst wie **Speichern** und nennt einen fehlenden Host, eine fehlende Datenbank oder einen fehlenden Benutzer unter dem Feld, statt zu laufen. Prüfe Erreichbarkeit und Erweiterungen. Ein erfolgreicher Verbindungstest belegt keinen abgeschlossenen Korpusumzug.
3. Speichere erst, wenn Ziel und Plan für vorhandene Daten bereit sind. Folgende Anfragen nutzen die gewählte Verbindung ohne Container-Neustart.
4. Indexiere ein Testdokument, suche nach einer bekannten Formulierung und prüfe, ob benötigte ältere Inhalte weiter verfügbar sind.

Die Dateien liegen unter `$TALE_CONFIG_DIR/<orgSlug>/knowledge/`: `connection.json`, `connection.secrets.json` und `embedding.json`. Bei konfiguriertem age-Schlüssel nutzt die Geheimnisdatei SOPS. Das Entfernen der Verbindung leitet wieder auf den Standard um. Externe Daten bleiben bestehen, sind über die entfernte Verbindung aber nicht mehr zugänglich.

### Embedding-Modell auf den Korpus abstimmen {#das-embedding-modell-der-organisation}

Wähle unter **Embedding-Modell** Anbieter und gespeicherte Zugangsdaten und dann das Modell. **Modell** führt die Embedding-Modelle aus dem Katalog des Anbieters auf und füllt die Vektorbreite aus dem Katalog aus. Ein Anbieter, der überhaupt kein Embedding-Modell anbietet, etwa Anthropic, lässt sich nicht wählen: In der Zeile steht **Bietet keine Embeddings**, und du wählst einen anderen Anbieter. Kennt Tale für den Anbieter keine Vektorbreite, trägst du das Modell-Tag (bei Azure OpenAI den Namen deines Deployments) und die Vektorbreite ein, die dieses Modell erzeugt. Das gilt für einen mitgelieferten Anbieter, dessen Katalog kein Embedding-Modell führt, für einen von deiner Organisation selbst definierten Anbieter, dessen Modellliste keines führt, und für Azure OpenAI, dessen Deployments deine eigenen Namen tragen. Welcher der beiden Fälle vorliegt, entscheidet die [`embedding`-Angabe](https://docs.tale.dev/de/self-hosted/configuration/providers#was-ein-connector-deklariert) des Anbieters, und das Speichern lehnt einen Anbieter ohne Embeddings ab, egal auf welchem Weg die Anfrage kommt. Kann Tale die Angaben nicht prüfen, sagt der Abschnitt das und bietet **Erneut versuchen** an; bis die Prüfung antwortet, lässt sich kein Modell wählen. Eine optionale Basis-URL wählt einen OpenAI-kompatiblen Endpunkt. Ohne konfiguriertes Embedding-Modell können Wissensindexierung und Suche nicht regulär arbeiten.

Die Vektorbreite wird bei erster Verwendung pro Datenbank festgelegt. Organisationen auf derselben Datenbank müssen diese Breite verwenden. Eine andere Breite braucht eine separate kompatible Datenbank. Auch ein Modellwechsel bei gleicher Breite kann vorhandene Vektoren inkompatibel machen. Plane eine Neuindexierung mit dem gewählten Modell, statt Embeddings ungeprüft zu mischen.

`embedding.json` kann `minSimilarity` als Untergrenze für den Vektoranteil der Assistentensuche setzen; der Standard ist `0.45`. Das Einstellungsformular erhält diesen Dateiwert, bietet aber kein Feld dafür. Stimme ihn anhand repräsentativer Suchanfragen ab. Die REST-Wissenssuche verwendet eine Grenze nur, wenn die Anfrage sie angibt. Es ist kein allgemeiner Schwellenwert für alle Suchen.

### Anfragen an einen selbst betriebenen Embedding-Server dosieren {#kapazitaet-des-embedding-servers}

Zwei weitere optionale Einstellungen in `embedding.json` beschreiben, wie viel Arbeit der Embedding-Server verkraftet. Setze sie, wenn du den Server selbst betreibst, etwa einen Modellserver auf eigener Hardware, der eine Anfrage nach der anderen berechnet und die übrigen in eine Warteschlange stellt. Wie `minSimilarity` gibt es sie nur in der Datei: Das Einstellungsformular behält sie beim Speichern bei, und die CLI deklariert sie in der Ressource `knowledge-embedding`.

- `maxConcurrentRequests` (1 bis 64, Standard 3) legt fest, wie viele Embedding-Anfragen an dieses Modell Tale für die Organisation gleichzeitig offen hält. Dokumentindexierung, die Indexierung eingehender E-Mails, Website-Scans und Suchen teilen sich dieses Limit. Weitere Anfragen warten in der Reihenfolge ihres Eintreffens; nur eine Suchanfrage zieht an wartenden Indexierungs-Batches vorbei. Jeder Tale-Prozess zählt für sich, sodass die API und jedes Worker-Replikat das Limit jeweils ausschöpfen können. Ein niedrigerer Wert gilt sofort, ein höherer erst, wenn die unter dem alten Wert gestarteten Anfragen abgeschlossen sind. Berechnet der Server eine Anfrage nach der anderen, erzeugt ein höherer Wert keine zusätzliche Last; jede Anfrage wartet nur länger.
- `minTokensPerSecond` (eine beliebige positive Zahl) ist die niedrigste Rate, mit der der Server unter seiner üblichen Last Embeddings für dieses Modell berechnet. Miss sie, während auf derselben Hardware andere Arbeit läuft, etwa ein Chat-Modell, aber zähle die Zeit nicht mit, die eine Anfrage hinter anderen Anfragen wartet. Diese Wartezeit rechnet Tale selbst hinzu.
- `maxTokensPerMinute` und `maxRequestsPerMinute` (ganze Zahlen) dosieren, was Tale diesem Modell innerhalb einer Minute schickt, für die Organisation in jedem Tale-Prozess. Setze sie auf die Minutenlimits eines gehosteten Anbieters, die pro Anbieterkonto über alle Deployments gezählt werden, die sich den Schlüssel teilen: Ein Indexierungs-Batch, der ein Limit überschreiten würde, wartet, bis genug von der letzten Minute verstrichen ist, sodass ein Crawl über Hunderte Seiten dosiert wird statt mit `429` abgewiesen zu werden. Tale schätzt Tokens anhand der Zeichen, eher zu hoch, hält zusätzlich ein Sechzigstel jedes Limits innerhalb jeder einzelnen Sekunde ein – ein Anbieter setzt seinen Minutenwert auch pro Sekunde durch – und bemisst jede Anfrage so, dass sie in diese Sekunde passt. Ein `429`, das der Anbieter trotzdem schickt, hält jede Anfrage der Organisation an dieses Modell an und wird im Minutentakt wiederholt; eine Suchanfrage wird von beidem nicht gebremst. Alibaba Cloud Model Studio erlaubt für text-embedding-v4 zum Beispiel 1.800 Anfragen und 1.000.000 Tokens pro Minute.

```json
{
  "providerSlug": "local-embedding",
  "model": "example-embedding",
  "dimensions": 1024,
  "baseUrl": "https://embeddings.example.internal/v1",
  "maxConcurrentRequests": 2,
  "minTokensPerSecond": 800,
  "maxTokensPerMinute": 1000000,
  "maxRequestsPerMinute": 1800
}
```

Jede Embedding-Anfrage hat eine Obergrenze: 15 Minuten für die Indexierung und 5 Minuten für eine Suchanfrage, auf die eine Chat-Antwort wartet. Ohne `minTokensPerSecond` weiß Tale nicht, wie lange die Warteschlange des Servers dauern kann, und lässt eine Anfrage ihre ganze Obergrenze ausschöpfen. Mit dieser Einstellung gibt Tale jeder Anfrage Zeit für die Arbeit, die auf dem Server vor oder neben ihr liegen kann, und für ihre eigene. Dazu zählen die Tokens der Anfrage selbst, großzügig aus ihren Zeichen geschätzt, die übrigen Anfragen, die dieser Tale-Prozess gleichzeitig offen haben kann, und `maxConcurrentRequests` weitere von anderen Clients. Jede dieser Anfragen rechnet Tale mindestens als vollen Batch aus 64 Texten mit je 1.024 Tokens. Die Summe teilt Tale durch `minTokensPerSecond` und schlägt 50 % auf, gibt aber nie weniger als 60 Sekunden und nie mehr als die Obergrenze. Mit dem Beispiel oben bekommt ein voller Batch mit gewöhnlichem Text rund acht Minuten und eine Suchanfrage ihre Obergrenze von fünf Minuten. Eine Suchanfrage endet außerdem nach insgesamt fünf Minuten, einschließlich der Wartezeit auf einen freien Platz. Teilen sich mehr Clients den Server als ein weiterer Tale-Prozess mit demselben Limit, gib eine niedrigere Rate an.

Eine Anfrage, deren Zeit abgelaufen ist, sendet Tale nicht sofort erneut: Der Server hatte sie die ganze Zeit, und eine Wiederholung würde seine Warteschlange nur verlängern. Eine abgelehnte Verbindung, eine Ratenbegrenzung oder ein Serverfehler wird nach einer Pause wiederholt, die mit jedem Versuch wächst, oder nach der Pause, die ein ausgelasteter Server mit `Retry-After` verlangt, höchstens einer Minute. Verlangt ein Server eine längere Pause, lässt Tale ihn in Ruhe. Schlägt bei einer Anfrage aus mehreren Batches einer fehl, etwa bei einer langen Webseite, bricht Tale die übrigen Batches ab, ob sie laufen oder noch warten, sodass der Server nicht weiter an ihnen rechnet.

Für die Indexierung eines Dokuments bleiben pro Versuch höchstens 15 Minuten. Braucht ein großes Dokument oder eine lange Warteschlange mehr, endet der Versuch an dieser Grenze und bricht seine offene Anfrage ab; eine Anfrage, deren Zeit abläuft, beendet den Versuch ebenfalls. Der nächste Versuch beginnt nach einer Pause, die mit jedem Versuch wächst, und macht nach den bereits gespeicherten Chunks weiter. Ist ein Dokument nach sechs Versuchen noch nicht fertig, erscheint es als fehlgeschlagen. **Indexierung erneut versuchen** macht dann bei den gespeicherten Chunks weiter.

## Bucket einer Organisation verbinden

1. Stelle einen S3-kompatiblen Bucket mit den benötigten Objektrechten bereit. Konfiguriere CORS für die tatsächlichen Browser-Ursprünge und benötigten Methoden `GET`, `PUT` und `HEAD`.
2. Trage unter **Objektspeicher** Region, bei Bedarf Endpunkt, Bucket, optionales Schlüsselpräfix und Zugangsdaten ein. Nutze Path-Style, wenn dein Speicher es verlangt.
3. Wähle **Verbindung testen** und speichere danach. Eine fehlende Region, ein fehlender Bucket oder ein Wert über der Längengrenze eines Felds wird unter dem Feld genannt, bevor etwas gesendet wird. Der Servertest schreibt, liest und löscht ein Testobjekt; Browser-CORS prüft er nicht.
4. Lade im Browser eine Testdatei hoch und wieder herunter, bevor du dich auf die Verbindung verlässt.

Neue Uploads verwenden den Organisations-Bucket. Ältere Dateien im Standardspeicher können über gemischte Referenzen lesbar bleiben. Die Verbindung allein erfüllt daher keine Pflicht, auch den bisherigen Bestand umzuziehen. Die Konfiguration liegt unter `$TALE_CONFIG_DIR/<orgSlug>/object-storage/connection.json` und `connection.secrets.json`.

Entfernst du die Verbindung, gehen neue Uploads an den Standardspeicher. Vorhandene Objekte bleiben im Organisations-Bucket. Tale kann sie erst nach Wiederherstellen der Verbindung wieder lesen.

### Vorhandene Dateien gezielt verschieben

Nutze nach dem Speichern des Buckets **Bestehende Dateien verschieben** im selben Abschnitt. Prüfe eine angebotene Vorschau, bestätige den Umzug und verfolge den Fortschritt. Halte die Verbindung bis zum Abschluss stabil.

Der Nachzug durchläuft referenzierte Dokumente samt Verlauf, hochgeladene Dateien, erzeugtes Audio und Videotranskripte dieser Organisation. Er kopiert jedes Objekt mit Inhaltstyp, prüft die Zielgröße und löscht danach die Quelle. Objektschlüssel bleiben erhalten. Bereits verifizierte Kopien lassen sich nach einer Unterbrechung abschließen. Das ist ein Umzug, kein zusätzliches Backup oder kryptografischer Inhaltsnachweis.

Das Ziel muss sich vom Standardspeicher unterscheiden. Prüfe bei einem Fehlschlag letzten Fehler und Fortschritt vor einem neuen Lauf. Bewahre beide Speicher auf, bis Ergebnis und Downloads beispielhafter alter Dateien bestätigt sind. [Geheimnisse mit SOPS](https://docs.tale.dev/de/self-hosted/configuration/secrets-with-sops) erklärt den Schutz der Verbindungsdateien.

# Umgebungsvariablen-Referenz
Source: https://docs.tale.dev/de/self-hosted/configuration/environment-reference

Hier findest du Bereitstellungsvariablen, ihre Standardwerte und die Prozesse, die sie benötigen. Die Projektdatei `.env` ist eine mögliche Quelle; Container-Umgebungen und Secret-Manager können Werte ebenfalls bereitstellen. Die [Beispieldatei](https://github.com/tale-project/tale/blob/main/.env.example) enthält die zugehörige Quellkonfiguration.

Erstelle betroffene Dienste nach einer Umgebungsänderung über deinen Bereitstellungsablauf neu. `docker compose restart` behält die vorhandene Containerumgebung. Dateibasierte Organisationskonfiguration hat einen getrennten Lebenszyklus.

## Wie du diese Seite liest

Die Tabellen nennen Variablennamen, Standardwerte und Zweck. Erforderliche Werte müssen den jeweiligen Dienst erreichen; einige erzeugt die Bereitstellung automatisch. Optionale Werte können ungesetzt bleiben. Ein angegebener Standard kann aus Compose stammen statt aus dem Prozess selbst.

Nutze zusätzlich die kommentierte Beispieldatei und prüfe bei fehlenden Werten die wirksame Umgebung des betroffenen Dienstes.

## Domain-Identität (Pflicht beim ersten Boot)

| Name        | Default             | Beschreibung                                                                                                                   |
| ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `HOST`      | `localhost`         | **Pflicht.** Hostname ohne Protokoll. Wird für Docker-Networking und ausgehende Mails verwendet.                               |
| `SITE_URL`  | `https://localhost` | **Pflicht.** Vollständige kanonische URL inklusive Schema und Port. Auth-Callbacks und externe Links nutzen das.               |
| `ADDITIONAL_SITE_URLS` | unset    | **Optional.** Weitere Origins, auf denen dasselbe Deployment antwortet, per Komma oder Leerzeichen getrennt (z. B. `https://a.example,https://b.example`). Jeder ist ein vollwertiger Eingang. Siehe [TLS und Domains](https://docs.tale.dev/de/self-hosted/configuration/tls-and-domains#mehrere-domains-gleichzeitig). |
| `TOTP_ENVIRONMENT` | nicht gesetzt | Umgebungsname für die Authenticator-Einträge von `backend-api` und der Rolle `all`: 1–32 Buchstaben, Ziffern, Unterstriche oder Bindestriche. Leerzeichen am Rand werden entfernt, Buchstaben großgeschrieben. `pr` oder ein fehlender Wert behält `Tale` bei; mit `te` heißen neu erzeugte Einträge `Tale <TE>`. Ein ungültiger Wert verhindert den Backend-Start. |
| `BASE_PATH` | unset               | **Optional.** Pfad-Präfix für Subpath-Deployments hinter einem Reverse-Proxy (z. B. `/app`). Bei Root-Deployment unset lassen. |
| `DOCS_URL` | `https://docs.<HOST>` | Öffentliche Origin des eigenen Dokumentationshosts im Proxy. Der Docs-Dienst muss ebenfalls zur Bereitstellung gehören. |

`SITE_URL` bezeichnet den kanonischen öffentlichen Ursprung. Protokoll, Hostname und Port müssen zur Browseradresse und zu registrierten Callbacks passen. `BASE_PATH` ergänzt einen Bereitstellungspfad. Einen abschließenden Schrägstrich normalisiert der Proxy. Weitere Adressen gehören als reine Ursprünge in `ADDITIONAL_SITE_URLS`. Ungültige zusätzliche Ursprünge verhindern den Backend-Start.

Die Dokumentation verwendet eine eigene Origin. Auf der Plattform-Origin öffnet `/docs` die interaktive API-Referenz; `/openapi.json` liefert deren Schema. `DOCS_URL` ändert den Docs-Host des Proxys. Die Variable installiert keinen Docs-Dienst und schreibt keine Links in vorhandenen Client-Bundles um. `TALE_DOCS_URL` in den SEO-Buildwerkzeugen und das Build- und Laufzeitpfadpräfix `DOCS_BASE_URL` des Docs-Dienstes sind separate Einstellungen.

Eine Änderung von `TOTP_ENVIRONMENT` gilt für neu erzeugte QR-Codes und Einrichtungs-URIs, auch wenn ein bestehender Schlüssel erneut angezeigt wird. Sie ändert weder den Schlüssel noch den Namen eines bereits auf deinem Gerät gespeicherten Eintrags. Diesen kannst du bei Bedarf in deiner Authenticator-App umbenennen.

## TLS

| Name        | Default      | Beschreibung                                                                                                               |
| ----------- | ------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `TLS_MODE`  | `selfsigned` | Einer von `selfsigned`, `letsencrypt`, `external`. Siehe [TLS und Domains](https://docs.tale.dev/de/self-hosted/configuration/tls-and-domains). |
| `TLS_EMAIL` | unset        | Kontakt-E-Mail für Let's-Encrypt-Benachrichtigungen. Optional aber empfohlen in Produktion.                                |
| `TRUSTED_PROXIES` | `private_ranges` | Bei `TLS_MODE=external` die Adressen, deren weitergeleitete Header der Proxy übernimmt: durch Leerzeichen getrennte CIDR-Bereiche oder `private_ranges`. Die übrigen Modi ignorieren die Variable. Siehe [TLS und Domains](https://docs.tale.dev/de/self-hosted/configuration/tls-and-domains). |

`selfsigned` erstellt ein lokales Caddy-Zertifikat. Vertraue der zugehörigen CA nur für deine eigene kontrollierte Installation. `letsencrypt` benötigt eine öffentliche Domain sowie erreichbare Ports 80/443. Bei `external` bedient Caddy HTTP hinter einem TLS-Proxy.

## Sicherheits-Secrets (Pflicht)

| Name                    | Default                   | Beschreibung                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ----------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `BETTER_AUTH_SECRET` | Beispielwert in der Datei | Authentifizierungsgeheimnis für alle Backend-Replikate. Erzeuge einen zufälligen Wert, etwa mit `openssl rand -base64 32`, und halte ihn stabil. Ein Wechsel kann Sitzungen und laufende Anmeldungen ungültig machen. |
| `ENCRYPTION_SECRET_HEX` | Beispielwert in der Datei | Verschlüsselungsschlüssel mit 32 Byte als Hex-Wert; erzeuge ihn mit `openssl rand -hex 32`. Bewahre den zu vorhandenen Geheimnissen passenden Wert auf. Ein Austausch migriert keine verschlüsselten Daten. Stelle den passenden Schlüssel wieder her oder erfasse betroffene Geheimnisse über ihren vorgesehenen Ablauf neu. |
| `INSTANCE_SECRET`       | Beispielwert in der Datei | **Pflicht.** Das Root-Secret der Instanz: 64 Hex-Zeichen, `tale init` erzeugt es (von Hand: `openssl rand -hex 32`). Beim Boot leitet Tale daraus den WebDAV-App-Passwort-HMAC-Schlüssel (`WEBDAV_APP_PASSWORD_HMAC_KEY`) ab, sofern du den nicht selbst setzt; auch die kurzlebigen Tokens, mit denen Sandbox-Sessions Blobs holen, signiert ein Unterschlüssel derselben Ableitung. Halte ihn über Deploys stabil: Eine Rotation leitet den Schlüssel neu ab und macht jedes WebDAV-App-Passwort ungültig. |
| `SANDBOX_TOKEN`         | Beispielwert in der Datei | **Pflicht.** Gemeinsames HMAC-Secret zwischen Backend und Sandbox-Spawner: Das Backend signiert damit jeden Spawner-Aufruf, der Spawner weist unsignierte ab. Ohne das Secret startet der Spawner nicht — er hält den Docker-Socket des Hosts, es gibt also keinen unsignierten Modus. `tale init` und `bun run dev` erzeugen es; ein Stack, den du selbst zusammenstellst, setzt es vor dem ersten Boot (`openssl rand -hex 32`). Eine Rotation heißt: Backend und Spawner zusammen neu starten — sie müssen übereinstimmen. |
| `SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD` | nicht gesetzt | **Für Sandbox-Harness-Aufrufe erforderlich.** Das Backend nutzt dieses Verwaltungsgeheimnis, um Sitzungsschlüssel am Gateway bereitzustellen. Gib dem Gateway denselben Wert: Solange es kein Admin-Konto hat, legt es eines nur für einen Aufrufer an, der dieses Geheimnis vorweist — so übernimmt das Backend das Gateway bei der ersten Verwendung. Das Image des Gateways nimmt diesen Wert immer als Setup-Token (`BIFROST_SETUP_TOKEN`) und ersetzt ein am Container gesetztes. Danach bleibt der Passwort-Hash in `llm-gateway-data`. Bewahre das passende Geheimnis auf oder nutze die unterstützte Wiederherstellung bzw. Rotation des Gateways. Lösche dessen Zustand nicht als gewöhnlichen Reparaturschritt. Der Benutzername ist standardmäßig `admin` (`SANDBOX_LLM_GATEWAY_ADMIN_USERNAME`). |

Ersetze die unsicheren Beispielwerte aus `.env.example`, bevor du die Instanz für andere zugänglich machst.

## Datenbank

Tale verwendet `tale_app` für Anwendungsdaten und `tale_knowledge` für Textabschnitte, Embeddings und Webseiten. Der Standardaufbau betreibt beide in einem Postgres-Dienst `db` mit dem Alias `knowledge-db`. Externe Verbindungen kannst du getrennt konfigurieren.

| Name                                      | Default                                                             | Beschreibung                                                                                                                                                                                                                                                                                                                    |
| ----------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DB_PASSWORD` | `tale_password_change_me` | **Für das mitgelieferte Postgres erforderlich.** Gemeinsames Passwort der Anwendungs- und Wissensdatenbank im Standardaufbau. Ersetze den Beispielwert vor dem Produktivbetrieb. |
| `DATABASE_URL`                            | aus `DB_PASSWORD` konstruiert                                       | **Optional.** Verbindungs-URL der operativen Datenbank. Setz sie, um das Backend auf einen Postgres zu richten, den du selbst betreibst: er braucht keine Extensions und keinen Superuser, nur eine Datenbank und eine Rolle, die Schemata anlegen darf. Wird bei jedem Start gelesen. |
| `DATABASE_POOL_MAX` | `10` | **Optional.** Maximale Verbindungen je Pool der operativen Datenbank. Jede Replik von `backend-api` oder `backend-worker` benötigt normalerweise bis zum Doppelten dieses Werts (App-Pool plus Job-Queue). Sandbox-Aktionen können vorübergehend je belegtem App-Pool-Platz eine weitere Verbindung öffnen: In der Spitze ist es das Dreifache je Replik. Rechne diese Spitze gegen `max_connections` der Datenbank. |
| `POSTGRES_CA_FILE`                        | nicht gesetzt                                                       | **Optional.** Pfad zu einem PEM-Bundle, dem **jede** Postgres-Verbindung vertraut: operative Datenbank, Wissens-Korpus und die Datenbanken, die Organisationen selbst mitbringen. Nötig, sobald eine URL `sslmode=verify-ca` oder `verify-full` gegen einen Anbieter verlangt, dessen Root Node nicht mitliefert — Amazon RDS ist der übliche Fall. Nutzen mehrere Datenbanken verschiedene Anbieter, häng ihre Roots in einer Datei aneinander. |
| `KNOWLEDGE_DATABASE_URL` | `postgresql://tale:${DB_PASSWORD}@knowledge-db:5432/tale_knowledge` | Verbindungs-URL des Standard-Wissenskorpus. Eine andere URL wählt eine andere Datenbank; vorhandene Textabschnitte und Vektoren werden nicht übertragen. |
| `KNOWLEDGE_DB_POOL_MAX` | `10` | **Optional.** Verbindungen, die ein Backend-Prozess zum Wissenskorpus öffnet. Jeder Indexierungsjob belegt eine, während er einen Block Textabschnitte festschreibt — erlaubt `WORKER_CONCURRENCY` mehr gleichzeitige Jobs als das, warten sie auf den Pool; erhöhe beide zusammen. Wie `DATABASE_POOL_MAX` zählt der Wert je Replik gegen `max_connections` der Korpus-Datenbank. |
| `KNOWLEDGE_DB_NAME` | `tale_knowledge` | Name der Wissensdatenbank, die die mitgelieferte Datenbankinitialisierung erstellt. |
| `KNOWLEDGE_INDEX_REPAIR_INLINE_MAX_BYTES` | `1073741824`                                                        | **Optional.** Größter BM25-Suchindex (in Bytes), den das Backend beim Start synchron neu aufbaut, wenn es ihn beschädigt vorfindet; einen größeren baut ein Hintergrundjob neu auf, während Schreibzugriffe auf diesen Korpus abgewiesen werden. Siehe [Container-Architektur](https://docs.tale.dev/de/self-hosted/operate/container-architecture). |
| `KNOWLEDGE_INDEX_REPAIR_DISABLED` | nicht gesetzt | `1` oder `true` deaktiviert die automatische BM25-Prüfung und Reparatur beim Start. Beschädigungen bleiben bestehen; fehlgeschlagene Abfragen oder Schreibzugriffe brauchen eine Untersuchung und kontrollierte Reparatur. |
| `KNOWLEDGE_CRAWL_DOCUMENT_MAX_BYTES` | `104857600` | **Optional.** Größtes Dokument (PDF, DOCX, XLSX, PPTX, ODT — in Bytes), das der Website-Crawler herunterlädt und ausliest; ein größeres vermerkt er an seiner Seite als zu groß. HTML-Seiten haben ein eigenes Budget von 2 MiB. Jeder Abruf liegt während der Textextraktion im Speicher, und bis zu fünf Websites werden gleichzeitig gescannt — bemesse den Speicher des Backends entsprechend. Ein Wert unter 1 MiB oder keine ganze Zahl fällt auf den Standard zurück. |

Die erzeugte Verbindungs-URL lautet `postgresql://tale:${DB_PASSWORD}@db:5432/tale_app`; `APP_DB_NAME` ändert den Datenbanknamen. Der Wissenskorpus nutzt die Schemata `private_knowledge` und `public_web`. Unter **Einstellungen > Datenresidenz** kann eine Organisation eigene Verbindungen wählen. Eine gespeicherte URL ändert den Speicherort, überträgt aber keine Daten. Siehe [Datenresidenz](https://docs.tale.dev/de/self-hosted/configuration/data-residency).

Zwei Dinge musst du wissen, bevor du eine der beiden Datenbanken auf eigene Infrastruktur richtest:

- **Der Wissens-Korpus braucht ein installiertes `pgvector`.** Tale legt Schemata und Tabellen auf einer leeren Datenbank selbst an, installiert aber nie Extensions — die Chunk-Tabelle hat eine `vector`-Spalte, also muss `CREATE EXTENSION vector;` auf der Zieldatenbank bereits gelaufen sein. ParadeDBs `pg_search` ist optional: Fehlt es, fällt die Suche auf reine Vektorsuche zurück, statt zu scheitern. Die operative Datenbank braucht gar keine Extensions.
- **Verwende eine direkte oder sitzungskompatible Postgres-Verbindung.** Job-Benachrichtigungen, Migrationssperren und vorbereitete Abfragen brauchen Sitzungseigenschaften. Prüfe einen verwalteten Verbindungsproxy anhand dieser Anforderungen.

## Object-Store

Dateien und Medien verwenden S3-kompatiblen Speicher. Diese Variablen bestimmen den Bereitstellungsstandard. Eine ausdrücklich gewählte Organisationsverbindung hat Vorrang; ein ausgefallener Standardspeicher bedeutet nicht, dass auch die eigenen Buckets aller Organisationen ausfallen.

| Name                             | Default                        | Beschreibung                                                                                                                                                                    |
| -------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OBJECT_STORE_ACCESS_KEY` | nicht gesetzt | Zugriffsschlüssel der Standard-S3-Verbindung. Setze bei mitgeliefertem MinIO denselben Wert als `MINIO_ROOT_USER`. Ohne Zugangsdaten entsteht keine Standardverbindung; eine Organisation kann trotzdem eine eigene gültige Verbindung haben. |
| `OBJECT_STORE_SECRET_KEY` | von `tale init` autogeneriert | Geheimschlüssel des Standardspeichers. Bei mitgeliefertem MinIO muss er zu `MINIO_ROOT_PASSWORD` passen. Rotiere Speicher- und Backend-Zugangsdaten abgestimmt und prüfe Lesen und Schreiben. Ein Passwortwechsel überträgt keine Dateien und macht sie nicht von sich aus verwaist. |
| `OBJECT_STORE_BUCKET`            | `tale-blobs`                   | Bucket, in dem Blobs liegen. Das Backend legt ihn an, wenn er fehlt und der Schlüssel das darf; einen vorhandenen nutzt es, wie er ist. |
| `OBJECT_STORE_ENDPOINT` | `http://object-store:9000` im mitgelieferten Compose | Endpunkt des Speichers aus Sicht des Backends. AWS S3 verwendet keinen eigenen Endpunkt; entferne oder leere den mitgelieferten Endpunkt ausdrücklich in der wirksamen Compose-Umgebung. MinIO, R2 und andere kompatible Dienste verwenden eine eigene URL. |
| `OBJECT_STORE_REGION`            | `us-east-1`                    | Signier-Region. Auf AWS bedeutungstragend; bei einem selbst gehosteten Store beliebig, aber vom Signierer verlangt. |
| `OBJECT_STORE_FORCE_PATH_STYLE`  | `true` mit Endpoint, sonst `false` | Adressiert den Bucket als `endpoint/bucket/key` statt `bucket.endpoint/key`. Der Default folgt dem Endpoint und passt damit für beide Fälle; setz ihn nur für einen Store, der von seiner eigenen Form abweicht. |
| `OBJECT_STORE_PREFIX`            | nicht gesetzt                  | Schlüssel-Präfix im Bucket, damit Tales Blobs sich einen Bucket mit anderen Daten teilen können. Leer heißt Bucket-Wurzel. |
| `OBJECT_STORE_PUBLIC_ENDPOINT`   | `${SITE_URL}` (die CLI setzt ihn) | Wo der **Browser** den Store erreicht. Der Proxy publiziert den gebündelten Store unter `/<bucket>/*` und leitet presignte URLs unverändert weiter, sodass Up- und Downloads direkt Browser↔Store laufen. Ist dieser Endpunkt einer der Ursprünge des Deployments, wird ein Link für einen Browser auf einem anderen konfigurierten Ursprung für jenen Ursprung signiert. Für einen Bucket, den der Browser ohnehin erreicht, lässt du ihn leer. |

Der mitgelieferte Proxy macht die Objektroute im Browser erreichbar, ohne den Verwaltungsport des Speichers zu veröffentlichen. Ein externer Speicher kann über seinen eigenen öffentlichen Endpunkt erreichbar sein.

### Wie diese Variablen im laufenden Deployment ankommen

Beim Start gleicht das Backend `default/object-storage/connection.json` mit seiner Umgebung ab. Erstelle `backend-api` und `backend-worker` mit den geänderten Werten neu. Die Startmeldungen unterscheiden diese Ergebnisse:

| Zeile | Bedeutung |
| --- | --- |
| `object store (seeded)` | es gab keine Verbindung; eine wurde aus der Umgebung geschrieben |
| `object store (reconciled)` | die Umgebung hat sich geändert; die Verbindung zieht nach |
| `object store (adopted)` | eine von einem älteren Release geschriebene Verbindung wurde erkannt und wird jetzt mitgeführt |
| `object store (ignored)` | die Verbindung trägt `"managedBy": "operator"`, diese Variablen tun also nichts |
| `object store (skipped)` | Keine Zugangsdaten für einen Bereitstellungsstandard vorhanden. Prüfe, ob eine nutzbare bestehende oder organisationsgebundene Verbindung bleibt. |
| *(nichts)* | schon im Gleichstand — der Normalfall |

Willst du den Store lieber von Hand führen, trag `"managedBy": "operator"` in `connection.json` ein; das Backend fasst die Datei dann nie wieder an. Eine Datei ganz ohne `managedBy` — vor diesem Verhalten geschrieben — übernimmt das Backend nur, wenn sie noch denselben Bucket am selben Endpoint nennt wie die Umgebung; hattest du sie von Hand umgebogen, bleibt deine Änderung stehen.

Bucket-Rechte: Das Backend prüft mit `HeadBucket`, ob der Bucket existiert, und legt ihn nur an, wenn nicht. Ein Schlüssel, der Objekte lesen, schreiben und löschen darf, aber keine Buckets anlegen, reicht also — solange du den Bucket selbst anlegst. Presignte Up- und Downloads laufen im Browser, ein externer Bucket braucht deshalb zusätzlich eine CORS-Policy, die den Origin deines Deployments mit `GET`, `PUT` und `HEAD` zulässt — siehe [Datenresidenz](https://docs.tale.dev/de/self-hosted/configuration/data-residency).

## Datenschutz im Audit-Log

Ein Pepper pseudonymisiert personenbezogene Daten fehlgeschlagener Anmeldungen. Frühere Releases haben zusätzlich `TALE_AUDIT_SIGNING_KEY` und `TALE_AUDIT_SIGNING_KEY_PREVIOUS` erzeugt. Beide liest nichts mehr, einen vorhandenen Wert kannst du also behalten oder löschen.

| Name                              | Default                       | Beschreibung                                                                                                                                                                                                                                                                                                                                                                                                                              |
| --------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TALE_AUDIT_PEPPER` | von `tale init` autogeneriert | Mindestens 16 Zeichen für die Pseudonymisierung fehlgeschlagener Anmeldungen: HMAC-SHA256 aus E-Mail und gekürzter IP-Adresse. Ohne Wert enthalten diese Audit-Felder Klartext und das Backend warnt. Nach einer Rotation lassen sich neue Kennungen nicht mit früheren vergleichen. Die Aufbewahrung folgt der angewendeten Organisationsrichtlinie. |

Siehe [Audit-Log-Integrität](https://docs.tale.dev/de/self-hosted/operate/security/audit-log-integrity) für das Verifikationsmodell.

## Observability

| Name                        | Default | Beschreibung                                                                                                                                 |
| --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `SENTRY_DSN`                | unset   | Sentry-DSN für Error-Tracking. Unset zum Deaktivieren. Kompatibel mit selbst gehostetem GlitchTip und Bugsink.                               |
| `SENTRY_ENVIRONMENT` | unset | Gemeinsame Umgebungsbezeichnung für Fehler aus Browser, Backend und Sandbox. Verwaltete Deployments verwenden standardmäßig ihren bestehenden `name`; eine explizite Umgebungsreferenz kann eine kanonische Bezeichnung setzen, ohne das Deployment umzubenennen. |
| `SENTRY_TRACES_SAMPLE_RATE` | unset | Optionale Abtastrate für Leistungstraces im Browser (`0.0`–`1.0`), unabhängig von der Backend-Abtastrate. |
| `BACKEND_SENTRY_TRACES_SAMPLE_RATE` | `0` | Abtastrate für HTTP- und Worker-Spans im Backend (`0.0`–`1.0`). Erfordert `SENTRY_DSN` und ein Ziel, das Sentry-Transaktionen annimmt; `0` deaktiviert Spans. |
| `METRICS_BEARER_TOKEN` | unset | Bearer-Token für die Proxy-Routen `/metrics/*`. Ohne konfigurierten Token antworten sie mit 401. Den Netzwerkzugriff auf interne Prozessendpunkte musst du gesondert beschränken. |
| `UMAMI_URL` | nicht gesetzt | HTTPS-Origin des authentifizierten Erfassungs-Gateways. HTTP ist nur für lokale Tests mit `localhost`, `127.0.0.1` oder `[::1]` zulässig. Erfordert gültige Website-ID und Proxy-Token; die URL enthält weder Pfad noch Suchparameter oder Zugangsdaten. |
| `UMAMI_WEBSITE_ID` | nicht gesetzt | Website-UUID von Umami. Fehlt sie oder ist sie ungültig, bleibt die Erfassung aus. Verwende je Deployment eine eigene ID. |
| `UMAMI_PROXY_TOKEN` | nicht gesetzt | Bearer-Token für das Erfassungs-Gateway, ausschließlich auf dem Server: 16–256 ASCII-Buchstaben, Ziffern oder Zeichen aus `._~-`. Übergib es niemals an die Browserkonfiguration. |

Mit `METRICS_BEARER_TOKEN` schützt der Proxy die Routen `/metrics/platform`, `/metrics/backend` und `/metrics/sla-rules`. [Überwachung einrichten](https://docs.tale.dev/de/self-hosted/configuration/observability-config) erklärt Inhalt und Grenzen der Messwerte.

## Provider-Secrets-Verschlüsselung

SOPS schützt unterstützte Geheimnisdateien der Konfiguration. Aktuelle Anbieterzugangsdaten in der Datenbank verwenden `ENCRYPTION_SECRET_HEX` aus dem Abschnitt zu Sicherheitsgeheimnissen.

| Name | Standard | Beschreibung |
| --- | --- | --- |
| `SOPS_AGE_KEY` | nicht gesetzt | Ein direkt gesetzter privater age-Schlüssel. Hat Vorrang vor der Schlüsseldatei. |
| `SOPS_AGE_KEY_FILE` | nicht gesetzt | Im lesenden Prozess erreichbarer Pfad mit einem oder mehreren privaten age-Schlüsseln, je einer pro Zeile. Binde die Datei in jeden benötigten Container ein. |

Ohne age-Schlüssel schreibt der SOPS-Helfer unterstützte Geheimnisdateien als Klartext mit Modus `0600`. Bereits verschlüsselte Dateien brauchen weiterhin ihren Schlüssel. Lies [Geheimnisse mit SOPS](https://docs.tale.dev/de/self-hosted/configuration/secrets-with-sops), bevor du eine der Variablen änderst.

Anbieterzugangsdaten können stattdessen eine Variable mit Präfix `TALE_PROVIDER_KEY_` und höchstens 40 Zeichen referenzieren. Zugangsdaten für Abonnement-Broker verwenden das getrennte Präfix `TALE_TOKEN_SOURCE_` mit höchstens 60 Zeichen. Diese Felder speichern Variablennamen, keine Geheimniswerte. Übergib Werte an die Backend-Prozesse und erstelle betroffene Container nach Änderungen neu. [Anbieter](https://docs.tale.dev/de/self-hosted/configuration/providers) beschreibt die Einrichtung.

## Connector-OAuth-Apps

OAuth-Connectoren (Gmail, Google Drive, Outlook, Teams, Slack, …) lösen ihre Vendor-App zuerst pro Organisation auf: Eine unter **Einstellungen > Connectors > OAuth-Apps** hinterlegte App gewinnt für diese Org. Die Umgebung liefert darunter den deployment-weiten Standard (und ist die einzige Quelle für Slack, dessen Event-Signaturprüfung läuft, bevor eine Org bekannt ist). Pro Connector-Slug:

| Name                                   | Default | Beschreibung                                                                                                   |
| -------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
| `CONNECTOR_OAUTH_<SLUG>_CLIENT_ID`     | unset   | OAuth-Client-ID für diesen Connector. Slug großgeschrieben, Bindestriche als Unterstriche (`gmail` → `GMAIL`). |
| `CONNECTOR_OAUTH_<SLUG>_CLIENT_SECRET` | unset   | Passendes Client-Secret.                                                                                       |
| `CONNECTOR_SLACK_SIGNING_SECRET`       | unset   | Das Signing-Secret der Slack-App. Der eingehende Events-Endpunkt prüft jede Zustellung damit und antwortet mit 503, solange es fehlt. |

Registriere `${SITE_URL}${BASE_PATH}/api/connectors/oauth2/callback` in der Vendor-App, für Slack zusätzlich `${SITE_URL}${BASE_PATH}/api/connectors/slack/events` als Events Request URL. Details: [Connectors (Develop)](https://docs.tale.dev/de/develop/connectors).

## Knowledge-Cloud-Import (Dokumente)

Pro-Benutzer-Autorisierungen für OneDrive / Google Drive unter **Wissen → Dokumente** sind getrennt von Org-Connectors und vom Login. Auch hier hat eine unter **Einstellungen > Connectors > OAuth-Apps** hinterlegte Org-App Vorrang — der **google-drive**-Eintrag wird mit der Connector-Bahn geteilt, **OneDrive / SharePoint (Wissens-Import)** hat einen eigenen Eintrag; die Ketten unten greifen überall dort, wo die Org keine hinterlegt hat. Registriere diese Redirect-URI in der Microsoft- (oder Google-)App:

`${SITE_URL}${BASE_PATH}/api/cloud-import/oauth2/callback`

Credential-Auflösung für OneDrive (erster Treffer gewinnt):

| Name                                           | Beschreibung                             |
| ---------------------------------------------- | ---------------------------------------- |
| `CLOUD_IMPORT_MICROSOFT_CLIENT_ID` / `_SECRET` | Eigene Knowledge-Import-App (bevorzugt). |
| `CLOUD_IMPORT_MICROSOFT_TENANT_ID`             | Directory-(Tenant-)ID für diese App.     |
| `AUTH_MICROSOFT_ENTRA_ID_ID` / `_SECRET`       | Microsoft-Login-App.                     |
| `AUTH_MICROSOFT_ENTRA_ID_TENANT_ID`            | Directory-(Tenant-)ID für die Login-App. |

Single-Tenant-Entra-App-Registrierungen brauchen eine tenant-spezifische Authorize-URL — `/common` scheitert mit AADSTS50194. Setze die Tenant-ID (oder `organizations` / `common` für eine Multi-Tenant-App). Fehlt sie, fällt Tale auf den Entra-SSO-Issuer-Tenant der Organisation zurück, falls konfiguriert.

Der Microsoft-Freigabe-Dialog fordert Graph **Files.Read** und **Sites.Read.All** (OneDrive und SharePoint listen/laden), **User.Read** (Konto-Label) und **offline_access** (Refresh-Token für Sync). Die Freigabe ist absichtlich und pro Benutzer — sie kommt nicht mit der Tale-Anmeldung.

Google Drive nutzt nur eine eigene App (kein Login-App-Fallback):

| Name                                              | Beschreibung                       |
| ------------------------------------------------- | ---------------------------------- |
| `CLOUD_IMPORT_GOOGLE_DRIVE_CLIENT_ID` / `_SECRET` | Knowledge-Google-Drive-Import-App. |

Registriere dieselbe Cloud-Import-Callback-URI am Google-OAuth-Client. Die Freigabe fordert **drive.readonly** und **userinfo.email**.

## Feature-Flags

Diese Variablen steuern Backend-Anmeldung, Datei-Ereignisse und Betreiberrechte. Erstelle die betroffenen Backend-Rollen nach einer Umgebungsänderung neu. Nur den Webcontainer zu ändern reicht nicht aus.

| Name                              | Default                  | Beschreibung                                                                                                                                                                                                                                 |
| --------------------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TRUSTED_SECRET_HEADER` | `Remote-Internal-Secret` | Name des Request-Headers, der den Trusted-Header-Schlüssel der Organisation auf der Übergabeanfrage trägt. |
| `TRUSTED_EMAIL_HEADER`            | `Remote-Email`           | Name des Request-Headers mit der E-Mail-Adresse des Benutzers — die Identität, für die die Session ausgestellt wird.                                                                                                                         |
| `TRUSTED_NAME_HEADER`             | `Remote-Name`            | Name des Request-Headers mit dem Anzeigenamen. Fehlt er, nimmt Tale den lokalen Teil der E-Mail-Adresse.                                                                                                                                     |
| `TRUSTED_ROLE_HEADER` | `Remote-Role` | Name des Request-Headers mit der Organisationsrolle, mit der die Session handelt, begrenzt auf die Obergrenze der Organisation (`member`, wenn der Header fehlt). |
| `TRUSTED_TEAMS_HEADER`            | `Remote-Teams`           | Name des Request-Headers mit den Team-Zugehörigkeiten als kommagetrennte Teamnamen (`id:name`-Einträge werden ebenfalls akzeptiert). Fehlt er, bleiben Teams unangetastet; ist er gesetzt, gilt die Liste des Proxys für die von ihm vergebenen Zugehörigkeiten (leer entzieht sie). |
| `TALE_FILE_EVENTS`                | `false`                  | Streamt Änderungen an Config-Dateien unter `TALE_CONFIG_DIR` an offene Browser-Tabs (`/events/file`): Eine auf der Platte bearbeitete Agent-, Skill- oder Branding-Datei erscheint ohne Reload. Im Dev-Compose an, in Produktion aus.        |
| `TALE_DEPLOYMENT_CONFIG_ADMINS`   | unset                    | Kommagetrennte E-Mail-Allowlist der Operatoren, die die Deployment-Konfigurationsdatei (`deployment.yml`, heute der Abschnitt zur Sandbox-Runtime) über die API schreiben dürfen. Leer/nicht gesetzt = nur lesend für alle Admins. Die Datenresidenz wird pro Organisation konfiguriert und hängt nicht an dieser Liste. |
| `TALE_ALLOW_PRIVATE_PROVIDER_HOSTS` | nicht gesetzt | Mit `1` in der Backend-Umgebung private Modellanbieter zulassen, einschließlich ihrer Sandbox-Gateway-Konfiguration. Cloud-Metadatenziele bleiben gesperrt. Siehe [Anbieter](https://docs.tale.dev/de/self-hosted/configuration/providers). |
| `TALE_ALLOW_PRIVATE_CRAWL_HOSTS` | nicht gesetzt | Mit `1` Intranet-Crawl-Ziele und private Hosts in der `imageUrl` eines Produkts zulassen. Cloud-Metadatenziele bleiben gesperrt. |
| `TALE_ALLOW_OPEN_SIGN_UP` | nicht gesetzt | Genau `true` hält `POST /api/auth/sign-up/email` auch nach dem ersten Konto der Installation offen. Nur für Wegwerf-Teststacks — der lokale Dev-Orchestrator und das Dev-Compose-Overlay setzen es selbst. Eine echte Installation lässt es ungesetzt, damit jedes weitere Konto von einer Administratorin oder einem Administrator angelegt wird. |
| `TALE_ORGANIZATION_CREATORS` | nicht gesetzt | Kommagetrennte E-Mail-Allowlist der Konten, die eine Organisation erstellen dürfen, verglichen ohne Rücksicht auf Groß- und Kleinschreibung. Ungesetzt darf das jede angemeldete Person. Gesetzt wird jede andere Person mit `403 ORGANIZATION_CREATION_FORBIDDEN` abgewiesen, sobald die Installation eine Organisation hat — die erste ist immer erlaubt — und die App blendet **Organisation erstellen** für sie aus. Ein gesetzter, aber leerer Wert schließt die Erstellung für alle. Ein verwaltetes Deployment schreibt die Variable aus `organizations.creators` seiner Spezifikation; siehe [Die tale-CLI installieren](https://docs.tale.dev/de/self-hosted/install/cli-install#managed-organization-creators). |

Die Freigabe privater Crawl-Ziele betrifft zwei Grenzen: Website-Registrierung und Crawler-Anfragen sowie die Validierung der `imageUrl` eines Produkts. Ohne Freigabe erhält ein privates Website-Ziel `400 WEBSITE_DOMAIN_NOT_CRAWLABLE`; eine private Produktbild-URL erhält `400 INVALID_BODY`. Bei Produktbildern wird nur die Hostzeichenfolge geprüft, ohne Bildabruf oder DNS-Auflösung. Website-Registrierung und Crawler prüfen zusätzlich die aufgelösten Adressen. Aktiviere die Variable nur, wenn die Installation diese privaten Ziele braucht. Sie ist unabhängig von der Freigabe privater Modellanbieter.

## Deployment-Topologie

Diese Werte prägen die Anwendungsrollen eines Workspace-Deployments: die Replikatzahlen, die `tale deploy` aus der Projektumgebung liest und mit einer Warnung auf den unterstützten Bereich begrenzt, und wie viel Arbeit ein einzelnes Worker-Replikat gleichzeitig übernimmt.

| Name                           | Default | Beschreibung                                                                                             |
| ------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------- |
| `TALE_PLATFORM_REPLICAS`       | `1`     | Replicas des Web-Tiers, der die App-Shell ausliefert. Bereich `1`–`16`.                                    |
| `TALE_BACKEND_API_REPLICAS`    | `1`     | Replicas der API — jede Anwendungstür, Auth und der Hint-Stream. Bereich `1`–`16`.                         |
| `TALE_BACKEND_WORKER_REPLICAS` | `1`     | Replicas des Job-Runners: Ingest, Crawls, Automations, Agent-Turns. Bereich `1`–`16`.                      |
| `WORKER_CONCURRENCY`           | `5`     | Jobs, die ein `backend-worker`-Replikat je Job-Warteschlange gleichzeitig ausführt — Ingest, Crawls, Automations und Agent-Turns erhalten jeweils so viele. Agent-Turn-Starts erhalten mindestens 8 und die Abarbeitungsfenster laufender Agent-Turns mindestens 16 je Warteschlange, da jedes vor allem auf seine Sandbox wartet (`AGENT_START_SLOTS`, `AGENT_DRIVE_SLOTS`). Der Worker-Prozess liest sie selbst; Bereich `1`–`64`. Stell zuerst diesen Wert höher, bevor du Worker-Replikate hinzufügst, wenn ein Rückstand wächst. Jeder laufende Indexierungsjob schreibt über den Wissens-Pool, also erhöhe `KNOWLEDGE_DB_POOL_MAX` mit. |
| `AGENT_START_SLOTS` | `WORKER_CONCURRENCY`, mindestens `8` | Agent-Turn-Starts, die ein `backend-worker`-Replikat gleichzeitig ausführt, jeweils für Aufgabenläufe und für Automations-Schritte. Ein Start belegt seinen Platz während der Sandbox-Erstellung und des ersten 90-Sekunden-Fensters des Turns. Bereich `1`–`256`. |
| `AGENT_DRIVE_SLOTS` | `WORKER_CONCURRENCY`, mindestens `16` | Abarbeitungsfenster laufender Agent-Turns, die ein `backend-worker`-Replikat je Bereich gleichzeitig ausführt. Ein Replikat hält etwa das 2,5-Fache an laufenden Turns je Bereich abgearbeitet; darüber warten Fenster so lange, dass die Wiederherstellung eingreift. Erhöhe den Wert (oder füge Replikate hinzu) für mehr gleichzeitige Turns. Bereich `1`–`256`. |
| `TALE_BACKEND_URL` | `http://backend-api:3005` | Wo der Web-Tier das Anwendungs-Backend erreicht: Die öffentliche `/status`-Seite prüft es darüber, und der Webserver holt sich dort die Antworten, die nur eine Datenbank geben kann. Das mitgelieferte Compose und der Container-Entrypoint setzen den In-Compose-Alias als Default; setze die Variable nur, wenn dein Backend-Service anders heißt. Liest nur der `platform`-Service. |

Bei einem Workspace-Deployment laufen vorübergehend beide Farben. Plane Kapazität für diese Überschneidung. Erhöhe die Rolle, deren gemessene Last den Engpass bildet. Mehr Replikate brauchen auch mehr Datenbankverbindungen und Arbeitsspeicher. Siehe [Upgrades](https://docs.tale.dev/de/self-hosted/operate/upgrades).

## Sitzungen

| Name                           | Default | Beschreibung                                                                                                                                                                                                                     |
| ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SESSION_IDLE_TIMEOUT_MINUTES` | unset   | **Optional.** Meldet eine Sitzung nach so vielen Minuten Inaktivität ab (`1`–`1440`). Das Fenster verschiebt sich bei Aktivität und wird serverseitig durchgesetzt — über E-Mail-/Passwort-, SSO- und Trusted-Headers-Sitzungen. |

Ohne Wert gilt die normale Sitzungsdauer. Mit gesetztem Limit läuft eine inaktive Sitzung serverseitig ab; Aktivität verschiebt das Fenster. Organisationsadmins können es über die [Richtlinie zur Sitzungsinaktivität](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits) weiter verkürzen. Die zugehörige Bereinigung läuft ungefähr alle fünf Minuten.

## Support-Link

| Name                       | Default                    | Beschreibung |
| -------------------------- | -------------------------- | ------------ |
| `TALE_CONTACT_SUPPORT_URL` | `https://tale.dev/contact` | **Optional, gelesen vom Dienst `platform`.** Ziel des Links **kontaktiere den Support** auf den Fehlerseiten der App. Eine absolute `http://`- oder `https://`-URL. |

Trag hier deinen eigenen Helpdesk ein, damit Personen nach einem Fehler das Team erreichen, das dein Deployment betreibt. Kennt die Fehlerseite die Organisation, hängt der Link `organizationId=<id>` an den Query-String an, hinter eine bereits vorhandene Query, und ersetzt einen `organizationId`-Parameter, den die URL schon trägt. Jeder andere Wert, etwa `mailto:` oder eine URL ohne Schema, wird mit einer Warnung im Log des Dienstes `platform` ignoriert, und der Link behält den Standardwert.

## Sandbox-Infrastruktur {#sandbox-infrastructure}

Der Sandbox-Spawner liest die folgenden Einstellungen. Übergib sie seiner Umgebung und erstelle den Dienst nach einer Änderung neu. `SANDBOX_MAX_SESSIONS` legt die gemeinsame Kapazität aller Organisationen fest. Die drei Arbeitslimits einer Organisation ergeben automatisch ihre Gesamtsumme; liegt sie über dieser Kapazität, kannst du die Limits nicht speichern. Unter [Sandboxes](https://docs.tale.dev/de/platform/admin/sandboxes) verwaltest du die Limits und siehst tatsächliche Laufzeitzahlen und Host-Messwerte getrennt von der Kontingentbelegung.

| Name | Default | Beschreibung |
| --- | --- | --- |
| `SANDBOX_MAX_SESSIONS` | auf einem lokalen Docker-Host nach dem Host-Speicher bemessen (mindestens `8`, höchstens `256`); sonst `8` | Höchstzahl laufender und startender Sessions aller Organisationen auf dem Docker-Host oder im Kubernetes-Namespace, einschließlich weiterlaufender Container im Leerlauf. Die Kapazität reserviert weder CPU noch Arbeitsspeicher. Fehlt die Variable auf einem Docker-Host, dessen Speicher der Spawner lesen kann, bemisst er sie nach diesem Speicher: eine Session je 768 MiB, die nach `SANDBOX_MIN_FREE_MEMORY` übrig bleiben, oder je 1,5 GiB, wenn Agent-Sessions Docker in der Sandbox betreiben. Lässt sich der Speicher beim Start nicht lesen, bleibt die Kapazität bei `8`, bis er lesbar ist. Ein expliziter Wert legt sie fest. Gleichzeitige Kubernetes-Replikate setzen sie nach bestem Bemühen durch; harte Ressourcengrenzen im Namespace setzt du mit ResourceQuota. |
| `SANDBOX_MIN_FREE_MEMORY` | ein Zehntel des Host-Speichers, mindestens `1g` | Speicher, den eine neue Session oder eine freigegebene, noch laufende Session bei der Wiederaufnahme auf einem lokalen Docker-Host frei lassen muss, neben dem, was noch startende und eben gestartete Sessions gleich belegen werden. Würde ein Start weniger übrig lassen, stoppt der Spawner zuerst eine freigegebene Session im Leerlauf; reicht der Speicher dann immer noch nicht, antwortet er mit „beschäftigt“, und die Arbeit wartet, bis laufende Sessions Speicher freigeben. Akzeptiert Größen wie `2g` oder `1536m`. Wirkt nicht unter Kubernetes oder mit einem entfernten Docker-Daemon. |
| `SANDBOX_MIN_FREE_DISK` | ein Zwanzigstel jedes Datenträgers, mindestens `2g`, höchstens `20g` | Freier Speicher für neue und reaktivierte Sitzungen im Dateisystem der Arbeitsbereiche und im verifizierten Docker-Daten-Dateisystem. Unterhalb der Grenze wartet die Arbeit; gestoppte, ungenutzte Build-Caches werden zuerst entfernt. Akzeptiert `10g` oder `4096m`; `0` deaktiviert die Prüfung. Kubernetes stützt sich auf Storage-Klasse und Volume-Bereitstellung. |
| `SANDBOX_DOCKER_WORKLOADS` | `project,workflow` | Workloads, die Docker in ihrer Sandbox nutzen dürfen, wenn es für das Deployment aktiviert ist. Mit `project` starten Workflow-Agenten ohne Docker, mit `workflow` gilt das für Projektagenten und mit `none` für beide. Die Einstellung gilt für neu erstellte Sessions; bestehende behalten ihre Fähigkeiten. Eine Session-Anfrage kann Docker mit `docker: false` abwählen, aber weder diese Liste noch die Deployment-Einstellung erweitern. |
| `SANDBOX_AGENT_CPUS` | `2` | CPU-Grenze je Agent-Session. Berücksichtige bei der Session-Anzahl gleichzeitig laufende Builds und andere Aufgaben auf dem Host. |
| `SANDBOX_AGENT_MEMORY` | `4g`; `8g` mit Docker in der Sandbox | Speichergrenze je Agent-Session, die auch für ihren inneren Docker-Daemon und dessen Container gilt. Ein expliziter Wert ersetzt beide Standardwerte und gilt für neu erstellte Sessions. |
| `SANDBOX_AGENT_PROFILE` | `agent` | Wird von Backend-API und Worker gelesen. Profil für neue Agenten- und Workflow-Arbeitsbereiche: `agent` unterstützt inneres Docker; `agent-light` behält Coding-Werkzeuge und den persistenten Arbeitsbereich, ohne Docker oder Build-Cache-Helfer zu starten. Bestehende Arbeitsbereiche behalten ihr gespeichertes Profil. |
| `TALE_SANDBOX_CLAUDE_EFFORT` | nicht gesetzt (übernimmt den Harness-Standard) | Wird von Backend-API und Worker gelesen. Denktiefe von Claude Code: `low`, `medium`, `high` oder `max`. Niedrigere Werte lassen die automatische Ultrathink-Anweisung weg und setzen den Wert pro Ausführung; adaptives Denken bleibt aktiv. Andere Harnesses und fremde Modelle bleiben unverändert. Vergleiche repräsentative Aufgaben, bevor du den Wert senkst; kürzere Läufe sind nicht garantiert. |
| `SANDBOX_SESSION_CREATE_TIMEOUT_MS` | `180000` | Gesamtbudget für den Sitzungsstart, einschließlich optionalem Build-Cache, Container- oder Pod-Start, Daemon-Bereitschaft und Umgebungsübergabe. Ein abgebrochener Request bricht seine Sitzungsstartarbeiten ab; die Bereinigung stoppt Compute und erhält den Arbeitsbereich. Die gemeinsame Cache-Vorbereitung hat eine eigene begrenzte Laufzeit. |
| `SANDBOX_DOCKER_DATA_ROOT` | nicht gesetzt | Optionaler Host-Pfad, der Dockers `DockerRootDir` entspricht. Die CLI bindet ihn schreibgeschützt in den Sandbox-Dienst ein. Bei direktem Compose ist der unten gezeigte Mount erforderlich. |
| `SANDBOX_DOCKER_DATA_PATH` | `/var/lib/tale-sandbox/docker-data`, wenn der Root-Pfad gesetzt ist | Pfad dieses schreibgeschützten Mounts im Spawner. Die Zulassung prüft dieses Dateisystem zusätzlich zum Arbeitsbereich. Ein konfigurierter Mount, der nicht verifiziert oder gelesen werden kann, blockiert die Zulassung. |
| `SANDBOX_BUILDKITD_CPUS` | `SANDBOX_AGENT_CPUS` | CPU-Grenze des Build-Cache-Hilfscontainers einer Organisation, der die Image-Builds all ihrer Agent-Sessions ausführt, wenn Docker in der Sandbox läuft. Laufende Hilfscontainer übernehmen einen neuen Wert sofort. Die Anzahl paralleler BuildKit-Solver-Schritte entspricht diesem abgerundeten CPU-Limit, mindestens jedoch eins; diese Grenze gilt nach dem Neuerstellen eines inaktiven Hilfscontainers. |
| `SANDBOX_BUILDKITD_MEMORY` | das Doppelte von `SANDBOX_AGENT_MEMORY` | Speichergrenze des Build-Cache-Hilfscontainers einer Organisation, die sich die gleichzeitigen Builds ihrer Agent-Sessions teilen. Akzeptiert Größen wie `16g` oder `12288m`. Ein laufender Hilfscontainer übernimmt einen neuen Wert, wenn er neu erstellt wird, sobald kein Build läuft. |
| `SANDBOX_BUILDKITD_IDLE_CACHE` | `5g` | Build-Cache, den der Build-Cache-Hilfscontainer einer Organisation behält, wenn er mangels Agent-Sessions stoppt. Unmittelbar vor diesem Stopp kürzt der Spawner den Cache auf diese Größe, die am längsten ungenutzten Einträge zuerst: Die eigene Speicherbereinigung des Caches läuft nur, solange der Hilfscontainer läuft. Akzeptiert Größen wie `5g` oder `2048m`; `0` behält nichts. |
| `SANDBOX_BUILDKITD_PROVISION_TIMEOUT_MS` | `5000` | Gesamtes Zeitbudget in Millisekunden für den optionalen gemeinsamen Build-Cache beim Erstellen einer Sitzung, einschließlich wartender Docker-Aufrufe und Registry-Spiegel. Bereich `100`–`60000`. Läuft das gemeinsame Zeitbudget ab, werden wartende Hilfscontainer-Aufrufe abgebrochen und später nicht mehr gestartet; die Session nutzt ihren lokalen Builder. |
| `SANDBOX_BUILDKITD_CACHE_RETENTION` | `14d` | Wie lange die gestoppten Build-Cache-Hilfscontainer einer Organisation ihre Caches behalten. Ist der Builder länger gestoppt und kann keine Session der Organisation ihn nutzen, entfernt der Spawner ihre Hilfscontainer, ihr Netzwerk und ihre Cache-Volumes, wie beim Löschen einer Organisation; ihr nächster Build startet ohne Cache. Akzeptiert ganze Tage oder Stunden wie `14d` oder `336h`; `off` (oder `0`) behält die Caches, bis die Organisation gelöscht wird. |
| `SANDBOX_SESSION_MAX_IDLE_MS` | `1800000` (30 Min.) | Leerlauffenster, nach dem nicht angepinnte Sessions stoppen. Die Build-Cache-Hilfscontainer einer Organisation stoppen ebenfalls nach diesem Fenster ohne möglicherweise aktive Session; Netzwerke und Cache-Volumes bleiben erhalten. |
| `SANDBOX_SESSION_RELEASED_IDLE_MS` | `300000` (5 Min.) | Leerlauffenster für eine freigegebene Session, also eine, deren Aufgabe oder Lauf beendet ist und die keine andere Arbeit mehr belegt. Eine nicht angepinnte, freigegebene Session stoppt nach dieser Leerlaufzeit, statt `SANDBOX_SESSION_MAX_IDLE_MS` abzuwarten; die nächste Runde setzt sie auf ihrem erhaltenen Arbeitsverzeichnis fort. Agent-Sessions mit Docker in der Sandbox behalten das volle Leerlauffenster, weil ihr innerer Docker-Daemon bei jeder Fortsetzung mit einem leeren Image-Speicher startet. |
| `SANDBOX_RUNTIME_IMAGE`          | `tale-sandbox-runtime:latest` | **Optional, vom Spawner gelesen.** Das Image, aus dem jeder Session-Container entsteht. Der Default ist der Tag, den der Entwicklungs-Stack lokal baut; ein Host, der seine Images zieht, setzt deshalb den Registry-Namen: `ghcr.io/tale-project/tale/tale-sandbox-runtime:<version>`, passend zum Rest des Stacks. `tale deploy` setzt ihn für dich. |
| `SANDBOX_DIND_INNER_POOL` | nicht gesetzt (automatisch) | Optionaler Adresspool für den inneren Docker-Daemon in Agent-Sessions auf Docker oder Kubernetes. Verwende ein kanonisches privates IPv4-`/16` nach RFC1918 außerhalb deiner Pod-, Service- und VPC-Netze. Die Runtime lehnt Überschneidungen mit erkannten Netzen und Adressen ab. |
| `SANDBOX_EGRESS_MAX_CLIENTS` | `2000` | **Vom Dienst `sandbox-egress` gelesen**, nicht vom Spawner: Erstelle diesen Dienst nach einer Änderung neu. Verbindungen, die der Egress-Proxy für alle Sessions zusammen gleichzeitig bedient; mit transparentem Egress läuft jede ausgehende Verbindung einer Session, ihrer Builds und ihrer Paketinstallationen über ihn. Jenseits der Grenze lehnt der Proxy neue Verbindungen ab, und Installationen und Seitenaufrufe brechen mit zurückgesetzten Verbindungen ab. Jede Verbindung belegt einen Thread und zwei offene Dateien, deshalb bemessen die mitgelieferten Compose-Dateien die Prozess- und Dateigrenzen des Proxys für den Default; ein höherer Wert braucht auch höhere Grenzen, und der Proxy warnt beim Start, wenn seine Grenze für offene Dateien zu niedrig ist. Beim Start hebt der Proxy seine Grenze für offene Dateien auf das an, was die Verbindungen brauchen, so weit die harte Grenze des Containers es erlaubt. Unter Kubernetes setzt du ihn am Egress-Deployment; eine Pod-Spezifikation setzt keine Prozessgrenze, daher muss das `podPidsLimit` des Nodes Platz für einen Thread je Verbindung lassen. |

Die Backend-Einstellungen oben müssen API und Worker erreichen. Erstelle beide Dienste nach einer Änderung neu. Der Spawner prüft freien Arbeitsspeicher und Plattenplatz auch beim erneuten Belegen einer freigegebenen Sitzung; daher kann auch ein warmer Arbeitsbereich auf Kapazität warten.

Verbundene Geräte prüfen Arbeitsspeicher und freien Speicherplatz nach denselben Regeln wie ein lokaler Docker-Host; ihre konfigurierte Session-Obergrenze bleibt bestehen.

Ein absichtlich gestoppter Docker-Daemon bleibt für den nächsten Befehl bereit; Zustandsprüfungen starten ihn nicht. Eine fehlgeschlagene Prüfung sperrt sofort neue Arbeit, stoppt aber allein noch nicht die Session. Dafür müssen mindestens drei abgeschlossene Prüfungen über einen Zeitraum von mindestens fünf Sekunden fehlschlagen. Eine erfolgreiche Prüfung oder eine neue Engine setzt diese Fehlerhistorie zurück. Ein bestätigter Startfehler oder ein unerwartetes Ende der Engine kann die Wiederherstellung sofort auslösen. Der Spawner kann dann eine inaktive, nicht angepinnte Session nach einer atomaren Aktivitätsprüfung stoppen und ihren Arbeitsbereich für den nächsten Start behalten. Unter Docker geht beim Stoppen der gesamten Session ihr innerer Docker-Speicher verloren; beim automatischen Leerlaufstopp nur der inneren Engine bleibt er erhalten. Beschäftigte oder angepinnte Sessions bleiben bestehen und lehnen neue Starts ab, bis Docker wieder antwortet oder der Betreiber die Störung behebt.

Behalte bei einem schrittweisen Upgrade für jeden alten Spawner sein bisheriges, fest referenziertes Runtime-Image bei, bis der Spawner ersetzt ist. Ändere keinen Runtime-Tag, den ein alter Spawner noch verwendet: Er unterscheidet vorübergehende Prüfungsfehler nicht von bestätigten Ausfällen. Ein neuer Spawner mit einer älteren Runtime lehnt neue Arbeit bei einem fehlerhaften Zustand ab und behält die üblichen Grenzen für Leerlauf und Lebensdauer bei.

Ein Spawner im Container prüft Dockers Daten-Dateisystem automatisch, wenn sich sein vorhandener `/etc/hostname`-Mount anhand des Daemons verifizieren lässt. Gelingt die Erkennung nicht, bleibt die Prüfung der Arbeitsbereiche aktiv; `/health` meldet die Docker-Datenträgerüberwachung als `unavailable`. Ein ausdrücklich konfigurierter, schreibgeschützter Mount des Docker-Datenverzeichnisses hat Vorrang. Lässt er sich nicht verifizieren oder lesen, wartet die Zulassung neuer Arbeit, bis er verfügbar ist. Lies zur Konfiguration `docker info --format '{{.DockerRootDir}}'` aus und verwende diesen tatsächlichen Host-Pfad. Docker Desktop und entfernte Daemons können einen anderen Aufbau benötigen. Ergänze bei direktem Compose den folgenden Override und übergib beide Variablen an den Sandbox-Dienst:

```yaml
services:
  sandbox:
    environment:
      SANDBOX_DOCKER_DATA_ROOT: ${SANDBOX_DOCKER_DATA_ROOT}
      SANDBOX_DOCKER_DATA_PATH: /var/lib/tale-sandbox/docker-data
    volumes:
      - ${SANDBOX_DOCKER_DATA_ROOT}:/var/lib/tale-sandbox/docker-data:ro
```

Eine Speichergrenze für die Zulassung ist keine Speicherquote pro Sitzung. Docker-Named-Volumes haben kein portables Größenlimit, und die Durchsetzung einer Kubernetes-PVC-Größenanforderung hängt vom Storage-Backend ab. Nutze für harte Quoten ein Dateisystem oder eine Storage-Klasse mit Quotenunterstützung. Überwache separat eingehängte containerd-Speicher, Volume-Verzeichnisse und externe Volume-Treiber zusätzlich zu Arbeitsbereichen, Image-Layern und Build-Caches.

Kubernetes-Sitzungen verwenden `/readyz` für die Startprüfung und `/livez` für die Lebendigkeitsprüfung des Daemons. Ein absichtlich gestoppter innerer Docker-Daemon gilt beim Start als bereit; ein laufender Docker-Daemon muss auf seine Gesundheitsprüfung antworten. Die Lebendigkeitsprüfung erfasst nur den Sandbox-Daemon, damit Fehler bei Abhängigkeiten keine beschäftigte Sitzung neu starten. Ein blockierter Daemon kann auch bei angehefteter Sitzung neu starten. Docker- und Egress-Diagnosen erscheinen unter `/healthz`.

Eine bereits aktive Generation wird nicht erneut angerechnet. Ein Workflow ohne inneres Docker behält die Identität und Werkzeuge seines Agenten, startet aber keinen Docker-Daemon und hält keine Build-Cache-Hilfscontainer aktiv. Ohne expliziten Wert für `SANDBOX_AGENT_MEMORY` gilt pro Session standardmäßig `4g` ohne inneres Docker oder `8g` mit Docker, auch wenn andere Sessions im Deployment Docker nutzen. Ein expliziter Wert gilt für beide Varianten. Die Grenzen sind Obergrenzen, kein reservierter Arbeitsspeicher.

Bei voller Kapazität kann der Spawner eine freigegebene, nicht angepinnte Session im Leerlauf schon vor Ablauf des Leerlauffensters stoppen, um neue Arbeit zuzulassen, zuerst die am längsten untätige. Der Daemon muss bestätigen, dass keine Arbeit läuft; beschäftigte Sessions und Sessions mit unbekanntem Zustand bleiben geschützt. Das dauerhafte Arbeitsverzeichnis oder Volume bleibt beim Stoppen erhalten. Lässt sich keine Session sicher freigeben, blockiert die Kapazitätsgrenze weiterhin neue Starts. Dasselbe gilt, wenn der freie Speicher des Hosts unter `SANDBOX_MIN_FREE_MEMORY` fallen würde. Solange der Datenträger mit den Arbeitsverzeichnissen der Sessions unter `SANDBOX_MIN_FREE_DISK` liegt, wartet neue Arbeit, ohne dass Sessions im Leerlauf gestoppt werden: Eine gestoppte Session behält ihr Arbeitsverzeichnis.

Datensätze im Harness-Protokoll, einschließlich unvollständiger Zeilen, sind auf 8 MiB begrenzt. Zu große oder unvollständige Ausgaben führen zu einem ausdrücklichen Fehler; eine begrenzte Fortschrittsvorschau gilt nie als vollständiges strukturiertes Ergebnis. Vollständige Endantworten bleiben getrennt von dieser Vorschau erhalten.

Auch die Wiederaufnahme einer freigegebenen, noch laufenden Session prüft die Speicherreserve und reserviert vorab den erwarteten Arbeitsspeicher. Gleichzeitige Wiederaufnahmen teilen sich diese Berechnung. Eine Antwort „beschäftigt“ lässt sich erneut versuchen; sie löscht weder das Arbeitsverzeichnis noch unterbricht sie bereits belegte Sessions. Diese Reservierungen begrenzen nicht den späteren Speicherzuwachs aktiver Werkzeuge oder der Builder einer Organisation.

Ist Docker in Agent-Sandboxes aktiviert, startet der Daemon automatisch beim ersten Docker-Befehl. Agenten müssen keinen Modus wählen. Nach fünf Minuten ohne verbundene Clients stoppt er nur, wenn kein Container läuft, neu startet oder pausiert ist und für alle Container die automatische Neustartregel deaktiviert ist; bei unbekanntem Zustand läuft er weiter. Der nächste Befehl startet ihn mit denselben Images, Volumes und demselben Arbeitsverzeichnis. Sind beim Start des Session-Containers bereits Container-Metadaten vorhanden, startet der Daemon sofort, damit die Neustartregeln weiterhin greifen. Isolation, Berechtigungen und Speichergrenzen des Deployments bleiben dabei unverändert.

### Session-Kapazität bemessen

Fehlt `SANDBOX_MAX_SESSIONS` auf einem Docker-Host, bemisst der Spawner die Kapazität nach dem Speicher des Hosts (ein Host mit 16 GiB erhält 19 Sessions, einer mit 64 GiB 76; 9 und 38, wenn Agent-Sessions einen eigenen Docker-Daemon betreiben) und lässt eine neue Session nur zu, solange der Host `SANDBOX_MIN_FREE_MEMORY` frei behält, wobei er mitzählt, was noch startende und eben gestartete Sessions gleich belegen werden. Eine Lastspitze neuer Sessions, die den Host überbuchen würde, wartet deshalb, statt zu starten; Sessions, die bereits laufen, hindert diese Prüfung nicht daran, weiter zu wachsen. Lege die Kapazität selbst fest unter Kubernetes, mit einem entfernten Docker-Daemon oder wenn auf dem Host auch andere speicherhungrige Dienste laufen: Teste dann die Aufgaben, die deine Bereitstellung gleichzeitig ausführen soll. Browser-Rendering und Docker-Builds haben unterschiedliche Lastspitzen; berücksichtige Agents, Workflows und Crawling aller Organisationen. Ein freier Session-Platz garantiert keine ausreichenden Ressourcen.

Miss unter Docker den Ressourcenbedarf, während typische Aufgaben gleichzeitig laufen. Wiederhole diesen Befehl während des Durchlaufs; eine Messung im Leerlauf zeigt keine Lastspitzen:

```bash
docker stats --no-stream --format 'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}'
```

Ziehe den Bedarf von Betriebssystem, Plattformdiensten, Datenbanken und Build-Cache-Hilfscontainern sowie eine Sicherheitsreserve vom Host-Speicher ab. Teile den verbleibenden Speicher durch den gemessenen Spitzenbedarf je aktiver Session und runde ab. Beispiel: Ein Host mit 32 GiB, davon 8 GiB für Dienste und Reserve, und einem gemessenen Spitzenbedarf von 3 GiB je Session ergibt `(32 - 8) / 3 = 8` Sessions. Das ist ein Rechenbeispiel, kein Benchmark. Bei gemischten Aufgaben addierst du die gleichzeitig auftretenden Spitzen. Prüfe außerdem CPU-Auslastung und Aufgabendauer, bevor du die Grenze erhöhst.

Die 4 GiB oder 8 GiB eines Agents sind eine Speicherobergrenze; beim Start reserviert er diesen Speicher nicht. Acht Agents mit laufenden Docker-Builds können daher deutlich mehr Speicher benötigen als acht überwiegend untätige Sessions. Miss unter typischer Last und halte Reserven frei. Erhöhe die Kapazität erst auf 16 oder mehr, wenn der Host die Last dauerhaft trägt. Verringere vor einer Absenkung alle Organisationssummen, die über dem neuen Wert liegen. Die Standardlimits einer Organisation ergeben 6; eine kleinere Bereitstellungskapazität braucht entsprechend kleinere Organisationslimits.

### Eine Kapazitätsänderung anwenden

Ergänze oder ändere diese Zeile in der `.env` deiner Bereitstellung. Behalte die übrigen Einträge bei. Explizite Werte gelten auch nach Upgrades weiter; ohne einen bemisst ein Docker-Host die Kapazität wie oben beschrieben nach seinem Speicher, und Kubernetes verwendet 8.

```dotenv .env
SANDBOX_MAX_SESSIONS=8
```

Erstelle bei einem selbst verwalteten Compose-Stack nur den Sandbox-Dienst mit seinem vorhandenen lokalen Image neu:

```bash
docker compose up -d --no-deps --no-build --pull never sandbox
```

Verwende dasselbe Projekt, dieselben `-f`-Dateien und dieselben Optionen für Umgebungsdateien wie beim laufenden Stack. Ein Neustart allein lädt eine geänderte `.env` nicht. Für CLI-verwaltete Installationen folgst du dem Deployment-Ablauf unter [Upgrades](https://docs.tale.dev/de/self-hosted/operate/upgrades). Setze unter Kubernetes die Variable im Deployment des Sandbox-Spawners und führe dessen Rollout aus.

Prüfe die neue Bereitstellungskapazität unter [Sandboxes](https://docs.tale.dev/de/platform/admin/sandboxes). Bei Organisationslimits von 2/2/2 und einer Kapazität von 8 zeigt die Summe **6 / 8**. Bestehende Organisationseinstellungen bleiben erhalten; zum Speichern muss ihre Summe weiterhin in die aktuelle Kapazität passen. Die Kapazitätsänderung erhöht keine CPU- oder Speichergrenze eines Containers.

### Nach einem Upgrade

Die Standardkapazität lag bisher bei 16, und Organisationen aus früheren Versionen wurden mit den Limits 2/4/4 angelegt, also einer Summe von 10. Eine Bereitstellung, die `SANDBOX_MAX_SESSIONS` nie gesetzt hat, startet mit der neuen Version daher mit einer Kapazität von 8 und Organisationen, deren gespeicherte Summe darüber liegt. Laufende Arbeit ist davon nicht betroffen, und jede Organisation lässt weiterhin Arbeit unter ihren gespeicherten Limits zu; nur das Speichern der Sandbox-Seite bleibt gesperrt, bis die Summe passt, und niedrigere Limits lassen sich weiterhin speichern. Setze entweder `SANDBOX_MAX_SESSIONS=16` explizit, um die bisherige Kapazität zu behalten, oder bitte jede betroffene Organisation, ein Limit zu verringern.

Ab dieser Version erhält eine Docker-Bereitstellung, die `SANDBOX_MAX_SESSIONS` nie gesetzt hat, eine nach dem Host-Speicher bemessene Kapazität statt 8, nie weniger als 8. Sie kann mehr Sessions gleichzeitig zulassen als zuvor, und das nur, solange der Host Speicher übrig hat. Setze einen expliziten Wert, um eine feste Kapazität zu behalten.

### Docker-Build-Caches

Die Vorbereitung des gemeinsamen Build-Caches verwendet `SANDBOX_BUILDKITD_PROVISION_TIMEOUT_MS` (standardmäßig 5 Sekunden). Eine Session wartet höchstens so lange oder ein Viertel ihres gesamten Startbudgets, falls das kürzer ist. Danach nutzt sie ihren lokalen Builder. Die gemeinsame Vorbereitung hat ein eigenes begrenztes Zeitbudget: Wird die Wartezeit einer Session abgebrochen, läuft die Vorbereitung für andere Sessions weiter. Eine Session, die bereits ihren lokalen Builder nutzt, wechselt bei einem verspäteten Ergebnis nicht nachträglich zum gemeinsamen Builder. Registry-Mirrors werden parallel vorbereitet. Die Zahl gleichzeitiger Schritte des gemeinsamen Builders ergibt sich aus seiner abgerundeten CPU-Grenze und beträgt mindestens eins; seine Speichergrenze gilt weiterhin. Die Vorbereitungszeit wird vom verbleibenden Startbudget der Session abgezogen.

Docker-Build-Caches sind nach Organisation getrennt. Jede Organisation nutzt einen privilegierten Builder und drei Registry-Mirrors ohne erhöhte Rechte. Sobald keine Session mehr auf sie zugreifen könnte, beginnt das Leerlauffenster; danach stoppen die Hilfscontainer. Der nächste Build startet sie mit ihren erhaltenen Cache-Volumes neu. Unmittelbar bevor der Builder stoppt, kürzt der Spawner seinen Cache auf `SANDBOX_BUILDKITD_IDLE_CACHE`, denn seine Speicherbereinigung läuft nur, solange er läuft. Der Cache einer gestoppten Organisation wird danach nicht weiter gekürzt; nach `SANDBOX_BUILDKITD_CACHE_RETENTION` (14 Tage) ohne Build werden ihre Hilfscontainer und Caches entfernt, sonst gehen sie mit der Organisation. Solange der Datenträger der Sessions unter `SANDBOX_MIN_FREE_DISK` liegt, gehen die Caches gestoppter Organisationen früher, die am längsten gestoppten zuerst. Netzwerke und Volumes bleiben für die Wiederverwendung bestehen. Kubernetes-Sessions nutzen ihren eigenen inneren Docker-Builder; der Kubernetes-Abgleich ruft für diese Hilfscontainer keine Docker-CLI auf.

Der Spawner füllt den ersten verfügbaren Docker-Adresspool mit Organisationsnetzwerken, bevor er zum nächsten wechselt. Standardmäßig erhält jedes Netzwerk ein `/23` mit 512 Adressen; ein ansonsten freies `/16` bietet damit Platz für 128 Organisationsnetzwerke. Kleinere in Docker konfigurierte Subnetze bleiben kleiner. Der Spawner schließt vorhandene Docker-Netzwerke, Routen und DNS-Serveradressen auf dem Host des Docker-Daemons sowie `172.31.0.0/16` für ältere Runtime-Images aus und prüft anschließend das angelegte Netzwerk.

Auch bei einem entfernten Docker-Daemon erfasst der Spawner dessen Host über einen kurzlebigen Container aus dem konfigurierten BuildKit-Image. Dieser läuft im Host-Netzwerk-Namespace mit schreibgeschütztem Dateisystem, ohne Capabilities und ohne Mounts. Scheitert diese Abfrage oder bleibt kein sicheres Subnetz frei, bauen Sessions lokal ohne gemeinsamen Cache. Ein ungenutztes eigenes Netzwerk mit ungültigem Subnetz legt der Spawner neu an; belegte und fremde Netzwerke bleiben erhalten.

Beim Upgrade entstehen leere Organisationscaches; die alten globalen Cachedaten bleiben erhalten. Alte Hilfscontainer stoppen automatisch, sobald keine laufende Session mehr auf sie angewiesen ist. Lass alte angepinnte Sessions auslaufen oder stoppe sie, um den Übergang abzuschließen; bis dahin bleibt der alte gemeinsame Cachedienst erreichbar. Browserautomatisierung nutzt Chromium ohne grafische Oberfläche. Die Live-Ansicht und manuelle Browserübernahme sind entfernt.

### Innere Docker-Netzwerke

Die automatische Auswahl prüft unter Docker und Kubernetes IPv4-Routen und Gateways aus allen Routingtabellen, Adressen und Präfixe der Schnittstellen, DNS-Server sowie die aufgelösten Adressen der beim Containerstart konfigurierten Proxy- und Gateway-Hosts. Hosts, die erst während eines Agent-Turns übergeben werden, fehlen in dieser anfänglichen Erfassung. Ein später angeschlossenes Docker-Organisationsnetzwerk berücksichtigt sie ebenfalls. Die Runtime bevorzugt ein freies `172.31.0.0/16` und prüft danach andere private `/16`-Bereiche. Das erste `/24` gehört zu `docker0`; innere Compose-Netzwerke erhalten `/24`-Blöcke aus demselben Pool. Im automatischen Modus startet die Session nicht, wenn Abfragen scheitern oder kein privater Bereich frei bleibt.

Aus seinem eigenen Netzwerk-Namespace kennt ein Pod nicht die vollständigen Pod-, Service- und VPC-CIDRs des Clusters. Setze für DinD auf Kubernetes `SANDBOX_DIND_INNER_POOL` auf ein privates `/16`, das du gegen all diese Netze geprüft hast. Auch ein vorgegebener Pool scheitert bei jeder erkannten Überschneidung oder einem ungültigen Wert. Bleiben einzelne Abfragen ohne Ergebnis, nennt die Runtime sie in einer Warnung und kann mit dem vorgegebenen Pool fortfahren. Den nicht sichtbaren Adressraum musst du selbst berücksichtigen.

Starte nach einer Änderung dieses Pools den Spawner neu und erstelle bestehende Sessions neu, damit sie den Wert übernehmen. Ein Runner-Neustart innerhalb desselben Kubernetes-Pods behält dessen Umgebung und den inneren Docker-Speicher bei.

Der Egress-Proxy erlaubt DNS-Anfragen an die geprüften Nameserver-IP-Adressen aus seiner `/etc/resolv.conf`, auch an einen privaten Cluster-DNS-Dienst. Jede Ausnahme gilt nur für diese eine IP und den UDP-/TCP-Zielport 53. Andere private Ziele und die Weiterleitung zwischen angeschlossenen Netzwerken bleiben gesperrt.

### IPv6-Weiterleitungsschutz

Halte `sandbox`, `sandbox-egress` und `SANDBOX_RUNTIME_IMAGE` beim Upgrade auf demselben Release. Bevor der Spawner unter Docker das Build-Netzwerk einer Organisation anschließt, prüft er den Weiterleitungsschutz der Session. Compose und generierte Docker-Session-Container deaktivieren IPv6 mit `net.ipv6.conf.all.disable_ipv6=1` und `net.ipv6.conf.default.disable_ipv6=1`. Übernimm beide Werte in eigene Docker-Definitionen.

Kubernetes-Pods erhalten nicht automatisch unsichere Sysctls. Der Egress-Proxy braucht eine funktionierende IPv6-Firewall oder deaktiviertes IPv6 in seinem Netzwerk-Namespace. Ist die IPv6-Firewall nicht verfügbar, versucht der Entrypoint IPv6 dort zu deaktivieren und prüft danach den Standardwert und jede Schnittstelle. Ein schreibgeschütztes `/proc/sys` oder fehlende Schreibrechte können das verhindern; ohne Schutz für weiterhin aktives IPv6 startet der Proxy nicht. Konfiguriere den Egress-Pod vor dem Deployment mit den Netzwerkeinstellungen, die dein Cluster erlaubt.

## Sandbox-Geräte {#sandbox-devices}

Organisationen können ihre Sandboxes auf eigenen Rechnern ausführen, die sie unter [Einstellungen > Sandboxes](https://docs.tale.dev/de/platform/admin/sandbox-devices) verbinden. Ein Gerät baut über HTTPS eine Verbindung zu `<SITE_URL><BASE_PATH>/sandbox/tunnel` auf und hält einen WebSocket offen. Der mitgelieferte Proxy leitet diesen Pfad, und nur diesen, an den Geräte-Hub des Spawners weiter; die signierte API des Spawners bleibt im internen Netz. Geräte brauchen das Docker-Backend: Mit Kubernetes bleibt der Hub ausgeschaltet.

| Name | Standard | Beschreibung |
| --- | --- | --- |
| `SANDBOX_HUB_PORT` | `8004` | **Liest der Spawner.** Port des Geräte-Hubs, der nur ein per Ticket authentifiziertes WebSocket-Upgrade und eine Zustandsprüfung beantwortet. `0` schaltet Geräte aus: **Gerät hinzufügen** ist dann nicht verfügbar. Änderst du den Port, stelle auch `SANDBOX_HUB_UPSTREAM` darauf um. |
| `SANDBOX_DEVICE_TUNNEL_URL` | `<SITE_URL><BASE_PATH>/sandbox/tunnel` als `wss://` | **Optional, liest das Backend.** Wohin sich Geräte verbinden, wenn ein vorgeschalteter Proxy den Hub unter einem anderen Host oder Pfad veröffentlicht. Eine `https://`-Adresse gilt als `wss://`. |
| `SANDBOX_DEVICE_IMAGE_REGISTRY` | `GHCR_REGISTRY`, sonst `ghcr.io/tale-project/tale` | **Optional, liest das Backend.** Woher Geräte die Sandbox-Images des Server-Releases laden. |
| `SANDBOX_HUB_UPSTREAM` | `sandbox:8004` | **Optional, liest der Proxy.** Wohin der Proxy `/sandbox/tunnel` weiterleitet, wenn der Spawner nicht der Dienst `sandbox` ist. |

Ein Gerät läuft immer mit dem Release des Servers. Es erfährt das Release bei jeder Erneuerung seiner Verbindung und ersetzt seine eigenen Container, sobald der Server weiterzieht, außer es wurde mit `--no-auto-update` verbunden. Es legt keine Daten auf dem Server ab: Seine Arbeitsbereiche bleiben auf dem Rechner. Sandboxes auf einem Gerät erreichen die Sandbox-Endpunkte des Backends und das Modell-Gateway über die Verbindung des Geräts, auf denselben Pfaden wie Sitzungen auf dem Server; die Verwaltungs-API des Gateways ist auf diesem Weg nie erreichbar. Ein Gerät behält die Adressen von Backend und Gateway, die es beim Verbinden erhalten hat: Nachdem du `SANDBOX_HTTP_API_BASE_URL` oder `EXTERNAL_AGENT_GATEWAY_URL` geändert hast, führe auf jedem Gerät `tale sandbox update` aus.

Ein Gerät muss dem TLS-Zertifikat der Website vertrauen. Eine Bereitstellung mit `TLS_MODE=selfsigned` kann keine Geräte aufnehmen.

Setzt du statt des mitgelieferten Proxys einen eigenen ein, leite `/sandbox/tunnel` an den Port `SANDBOX_HUB_PORT` des Spawners weiter, lass WebSocket-Upgrades und den Header `Authorization` unverändert und erlaube Verbindungen, die stundenlang offen bleiben.

## Sandbox-Agent-Turns

| Name                             | Default              | Beschreibung                                                                                                                                                                                                                                                                                                       |
| -------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TALE_EXTERNAL_TURN_DEADLINE_MS` | `1800000` (30 Min.)  | **Optional.** Wie lange ein Coding-Agent-Turn in der Sandbox (Claude Code, OpenCode, Codex) ohne Abnehmer seiner Ausgabe liegen darf, bevor der Sandbox-Daemon ihn abräumt. Ein gleitendes Fenster, das bei jedem Wiederanbinden der Plattform neu startet — keine absolute Obergrenze für den Turn. Millisekunden. |
| `SANDBOX_LLM_GATEWAY_STREAM_IDLE_TIMEOUT_SECONDS` | `600` (10 Min.) | **Optional.** Wie lange das Modell-Gateway der Sandbox auf das nächste Byte eines stillen Upstream-Modells wartet, bevor es den Stream abbricht — auch während ein langsames lokales Modell noch einen langen Prompt verarbeitet. Das Backend liest den Wert und konfiguriert damit das Gateway. Claude-Code-Turns warten mindestens genauso lange, bevor sie einen stillen Stream aufgeben und die Anfrage erneut senden. Du kannst den Wert für ein langsames lokales Modell also erhöhen, ohne dass Claude Code oder Codex einen Turn doppelt sendet. Ein hängendes Upstream-Modell hält einen Turn dann aber auch länger auf, bevor das Gateway den Stream abbricht. Ein Wert über 600 hebt auch das Anfrage-Timeout des Gateways entsprechend an: Es begrenzt eine ganze nicht gestreamte Antwort, auf die ein Agent ausweicht, wenn ein Stream abbricht, und wie lange ein Upstream-Modell brauchen darf, um eine gestreamte Antwort zu beginnen. Sekunden. |

Untersuche zuerst, warum die Ausgabe nicht mehr gelesen wird. Die Frist begrenzt verwaiste Ausgabeströme, nicht die gesamte Aufgabendauer. Erstelle die betroffenen Backend-Rollen nach einer Umgebungsänderung neu.

## Video-Link-Ingestion (yt-dlp)

Der Worker verwendet diese Werte zum Abrufen von Videotranskripten. Sein Image enthält yt-dlp und ein PO-Token-Plugin. [Video-Import](https://docs.tale.dev/de/self-hosted/configuration/video-ingestion) hilft bei Quellenbeschränkungen, Egress-Problemen und berechtigten Sitzungen. Erstelle den Worker nach Änderungen seiner Umgebung neu. Erneutes Lesen einer Prozessvariablen lädt `.env` nicht nach.

| Name                             | Standard                                     | Beschreibung                                                                                                                                                                                                                                                                                                                                                        |
| -------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VIDEO_INGEST_PROXY_URL` | nicht gesetzt | Proxy für yt-dlp-Anfragen. Unterstützte Protokolle: `http`, `https`, `socks4`, `socks4a`, `socks5`, `socks5h`; das letzte löst Zielnamen am Proxy auf. Nutze einen freigegebenen Egress-Dienst. |
| `VIDEO_INGEST_POT_PROVIDER_URL` | `http://bgutil-provider:4416` (eingebacken) | URL des PO-Token-Anbieters. Bei vorhandenem Image-Plugin gilt der mitgelieferte Sidecar als Standard. Token können den Abruf unterstützen, geben aber keinen Zugriff auf private Inhalte und garantieren keinen Erfolg. |
| `VIDEO_INGEST_FETCH_POT` | `always`, sobald ein Provider angebunden ist | Zeitpunkt des Token-Abrufs: `never`, `auto` oder `always`. Mit mitgeliefertem Anbieter gilt `always`. Verwende `never`, wenn du diesen Token-Abruf bewusst deaktivierst. |
| `VIDEO_INGEST_YTDLP_PLUGIN_DIRS` | `/opt/yt-dlp/plugins` (eingebacken)          | Verzeichnis, aus dem yt-dlp Plugins lädt — jedes Plugin eine Ebene tiefer verschachtelt (`<dir>/<name>/yt_dlp_plugins/…`). Standardmäßig das eingebackene bgutil-Plugin-Verzeichnis, wenn vorhanden; nur überschreiben, um eigene Plugins zu ergänzen.                                                                                                              |
| `VIDEO_INGEST_COOKIES_FILE` | nicht gesetzt | Pfad im Worker zu einer Netscape-Cookiedatei. Schütze sie wie Kontozugangsdaten und verwende nur eine berechtigte Sitzung. Der organisationsgebundene Sitzungspool in der Video-Anleitung unterstützt verwalteten Import und Widerruf. |
| `VIDEO_INGEST_PLAYER_CLIENT`     | `default,tv_simply`                          | Kommagetrennte Fallback-Liste der YouTube-Player-Clients. Mit angebundenem PO-Token-Provider erweitert sich der Standard auf `default,mweb,tv_simply` (mweb benötigt ein GVS-Token); explizit setzen, um eine Liste zu erzwingen.                                                                                                                                   |
| `VIDEO_INGEST_PO_TOKEN`          | nicht gesetzt                                | Manuell gesetztes PO-Token (`CLIENT.CONTEXT+TOKEN`). Vor allem zum Testen — Tokens sind an die Video-ID gebunden und kurzlebig; den Provider bevorzugen.                                                                                                                                                                                                            |
| `VIDEO_INGEST_IMPERSONATE`       | nicht gesetzt                                | Ziel für Browser-TLS/JA3-Imitation (z. B. `safari`). Erfordert `curl_cffi` im Image; nicht setzen, sofern nicht verfügbar.                                                                                                                                                                                                                                          |
| `VIDEO_INGEST_BIN_DIR`           | nicht gesetzt                                | Verzeichnis, das dem `PATH` des yt-dlp/ffmpeg-Kindprozesses vorangestellt wird, damit ein selbst bereitgestelltes `yt-dlp` (samt Deno-Runtime) außerhalb der eingebackenen Bin-Verzeichnisse zuerst gefunden wird. Das Backend-Image backt yt-dlp in den `PATH` ein, dort also nicht gesetzt lassen; auf einem Host- oder Dev-Rechner mit eigener Toolchain setzen. |
| `VIDEO_INGEST_FFMPEG_LOCATION`   | `/usr/bin/ffmpeg`                            | Absoluter Pfad zu dem ffmpeg, das yt-dlp für die Nachbearbeitung nutzt (Untertitel-Konvertierung, Audio-Extraktion). Überschreiben, wenn ffmpeg woanders liegt — z. B. Homebrews `/opt/homebrew/bin/ffmpeg` auf einem macOS-Dev-Rechner.                                                                                                                            |

# Überwachung einrichten
Source: https://docs.tale.dev/de/self-hosted/configuration/observability-config

Beginne mit den Containerprotokollen und dem Zustand der Dienste. Ergänze Prometheus-Messwerte für Trends und Alarme sowie eine Fehlererfassung, wenn du vergangene Fehler durchsuchen möchtest. Tale übermittelt diese Daten nur dann an einen externen Überwachungsdienst, wenn du einen einrichtest.

## Anwendungsprotokolle lesen

Container schreiben auf stdout und stderr. Die mitgelieferte Compose-Konfiguration nutzt Dockers Protokolltreiber `json-file`: maximal 10 MB pro Datei und drei Dateien pro Container. Verwende die Dienstnamen aus der Compose-Datei deiner Installation:

```bash
docker compose logs --tail=100 backend-api backend-worker
docker compose logs -f backend-api
```

Mit `Ctrl-C` beendest du die laufende Anzeige; die Container laufen weiter. Suche für Anfragen, Anmeldung und interaktive Chat-Antworten in `backend-api`; für Hintergrundaufgaben, eingereihte Agent-Aufrufe und Dokumentverarbeitung in `backend-worker`. `docker compose ps` zeigt dir Container, die wiederholt neu starten.

`journalctl -u docker` zeigt das Journal des Docker-Daemons. Beim Standardtreiber `json-file` ersetzt es die Containerprotokolle nicht. Für journald oder eine zentrale Protokollsammlung musst du den Docker-Protokolltreiber und die Sammlung gesondert einrichten. Tale liefert keinen Dienst zur Protokollweiterleitung mit. Nach einem Treiberwechsel musst du die betroffenen Container neu erstellen.

## Geschützte Messwerte aktivieren {#metriken}

Setze einen starken `METRICS_BEARER_TOKEN` in der Bereitstellungsumgebung. Übernimm die Änderung über deinen Bereitstellungsablauf, sodass die betroffenen Dienste neu erstellt werden. Ein einfacher Containerneustart lädt die Compose-Umgebungswerte nicht neu. Hinterlege denselben Token in der Geheimnisverwaltung deines Überwachungssystems.

Der Proxy verlangt für diese Routen `Authorization: Bearer <token>`. Ohne konfigurierten Token antworten sie mit **401**.

| Route | Inhalt | Verwendung |
| --- | --- | --- |
| `/metrics/platform` | Prozessmesswerte der Webanwendung und Zielwerte für Antwortzeiten | Prometheus-Abfrageziel |
| `/metrics/backend` | HTTP- und Prozessmesswerte des Backends, Warteschlangen, aktive Generierungen und Entleerungsstatus | Prometheus-Abfrageziel |
| `/metrics/sla-rules` | Generierte Aufzeichnungs- und Alarmregeln als YAML | Als Prometheus-Regeldatei laden |

Das Backend beantwortet Wissensanfragen und verarbeitet Dokumente. HTTP- und Warteschlangenmesswerte helfen, Fehler und Rückstau zu erkennen; sie messen nicht gesondert die Dauer der Suche oder Antwortgenerierung. `BACKEND_UPSTREAM` legt bei einer getrennten Bereitstellung das Backend-Ziel fest. Es entsteht dadurch kein eigener Metrikdienst für die Wissensverarbeitung.

Richte pro Metrikroute einen eigenen Abfrageauftrag ein. Im Beispiel ist `/run/secrets/tale_metrics_token` eine Datei im Prometheus-Container, die ausschließlich den Token enthält. Erstelle sie über deine Geheimnisverwaltung und erlaube Prometheus den Lesezugriff.

```yaml
scrape_configs:
  - job_name: tale-platform
    scheme: https
    metrics_path: /metrics/platform
    authorization:
      credentials_file: /run/secrets/tale_metrics_token
    static_configs:
      - targets: ['tale.example.com']
  - job_name: tale-backend
    scheme: https
    metrics_path: /metrics/backend
    authorization:
      credentials_file: /run/secrets/tale_metrics_token
    static_configs:
      - targets: ['tale.example.com']
```

Frage `/metrics/sla-rules` nicht als Metriken ab. Die generierten Regeln verweisen auf Zeitreihen, die zusätzliche Instrumentierung benötigen. Allein das Laden der Datei weist die Einhaltung der Antwortzeitziele nicht nach. Prüfe die Regeln, bevor du sie über die Regelkonfiguration von Prometheus lädst. Die vollständige Einrichtung beschreibt [Prometheus und Grafana](https://docs.tale.dev/de/self-hosted/operate/observability/prometheus-grafana).

## Ziel für Fehlerberichte wählen

`SENTRY_DSN` aktiviert die optionale Fehlererfassung. Du kannst Sentry oder einen kompatiblen Dienst wie GlitchTip oder Bugsink verwenden. Browser, Backend und Sandbox nutzen denselben DSN und die Umgebungsbezeichnung `SENTRY_ENVIRONMENT`; Server-Ereignisse enthalten Prozessrolle und Versionsnummer.

```bash
SENTRY_DSN=https://your-key@your-sentry-host/project-id
SENTRY_ENVIRONMENT=example-pr
SENTRY_TRACES_SAMPLE_RATE=0.1
```

Verwaltete Deployments verwenden als Umgebungsbezeichnung standardmäßig ihren bestehenden `name`. Für eine andere Bezeichnung deklarierst du `"environment": { "SENTRY_ENVIRONMENT": { "env": "TALE_REPORTING_ENVIRONMENT" } }` in der Deployment-Spezifikation und setzt die Variable am Ziel. Der Wert beginnt mit einem Kleinbuchstaben oder einer Ziffer und enthält 1–64 Kleinbuchstaben, Ziffern oder Bindestriche. Deployment-Identität, Zustand und gespeicherte Zugangsdaten bleiben an ihren bestehenden Pfaden.

Sandbox-Fehler umfassen fehlgeschlagene HTTP-Anfragen und Hintergrundaufgaben. Erwartete Client-Abbrüche und nach einer Abmeldung geschlossene SSE-Streams werden ausgeschlossen. Die Sandbox sendet nur Fehler; die Tracing-Einstellungen für Browser und Backend aktivieren kein Sandbox-Tracing. Sie nutzt den unten beschriebenen Datenschutzfilter des Backends.

`SENTRY_TRACES_SAMPLE_RATE` gilt für Leistungstraces im Browser; in der Entwicklung beträgt die Standardrate 1.0. Backend-Tracing ist standardmäßig deaktiviert. Setze `BACKEND_SENTRY_TRACES_SAMPLE_RATE` auf einen Wert zwischen `0` und `1`, um es einzuschalten (zum Beispiel erfasst `0.05` 5 % der Vorgänge), und verwende ein Ziel, das Sentry-Transaktionen annimmt. Erstelle die Backend-API- und Worker-Dienste nach der Änderung neu. Wähle Raten passend zu deinem Überwachungsbudget; mit der Backend-Rate `0` deaktivierst du Spans, während die Fehlererfassung aktiv bleibt.

Backend-Spans messen die Bearbeitung von HTTP-Anfragen und die Ausführung von Hintergrundjobs. Ein Job enthält untergeordnete Spans für die Drain-Prüfung, den Handler oder die Übergabe. Zustandsprüfungen und Metrikabfragen sind ausgenommen; HTTP-Spans messen nicht die Lebensdauer eines gestreamten Antwortinhalts. Span-Namen verwenden Routenklassen und registrierte Warteschlangennamen. Spans enthalten weder Anfrage- und Job-Inhalte noch SQL-Text, Kennungen, URLs, Benutzerkontext oder Breadcrumbs. Ausgehende Anfragen tragen keine Trace-Header. Agentenarbeit enthält außerdem untergeordnete Spans für Belegen, Gateway-Bereitstellung, Staging, Ausführung, Persistierung und Harvest. Sie verwenden feste Namen und enthalten keine Prompts, Dateipfade oder Zugangsdaten.

Backend-Ereignisse enthalten nie Cookies oder Inhalte der Anfrage. Autorisierungs-, Cookie-, API-Schlüssel-, Token-, Secret- und Sitzungs-Header, Webhook- und Freigabe-Tokens in URLs sowie Zugangswerte in Abfrageparametern wie OAuth-Codes werden vor dem Senden durch `[Filtered]` ersetzt. Stackframes und Fehlermeldungen werden unverändert übertragen; berücksichtige bei der Zielwahl deine Vorgaben zur Datenverarbeitung.

Ein Neustart der Datenbank gilt nicht als Fehler; ein verwaltetes Upgrade erstellt die Datenbank bei jedem Release neu. Solange sie nicht erreichbar ist, antworten Anfragen mit `503 DATABASE_UNAVAILABLE` und `Retry-After`, Hintergrundjobs schlagen fehl und werden nach der Richtlinie ihrer Warteschlange wiederholt, und offene Live-Update-Streams warten ab und laufen danach weiter. Stattdessen landet jeweils eine Warnung im Protokoll. Die Job-Warteschlange schreibt für den ganzen Ausfall nur eine, nicht eine für jede fehlgeschlagene Abfrage. Bleibt die Datenbank länger als etwa eine Minute unerreichbar, sendet ein API-Prozess mit offenen Live-Update-Streams für diesen Ausfall ein einziges Ereignis der Stufe „warning“. Ein Backend-Prozess, der startet, während die Datenbank nicht erreichbar ist, wartet bis zu etwa einer Minute auf sie, statt sich zu beenden, und schreibt für jeden neuen Versuch eine Warnung ins Protokoll. Ist die Datenbank danach noch immer nicht erreichbar, schlägt der Start fehl und wird als Fehler gemeldet. Ein falscher Host oder Port in `DATABASE_URL` lässt den Start deshalb erst nach etwa einer Minute fehlschlagen.

Auch eine Anfrage, die ihr Client aufgegeben hat, meldet das Backend nicht. Das passiert etwa, wenn du einen Browser-Tab schließt oder einen Upload abbrichst, während die Daten noch übertragen werden. Die Anfrage erhält den Status `499`, zählt in den Anfragemetriken zu den Clientfehlern und hinterlässt eine einzige Debug-Zeile im Protokoll. Jeder andere Fehler in einer Anfrage, deren Client nicht mehr verbunden ist, wird weiterhin gemeldet. Eine App-Anfrage mit leerem oder abgeschnittenem JSON-Body beantwortet das Backend mit `400 INVALID_JSON`, ohne sie zu melden.

Fehler, die auf keinen Defekt in Tale hinweisen, meldet der Browser nicht:

- Fehler aus einer Browsererweiterung
- Anfragen, die die Seite selbst abgebrochen hat, etwa weil du sie vor dem vollständigen Laden verlassen hast
- Anfragen, die das Backend mit einem Status unter 500 ablehnt, etwa bei fehlender Berechtigung oder einem bereits vergebenen Namen
- Anfragen, die gar keine Antwort erhalten, zum Beispiel weil das Gerät offline ist
- Anfragen, die fehlschlagen, während die Plattform oder ihre Datenbank neu startet: `UPSTREAM_UNAVAILABLE` vom Proxy während eines Deployments oder Neustarts und `503 DATABASE_UNAVAILABLE` von der Plattform

Andere Serverfehler ab Status 500 meldet er weiterhin.

## Aggregierte Nutzungsstatistik mit Umami

Die Erfassung ist standardmäßig ausgeschaltet. Du aktivierst sie für jedes Deployment getrennt mit `UMAMI_URL`, `UMAMI_WEBSITE_ID` und `UMAMI_PROXY_TOKEN`; die [Umgebungsreferenz](https://docs.tale.dev/de/self-hosted/configuration/environment-reference) beschreibt die Werte. Verwende je Deployment eine eigene Website-ID. Erstelle den betroffenen Produktionsdienst mit den neuen Umgebungswerten neu; ein neues Image ist nicht nötig. Leere zum Abschalten die Website-ID und wende die Änderung genauso an. Der Vite-Entwicklungsserver stellt diese Konfiguration nicht bereit.

Der Browser lädt den Umami-Tracker von seiner eigenen Origin unter `/_a/script.js` und sendet ausgewählte Ereignisse an `/_a/api/send`. Ein konfigurierter Basispfad steht vor diesen URLs. Nur Website-ID und Proxy-Pfad gelangen in die Browserkonfiguration; Origin und Bearer-Token der Erfassung bleiben auf dem Server.

`UMAMI_URL` muss auf ein Gateway zeigen, das `GET /_collect/script.js` und `POST /_collect/api/send` mit diesem Bearer-Token authentifiziert. Die URL eines normalen Umami-Dashboards allein erfüllt diese Anforderungen nicht. Caddy muss `X-Analytics-Client-IP` aus einer vertrauenswürdigen Client-Adresse neu setzen. Halte die Anwendungsports privat und konfiguriere vertrauenswürdige Proxy-Netze, wenn ein weiterer Proxy vorgeschaltet ist. Der Server leitet die geprüfte IP-Adresse, den User-Agent des Browsers und die nötigen Umami-Header weiter; Browser-Cookies, Zugangsdaten und Referrer-Header entfernt er.

Die Berichte enthalten bekannte öffentliche Seitenpfade oder private Routenvorlagen der Plattform, Referrer-Origins, Browsersprache, Bildschirmgröße, Browser, Betriebssystem, Gerät und ungefähren Standort. Die Erfassung leitet Besuche und Standort aus der IP-Adresse ab, ohne die ursprüngliche Adresse zu speichern. Platzhalter ersetzen private Organisations- und Ressourcen-IDs. Seitentitel, Suchparameter, Fragmente, Formularfelder und Produktinhalte sind ausgeschlossen. Die Marketing-Seite zählt zusätzlich abgeschlossene Kontakt- und Demo-Anfragen ohne deren Inhalt. Es gibt keine websiteübergreifende Identität, automatische Klickerfassung oder Sitzungsaufzeichnung. Do Not Track und Global Privacy Control deaktivieren die Erfassung.

Prüfe nach dem Rollout das Verhalten mit einem Browser, der die Erfassung zulässt:

1. Öffne eine bekannte Seite, wechsle zu einer anderen und prüfe beide Seitenaufrufe in der Umami-Website des Deployments.
2. Prüfe den Anfrageinhalt. Private Routen enthalten Platzhalter, aber keine Suchparameter, Titel oder Formulardaten.
3. Aktiviere Do Not Track oder Global Privacy Control und prüfe, dass die Erfassung stoppt.
4. Blockiere die Erfassung oder teste einen Ausfall. Die normale Navigation muss weiter funktionieren.

## Grenzen kennen

Tale exportiert derzeit keine OpenTelemetry-Traces über OTLP. Ein OpenTelemetry Collector kann die Prometheus-Messwerte erfassen. Aus dem Abfragen von Messwerten entstehen aber keine verteilten Traces. Dafür braucht die Anwendung zusätzlich eine entsprechende Instrumentierung.

Alarmgrenzen und Reaktionsabläufe findest du unter [Betrieb](https://docs.tale.dev/de/self-hosted/operate/observability/operations). Bei einem ausgefallenen Dienst helfen die Symptomtabellen der [Fehlersuche](https://docs.tale.dev/de/self-hosted/operate/observability/troubleshooting).

# Anbieter
Source: https://docs.tale.dev/de/self-hosted/configuration/providers

Unterscheide bei einem KI-Anbieter drei Dinge: Connector-Definition, Zugangsdaten der Organisation und Modellserver. Der Connector beschreibt Endpunkt und Protokoll, Zugangsdaten steuern den Zugriff, und der Endpunktbetreiber betreibt den Modelldienst.

Diese Seite behandelt eigene Anbieterdefinitionen und Geheimnisse aus der Umgebung. Zugangsdaten und Standardmodelle in der App beschreibt [KI-Anbieter](https://docs.tale.dev/de/platform/admin/providers).

## Lokale Anbieterendpunkte

Ein lokaler Inferenzserver braucht eine Anbieterdefinition und die Erlaubnis für das Backend, seinen Host zu erreichen. Die Definition installiert keinen Server und lädt kein Modell.

1. Mache den Inferenzserver für jede Backend-Rolle erreichbar, die ihn aufruft. `localhost` bezeichnet im Container diesen Container, nicht den Hostrechner. Prüfe Namensauflösung, Netzwerkzugriff und gegebenenfalls das TLS-Zertifikat aus dem tatsächlichen Laufzeitnetz.
2. Setze für einen privaten oder Loopback-Endpunkt `TALE_ALLOW_PRIVATE_PROVIDER_HOSTS=1` in der Backend-Bereitstellungsumgebung. Die Einstellung erlaubt private Anbieterhosts für die gesamte Installation; sie ist keine Freigabeliste einzelner Anbieter. Cloud-Metadatenendpunkte bleiben gesperrt. Erstelle die betroffenen Container neu, um die Änderung zu übernehmen. Ein Neustart behält ihre bestehende Compose-Umgebung.
3. Lege die Anbieterdefinition unter `TALE_CONFIG_DIR/<orgSlug>/providers/local-models.yml` ab oder nutze den [verwalteten Konfigurationsablauf](https://docs.tale.dev/de/self-hosted/configuration/config-releases). Halte das native Anbieterschema ein und wähle einen Namen, der nicht mit einer mitgelieferten Definition kollidiert. Ein Organisationsadmin kann dieselbe Datei auch in der App anlegen: **Zugangsdaten hinzufügen** > **Eigener Anbieter** unter **Einstellungen > KI-Anbieter**; siehe [Einen eigenen Anbieter definieren](https://docs.tale.dev/de/platform/admin/providers#einen-eigenen-anbieter-definieren).

Ersetze im Beispiel private IP und Port durch deinen erreichbaren Server. HTTP ist nur für als privat oder Loopback erkannte Hosts zulässig; öffentliche Endpunkte brauchen HTTPS. Ein interner DNS-Name umgeht die Prüfung privater Hosts zur Anfragezeit nicht.

```yaml
name: local-models
displayName: Local models
apiFormat: openai
baseUrl: http://192.168.1.20:8000/v1
catalog:
  source: models-endpoint
auth:
  - method: api-key
  - method: env
```

Die Definition verwendet eine OpenAI-kompatible Chat-API und liest Modelle aus `/v1/models`. Prüfe die tatsächliche Kompatibilität des Servers. Eine Modellliste beweist noch nicht, dass Generierung, Werkzeugaufrufe oder Streaming funktionieren. Kann der Server keine Modelle auflisten, verwende `catalog.source: none` und trage die genauen Modellbezeichner in die Freigabeliste der Zugangsdaten ein. Eigene Anbieter laden keine statische Modelldatei aus dem Organisationsverzeichnis.

Lass anschließend einen Organisationsadmin unter [KI-Anbieter](https://docs.tale.dev/de/platform/admin/providers) Zugangsdaten hinzufügen, den Katalog aktualisieren und ein bestimmtes Modell für einen kurzen Chat auswählen. Prüfe die abgeschlossene Anfrage im Protokoll des vorgesehenen Inferenzservers. Für Embeddings, Sprache und Werkzeugverkehr musst du die Ziele getrennt prüfen; ein lokaler Chatendpunkt hält sie nicht automatisch lokal.

## Audiotranskription konfigurieren

Die Organisationsrichtlinie liegt unter `TALE_CONFIG_DIR/<org>/governance/transcription-model.yml` und hat den Richtlinientyp `transcription_model`. Die Seite [Modelle](https://docs.tale.dev/de/platform/admin/governance/content-models) bearbeitet dieselbe Auswahl. Eine fehlende Datei oder ein leeres Objekt bedeutet automatische Auswahl:

```yaml
{}
```

Um ein Modell festzulegen, gib beide Felder an. Dieses Beispiel verwendet das mitgelieferte OpenAI-Whisper-Modell und benötigt weiterhin einen aktiven, nutzbaren Zugang der Organisation:

```yaml
providerSlug: openai
modelId: whisper-1
```

Eine unvollständige Festlegung ist ungültig. Ist das festgelegte Modell nicht verfügbar, wechselt Tale nie zu einem anderen Modell. Stelle den Zugang oder die dafür erlaubten Modelle wieder her oder wechsle ausdrücklich zur automatischen Auswahl. Auch Lese- oder Validierungsfehler der Konfiguration verhindern die serverseitige Transkription. Die Richtlinie gilt für Audio- und Videodateien, Videolinks mit Audiotranskription und Serverdiktate. Die Spracherkennung des Browsers bleibt davon unabhängig.

Mit einem aktiven Standardzugang für OpenRouter findet Tale auch die Modelle zur Spracherkennung unter `/models?output_modalities=transcription`. Dafür gelten derselbe Zugang und dessen erlaubte Modelle. Übernimm beim Festlegen eines Modells die genaue Kennung aus diesem Katalog oder behalte die automatische Auswahl bei. Die Schnittstelle beschreibt [OpenRouters Anleitung zur Spracherkennung](https://openrouter.ai/docs/guides/overview/multimodal/stt).

Für einen eigenen OpenAI-kompatiblen Endpunkt verwende `catalog.source: models-endpoint`. Seine Antwort auf `/models` muss das Audiomodell mit einer genauen `id` und entweder `type: transcription` oder `architecture.output_modalities: [transcription]` ausweisen. Bei einem reinen Transkriptionsmodell darf `context_window` fehlen oder `0` sein; andere Modelle brauchen weiterhin einen positiven Wert. Ein Chatmodell mit Audioeingabe oder ein Sprachsynthesemodell gilt nicht automatisch als Transkriptionsmodell.

Tale sendet die Multipart-Felder `file` und `model` mit Bearer-Authentifizierung an `POST <baseUrl>/audio/transcriptions`. Bei OpenRouter fordert Tale `response_format: json` an, weil einige der dort verfügbaren Modelle `verbose_json` ablehnen. Andere kompatible Endpunkte müssen `response_format: verbose_json` unterstützen. Die JSON-Antwort liefert das Transkript als `text`. Tale verwendet zuerst eine gültige `duration`, ersatzweise eine gültige `usage.seconds`. Ist keiner der Werte nutzbar, verwendet Tale eine lokal gemessene Dauer, soweit verfügbar. Zeitangaben in `segments` können Videozeitstempel liefern; ohne sie bleibt das Transkript reiner Text. Ein Katalogeintrag beweist nicht, dass diese API funktioniert. Aktualisiere den Katalog, wähle das Modell, teste eine kurze Aufnahme und prüfe die Anfrage in den Logs dieses Endpunkts.

## Bildgenerierung konfigurieren {#configure-image-generation}

Die Organisationsrichtlinie liegt unter `TALE_CONFIG_DIR/<org>/governance/image-generation.yml` und hat den Richtlinientyp `image_generation`. Die Seite [Modelle](https://docs.tale.dev/de/platform/admin/governance/content-models#let-agents-generate-images) bearbeitet dieselben Einstellungen. Eine neue Organisation startet mit ausgeschalteter Bildgenerierung, und auch eine fehlende Datei bedeutet aus:

```yaml
enabled: false
```

Setze `enabled: true` für die automatische Auswahl, oder lege ein Modell fest, indem du beide Felder angibst:

```yaml
enabled: true
providerSlug: openai
modelId: gpt-image-1
```

Eine unvollständige Festlegung oder ein unbekanntes Feld ist ungültig. Bei einer ungültigen oder nicht lesbaren Datei bleibt die Bildgenerierung aus, und die Seite Modelle nennt das Problem. Die automatische Auswahl versucht `google/gemini-2.5-flash-image`, `gpt-image-1-mini`, `gpt-image-1` und `black-forest-labs/flux.2-pro` in dieser Reihenfolge, jeweils über einen Standardzugang für OpenRouter oder OpenAI. Ist das festgelegte Modell nicht verfügbar, wechselt Tale nie zu einem anderen Modell. Eine Festlegung darf in der Datei bleiben, während `enabled` auf `false` steht.

Das Backend ruft das Bildmodell mit dem Zugang der Organisation auf; kein Schlüssel gelangt in die Sandbox. Bei OpenRouter sendet es `POST <baseUrl>/images` mit dem Seitenverhältnis `1:1`, `3:2` oder `2:3` an OpenRouters Image-API und erfasst die Kosten, die die Antwort meldet. Bei jedem anderen Anbieter nutzt es die Bild-API von OpenAI: `POST <baseUrl>/images/generations`, oder `POST <baseUrl>/images/edits` als Multipart-Formular, wenn der Agent Referenzbilder mitgibt; ein GPT-Bildmodell fragt es dabei in der Qualität `medium` an. Die gemeldeten Tokens bewertet Tale dann mit den Preisen aus dem Katalogeintrag des Modells. Die Bildmodelle von OpenRouter findet Tale unter `/models?output_modalities=image`, und der mitgelieferte OpenAI-Katalog enthält `gpt-image-1` und `gpt-image-1-mini`.

Die Antwort eines eigenen OpenAI-kompatiblen Endpunkts auf `/models` muss ein Bildmodell mit `image` unter `architecture.output_modalities` oder `modalities.output` und einem positiven `context_length` oder `context_window` ausweisen. Tale speichert nur Rasterbilder (PNG, JPEG, WebP, GIF) und lehnt SVG-Ausgaben eines Modells ab; ein Referenzbild, das ein Agent mitgibt, muss eine PNG-, JPEG- oder WebP-Datei von höchstens 4 MB sein. Ein Katalogeintrag beweist nicht, dass der Endpunkt funktioniert: Schalte die Bildgenerierung ein, lege das Modell fest, lass einen Agenten ein Testbild erstellen und prüfe die Anfrage in den Logs des Endpunkts.

Ein Zug eines Agenten erstellt höchstens 16 Bilder und führt jeweils nur eine Generierung aus. Vor jedem Aufruf hält Tale 0,25 USD pro Bild gegen den Rahmen des Zugs und die Budgetgrenzen fest und bucht nach dem Aufruf die gemeldeten Kosten an ihrer Stelle. Der Gateway-Schlüssel des Zugs gibt denselben Betrag von seiner Grenze ab, sodass Modell und Bilder zusammen in einem Rahmen bleiben; kann das Gateway diese Grenze nicht senken, wird das Bild abgelehnt. Ein Zug über ein Anbieter-Abonnement hat keinen Gateway-Rahmen; seine Bilder werden an dem Rahmen gemessen, den die Installation einem Zug standardmäßig gibt.

## Den Standard-Agenten konfigurieren {#configure-the-standard-agent}

Die Richtlinie der Organisation liegt unter `TALE_CONFIG_DIR/<org>/governance/standard-agent.yml`, mit dem Richtlinientyp `standard_agent`. Die [Seite Modelle](https://docs.tale.dev/de/platform/admin/governance/content-models#standard-agent) bearbeitet dieselben Einstellungen. Eine neue Organisation erhält den Standard-Agenten eingeschaltet, und eine fehlende Datei bedeutet ebenfalls eingeschaltet:

```yaml
enabled: true
```

Lege die Laufzeit, das Modell oder beides fest und ersetze die eingebauten Anweisungen:

```yaml
enabled: true
harness: claude-code
providerSlug: anthropic
modelId: claude-sonnet-5
instructions: |
  Schreibe im Stil unseres Hauses. Liefere jedes Dokument als Word-Datei.
```

`harness` nimmt den Slug einer Laufzeit, die ein Projektagent nutzen kann, etwa `claude-code` oder `codex`; eine andere lehnt die Seite Modelle ab. Ein festgelegtes Modell braucht `providerSlug` und `modelId`. Ungültig sind eine halbe Festlegung, ein unbekanntes Feld und Anweisungen mit mehr als 20.000 Zeichen. Eine ungültige oder unlesbare Datei hält jeden Standard-Agenten vom Start ab, und die Seite Modelle nennt das Problem; als eingeschaltet gilt sie nie. Ein nicht verfügbares Modell weicht nie auf ein anderes aus, ebenso wenig eines, das der Modellzugriff einer Person nicht erlaubt. Tale liest die Richtlinie bei jedem Start eines Laufs, eine Änderung gilt also ab dem nächsten Lauf. Mit `enabled: false` bleiben die schon eingerichteten Standard-Agenten in ihren Projekten, aber keiner von ihnen startet.

## Modellzugriff aus der Sandbox prüfen

Chats rufen einen Anbieter aus dem Backend auf. Coding-Agenten verwenden `sandbox-llm-gateway`; ein erfolgreicher Chat belegt daher nicht den Agentenpfad. Der Endpunkt muss aus Backend und Gateway auflösbar und erreichbar sein. Beide HTTPS-Clients müssen seinem Zertifikat vertrauen. Auch ein Name wie `https://models.internal/v1` braucht die Freigabe privater Anbieter, wenn DNS ihn zu einer privaten Adresse auflöst. HTTP bleibt auf die vom Anbieterschema akzeptierten Hostformen begrenzt, etwa private IP-Adressen, `localhost` und `.local`.

Beim Start einer neuen Sandbox-Sitzung prüft das Backend Hostname und DNS-Antworten des eigenen Anbieters, bevor es ihn im Gateway einrichtet. Private Ziele erfordern `TALE_ALLOW_PRIVATE_PROVIDER_HOSTS=1`; Metadatenziele bleiben auch damit gesperrt. Diese Vorprüfung bindet spätere Gateway-Anfragen nicht an dieselbe DNS-Antwort. Anbieterdefinitionen und DNS müssen deshalb unter der Kontrolle vertrauenswürdiger Betreiber bleiben.

Erstelle die betroffenen Backend-Prozesse mit der aktualisierten Umgebung neu. Starte dann eine neue Sandbox-Sitzung mit dem vorgesehenen Anbieter und Modell sowie einer kompatiblen Agenten-Laufzeit. Prüfe mit einer harmlosen Anfrage die vollständige Antwort und den passenden Eintrag im Inferenzserver-Protokoll. Funktioniert der Chat, aber der Agent erreicht sein Modell nicht, prüfe die Protokolle von `sandbox-llm-gateway`. `SANDBOX_EGRESS_ALLOWLIST` steuert allgemeine Webzugriffe der Sandbox, nicht diese separate Modellverbindung.

Coding-Agenten richten sich außerdem nach dem Kontextfenster, das der Katalog für das Modell meldet: nach `context_length` oder `context_window` in der Modellliste deines Servers unter `/v1/models`, und nach 128.000 Token, wenn die Liste keines von beiden nennt, ebenso bei einem Anbieter mit `catalog.source: none`. Sorge dafür, dass die Liste den Kontext nennt, den dein Server tatsächlich bereitstellt. Liegt dieses Fenster oder ein niedrigeres [Kontextlimit](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits) der Person, die den Lauf gestartet hat, unter 200.000 Token, fasst eine verwaltete Claude-Code-Sitzung ihre Konversation zusammen, bevor der Prompt darüber hinauswächst. Claude Code behandelt jeden Wert unter 100.000 Token wie 100.000. Ein Modell mit weniger Kontext kann also längere Prompts erhalten, als es aufnehmen kann. Setze Claude Code deshalb nur mit Modellen ein, die mindestens so viel Kontext bereitstellen.

Auf einem Modell, das nicht Claude ist, lässt eine verwaltete Claude-Code-Sitzung außerdem die Zuordnungszeile weg, die Claude Code sonst an den Anfang jedes Systemprompts stellt. Diese Zeile ändert sich mit jeder Anfrage, und ein Server, der Prompt-Anfänge zwischenspeichert, müsste sonst bei jedem Schritt die ganze Konversation neu berechnen.

## Wo die Connectoren liegen

Mitgelieferte Definitionen liegen unter `configs/platform/system/providers/<slug>/provider.yml`, ihre statischen Kataloge unter `configs/platform/system/models/<slug>/models.yml`. Anthropic verwendet beispielsweise `providers/anthropic/provider.yml` und `models/anthropic/models.yml`. Die Dateien gehören zum Image und ändern sich mit dessen Version.

<Warning>

Mitgelieferte Dateien sind schreibgeschützte Image-Eingaben und werden beim Upgrade ersetzt. Nutze für externe Anbieter die geprüfte Deployment-Deklaration `configuration` aus [CLI-Installation](https://docs.tale.dev/de/self-hosted/install/cli-install#plattform-konfigurieren). Sie erstellt mit dem nativen Schema einen organisationsgebundenen Connector unter `TALE_CONFIG_DIR/<org>/providers/`; Änderungen an Zugangsdaten und Richtlinien nutzen native APIs. Der Eintrag **Eigener Anbieter** unter **Zugangsdaten hinzufügen** in der App schreibt dieselbe organisationsgebundene Datei und bewahrt jede gespeicherte Version unter `.history/` auf.

</Warning>

## Was ein Connector deklariert

Eine Definition beschreibt Protokoll, Endpunkt, Katalog und erlaubte Authentifizierungsmethoden. Sie enthält keine Zugangsdaten einer Organisation. Diese beiden Ausschnitte zeigen das Format:

<CodeGroup>

```yaml anthropic.yml
name: anthropic
displayName: Anthropic
apiFormat: anthropic
baseUrl: https://api.anthropic.com
catalog:
  source: static
auth:
  - method: api-key
  - method: env
  - method: subscription-broker
    constraints:
      execution: sandbox
      harness: claude-code
```

```yaml openrouter.yml
name: openrouter
displayName: OpenRouter
apiFormat: openai
baseUrl: https://openrouter.ai/api/v1
catalog:
  source: openrouter-api
auth:
  - method: api-key
  - method: env
```

</CodeGroup>

| Feld | Bedeutung |
| --- | --- |
| `apiFormat` | Anfrageformat: `openai` oder `anthropic`. |
| `wireDialect: openai-modern` | Für Endpunkte im OpenAI-Format: verwendet `max_completion_tokens` und lässt eigene Temperaturwerte bei Reasoning-Modellen weg. Für Endpunkte mit klassischen Feldern bleibt es ungesetzt. |
| `baseUrl` | Fester Endpunkt für alle zugehörigen Zugangsdaten. |
| `endpointMode: per-credential` | Verwendet statt `baseUrl` einen Endpunkt je Zugangsdaten-Eintrag, etwa bei Azure OpenAI. |
| `catalog.source` | `static`, `openrouter-api`, `models-endpoint` oder `none`. Statische Einträge stammen aus dem oben beschriebenen Modellkatalog. |
| `embedding` | Ob der Anbieter Embeddings bedient: `supported`, wenn sein Katalog eine kuratierte Vektorbreite mitliefert; `unsupported`, wenn der Anbieter kein Embedding-Modell anbietet, sodass **Einstellungen > Datenresidenz > Embedding-Modell** ihn ablehnt; oder `unknown`, der Standard, wenn Admins Modell und Vektorbreite selbst eingeben. Deklariere `unsupported` nur, wenn die Dokumentation des Anbieters selbst das sagt. |
| `auth` und `constraints` | Erlaubte Zugangsmethoden und Ausführungsbedingungen, etwa ein bestimmter Sandbox-Harness. |

## Umgebungsvariable als Schlüsselquelle {#umgebungsvariable-als-schlusselquelle}

Bei der Authentifizierungsmethode **Umgebungsvariable** speichern die Zugangsdaten einen Variablennamen. Das Backend liest dessen Wert bei der Anfrage aus seiner Prozessumgebung. Übergib ihn über die Geheimnisverwaltung deiner Bereitstellung. Bei dieser Methode wird der API-Schlüssel nicht in der Anwendungsdatenbank gespeichert.

Zulässig sind nur Namen mit dem Präfix `TALE_PROVIDER_KEY_`. Der vollständige Name darf höchstens 40 Zeichen haben; im Suffix sind Buchstaben, Ziffern und Unterstriche erlaubt. Das Formular ergänzt das Präfix automatisch.

```bash
TALE_PROVIDER_KEY_OPENROUTER=sk-or-...
TALE_PROVIDER_KEY_OPENAI_PROD=sk-...
```

<Note>

Das reservierte Präfix verhindert, dass Zugangsdaten auf fremde Geheimnisse wie `SOPS_AGE_KEY` oder `BETTER_AUTH_SECRET` verweisen. Die Validierung lehnt ungültige Namen vor dem Speichern ab.

</Note>

Erstelle nach dem Hinzufügen oder Rotieren des Werts sowohl `backend-api` als auch `backend-worker` mit der aktualisierten Umgebung neu. Ein Compose-Neustart behält alte Werte. Leerraum am Anfang und Ende wird vor der Verwendung entfernt. Prüfe nach dem Ausrollen eine echte Anfrage.

## Einen Abo-Broker verbinden

Ein Abo-Broker liefert einen Pool von OAuth-Zugriffstokens. Tale wählt daraus für jeden Agentendurchlauf ein nutzbares Konto. Mitgeliefert sind die Anbindungen für Anthropic mit Claude Code und OpenAI ChatGPT mit Codex, jeweils für Aufgaben- und Automatisierungsagenten. Chats und andere direkte Modellaufrufe benötigen weiterhin API-Zugangsdaten. Ein OAuth-Token ist kein Anbieter-API-Schlüssel.

Verwende für jeden Anbieter einen eigenen Endpunkt. Das Tale AI Gateway stellt `/api/tokens/anthropic` und `/api/tokens/openai` bereit. Zur Anmeldung dient sein API-Schlüssel als Bearer-Token. Der gemeinsame Endpunkt `/api/tokens` eignet sich nicht als Quelle für Zugangsdaten eines einzelnen Anbieters. Das Backend muss den Broker unter derselben Host-Richtlinie erreichen können, die oben für Anbieter-Endpunkte beschrieben ist.

Das folgende Beispiel zeigt das Broker-Dokument, das das [Formular für KI-Anbieter](https://docs.tale.dev/de/platform/admin/providers#einen-abo-broker-verbinden) erstellt. Es ist keine Anbieter-Definitionsdatei. Ersetze den Hostnamen durch deinen Broker und stelle dessen API-Schlüssel in beiden Backend-Prozessen als `TALE_TOKEN_SOURCE_AI_GATEWAY` bereit. Die zugeordneten Feldnamen passen zum Tale AI Gateway; bei einem anderen Broker musst du sie an dessen Antwort anpassen.

```json
{
  "endpoint": "https://broker.example.com/api/tokens/anthropic",
  "httpMethod": "GET",
  "auth": {
    "method": "bearer",
    "secretEnv": "TALE_TOKEN_SOURCE_AI_GATEWAY"
  },
  "responseMapping": {
    "tokensPath": "$.tokens",
    "tokenField": "access_token",
    "statusField": "status",
    "activeValue": "active",
    "expiresField": "expires_at"
  },
  "targetEnvVar": "CLAUDE_CODE_OAUTH_TOKEN",
  "selection": "round-robin"
}
```

Ändere für OpenAI das Ende des Endpunkts auf `/api/tokens/openai` und `targetEnvVar` auf `TALE_SUBSCRIPTION_TOKEN`. Jeder nutzbare OpenAI-Eintrag muss außerdem die `account_id` des Anbieters enthalten. Tale übergibt sie neben dem Token als `TALE_SUBSCRIPTION_ACCOUNT_ID` an die ChatGPT-Anbindung von Codex. Verwende dafür weder die `id` des Gateways noch `CODEX_ACCESS_TOKEN`. Beschränke die erlaubten Modelle der Zugangsdaten auf Modell-IDs, die das ChatGPT-Abonnement unterstützt. Der OpenAI-API-Katalog kann Modelle enthalten, die mit Abonnements nicht nutzbar sind.

Verwende für Anthropic OAuth die Variable `CLAUDE_CODE_OAUTH_TOKEN`. Das bisherige Ziel `ANTHROPIC_AUTH_TOKEN` bleibt bei ausdrücklicher Konfiguration unterstützt und nutzt die allgemeine Bearer-Authentifizierung von Claude Code. Tale entfernt konkurrierende Anbieter-Zugangsdaten aus der Umgebung, bevor es das ausgewählte Token übergibt. Eine Zielvariable, die die gewählte Laufzeit nicht unterstützt, wird abgelehnt.

### Kontoidentität und Kontingent

Neben den zugeordneten Token-, Status- und Ablauffeldern kann jeder Token-Eintrag die folgenden Standardfelder enthalten. Die Feldnamen sind festgelegt; eine zusätzliche Zuordnung ist nicht nötig.

| Feld | Zweck |
| --- | --- |
| `id` | Broker-Kontokennung |
| `provider` | Anbieterkennung |
| `account_id` | Anbieter-Kontokennung |
| `available` | Verfügbarkeit für neue Arbeit |
| `available_at` | Zeitpunkt, ab dem es wieder verfügbar ist |
| `hold` | Grund, aus dem ein nicht verfügbares Konto zurückgehalten wird |
| `usage` | Nutzungsstand |

Die `id` muss bei einem Tokenwechsel gleich bleiben, damit Tale das Konto bei Wiederholungsversuchen erkennt. Sie ist unabhängig von der `account_id` des Anbieters, die OpenAI benötigt. Nennt `provider` einen anderen Anbieter als den der Zugangsdaten, wird der Eintrag ausgeschlossen.

`available: false` schließt das Konto bis zum ISO-Zeitstempel in `available_at` aus. Ist kein Zeitpunkt bekannt, lasse das Feld weg oder verwende `null`. Das Konto bleibt dann ausgeschlossen, bis der Broker es wieder als verfügbar meldet. Status und Token-Ablauf werden separat geprüft. Das Tale AI Gateway berechnet die Verfügbarkeit aus dem Nutzungsstand `usage` mit `checked_at` und `windows`. Jedes Zeitfenster enthält Art, Auslastung und Erneuerungszeitpunkt.

Ältere Broker können die optionalen Metadaten weglassen. Ohne `id` verwendet Tale bei Wiederholungsversuchen einen Hash des Tokens. Nach einem Tokenwechsel lässt sich das Konto damit nicht wiedererkennen. Fehlen Kontingentdaten, bleibt das Konto auswählbar. Daraus folgt nicht, dass es noch freies Kontingent hat.

Das Tale AI Gateway schließt ein Konto aus, wenn ein aktueller Nutzungsstand ein globales Sitzungs- oder Wochenfenster mit 100 % Auslastung meldet und dessen Erneuerungszeitpunkt noch nicht erreicht ist. Meldet der Anbieter ausdrücklich eine erreichte Grenze (`usage.limited: true`), ist das Konto ebenfalls nicht verfügbar, auch wenn der angezeigte Auslastungswert niedriger ist oder fehlt. Modellspezifische Grenzen sperren nicht das ganze Konto. Nach 15 Minuten gilt ein Nutzungsstand als veraltet. Unbekannte oder veraltete Werte lassen das Konto daher auswählbar; ein ausgeschöpftes Fenster ohne Erneuerungszeitpunkt sperrt es nur, solange die Meldung aktuell ist. Die nächste Token-Anfrage aktualisiert veraltete Nutzungsdaten, soweit der Anbieter das unterstützt. Nach der betreffenden Kontingent-Erneuerung kann das Konto wieder in den Pool aufgenommen werden. Zwischen den Aktualisierungen kann der Anbieter weiterhin eine Anfrage ablehnen. Außerdem meldet das Gateway ein Konto bis zur geplanten Token-Erneuerung (`refresh_at`) als nicht verfügbar, sobald diese weniger als eine Stunde entfernt ist (seine voreingestellte Mindestrestlaufzeit) und ein anderes Konto die Arbeit übernehmen kann. Ein solches Konto trägt `hold: "refresh"`, ein ausgeschöpftes Kontingent dagegen `hold: "quota"`. Ob ein anderes Konto die Arbeit übernehmen kann, entscheidet das Gateway, ohne Tales eigene Regeln zu kennen: die unten beschriebene Wartezeit nach HTTP 429 und die `account_id`, die OpenAI verlangt. Bleibt deshalb kein verfügbares Konto übrig, nimmt Tale unter den wegen ihrer Erneuerung zurückgehaltenen Konten dasjenige, dessen Erneuerung am weitesten entfernt ist, statt die Arbeit abzulehnen. Ein Durchlauf beginnt also nur dann mit einem Token, das kurz darauf widerrufen wird, wenn der Pool nichts Besseres hat; ein Pool mit nur einem Konto wird auf diese Weise nie zurückgehalten. Sendet ein Broker kein Feld `hold`, bleiben alle nicht verfügbaren Konten ausgeschlossen.

### Auswahl und Fehlerbehebung

`random` ist im Formular vorausgewählt; `first` folgt der Reihenfolge des Brokers. `round-robin` wählt das nutzbare Konto, dessen letzte Auswahl am längsten zurückliegt, und speichert den Verlauf je Organisation und Zugangsdaten-Eintrag. Gleichzeitige Anfragen verschiedener Backend-Prozesse aktualisieren ihn atomar. Eine andere Antwortreihenfolge und Backend-Neustarts setzen ihn nicht zurück. Damit der Verlauf eines Kontos auch nach einem Tokenwechsel erhalten bleibt, braucht es eine stabile `id`. Diese Verfahren verteilen Kontoauswahlen, nicht den Tokenverbrauch oder die Kapazität laufender Agenten. Bestehende Zugangsdaten behalten ihre gespeicherte Strategie.

Antwortet ein Konto mit HTTP 429, schließt Tale es für diese Organisation und diese Zugangsdaten 60 Sekunden lang von neuen Auswahlen aus. Bei Wiederholungsversuchen werden Konten bevorzugt, die während der aktuellen Fehlerfolge des Durchlaufs noch nicht versucht wurden. Wurden alle ansonsten nutzbaren Konten versucht, darf ein Konto erneut gewählt werden. Kontingentsperren und die Wartezeit gelten weiterhin. Befinden sich alle Konten in der Wartezeit, wird eine automatische Wiederholung einer Aufgabe oder Automatisierung sofort eingereiht, startet aber erst, sobald das erste Konto wieder verfügbar ist. Dieses Warten verbraucht keinen automatischen Wiederholungsversuch, wenn der abgelehnte Durchlauf selbst einen Fehler mit HTTP 429 wiederholte.

Ein HTTP 401 während eines Durchlaufs mit Broker-Token kann bedeuten, dass das Token während der Arbeit erneuert wurde. Tale fragt die Zugangsdaten erneut beim Broker ab und setzt die Konversation fort, sofern ihre Kennung und die Sandbox-Sitzung noch vorhanden sind. Andernfalls beginnt ein neuer Durchgang. Die ersten beiden solchen Unterbrechungen in Folge verbrauchen keinen automatischen Wiederholungsversuch und schließen das Konto nicht aus, damit ein Ersatz-Token desselben Kontos genutzt werden kann. Die dritte zählt wie jeder andere Fehler. Diese Grenze greift auch, wenn der 401 durch eine ungültige Autorisierung statt durch einen Tokenwechsel entsteht. Nach mindestens fünfzehn Minuten Arbeit beginnt die Zählung von vorn.

Ohne andere Vorgabe beträgt das Zeitlimit einer Pool-Anfrage 10 Sekunden, die maximale Antwortgröße 262.144 Bytes. Ein zugeordnetes Ablaufdatum muss weiter in der Zukunft liegen als der Sicherheitsabstand `expirySkewMs`, standardmäßig fünf Minuten. Behalte beim Tale AI Gateway die Status- und Ablaufzuordnung bei, damit inaktive oder bald ablaufende Tokens übersprungen werden; Konten, deren Token bald erneuert wird, hält das Gateway über seine Mindestrestlaufzeit bereits selbst zurück. Das Feld `refresh_at` des Gateways nennt den Zeitpunkt, zu dem seine Erneuerung ein Token beendet, früher als das `expires_at` des Anbieters. Ordnest du `refresh_at` als Ablauffeld zu und erhöhst `expirySkewMs` (höchstens 3.600.000 ms), wird diese Regel streng: Dann beginnt kein Durchlauf mit einem Token, das kürzer als der Sicherheitsabstand gilt. Solange aber alle Konten ihrer Erneuerung so nahe sind, nimmt der Pool keine neue Arbeit an, und ein Pool mit nur einem Konto tut das vor jeder Erneuerung. Ablaufwerte dürfen ISO-Zeitstempel oder Unix-Zeitstempel in Sekunden oder Millisekunden sein.

Die Mindestrestlaufzeit schützt den Start eines Durchlaufs, nicht seine gesamte Dauer. Lange Aufgaben- oder Automatisierungsdurchläufe können ein Token überdauern und die oben beschriebene, begrenzte Wiederholung benötigen. Eine erneute Broker-Anfrage garantiert keine funktionierenden Zugangsdaten.

Ist kein Konto nutzbar, prüfe Broker-Anmeldung, Kontostatus, Token-Ablauf und geplante Token-Erneuerungen, Kontingent-Erneuerungen und die Feldzuordnung. Erneuere gegebenenfalls die Kontoautorisierung oder warte, bis das Kontingent frei oder das Token erneuert ist. Prüfe anschließend eine abgeschlossene Aufgaben- oder Automatisierungsantwort mit dem vorgesehenen Anbieter und der passenden Laufzeit. Eine erfolgreiche Broker-Anfrage allein prüft die Verbindung zum Anbieter nicht.

## Broker-Geheimnisse aus der Umgebung

Zugangsdaten vom Typ **Abo-Broker** können das Broker-Geheimnis aus der Bereitstellungsumgebung lesen. Verwende im Feld **Secret aus Umgebungsvariable** das eigene Präfix `TALE_TOKEN_SOURCE_` und lasse **Broker-Secret** leer. Andere Namen werden abgelehnt. Gibst du beides an, hat das gespeicherte Broker-Geheimnis Vorrang. Erstelle die verwendenden Prozesse nach der Rotation eines Umgebungswerts neu.

Wenn die neue Broker-Konfiguration weiterhin eine Authentifizierung nutzt und du beide Geheimnisfelder leer lässt, bleibt das bisher gespeicherte Geheimnis erhalten. Ein Umgebungsverweis ohne neues Broker-Geheimnis stellt auf die Umgebungsquelle um. Wählst du bei der Broker-Authentifizierung **Keine**, wird das gespeicherte Geheimnis aus der ersetzenden Konfiguration entfernt.

## Organisationseinstellungen bei der Organisation verwalten

Namen von Zugangsdaten, erlaubte Modelle, Standards und Aktivierungszustand bleiben Organisationsdaten. Normalerweise verwaltest du sie unter [KI-Anbieter](https://docs.tale.dev/de/platform/admin/providers). Eine verwaltete Konfigurationsversion kann nach Prüfung von Organisation und Betreiber genaue umgebungsgebundene Zugangsdaten über native APIs anlegen. Sie installiert keinen Inferenzserver und belegt kein Modellverhalten. Prüfe nach der Bereitstellung den lokalen Endpunkt wie oben beschrieben.

# Aufbewahrungsgrenzen festlegen
Source: https://docs.tale.dev/de/self-hosted/configuration/retention

Die Aufbewahrungsrichtlinie bestimmt, wie lange Tale einzelne Datenkategorien behält. Betreiber legen die zulässigen Grenzen fest; Organisationsadmins aktivieren Kategorien und wählen eine Dauer innerhalb dieser Grenzen. Eine kürzere Dauer kann vorhandene Historie löschen. Prüfe deshalb die Folgen vor der Übernahme.

## Grenzen und Richtlinie unterscheiden

Zwei Dateien unter `TALE_CONFIG_DIR/<orgSlug>/governance/` erfüllen unterschiedliche Aufgaben:

| Datei | Zweck |
| --- | --- |
| `retention.yml` | Grenzen und Standardwerte des Betreibers für jede Kategorie. JSON wird ebenfalls akzeptiert. |
| `retention-policy.yml` | Aktivierte Kategorien und gewählte Fristen der Organisation. Die Governance-Einstellungen verwalten diese Datei. |

Jede Organisation erhält bei ihrer Erstellung eigene Dateien. Eine Änderung an einer Organisation ändert nicht die Richtlinie einer anderen. Fehlt ihre Grenzdatei, greift Tale nicht auf eine Organisation namens `default` zurück.

Jede Kategorie enthält `min`, `max`, `default` und `unit`. Ein höheres `min` verlangt eine längere Aufbewahrung; ein niedrigeres `max` begrenzt die zulässige Dauer. Keiner der beiden Werte aktiviert allein die Bereinigung. Dafür ist die angewendete Richtlinie maßgeblich.

## Grenzen einer Organisation ändern

Gehe von der vorhandenen vollständigen Datei aus und behalte unveränderte Kategorien bei. Dieser Ausschnitt zeigt eine einzelne Kategorie; er ersetzt nicht die gesamte Datei:

```yaml
chatHistory:
  min: 30
  max: 730
  default: 90
  unit: days
```

Die meisten Kategorien verwenden Tage; `userTempHours` und `agentTempHours` verwenden Stunden. Die Kategorie für den Tokenverbrauch heißt `usageLedger`. Verwende die Bezeichner aus der vorhandenen Datei, damit die Validierung Fehler erkennen kann.

Umgebungsvariablen werden ausdrücklich in `_metadata.envNames` an der Dateiwurzel zugeordnet, optional mit `_metadata.envPrefix`. Die mitgelieferte Datei ordnet beispielsweise `TALE_RETENTION_AUDIT_MIN` dem Feld `auditLog.min` zu. Eine Mindestgrenze darf über die Umgebung nur steigen, eine Höchstgrenze nur sinken. Starte die Backend-Prozesse nach Änderungen ihrer Umgebung neu.

Zwei Untergrenzen sind fest vorgegeben: `auditLog.min` darf nicht unter 180 Tagen liegen und `loginAttempt.min` nicht unter 90 Tagen. Eine Datei, die eine davon unterschreitet, lädt Tale nicht. Bis du sie korrigierst, zeigt die **Aufbewahrungsrichtlinie** der Organisation keine zulässigen Bereiche an und lässt sich nicht speichern; das Backend-Protokoll nennt beide Untergrenzen. Die geplante Bereinigung arbeitet weiter mit den zuletzt übernommenen Grenzen.

Mit der mitgelieferten Datei kann eine Organisation Audit-Logs 180 bis 3650 Tage aufbewahren. Ein Upgrade von Tale überschreibt die Datei einer Organisation nicht. Eine Organisation aus einem früheren Release kann deshalb noch `auditLog.min: 365` enthalten. Senke diesen Wert, um eine kürzere Aufbewahrung der Audit-Logs zu erlauben, oder erhöhe ihn, wenn eine Vorschrift oder ein Vertrag eine längere Audit-Historie verlangt.

## Änderung prüfen und übernehmen

Bitte nach der Änderung den Organisationsadmin, den Vorschlag unter [Richtlinien und Grenzen](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits) zu prüfen. Die Bereinigung verwendet den übernommenen Stand der Grenzen. Eine Dateiänderung des Betreibers aktiviert neue Grenzen nicht stillschweigend.

Prüfe aktivierte Kategorien, bisherige und neue Fristen sowie eine mögliche Schonfrist. `auditLogRetentionDays: 730` ist eine gewählte Dauer; `auditLog.min: 180` ist eine Mindestgrenze. Unterscheide diese Bedeutungen beim Prüfen eines Diffs.

<Tip>

Teste kürzere Fristen zunächst mit synthetischen Daten. Prüfe, ob Daten innerhalb der Frist erhalten bleiben, abgelaufene Daten der jeweiligen Löschregel folgen und gesperrte Daten geschützt bleiben.

</Tip>

## Ergebnis der Bereinigung verstehen

Der Backend-Worker bereinigt Daten nach Zeitplan und getrennt je Organisation. Threads, Dokumente, Kontakte und externe Konversationen durchlaufen einen Lebenszyklus. Kategorien mit einzelnen Datensätzen können nach Aufbewahrungs- und Schonfrist direkt gelöscht werden. Nicht jeder gelöschte Datensatz erscheint im Papierkorb.

Jeder Lauf löscht je Kategorie und Organisation nur eine begrenzte Zahl von Datensätzen: bis zu 50.000 Chat-Filter-Ereignisse und bei allen anderen Kategorien Stapel von höchstens 1.000 Datensätzen. Ein größerer Rückstand, etwa eine lange Historie beim ersten Aktivieren einer Kategorie, wird über mehrere tägliche Läufe abgebaut.

Auch Audit-Einträge werden je Organisation aufbewahrt. Die Bereinigung entfernt den ältesten zulässigen zusammenhängenden Anfang ihrer Audit-Kette und stoppt an einem Eintrag, den eine Aufbewahrungssperre schützt. Eine kürzere Frist eines Mandanten verkürzt nicht die Historie eines anderen.

Jeder Bereinigungslauf wird im [Audit-Log](https://docs.tale.dev/de/platform/admin/governance/audit-logs) der Organisation als Systemereignisse der Kategorie Daten festgehalten. Er beginnt mit **Aufbewahrungs-Run gestartet**, erfasst für jede Kategorie, in der er Datensätze gelöscht hat, ein einziges Ereignis mit deren Anzahl statt eines Ereignisses pro Datensatz, und endet mit **Aufbewahrungs-Run abgeschlossen**. Stoppt ein Lauf an einem Fehler oder behält er fällige Datensätze, weil ihre Löschung fehlgeschlagen ist, endet er stattdessen mit **Aufbewahrungs-Run fehlgeschlagen**; der nächste geplante Lauf versucht diese Datensätze erneut. Alle Ereignisse eines Laufs nennen denselben Aufbewahrungs-Run als Ziel, und auch ein Lauf, der nichts zu löschen findet, hält Beginn und Ende fest.

`TALE_RETENTION_DISABLED=true` pausiert die geplante Aufbewahrungsbereinigung für ein Wartungsfenster. Die Variable stellt keine Daten wieder her und verhindert keine anderen Löschwege. Halte ihre Aktivierung fest und entferne sie nach der Wartung.

## Gesperrte Daten bewahren

Aufbewahrungssperren haben für ihren unterstützten Geltungsbereich Vorrang vor der Richtlinie. Eine organisationsweite Sperre schützt die Organisation; engere Sperren schützen die zugeordneten Objekte oder Personen. Lies den [Ablauf für Aufbewahrungssperren](https://docs.tale.dev/de/platform/admin/governance/legal-hold), bevor du eine betroffene Richtlinie änderst.

Eine Sperre ersetzt kein Backup. Sind Daten außerhalb einer Sperre bereits gelöscht, bringt eine längere Frist sie nicht zurück. Dafür brauchst du ein erhaltenes Backup und den dazu passenden Bereitstellungsstand.

# Geheimnisse mit SOPS schützen
Source: https://docs.tale.dev/de/self-hosted/configuration/secrets-with-sops

Tale verwendet SOPS und age für unterstützte Geheimnisdateien der Konfiguration, unter anderem für Verbindungen zur Wissensdatenbank und zum Objektspeicher. Aktuelle Zugangsdaten für AI-Anbieter liegen dagegen in der Anwendungsdatenbank und verwenden `ENCRYPTION_SECRET_HEX`. Eine age-Schlüsselrotation ändert diese Datenbankzugangsdaten nicht.

## Das betroffene Geheimnis zuordnen

Die Speicherart bestimmt den passenden Schlüssel:

| Speicherung | Verschlüsselung | Folge für den Betrieb |
| --- | --- | --- |
| SOPS-fähige Konfigurationsdatei `*.secrets.json` | `SOPS_AGE_KEY` oder `SOPS_AGE_KEY_FILE` | Bewahre einen Schlüssel auf, der alle erhaltenen Dateien und Backups entschlüsselt. |
| Anbieterzugangsdaten und weitere Secret-Box-Werte in der Datenbank | `ENCRYPTION_SECRET_HEX` | Ein Austausch macht vorhandene Geheimnisse unlesbar; eine age-Rotation migriert sie nicht. |
| Anbieterzugangsdaten aus einer Umgebungsvariablen | `TALE_PROVIDER_KEY_*` | Rotiere den Wert im Secret-Manager und starte die verwendenden Prozesse neu. |

In alten Konfigurationsverzeichnissen kann noch `providers/<name>.secrets.json` liegen. Das bedeutet nicht, dass aktuelle Anbieterzugangsdaten diese Datei verwenden. Das heutige Modell beschreibt [Anbieter](https://docs.tale.dev/de/self-hosted/configuration/providers).

## Eine Quelle für den age-Schlüssel wählen

Ein direkt gesetztes `SOPS_AGE_KEY` hat Vorrang vor `SOPS_AGE_KEY_FILE`. Wähle bewusst eine Quelle. Die Dateivariante akzeptiert einen privaten age-Schlüssel pro Zeile und ignoriert Leerzeilen sowie `#`-Kommentare. Beim Schreiben neuer SOPS-Geheimnisse berücksichtigt Tale alle konfigurierten Empfänger.

Der Pfad gilt innerhalb des lesenden Prozesses. Ein Hostpfad in `.env` reicht nicht aus: Binde die Datei in jeden benötigten Container ein, verwende den Pfad im Container und beschränke den Dateizugriff. Erstelle betroffene Container nach einer Umgebungsänderung neu; `docker compose restart` übernimmt keine geänderten Umgebungsdefinitionen.

Sind beide Variablen leer, schreibt der SOPS-Helfer unterstützte Geheimnisdateien als Klartext-JSON mit Modus `0600`. Vorhandene verschlüsselte Dateien erkennt er weiterhin und verweigert den Zugriff ohne Schlüssel. Das Entfernen der Variablen entschlüsselt keine vorhandenen Dateien.

## Eine Rotation vorbereiten

Erfasse vor dem Schlüsseltausch alle SOPS-verschlüsselten Dateien und ihre Backups. Bewahre den alten Schlüssel geschützt auf und prüfe, ob sich eine repräsentative Datei entschlüsseln lässt, ohne ihren Inhalt auszugeben oder zu protokollieren.

Erzeuge einen neuen age-Schlüssel mit deinem vorhandenen Werkzeug zur Geheimnisverwaltung. Erstelle eine geschützte Schlüsseldatei mit **dem bisherigen und dem neuen privaten Schlüssel**. Überschreibe die alte Datei nicht mit einem Befehl, der nur einen neuen Schlüssel erzeugt.

Binde diese Datei in der Bereitstellung ein und setze `SOPS_AGE_KEY_FILE`. Entferne den direkten Wert aus der Umgebung der betroffenen Prozesse, sonst behält er Vorrang. Rolle die Änderung aus und prüfe, ob vorhandene Verbindungen weiter funktionieren.

## Neu verschlüsseln und prüfen

Schreibe jede betroffene Geheimnisdatei über ihren unterstützten Speicherweg oder ein kontrolliertes SOPS-Verfahren neu. Tale verschlüsselt neue Dateien für alle aktuell konfigurierten Empfänger. Ein zusätzlicher Schlüssel allein ändert vorhandene Dateien nicht.

<Warning>

Entferne den alten Schlüssel erst, wenn jede aktive verschlüsselte Datei mit dem neuen Schlüssel allein geprüft wurde. Bewahre den alten Schlüssel weiterhin geschützt für historische Backups auf, die ihn noch benötigen.

</Warning>

Stelle danach eine Schlüsseldatei bereit, die nur den neuen Schlüssel enthält. Starte die betroffenen Prozesse neu, um entschlüsselte Zwischenspeicher zu leeren, und teste jede Verbindung. Ein gelungener Prozessstart beweist nicht, dass jede Datei lesbar ist.

## Entschlüsselungsfehler beheben

| Symptom | Prüfung |
| --- | --- |
| Verschlüsselte Datei ohne Schlüssel gefunden | Stelle die passende Schlüsselquelle wieder her; ausgeschaltete Verschlüsselung konvertiert die Datei nicht. |
| Schlüsseldatei nicht lesbar | Prüfe Einbindung, Containerpfad, Eigentümer und Rechte. |
| Alter Schlüssel wird weiter gewählt | Entferne das nicht leere `SOPS_AGE_KEY`, bevor du die Datei verwendest. |
| Neuer Schlüssel kann eine Datei nicht lesen | Behalte den alten Schlüssel und verschlüssele die Datei vor Abschluss der Rotation neu. |
| Anbieterzugangsdaten scheitern nach Änderung von `ENCRYPTION_SECRET_HEX` | Stelle den Zugriff auf Datenbankgeheimnisse wieder her; age-Schlüssel helfen hier nicht. |

Für Geheimnisse aus Vault, Kubernetes oder einem anderen externen Speicher bevorzuge, soweit unterstützt, die [Schlüsselquelle aus Umgebungsvariablen](https://docs.tale.dev/de/self-hosted/configuration/providers#umgebungsvariable-als-schlusselquelle). Bewahre Verschlüsselungsschlüssel mit deinem Wiederherstellungsplan auf, getrennt geschützt von den Backups, die sie entschlüsseln.

# TLS und Domains
Source: https://docs.tale.dev/de/self-hosted/configuration/tls-and-domains

Lege vor der Anmeldungskonfiguration und vor Einladungen fest, welche URL Nutzer öffnen und welcher Dienst TLS beendet. Tales Caddy-Proxy kann eine interne Zertifizierungsstelle nutzen, öffentliche Zertifikate beziehen oder HTTP hinter deinem eigenen TLS-Proxy bereitstellen.

## TLS-Modus wählen

| `TLS_MODE` | Geeignet für | Deine Aufgabe |
| --- | --- | --- |
| `selfsigned` | Lokale Entwicklung oder private Umgebungen, deren Clients deiner CA vertrauen. | Caddys Stammzertifikat in den Vertrauensspeicher jedes Clients aufnehmen. |
| `letsencrypt` | Einen öffentlichen Hostnamen über Tales Proxy. | Öffentliches DNS, erreichbare Ports 80/443 und dauerhaften Caddy-Zertifikatsspeicher bereitstellen. |
| `external` | Einen vorgeschalteten Load-Balancer oder Reverse-Proxy mit TLS. | Dessen Zertifikat, vertrauenswürdige Weiterleitung und private HTTP-Verbindung zu Tale betreiben. |

`SITE_URL` bleibt die öffentliche URL, `HOST` ihr Hostname. Neue Umgebungswerte erfordern das Neuerstellen betroffener Dienste. Nutze bei der Workspace-CLI den Bereitstellungsablauf und `--stop`, wenn der Proxy neu erstellt werden muss. Prüfe die Vorschau und plane die Unterbrechung ein. In deiner eigenen Compose-Datei heißt der Dienst `proxy`, nicht wie der erzeugte Container.

## Einem privaten Entwicklungszertifikat vertrauen

Mit `TLS_MODE=selfsigned` stellt Caddy Zertifikate seiner internen CA aus. Eine Browserwarnung kann bedeuten, dass der Client dieser CA nicht vertraut oder der Hostname nicht passt. Prüfe beides.

Kopiere das **öffentliche Stammzertifikat** aus dem laufenden Proxy-Container. Setze `TALE_PROXY_CONTAINER` auf dessen tatsächlichen Namen:

```bash
docker cp "$TALE_PROXY_CONTAINER:/data/caddy/pki/authorities/local/root.crt" ./tale-local-root.crt
```

Prüfe die Herkunft aus deiner eigenen Instanz. Installiere es dann auf jedem benötigten Client über die Zertifikatseinstellungen des Betriebssystems oder Browsers. Verteile niemals den privaten CA-Schlüssel. `caddy trust` über `docker exec` ändert den Vertrauensspeicher des Containers, nicht den deines Arbeitsplatzrechners. [Caddys Anleitung für lokales HTTPS](https://caddyserver.com/docs/automatic-https#local-https) erklärt diese Grenze.

## Ein öffentliches Zertifikat beziehen

1. Richte die öffentlichen DNS-Einträge auf den vorgesehenen Host. Prüfe bei IPv6 sowohl A- als auch AAAA-Einträge.
2. Mache Ports 80 und 443 an diesem Proxy erreichbar und erhalte sein Volume `caddy-data` beim Ersetzen.
3. Konfiguriere öffentliche URL und Zertifikatsmodus:

```bash
HOST=tale.example.com
SITE_URL=https://tale.example.com
TLS_MODE=letsencrypt
TLS_EMAIL=ops@example.com
```

4. Übernimm die Konfiguration, prüfe `tale logs proxy` und öffne die öffentliche URL von einem anderen Rechner. Kontrolliere Hostname und Zertifikatskette im Browser.

Caddy übernimmt Ausstellung und Erneuerung. DNS-, Firewall-, ACME- oder Speicherprobleme können beides verzögern oder verhindern. Überwache daher Ablaufdatum und Proxy-Fehler, statt eine feste Ausstellungsdauer anzunehmen. `TLS_EMAIL` ist die ACME-Kontaktadresse und ersetzt keine Ablaufüberwachung. [Caddys HTTPS-Voraussetzungen](https://caddyserver.com/docs/automatic-https) beschreiben die öffentlichen Netzwerkbedingungen.

## Einen vorgeschalteten TLS-Proxy oder ein eigenes Zertifikat verwenden

Setze `TLS_MODE=external`, wenn ein anderer Proxy TLS beendet. Behalte die öffentliche HTTPS-URL bei:

```bash
HOST=tale.example.com
SITE_URL=https://tale.example.com
TLS_MODE=external
TRUSTED_PROXIES=10.20.0.0/16
```

Tales Caddy-Instanz stellt in diesem Aufbau intern HTTP bereit. Dein Proxy muss ihr deshalb mitteilen, wie der Browser verbunden ist: Leite den ursprünglichen `Host`-Header weiter und sende `X-Forwarded-Proto: https`. Anhand beider Werte hält Tale jeden Browser auf dem Ursprung, den er geöffnet hat. Caddy übernimmt weitergeleitete Header nur von den Adressen in `TRUSTED_PROXIES`: durch Leerzeichen getrennte CIDR-Bereiche oder `private_ranges` für alle privaten und Loopback-Adressen. Das gilt auch als Standard, wenn die Variable fehlt. Trage den Bereich ein, aus dem dein Proxy die Verbindung aufbaut. Andere Werte verhindern den Start des Proxys; die übrigen TLS-Modi ignorieren die Variable.

Halte die HTTP-Verbindung privat. Der Proxy-Container veröffentlicht Port 80. Erlaube dort nur deinem TLS-Proxy den Zugriff, sonst könnte ein Client aus einem vertrauenswürdigen Bereich eine HTTPS-Verbindung vorgeben, die es nie gab. Prüfe Anmeldung, sichere Cookies, Uploads und Streaming über den vollständigen Weg. Ein Zertifikat auf dem vorgeschalteten Proxy ist unabhängig von Tales TLS-Modus.

Wenn du stattdessen ein eigenes Tale-Proxy-Image mit eigener Caddyfile verwaltest, binde Zertifikat und privaten Schlüssel nur lesbar ein und konfiguriere Caddys Direktive `tls <cert-file> <key-file>`. Ein Mount oder `TLS_MODE=external` allein lädt die Dateien nicht. Die eigene Konfiguration muss Tales Routen, Zustandsprüfungen und Metrikschutz erhalten.

## Öffentliche Domain oder Basispfad ändern

Ändere `HOST` und `SITE_URL` gemeinsam. Prüfe auch öffentliche Speicherendpunkte und Callback-Registrierungen beim Identitätsanbieter, die den alten Ursprung verwenden. Erstelle betroffene Anwendungs- und Proxy-Dienste neu. Teste anschließend Anmeldung, Download einer vorhandenen Datei, Upload und eine live aktualisierte Seite unter der neuen URL.

Bei einem verwalteten Deployment mit `identity.bootstrap: "fresh"` gehört die [Migration des verwalteten Hostnamens](https://docs.tale.dev/de/self-hosted/install/cli-install#managed-origin-migration) zu diesem Wechsel. Sie benötigt den gespeicherten Deployment-Zustand und ein ausdrückliches `identity.migrateOriginFrom`. Nur `HOST` und `SITE_URL` zu ändern aktualisiert die verwalteten Identitäts- und Client-Journale nicht. Behalte Konto, Organisation und Client-Zugangsdaten bei und exportiere nach dem abgeschlossenen Deployment die Client-Konfiguration für den neuen Issuer.

Setze für einen Unterpfad wie `https://example.com/app` zusätzlich `BASE_PATH=/app`. Erhalte dieses Präfix bei Anfragen an Tales Proxy: Seine erzeugten Routen entfernen es intern. Prüfe absolute Links und Callbacks, nicht nur die Startseite. Halte bei einem geplanten Übergang die alte Domain erreichbar, solange Nutzer deren Links oder Sitzungen benötigen.

## Mehrere Domains bedienen {#mehrere-domains-gleichzeitig}

Trage zusätzliche reine Ursprünge, durch Komma oder Leerraum getrennt, in `ADDITIONAL_SITE_URLS` ein:

```bash
HOST=tale.example.com
SITE_URL=https://tale.example.com
ADDITIONAL_SITE_URLS=https://tale.partner.example,https://app.example.org
```

Ein Ursprung besteht aus Schema, Host und optionalem Port, aber keinem Pfad. Caddy bedient diese Ursprünge und fordert im Modus `letsencrypt` öffentliche Zertifikate an. Richte DNS und Erreichbarkeit für jeden ein. Es sind eigene Einstiegspunkte; Cookies gelten für die Domain der jeweiligen Anmeldung.

Beim Ableiten öffentlicher URLs akzeptiert Tale nur konfigurierte Ursprünge. Ein unbekannter Host fällt auf `SITE_URL` zurück. Verwende diesen Rückfall nicht als Ersatz für die Domainkonfiguration.

Bei einem verwalteten Deployment deklarierst du diese Ursprünge als `additionalOrigins` in der Deployment-Spezifikation, statt die Laufzeitumgebung zu bearbeiten; siehe [Zusätzliche Ursprünge bedienen](https://docs.tale.dev/de/self-hosted/install/cli-install#managed-additional-origins). Die CLI verwaltet dort `ADDITIONAL_SITE_URLS` und belässt die native Identität beim primären Ursprung.

### Kanonische Einstellungen stabil halten

| Einstellung | Warum die Hauptdomain wichtig ist |
| --- | --- |
| E-Mail-Links und Benachrichtigungen | Hintergrundarbeit hat keinen Browser-Ursprung. |
| SAML-SP-Entity-ID | Der Identitätsanbieter kennt einen stabilen Dienstanbieter. |
| SCIM-Ressourcenadressen | Verzeichnissynchronisierung braucht stabile URLs. |
| Passkeys | Zugangsdaten sind an eine Relying-Party-Domain gebunden und wechseln nicht automatisch zwischen Domains. |
| Öffentlicher Objektspeicher-Endpunkt | Hintergrundaufgaben signieren Dateilinks für diesen Endpunkt. Ein Link für den Browser nutzt die Domain, auf der dieser gerade ist, wenn der Endpunkt einer der Ursprünge dieses Deployments ist; prüfe einen separaten Datei-Host beim Domainwechsel. |

### Alle Anbieter-Callbacks registrieren

Kopiere unter **Einstellungen > Enterprise-SSO** die OIDC-Weiterleitungs- oder SAML-ACS-URL jeder Domain. Die SAML-Metadaten enthalten die konfigurierten ACS-Einträge. Für Konnektoren findest du die Weiterleitungs-URLs je Domain unter **Einstellungen > Connectors > OAuth-Apps**. Registriere die benötigten URLs bei jedem Anbieter und teste eine neue Anmeldung von jedem unterstützten Ursprung.

# Videotranskripte importieren
Source: https://docs.tale.dev/de/self-hosted/configuration/video-ingestion

Tale verwendet `yt-dlp`, um Inhalte für den Import von Videolinks abzurufen. Ob das gelingt, hängt vom Video, verfügbaren Untertiteln oder Extraktionsweg und den Zugriffsprüfungen der Plattform ab. Ein Video kann auf deinem Laptop abspielen und trotzdem Netzwerk oder Sitzung des Servers zurückweisen.

Diese Betriebsanleitung behandelt den Transkriptabruf. Beginne mit einem öffentlichen Video, auf das du zugreifen kannst, und lies den Importfehler, bevor du Zugangsdaten ergänzt oder den Netzausgang änderst.

## Die fehlerhafte Phase eingrenzen

| Beobachtung | Zuerst prüfen |
| --- | --- |
| Ein Video scheitert | Unterstützung der URL, Verfügbarkeit des Inhalts und brauchbare Transkript- oder Audioquelle. |
| Viele Videos scheitern von einem Host | Extraktionsfehler im Worker, Antworten der Quellplattform und Netzwerkweg dieses Hosts. |
| Abruf gelingt, Wissenssuche scheitert | Embedding-Konfiguration der Organisation und Indexierungsstatus. |
| Fehler nach einer zunächst funktionierenden Sitzung | Ablauf, Zustand des Quellkontos und Abkühlung oder Stilllegung im Pool. |

Lies `tale logs backend-worker --tail 200` und den Fehlergrund des Eintrags. Halte URL und Fehlerkategorie fest. Entferne vor dem Teilen Cookies, signierte URLs und Zugangsdaten aus Diagnosen. Ein erneuter Versuch kann bei vorübergehenden Fehlern helfen; gleichbleibende Verweigerungen erfordern eine Untersuchung.

## Mitgelieferten Token-Anbieter prüfen

Das Platform-Image enthält das Token-Plugin. Die mitgelieferte Bereitstellung startet `bgutil-provider` im internen Netzwerk unter `http://bgutil-provider:4416`. Der Dienst liefert Proof-of-Origin-Tokens für unterstützte Extraktionsanfragen. Er gewährt keinen Zugriff auf private Inhalte und garantiert keine Annahme durch die Quellplattform.

Prüfe `tale logs bgutil-provider` und die Erreichbarkeit vom Worker. Der Sidecar ist optional für den Start des Kernsystems: Sein Ausfall blockiert die Bereitstellung nicht, kann den Transkriptabruf aber beeinträchtigen.

`VIDEO_INGEST_POT_PROVIDER_URL` wählt einen anderen Anbieterendpunkt. `VIDEO_INGEST_PO_TOKEN` übergibt ein manuell beschafftes Token. Bewahre Tokens in deiner Geheimniskonfiguration auf. Die [Umgebungsreferenz](https://docs.tale.dev/de/self-hosted/configuration/environment-reference) beschreibt auch Extraktions-Client und Plugin-Optionen. Ändere sie passend zum beobachteten Fehler.

## Einen Egress-Proxy konfigurieren

Nutze `VIDEO_INGEST_PROXY_URL`, wenn Videoabrufe über einen freigegebenen Proxy laufen sollen. Metadaten, Untertitel und Audio verwenden diesen Weg. Unterstützt werden `http`, `https`, `socks4`, `socks4a`, `socks5` und `socks5h`; die letzte Variante löst DNS am Proxy auf.

```bash
VIDEO_INGEST_PROXY_URL=socks5h://proxy.example.com:1080
```

Ergänze erforderliche Zugangsdaten über deine Geheimnisverwaltung. Eine ungültige URL oder ein nicht unterstütztes Schema wird mit Warnung ignoriert. Prüfe deshalb die übernommene Konfiguration und einen echten Abruf. Erstelle den Worker nach Änderungen seiner Umgebung neu. Ein Neustart des bestehenden Containers liest eine geänderte `.env` nicht ein.

Ein anderer Netzwerkweg garantiert keinen Zugriff. Prüfe, ob Proxy und Quellkonto für die benötigten Inhalte verwendet werden dürfen. Bleibt die Quelle unerreichbar, importiere ein bereits vorliegendes Transkript als [Wissensdokument](https://docs.tale.dev/de/platform/knowledge/documents).

## Eine berechtigte Browsersitzung importieren

Der Server kann Cookies aus einem nach **Organisation und Domain** getrennten Sitzungspool beziehen. Er verschlüsselt Cookie-Dateien mit `ENCRYPTION_SECRET_HEX` und gibt sie in Listen nicht zurück. Der Pool gehört zum serverseitigen Videoimport und exportiert keine Cookies an Agentenskripte.

Es gibt kein Importformular in der Anwendung. Der REST-Schreibzugriff braucht einen Schlüssel eines Organisationsadministrators, dessen Konto auf `TALE_DEPLOYMENT_CONFIG_ADMINS` steht. Der Schlüssel muss zudem die Zielorganisation auflösen können. `GET /api/v1/me` zeigt dafür `capabilities.deploymentEditor`. Gib die Organisation mit `X-Organization-Slug` ausdrücklich an, besonders bei mehreren Mitgliedschaften.

1. Exportiere eine Cookie-Datei im Netscape-Format aus einer berechtigten Browsersitzung für die Quelldomain. Behandle sie wie Kontozugangsdaten und halte sie aus der Versionsverwaltung heraus.
2. Setze `TALE_URL`, `TALE_API_KEY` und `TALE_ORG_SLUG` für Instanz und Organisation. Beschränke den Lesezugriff auf `cookies.txt` auf das Betreiberkonto.
3. Importiere die Datei, ohne ihren Inhalt als Befehlsargument zu übergeben:

```bash
jq -n --arg domain youtube.com --rawfile cookiesJar cookies.txt \
  '{domain: $domain, cookiesJar: $cookiesJar, label: "operator-managed session"}' |
  curl --fail-with-body -sS -X POST "$TALE_URL/api/v1/browser-sessions/import" \
    -H "Authorization: Bearer $TALE_API_KEY" \
    -H "X-Organization-Slug: $TALE_ORG_SLUG" \
    -H 'Content-Type: application/json' \
    --data-binary @-
```

Ein erfolgreicher Import liefert HTTP 201 mit `sessionId`. Ungültige Daten führen zur Validierungsverweigerung, fehlende Rechte zu 403. Kläre die genannte Schranke, statt nur für den Aufruf eine weitergehende Rolle zu vergeben.

## Sitzungen prüfen und widerrufen

```bash
curl --fail-with-body -sS "$TALE_URL/api/v1/browser-sessions" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG"
```

Die Liste zeigt Metadaten wie Status, Ablauf und Fehlerzahl. Die Standardlaufzeit beträgt 14 Tage. Beim Import ist ein positives `ttlMs` bis 180 Tage möglich. Cookies der Quelle können früher ablaufen; ein noch gültiger Pool-Eintrag beweist keine funktionierende Kontositzung.

Ein blockierter Abruf lässt eine Sitzung abkühlen. Wiederholte Blockaden können sie stilllegen; ein geplanter Lauf bereinigt abgekühlte oder abgelaufene Einträge. Ein späterer Versuch kann eine andere gesunde Sitzung derselben Organisation und Domain verwenden. Ohne passende Sitzung kann der Abruf mit den anderen konfigurierten Optionen fortfahren.

Widerrufe eine importierte Sitzung mit `DELETE /api/v1/browser-sessions/<sessionId>` und demselben Organisationsumfang sowie den erforderlichen Schreibrechten. Prüfe die ID zuvor in der Liste. Widerrufe oder erneuere auch die Sitzung beim Quellkonto, wenn ihre Cookies offengelegt wurden. Teste zuletzt ein kontrolliertes Video und prüfe Transkript sowie Indexierung. Der Cookie-Import allein belegt keinen erfolgreichen Videoimport.

# Tale auf deiner Infrastruktur betreiben
Source: https://docs.tale.dev/de/self-hosted

Mit selbst gehostetem Tale bestimmt deine Organisation, wo die Anwendung läuft, wo Daten gespeichert werden und welche Modelle sie nutzt. Die Open-Source-Plattform bietet dieselben Produktfunktionen wie die Enterprise-Ausgabe. Dein Team betreibt die Infrastruktur und legt fest, welche externen Dienste sie erreichen darf.

Für deine erste Installation folge dem [lokalen Schnellstart](https://docs.tale.dev/de/self-hosted/install/quickstart): Installiere die veröffentlichte CLI und führe `tale init` und danach `tale dev` aus. Der Leitfaden führt dich vom Inhaberkonto über die Anbieterverbindung bis zur ersten Chatantwort. Docker führt die fertigen Dienste aus; du brauchst weder einen Quellcode-Klon noch Build-Werkzeuge. Wenn `tale --help` den Befehl `doctor` aufführt, kannst du deinen Rechner mit `tale doctor` vor dem Anlegen des Projekts prüfen.

## Den passenden Einstieg wählen

| Dein Vorhaben | Einstieg |
| --- | --- |
| Eine lokale Instanz testen oder eine neue Umgebung installieren | [Schnellstart zur Installation](https://docs.tale.dev/de/self-hosted/install/quickstart) |
| Dienste, Datenhaltung und Netzwerkverbindungen verstehen | [Architekturübersicht](https://docs.tale.dev/de/self-hosted/overview) |
| Ein eigenes Compose- oder Kubernetes-Deployment aufsetzen | [Einen eigenen Stack betreiben](https://docs.tale.dev/de/self-hosted/install/own-compose) |
| Den Quellcode der Anwendung ändern | [Entwicklungsumgebung einrichten](https://docs.tale.dev/de/develop/contributor-setup) |
| Eine bereits betriebene Instanz nutzen | [Deine erste Nachricht senden](https://docs.tale.dev/de/get-started/quickstart) |

## Die Betriebsverantwortung klären

Lege fest, wer Zugriff, TLS, Updates, Backups, Überwachung und Störungen betreut, bevor du weitere Nutzer hinzufügst. Richte einen KI-Anbieter ein. Für durchsuchbare Dokumente brauchst du außerdem ein Embedding-Modell und den Wissensspeicher. Teste einen Upload und einen vollständigen Chat, bevor du die Instanz freigibst.

Selbst zu hosten bedeutet nicht, dass jede Anfrage im eigenen Netzwerk bleibt. Ein konfigurierter Modellanbieter, Connector, Webcrawler oder externer Überwachungsdienst kann Daten erhalten. Prüfe die tatsächlichen Ziele anhand der [Sicherheitshärtung](https://docs.tale.dev/de/self-hosted/operate/security/hardening) und der Anbieterkonfiguration. Für eine isolierte Installation müssen Images, Modelle, Zugangsdaten und Abhängigkeiten lokal verfügbar sein.

## Die Instanz konfigurieren und warten

Die [Umgebungsreferenz](https://docs.tale.dev/de/self-hosted/configuration/environment-reference) beschreibt Deployment-Variablen; die Konfigurationsanleitungen behandeln Organisationseinstellungen. Die [Container-Architektur](https://docs.tale.dev/de/self-hosted/operate/container-architecture) erklärt die Abhängigkeiten im Betrieb. [Backups und Wiederherstellung](https://docs.tale.dev/de/self-hosted/operate/backups-and-restore) hilft dir bei der Wiederherstellungsplanung.

Soll Tale den Dienst für dein Team betreiben, lies [Tale Cloud](https://docs.tale.dev/de/cloud). Die Plattformanleitungen gelten für beide Hosting-Varianten.

# Die tale-CLI installieren
Source: https://docs.tale.dev/de/self-hosted/install/cli-install

Mit der `tale`-CLI installierst und betreibst du Tale und stellst neue Versionen bereit. Installiere sie dort, wo du deine Betriebsbefehle ausführen möchtest. Danach hilft dir der [lokale Schnellstart](https://docs.tale.dev/de/self-hosted/install/quickstart) oder der unten beschriebene Deployment-Ablauf weiter.

Dieselbe CLI übernimmt Container-Operationen im Workspace, verwaltete Deployments aus exakten Quell-Commits und Client-Konfigurations-Releases. Deine Deployment-Automatisierung wählt Ziel, Referenzen und Zugangsdatenverweise und ruft die CLI auf. [Client-Konfigurationen veröffentlichen](https://docs.tale.dev/de/self-hosted/configuration/config-releases) behandelt die Inhalte im eigenen Repository des Clients.

Für deine erste Instanz nutze den [Schnellstart](https://docs.tale.dev/de/self-hosted/install/quickstart). Der übliche Ablauf ist `tale init` und danach `tale dev`. Eine Spezifikation für verwaltete Deployments brauchst du erst, wenn deine Automatisierung exakte Quell-Commits für Laufzeit und Client festlegen muss.

## Bevor du beginnst

Du brauchst:

- Einen Rechner mit macOS, Linux oder Windows mit PowerShell.
- Für lokale Container: Docker mit Compose und einen laufenden Docker-Daemon.
- Für einen entfernten Workspace: Zugriff auf dessen Docker-Daemon, üblicherweise über einen SSH-Docker-Kontext. Der Benutzer auf dem Zielhost muss Docker ausführen dürfen.

Den mitgelieferten Objektspeicher gibt es derzeit nur als `linux/amd64`-Image. Auf ARM64-Hosts brauchen lokale Entwicklung und Workspace-Deployments deshalb eine funktionierende amd64-Emulation: Docker Desktop bringt sie mit; auf einem eigenständigen Linux-Docker-Host muss [QEMU auf dem Host registriert sein](https://docs.docker.com/build/building/multi-platform/#install-qemu-manually). Tale wählt das amd64-Image aus, installiert aber keine Emulation. Verwaltete Bundles benötigen weiterhin native Images für ihre deklarierte Architektur. Ein verwaltetes ARM64-Deployment ist daher erst mit einem nativen Objektspeicher-Image möglich.

Der Installer lädt die ausführbare Datei von GitHub herunter. Dafür braucht er Zugriff auf `raw.githubusercontent.com`, `api.github.com`, `github.com` und die Download-Ziele, auf die GitHub weiterleitet.

## install-cli.sh oder install-cli.ps1 ausführen

Auf macOS oder Linux:

```bash
curl -fsSL https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.sh | bash
```

Auf Windows PowerShell:

```powershell
irm https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.ps1 | iex
```

Der Unix-Installer wählt die Datei für dein Betriebssystem und deine CPU. Er ersetzt standardmäßig eine vorhandene `tale`-Datei im `PATH` oder installiert sie unter `/usr/local/bin`. Nur wenn das Verzeichnis sonst nicht beschreibbar ist, fordert er `sudo` an. Unter Windows nutzt der Installer standardmäßig `%LOCALAPPDATA%\Programs\tale` und ergänzt den `PATH` deines Benutzers.

Fertige Binärdateien gibt es für macOS mit Apple Silicon oder Intel, Linux mit x86_64 oder arm64 sowie Windows x64. Windows ARM benötigt die x64-Emulation. Bei einer nicht unterstützten Unix-Architektur verweist der Installer auf den Build aus dem Quellcode.

Mit `VERSION` legst du eine Release-Version fest, mit `INSTALL_DIR` ein anderes Zielverzeichnis. **Exportiere** diese Variablen in einer Unix-Shell vor dem Aufruf der Pipeline, damit auch `bash` sie erhält. Eine Zuweisung nur vor `curl` erreicht den Installer nicht. In PowerShell nutzt du `$env:VERSION` und `$env:INSTALL_DIR`.

| OS      | Installer-Skript          |
| ------- | ------------------------- |
| macOS   | `scripts/install-cli.sh`  |
| Linux   | `scripts/install-cli.sh`  |
| Windows | `scripts/install-cli.ps1` |

## Verifizieren

```bash
tale --version
```

Die CLI zeigt die installierte Version. Falls der Befehl nicht gefunden wird, prüfe das Zielverzeichnis in der Installer-Ausgabe und ergänze es im `PATH`. Falls ein bereits geöffnetes Windows-Terminal `tale` weiterhin nicht findet, öffne es neu. Schlägt der Download fehl, prüfe die oben genannten Netzwerkziele. Mit der optionalen Umgebungsvariable `GITHUB_TOKEN` authentifizierst du die Release-Abfrage, falls GitHub anonyme API-Anfragen begrenzt.

## Konfiguration prüfen

Nutze für Container-Befehle den Workspace, den du mit `tale init` im [Schnellstart](https://docs.tale.dev/de/self-hosted/install/quickstart) erstellt hast. Die CLI sucht im aktuellen Verzeichnis und seinen Eltern nach `tale.json`. Prüfe das gewählte Projekt, bevor du es veränderst:

```bash
tale config show
```

Konfigurations-Releases und [verwaltete Deployments](https://docs.tale.dev/de/self-hosted/install/cli-install#managed-deployments) wählen Quellen und Ziele explizit und gleichen sich nicht an einen benachbarten Workspace an. `config show` behält sein bisheriges Verhalten für lokale Projekte.

Bei Workspace-Deployments liegen Proxy-Host, TLS-Einstellungen und Secrets in der `.env` des Projekts. Ändere für die Produktion `HOST` dort oder übergib `--host` an `tale deploy`. Lokal verwendet `tale dev` standardmäßig `localhost`; seine Optionen `--host` und `--port` gelten nur für diesen Lauf. Für entfernte Workspace-Hosts nutzt du den Docker-Kontext deiner Shell oder `DOCKER_HOST`. Ein verwaltetes Bundle-Deployment läuft dagegen auf dem festgelegten Ziel mit dessen lokalem Docker-Daemon.

## tale deploy ausführen

```bash
tale deploy
```

Ohne `--bundle` stellt `tale deploy` die Version der CLI bereit: Es lädt deren Images, startet betroffene Container in der vorgesehenen Reihenfolge und führt Schema-Migrationen aus. Wähle eine andere Workspace-Version vorher mit `tale update`. Für getrennt festgelegte Runtime- und Client-Quell-Commits nutze [Verwaltete Deployments](https://docs.tale.dev/de/self-hosted/install/cli-install#managed-deployments).

## Befehlsreferenz

Die CLI gruppiert ihre Befehle danach, was du gerade tust — genau wie `tale --help`. Jeder Befehl und seine Argumente sind unten aufgeführt. So liest du die Notation:

- Ein positionales Argument in `[eckigen Klammern]` ist **optional**, eines in `<spitzen Klammern>` ist **erforderlich**.
- Pflichtoptionen für Konfigurations-Releases sind ausdrücklich benannt; andere Flags sind optional, sofern die Befehlshilfe sie nicht als erforderlich markiert.
- Ein Flag der Form `--flag <wert>` **erfordert einen Wert**, wenn du es nutzt (z. B. `--port 8443`); ein bloßes Flag wie `--detach` ist ein boolescher Schalter.
- **Standardwerte** stehen in Klammern hinter der Beschreibung. Kein Standard bedeutet, das Flag ist aus oder der Wert wird aus `.env` / Kontext aufgelöst.

Diese Referenz beschreibt auch Befehle aus dem aktuellen Quellcode. Die veröffentlichte CLI-Version v0.5.70 enthält weder `tale doctor` noch `tale dev --stop`. Mit `tale --help` und `tale <befehl> --help` prüfst du, welche Befehle und Optionen deine installierte Version unterstützt.

**Globale Flags** funktionieren bei jedem Befehl:

- `--verbose` — ausführliche Ausgabe: Debug-Logs und der rohe Subprozess-Stream (nur die Langform; ein `-v` gibt es nicht).
- `-q, --quiet` — nur Warnungen und Fehler.
- `-y, --yes` — bei allen Rückfragen «ja» annehmen (nicht-interaktiv).
- `--no-color` — ANSI-Farben deaktivieren (berücksichtigt auch `NO_COLOR` / `FORCE_COLOR`).
- `--json` — maschinenlesbares JSON auf stdout; unterstützt von `doctor`, `status`, `sandbox status`, allen `config`-Unterbefehlen und verwalteten Deployment-Befehlen.
- `--ci` — erzwingt nicht-interaktive, rein anhängende Ausgabe (keine Cursor-Steuerung).

Befehle beenden mit `0` bei Erfolg, `2` bei einem Nutzungsfehler, `3` bei einer nicht erfüllten Voraussetzung (kein Projekt, Docker läuft nicht, Port belegt), `4` bei einem Abbruch durch dich (Ctrl-C oder eine erforderliche Rückfrage ohne Terminal) und `5` beim Fehler einer externen Abhängigkeit — so können Skripte anhand der Ursache verzweigen.

### Einrichtung

`tale doctor` — prüft die Voraussetzungen für einen lokalen Start, ohne ein Projekt anzulegen, Software zu installieren oder Konfiguration zu ändern. Der Befehl prüft Docker-Daemon, Compose-Unterstützung und Linux-Container-Modus, meldet die Daemon-Architektur und untersucht lokale Ports. Bei einem entfernten Docker-Kontext entfällt die lokale Portprüfung. Prüfe Warnungen zu ARM64 oder belegten Ports; eine bestehende Instanz kann den Port bereits verwenden.

- `-p, --port <port>` — zu prüfender HTTPS-Port (Standard `443`); Sandbox-Port `8003` wird ebenfalls geprüft.
- `--json` — gibt die Prüfergebnisse als maschinenlesbares JSON aus.

Fehler bei Docker, Compose, einem nicht unterstützten Container-Modus oder die Wahl von HTTPS-Port `8003` führen zum Exit-Code `3`. Warnungen allein ergeben `0`; Image-Downloads, Speicherkapazität und Modellanbieter sind damit nicht geprüft. Prüfe einen anderen Port mit `tale doctor --port 8443` und verwende denselben Port bei `tale dev`.

`tale init [directory]` — ein Projekt anlegen: erzeugt die Beispiel-Configs, `AGENTS.md` + einen `CLAUDE.md`-Verweis sowie eine lokale Standard-`.env` (localhost, selbstsigniertes Zertifikat, generierte Secrets). Docker braucht es nicht; Produktiv-Domain und TLS werden später bei `tale deploy` gewählt. Im Terminal fragt es nach einem Projektnamen, wenn `directory` fehlt, bestätigt vor dem Überschreiben eines bestehenden Projekts und fragt einmal, ob Agents in Sandboxes `docker` ausführen dürfen (Standard: nein — die Freigabe startet einen privilegierten inneren Docker); nicht-interaktive Läufe überspringen alle Rückfragen. `directory` ist optional (Standard: das aktuelle Verzeichnis).

- `-f, --force` — eine vorhandene `tale.json` überschreiben statt abzubrechen.
- `--no-env` — das Projekt anlegen, aber die `.env`-Generierung überspringen.

`tale dev` — alle Dienste lokal mit selbstsigniertem Zertifikat starten. Der gewählte Host und Port bestimmen die lokale Anwendungsadresse für diesen Lauf, ohne die Produktionseinstellungen in `.env` umzuschreiben. Die Bereitschaftsprüfung wartet, bis Dienste mit Gesundheitsprüfungen gesund sind und die übrigen Dienste laufen. Läuft sie ab, prüfe vor dem nächsten Versuch die Protokolle der gemeldeten Dienste.

- `-d, --detach` — im Hintergrund laufen statt Logs zu streamen.
- `--stop` — stoppt die lokalen Entwicklungscontainer dieses Projekts und erhält ihre Daten. Mit `tale dev` setzt du den Betrieb fort.
- `-p, --port <port>` — auszugebender HTTPS-Port (Standard `443`).
- `--host <hostname>` — Host-Alias für den Proxy (Standard `localhost`).
- `-y, --yes` — nicht-interaktiv: Abfragen automatisch akzeptieren (z. B. Docker installieren oder starten).

`tale deploy` — die aktuelle CLI-Version bereitstellen und Anwendungsrollen per Blue-Green-Verfahren ersetzen. Gemeinsame Ausführungsdienste werden direkt ersetzt; Datenbank und Proxy brauchen dafür `--stop`. Beim ersten Deployment fragt die CLI nach Produktiv-Domain und TLS-E-Mail, soweit nicht vorgegeben. Lies vor Änderungen einer bestehenden Installation [Upgrades](https://docs.tale.dev/de/self-hosted/operate/upgrades).

- `--stop` — auch die stop-gebundene Schicht (`db`, `proxy`) aktualisieren — sie wird neu erstellt, also nimm eine kurze Ausfallzeit in Kauf; ohne das Flag bleiben laufende `db`/`proxy` unangetastet.
- `-s, --services <list>` — nur diese kommagetrennten Dienste aktualisieren (Standard: alle rotierbaren Dienste).
- `--host <hostname>` — Host-Alias für den Proxy (Standard: der `HOST`-Wert aus `.env`).
- `--override` — Container-Config aus dem Host-Workspace überschreiben (verschlüsselte `*.secrets.json` und `.history/` bleiben stets erhalten).
- `--override-all` — den Builtin-Katalog serverseitig in jede Organisation zurücksetzen; impliziert `--stop`.
- `-q, --quiet` — Container-Logs während des Deployments unterdrücken.
- `-y, --yes` — destruktive Bestätigungsabfragen automatisch akzeptieren (z. B. `--override-all`).
- `--skip-backup` — den automatischen Pre-Deploy-Snapshot überspringen.
- `--dry-run` — Vorschau ohne Änderungen.

### Verwaltete Deployments {#managed-deployments}

Nutze eine geprüfte Deployment-Deklaration, wenn Runtime und Client-Konfigurationen exakten Quell-Commits folgen sollen. Deine Deployment-Automatisierung wählt Ziel, Zugangsdaten und Referenzen und ruft die Tale-CLI auf. Die CLI beschafft Quellen, ermittelt und prüft Image-Digests, bereitet den Transfer vor, erhält unterstützten Bestandszustand, erstellt erforderliche Wiederherstellungssnapshots, rollt den Stack aus, provisioniert die native Instanz und prüft die Konfiguration. Diese Deployment-Logik bleibt in Tale.

#### Laufzeit und Quellstände vorbereiten

Führe die Vorbereitung unter Linux mit einer kompilierten CLI aus einem sauberen, committeten Tale-Checkout aus. Die Architektur muss zum Ziel passen: `linux/amd64` oder `linux/arm64`. Dasselbe Binary reist für die lokale Provisionierung im Backend mit. Die Vorbereitung braucht Git und Docker zur Quellen- und Image-Prüfung. Anwenden läuft auf dem Ziel mit dessen lokalem Docker-Daemon, erhaltenem Zustandsverzeichnis und Umgebung. Vollständiger CLI-Commit, Runtime-Quell-Commit und Quell-Commit der Client-Konfiguration sind getrennte Referenzen. Auf dem Ziel veröffentlicht die vorbereitete Runtime nur die Ports 80 und 443 des Proxys sowie die beiden Datenbanken auf `127.0.0.1:5432` und `127.0.0.1:5433`; der Sandbox-Spawner (8003) und sein Geräte-Hub (8004) bleiben im internen Netzwerk, wo Backend und Proxy sie erreichen.

Ein verwaltetes Deployment hält seinen Wiederherstellungspunkt fest, bevor es etwas ändert: den Snapshot vor dem Deployment und das Bundle, das gerade angewendet wird, beides im Zustandsverzeichnis, bis der Ready-Beleg geschrieben ist. Ein unterbrochenes Deployment erwartet beim nächsten Versuch deshalb dasselbe Bundle und lehnt ein anderes ab; die Ablehnung nennt den sha256 des ausstehenden Bundles. Kann dieses Bundle nicht mehr abschließen — etwa weil inzwischen eine korrigierte CLI gepinnt ist —, trägst du den genannten sha256 als `supersedesPendingBundle` in die Deployment-Deklaration ein und bereitest erneut vor: Das geprüfte Bundle übernimmt denselben Snapshot, der Ready-Beleg führt es unter `supersededBundles`, und danach nimmst du den Eintrag wieder heraus. Diese Übernahme gilt für den Wiederherstellungspunkt des Deployments, nicht für einen laufenden Runtime-Rollout. Ein Rollout, der nach der Prüfung seiner Images angehalten hat — beim Compose-Start oder beim Warten auf die Gesundheitsprüfungen —, läuft nur mit derselben vorbereiteten Runtime (`runtime/runtime.json`) und denselben Einstellungen für Origin, TLS und Umgebung weiter. Ein Bundle mit abweichender Runtime oder abweichenden Einstellungen lehnt er ab, ob mit `supersedesPendingBundle` oder ohne, und zwar mit `A different runtime operation is pending; recover that exact operation first.` Schließe ihn mit dem Bundle ab, das ihn begonnen hat, bevor du die gepinnte CLI in eine der beiden Richtungen wechselst: Eine andere CLI kann aus demselben Runtime-Commit eine andere Runtime vorbereiten. Die backendlokalen Phasen (`deploy provision`, `deploy export-client-native`) laufen im Backend unter dessen eigenem Benutzer, dem Eigentümer seines Datenverzeichnisses; schlägt eine fehl, wiederholt das Deploy-Ergebnis die Zusammenfassung der inneren CLI.

Der Snapshot vor dem Deployment enthält auch den Speicher des Modell-Gateways, `llm-gateway-data`, den ein neueres Gateway beim ersten Start darauf unumkehrbar migriert. Ein ausstehendes Deployment, das nichts geändert hat, hält keinen Snapshot fest. Eine Übernahme mit `supersedesPendingBundle` oder ein erneuter Versuch, der die Runtime ändern würde, erstellt zuerst den Snapshot und hält ihn beim ausstehenden Deployment fest. Ein Wiederherstellungspunkt ohne den Speicher des Gateways (ein Snapshot aus der Zeit, bevor die CLI ihn erfasste, oder keiner nach der Übernahme durch eine ältere CLI) blockiert jeden Rollout, der ein Gateway-Image starten würde, das laut Runtime-Beleg und Gateway-Container noch nie auf dem Speicher lief: Das Anwenden wird abgelehnt, bevor sich etwas ändert, und der ausstehende Beleg bleibt, wie er war, denn ein jetzt erstellter Snapshot könnte schon einen migrierten Speicher enthalten. Entferne den Beleg nicht. Solange kein Runtime-Rollout aussteht, kann ein geprüftes Bundle, das noch das zuletzt laufende Gateway-Image des Deployments auflöst, es mit `supersedesPendingBundle` übernehmen; der Rollout danach erstellt einen Snapshot, der den Speicher des Gateways enthält. Steht bereits ein Runtime-Rollout aus, bietet die CLI für diesen Zustand keinen Weg weiter. Ein Rollout auf einem Gateway-Image, mit dem der Speicher schon lief, schließt ab und warnt, wenn der zugehörige Snapshot den Speicher nicht enthält oder es gar keinen Wiederherstellungspunkt gibt. Ein verwaltetes Deployment rollt nie von selbst zurück und stellt kein Volume wieder her; es behält seinen ausstehenden Zustand für die Wiederherstellung.

Verwaltete Bundle-Befehle sind unter Windows nicht verfügbar, einschließlich `deploy verify-bundle` und des backendlokalen `deploy provision`. Die Integritätsprüfungen benötigen POSIX-Ausführungsrechte. Führe das vollständige verwaltete Deployment auf einem Linux-Host aus. Gewöhnliche Workspace-Befehle sowie eigenständige `config build`, `verify`, `stage`, `deploy` und `verify-native` bleiben unter Windows verfügbar.

Dieses synthetische Beispiel adressiert eine bestehende Organisation und ein Projekt. Ersetze die öffentlichen IDs und setze die benannten Umgebungswerte. `revision` nimmt einen vollständigen Commit-SHA oder einen Umgebungsverweis an. Zugangsdaten bleiben Verweise und werden am Ziel privat aufgelöst. `tlsMode: "external"` nutzt vorhandenes öffentliches TLS am vorgeschalteten Zugang; `letsencrypt` verlangt zusätzlich `tlsEmail`.

Nutze für Linux- oder macOS-ARM64-Jobs in GitHub Actions Tales Composite Action `.github/actions/setup-cli`. Lege die Action und `revision` auf denselben vollständigen Tale-Commit fest. Sie baut mit Bun 1.4.2, prüft das fertige Binary, liefert `executable` und ergänzt den `PATH`. macOS-Builds unterstützen die allgemeine Konfigurationsvorbereitung; ein verwalteter Linux-Stack braucht weiter ein passendes Linux-Binary. Setze auf einem Linux-x64-Runner `linux-baseline: 'true'`, wenn die Ziel-CPU kein AVX2 unterstützt (etwa Intel vor Haswell): Das Standard-Binary bricht dort mit `Illegal instruction` ab, das Baseline-Binary läuft. Andere Runner lehnen die Option ab.

Auch `origin` und einzelne native `redirectUris` akzeptieren Umgebungsverweise. So kann eine Deployment-Registry die öffentlichen Adressen verwalten. Die Vorbereitung löst sie zu geprüften wörtlichen HTTPS-URLs im Bundle auf.

Im Beispiel macht `runtime.containerPrefix` die Umgebung in der Containerliste erkennbar. Die optionale Einstellung wird unten erläutert.

```json
{
  "schemaVersion": 1,
  "name": "example-native",
  "stateDirectory": "/opt/tale-example",
  "composeProject": "tale-example",
  "runtime": {
    "revision": { "env": "TALE_RUNTIME_REF" },
    "platform": "linux/amd64",
    "containerPrefix": "north-desk-prod"
  },
  "origin": { "env": "TALE_PUBLIC_ORIGIN" },
  "tlsMode": "external",
  "identity": {
    "email": { "env": "EXAMPLE_OPERATOR_EMAIL" },
    "password": { "env": "EXAMPLE_OPERATOR_PASSWORD" },
    "slug": "example-team",
    "name": "Example team",
    "ssoEnabled": false,
    "nativeClients": [
      {
        "key": "example-portal",
        "name": "Example portal",
        "clientId": { "env": "EXAMPLE_NATIVE_CLIENT_ID" },
        "redirectUris": [{ "env": "EXAMPLE_PORTAL_CALLBACK" }]
      }
    ]
  },
  "configs": [
    {
      "repository": "https://github.com/example-team/client-app",
      "revision": { "env": "EXAMPLE_CONFIG_REF" },
      "client": "example-team",
      "descriptor": "tale/client.json",
      "automation": "document-review",
      "projectId": "existing-project-id",
      "skillOwner": "native-operator-id"
    }
  ]
}
```

#### Die Umgebung für Fehlerberichte wählen

Verwaltete Laufzeiten setzen `SENTRY_ENVIRONMENT` standardmäßig auf den bestehenden Deployment-`name`. Für eine kanonische Bezeichnung wie `example-pr` deklarierst du `"environment": { "SENTRY_ENVIRONMENT": { "env": "TALE_REPORTING_ENVIRONMENT" } }` und setzt die Variable am Ziel. Die Bezeichnung beginnt mit einem Kleinbuchstaben oder einer Ziffer und enthält 1–64 Kleinbuchstaben, Ziffern oder Bindestriche. Browser, Backend und Sandbox verwenden sie, ohne `name`, `composeProject`, `stateDirectory` oder gespeicherte Zugangsdaten zu ändern.

#### Containernamen wählen

Setze `runtime.containerPrefix`, wenn in der Containerliste Namen wie `north-desk-prod-db` und `north-desk-prod-backend-api` erscheinen sollen. Das Präfix beginnt mit einem Kleinbuchstaben und besteht aus Kleinbuchstaben, Ziffern und einzelnen Bindestrichen. Es darf höchstens 40 Zeichen lang sein. Leerzeichen, Unterstriche, doppelte Bindestriche und ein Bindestrich am Ende sind nicht erlaubt.

| Einstellung | Zugehörige Identität |
| --- | --- |
| `runtime.containerPrefix` | Sichtbare Containernamen: `<prefix>-<service>` für jeden verwalteten Dienst. |
| `name` und `composeProject` | Das bestehende Deployment und sein Compose-Projekt, einschließlich der Zuordnung der Volumes. |
| `stateDirectory` | Der vorhandene Deployment-Zustand, Zugangsdaten und Wiederherstellungsprotokolle. |

Lass die Werte der letzten beiden Zeilen unverändert, wenn du die Container einer bestehenden Installation umbenennst. Das Präfix verändert die DNS-Namen der Dienste nicht; interne Dienstadressen verwenden weiterhin ihre bisherigen Namen. Ohne Präfix gilt die Benennung aus dem Quellcode.

Wenn du ein Präfix hinzufügst, änderst oder entfernst, werden Container neu erstellt. Dabei kann der Dienst kurz unterbrochen werden. Bereite ein neues Bundle vor, prüfe den Probelauf und wende es über den üblichen Ablauf mit Snapshot und Wiederherstellung an. Wiederhole nach einer Unterbrechung genau dieses Bundle; ein ausstehender Rollout lehnt ein anderes Bundle ab. Sobald der Rollout abgeschlossen ist, kannst du das Präfix mit einem weiteren vorbereiteten Bundle entfernen und so zur Benennung aus dem Quellcode zurückkehren.

Betreibe nur eine vollständige verwaltete Laufzeit pro Docker-Daemon. Ein Namenspräfix vergibt keine separaten Ports, Sandbox-Netzwerke oder Arbeitsverzeichnisse auf dem Host.

#### Zusätzliche Ursprünge bedienen {#managed-additional-origins}

Deklariere `additionalOrigins`, wenn dieselbe Instanz auch unter weiteren HTTPS-Ursprüngen antworten soll, etwa unter einer Partnerdomain oder während eines Umzugs unter dem bisherigen Hostnamen. Jeder Eintrag ist ein reiner HTTPS-Ursprung auf dem Standardport oder eine Umgebungsreferenz, die bei der Vorbereitung zu einem solchen Ursprung aufgelöst wird. Die Liste enthält 1 bis 16 verschiedene Ursprünge; keiner davon darf `origin` wiederholen.

```json
{
  "origin": "https://desk.example.org",
  "additionalOrigins": [
    "https://desk.partner.example",
    { "env": "TALE_EXTRA_ORIGIN" }
  ]
}
```

Die CLI schreibt die Liste in die Laufzeitvariable `ADDITIONAL_SITE_URLS` und verwaltet sie selbst, deshalb kann ein Eintrag unter `environment` sie nicht setzen. Jeder Ursprung ist ein vollwertiger Einstieg mit eigenen Sitzungen, Dateilinks, Anmeldewegen und Connector-Callbacks. Mit `tlsMode: "letsencrypt"` bezieht der Proxy für jeden Ursprung ein Zertifikat; lokale Hostnamen und IP-Adressen werden abgelehnt. Mit `tlsMode: "external"` muss dein TLS-Proxy für jeden Ursprung den ursprünglichen `Host` weiterleiten und `X-Forwarded-Proto: https` von einer Adresse senden, der Tales Proxy vertraut. Ist dieser Adressbereich enger als die privaten Bereiche, setze `TRUSTED_PROXIES` über eine Referenz unter `environment`.

Die native Identität bleibt bei `origin`: Konto- und Organisationsbindungen, Client-Journale, der OIDC-Issuer, Passkeys und E-Mail-Links verwenden nur diesen Ursprung. Ein Eintrag darf `identity.migrateOriginFrom` entsprechen, damit der bisherige Hostname während einer Migration erreichbar bleibt.

Die Vorbereitung lehnt eine Laufzeitrevision ab, deren Proxy einem externen TLS-Terminator nicht vertrauen kann, und meldet `Runtime does not serve additional origins`. Wenn du die Liste hinzufügst, änderst oder entfernst, werden die Dienste neu erstellt, die sie lesen. Entfernst du die Deklaration, entfernt das nächste angewendete Bundle auch die Variable. Registriere die Callback-URLs jedes Ursprungs bei deinen Identitäts- und Connector-Anbietern und plane DNS und Zertifikate mit [TLS und Domains](https://docs.tale.dev/de/self-hosted/configuration/tls-and-domains#mehrere-domains-gleichzeitig).

#### Festlegen, wer Organisationen erstellen darf {#managed-organization-creators}

Ein verwaltetes Deployment lehnt das Erstellen von Organisationen an seinem Proxy für alle ab: Die Organisationsauswahl zeigt keinen Eintrag **Organisation erstellen**, und `POST /api/auth/organization/create` antwortet mit 403. Damit benannte Personen weitere Arbeitsbereiche eröffnen können, deklariere `organizations.creators` — 1 bis 64 verschiedene Anmeldeadressen, wörtlich oder als Umgebungsreferenzen, die die Vorbereitung auflöst.

```json
{
  "organizations": {
    "creators": ["ops@example.org", { "env": "TALE_WORKSPACE_LEAD" }]
  }
}
```

Die CLI schreibt die Liste in die Laufzeitvariable `TALE_ORGANIZATION_CREATORS` und verwaltet sie selbst, deshalb kann ein Eintrag unter `environment` sie nicht setzen. Mit der Deklaration lehnt der Proxy das Erstellen nicht mehr ab; stattdessen prüft das Backend jede anfragende Person gegen die Liste, antwortet allen anderen mit `403 ORGANIZATION_CREATION_FORBIDDEN`, und die App zeigt **Organisation erstellen** nur den benannten Personen. Adressen werden ohne Rücksicht auf Groß- und Kleinschreibung verglichen; zwei Schreibweisen derselben Adresse gelten als Duplikat und werden abgelehnt.

Die verwaltete Organisation selbst bleibt unberührt: Das Deployment erstellt sie beim Bootstrap, und die erste Organisation eines Deployments ist immer erlaubt. Entfernst du die Deklaration und wendest das nächste Bundle an, kehrt die Ablehnung am Proxy zurück und die Variable wird entfernt. Dieselbe Variable funktioniert auch auf einem Deployment, das du selbst betreibst; siehe die [Umgebungsvariablen-Referenz](https://docs.tale.dev/de/self-hosted/configuration/environment-reference).

#### Bundle vorbereiten, prüfen und anwenden

Setze `TALE_DEPLOY_SPEC` auf die JSON-Datei, `TALE_DEPLOY_BUNDLE` auf ein neues absolutes Ausgabeverzeichnis und `TALE_CLI_COMMIT` auf den vollständigen Commit des Binaries. `DEPLOYMENT_COMMIT` ist ein optionaler Herkunftsvermerk für die Orchestrierung; lass die zugehörigen Flags bei Nichtgebrauch weg. Bereite vor und prüfe, übertrage das vollständige Verzeichnis und führe Vorschau und Deployment auf dem Ziel mit derselben festgelegten CLI aus.

```bash
tale --json deploy prepare \
  --spec "$TALE_DEPLOY_SPEC" \
  --deployment-ref "$DEPLOYMENT_COMMIT" \
  --output "$TALE_DEPLOY_BUNDLE"

tale --json deploy verify-bundle \
  --bundle "$TALE_DEPLOY_BUNDLE" \
  --cli-ref "$TALE_CLI_COMMIT" \
  --deployment-ref "$DEPLOYMENT_COMMIT"

tale --json deploy --bundle "$TALE_DEPLOY_BUNDLE" \
  --cli-ref "$TALE_CLI_COMMIT" \
  --deployment-ref "$DEPLOYMENT_COMMIT" --dry-run

tale --json --yes deploy --bundle "$TALE_DEPLOY_BUNDLE" \
  --cli-ref "$TALE_CLI_COMMIT" \
  --deployment-ref "$DEPLOYMENT_COMMIT"
```

`deploy prepare` akzeptiert optional `--sources-file <file>` mit einer Zuordnung von `repository@fullSHA` zu vorhandenen exakten Checkouts. Sonst lädt die CLI kanonische GitHub-Repositories. Übergib den Inhalt eines nur lesenden SSH-Schlüssels für private Client-Repositories während der Vorbereitung über `TALE_SOURCE_SSH_KEY`. Die CLI prüft GitHubs SSH-Hostschlüssel über HTTPS und hält den Schlüssel aus Paket und Runtime heraus. Docker braucht bereits Zugriff auf die Registry.

Die Vorbereitung prüft zuerst jede Konfiguration mit den eigenen Schemas der CLI und lädt und prüft erst danach die Runtime-Images. Dabei nennt sie jede Phase und jedes Image. Ein Paket mit Feldern, die diese CLI nicht kennt, lehnt sie innerhalb von Sekunden mit `native manifest normalization changes release semantics at <fields>` ab. Bereite es dann mit einer CLI vor, die mindestens so neu ist wie das Tale, für das das Paket geschrieben wurde. Einen Fehler, den die CLI bewusst meldet, zeigt sie mit seiner Ursache. Jeder andere Fehler behält eine feste Zusammenfassung, damit weder Zugangsdaten noch Ausgaben der Registry ins Log gelangen.

`deploy verify-bundle` prüft vollständiges Inventar und Datei-Hashes ohne Zielkontakt. `deploy --bundle --dry-run` prüft Konfigurationsartefakte und Zielbedingungen, ohne Änderungen anzuwenden. Verwaltete Deployments akzeptieren keine Workspace-Optionen wie `--services`, `--host` oder `--override-all`. Sie rollen den Stack unter Erhalt seines Zustands mit Zustands- und Herkunftsprüfungen aus. Das oben beschriebene Blue-Green-Verhalten des Workspace ist ein eigener Ablauf.

#### Native Identität bereitstellen

`deploy provision [--bundle <directory>]` ist die lokale Backend-Phase des Bundle-Deployments. Sie liest höchstens 64 KiB privates JSON von stdin, weist das lokale Konto und die ausgewählte Organisation nach und meldet die Sitzung vor der Erfolgsmeldung ab. Die Felder umfassen `origin`, `email`, `password`, `slug`, `name`, `ssoEnabled`, optionale Entra-Zugangsdaten und `nativeClients`. Standardmäßig bleibt das bestehende Konto erforderlich. Explizites `identity.bootstrap: "fresh"` erlaubt die Anlage des ersten lokalen Kontos und der Organisation. Ein Bundle bindet diese Wahl und die vorbereiteten Konfigurationen vor nativen Änderungen. `deploy provision` verweigert Workspace-Flags und `--dry-run`; nutze lesende Bundle- und Konfigurationsprüfungen. Die optionalen Erwartungen `--cli-ref` und `--deployment-ref` erfordern `--bundle` und greifen vor der Anmeldung.

Für einen administrativ geprüften neuen Betreiber deklarierst du ausdrücklich `identity.emailVerification: "operator-attested"`. Damit bestätigst du als Betreiber den Besitz der E-Mail-Adresse des authentifizierten Kontos; eine Postfachzustellung ist damit nicht nachgewiesen. Das Backend verwendet ein kurzlebiges natives Prüftoken für genau dieses Konto und diese Adresse und erhält native Hooks. Es verschickt keine E-Mail, ändert keine Adresse und erstellt keine weitere Sitzung. Die Option ist nur mit `bootstrap: "fresh"` zulässig. Ohne sie bleibt die normale native E-Mail-Prüfung bestehen. Ändert sich der Prüfstatus eines zuvor freigegebenen Kontos, stoppt der Ablauf zur Prüfung.

Ersetze für ein neues Ziel `projectId` einer Konfiguration durch `project: { "key": "NORTH", "name": "Configuration" }`. Native Projektschlüssel haben 2–6 Großbuchstaben, Namen höchstens 80 Zeichen. `skillOwner: "operator"` überträgt eine geprüfte Quellkapsel und kompiliert sie im Backend für den authentifizierten nativen Benutzer; der Host prüft das Ergebnis unabhängig. Explizite bestehende IDs und bereits an Besitzer gebundene Releases behalten ihr Verhalten.

Jeder native Client wählt eine bestehende `clientId` oder explizites `managed: true`. Vor der nativen Anlage speichert die CLI eine private Absicht; danach liefert sie nur einen privaten Übergabepfad und SHA für die Zugangsdaten. Wiederholungen erhalten IDs, Sicherheitsrichtlinie und Secrets. Unklare Annahme ohne passendes natives Objekt stoppt. Bei bestehenden Clients lassen sich nur Anzeigename und HTTPS-Callback-URLs angleichen. Auf unterstützten 0.5-Backends verwenden nötige Anlagen oder Änderungen feste backendlokale Auth-Adapter, deren Verbindungen anschließend schließen. Es entstehen keine öffentliche Registrierungs- oder Update-Route, frei wählbaren Modulpfade oder Secret-Rotationen.

#### Den Hostnamen eines verwalteten Deployments ändern {#managed-origin-migration}

Verwende das bestehende verwaltete Deployment und sein privates Zustandsverzeichnis. Der Ablauf ändert die Origin-Bindungen des vorhandenen Kontos, der Organisation und der Clients. Er verschiebt keine Datenbank und legt keine Ersatzidentitäten an.

1. Setze `origin` in der Deployment-Spezifikation auf die neue HTTPS-Origin und `identity.migrateOriginFrom` auf die genaue bisherige HTTPS-Origin, etwa `https://old.example.org`. Beide müssen verschieden sein. Behalte `identity.bootstrap: "fresh"`, Konto, Organisation und die Schlüssel der verwalteten Clients bei.
2. Prüfe vor der Bundle-Vorbereitung den gespeicherten Zustand. Der Bootstrap muss abgeschlossen sein. Jede deklarierte E-Mail-Bestätigung und jeder verwaltete Client benötigen ihr passendes abgeschlossenes Journal. Fehlende, ausstehende oder fremde Identitäts- und Client-Journale blockieren die Migration.
3. Bereite das Bundle vor, prüfe es, kontrolliere die Vorschau und wende es mit dem oben beschriebenen Ablauf an. Die CLI authentifiziert das bestehende Konto und prüft die Client-Zugangsdaten, bevor sie die Origin-Bindungen aktualisiert. Bei einer Wiederholung akzeptiert sie abgeschlossene Journale an beiden deklarierten Origins und erhält IDs und Secrets.
4. Exportiere nach dem abgeschlossenen Deployment-Beleg die Client-Konfiguration für den neuen Issuer. Entferne `migrateOriginFrom` aus künftigen Deployment-Spezifikationen.

Ist native Konfiguration deklariert, braucht sie ebenfalls ihren gespeicherten Beleg. Die Migration erhält Organisations-ID und Slug und prüft jede Ressource mit dem üblichen Plan- und Rückleseablauf. Eine an der neuen Origin unterbrochene Konfigurationsänderung lässt sich nur mit genau ihrem ausstehenden Plan fortsetzen. Ein ausstehender Konfigurationsbeleg an der alten Origin blockiert die Migration.

Für den Rückweg nach einer abgeschlossenen Migration tauschst du beide Origins ausdrücklich und durchläufst denselben geprüften Ablauf. Plane DNS, Zertifikate, Callback-Registrierungen und Zugriffstests mit [TLS und Domains](https://docs.tale.dev/de/self-hosted/configuration/tls-and-domains). Die Änderung der Bundle-Origin erledigt diese externen Schritte nicht.

#### Die Anmeldeadresse des Deploy-Operators ändern {#managed-operator-address-migration}

Ein verwaltetes Deployment meldet sich bei jedem Lauf als sein `identity`-Operator an. Soll dieses Konto eine Maschinenadresse bekommen, damit sich Personen mit eigenen Konten anmelden, behältst du das Konto und änderst nur seine Anmeldeadresse. Seine Benutzer-ID und alles, was daran hängt – verwaltete Clients, Skills im Besitz des Operators, API-Schlüssel und aufbewahrte Journale –, bleibt erhalten.

1. Setze `identity.email` auf die neue Adresse und `identity.migrateEmailFrom` auf die genaue bisherige Adresse. Beide müssen verschieden sein. Behalte `identity.bootstrap: "fresh"` und das Passwort des Kontos bei. Der Bootstrap muss abgeschlossen sein, und eine deklarierte E-Mail-Bestätigung braucht ihr abgeschlossenes Journal.
2. Bereite das Bundle vor, prüfe es, sieh dir die Vorschau an und wende es an. Die CLI liest die aktuelle Adresse des aufbewahrten Kontos im Backend, meldet sich damit an und weist die aufbewahrte Benutzer-ID nach. Sie hält die Änderung im Journal fest, benennt das Konto über den nativen Adapter um, beendet alle Sitzungen des Kontos und meldet sich mit der neuen Adresse erneut an. Die Umbenennung ist an die bisherige Adresse gebunden, sodass eine gleichzeitige Änderung abgelehnt statt überschrieben wird. Eine deklarierte E-Mail-Bestätigung bestätigt danach die neue Adresse.
3. Ein erneuter Lauf nach einer Unterbrechung findet die Adresse bereits geändert vor und schließt die Journale ohne zweite Umbenennung ab. `migrateEmailFrom` danach deklariert zu lassen, schadet nicht; entferne es, sobald der Deployment-Beleg bereit ist.

Hält ein anderes Konto die neue Adresse, das aufbewahrte Konto keine der beiden Adressen oder das Operator-Konto eine Single-Sign-on-Verknüpfung, stoppt das Deployment vor jeder Änderung. Entferne eine solche Verknüpfung zuerst: Sie gehört der Person, die sich damit angemeldet hat, nicht einem Maschinenkonto.

#### Einen Break-Glass-Administrator deklarieren {#managed-break-glass}

`identity.breakGlass` hält einen Administrator für den Fall bereit, dass der Deploy-Operator nicht verfügbar ist, etwa `{ "email": "break-glass@example.org", "passwordHash": { "env": "TALE_BREAK_GLASS_PASSWORD_HASH" } }`. Die Adresse ist ein fester Wert oder eine verpflichtende Umgebungsreferenz und muss sich von der aktuellen und der bisherigen Adresse des Operators unterscheiden. Das Passwort erreicht das Deployment nie: Erzeuge seinen Hash mit `tale auth hash-password` dort, wo das Passwort aufbewahrt wird, und übergib nur den Hash.

Jedes Deployment gleicht das Backend an die Deklaration an. Ein fehlendes Konto wird mit bestätigter Adresse und genau den deklarierten Zugangsdaten angelegt, und ein aufbewahrtes Journal bindet die Adresse an seine Konto-ID, sobald das Konto existiert. Spätere Deployments setzen das gebundene Konto auf die deklarierten Zugangsdaten zurück und beenden alle seine Sitzungen, sobald sich die Zugangsdaten ändern, auch wenn sie einen unterbrochenen Lauf abschließen. Ein Konto mit dieser Adresse, das nicht von diesem Deployment angelegt wurde, oder später ein anderes Konto mit dieser Adresse stoppt das Deployment. Das Konto wird über die nativen Mitglieder-Endpunkte `admin` der verwalteten Organisation; ein `owner` wird nie verändert. Das Deployment meldet sich nie mit diesem Konto an. Ändere sein Passwort über den deklarierten Hash, nicht in der Anwendung. Das Deployment hält keinen Zeitpunkt der Passwortänderung fest; eine Richtlinie zur Passwortrotation der Organisation kann dieses Konto daher nach einem neuen Passwort fragen, das das nächste Deployment wieder zurücksetzt.

#### Erzwungene Zwei-Faktor-Anmeldung

Ein verwaltetes Deployment meldet sich allein mit dem Passwort als sein Operator an. Erzwingt die Organisation `two_factor_policy`, gib dem Operator einen Passkey und nie eine Authenticator-App: Die Passwort-Anmeldung eines Kontos mit Authenticator-App wird mit einer Code-Abfrage beantwortet, und ein Konto ohne beide Faktoren wird nach Ablauf seiner Übergangsfrist zur Einrichtung geschickt. Die CLI stoppt bei beiden Antworten und nennt die erhaltene. Personen melden sich mit eigenen Konten an und können beide Faktoren nutzen.

#### Zugangsdaten nativer Clients exportieren

Um Zugangsdaten eines verwalteten Clients an eine separate Anwendung zu übergeben, setze `NATIVE_CLIENT_KEY` auf den deklarierten Schlüssel und `PRIVATE_EXPORT_DIRECTORY` auf einen neuen privaten Ausgabeordner. Dessen übergeordneter Ordner muss bereits deinem Konto gehören, Modus `0700` haben und unter vertrauenswürdigen Verzeichnissen liegen. Exportiere aus demselben freigegebenen Deployment, ohne Backend-Pfade oder Containernamen auszuwerten:

```bash
tale --json deploy export-client --bundle "$TALE_DEPLOY_BUNDLE" \
  --client "$NATIVE_CLIENT_KEY" --output "$PRIVATE_EXPORT_DIRECTORY" \
  --env-prefix TALE_OIDC --cli-ref "$TALE_CLI_COMMIT" \
  --deployment-ref "$DEPLOYMENT_COMMIT"
```

Der Ausgabeordner hat Modus `0700`. Seine regulären Dateien `client.json`, `receipt.json` und optional `consumer-env.json` haben Modus `0600`. Mit `--env-prefix` entsteht die letzte Datei als wörtliche Zuordnung der vier Zeichenketten `TALE_OIDC_ISSUER`, `TALE_OIDC_CLIENT_ID`, `TALE_OIDC_CLIENT_SECRET` und `TALE_OIDC_ORG_SLUG`. Der Issuer besteht aus der Tale-Origin und `/api/auth`. Übertrage die Bytes über deinen privaten Zugangsdatenkanal und lass die Anwendung JSON lesen; führe die Datei nicht als Shell aus und veröffentliche sie nicht als CI-Artefakt. Stdout enthält nur unkritische Metadaten, Pfade, Größen und Hashes. Eine identische Ausgabe wird erst nach erneuter Zustands- und vollständiger Artefaktprüfung wiederverwendet. Unvollständige, veraltete oder fremde Ausgaben stoppen ohne Überschreiben.

### Plattform konfigurieren

Mit `tale config` verwaltest du bestehende Plattform-Einstellungen über die nativen APIs. Speichere diese Deklaration als `configuration.json`, um Akzentfarbe und ein Inaktivitätslimit von 45 Minuten festzulegen:

```json
{
  "schemaVersion": 1,
  "resources": [
    {
      "kind": "branding",
      "config": {
        "accentColor": "#336699"
      }
    },
    {
      "kind": "governance",
      "key": "session_idle_timeout",
      "config": {
        "enabled": true,
        "idleTimeoutMinutes": 45
      }
    }
  ]
}
```

Setze `TALE_URL` auf die HTTPS-Origin der Instanz und `TALE_ORG_ID` auf die native Organisations-ID. Übergib ein berechtigtes Sitzungscookie über `TALE_CONFIG_COOKIE`; es gehört weder in Argumente noch in versionierte Dateien. Prüfe die Deklaration lokal, speichere und prüfe den Plan, wende ihn an und vergleiche den nativen Zustand:

```bash
tale --json config validate --file configuration.json
tale --json config plan --file configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID" --output configuration-plan.json
tale --json --yes config apply --file configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID" \
  --plan configuration-plan.json --receipt configuration-receipt.json
tale --json config read --file configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID"
```

Die Ausgabe- und Belegordner müssen bereits existieren. Eine HTTP-Verbindung über Loopback braucht zusätzlich `--origin` mit der öffentlichen HTTPS-Origin. `read` meldet für jede deklarierte Ressource `matches`. Der Plan zeigt Organisations- oder Instanzumfang, aktuelle und gewünschte Hashes sowie native Folgewirkungen. Zum Anwenden müssen Deklaration und Ziel exakt stimmen. Eine konkurrierende native Änderung stoppt den Schreibvorgang. Nicht deklarierte Ressourcen bleiben bestehen. Die CLI bietet weder Löschbefehle noch beliebige Dateizugriffe.

Diese Ressourcenarten nutzen die gemeinsamen Plattform-Schemas und nativen Berechtigungen:

| Art                   | Konfiguration                                             | Geltungsbereich |
| --------------------- | --------------------------------------------------------- | --------------- |
| `branding`            | Native Branding-Felder                                    | Organisation    |
| `governance`          | Dateibasierte Richtlinie mit `key` und nativer `config`   | Organisation    |
| `provider`            | Eigene Anbieterdefinition und optionale `expectedModels`  | Organisation    |
| `provider-credential` | Metadaten benannter Umgebungszugangsdaten                 | Organisation    |
| `knowledge-embedding` | Anbieter, Modell, Dimensionen, Endpunkt und Servergrenzen | Organisation    |
| `deployment`          | Instanz-Einstellungen einschließlich Sandbox-Runtime      | Instanz         |

Aufbewahrungs- und DSAR-Richtlinien brauchen ihre eigenen nativen Workflows. Pausiere Uploads, Synchronisation und Crawls, bevor du das Embedding-Modell wechselst. Die CLI prüft die Anzahl der Dokumente und Websites der gesamten Organisation; sie sperrt den Import nicht und migriert keine bestehenden Vektoren. Hat die Organisation Dokumente oder registrierte Websites, braucht ein Modellwechsel eine separate native Indexmigration. Eine Änderung, die nur `minSimilarity`, `maxConcurrentRequests`, `minTokensPerSecond`, `maxTokensPerMinute` oder `maxRequestsPerMinute` betrifft, lässt die vorhandenen Vektoren gültig; für sie entfällt diese Prüfung. Instanz-Einstellungen erfordern zusätzlich die native Freigabeliste für Deployment-Editoren. Bei Boot-Einstellungen meldet der einzelne Konfigurationsaufruf `restartRequired`; Speichern allein aktiviert diese Einstellungen noch nicht. Prüfe die Folgen im Plan vor dem Anwenden.

Verwaltete Deployments nutzen denselben Ablauf über `configuration`. Ergänze die Deployment-Deklaration um dieses Beispiel, wenn ein externer Betreiber den Anbieter bereits bereitstellt. Ersetze den synthetischen Endpunkt und Katalog durch geprüfte Werte und übergib `EXTERNAL_PROVIDER_SECRET` aus deinem Secret Manager:

```json
{
  "environment": {
    "TALE_PROVIDER_KEY_EXTERNAL": {
      "env": "EXTERNAL_PROVIDER_SECRET"
    }
  },
  "configuration": {
    "schemaVersion": 1,
    "resources": [
      {
        "kind": "provider",
        "config": {
          "name": "external-chat",
          "displayName": "External chat",
          "apiFormat": "openai",
          "baseUrl": "https://models.example.invalid/v1",
          "catalog": {
            "source": "models-endpoint"
          },
          "embedding": "unknown",
          "auth": [
            {
              "method": "env"
            }
          ]
        },
        "expectedModels": [
          {
            "id": "Example-chat",
            "provider": "external-chat",
            "tags": ["chat"],
            "supportsTools": true,
            "supportsVision": false,
            "contextWindow": 131072
          }
        ]
      },
      {
        "kind": "provider-credential",
        "config": {
          "providerSlug": "external-chat",
          "authMethod": "env",
          "name": "Managed external provider",
          "envName": "TALE_PROVIDER_KEY_EXTERNAL",
          "modelAllowlist": ["Example-chat"]
        }
      }
    ]
  }
}
```

Für `envName` gelten das native Präfix `TALE_PROVIDER_KEY_` und die Grenze von 40 Zeichen. Jeder Alias braucht eine verpflichtende `environment`-Referenz. Private Endpunkte erfordern zusätzlich eine explizite Referenz `TALE_ALLOW_PRIVATE_PROVIDER_HOSTS` mit dem Wert `1`; native Host-Regeln gelten weiter. `expectedModels` prüft Tales frisch aufgelösten Katalog beim Rücklesen. Das belegt weder Inferenzkapazität und Latenz noch fachliche Ergebnisse.

Die Bildmodellauswahl nutzt `governance` mit `key: "vision_model"` und den nativen Feldern `providerSlug`/`modelId`. Embedding nutzt `knowledge-embedding` mit `providerSlug`, `model`, `dimensions` und `baseUrl`, dazu die optionalen Einstellungen, die die Plattform neben dem Modell in [`embedding.json`](https://docs.tale.dev/de/self-hosted/configuration/data-residency#das-embedding-modell-der-organisation) hält: `minSimilarity`, die Kosinus-Untergrenze des Assistenten für dieses Modell, sowie die Servergrenzen `maxConcurrentRequests`, `minTokensPerSecond`, `maxTokensPerMinute` und `maxRequestsPerMinute` ([Anfragen an einen selbst betriebenen Embedding-Server dosieren](https://docs.tale.dev/de/self-hosted/configuration/data-residency#kapazitaet-des-embedding-servers)). Für jede gilt die Regel der Plattform selbst: Ein Wert setzt sie, ein weggelassener Schlüssel lässt stehen, was die Datei hält (ein von Hand gesetzter Wert überlebt ein Release, das ihn nicht erwähnt), und `null` löscht sie — `"minSimilarity": null` etwa ist der einzige Weg, eine Untergrenze über die CLI zu entfernen. Wenn du Standardzugangsdaten ersetzt, deklariere auch die bisherigen Umgebungszugangsdaten mit `isDefault: false`; die CLI wendet diese explizite Änderung zuerst an. Schlüsselwerte stehen weder in der Deklaration noch im Beleg.

Die native Einrichtung folgt auf die Identitätsprüfung und läuft vor den Konfigurations-Releases. Der Beleg `native.configuration` bindet Deklarations- und Bundle-Hashes, Organisation, Ressourcen-Hashes und native Revisionen. Vor der ersten Änderung entsteht ein ausstehender Beleg. Scheitert eine spätere Ressource, können frühere Änderungen bestehen bleiben. Lies den nativen Zustand und den Beleg, bevor du denselben geprüften Plan erneut ausführst. Natives Compare-and-set schützt jede Ressource vor konkurrierenden Admin-Änderungen; eine ressourcenübergreifende Transaktion gibt es nicht. Bewahre Deployment-Zustand, Snapshots und Belege für die Wiederherstellung auf.

Verwaltete Deployments aktivieren auch eine deklarierte `deployment`-Ressource, bevor sie Bereitschaft melden. Die CLI speichert die ausstehende Aktivierung, wartet bis zu fünf Minuten auf das Ende laufender Sitzungen im geprüften Sandbox-Spawner und startet dann diesen Container neu. Laufen noch Sitzungen, bleibt der Vorgang ausstehend. Der Beleg `configurationActivation` erfasst die eingebundene Konfiguration und den beobachteten Container-Start; Bereitschaft setzt erneute Gesundheitsprüfungen voraus. Bei einer Wiederholung prüft die CLI einen bereits angenommenen Neustart. Eine unveränderte Wiederholung nach erfolgreicher Aktivierung startet den Dienst nicht erneut.

#### Einen ausstehenden Konfigurationsplan ersetzen

Kann ein unterbrochener Plan noch abgeschlossen werden, führe denselben Plan erneut aus. Ein ausdrücklicher Ersatz ist nötig, wenn die deklarierten Einstellungen nicht mehr funktionieren können, etwa weil ein Embedding-Endpunkt nicht mehr verfügbar ist. Bewahre den vorhandenen Beleg auf: Er hält fest, welche Änderungen die Plattform bereits erreicht haben können.

1. Lies den ausstehenden Beleg und vergleiche die deklarierten Ressourcen mit dem aktuellen Zustand der Plattform. Speichere die korrigierten Einstellungen in `replacement-configuration.json`. Ziel und Ressourcenkennungen müssen exakt gleich bleiben; Ressourcen lassen sich dabei weder hinzufügen noch weglassen.
2. Berechne den Hash von `plan` im aufbewahrten Beleg, nicht vom gesamten Beleg oder vom Ersatzplan. Der folgende Befehl benötigt Bun. Er verwendet kanonisches JSON: rekursiv sortierte Objektschlüssel, unveränderte Array-Reihenfolge und keine Leerzeichen.

```bash
PENDING_PLAN_SHA=$(bun -e '
  const receipt = await Bun.file(process.argv[1]).json();
  if (receipt.phase !== "pending") throw new Error("Receipt is not pending");
  function canonical(value) {
    if (Array.isArray(value)) return "[" + value.map(canonical).join(",") + "]";
    if (value !== null && typeof value === "object") {
      return "{" + Object.keys(value).sort().map(key =>
        JSON.stringify(key) + ":" + canonical(value[key])
      ).join(",") + "}";
    }
    return JSON.stringify(value);
  }
  console.log(new Bun.CryptoHasher("sha256")
    .update(canonical(receipt.plan)).digest("hex"));
' configuration-receipt.json)
```

3. Erstelle aus der Ersatzdeklaration einen neuen Plan und prüfe ihn vor dem Anwenden:

```bash
tale --json config plan --file replacement-configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID" --output replacement-plan.json
```

Wende den geprüften Plan mit dem bisherigen Belegpfad und dem Hash des aufbewahrten Plans an:

```bash
tale --json --yes config apply --file replacement-configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID" \
  --plan replacement-plan.json --receipt configuration-receipt.json \
  --supersedes-pending-plan "$PENDING_PLAN_SHA"
tale --json config read --file replacement-configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID"
```

Jede Ressource muss weiterhin dem ursprünglichen Zustand, der beabsichtigten Änderung oder dem verifizierten Ergebnis des ausstehenden Plans entsprechen. Eine unabhängige Änderung auf der Plattform blockiert den Ersatz vor dem ersten Schreibzugriff. Kläre die Abweichung mit dem zuständigen Administrator; entferne den Beleg nicht, um die Prüfung zu umgehen.

Unter `superseded` bewahrt der Beleg den früheren Plan samt verifizierten Ressourcen auf, auch bei Unterbrechung und Wiederholung. Prüfe, ob der Beleg `phase: "ready"` erreicht und `config read` übereinstimmende Ressourcen meldet. Lass den einmaligen Auswahlparameter bei späteren Vorgängen weg.

Bei einem verwalteten Deployment setzt du `supersedesPendingConfigurationPlan` in der Deployment-Spezifikation auf denselben Hash des aufbewahrten Plans und korrigierst `configuration`. Bereite anschließend ein neues Bundle vor und prüfe es. Ersetzt dieses Bundle auch einen ausstehenden Rollout, gib dessen Hash zusätzlich über `supersedesPendingBundle` an. Dieser Bundle-Parameter allein erlaubt keinen Ersatz des nativen Konfigurationsplans. Entferne beide Wiederherstellungsparameter aus späteren Spezifikationen, sobald der Vorgang bereit ist.

Der öffentliche Nachweis `native.configuration` enthält pro Ressource den beabsichtigten Hash als `configurationSha256` und den Hash des zurückgelesenen Zustands als `observedConfigurationSha256`. Beide können voneinander abweichen, wenn eine Einstellung einen vorhandenen Wert erhält, etwa bei einer ausgelassenen Ähnlichkeitsschwelle oder Servergrenze für Embeddings. Der private Beleg bewahrt den exakt beobachteten Zustand für die Wiederherstellung auf.

### Betrieb

`tale status` — den aktuellen Deployment-Status anzeigen. Keine Argumente.

`tale logs <service>` — Logs eines Dienstes streamen (`service` ist einer der laufenden Dienste; auf einem reinen Dev-Stack ohne Deployment fällt der Befehl auf den Dev-Container zurück).

- `-f, --follow` — der Log-Ausgabe folgen, während sie geschrieben wird.
- `-n, --tail <lines>` — nur die letzten N Zeilen anzeigen.
- `--since <duration>` — Logs seit einer relativen Zeit anzeigen (z. B. `1h`, `30m`).
- `-c, --color <color>` — eine bestimmte Deployment-Farbe ansprechen (`blue` oder `green`).
- `--raw` — die rohe, ungefilterte Log-Ausgabe streamen (keine Klassifizierung).

`tale backup` — unterstützte, vorhandene Projekt-Volumes sichern. Keine Argumente. Externe Datenbanken und Buckets brauchen eigene Backups; siehe [Sicherungsumfang](https://docs.tale.dev/de/self-hosted/operate/backups-and-restore).

`tale restore [snapshot-id]` — einen Snapshot wiederherstellen; ohne ID werden die verfügbaren Snapshots aufgelistet.

- `--stop` — laufende Projekt-Container vor dem Wiederherstellen stoppen.
- `-y, --yes` — die Bestätigungsabfrage überspringen.

`tale rollback` — auf die vorherige Patch-Version zurückrollen (nur Patch-Ebene). Fragt vorher nach Bestätigung.

- `-y, --yes` — die Bestätigungsabfrage überspringen (im nicht-interaktiven Betrieb erforderlich).

### Wartung

`tale update` — eine Workspace-Instanz auf eine neue Version bringen: CLI-Binary aktualisieren und Projektdateien synchronisieren, danach `tale deploy` ausführen. Workspace-Befehle gleichen sich an diese Version an. Verwaltete Bundles und Konfigurations-Releases behalten ihre separat festgelegte CLI-Revision.

- `-v, --version <version>` — auf genau diese Version aktualisieren (z. B. `0.9.0`) statt der neuesten; erlaubt Downgrades.
- `-f, --force` — Re-Sync erzwingen und lokal geänderte Projektdateien überschreiben.
- `--dry-run` — anzeigen, was sich ändern würde, ohne etwas zu ändern.

`tale migrate` — die mitgelieferten Defaults für jede Organisation auf dem laufenden Deployment neu provisionieren — derselbe idempotente Schritt, den jeder Deploy ausführt, nur auf Zuruf. Schema-Migrationen sind kein Command: Das Backend wendet sie beim Start an, ein deployter Container ist also immer auf seinem eigenen Schema.

- `--dry-run` — zeigen, was laufen würde, ohne es auszuführen.

`tale cleanup` — inaktive (nicht-aktuelle) Container entfernen. Keine Argumente.

`tale reset` — alle Blue-Green-Container entfernen.

- `-f, --force` — die Bestätigungsabfrage überspringen.
- `-a, --all` — auch die zustandsbehafteten Infrastruktur-Container entfernen.
- `--dry-run` — den Reset vorab anzeigen, ohne Änderungen.

`tale uninstall` — das `tale`-CLI-Binary von diesem System entfernen. Fragt nach, bevor etwas gelöscht wird, und _bietet an_, zusätzlich das [Sandbox-Gerät](https://docs.tale.dev/de/self-hosted/install/cli-install#sandbox-device) dieses Rechners zu trennen, das vom eingestellten `tale daemon` hinterlassene `~/.tale-daemon` zu entfernen und die Docker-Ressourcen und Dateien eines Projekts abzubauen. Ohne `--purge` bleiben ein Projekt und seine Container unangetastet — führ darin `tale reset --all` aus, um sie zu entfernen. Lässt sich das Sandbox-Gerät nicht stoppen, wird nichts deinstalliert.

- `-f, --force` — die Bestätigungsabfrage überspringen (entfernt nur das Binary; die optionalen Aufräumschritte brauchen weiterhin `--purge`).
- `--purge` — zusätzlich das Sandbox-Gerät trennen und seine Arbeitsbereiche löschen, `~/.tale-daemon` entfernen und, für ein vom aktuellen Verzeichnis aus gefundenes Projekt, dessen Docker-Ressourcen abbauen und seine Dateien löschen. Nicht umkehrbar.
- `--dry-run` — anzeigen, was entfernt würde, ohne etwas zu entfernen.

`tale config show` — das aufgelöste lokale Projektverzeichnis und die CLI-Version ausgeben. Außerhalb eines Projekts meldet der Befehl, dass er keines gefunden hat, und endet ohne Fehler.

### Konfigurations-Releases

Diese Befehle nutzen die gewählte CLI-Revision ohne Instanzangleichung oder Docker-Operationen. [Client-Konfigurationen veröffentlichen](https://docs.tale.dev/de/self-hosted/configuration/config-releases) beschreibt Deskriptoren, Quell-Commits, Zugangsdaten und Wiederherstellung. Standardmäßig kennzeichnet der vollständige Quell-SHA das Release: Manifest-Schema 4/Compiler 3 mit `releaseRef === sourceCommit`. Native ganzzahlige Automatisierungsversionen bleiben davon getrennt.

`build`, `verify` und `stage` verlangen `--repo <directory>`, `--descriptor <path>` und `--automation <name>`. Der Deskriptorpfad ist repositoryrelativ. Ein Prüfmanifest darf absolut oder repositoryrelativ angegeben werden.

| Befehl               | Pflichtoptionen                              | Optionale Angaben                                                                                                            |
| -------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `tale config build`  | `--source-commit <sha>`                      | `--skill-owner <user-id>` (bei eigenen Skills erforderlich), `--output <directory>`, kompatibel `--config-version <version>` |
| `tale config verify` | `--manifest <path>`                          | `--rebuild` für exakte Offline-Rekonstruktion                                                                                |
| `tale config stage`  | `--config-ref <sha>`, `--output <directory>` | `--skill-owner <user-id>`, `--client <name>`, `--deployment-ref <sha>`                                                       |

Die Quellvorbereitung verlangt Checkout-`HEAD` auf diesem vollständigen Commit und ein Ausgabeziel außerhalb des Checkouts. Sie baut committete Inhalte ohne zusätzlichen Katalog-Commit. Explizites `stage --config-version` wählt stattdessen den kompatiblen Katalogweg und verlangt `--catalogue-commit`, `--catalogue-repository`, `--client` und `--ops-commit`. Kombiniere `--config-ref` und `--config-version` nicht.

Native Befehle verlangen `--stage <directory>`, `--url <origin>`, `--org <id>` und `--project <id>`. Außer lokalem HTTP ist HTTPS Pflicht. Nutze `--origin <origin>` für die kanonische Browser-Origin hinter einem Proxy. Beide lesen `TALE_CONFIG_COOKIE` ausschließlich aus der Umgebung.

| Befehl                      | Pflichtoptionen                | Optionale Angaben                                                   |
| --------------------------- | ------------------------------ | ------------------------------------------------------------------- |
| `tale config deploy`        | `--receipt <path>`             | Globales `--yes` für ein autorisiertes unbeaufsichtigtes Deployment |
| `tale config verify-native` | Keine weiteren Pflichtoptionen | `--native-version <number>`, `--allow-retained`                     |

Beide nativen Befehle nehmen exakte Erwartungen über `--config-ref`, `--source-repository`, `--artifact-sha256`, `--deployment-ref`, `--client` und `--automation` entgegen. Historische Katalog-Flags bleiben kompatibel. `verify-native` liest nur; `--allow-retained` prüft eine explizit gewählte aufbewahrte Version, ohne sie als bereitgestellt auszuweisen. Ohne `--native-version` wählt die Prüfung die zuletzt gespeicherte Version. Die native API zeigt den Aufgabenvertrag nur für die bereitgestellte Version; eine Prüfung aufbewahrter Versionen kann dieses Feld nicht bestätigen.

Konfigurationsbefehle haben kein `--dry-run`: Nutze `stage`, `verify --rebuild` und `verify-native`. Erfolgs-JSON hat die Form `{ok:true,command:"config <verb>",data}`. Build- und Prüfdaten enthalten `automationName`, `releaseRef`, `sourceCommit`, `artifactSha256`, `artifactPath` und `verified`; kompatible Ausgaben verwenden `configVersion` statt `releaseRef`. SHA-Transferbelege und native Belege nutzen Schema 2. Ein Deployment-Ergebnis enthält `automationVersion` und `unchanged`; das explizite Feld `verified` gehört zur Prüfausgabe.

### Sandbox-Gerät {#sandbox-device}

Diese Befehle führen die Sandboxes deiner Tale-Organisation auf dem Rechner aus, auf dem du sie aufrufst. [Sandboxes auf eigenen Geräten ausführen](https://docs.tale.dev/de/platform/admin/sandbox-devices) beschreibt, wie du ein Gerät unter **Einstellungen > Sandboxes** hinzufügst und dort den Befehl `connect` erhältst. Das Gerät speichert seine Konfiguration und Arbeitsbereiche in `~/.tale/sandbox`; `TALE_SANDBOX_HOME` verlegt sie.

`tale sandbox connect <site> --token <token>` — diesen Rechner mit der Organisation verbinden, die das Token ausgestellt hat: prüft Docker (und bietet an, es zu installieren), registriert den Rechner und startet die Container des Geräts mit dem Release des Servers. `site` ist deine Tale-Website, etwa `https://your-org.tale.dev`. Das Token (`tsdj_…`) funktioniert einmal, innerhalb einer Stunde. Nur Linux und macOS.

- `--name <name>` — der Name, den Tale für das Gerät anzeigt (Standard: der Hostname des Rechners). Andere Zeichen als `A`–`Z`, `a`–`z`, Ziffern, `.`, `-` und `_` werden zu Bindestrichen.
- `--max-sessions <n>` — wie viele Sandboxes hier gleichzeitig laufen, von 1 bis 256 (Standard: eine pro zwei CPUs und pro 4 GiB Arbeitsspeicher, die Docker nutzen kann, höchstens 16).
- `--no-auto-update` — dem Release des Servers nicht automatisch folgen; führ stattdessen nach jedem Tale-Update `tale sandbox update` aus.
- `--docker-socket <path>` — der Docker-Socket, den die Container des Geräts verwenden, für Rootless Docker (Standard: `/var/run/docker.sock`).

`tale sandbox status` — Verbindung, Organisation, Release und Container des Geräts anzeigen, dazu die gerade laufenden Sandboxes. Keine Argumente.

`tale sandbox update` — das Gerät sofort auf das Release des Servers bringen und die aktuellen Adressen des Servers für seine Sandboxes übernehmen (nötig, nachdem sich die Adresse des Backends oder des Modell-Gateways geändert hat). Keine Argumente.

`tale sandbox logs` — das Log des Geräts anzeigen.

- `-f, --follow` — neue Zeilen fortlaufend ausgeben.
- `--tail <lines>` — wie viele Zeilen zuerst angezeigt werden (Standard: `200`).

`tale sandbox disconnect` — das Gerät aus seiner Organisation entfernen, seine Sandboxes stoppen und ihre Arbeitsbereiche von diesem Rechner löschen. Fragt vorher nach und ändert nichts, solange Docker nicht läuft. Ist der Server nicht erreichbar, wird der Rechner trotzdem aufgeräumt, und ein Admin entfernt das Gerät unter **Einstellungen > Sandboxes**.

- `--keep-data` — die Arbeitsbereiche auf diesem Rechner behalten.
- `-f, --force` — die Bestätigungsabfrage überspringen.

### Erweitert

`tale auth hash-password` — den Better-Auth-Hash eines Passworts ausgeben, für einen [Break-Glass-Administrator](https://docs.tale.dev/de/self-hosted/install/cli-install#managed-break-glass).

Der Befehl liest das Passwort von stdin oder im interaktiven Terminal aus einer verdeckten Eingabe mit Bestätigung. Er lehnt ein Passwort ab, das die Standard-Passwortrichtlinie der Plattform verletzt, und gibt nur den Hash aus.

`tale auth reset-owner` — die Zugangsdaten des Owner-Kontos zurücksetzen.

Führe den Befehl bei einer manuellen Wiederherstellung ohne Flags im interaktiven Terminal aus. So gibst du das Passwort verdeckt ein, ohne es in Shell-Verlauf oder Argumenten abzulegen. Die Rücksetzung macht bestehende Sitzungen ungültig.

- `-e, --email <email>` — eine neue Owner-E-Mail-Adresse setzen.
- `-p, --password <password>` — ein neues Owner-Passwort setzen.

## Fehlersuche

- **`tale deploy` trifft die falsche Maschine.** Die CLI nutzt den Docker-Kontext / `DOCKER_HOST` deiner Shell. Wechsle mit `docker context use …` (oder setz `DOCKER_HOST`), sodass er auf den gewünschten Host zeigt, und lauf erneut.
- **`tale deploy` nutzt den falschen Host-Alias.** Der Host, auf dem der Proxy antwortet, kommt aus `HOST` im `.env` des Projekts, nicht aus einem separaten CLI-Speicher. Bearbeite `.env` oder übergib `--host`, um ihn für einen Lauf zu überschreiben.
- **Installer scheitert auf macOS, weil das Binary nicht ausführbar ist.** Verweigert das frisch installierte Binary den Start (z. B. weil Gatekeeper es beendet), bricht der Installer mit Hinweisen zur Behebung ab, statt Erfolg zu melden — folg ihnen und lauf den Installer erneut.
- **`tale` nach der Installation auf Linux nicht gefunden.** Der Installer legt das Binary in `/usr/local/bin` ab; verifizier, dass das Verzeichnis im `PATH` des Users ist (`echo $PATH`).

Für den laufenden Betrieb helfen [Upgrades](https://docs.tale.dev/de/self-hosted/operate/upgrades), [Backups und Wiederherstellung](https://docs.tale.dev/de/self-hosted/operate/backups-and-restore) und [Container-Architektur](https://docs.tale.dev/de/self-hosted/operate/container-architecture).

# Das erste Inhaberkonto erstellen
Source: https://docs.tale.dev/de/self-hosted/install/first-admin

Auf einer leeren Instanz erstellt die Tale-Einrichtung das erste Konto und die erste Organisation. Dieses Konto erhält die Rolle Inhaber. Schließe die Einrichtung ab, solange du den Zugriff auf die neue Instanz kontrollierst und bevor du ihre Adresse weitergibst.

## Bereitschaft der Instanz prüfen

Öffne die von `tale dev` angezeigte Adresse oder bei einer Bereitstellung die konfigurierte `SITE_URL`. Prüfe Zertifikat und Hostname. Bei einer CLI-Bereitstellung verwende `tale status`; bei einer eigenen Bereitstellung prüfe Dienste und Gesundheitsprüfungen. Ein fehlerhaftes Backend braucht [Fehlerbehebung](https://docs.tale.dev/de/self-hosted/operate/observability/troubleshooting), bevor du Konten einrichtest.

Eine Anmeldeseite statt der Einrichtung bedeutet meist, dass bereits ein Konto existiert. In einer vorbereiteten Entwicklungsumgebung ist das normal. Lösche nicht die Datenbank, um Zugriff zurückzubekommen. Melde dich mit dem vorhandenen Konto an oder bitte einen Admin, dein Konto hinzuzufügen.

## Einrichtung abschließen

Öffne die Instanz-URL. Folge der Einrichtung, erstelle dein Konto und benenne die Organisation. Bewahre deine Anmeldedaten in einem Passwortmanager auf.

Öffne nach dem Erstellen von Konto und Organisation den Anbieterlink auf der Abschlussseite oder **Einstellungen > KI-Anbieter**. Ohne Anbieter kannst du die App ansehen; für eine echte Antwort brauchst du gültige Zugangsdaten und ein verfügbares Modell. [KI-Anbieter](https://docs.tale.dev/de/platform/admin/providers) beschreibt die Verbindung.

## Inhaberrolle bestätigen

Öffne **Einstellungen > Mitglieder** und prüfe, ob dein Konto die Rolle **Inhaber** hat. Organisation und Konto sollten zu der Instanz passen, die du einrichten wolltest.

<Frame caption="Prüfe Inhaber und Rollen der Mitglieder, bevor du dem Team Zugriff gibst.">

![Die Mitgliederseite der Organisation zeigt Personen und ihre zugewiesenen Rollen.](https://docs.tale.dev/images/get-started/settings-organization-members.webp)

</Frame>

Melde dich ab und erneut an, um die Zugangsdaten unabhängig von der Einrichtungssitzung zu testen. Halte einen weiteren geprüften administrativen Wiederherstellungsweg bereit, bevor du die Authentifizierung änderst.

## Teammitglieder hinzufügen {#teammitglieder-einladen}

Füge Personen unter **Einstellungen > Mitglieder** hinzu und wähle ihre Rollen bewusst. Für ein neues Konto legt das Formular ein Anfangspasswort fest; bestehende Konten behalten ihre Zugangsdaten. Dieser Ablauf versendet keine Einladungs-E-Mail. Übermittle neue Zugangsdaten über einen sicheren Kanal. Nach dem ersten Konto ist die öffentliche Selbstregistrierung geschlossen. Für Unternehmens-SSO und Bereitstellung gelten eigene [Einrichtungs- und Mitgliedschaftsregeln](https://docs.tale.dev/de/platform/admin/enterprise-sso).

Das setzt das Backend selbst durch, nicht nur der Proxy davor: Sobald ein Konto existiert, antwortet `/api/auth/sign-up/email` mit 403. Das zählt, weil das Backend auch aus dem Sandbox-Netz der Agenten erreichbar ist, das der Proxy nie sieht — Code in einer Agenten-Sitzung kann also ebenfalls keine Konten anlegen. **Einstellungen > Mitglieder** legt Konten serverseitig an und bleibt davon unberührt. Eine Wegwerf-Testumgebung, die die offene Route braucht, setzt `TALE_ALLOW_OPEN_SIGN_UP=true`; auf einer echten Umgebung niemals.

Eine weitere Organisation darf jede angemeldete Person erstellen, solange du nicht festlegst, wer das darf: Setze `TALE_ORGANIZATION_CREATORS` auf deren Anmeldeadressen, dann verschwindet für alle anderen der Eintrag **Organisation erstellen** aus der Organisationsauswahl, und die API weist sie mit `403 ORGANIZATION_CREATION_FORBIDDEN` ab. Die erste Organisation ist immer erlaubt, die Einrichtung bleibt also unberührt. Ein verwaltetes Deployment deklariert dieselbe Liste als `organizations.creators` in seiner Spezifikation; siehe [Die tale-CLI installieren](https://docs.tale.dev/de/self-hosted/install/cli-install#managed-organization-creators) und die [Umgebungsvariablen-Referenz](https://docs.tale.dev/de/self-hosted/configuration/environment-reference).

[Mitglieder und Rollen](https://docs.tale.dev/de/platform/admin/members-and-roles) hilft bei der Zugriffswahl. [Sende danach deine erste Nachricht](https://docs.tale.dev/de/get-started/quickstart) und prüfe die vollständige Antwort. Erstelle einen [Projektagenten](https://docs.tale.dev/de/tutorials/editor/first-agent-end-to-end), sobald du eine Aufgabe delegieren möchtest. Ein funktionierendes Dashboard bestätigt den App-Zugriff, aber noch nicht den Anbieter oder jeden Hintergrunddienst.

# Eine Installationsmethode wählen
Source: https://docs.tale.dev/de/self-hosted/install

Für eine gewöhnliche Installation nutzt du die Tale-CLI. Ein eigener Stack ist sinnvoll, wenn deine Infrastrukturwerkzeuge die Dienstdefinitionen verwalten müssen. Beide Wege brauchen dieselben Anwendungsdienste und eine verantwortliche Person für Konfiguration und Wartung.

## Mit der CLI installieren

Der [Schnellstart](https://docs.tale.dev/de/self-hosted/install/quickstart) führt dich durch Voraussetzungen, Projekterstellung, Start und erste Anmeldung. `tale init` bereitet ein Projektverzeichnis vor. `tale dev` startet eine Entwicklungsinstanz; `tale deploy` führt das Deployment dieser Umgebung aus.

Die CLI übernimmt Containeraktionen. Für Konfiguration, Zugangsdaten, Volumes und Updates bleibst du verantwortlich. Bewahre das Projektverzeichnis zusammen mit seinen Deployment-Einstellungen auf. [CLI installieren](https://docs.tale.dev/de/self-hosted/install/cli-install) beschreibt unterstützte Systeme, den Zugriff auf einen entfernten Docker-Host, Befehle und verwaltete Deployments.

## Eigene Dienstdefinitionen verwenden

[Einen eigenen Stack betreiben](https://docs.tale.dev/de/self-hosted/install/own-compose) beschreibt Dienste, Volumes, Netzwerk, Bereitschaftsprüfungen und Startreihenfolge. Nutze die Anleitung, wenn du Compose selbst pflegst. [Auf Kubernetes bereitstellen](https://docs.tale.dev/de/self-hosted/install/kubernetes) überträgt diesen Vertrag in Deployments, Services und NetworkPolicies und nennt die Prüfungen, die ein Cluster bestehen muss. Tale liefert kein offizielles Helm-Chart.

Für Änderungen am Tale-Quellcode richtest du eine [Entwicklungsumgebung](https://docs.tale.dev/de/develop/contributor-setup) ein, statt mit einem Produktionsdeployment zu beginnen.

## Die Ersteinrichtung abschließen

Sobald die Instanz bereit ist, [erstellst du das erste Administratorkonto](https://docs.tale.dev/de/self-hosted/install/first-admin), verbindest einen Anbieter und testest einen Chat. Weitere Nutzer fügst du über [Mitglieder und Rollen](https://docs.tale.dev/de/platform/admin/members-and-roles) hinzu. Welche Konto- und Anmeldeoptionen verfügbar sind, hängt von deiner Organisation ab.

Richte vor der Arbeit mit Produktionsdaten TLS und Backups ein. Prüfe die [Umgebungseinstellungen](https://docs.tale.dev/de/self-hosted/configuration/environment-reference) und lies die [Betriebsarchitektur](https://docs.tale.dev/de/self-hosted/operate/container-architecture).

# Auf Kubernetes bereitstellen
Source: https://docs.tale.dev/de/self-hosted/install/kubernetes

Tale läuft auf Kubernetes, wenn du den [Dienstvertrag](https://docs.tale.dev/de/self-hosted/install/own-compose) in Deployments, Services und Volumes überträgst und den Sandbox-Spawner auf `SANDBOX_BACKEND=kubernetes` umstellst. Ein offizielles Helm-Chart gibt es nicht. Diese Anleitung enthält einen vollständigen Manifestsatz für einen Namespace, der mit Tale 0.5.31 auf einem Cluster mit einem Node von Anfang bis Ende durchgespielt wurde, zusammen mit den Prüfungen, die das Ergebnis belegen. Cluster, Speicher, öffentlicher Zugang und Rollout-Ablauf bleiben in deiner Verantwortung.

## Voraussetzungen prüfen

| Voraussetzung | Grund |
| --- | --- |
| Ein CNI, das NetworkPolicy durchsetzt, etwa Calico, Cilium oder kube-network-policies | Die Egress-Sperre der Sandbox und die Sperre des Backends sind NetworkPolicy-Objekte. Jeder API-Server nimmt sie an; erst das CNI blockiert damit Verkehr. |
| Eine Standard-StorageClass, deren `ReadWriteOnce`-Volumes dort wieder eingebunden werden, wo ein Pod eingeplant wird | Datenbank, Objektspeicher, Proxy-Zertifikate, Gateway-Zustand und jeder Sandbox-Workspace liegen auf PersistentVolumeClaims. Das Volume eines gelöschten Sandbox-Workspace folgt der `reclaimPolicy` der StorageClass: Mit `Delete` verschwinden seine Dateien mit ihm, mit `Retain` bleiben sie, bis du das Volume entfernst. |
| `ReadWriteMany`-Speicher oder ein einzelner Node für die Organisationskonfiguration | Die Backend-Rollen schreiben `config-data`; Web-Ebene und Spawner lesen es. Auf einem Node genügt `ReadWriteOnce`. Mehrere Nodes brauchen `ReadWriteMany` oder eine Node-Bindung für diese Pods. |
| Nodes, die `NET_ADMIN` gewähren und ip6tables bereitstellen oder die IPv6-Sysctls erlauben | Der Egress-Proxy installiert beim Start seine Firewall und verweigert den Start ohne sie. |
| Ports 80 und 443 unter der öffentlichen Adresse erreichbar | Caddy besorgt sich im Modus `selfsigned` und `letsencrypt` die Zertifikate selbst. Hinter einem Ingress, der TLS terminiert, setzt du `TLS_MODE=external`. |
| Pull-Zugriff auf `ghcr.io/tale-project/tale/*` auf jedem Node, einschließlich des Sandbox-Runtime-Images | Sitzungs-Pods starten aus `SANDBOX_RUNTIME_IMAGE`. Ein Node, der es nicht laden kann, lässt die erste dort eingeplante Sitzung scheitern. |
| Eine sysbox- oder kata-RuntimeClass, wenn Agenten Docker in ihrer Sandbox brauchen | Ohne sie bleibt `SANDBOX_DOCKER_IN_CONTAINER=false`. Die Stufe `runc` bräuchte privilegierte Pods. |
| `kubectl` und `envsubst` auf dem Rechner, der die Manifeste anwendet | Die Manifeste enthalten eine Variable `${VERSION}`, die kubectl nicht expandiert. |

Reserviere Arbeitsspeicher für die Anwendungsrollen plus eine Agentensitzung je gleichzeitiger Aufgabe; `SANDBOX_AGENT_MEMORY` und die übrigen Sitzungslimits stehen in der [Umgebungsreferenz](https://docs.tale.dev/de/self-hosted/configuration/environment-reference#sandbox-infrastructure).

## Den Namespace aufteilen

Alle Dienste laufen in einem Namespace, `tale`. Sitzungs-Pods müssen `backend-api` und `sandbox-llm-gateway` direkt erreichen, und die Egress-Sperre, die der Spawner anlegt, erlaubt nur den Namespace, in dem er läuft. Deshalb gehören auch die Anwendungsrollen dorthin. Die Service-Namen entsprechen den Compose-Dienstnamen: Die Images lösen `db`, `knowledge-db`, `object-store`, `backend-api`, `platform`, `sandbox`, `sandbox-egress`, `sandbox-llm-gateway` samt Alias `llm-gateway` und `bgutil-provider` über den Namen auf.

<Warning>

Jeder Pod unten setzt `enableServiceLinks: false`. Andernfalls injiziert Kubernetes für jeden Service im Namespace Variablen im Docker-Stil, etwa `SANDBOX_PORT=tcp://10.96.6.49:8003` und `DB_PORT=tcp://10.96.150.113:5432`. Der Spawner liest `SANDBOX_PORT` als seinen Listen-Port und beendet sich beim Start, und das Platform-Image leitet seine Datenbank-URL aus `DB_PORT` ab.

</Warning>

| Compose-Dienst | Kubernetes-Objekte | Hinweise |
| --- | --- | --- |
| `db` mit Alias `knowledge-db` | StatefulSet `db`; Services `db` und `knowledge-db` auf denselben Pod | `TALE_DB_ROLE` bleibt ungesetzt: Das Image legt beide Datenbanken an und wendet die Wissensmigrationen an; das Backend migriert das Anwendungsschema beim Start. Ein `emptyDir` im Arbeitsspeicher mit 256 MiB dient als `/dev/shm`. Das Image stoppt mit `SIGINT` innerhalb von 60 Sekunden Frist. |
| `object-store` | Deployment mit Strategie `Recreate`, PVC unter `/data`, Service auf 9000 | Das Backend legt den Bucket beim Start an. |
| `platform` | Deployment; Service auf 3000 | `config-data` nur lesend, `TALE_BACKEND_URL=http://backend-api:3005`. |
| `backend-api` | Deployment mit zwei Replikaten; Service auf 3005 | `config-data` lesend und schreibend. Zwei Replikate ermöglichen einen Rollout ohne Lücke. |
| `backend-worker` | Deployment | Kein Service und keine HTTP-Prüfung. |
| `proxy` | Deployment mit Strategie `Recreate`; `hostPort` 80 und 443; PVC für `/data` | Der Zertifikatspeicher überlebt Neustarts auf dem PVC. |
| `sandbox` | ServiceAccount, Role, RoleBinding, Deployment; Service auf 8003 | `SANDBOX_BACKEND=kubernetes`; `config-data` nur lesend unter `/app/platform-config`. Kein Docker-Socket. |
| `sandbox-egress` | Deployment; Service auf 3128 | Der ausgelieferte Capability-Satz, keine Sysctls. |
| `sandbox-llm-gateway` | Deployment mit Strategie `Recreate`, PVC unter `/app/data`; Services `sandbox-llm-gateway` und `llm-gateway` auf 8080 | Das Image läuft als uid 1000; `fsGroup: 1000` lässt es seinen Zustand schreiben. Das Gateway liest `SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD` aus `tale-env`: Solange es kein Admin-Konto hat, legt es eines nur für einen Aufrufer an, der dieses Geheimnis vorweist. |
| `bgutil-provider` | Deployment; Service auf 4416 | Optionaler Token-Anbieter für Videos. |

Die Prüfungen übertragen die Compose-Healthchecks:

| Dienst | Startprüfung | Bereitschaftsprüfung | Lebendigkeitsprüfung |
| --- | --- | --- | --- |
| `backend-api` | `GET /ping` auf 3005, bis zu fünf Minuten für Migrationen | `GET /ready` auf 3005 | `GET /ping` auf 3005 |
| `platform` | `curl -sf http://localhost:3000/api/health && [ -f /tmp/platform-ready ]`, bis zu drei Minuten | derselbe Befehl | keine |
| `db` | `pg_isready -U tale -d tale && [ -f /tmp/.db_ready ]`, bis zu drei Minuten | derselbe Befehl | `pg_isready -U tale -d tale` |
| `object-store` | keine | `mc ready local` | keine |
| `proxy` | keine | `GET /health` auf 2020 | keine |
| `sandbox` | `GET /health` auf 8003 | `GET /health` auf 8003 | keine |
| `sandbox-egress` | keine | `curl -sS -o /dev/null --max-time 3 --noproxy '*' http://127.0.0.1:3128/` | keine |
| `sandbox-llm-gateway` | keine | `GET /health` auf 8080 | keine |

Kubernetes kennt kein `depends_on`. Eine Backend-Rolle, die startet, bevor Postgres antwortet, beendet sich einmal mit `ECONNREFUSED`; die Neustartrichtlinie heilt das.

## Die Manifeste vorbereiten

Speichere jeden YAML-Block der folgenden Abschnitte unter dem Dateinamen aus seiner ersten Zeile in einem Verzeichnis. Bearbeite das Secret: Ersetze jeden Platzhalter `<...>` und setze `HOST`, `SITE_URL`, `TLS_MODE` und `OBJECT_STORE_PUBLIC_ENDPOINT` für deine Adresse. Enthält diese Adresse einen abweichenden Port, trage ihn auch als `containerPort` und `hostPort` des Proxys in `30-proxy.yaml` ein; Caddy lauscht auf dem Port aus `SITE_URL`. Lege dann eine Version für alle Tale-Images fest, zum Zeitpunkt dieser Anleitung `0.5.31`, und wende die Dateien der Reihe nach an:

```bash
export VERSION=0.5.31
for f in 00-namespace.yaml 10-stores.yaml 20-application.yaml 30-proxy.yaml 40-sandbox.yaml; do
  envsubst '${VERSION}' < "$f" | kubectl apply -f -
done
```

`envsubst` ersetzt nur `${VERSION}`; jeder andere Wert in den Dateien ist wörtlich gemeint. Dieselbe Schleife führt ein Upgrade aus: Ändere `VERSION`, starte sie erneut, und die Deployments rollen auf das neue Image.

## Die gemeinsame Umgebung anlegen

Die erste Datei enthält den Namespace, die deploymentweiten Werte aus der Compose-`.env` und den gemeinsamen Konfigurations-Claim. Erzeuge jedes Geheimnis einmal und bewahre es auf; besonders `ENCRYPTION_SECRET_HEX` muss für vorhandene verschlüsselte Werte stabil bleiben. Die [Umgebungsreferenz](https://docs.tale.dev/de/self-hosted/configuration/environment-reference) erklärt jede Variable.

```yaml
# 00-namespace.yaml
apiVersion: v1
kind: Namespace
metadata: { name: tale }
---
apiVersion: v1
kind: Secret
metadata: { name: tale-env, namespace: tale }
type: Opaque
stringData:
  HOST: tale.example.com
  SITE_URL: https://tale.example.com
  TLS_MODE: letsencrypt
  POSTGRES_USER: tale
  POSTGRES_DB: tale
  DB_PASSWORD: <generated>
  DATABASE_URL: postgresql://tale:<DB_PASSWORD>@db:5432/tale_app
  KNOWLEDGE_DB_NAME: tale_knowledge
  INSTANCE_SECRET: <openssl rand -hex 32>
  BETTER_AUTH_SECRET: <openssl rand -hex 32>
  ENCRYPTION_SECRET_HEX: <openssl rand -hex 32>
  TALE_AUDIT_PEPPER: <openssl rand -hex 32>
  SANDBOX_TOKEN: <openssl rand -hex 32>
  SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD: <generated>
  OBJECT_STORE_ACCESS_KEY: tale
  OBJECT_STORE_SECRET_KEY: <generated>
  OBJECT_STORE_BUCKET: tale-blobs
  OBJECT_STORE_ENDPOINT: http://object-store:9000
  OBJECT_STORE_REGION: us-east-1
  OBJECT_STORE_PUBLIC_ENDPOINT: https://tale.example.com
---
# Organisationskonfiguration: Backend-Rollen schreiben, Platform und Spawner lesen.
# Auf einem Node genügt ReadWriteOnce; mehrere Nodes brauchen ReadWriteMany.
apiVersion: v1
kind: PersistentVolumeClaim
metadata: { name: config-data, namespace: tale }
spec:
  accessModes: [ReadWriteOnce]
  resources: { requests: { storage: 2Gi } }
```

`DATABASE_URL` enthält dasselbe Passwort wie `DB_PASSWORD`; die Wissensverbindung verwendet standardmäßig `knowledge-db:5432/tale_knowledge` mit diesem Passwort. `SITE_URL` muss der Adresse im Browser entsprechen, einschließlich eines abweichenden Ports.

## Die Speicher betreiben

Das StatefulSet behält das Datenvolume über Pod-Ersetzungen hinweg und gibt dem Image das Herunterfahren, das es erwartet. MinIO läuft als einzelnes Deployment auf einem eigenen Claim.

```yaml
# 10-stores.yaml
apiVersion: v1
kind: Service
metadata: { name: db, namespace: tale }
spec:
  selector: { app: db }
  ports: [{ name: pg, port: 5432, targetPort: 5432 }]
---
apiVersion: v1
kind: Service
metadata: { name: knowledge-db, namespace: tale }
spec:
  selector: { app: db }
  ports: [{ name: pg, port: 5432, targetPort: 5432 }]
---
apiVersion: apps/v1
kind: StatefulSet
metadata: { name: db, namespace: tale }
spec:
  serviceName: db
  replicas: 1
  selector: { matchLabels: { app: db } }
  template:
    metadata: { labels: { app: db } }
    spec:
      enableServiceLinks: false
      terminationGracePeriodSeconds: 60
      containers:
        - name: postgres
          image: ghcr.io/tale-project/tale/tale-db:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          ports: [{ name: pg, containerPort: 5432 }]
          volumeMounts:
            - { name: data, mountPath: /var/lib/postgresql/data }
            - { name: shm, mountPath: /dev/shm }
          startupProbe:
            exec: { command: [sh, -c, 'pg_isready -U tale -d tale && [ -f /tmp/.db_ready ]'] }
            periodSeconds: 5
            failureThreshold: 36
          readinessProbe:
            exec: { command: [sh, -c, 'pg_isready -U tale -d tale && [ -f /tmp/.db_ready ]'] }
            periodSeconds: 5
          livenessProbe:
            exec: { command: [sh, -c, 'pg_isready -U tale -d tale'] }
            periodSeconds: 15
          resources:
            requests: { cpu: 250m, memory: 512Mi }
      volumes:
        - name: shm
          emptyDir: { medium: Memory, sizeLimit: 256Mi }
  volumeClaimTemplates:
    - metadata: { name: data }
      spec:
        accessModes: [ReadWriteOnce]
        resources: { requests: { storage: 20Gi } }
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata: { name: object-store-data, namespace: tale }
spec:
  accessModes: [ReadWriteOnce]
  resources: { requests: { storage: 20Gi } }
---
apiVersion: v1
kind: Service
metadata: { name: object-store, namespace: tale }
spec:
  selector: { app: object-store }
  ports: [{ name: s3, port: 9000, targetPort: 9000 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: object-store, namespace: tale }
spec:
  replicas: 1
  strategy: { type: Recreate }
  selector: { matchLabels: { app: object-store } }
  template:
    metadata: { labels: { app: object-store } }
    spec:
      enableServiceLinks: false
      terminationGracePeriodSeconds: 30
      containers:
        - name: minio
          image: ghcr.io/tale-project/ops/minio:RELEASE.2025-04-22T22-12-26Z
          args: ['server', '/data', '--address', ':9000', '--console-address', ':9001']
          env:
            - name: MINIO_ROOT_USER
              valueFrom: { secretKeyRef: { name: tale-env, key: OBJECT_STORE_ACCESS_KEY } }
            - name: MINIO_ROOT_PASSWORD
              valueFrom: { secretKeyRef: { name: tale-env, key: OBJECT_STORE_SECRET_KEY } }
            - { name: MINIO_BROWSER, value: 'off' }
          ports: [{ name: s3, containerPort: 9000 }]
          volumeMounts: [{ name: data, mountPath: /data }]
          readinessProbe:
            exec: { command: [sh, -c, 'mc ready local'] }
            periodSeconds: 10
          resources:
            requests: { cpu: 100m, memory: 256Mi }
      volumes:
        - name: data
          persistentVolumeClaim: { claimName: object-store-data }
```

Für ein externes Postgres setzt du `DATABASE_URL` und `KNOWLEDGE_DATABASE_URL` wie unter [Externe Speicher verbinden](https://docs.tale.dev/de/self-hosted/install/own-compose#externe-speicher-verbinden) beschrieben und lässt StatefulSet und Services weg; für einen externen Bucket setzt du die `OBJECT_STORE_*`-Werte und lässt die MinIO-Objekte weg.

## Die Anwendungsrollen betreiben

Die drei Rollen teilen sich das Platform-Image: API und Worker schreiben `config-data`, die Web-Ebene liest es. Die Datei enthält außerdem den optionalen Token-Anbieter für Videos, den der Worker nutzt; entferne seine beiden Objekte, wenn du keine Videos aufnimmst.

<Warning>

Die Backend-Rollen laufen ohne `NET_ADMIN` und mit `TALE_SKIP_SSRF_FIREWALL=1`. Mit dieser Capability installiert das Image seine iptables-Egress-Sperre, die nur die direkt angebundenen Subnetze des Pods erlaubt und den übrigen privaten Adressraum abweist. In einem Pod-Netz trifft das auch den Cluster-DNS und jede Service-Adresse: Die Rolle scheitert mit `getaddrinfo EAI_AGAIN db` und startet neu, bis du die Capability entfernst. Die NetworkPolicy am Ende der Datei übernimmt die Sperre: Die Rollen erreichen jeden Nachbarn im Namespace, den Cluster-DNS und das öffentliche Internet, aber nie den Cloud-Metadatendienst, die Nodes oder private Netze. Erweitere ihre letzte Regel, wenn deine Modellanbieter oder Konnektoren in einem privaten Bereich liegen.

</Warning>

```yaml
# 20-application.yaml
apiVersion: v1
kind: Service
metadata: { name: backend-api, namespace: tale }
spec:
  selector: { app: backend-api }
  ports: [{ name: http, port: 3005, targetPort: 3005 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: backend-api, namespace: tale }
spec:
  replicas: 2
  selector: { matchLabels: { app: backend-api } }
  template:
    metadata: { labels: { app: backend-api, tale.tier: backend } }
    spec:
      enableServiceLinks: false
      terminationGracePeriodSeconds: 45
      containers:
        - name: backend-api
          image: ghcr.io/tale-project/tale/tale-platform:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          env:
            - { name: TALE_ROLE, value: api }
            - { name: PORT, value: '3005' }
            - { name: TALE_CONFIG_DIR, value: /app/data }
            - { name: SANDBOX_URL, value: http://sandbox:8003 }
            - { name: SANDBOX_HTTP_API_BASE_URL, value: http://backend-api:3005 }
            - { name: TALE_SKIP_SSRF_FIREWALL, value: '1' }
          ports: [{ name: http, containerPort: 3005 }]
          volumeMounts: [{ name: config-data, mountPath: /app/data }]
          startupProbe:
            httpGet: { path: /ping, port: 3005 }
            periodSeconds: 5
            failureThreshold: 60
          readinessProbe:
            httpGet: { path: /ready, port: 3005 }
            periodSeconds: 5
          livenessProbe:
            httpGet: { path: /ping, port: 3005 }
            periodSeconds: 10
          resources:
            requests: { cpu: 500m, memory: 1Gi }
      volumes:
        - name: config-data
          persistentVolumeClaim: { claimName: config-data }
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: backend-worker, namespace: tale }
spec:
  replicas: 1
  selector: { matchLabels: { app: backend-worker } }
  template:
    metadata: { labels: { app: backend-worker, tale.tier: backend } }
    spec:
      enableServiceLinks: false
      terminationGracePeriodSeconds: 45
      containers:
        - name: backend-worker
          image: ghcr.io/tale-project/tale/tale-platform:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          env:
            - { name: TALE_ROLE, value: worker }
            - { name: TALE_CONFIG_DIR, value: /app/data }
            - { name: SANDBOX_URL, value: http://sandbox:8003 }
            - { name: SANDBOX_HTTP_API_BASE_URL, value: http://backend-api:3005 }
            - { name: TALE_SKIP_SSRF_FIREWALL, value: '1' }
          volumeMounts: [{ name: config-data, mountPath: /app/data }]
          resources:
            requests: { cpu: 500m, memory: 1Gi }
      volumes:
        - name: config-data
          persistentVolumeClaim: { claimName: config-data }
---
apiVersion: v1
kind: Service
metadata: { name: platform, namespace: tale }
spec:
  selector: { app: platform }
  ports: [{ name: http, port: 3000, targetPort: 3000 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: platform, namespace: tale }
spec:
  replicas: 1
  selector: { matchLabels: { app: platform } }
  template:
    metadata: { labels: { app: platform } }
    spec:
      enableServiceLinks: false
      terminationGracePeriodSeconds: 45
      containers:
        - name: platform
          image: ghcr.io/tale-project/tale/tale-platform:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          env:
            - { name: TALE_BACKEND_URL, value: http://backend-api:3005 }
            - { name: TALE_CONFIG_DIR, value: /app/data }
          ports: [{ name: http, containerPort: 3000 }]
          volumeMounts: [{ name: config-data, mountPath: /app/data, readOnly: true }]
          startupProbe:
            exec: { command: [sh, -c, 'curl -sf http://localhost:3000/api/health && [ -f /tmp/platform-ready ]'] }
            periodSeconds: 5
            failureThreshold: 36
          readinessProbe:
            exec: { command: [sh, -c, 'curl -sf http://localhost:3000/api/health && [ -f /tmp/platform-ready ]'] }
            periodSeconds: 5
          resources:
            requests: { cpu: 250m, memory: 512Mi }
      volumes:
        - name: config-data
          persistentVolumeClaim: { claimName: config-data }
---
apiVersion: v1
kind: Service
metadata: { name: bgutil-provider, namespace: tale }
spec:
  selector: { app: bgutil-provider }
  ports: [{ name: http, port: 4416, targetPort: 4416 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: bgutil-provider, namespace: tale }
spec:
  replicas: 1
  selector: { matchLabels: { app: bgutil-provider } }
  template:
    metadata: { labels: { app: bgutil-provider } }
    spec:
      enableServiceLinks: false
      automountServiceAccountToken: false
      containers:
        - name: provider
          image: brainicism/bgutil-ytdlp-pot-provider:1.3.1
          ports: [{ name: http, containerPort: 4416 }]
          readinessProbe:
            tcpSocket: { port: 4416 }
            periodSeconds: 30
          resources:
            requests: { cpu: 50m, memory: 128Mi }
            limits: { memory: 512Mi }
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata: { name: tale-backend-egress, namespace: tale }
spec:
  podSelector:
    matchLabels: { tale.tier: backend }
  policyTypes: [Egress]
  egress:
    - to:
        - podSelector: {}
    - to:
        - namespaceSelector: {}
      ports:
        - { protocol: UDP, port: 53 }
        - { protocol: TCP, port: 53 }
    - to:
        - ipBlock:
            cidr: 0.0.0.0/0
            except:
              - 169.254.0.0/16
              - 10.0.0.0/8
              - 172.16.0.0/12
              - 192.168.0.0/16
```

Die Platform-Container starten als root, korrigieren die Besitzrechte von `/app/data` und wechseln dann zum Anwendungsbenutzer; setze auf ihnen kein `runAsNonRoot`.

## Den Proxy veröffentlichen

Der Proxy ist der einzige öffentliche Dienst. Er bindet `hostPort` 80 und 443 auf dem Node, auf dem er läuft; richte den öffentlichen Namen auf die Adresse dieses Nodes. Caddy lauscht auf dem Port, den `SITE_URL` nennt: Mit `https://tale.example.com:8443` muss der Pod 8443 statt 443 freigeben, während Port 80 weiter die Umleitung auf HTTPS bedient. Die Strategie ist `Recreate`: Zwei Proxy-Pods können sich weder einen `hostPort` noch ein `ReadWriteOnce`-Volume teilen.

```yaml
# 30-proxy.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata: { name: caddy-data, namespace: tale }
spec:
  accessModes: [ReadWriteOnce]
  resources: { requests: { storage: 1Gi } }
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: proxy, namespace: tale }
spec:
  replicas: 1
  strategy: { type: Recreate }
  selector: { matchLabels: { app: proxy } }
  template:
    metadata: { labels: { app: proxy } }
    spec:
      enableServiceLinks: false
      containers:
        - name: caddy
          image: ghcr.io/tale-project/tale/tale-proxy:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          env:
            - { name: BACKEND_UPSTREAM, value: 'backend-api:3005' }
            - { name: OBJECT_STORE_UPSTREAM, value: 'object-store:9000' }
          ports:
            - { name: http, containerPort: 80, hostPort: 80 }
            - { name: https, containerPort: 443, hostPort: 443 }
          volumeMounts:
            - { name: caddy-data, mountPath: /data }
            - { name: caddy-config, mountPath: /config }
          readinessProbe:
            httpGet: { path: /health, port: 2020 }
            periodSeconds: 10
          resources:
            requests: { cpu: 50m, memory: 64Mi }
      volumes:
        - name: caddy-data
          persistentVolumeClaim: { claimName: caddy-data }
        - name: caddy-config
          emptyDir: {}
```

Zwei Alternativen behalten denselben Pod:

- Ein LoadBalancer-Service auf 80 und 443 vor dem Proxy statt der `hostPort`-Einträge. `TLS_MODE=selfsigned` und `letsencrypt` funktionieren unverändert; der Proxy bedient auch `docs.<HOST>` und besorgt dafür ein Zertifikat.
- Ein Ingress, der TLS terminiert. Setze `TLS_MODE=external` und `TRUSTED_PROXIES` auf den Adressbereich des Ingress, damit weitergeleitete Header akzeptiert werden, wie in [TLS und Domains](https://docs.tale.dev/de/self-hosted/configuration/tls-and-domains) beschrieben.

## Die Sandbox-Ebene betreiben

Der Egress-Proxy braucht den Capability-Satz aus dem Compose-Vertrag und keine Sysctls: Der Entrypoint installiert die IPv6-Firewall mit ip6tables, wenn der Node-Kernel sie anbietet, und deaktiviert IPv6 andernfalls im eigenen Netzwerk-Namespace. Ein Cluster, der beides verweigert, blockiert den Pod beim Start; erlaube in dem Fall die Sysctls `net.ipv6.conf.*` auf dem Kubelet. Der Spawner legt Sitzungs-Pods, Secrets und Workspace-Claims über die Kubernetes-API an und läuft deshalb mit einer namespacegebundenen Role und ohne Docker-Socket.

Der Proxy bedient `SANDBOX_EGRESS_MAX_CLIENTS` Verbindungen gleichzeitig (standardmäßig 2000) für alle Sessions zusammen, jede mit einem Thread und zwei offenen Dateien. Eine Pod-Spezifikation kann keine Grenzen für Prozesse oder offene Dateien setzen: Beim Start hebt der Proxy seine Grenze für offene Dateien auf das an, was seine Verbindungen brauchen, so weit die harte Grenze der Container-Runtime es erlaubt, und warnt in seinem Log, wenn sie zu niedrig ist. Seine Threads zählen gegen das `podPidsLimit` des Kubelets; setzen deine Nodes eines, halte es über der Verbindungsgrenze oder senke `SANDBOX_EGRESS_MAX_CLIENTS` passend.

```yaml
# 40-sandbox.yaml
apiVersion: v1
kind: Service
metadata: { name: sandbox-egress, namespace: tale }
spec:
  selector: { app: sandbox-egress }
  ports: [{ name: proxy, port: 3128, targetPort: 3128 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: sandbox-egress, namespace: tale }
spec:
  replicas: 1
  selector: { matchLabels: { app: sandbox-egress } }
  template:
    metadata: { labels: { app: sandbox-egress } }
    spec:
      enableServiceLinks: false
      automountServiceAccountToken: false
      containers:
        - name: egress
          image: ghcr.io/tale-project/tale/tale-sandbox-egress:${VERSION}
          env:
            - { name: SANDBOX_EGRESS_MAX_CLIENTS, value: '2000' }
          securityContext:
            runAsUser: 0
            capabilities:
              drop: ['ALL']
              add: ['NET_ADMIN', 'DAC_OVERRIDE', 'CHOWN', 'SETUID', 'SETGID', 'NET_BIND_SERVICE', 'KILL']
          ports: [{ name: proxy, containerPort: 3128 }]
          readinessProbe:
            exec: { command: [sh, -c, "curl -sS -o /dev/null --max-time 3 --noproxy '*' http://127.0.0.1:3128/"] }
            periodSeconds: 10
          resources:
            requests: { cpu: 50m, memory: 64Mi }
            limits: { memory: 512Mi }
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata: { name: llm-gateway-data, namespace: tale }
spec:
  accessModes: [ReadWriteOnce]
  resources: { requests: { storage: 1Gi } }
---
apiVersion: v1
kind: Service
metadata: { name: sandbox-llm-gateway, namespace: tale }
spec:
  selector: { app: sandbox-llm-gateway }
  ports: [{ name: http, port: 8080, targetPort: 8080 }]
---
apiVersion: v1
kind: Service
metadata: { name: llm-gateway, namespace: tale }
spec:
  selector: { app: sandbox-llm-gateway }
  ports: [{ name: http, port: 8080, targetPort: 8080 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: sandbox-llm-gateway, namespace: tale }
spec:
  replicas: 1
  strategy: { type: Recreate }
  selector: { matchLabels: { app: sandbox-llm-gateway } }
  template:
    metadata: { labels: { app: sandbox-llm-gateway } }
    spec:
      enableServiceLinks: false
      automountServiceAccountToken: false
      securityContext: { fsGroup: 1000 }
      containers:
        - name: gateway
          image: ghcr.io/tale-project/tale/tale-sandbox-llm-gateway:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          ports: [{ name: http, containerPort: 8080 }]
          volumeMounts: [{ name: data, mountPath: /app/data }]
          readinessProbe:
            httpGet: { path: /health, port: 8080 }
            periodSeconds: 10
          resources:
            requests: { cpu: 50m, memory: 128Mi }
            limits: { memory: 512Mi }
      volumes:
        - name: data
          persistentVolumeClaim: { claimName: llm-gateway-data }
---
apiVersion: v1
kind: ServiceAccount
metadata: { name: tale-sandbox-spawner, namespace: tale }
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata: { name: tale-sandbox-spawner, namespace: tale }
rules:
  - apiGroups: ['']
    resources: ['pods']
    verbs: ['create', 'get', 'list', 'delete', 'patch']
  - apiGroups: ['']
    resources: ['secrets']
    verbs: ['create', 'delete', 'list']
  - apiGroups: ['']
    resources: ['persistentvolumeclaims']
    verbs: ['get', 'list', 'create', 'delete']
  - apiGroups: ['networking.k8s.io']
    resources: ['networkpolicies']
    verbs: ['create', 'update']
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata: { name: tale-sandbox-spawner, namespace: tale }
roleRef: { apiGroup: rbac.authorization.k8s.io, kind: Role, name: tale-sandbox-spawner }
subjects: [{ kind: ServiceAccount, name: tale-sandbox-spawner, namespace: tale }]
---
apiVersion: v1
kind: Service
metadata: { name: sandbox, namespace: tale }
spec:
  selector: { app: sandbox }
  ports: [{ name: http, port: 8003, targetPort: 8003 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: sandbox, namespace: tale }
spec:
  replicas: 1
  selector: { matchLabels: { app: sandbox } }
  template:
    metadata: { labels: { app: sandbox } }
    spec:
      enableServiceLinks: false
      serviceAccountName: tale-sandbox-spawner
      terminationGracePeriodSeconds: 30
      containers:
        - name: spawner
          image: ghcr.io/tale-project/tale/tale-sandbox:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          env:
            - { name: SANDBOX_BACKEND, value: kubernetes }
            - { name: SANDBOX_K8S_NAMESPACE, value: tale }
            - { name: SANDBOX_RUNTIME_IMAGE, value: 'ghcr.io/tale-project/tale/tale-sandbox-runtime:${VERSION}' }
            - { name: NODE_EXTRA_CA_CERTS, value: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt }
            - { name: SANDBOX_RUNTIME, value: runc }
            - { name: SANDBOX_DOCKER_IN_CONTAINER, value: 'false' }
            - { name: SANDBOX_EGRESS_PROXY, value: 'http://sandbox-egress:3128' }
          ports: [{ name: http, containerPort: 8003 }]
          volumeMounts: [{ name: config-data, mountPath: /app/platform-config, readOnly: true }]
          startupProbe:
            httpGet: { path: /health, port: 8003 }
            periodSeconds: 5
            failureThreshold: 24
          readinessProbe:
            httpGet: { path: /health, port: 8003 }
            periodSeconds: 10
          resources:
            requests: { cpu: 100m, memory: 256Mi }
            limits: { memory: 512Mi }
      volumes:
        - name: config-data
          persistentVolumeClaim: { claimName: config-data }
```

| Einstellung | Anforderung |
| --- | --- |
| `SANDBOX_BACKEND` | `kubernetes`. Docker-Hostpfade und Bridge-Namen konfigurieren dieses Backend nicht. |
| `SANDBOX_K8S_NAMESPACE` | Der Namespace, in dem Sitzungs-Pods, Secrets und Workspace-Claims entstehen; in dieser Aufteilung der Namespace des Spawners selbst. Standard `tale-sandbox`. |
| `SANDBOX_RUNTIME_IMAGE` | Das passende Tale-Sandbox-Runtime-Image, für jeden Node verfügbar. |
| `NODE_EXTRA_CA_CERTS` | Die CA-Datei des Clusters, im Spawner normalerweise `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt`. Sie ist der einzige CA-Vertrauensweg, den der Spawner beachtet; lass die TLS-Prüfung eingeschaltet. |
| `SANDBOX_K8S_WORKSPACE_SIZE_LIMIT` | Die Größe des `/agent`-Workspace-Claims jeder Agent-Session, Standard `4Gi`; begrenzt auch den temporären Workspace eines Crawler-Renders, der ohne Claim auskommt, weil er nie fortgesetzt wird, und bei aktiviertem innerem Docker dessen temporären Speicher. |
| `SANDBOX_K8S_CPU_REQUEST` / `SANDBOX_K8S_MEMORY_REQUEST` | Was jeder Session-Pod beim Scheduler anfordert, als Kubernetes-Mengenangaben. Ohne Angabe fordert ein Agent-Pod `250m` und `512Mi` an (`1Gi` mit Docker in der Sandbox), ein Crawler-Render `250m` und `512Mi`; eine Anforderung liegt nie über der Grenze des Pods. Erhöhe die Werte, wenn Agents auf deinen Nodes schwerere Builds ausführen, damit der Scheduler nicht mehr Sessions auf einen Node legt, als er tragen kann. |
| `SANDBOX_K8S_CACHE_STORAGECLASS` | Die StorageClass der Workspace-Claims; ohne Wert gilt der Cluster-Standard. |
| `SANDBOX_RUNTIME` / `SANDBOX_RUNTIME_CLASS` | Eine unterstützte Laufzeitstufe und bei Bedarf der Name der installierten RuntimeClass. |
| `SANDBOX_EGRESS_PROXY` | Der Egress-Service, den die Sitzungen nutzen, Standard `http://sandbox-egress:3128`. |

Der Spawner skaliert horizontal. Jedes Replikat findet eine Sitzung, die es nicht selbst angelegt hat, über den deterministischen Pod-Namen und übernimmt sie; exec, Stopp und Zerstören funktionieren daher über jedes Replikat, das der Service auswählt. `SANDBOX_MAX_SESSIONS` zählt den Namespace, gleichzeitige Aufnahmen auf mehreren Replikaten können den Wert aber kurz überschreiten; eine ResourceQuota liefert die harte Grenze. Der [Kubernetes-Vertrag der Sandbox](https://github.com/tale-project/tale/blob/main/services/sandbox/docs/kubernetes.md) dokumentiert die Pod-Form und die Laufzeitdetails.

### Was der Spawner durchsetzt

Beim Start legt der Spawner die NetworkPolicy `tale-sandbox-session-egress` an: Sitzungs-Pods erreichen DNS und die Pods ihres eigenen Namespace und sonst nichts. Der Cloud-Metadatendienst, die Nodes und andere Namespaces bleiben damit auch für einen Prozess unerreichbar, der `HTTP_PROXY` ignoriert. Öffentliche Ziele laufen über `sandbox-egress`. Eine fehlende Berechtigung für `networkpolicies` wird protokolliert und stoppt den Spawner nicht; prüfe, dass die Richtlinie existiert, bevor du Arbeit zulässt.

Sitzungs-Pods führen den Runner als uid 65534 aus, mit allen Capabilities entfernt, einem schreibgeschützten Root-Dateisystem, ohne ServiceAccount-Token und mit dem Sitzungs-Secret nur als Umgebung eingebunden. Der Workspace `/agent` ist ein Claim, der einen Leerlaufstopp überlebt. Ein ausdrückliches Zerstören löscht ihn, ebenso die Workspace-Bereinigung, sobald sein Besitzer entfernt ist oder er länger als das Zeitfenster der Organisation ungenutzt bleibt; die Bereinigung findet die Claims über `list`. Sitzungsaktionen laufen per HTTP zu runnerd auf der Pod-IP an Port 8200; `pods/exec` kommt nicht vor.

<Note>

Die namespaceweite Freigabe ist weiter als das Compose-Netz. Aus einem Sitzungs-Pod antworten Postgres und der Objektspeicher auf ihren Service-Ports, obwohl die Sitzung keine Zugangsdaten für sie besitzt. Diese Speicher in einem anderen Namespace zu halten, würde das einschränken; diese Aufteilung wurde nicht geprüft und braucht eine eigene Richtlinie für die Backend-Rollen.

</Note>

Für Docker in Sitzungen wählst du einen ausdrücklichen `SANDBOX_DIND_INNER_POOL` außerhalb der Pod-, Service- und VPC-Bereiche und liest die [Netzwerkvoraussetzungen für inneres Docker](https://docs.tale.dev/de/self-hosted/configuration/environment-reference#sandbox-infrastructure); ein Pod kann nicht jedes Cluster-Netz erkennen.

## Ausrollen und prüfen

Warte nach der Apply-Schleife, bis jeder Pod bereit ist, und prüfe die Signale, auf die es ankommt:

```bash
kubectl -n tale get pods
kubectl -n tale logs -l 'app in (backend-api,backend-worker)' --tail=-1 | grep -c 'applying app migration'
kubectl -n tale get networkpolicy tale-sandbox-session-egress tale-backend-egress
curl -s https://tale.example.com/api/health
```

Die Backend-Rolle, die zuerst startet, wendet die Migrationen unter einer Advisory-Sperre an; die Zahl stammt deshalb aus beiden Rollen zusammen, und das API-Protokoll endet mit `api listening on :3005`; der Health-Endpunkt antwortet mit `{"status":"ok","version":"0.5.31"}`. Öffne dann die Site, [erstelle den ersten Inhaber](https://docs.tale.dev/de/self-hosted/install/first-admin) und verbinde einen Anbieter.

Unter **Einstellungen > Sandboxes** trägt die Deployment-Karte den Namespace als Geltungsbereich im Titel und zeigt keine CPU- und Speicherwerte des Hosts; auf diesem Backend ist das erwartet. Weise einem Agenten eine Aufgabe zu und warte auf sein Ergebnis: Der Lauf erzeugt im Namespace einen Sitzungs-Pod namens `tale-sbx-ses-<hash>` zusammen mit einem `-spec`-Secret und einem `-ws`-Claim.

Belege die Sperre aus einem laufenden Sitzungs-Pod heraus:

```bash
POD=$(kubectl -n tale get pods -l tale.sandbox/role=session -o name | head -1)
kubectl -n tale exec $POD -c runner -- curl -m 5 http://169.254.169.254/
kubectl -n tale exec $POD -c runner -- curl -m 20 -s -o /dev/null -w '%{http_code}\n' https://example.com/
```

Der erste Befehl läuft in einen Timeout; der zweite gibt `200` aus, erreicht über den Egress-Proxy. Teste danach den Lebenszyklus so, wie du dich im Betrieb darauf verlässt: Ein Runner-Neustart behält Pod und Workspace, eine leerlaufende Sitzung stoppt nach `SANDBOX_SESSION_MAX_IDLE_MS` und lässt ihren Claim zurück, die nächste Aufgabe setzt sie mit erhaltenen Dateien fort, und Zerstören entfernt Pod, Secret und Claim. Wiederhole eine Aufgabe mit zwei Spawner-Replikaten nach dem Skalieren und bestätige, dass das zweite Replikat sie bedient.

Rolle die API ohne Lücke aus, indem du zwei Replikate behältst und das Deployment neu startest:

```bash
kubectl -n tale rollout restart deploy/backend-api
kubectl -n tale rollout status deploy/backend-api
```

Migrationen laufen beim Start unter einer Advisory-Sperre, während das vorherige Image weiter bedient; der Health-Endpunkt bleibt während des Rollouts grün. Halte eine `VERSION` über alle Tale-Images hinweg fest und folge [Bereitstellung aktualisieren und wiederherstellen](https://docs.tale.dev/de/self-hosted/operate/upgrades), bevor du sie änderst; eine Version, die das Proxy-Image ändert, braucht auch einen neu erstellten Proxy-Pod.

Snapshots, Blue-Green-Wechsel und Rollback-Prüfungen der CLI laufen auf Kubernetes nicht. Sichere die Claims mit den Snapshots deines Speicheranbieters und bewahre Secret, Verschlüsselungsschlüssel und Organisationskonfiguration zusammen damit auf; [Backups und Wiederherstellung](https://docs.tale.dev/de/self-hosted/operate/backups-and-restore) nennt, was eine Wiederherstellung braucht.

## Geprüfter Umfang

Diese fünf Dateien wurden bis auf die Secret-Werte unverändert auf einem frischen kind-Cluster mit einem Node, Kubernetes 1.36, kube-network-policies, der StorageClass local-path und Tale 0.5.31 angewendet: Start und Migrationen, der öffentliche Zugang, die Einrichtung des ersten Inhabers samt Sandboxes-Karte, eine Agentenaufgabe mit Ergebnis, der Sitzungslebenszyklus einschließlich Leerlaufstopp, Fortsetzung und replikatübergreifendem Zugriff, die Sperrprüfungen oben und ein Rolling Restart der API mit zwei Replikaten. Mehrere Nodes mit `ReadWriteMany`-Konfigurationsspeicher, Docker in Sitzungen auf einer sysbox- oder kata-RuntimeClass, ein Ingress mit `TLS_MODE=external` und hochverfügbare Speicher waren nicht Teil dieses Laufs.

# Compose selbst betreiben
Source: https://docs.tale.dev/de/self-hosted/install/own-compose

Nutze diese Referenz, wenn dein Team Bereitstellungsdateien und Rollout selbst pflegt. Der [CLI-Schnellstart](https://docs.tale.dev/de/self-hosted/install/quickstart) ist der kürzere Weg, wenn Tale Dateien erzeugen und Upgrades koordinieren soll. Tale liefert kein offizielles Helm-Chart. Der Sandbox-Spawner unterstützt Docker und Kubernetes; wähle die dazu passende Laufzeit- und Netzwerkkonfiguration.

Dies ist eine Beschreibung des Bereitstellungsvertrags mit Beispiel für die Anwendungsebene, keine vollständige startfertige Compose-Datei. Ergänze und prüfe Speicher-, Proxy- und Sandbox-Dienste vor dem Einsatz des Beispiels.

## Dienstaufteilung wählen

| Gruppe | Dienste | Lebenszyklus |
| --- | --- | --- |
| Replizierbare Anwendung | `platform`, `backend-api`, `backend-worker` | Gleiches Image und Release; Schnittstellen während des Austauschs kompatibel halten. |
| Dauerhafte Speicher und Zugang | `db`, `object-store`, `proxy` | Volumes, Zugangsdaten, Zertifikate und stabile Netzwerknamen beim Austausch erhalten. |
| Gemeinsame Ausführungsdienste | `sandbox`, `sandbox-egress`, `sandbox-llm-gateway` | Aktive Sitzungen vor dem Austausch berücksichtigen; der Spawner braucht Docker-Daemon und passende Workspace-Pfade. |
| Optionale Video-Unterstützung | `bgutil-provider` | Token-Anbieter ohne Startgarantie; sein Ausfall kann Videoabrufe beeinträchtigen. |

Im mitgelieferten Aufbau liegen `tale_app` und `tale_knowledge` in einem Postgres-Dienst mit Alias `knowledge-db`. Separate oder verwaltete Datenbanken sind ebenfalls möglich. Konfiguriere ihre Verbindungen und Sicherungen ausdrücklich. Ein neuer Container zerstört vorhandene Daten nicht automatisch; ein entferntes oder ersetztes Volume kann es tun.

## Kompatible Images festlegen

Setze `VERSION` in der Compose-`.env` auf das geprüfte und getestete Tale-Release. Exportiere denselben Wert in deiner Shell für den separaten Image-Download weiter unten. Verwende für Tale-Images eine gemeinsame Version. Die beiden Dienste mit Upstream-Images haben eigene feste Versionen.

| Dienst | Image |
| --- | --- |
| `platform`, `backend-api`, `backend-worker` | `ghcr.io/tale-project/tale/tale-platform:<version>` |
| `proxy` | `ghcr.io/tale-project/tale/tale-proxy:<version>` |
| `db` | `ghcr.io/tale-project/tale/tale-db:<version>` |
| `sandbox` | `ghcr.io/tale-project/tale/tale-sandbox:<version>` |
| `sandbox-egress` | `ghcr.io/tale-project/tale/tale-sandbox-egress:<version>` |
| `sandbox-llm-gateway` | `ghcr.io/tale-project/tale/tale-sandbox-llm-gateway:<version>` |
| `object-store` | `ghcr.io/tale-project/ops/minio:RELEASE.2025-04-22T22-12-26Z` |
| `bgutil-provider` | `brainicism/bgutil-ytdlp-pot-provider:1.3.1` |

Sitzungscontainer nutzen zusätzlich `ghcr.io/tale-project/tale/tale-sandbox-runtime:<version>`. Setze `SANDBOX_RUNTIME_IMAGE` am Spawner und lade es vor dem Start. Sein lokaler Entwicklungstag reicht auf einem Host ohne vorherigen Build nicht aus. Bei Docker-in-Container oder gemeinsamem Build-Cache brauchst du außerdem die kompatiblen Laufzeit- und Cache-Images aus der [Umgebungsreferenz](https://docs.tale.dev/de/self-hosted/configuration/environment-reference).

## Geheimnisse und öffentliche Adressen vorbereiten

Erzeuge vor dem ersten Start eigene Werte und bewahre sie in deiner Geheimnisverwaltung auf. Übernimm keine Beispielzugangsdaten einer Entwicklungsumgebung in die Produktion.

| Wert | Anforderung |
| --- | --- |
| `BETTER_AUTH_SECRET` | Stabiles Authentifizierungsgeheimnis mit hoher Entropie. |
| `ENCRYPTION_SECRET_HEX` | 32 Bytes als Hexwert, etwa mit `openssl rand -hex 32` erzeugt; für vorhandene verschlüsselte Datenbankwerte erhalten. |
| `DB_PASSWORD` oder externe Datenbankzugangsdaten | Müssen zur tatsächlich verwendeten Datenbankrolle passen. |
| `SANDBOX_TOKEN` | Dasselbe zufällige Token in Backend und Spawner. |
| `SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD` | Dasselbe stabile Geheimnis in Backend und Gateway; ein Gateway ohne Admin-Konto legt eines nur für einen Aufrufer an, der es vorweist. Der Benutzername ist standardmäßig `admin`. |
| `OBJECT_STORE_ACCESS_KEY`, `OBJECT_STORE_SECRET_KEY` | Gültige Speicherzugangsdaten; bei MinIO auf `MINIO_ROOT_USER` und `MINIO_ROOT_PASSWORD` abbilden. |
| `OBJECT_STORE_PUBLIC_ENDPOINT` | Vom Browser erreichbarer Endpunkt, meist `SITE_URL`, wenn Tales Proxy den mitgelieferten Speicher weiterleitet. |
| SOPS-age-Identität | Zum Entschlüsseln deiner verschlüsselten Konfigurationsdateien; siehe [Geheimnisse mit SOPS](https://docs.tale.dev/de/self-hosted/configuration/secrets-with-sops). |

Das Backend gleicht eine umgebungsverwaltete Standard-Objektspeicherverbindung beim Start ab. Eine Datei mit `managedBy: operator` bleibt bewusst unverändert. Geänderte Speicherzugangsdaten verschieben oder verwaisen Dateien nicht automatisch, müssen aber zwischen Backend und Speicher übereinstimmen. Das Gateway behält seinen gespeicherten Passwort-Hash. Stelle das passende Geheimnis wieder her oder nutze dessen Passwortwechselverfahren, statt zur Fehlersuche das Volume zu löschen.

Setze `HOST`, `SITE_URL` und `TLS_MODE` für den öffentlichen Zugang. [TLS und Domains](https://docs.tale.dev/de/self-hosted/configuration/tls-and-domains) erklärt Zertifikate, weitere Ursprünge und Unterpfade.

## Anwendungsebene zusammenstellen

Die drei Rollen teilen sich ein Image. `TALE_ROLE=api` und `TALE_ROLE=worker` wählen Backend-Rollen; beim Webdienst bleibt die Variable ungesetzt. Vergib kein festes `container_name` für Rollen, die du skalieren willst.

```yaml
# Application-tier fragment; add the stores, proxy, and sandbox services.
# No container_name on replicated services.
services:
  platform:
    image: ghcr.io/tale-project/tale/tale-platform:${VERSION}
    env_file: [.env]
    volumes: ['config-data:/app/data:ro']
    restart: unless-stopped
    stop_grace_period: 45s
    healthcheck:
      test:
        [
          'CMD-SHELL',
          'curl -sf http://localhost:3000/api/health && [ -f /tmp/platform-ready ]',
        ]
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 180s
    networks:
      internal:
        aliases: [platform]
  backend-api:
    image: ghcr.io/tale-project/tale/tale-platform:${VERSION}
    environment:
      TALE_ROLE: api
      PORT: '3005'
      TALE_CONFIG_DIR: /app/data
      DATABASE_URL: ${DATABASE_URL:-postgresql://tale:${DB_PASSWORD:?required}@db:5432/tale_app}
      SANDBOX_URL: http://sandbox:8003
      SANDBOX_HTTP_API_BASE_URL: http://backend-api:3005
      OBJECT_STORE_ENDPOINT: ${OBJECT_STORE_ENDPOINT-http://object-store:9000}
    env_file: [.env]
    volumes: ['config-data:/app/data']
    cap_add: [NET_ADMIN]
    restart: unless-stopped
    healthcheck:
      test: ['CMD-SHELL', 'curl -sf http://localhost:3005/ping']
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 30s
    networks:
      internal:
        aliases: [backend-api]
      sandbox:
        aliases: [backend-api]
  backend-worker:
    image: ghcr.io/tale-project/tale/tale-platform:${VERSION}
    environment:
      TALE_ROLE: worker
      TALE_CONFIG_DIR: /app/data
      DATABASE_URL: ${DATABASE_URL:-postgresql://tale:${DB_PASSWORD:?required}@db:5432/tale_app}
      SANDBOX_URL: http://sandbox:8003
      SANDBOX_HTTP_API_BASE_URL: http://backend-api:3005
      OBJECT_STORE_ENDPOINT: ${OBJECT_STORE_ENDPOINT-http://object-store:9000}
    env_file: [.env]
    volumes: ['config-data:/app/data']
    cap_add: [NET_ADMIN]
    restart: unless-stopped
    healthcheck: { disable: true }
    networks: [internal]
volumes:
  config-data:
networks:
  internal:
  sandbox:
    name: tale-sandbox-net
    internal: true
    enable_ipv6: false
```

Einträge unter `environment` haben Vorrang vor `env_file`. Das Beispiel erhält deshalb externe Datenbank- und Objektspeicherwerte, statt interne Adressen zu erzwingen. Nutze in einem Compose-Projekt gesundheitsabhängige Startbedingungen. Bei mehreren Projekten muss dein Orchestrator die Reihenfolge sichern.

## Netzwerknamen und Isolation erhalten

| Adresse | Ziel und Netzwerkanforderung |
| --- | --- |
| `platform` | Webreplikate im internen Anwendungsnetz. Sie erreichen das Backend unter `TALE_BACKEND_URL`, ohne eigene Angabe `http://backend-api:3005`. |
| `backend-api` | API-Replikate in Anwendungs- und Sandbox-Netz, erreichbar auf Port 3005. |
| `knowledge-db` | Wissens-Postgres oder ein Ziel über `KNOWLEDGE_DATABASE_URL`. |
| `object-store` | Mitgeliefertes MinIO im Anwendungsnetz. |
| `sandbox` | Für das Backend erreichbarer Spawner auf Port 8003. |
| `sandbox-egress` | Für Sandbox-Sitzungen erreichbarer Egress-Proxy auf Port 3128. |
| `sandbox-llm-gateway` / `llm-gateway` | Gateway für Backend und Sandbox-Sitzungen auf Port 8080. |
| `bgutil-provider` | Vom Worker erreichbarer Token-Sidecar auf Port 4416. |

Das Sandbox-Netz darf keinen direkten Ausgang erlauben. Der erzeugte Stack nennt es `tale-sandbox-net`. Bei einem anderen Namen müssen `SANDBOX_EGRESS_NETWORK` und das tatsächliche Netz übereinstimmen. Ausgehender Verkehr muss weiterhin über `sandbox-egress` laufen.

Setze am Proxy `BACKEND_UPSTREAM=backend-api:3005`. Für den mitgelieferten Dateispeicher setzt du `OBJECT_STORE_UPSTREAM=object-store:9000` und denselben `OBJECT_STORE_BUCKET` in Proxy und Backend. Veröffentliche die Proxy-Ports 80/443. Datenbanken, Speicherverwaltung, Gateway und Sandbox-APIs bleiben privat. Erhalte eine vertrauenswürdige Client-Weiterleitung bei einem zusätzlichen vorgeschalteten Proxy.

## Dauerhafte Daten und erforderliche Rechte einbinden

| Ressource | Mounts oder Einstellungen |
| --- | --- |
| Organisationskonfiguration | `config-data:/app/data` schreibbar für Backend-Rollen, nur lesbar für `platform`; am Spawner nur lesbar unter `/app/platform-config`. |
| Anwendung und mitgelieferte Wissensdaten | `db-data:/var/lib/postgresql/data`; ein separater Wissensdienst braucht ein eigenes dauerhaftes Volume. |
| Mitgelieferter Objektspeicher | `object-store-data:/data` und MinIO `command: server /data`. |
| Zertifikate und Proxy-Zustand | `caddy-data:/data`, `caddy-config:/config`. |
| Gateway-Zustand | `llm-gateway-data:/app/data`. |
| Spawner | `/var/run/docker.sock` und `/var/lib/tale-sandbox` unter gleichen Host-/Containerpfaden. Docker-Socket-Zugriff erlaubt Kontrolle über den Host-Daemon. |
| Backend-Rollen | `cap_add: [NET_ADMIN]` für den Netzwerkschutz des mitgelieferten Entrypoints. |
| Egress-Dienst | Nach Entfernen aller anderen Rechte der begrenzte Satz `NET_ADMIN`, `DAC_OVERRIDE`, `CHOWN`, `SETUID`, `SETGID`, `NET_BIND_SERVICE` und `KILL`. Ohne `KILL` kann der Root-Supervisor tinyproxy nach dem Wechsel zu `nobody` kein Signal mehr schicken; ein Stopp wartet dann die Karenzzeit ab und endet mit Exit 137, statt sauber auszulaufen. |
| Egress-IPv6 | `sysctls` mit `net.ipv6.conf.all.disable_ipv6: '1'` und `net.ipv6.conf.default.disable_ipv6: '1'`, wie im mitgelieferten Stack. Die Egress-Firewall arbeitet fail-closed: Sie braucht eine funktionierende IPv6-Firewall oder deaktiviertes IPv6 für den Standardwert und jede Schnittstelle, und ein Container kann diese Sysctls über ein schreibgeschütztes `/proc/sys` nicht selbst setzen. Ohne sie startet der Proxy auf einem Kernel ohne das Modul `ip6_tables` nicht; siehe [Sandbox-Infrastruktur](https://docs.tale.dev/de/self-hosted/configuration/environment-reference#sandbox-infrastructure). |
| Postgres-Stopp | `stop_signal: SIGINT`, `stop_grace_period: 60s`, `shm_size: 256mb` im Referenzaufbau. |
| Web- und Spawner-Stopp | 45 Sekunden Stop-Wartezeit für Web, 30 für den Spawner; laufende Arbeit vor dem Stopp koordinieren. |

Behalte `db-backup`, wenn deine Datenbankwerkzeuge nach `/var/lib/postgresql/backup` schreiben. Ein Mount allein plant keine Sicherungen. Ältere Konfigurationsvolumes `convex-data` brauchen eine kontrollierte Übertragung nach `config-data`, keine Löschung. Bewahre die alte Kopie bis zur Prüfung auf.

## Passende Zustandsprüfungen verwenden

| Dienst | Prüfung | Aussage |
| --- | --- | --- |
| `backend-api` | `curl -sf http://localhost:3005/ping` | Prozess lebt; bleibt beim Entleeren erreichbar. |
| `backend-api` | `GET /ready` auf Port 3005 | Backend nimmt neue Arbeit an; getrennt vom Zustand externer Speicher. |
| `platform` | `curl -sf http://localhost:3000/api/health && [ -f /tmp/platform-ready ]` | Webdienst hat den Start abgeschlossen. |
| `backend-worker` | Web-Healthcheck des Images deaktivieren. | Kein HTTP-Server; Jobs und Fortschritt gesondert überwachen. |
| `proxy` | `curl -sf http://127.0.0.1:2020/health` | Proxy-Prozess antwortet. |
| `db` | `pg_isready -U tale && [ -f /tmp/.db_ready ]` | Postgres und Initialisierung bereit; Benutzer anpassen. |
| `object-store` | `mc ready local` | Bereitschaft des mitgelieferten MinIO. |
| `sandbox` | `curl -fsS http://127.0.0.1:8003/health` | Spawner nach Vorbereitung des Laufzeit-Images bereit. |
| `sandbox-egress` | `curl -sS -o /dev/null --max-time 3 --noproxy '*' http://127.0.0.1:3128/` | Der Proxy beantwortet eine Nicht-Proxy-Anfrage selbst (400-Seite); das belegt, dass er ausliefert, ohne externe Webseiten zu erreichen. Den Port nicht mit einer reinen TCP-Verbindung prüfen: tinyproxy protokolliert jedes Verbinden-und-Schließen als Fehler, eine Zeile pro Intervall. |
| `sandbox-llm-gateway` | `wget -q -O /dev/null http://127.0.0.1:8080/health` | Verwendet den vorhandenen Client; das Image enthält kein `curl`. |

Plane genug Zeit für Kaltstarts. Der Download der Sandbox-Laufzeit kann ein für warme Hosts passendes Zeitlimit überschreiten. Eine erfolgreiche Bereitschaftsprüfung belegt weder Dateizugriff noch Modellzugangsdaten oder einen vollständigen Nutzerablauf. Prüfe diese separat.

## Externe Speicher verbinden

Externe Anwendungsdatenbanken verwenden `DATABASE_URL`, externe Wissensdatenbanken `KNOWLEDGE_DATABASE_URL`. Für Letztere brauchst du pgvector und für volle Hybridsuche pg_search. Stelle eine sitzungskompatible Verbindung und bei Bedarf `POSTGRES_CA_FILE` bereit. Verlasse dich nicht darauf, dass ein Transaction-Pooler Tales Sitzungsverhalten erhält.

Setze für externe S3-kompatible Speicher `OBJECT_STORE_*` und den Browserendpunkt ausdrücklich. AWS S3 kann einen leeren benutzerdefinierten Endpunkt nutzen; andere Speicher brauchen gegebenenfalls Path-Style. Richte Objektrechte und Browser-CORS ein und teste Upload und Download. Entferne nur nicht mehr benötigte mitgelieferte Dienste samt `depends_on`-Referenzen. Erhalte alte Volumes bis zur bestätigten Migration.

Andere URLs verschieben keine vorhandenen Zeilen oder Dateien. [Datenresidenz](https://docs.tale.dev/de/self-hosted/configuration/data-residency) erklärt Organisations- und Bereitstellungsoptionen. Externe Speicher brauchen eigene abgestimmte Backups außerhalb der Volume-Archive von `tale backup`.

## Installation starten und abnehmen

Starte Speicher vor abhängigen Diensten und nutze Neustartregeln wie `unless-stopped`. Bereite `VERSION` wie oben beschrieben in der Shell vor und prüfe die vollständige Compose-Datei:

```bash
docker compose config --quiet
docker pull "ghcr.io/tale-project/tale/tale-sandbox-runtime:$VERSION"
docker compose up -d
docker compose ps
docker compose logs --tail=100 backend-api backend-worker
```

Prüfe gesunde Dienste, erfolgreiche Backend-Migrationen und Worker-Fortschritt. Öffne die öffentliche URL, folge [Erster Administrator](https://docs.tale.dev/de/self-hosted/install/first-admin), konfiguriere Anbieter und Embedding-Modell und teste kontrolliert Chat, Upload/Download und Wissenssuche. Werden Harnesses benötigt, prüfe auch eine Sandbox-Sitzung.

Datenbankmigrationen laufen beim Backend-Start. Dein Bereitstellungsablauf muss dabei kompatible Versionen verfügbar halten, bei Migrationsfehlern stoppen, aktive Arbeit vor Austausch entleeren und den Wiederherstellungszustand festhalten. Blue-Green-Koordination, Wiederaufnahme ausstehender Wechsel, automatische Snapshots und Rollback-Prüfungen entstehen nicht allein durch Kopieren der Dienstaufteilung.

## Den Vertrag auf Kubernetes übertragen

[Auf Kubernetes bereitstellen](https://docs.tale.dev/de/self-hosted/install/kubernetes) überträgt diesen Vertrag in Deployments, Services, StatefulSets und NetworkPolicies, stellt den Sandbox-Spawner auf `SANDBOX_BACKEND=kubernetes` um und nennt die Prüfungen, die ein Cluster bestehen muss, bevor du Nutzer zulässt. Diese Seite bleibt die Referenz für die Dienstnamen, Volumes, Prüfungen und Umgebungsvariablen, die die Kubernetes-Objekte nachbilden müssen.

# Deine erste selbst gehostete Instanz starten
Source: https://docs.tale.dev/de/self-hosted/install/quickstart

Starte Tale lokal mit der veröffentlichten CLI, richte deinen Arbeitsbereich ein und sende eine Nachricht. Dafür musst du weder das Repository klonen noch Bun installieren oder die Anwendung bauen. Die CLI lädt die Container-Images herunter und bereitet die Konfiguration vor.

## Den lokalen Rechner vorbereiten

Du brauchst:

- macOS, Linux oder Windows mit PowerShell sowie Docker mit Linux-Containern und Compose. Docker Desktop enthält Compose unter macOS und Windows. Fehlt Docker, bietet `tale dev` Hilfe bei der Installation an.
- Netzwerkzugriff auf GitHub für die CLI und auf Container-Registries für die Images. Beim ersten Start werden mehrere GB heruntergeladen; plane Platz für Images und deine Daten ein.
- Zugangsdaten für einen unterstützten Modellanbieter, damit du die erste Antwort testen kannst. Dein Konto kannst du schon vorher erstellen und die Anwendung erkunden.

Auf ARM64, auch auf Apple Silicon, benötigt der mitgelieferte Objektspeicher eine amd64-Emulation. Docker Desktop bringt sie mit; auf einem eigenständigen Linux-Docker-Host musst du sie separat einrichten. Prüfe vor dem Start auf ARM64 Linux die [Architekturanforderungen](https://docs.tale.dev/de/self-hosted/install/cli-install#bevor-du-beginnst).

Der HTTPS-Port ist standardmäßig `443`; der Sandbox-Dienst verwendet außerdem `127.0.0.1:8003`. Halte die Instanz privat, bis du ihr Inhaberkonto erstellt hast.

## CLI installieren

Wähle den Installer für dein Betriebssystem:

<Tabs>

<Tab title="macOS / Linux">

```bash
curl -fsSL https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.sh | bash
```

</Tab>

<Tab title="Windows (PowerShell)">

```powershell
irm https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.ps1 | iex
```

</Tab>

</Tabs>

Prüfe die Installation im selben Terminal mit `tale --version`. Fehlt der Befehl, folge den `PATH`-Hinweisen des Installers und öffne bereits laufende Terminals neu. Die [CLI-Installation](https://docs.tale.dev/de/self-hosted/install/cli-install) beschreibt feste Versionen und eigene Installationsverzeichnisse.

Prüfe mit `tale --help`, ob `doctor` verfügbar ist. Fehlt der Befehl, prüfe Docker und Compose mit `docker info` und `docker compose version`. Falls verfügbar, untersucht `tale doctor` zusätzlich die Container-Architektur und lokale Ports, ohne Software zu installieren oder Dateien zu ändern. Folge den angezeigten Hinweisen; ein erfolgreicher Check bestätigt weder Image-Downloads noch den Modellzugriff.

## Initialisieren und starten

Wähle einen Ort für dein Projekt und führe dort diese Befehle aus:

```bash
tale init my-project
cd my-project
tale dev
```

`tale init` erstellt das Projekt und eine private `.env` mit erzeugten Geheimnissen. Sichere diese Datei und ihre Verschlüsselungsschlüssel. Lass Docker in der Sandbox bei der entsprechenden Frage standardmäßig deaktiviert, solange deine Agenten Docker nicht benötigen: Das Aktivieren erlaubt verschachteltes Docker mit Privilegien.

`tale dev` startet die Container und zeigt die Adresse an, sobald die Anwendung bereit ist. Lass den Befehl während der ersten Image-Downloads und der Datenbankeinrichtung laufen. Öffne die angezeigte URL, normalerweise `https://localhost`. Das lokale Zertifikat ist selbstsigniert. Prüfe vor dem Bestätigen der Browserwarnung, ob die Adresse zu deiner eigenen Instanz gehört.

<Note>

Das erzeugte Verzeichnis `default/` enthält Katalogbeispiele und automatisch installierte Einträge. Für diesen ersten Start musst du es nicht bearbeiten. Seine `README.md` erklärt, welche Konfigurationsänderungen eine Organisation beeinflussen.

</Note>

## Inhaber erstellen und Antwort prüfen

1. Erstelle im Einrichtungsassistenten dein Konto und benenne die Organisation. Das erste Konto wird ihr **Inhaber**. [Erstes Inhaberkonto](https://docs.tale.dev/de/self-hosted/install/first-admin) beschreibt die Inhaberrolle und bereits vorhandene Konten.
2. Öffne nach der Einrichtung **Einstellungen > KI-Anbieter** und füge unterstützte Zugangsdaten hinzu. Auch die Abschlussseite der Einrichtung führt zu den Anbietereinstellungen. [KI-Anbieter](https://docs.tale.dev/de/platform/admin/providers) beschreibt die Felder und unterstützten Anmeldemethoden.
3. Öffne **Start**, wähle **Neuer Chat** und ein verfügbares Modell. Sende eine kurze Anfrage wie „Schreibe eine Checkliste mit drei Punkten für eine Besprechung.“ Warte, bis die Antwort vollständig ist.

Eine vollständige Antwort bestätigt, dass Konto, Anbieter und gewähltes Modell zusammen funktionieren. Ist die Modellliste leer oder schlägt die Anfrage fehl, folge der Fehlerhilfe im Anbieterleitfaden. [Deine erste Nachricht senden](https://docs.tale.dev/de/get-started/quickstart) zeigt, wie du fortfährst und die Unterhaltung wiederfindest. Sobald du Projektarbeit delegieren möchtest, [erstelle deinen ersten Agenten](https://docs.tale.dev/de/tutorials/editor/first-agent-end-to-end).

## Stoppen und später fortfahren

Drücke im Terminal mit `tale dev` die Tastenkombination `Ctrl-C`, um die Instanz im Vordergrund zu stoppen. Starte später im selben Projektverzeichnis erneut `tale dev`; die bisherigen Daten bleiben erhalten.

Prüfe `tale dev --help`, bevor du die folgenden Befehle für den Hintergrundbetrieb nutzt. Fehlt dort `--stop`, lass `tale dev` im Vordergrund laufen und stoppe es mit `Ctrl-C`.

```bash
tale dev --detach
tale dev --stop
```

Das Stoppen erhält Projekt, Geheimnisse und dauerhafte Daten. Verwende weiterhin dasselbe Projektverzeichnis; ein neues Projekt startet eine separate Instanz.

## Startprobleme beheben

| Symptom | Nächste Aktion |
| --- | --- |
| `tale` fehlt | Prüfe Installationsverzeichnis und `PATH`; öffne unter Windows ein neues Terminal. |
| Docker startet nicht | Öffne Docker Desktop oder starte den Daemon. Prüfe im selben Terminal `docker info` und versuche es dann erneut. |
| Compose fehlt | Prüfe `docker compose version`; installiere das Compose-Plugin oder aktualisiere Docker Desktop. |
| Ein Image-Download ist langsam oder scheitert | Prüfe die gemeldeten Registry- oder Netzwerkfehler und den freien Speicher. Starte nach der Korrektur `tale dev` im selben Verzeichnis erneut. |
| Der HTTPS-Port ist belegt | Prüfe, welcher Prozess Port `443` belegt. Gib bei der veröffentlichten CLI-Version v0.5.70 diesen Port frei, bevor du es erneut versuchst. |
| Port `8003` ist belegt | Stoppe die andere lokale Tale-Instanz oder den Dienst auf diesem Port. `--port` ändert nur HTTPS. |
| Ein Container startet ständig neu | Führe `tale status` aus, danach `tale logs backend-api --tail 100` oder `tale logs platform --tail 100`. Suche die Ursache in den Protokollen des gemeldeten Dienstes. |
| Statt der Einrichtung erscheint die Anmeldung | Es gibt bereits ein Konto. Melde dich damit an; setze die Daten nicht zurück, um die Einrichtung zu wiederholen. |
| Die App öffnet sich ohne Modellantwort | Prüfe Zugangsdaten und gewähltes Modell unter **Einstellungen > KI-Anbieter**. |

Versuche es erneut, sobald die gemeldete Ursache behoben ist. Behalte `.env` und die Datenvolumes. Bei anhaltenden Fehlern hilft die [Fehlerbehebung](https://docs.tale.dev/de/self-hosted/operate/observability/troubleshooting). Nenne bei einer Supportanfrage CLI-Version und relevanten Fehler; entferne Zugangsdaten aus Protokollen, bevor du sie teilst.

## Eine produktive Bereitstellung vorbereiten

`tale deploy` stellt die Projektkonfiguration auf dem gewählten Docker-Host bereit. Entwicklung und Bereitstellung verwenden getrennte Datenvolumes: Das lokale Konto, Chats und hochgeladene Dateien werden dabei nicht übertragen. Bereite DNS, TLS, Backups und Zugriffskontrollen vor, bevor du dein Team hinzufügst.

Lies [TLS und Domains](https://docs.tale.dev/de/self-hosted/configuration/tls-and-domains), [Backups und Wiederherstellung](https://docs.tale.dev/de/self-hosted/operate/backups-and-restore) und [Absicherung](https://docs.tale.dev/de/self-hosted/operate/security/hardening). Falls du die Dienstdefinitionen selbst verwalten musst, nutze [Compose selbst betreiben](https://docs.tale.dev/de/self-hosted/install/own-compose).

# Backups und Wiederherstellung
Source: https://docs.tale.dev/de/self-hosted/operate/backups-and-restore

Für eine wiederherstellbare Tale-Instanz reicht ein Datenbankarchiv nicht aus. Bewahre Dateien, Organisationskonfiguration, Bereitstellungsordner und Entschlüsselungsschlüssel zusammen mit der Information auf, welche Version die Daten geschrieben hat. Lege zuerst fest, wie viel Datenverlust und welche Wiederherstellungsdauer du akzeptieren kannst. Prüfe dann, ob Sicherungsplan und Wiederherstellung diese Ziele erfüllen.

Diese Anleitung beschreibt Docker-Volume-Snapshots der Workspace-CLI. Wenn du Compose selbst verwaltest, muss dein Sicherungsverfahren dieselben Speicher abdecken. Externe Datenbanken und Buckets brauchen eigene, zeitlich abgestimmte Backups.

## Einen leeren Wiederherstellungshost vorbereiten

Hole den ursprünglichen Workspace zurück und prüfe, ob deine Docker-Verbindung auf den Wiederherstellungshost zeigt. Lass den Stack gestoppt. Ersetze unten `your-project-id` durch die ursprüngliche ID aus `tale.json`. Für einen Entwicklungssnapshot verwende stattdessen `TALE_RESTORE_PREFIX="${TALE_RESTORE_PROJECT}-dev_"`. Produktiv- und Entwicklungsdaten haben getrennte Namensräume. Sind beide vorhanden, wählt die CLI zuerst den produktiven.

```bash
TALE_RESTORE_PROJECT=your-project-id
TALE_RESTORE_PREFIX="${TALE_RESTORE_PROJECT}_"
docker volume create --label "project=$TALE_RESTORE_PROJECT" "${TALE_RESTORE_PREFIX}config-data"
docker volume create --label "project=$TALE_RESTORE_PROJECT" "${TALE_RESTORE_PREFIX}backups"
docker volume inspect "${TALE_RESTORE_PREFIX}backups"
```

Damit entstehen Konfigurations- und Backup-Volume, ohne ein Backend zu starten oder Migrationen auszuführen. Spiele mit deinem Sicherungssystem den vollständigen gesicherten Inhalt von `backups` in dieses Volume ein. Der angezeigte Einhängepunkt gehört zum Docker-Host, der auch entfernt sein kann. Behalte Verzeichnisstruktur und Manifeste der Snapshots bei. `tale restore` muss anschließend den erwarteten Snapshot auflisten. Bei der eigentlichen Wiederherstellung erstellt die CLI nach der Snapshot-Prüfung weitere fehlende Ziel-Volumes.

## Umfang des Snapshots prüfen

`tale backup` erfasst vorhandene Projekt-Volumes aus dieser Liste:

| Volume | Enthaltene Daten |
| --- | --- |
| `db-data` | Anwendungsdaten und beim mitgelieferten Ein-Host-Stack auch die Wissensdatenbank. |
| `knowledge-db-data` | Die separate Wissensdatenbank, wenn dieses Volume vorhanden ist, etwa bei Compose aus dem Quellcode. |
| `config-data` | Organisationskonfiguration, unterstützte Geheimnis-Begleitdateien und Branding. In Postgres gespeicherte Anbieterzugangsdaten gehören zur Datenbanksicherung. |
| `object-store-data` | Hochgeladene Dateien und erzeugte Medien, wenn der Bereitstellungsstandard den mitgelieferten Speicher verwendet. |
| `caddy-data`, `caddy-config` | Zertifikate und Proxy-Zustand. |
| `llm-gateway-data` | Der Speicher des Modell-Gateways: Admin-Konto, Anbieterschlüssel, Sitzungsschlüssel mit ihren Budgets und Ausgaben sowie das Anfrageprotokoll. |

Für jedes erfasste Volume enthält der Snapshot ein Archiv und eine SHA-256-Prüfsummendatei. `manifest.json` wird zuletzt geschrieben und hält die Plattformversion fest, sofern sie ermittelt werden kann. Ein Verzeichnis ohne Manifest ist unvollständig: Es erscheint nicht in der Wiederherstellungsliste und kann bei der Rotation entfernt werden, sobald ein neuerer vollständiger Snapshot vorliegt. Snapshots, die entstanden sind, bevor die CLI den Speicher des Gateways erfasste, enthalten kein Archiv von `llm-gateway-data`.

Bewahre zusätzlich den Ordner mit `tale.json`, seine `.env` und separat eingebundene Schlüsseldateien auf. Dazu gehören insbesondere `ENCRYPTION_SECRET_HEX` und die age-Identität für SOPS-Dateien. Sandbox-Arbeitsverzeichnisse sind nicht Teil dieser Snapshot-Liste. Nimm sie bei Bedarf in deinen eigenen Sicherungsplan auf.

<Warning>

Externe Postgres-Daten werden nicht erfasst, auch wenn ein ungenutztes lokales Datenbank-Volume im Snapshot auftaucht. Die CLI warnt nicht vor dieser Datenbankkonfiguration. Externe Buckets liegen ebenfalls außerhalb des Snapshots; die CLI meldet einen umgeleiteten Standard-Bucket oder gefundene organisationsspezifische Buckets. Prüfe die Speicherverbindungen jeder Organisation, bevor du die Sicherung als vollständig bewertest.

</Warning>

## Snapshot erstellen und prüfen

Führe diese Befehle im vorgesehenen Bereitstellungsordner aus:

```bash
tale status
tale backup
tale restore
```

`backup` zeigt das Ergebnis an. `restore` ohne ID listet nur vorhandene Snapshots auf, einschließlich der erfassten Version und eines Hinweises, wenn Dateien oder der Speicher des Gateways fehlen. Halte die Snapshot-ID zusammen mit den IDs externer Backups fest.

Während ein Volume archiviert wird, pausiert der Sicherungsprozess die Container, die es verwenden. Uploads, Downloads, Datenbankarbeit und Modellaufrufe über das Gateway können während der jeweiligen Pause warten müssen. Die Dauer hängt von Datenmenge und Durchsatz ab. Docker meldet einen pausierten Container bis zu seiner nächsten erfolgreichen Zustandsprüfung als `unhealthy`. Nach jedem Archiv wartet der Sicherungsprozess deshalb, bis jeder Container, der vor der Pause gesund war, wieder `healthy` meldet; das dauert meist ein Intervall der Zustandsprüfung. Erholt sich ein Container nicht innerhalb der Wiederholungen, die seine Zustandsprüfung zulässt, schlägt die Sicherung fehl. Die Archive bilden einen absturzähnlichen Zustand je Volume ab, keine atomare Transaktion über alle Speicher. Für einen abgestimmten Wiederherstellungspunkt halte Schreibzugriffe und geplante Arbeit an oder nutze ein Wartungsfenster, das auch externe Speicher umfasst.

Ein `tale deploy` mit Versionswechsel oder einer Überschreibung der Host-Konfiguration erstellt vor Änderungen einen Snapshot. Schlägt die Sicherung fehl, bricht die Bereitstellung ab. `--skip-backup` umgeht diesen Schutz. Verwende die Option nur, wenn dein Wiederherstellungsplan die erforderliche Sicherung bereits bereitstellt.

## Eine Kopie außerhalb des Hosts aufbewahren

Snapshots liegen im Docker-Volume `backups` des Projekts. Ein Host- oder Plattenausfall kann laufende Daten und lokale Snapshots zugleich zerstören. Übertrage vollständige Snapshots, Workspace-Konfiguration und Schlüssel in dein geschütztes externes Sicherungssystem. Tale übernimmt diesen Upload nicht.

Ermittle das Volume mit der Projekt-ID aus `tale.json`:

```bash
docker volume inspect <project-id>_backups
```

Der Mount-Pfad gehört zum Docker-Host, der auch eine VM oder ein entfernter Rechner sein kann. Richte deinen Backup-Agenten dort ein; der Pfad muss nicht auf deinem Arbeitsplatzrechner existieren. Prüfe, ob die externe Kopie `manifest.json`, alle darin genannten Archive und deren Prüfsummendateien enthält.

Die lokale Rotation behält die neuesten fünf Snapshots **und** alle Snapshots der letzten 14 Tage. Gelöscht wird nur, was außerhalb beider Grenzen liegt. `BACKUP_KEEP_COUNT` und `BACKUP_KEEP_DAYS` in `.env` ändern diese Grenzen. Die Aufbewahrung außerhalb des Hosts konfigurierst du separat.

## Daten und passende Version wiederherstellen

<Warning>

Die Wiederherstellung ersetzt den Inhalt der enthaltenen Daten-Volumes. Sichere den aktuellen Zustand, falls du ihn noch brauchen könntest, und prüfe den Ziel-Workspace. Halte Nutzer und geplante Integrationen von der Wiederherstellungsumgebung fern, bis sie abgenommen ist.

</Warning>

1. Hole den vollständigen Snapshot, Bereitstellungsordner, passende Schlüssel und Backups externer Speicher zurück. Bereite einen neuen Host zuerst wie oben beschrieben vor.
2. Wähle mit `tale restore` eine ID und lies die Plattformversion ab. Ist sie unbekannt, ermittle sie vor dem Anwendungsstart aus deinen Bereitstellungsunterlagen.
3. Stelle bei angehaltenem Stack wieder her. `--stop` hält laufende Projektcontainer an. Danach prüft die CLI die Archiv-Prüfsummen und fragt vor dem Ersetzen der Daten nach Bestätigung. Nutze dafür deine aktuelle CLI, bevor Schritt 5 sie wechselt: Eine CLI aus der Zeit vor der Erfassung des Gateway-Speichers überspringt dessen Archiv.

```bash
tale restore <snapshot-id> --stop
```

4. Stelle externe Datenbanken und Buckets bei weiterhin gesperrtem Zugriff auf den abgestimmten Zeitpunkt zurück. Ein als `without blobs` markierter Snapshot lässt das vorhandene lokale Datei-Volume unangetastet. Einer mit der Markierung `without gateway` lässt `llm-gateway-data` unangetastet und kann das Gateway nicht auf seinen Speicher von vor einem Gateway-Upgrade zurückbringen; die CLI warnt davor, bevor sie nach der Bestätigung fragt. Wurde das Gateway nach diesem Snapshot aktualisiert, spiele vor dem nächsten Schritt deine eigene Kopie des Volumes zurück, wie unter [Upgrades](https://docs.tale.dev/de/self-hosted/operate/upgrades) beschrieben.
5. Wähle die im Snapshot vermerkte Version und stelle sie einschließlich der zustandsbehafteten Dienste bereit:

```bash
tale update --version <snapshot-platform-version>
tale deploy --stop
tale status
```

Die Version ist entscheidend: Ein neueres Backend kann direkt beim Start Migrationen anwenden. Eine Datenwiederherstellung mit einem beliebigen aktuellen Image stellt daher nicht den dokumentierten Zustand wieder her. Ältere Konfigurationsarchive namens `convex-data` spielt die CLI in das heutige Volume `config-data` ein.

## Wiederherstellung vor der Freigabe nachweisen

Melde dich in einer isolierten Übung an, öffne einen bekannten Chat, lade eine ältere Datei herunter, prüfe die Organisationskonfiguration und führe eine kontrollierte Wissenssuche aus. Prüfe den Zugriff auf Anbieterzugangsdaten und externe Speicher, ohne produktive Benachrichtigungen oder Automatisierungen auszulösen. Halte den Zeitraum verlorener Daten, die Wiederherstellungsdauer und alle manuellen Schritte fest.

Wiederhole die Übung nach wesentlichen Speicher-, Schlüssel- oder Bereitstellungsänderungen und in dem Abstand, den deine Wiederherstellungsziele erfordern. [Upgrades](https://docs.tale.dev/de/self-hosted/operate/upgrades) erklärt die Versionswahl. [Fehlerbehebung](https://docs.tale.dev/de/self-hosted/operate/observability/troubleshooting) hilft, wenn ein wiederhergestellter Dienst nicht betriebsbereit wird.

# Den betroffenen Dienst finden
Source: https://docs.tale.dev/de/self-hosted/operate/container-architecture

Grenze eine Störung anhand der Dienstzuständigkeit ein, bevor du Container änderst. Der mitgelieferte Stack fasst Anwendungs- und Wissensdatenbank in `db` zusammen; Compose aus dem Quellcode kann `knowledge-db` separat betreiben. Prüfe deinen tatsächlichen Aufbau mit `tale status` oder der Dienstübersicht deines Orchestrators.

## Die ersten Protokolle auswählen

| Symptom | Hier beginnen | Danach prüfen |
| --- | --- | --- |
| Öffentliche URL oder TLS scheitert | `proxy` | DNS, Zertifikatszustand, öffentliche Ports und Erreichbarkeit der Zieldienste. |
| Die Oberfläche lädt nicht | `platform`, dann `proxy` | Web-Zustand, statische Dateien und gewählte Bereitstellungsversion. |
| Oberfläche lädt, Anmeldung oder Datenabfragen scheitern | `backend-api` | API-Zustand, Datenbankzugriff, Anfragefehler und Proxy-Routen. |
| Jobs, geplante Automatisierungen oder Importe kommen nicht weiter | `backend-worker` | Warteschlange, Job-Fehler, Zugangsdaten und benötigte Speicher. |
| Lesen oder Schreiben scheitert an vielen Stellen | `db` oder die externe Anwendungsdatenbank | Verbindung, Plattenplatz, Sperren und Datenbankprotokolle. |
| Dateien lassen sich nicht hoch- oder herunterladen | `backend-api`, danach `object-store` oder externer Bucket | Aufgelöste Organisationsverbindung, Zugangsdaten, öffentlicher Endpunkt und Browser-CORS. |
| Ein Harness startet nicht oder erreicht sein Modell nicht | `sandbox`, `sandbox-llm-gateway` | Sitzungserstellung, Gateway-Anmeldung, Modellverfügbarkeit und Laufzeit-Image. |
| Sandbox-Netzzugriff oder Seitenrendering scheitert | `sandbox-egress`, `sandbox` | Zielhost, erlaubte Ports, Egress-Regeln und Sitzungsprotokolle. |
| Videotranskript wird nicht abgerufen | `backend-worker`, `bgutil-provider` | Videozugriff, Extraktionsfehler, konfigurierter Proxy und Browsersitzungsstatus. |

Nutze logische Dienstnamen mit `tale logs <service>`. Für deinen eigenen Compose-Stack gilt `docker compose logs --tail=200 <service>`. Erzeugte Containernamen können Projekt, Farbe und Replikatnummer enthalten.

## Einer interaktiven Chatanfrage folgen

1. Der Browser erreicht `proxy`. Webdateien gehen an `platform`, Anwendungs- und Anmeldeanfragen an `backend-api`.
2. Die API prüft Sitzung und Organisation, ermittelt Modell und Zugangsdaten und führt den interaktiven Turn aus. Fortschritt wird in der Anwendungsdatenbank gespeichert.
3. Der Browser liest Fortschritt über den Stream-Endpunkt des Chats. `/events` liefert Hinweise zum erneuten Laden von Daten und enthält nicht den Token-Stream.
4. Wissenswerkzeuge verwenden die Wissensverbindung der anfragenden Organisation. Originaldateien werden über deren Speicherkonfiguration gelesen.
5. Ein Turn mit Coding-Harness benötigt eine Sandbox-Sitzung und das Modell-Gateway. Eingereihte Aufgaben, Workflow-Agent-Jobs und REST-Chat-Turns können außerdem Worker benötigen.

Ein Worker-Ausfall hat daher einen anderen Umfang als ein API-Ausfall. Daraus folgt aber nicht, dass sämtliche Chat- oder Agentenarbeit weiterläuft. Prüfe Einstiegspunkt und Ausführungstyp des betroffenen Ablaufs. Sichere den ursprünglichen Fehler, bevor du einen Turn wiederholst, der Tokens verbrauchen oder externe Aktionen ausführen könnte.

## Abhängigkeiten der Sandbox verstehen

`sandbox` ist ein Spawner mit Zugriff auf den Docker-Daemon des Hosts. Er erstellt vorübergehende Container aus dem festgelegten Sandbox-Runtime-Image und bindet deren Arbeitsverzeichnisse ein. Diese Sitzungen verwenden ein isoliertes Netzwerk: Webanfragen laufen über `sandbox-egress`, Modellaufrufe über den begrenzten Sitzungszugriff des Gateways.

Die Laufzeit stellt auch Chromium und Playwright für Seitenrendering und Dokumenterzeugung bereit. Eine funktionierende Weboberfläche beweist daher nicht, dass die Ausführungsebene funktioniert. Prüfe Image-Verfügbarkeit, Workspace-Mounts, gemeinsames Sandbox-Token und Gateway-Zugangsdaten, bevor du ein einzelnes Skript untersuchst.

Der Egress-Dienst blockiert private Adressen und Metadatenziele und kann eine Hostnamen-Freigabeliste erzwingen. Ein ausgefallener Ausgang kann Verweigerungen oder Netzwerkfehler verursachen; die genaue Meldung hängt von der Operation ab. [Härtung](https://docs.tale.dev/de/self-hosted/operate/security/hardening) beschreibt die Regeln, [Compose selbst betreiben](https://docs.tale.dev/de/self-hosted/install/own-compose) die nötigen Rechte und Mounts.

## Reparaturen des Wissensindex erkennen

Ein beschädigter BM25-Index kann Importe scheitern lassen, obwohl die Dokumenttabellen noch lesbar sind. Das Backend prüft Wissensindizes mit `pdb.verify_index`. Ein Advisory Lock koordiniert Reparaturversuche pro Datenbank. Organisationsspezifische Datenbanken werden bei ihrer ersten Verwendung geprüft.

| Ergebnis | Verhalten des Backends | Deine Reaktion |
| --- | --- | --- |
| Fehlerfrei | Normal weiterarbeiten. | Keine Reparatur nötig. |
| Beschädigter Index bis `KNOWLEDGE_INDEX_REPAIR_INLINE_MAX_BYTES` | Direkt neu aufbauen und erneut prüfen; die Standardgrenze beträgt 1 GiB. | Mit längerem Start rechnen und das Endergebnis prüfen. |
| Größerer beschädigter Index | Gleichzeitigen Neuaufbau im Hintergrund einplanen; betroffene Indexierung kann mit entsprechendem Grund warten. | Worker-Fortschritt und abschließende Prüfung beobachten. |
| Reparatur scheitert oder Zustand bleibt ungeklärt | Fehler festhalten; betroffene Korpusoperationen können unverfügbar bleiben. | Ursache, Datenbankrechte und Speicherzustand vor einer manuellen Reparatur prüfen. |

Reparaturen können die Audit-Aktionen `knowledge_index_repaired`, `knowledge_index_rebuild_scheduled` oder `knowledge_index_repair_failed` und Admin-Benachrichtigungen auslösen. Ein fehlgeschlagener Neuaufbau beweist keinen Verlust der Quelldokumente. Ein erfolgreicher Neuaufbau ersetzt kein Datenbank-Backup.

`KNOWLEDGE_INDEX_REPAIR_DISABLED=1` schaltet die automatische Prüfung ab und behebt keine Beschädigung. Wiederkehrende Schäden nach Neustarts erfordern eine Untersuchung des Herunterfahrens und des Speichers. Bevorzuge reguläres Stoppen mit der eingestellten Wartezeit statt erzwungenem Beenden. [Fehlerbehebung](https://docs.tale.dev/de/self-hosted/operate/observability/troubleshooting) enthält die lesende Indexprüfung und Hinweise zur Wiederherstellung.

# Betrieb überwachen und Störungen bearbeiten
Source: https://docs.tale.dev/de/self-hosted/operate/observability/operations

Überwache die Aufgaben, die Nutzer abschließen müssen, ebenso wie die darunterliegenden Dienste. Eine erfolgreiche HTTP-Prüfung beweist nicht, dass Anmeldung, Dateidownload, Wissenssuche oder Automatisierung funktionieren. Lege die Dringlichkeit anhand der Auswirkungen auf deine Instanz fest und gib jedem Alarm einen Verantwortlichen und ein Wiederherstellungsverfahren.

[Observability konfigurieren](https://docs.tale.dev/de/self-hosted/configuration/observability-config) erklärt Endpunkte und Zugriffstoken. [Prometheus und Grafana](https://docs.tale.dev/de/self-hosted/operate/observability/prometheus-grafana) zeigt ein Beispiel für die Erfassung.

## Signale mit einer sinnvollen Reaktion wählen

| Signal | Untersuchung | Wann eskalieren? |
| --- | --- | --- |
| Öffentliche URL, Zertifikat oder Anmeldung schlägt fehl | Prüfe den öffentlichen Zugang von außerhalb des Hosts, danach Proxy- und Backend-Protokolle. | Nutzer erreichen einen benötigten Dienst nicht oder ein Zertifikat läuft ohne funktionierende Erneuerung bald ab. |
| Mehr 5xx-Antworten im Backend | Vergleiche `tale_backend_http_requests_total` nach `route` und `status` mit der betroffenen Aktion. | Fehler betreffen aktive Nutzer oder wichtige Integrationen. |
| Ein Speicher ist nicht erreichbar | Prüfe `tale_backend_store_up` und die Überwachung des Speichers selbst. | Benötigte Daten, Suche oder Dateizugriffe sind blockiert. |
| Wartende oder fehlgeschlagene Jobs häufen sich | Prüfe `tale_backend_jobs{state=...}`, Worker und beispielhafte Lauf-Fehler. | Der Rückstand baut sich nicht ab oder eine Frist ist gefährdet. |
| Speicherplatz oder freie Verbindungen werden knapp | Nutze Host- und Datenbanküberwachung; Tale liefert nicht alle diese Metriken. | Handle mit genug Vorlauf, um Kapazität zu schaffen oder die Ursache zu beseitigen. |
| Eine geplante Sicherung oder Kopie fehlt | Prüfe Backup-Job, vollständiges Manifest und externes Ziel. | Der maximal zulässige Datenverlust wird überschritten. |
| Anbieter drosselt oder verweigert Anfragen | Lies Anbieterantwort und Lauf-Fehler; prüfe Kontingent, Zugangsdaten und Anbieterstatus. | Benötigte Arbeit scheitert oder wartet länger als erlaubt. |

Ein Alarm bei 80 % Plattenbelegung kann ein Ausgangspunkt sein. Wachstumsrate und benötigte Reaktionszeit sind jedoch aussagekräftiger als ein pauschaler Prozentwert. Eine Störung der Wissenssuche kann für ein Team kritisch sein. Verschiebe sie nicht automatisch, nur weil die Oberfläche noch lädt.

## Den passenden Prüfendpunkt wählen

Verwende diese Pfade auf der öffentlichen Origin einer Produktionsinstallation hinter dem mitgelieferten Proxy:

| Pfad | Was eine erfolgreiche Antwort belegt |
| --- | --- |
| `/health` | Caddy antwortet mit `OK`. Der Endpunkt bleibt beim Neustart der Plattform erreichbar. |
| `/api/health` | Der Webprozess der Plattform beantwortet seine Lebenszeichenprüfung. |
| `/status.json` | Der öffentliche Abhängigkeitsbericht ist abrufbar. Prüfe die Bewertung der einzelnen Komponenten; Ergebnisse werden fünf Sekunden zwischengespeichert. |
| `/status` | Derselbe Verfügbarkeitsbericht als lesbare Webseite. |

Prüfe neben dem HTTP-Status den erwarteten Antwortinhalt. Ein unbekannter Frontend-Pfad wie `/healthz` kann die App-Hülle mit `200` zurückgeben; das ist kein Zustandsbericht. [Statusseite](https://docs.tale.dev/de/develop/status-page) beschreibt das Antwortformat.

## Aussagekraft der Metriken verstehen

Das Backend liefert Prozessmetriken, Anzahl und Dauer von HTTP-Antworten, Job-Zähler, laufende Generierungen, offene Hinweis-Streams, den Drain-Zustand und die Speichererreichbarkeit. Prüfe die tatsächlich ausgegebenen Zeitreihen deiner Version, bevor du Alarme darauf aufbaust.

- `tale_backend_store_up` prüft die **Bereitstellungsstandards** für Anwendungsdatenbank, Wissensdatenbank und Bucket. Organisationsspezifische Verbindungen brauchen eine eigene Überwachung.
- Speicherprüfungen werden 30 Sekunden zwischengespeichert. Eine Bucket-Antwort `403` gilt als erreichbar, weil dem Schlüssel lediglich das Auflisten fehlen kann. Der Wert `1` beweist nicht, dass sich ein bestimmtes Objekt hoch- oder herunterladen lässt.
- `/ready` beschreibt die Bereitschaft für einen Rollout. Externe Speicher fließen nicht ein; ein bereites Replikat kann daher von einem ausgefallenen Speicher abhängen.
- Die öffentliche Backend-Metrik-URL kann verschiedene API-Replikate erreichen. Prozessmetriken beschreiben das antwortende Replikat. Job- und Generierungszähler lesen gemeinsamen Datenbankzustand. Addiere diese gemeinsamen Zähler nicht so, als hätte jedes Replikat eine eigene Warteschlange.

Prüfe die Lücken mit einem kontrollierten Ablauf: Melde dich mit einem Überwachungskonto an, lies einen bekannten Datensatz und teste die benötigte Datei- oder Wissensfunktion. Nutze dafür einen eigenen Bereich und vermeide Versandaktionen oder andere externe Änderungen.

## Latenzziele von Messwerten trennen

Tale stellt `tale_sla_target_seconds` und eine Regelvorlage unter `/metrics/sla-rules` bereit. Die aktuellen Ziele sind im Mittel 1 Sekunde bis zum ersten Token über 30 Minuten sowie 40 Sekunden für lange Operationen über 6 Stunden. Das sind Zielwerte, keine Messwerte und keine Zusage, dass deine Instanz sie erreicht.

Die erzeugten Regeln erwarten Histogramme namens `tale_dialog_ttft_seconds` und `tale_long_operation_seconds`. Das Backend liefert diese beiden Latenzreihen nicht automatisch. Sein HTTP-Histogramm misst die Anfragebearbeitung; das entspricht weder der Zeit bis zum ersten Token noch der vollständigen Dauer eingereihter Arbeit. Instrumentiere die tatsächlichen Start- und Endpunkte der Operation und prüfe vorhandene Messwerte, bevor du diese Regeln aktivierst. Eine leere Abfrage bedeutet fehlende Daten, keine bestandene Latenzprüfung.

## Vor Zustandsänderungen untersuchen

1. Halte betroffene Organisation, URL oder Aktion, Fehlercode, Zeitraum und Ausmaß fest. Prüfe, ob sich der Fehler ohne Datenänderung nachvollziehen lässt.
2. Lies `tale status` und `tale logs <service>`. Bei selbst verwalteten Bereitstellungen verwendest du den Compose-Dienstnamen mit `docker compose ps` und `docker compose logs --tail=200 <service>`.
3. Gleiche Netzwerkfehler im Browser mit API-/Worker-Protokollen und dem Speicher- oder Anbieterstatus ab. Sichere relevante Protokolle, bevor ein Neustart sie rotiert oder Zusammenhänge verdeckt.
4. Behebe die ermittelte Ursache: Kapazität, Verbindung, Konfiguration, Zugangsdaten oder Prozessausfall. Erstelle betroffene Container nach Änderungen an Umgebungswerten neu; `docker compose restart` behält deren bisherige Umgebung.
5. Prüfe nach der Wiederherstellung die ursprüngliche Aktion und zugehörige wartende Arbeit. Halte fest, welche unterbrochenen Anfragen oder Jobs ausdrücklich wiederholt werden müssen, und ergänze den Störungsverlauf.

Eskaliere, sobald dein Störungsprozess es verlangt. Ein Neustart kann laufende Arbeit unterbrechen. Er ist weder ein verpflichtender Diagnoseschritt noch ein Grund, die Eskalation aufzuschieben. [Fehlerbehebung](https://docs.tale.dev/de/self-hosted/operate/observability/troubleshooting) ordnet häufige Symptome gezielteren Prüfungen zu.

# Prometheus und Grafana
Source: https://docs.tale.dev/de/self-hosted/operate/observability/prometheus-grafana

Nutze eine vorhandene Prometheus- und Grafana-Installation, wenn du bereits eine betreibst. Das folgende Beispiel startet ein separates Compose-Projekt zur Überwachung und ruft Tale über den öffentlichen Proxy ab. Es umfasst dauerhaften Metrikspeicher, eine eingebundene Token-Datei und zwei erste Alarmregeln.

## Zugriff und Dateien vorbereiten

Setze `METRICS_BEARER_TOKEN` für Tales Proxy und übernimm die Änderung mit deinem Bereitstellungsverfahren. Ein einfacher Container-Neustart lädt keine geänderten Umgebungswerte. Prüfe die geschützten Pfade unter [Observability konfigurieren](https://docs.tale.dev/de/self-hosted/configuration/observability-config#metriken), bevor du den Scraper einrichtest.

Erstelle einen eigenen Überwachungsordner mit `compose.monitoring.yml`, `prometheus.yml`, `tale-alerts.yml` und `secrets/tale-metrics-token`. Schreibe mit deinem Secret-Manager ausschließlich den Token-Wert in die Geheimnisdatei. Halte diese Datei und die Monitoring-`.env` aus der Versionsverwaltung heraus. Beschränke den Zugriff auf den Betreiber und den Container, der die Datei benötigt.

Lege in der Monitoring-`.env` geprüfte Tags für `PROMETHEUS_IMAGE` und `GRAFANA_IMAGE` sowie `GRAFANA_ADMIN_PASSWORD` fest. Wähle unterstützte Versionen auf den offiziellen Downloadseiten von [Prometheus](https://prometheus.io/download/) und [Grafana](https://grafana.com/grafana/download). Diese Versionen sind unabhängig vom Tale-Release-Tag.

## Überwachungsdienste definieren

Beide Oberflächen sind an Loopback gebunden. Öffne sie auf dem Docker-Host oder über einen SSH-Tunnel. Ein entfernter Docker-Kontext bindet sie nicht an deinen Arbeitsplatzrechner.

```yaml
# compose.monitoring.yml
services:
  prometheus:
    image: ${PROMETHEUS_IMAGE:?set a tested Prometheus image tag}
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - ./tale-alerts.yml:/etc/prometheus/tale-alerts.yml:ro
      - prometheus-data:/prometheus
    secrets: [tale_metrics_token]
    ports: ['127.0.0.1:9090:9090']
    restart: unless-stopped
  grafana:
    image: ${GRAFANA_IMAGE:?set a tested Grafana image tag}
    environment:
      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD:?set a strong password}
      GF_USERS_ALLOW_SIGN_UP: 'false'
    volumes: ['grafana-data:/var/lib/grafana']
    ports: ['127.0.0.1:3001:3000']
    restart: unless-stopped
secrets:
  tale_metrics_token:
    file: ./secrets/tale-metrics-token
volumes:
  prometheus-data:
  grafana-data:
```

Prometheus erhält das Geheimnis unter `/run/secrets/tale_metrics_token`. Stelle sicher, dass die Container-Laufzeit die Quelldatei lesen kann, ohne sie für andere Nutzer freizugeben.

## Erfassung und Alarme konfigurieren

Ersetze `tale.example.com` durch den erreichbaren Tale-Hostnamen, einschließlich Port, wenn du nicht 443 verwendest. Ergänze bei Bedarf den Basispfad der Instanz in jedem `metrics_path`. Nutze ein vertrauenswürdiges HTTPS-Zertifikat oder binde eine CA-Datei ein. Schalte die Zertifikatsprüfung nicht ab, um den Abruf zum Funktionieren zu bringen.

```yaml
# prometheus.yml
global:
  scrape_interval: 30s
rule_files:
  - /etc/prometheus/tale-alerts.yml
scrape_configs:
  - job_name: tale-platform
    scheme: https
    metrics_path: /metrics/platform
    authorization:
      credentials_file: /run/secrets/tale_metrics_token
    static_configs:
      - targets: ['tale.example.com']
  - job_name: tale-backend
    scheme: https
    metrics_path: /metrics/backend
    authorization:
      credentials_file: /run/secrets/tale_metrics_token
    static_configs:
      - targets: ['tale.example.com']
```

Das Token wird über `credentials_file` gelesen, wie in der [HTTP-Konfiguration von Prometheus](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#http_config) beschrieben. Ein wörtliches `${METRICS_BEARER_TOKEN}` in dieser YAML-Datei wird nicht durch Docker Compose ersetzt: Compose bindet die Datei ein, ohne ihren Inhalt umzuschreiben.

```yaml
# tale-alerts.yml
groups:
  - name: tale
    rules:
      - alert: TaleTargetDown
        expr: up{job=~"tale-.*"} == 0
        for: 2m
        labels: { severity: page }
        annotations:
          summary: 'Tale metrics target {{ $labels.job }} is down'
      - alert: TaleDefaultStoreUnreachable
        expr: tale_backend_store_up == 0
        for: 5m
        labels: { severity: page }
        annotations:
          summary: 'Tale cannot reach its default {{ $labels.store }} store'
```

Passe Dringlichkeit und Wartezeiten an deine Anforderungen an und richte die Zustellung über Alertmanager oder Grafana ein. Eine in Prometheus sichtbare Regel versendet für sich allein keine Benachrichtigung. Der Speicher-Alarm umfasst Bereitstellungsstandards, keine organisationsspezifischen Datenbanken oder Buckets.

## Erfassung starten und prüfen

Prüfe die Dateien vor dem Start:

```bash
docker compose -f compose.monitoring.yml config --quiet
docker compose -f compose.monitoring.yml run --rm --entrypoint promtool \
  prometheus check config /etc/prometheus/prometheus.yml
docker compose -f compose.monitoring.yml up -d
```

Öffne `http://127.0.0.1:9090/targets`. Beide Tale-Jobs sollten **UP** anzeigen. Prüfe die Abfrage `up{job=~"tale-.*"}` und die Alarmregeln. Ein `401` weist auf die Token-Konfiguration hin. Bei DNS-, Verbindungs- oder Zertifikatsfehlern prüfst du den Netzwerkweg des Scrapers. **UP** belegt einen erfolgreichen Metrikabruf, nicht jede Anwendungsfunktion.

Öffne Grafana unter `http://127.0.0.1:3001` und füge eine Prometheus-Datenquelle mit `http://prometheus:9090` hinzu. Diese Adresse wird innerhalb des Monitoring-Compose-Netzwerks aufgelöst.

## Ein hilfreiches erstes Dashboard aufbauen

| Panel | Abfrage | Aussage |
| --- | --- | --- |
| Scrape-Verfügbarkeit | `up{job=~"tale-.*"}` | Ob jeder öffentliche Metrikpfad dem Scraper geantwortet hat. |
| Backend-Speicher | `process_resident_memory_bytes{job="tale-backend"}` | Arbeitsspeicher des antwortenden API-Replikats. |
| Backend-Antwortrate | `sum by (status) (rate(tale_backend_http_requests_total[5m]))` | Anfrageraten nach Antwortstatusklasse. |
| Job-Zustände | `tale_backend_jobs` | Jobs nach Warteschlangenzustand; achte auf anhaltendes Wachstum und Fehler. |
| Standardspeicher | `tale_backend_store_up` | Zwischengespeicherte Erreichbarkeit von `app_db`, `knowledge_db` und `object_store`. |
| Bereitstellungs-Drain | `tale_backend_drain_active` | Ob das Entleeren vor einer Bereitstellung neue Turns zurückweist. |

Einige Metriken lesen gemeinsame Datenbankzähler, andere beschreiben einen einzelnen Prozess. Erfasse bei mehreren Replikaten die Prozessmetriken einzeln über dein privates Monitoring-Netz und vermeide mehrfaches Zählen gemeinsamer Werte. [Betrieb überwachen](https://docs.tale.dev/de/self-hosted/operate/observability/operations) erklärt die Grenzen der Speicherprüfungen und die zusätzlichen Messungen für die SLA-Regelvorlage.

# Fehler einer selbst gehosteten Instanz beheben
Source: https://docs.tale.dev/de/self-hosted/operate/observability/troubleshooting

Halte Zeitpunkt, betroffene Organisation, URL oder Aktion und Fehlercode fest, bevor du etwas neu startest. Prüfe, ob ein einzelner Eintrag, eine Organisation oder die gesamte Bereitstellung betroffen ist. Davon hängt ab, ob du eine Datei, eine Organisationsverbindung oder gemeinsame Infrastruktur untersuchst.

Beginne bei einer Workspace-Bereitstellung mit `tale status` und `tale logs <service> --tail 200`. In deinem eigenen Compose-Projekt verwendest du `docker compose ps` und `docker compose logs --tail=200 <service>`. Dienstnamen wie `platform` und `backend-api` unterscheiden sich von erzeugten Containernamen.

## Öffentliche URL, Zertifikat oder Anmeldung scheitert

| Symptom | Prüfung | Nächster Schritt |
| --- | --- | --- |
| Verbindung scheitert oder TLS warnt | DNS, öffentliche Ports, Hostname und Aussteller des Zertifikats, Proxy-Protokolle. | Behebe die betroffene Ebene. Installiere bei einer internen CA das öffentliche Stammzertifikat auf dem Client; `docker exec ... caddy trust` ändert dessen Vertrauensspeicher nicht. |
| Proxy antwortet mit 502/503 | Ermittle Pfad und Zieldienst. `/api/health` und Webdateien nutzen `platform`, Anwendungsanfragen `backend-api`. | Prüfe Startfehler und Bereitschaft des Dienstes vor Änderungen am Proxy. |
| Anfragen antworten mit `503 DATABASE_UNAVAILABLE` | `backend-api` läuft, aber seine Datenbank startet neu oder ist nicht erreichbar; das Protokoll zeigt Warnungen mit `database unavailable`. | Prüfe Zustand und Protokolle des Datenbank-Containers. Sobald er wieder Verbindungen annimmt, laufen die Anfragen von selbst wieder durch. |
| `400 BODY_LENGTH_MISMATCH` oder `400 BODY_CHUNK_MALFORMED` | Der Anfragekörper endet vor seiner angegebenen Länge oder enthält fehlerhafte HTTP/1.1-Chunk-Grenzen. | Korrigiere Längenangabe oder Übertragungsformat beim Sender und wiederhole dann die korrekt formatierte Anfrage. |
| Anmeldung führt zurück zur Anmeldeseite | Cookies und Callback-Anfragen im Browser; `SITE_URL`, weitere Ursprünge, Basispfad und Anbieterregistrierung. | Korrigiere Ursprung oder Callback und erstelle Dienste nach Umgebungsänderungen neu. |

Eine ladende Oberfläche ohne Daten deutet zunächst auf Anwendungsanfragen, nicht zwingend auf den Webserver. Prüfe fehlgeschlagene Browseranfragen und `backend-api`-Protokolle. Proxy, abgelaufene Sitzung, fehlende Rechte und Backend-Ausfall brauchen unterschiedliche Lösungen. [TLS und Domains](https://docs.tale.dev/de/self-hosted/configuration/tls-and-domains) sowie [Authentifizierung](https://docs.tale.dev/de/self-hosted/configuration/authentication) erklären die Einrichtung.

## Uploads oder Downloads scheitern

Vergleiche zuerst die Serverantwort mit der Browseranfrage an die vorsignierte URL. Ist nur eine Organisation betroffen, kann ihre eigene Speicherverbindung die Ursache sein, obwohl der Standard-Bucket erreichbar ist.

| Beobachtung | Bedeutung und Reaktion |
| --- | --- |
| `object store (skipped)` beim Start | Das Standard-Zugangsdatenpaar fehlt. Prüfe `OBJECT_STORE_ACCESS_KEY` und `OBJECT_STORE_SECRET_KEY`. Erzeuge für einen vorhandenen Speicher keine Ersatzwerte, ohne dessen Zugangsdaten abzustimmen. |
| `object store (ignored)` | Die Datei wird vom Betreiber verwaltet. Prüfe `default/object-storage/connection.json`; der Umgebungsabgleich lässt sie bewusst unverändert. |
| `seeded` oder `reconciled` | Die Standardverbindung wurde aus der Umgebung geschrieben oder aktualisiert. Das beweist keine vollständigen Objektrechte oder funktionierende Browserroute. |
| Speicherprüfung meldet Ausfall | Prüfe Endpunkt, Verbindung, Zugangsdaten, Bucket-Existenz und den genauen Backend-Fehler. |
| Server-Verbindungstest besteht, Browser-Upload scheitert | Prüfe öffentlichen Endpunkt, Zertifikatsvertrauen und Bucket-CORS für den tatsächlichen Browser-Ursprung. Erlaube die für den Dateifluss nötigen Methoden `GET`, `PUT` und `HEAD`. |

`tale_backend_store_up` erfasst Bereitstellungsstandards und misst Erreichbarkeit, keinen vollständigen Upload. Ein Objektspeicher-`403` kann trotzdem den Wert `1` ergeben. Prüfe nach der Korrektur einen kontrollierten Upload und Download. [Datenresidenz](https://docs.tale.dev/de/self-hosted/configuration/data-residency) erklärt Verbindungsänderungen und Dateiumzug.

## Ein Dokument wird nicht indexiert

Prüfe Status und Fehlergrund des Dokuments, dann die `backend-worker`-Protokolle. Kontrolliere Embedding-Modell und Zugangsdaten der Organisation, Vektordimensionen, Wissensdatenbankverbindung und Dateiformat. Ein erfolgreicher Upload belegt nur, dass die Originaldatei gespeichert wurde.

War ein Worker oder eine Abhängigkeit ausgefallen, stelle sie wieder her und prüfe, ob der Job weiterläuft oder **Jetzt indexieren** unter [Wissen](https://docs.tale.dev/de/platform/knowledge/documents) nötig ist. Bei beschädigten, verschlüsselten oder nicht unterstützten Dateien korrigierst du die Quelle vor einem neuen Versuch. Lösche ein Dokument nicht als ersten Diagnoseschritt: Identität, Verlauf und Referenzen können wichtig sein.

## Ein Website-Scan meldet einen Zertifikatsfehler

Der Crawl-Fehler `tls_error` bezeichnet einen gescheiterten TLS-Verbindungsaufbau, etwa wegen eines abgelaufenen Zertifikats, eines falschen Hostnamens oder einer nicht vertrauenswürdigen Zertifikatskette. Korrigiere das Website-Zertifikat oder die Vertrauenseinstellungen der Crawler-Laufzeit und starte danach einen neuen Scan. Dieselbe Anfrage erneut zu senden repariert kein Zertifikatsvertrauen. Deaktiviere die Zertifikatsprüfung nicht, um den Fehler zu verdecken.

`network_error` weist dagegen auf einen Verbindungsfehler hin. Lies die zugrunde liegende Ursache und prüfe DNS, Routing und Verfügbarkeit des Dienstes. [Websites crawlen](https://docs.tale.dev/de/platform/knowledge/crawling) erklärt Seitenfehler und Scan-Ergebnisse.

## Wissens-Postgres stürzt beim Import ab

Wiederholte Meldungen `PANIC: corrupted page pointers` oder `signal 6` können auf einen beschädigten BM25-Index hinweisen. Prüfe Datenbankprotokolle und das Ergebnis der automatischen Reparatur unter [Container-Architektur](https://docs.tale.dev/de/self-hosted/operate/container-architecture). Ermittle die genaue Korpusdatenbank: Im mitgelieferten Stack ist es `tale_knowledge` in `db`; andere Bereitstellungen verwenden einen separaten Dienst oder externen Host.

Diese Abfrage in einer berechtigten SQL-Sitzung auf der richtigen Datenbank prüft nur den genannten Index:

```sql
SELECT * FROM pdb.verify_index('private_knowledge.idx_pk_chunks_bm25');
```

Eine fehlende Funktion, ein Rechtefehler oder ein Timeout bestätigt keinen Indexschaden. Ist der Schaden belegt und die automatische Reparatur erfolglos, sichere den Zustand und plane eine Datenbankwartung. Einen abgeleiteten Index neu aufzubauen ist etwas anderes als Dokumenttabellen zu löschen:

```sql
REINDEX INDEX private_knowledge.idx_pk_chunks_bm25;
```

Dieser nicht nebenläufige Befehl kann Arbeit blockieren. Stimme ihn mit dem Datenbankbetrieb ab, prüfe danach den Index erneut und kontrolliere den Import. Führe keine spekulativen Index- oder Erweiterungsbefehle in der falschen Datenbank aus. Wiederkehrende Schäden erfordern die Prüfung von Plattenzustand und erzwungenen Stopps nach Ablauf der Wartezeit.

## Chat oder Automatisierung stoppt

Prüfe den Chat- oder Lauf-Fehler und die zuständigen API-/Worker-Protokolle. Anbieter-`429`, verweigerte Zugangsdaten, Ausführungs-Timeout, ausstehende Freigabe und unterbrochener Browser-Stream sind verschiedene Zustände. Eine Freigabe braucht eine Entscheidung, keinen Neustart. Hinter einem getrennten Stream kann die Operation weiterlaufen; prüfe ihr gespeichertes Ergebnis vor einer Wiederholung.

Kontrolliere bei Anbieterfehlern Kontingent und Rechte der gewählten Zugangsdaten sowie den Anbieterstatus. Wechsle Modelle nur, wenn der Ersatz erlaubt und für die Aufgabe geeignet ist. Prüfe bei Harness-Fehlern `sandbox`, `sandbox-llm-gateway`, Laufzeit-Image und Sitzungsprotokolle.

## Sandbox-Netzzugriff wird verweigert

Prüfe `sandbox-egress` und die Ziel-URL. Eine konfigurierte `SANDBOX_EGRESS_ALLOWLIST` muss den benötigten Hostnamen enthalten; private Ziele und Cloud-Metadaten bleiben blockiert. Für HTTPS-Tunnel gilt die unterstützte Portregel. Bestätige das gewünschte Ziel, bevor du eine Freigabeliste erweiterst. Erstelle den Egress-Dienst nach Umgebungsänderungen neu.

Ein gesunder Egress-Prozess belegt nicht die Verfügbarkeit von Gegenstelle, DNS, Zertifikat oder Konto. Bewahre den konkreten Anfragefehler im Störungsbericht auf.

Wenn viele Sessions gleichzeitig Pakete installieren oder Seiten laden und Verbindungen mit Resets abbrechen, während der Proxy gesund bleibt, hat er womöglich `SANDBOX_EGRESS_MAX_CLIENTS` erreicht, die Verbindungen, die er für alle Sessions zusammen gleichzeitig bedient. Sein Log meldet dann, dass die Höchstzahl an Verbindungen erreicht ist. Erhöhe den Wert zusammen mit den Prozess- und Dateigrenzen des Egress-Containers und erstelle den Egress-Dienst neu.

## Schreibzugriffe scheitern oder Speicher läuft voll

Prüfe Datenbankverbindung, freien Platz, Verbindungsbelegung und Sperren. Stoppe vermeidbares Wachstum und stelle Kapazität nach deinem Datenbankverfahren wieder her. Lösche keine Volume-Inhalte, setze keine Verschlüsselungsschlüssel zurück und erwarte keine automatische Wiederholung fehlgeschlagener Schreibzugriffe. Prüfe vor einem erneuten Versuch, ob die ursprüngliche Operation bereits gespeichert wurde.

Gib bei einer Hilfsanfrage Versionen, bereinigte Fehler, Zeitraum, betroffenen Umfang und Reproduktionsschritte an. `tale diagnostics` erstellt ein Diagnosepaket. Prüfe es vor dem Teilen, denn Bereitstellungsdetails können weiterhin sensibel sein. Reproduzierbare Fehler gehören in den [Issue-Tracker des Projekts](https://github.com/tale-project/tale/issues).

# Ein Release vor dem Upgrade prüfen
Source: https://docs.tale.dev/de/self-hosted/operate/release-notes/format

Lies die [Release-Hinweise auf GitHub](https://github.com/tale-project/tale/releases) für die Version, die du bereitstellen möchtest. Gehe von deiner installierten Version aus und prüfe jedes Release bis zum Ziel. Eine Patch-Nummer allein bedeutet nicht, dass Migrationen oder manuelle Schritte entfallen.

## Den Ausgangspunkt bestimmen

Mit `tale --version` ermittelst du die CLI-Version. Prüfe zusätzlich die laufende Runtime-Version: Die CLI zu aktualisieren und die Container neu bereitzustellen sind getrennte Vorgänge. Bei einem verwalteten Deployment nutzt du den Deployment-Beleg mit den festgelegten Quell-Commits und Image-Digests.

`tale update` wählt in der aktuellen CLI eine neuere Version innerhalb der bestehenden `x.y`-Reihe. Ein Wechsel zwischen Release-Reihen erfordert `--version`. Die Optionen deiner installierten CLI findest du mit `tale update --help`; die Release-Hinweise liest du auf GitHub.

## Die Folgen für den Betrieb bewerten

Prüfe ein Release in dieser Reihenfolge. Überschriften und Detailtiefe können variieren. Lies verlinkte Migrationshinweise oder Sicherheitsmeldungen vor der Bereitstellung.

| Information | Deine Entscheidung |
| --- | --- |
| Inkompatible Änderungen und Verhaltensänderungen | Welche Abläufe, Standardwerte oder Konfigurationen ändern sich? |
| Migrationen und Upgrade-Anleitung | Welche Voraussetzungen, Unterbrechungen oder Wiederherstellungsschritte sind nötig? |
| API-Änderungen | Brauchen Clients neue Anfragefelder, angepasstes Verhalten oder eine andere Fehlerbehandlung? Dieser Abschnitt wird beim Release aus dem Vertrags-Fingerabdruck erzeugt: Hat sich `info.version` seit dem vorherigen Tag geändert, nennt er die alte und die neue Version, die hinzugekommenen und entfernten Operationen sowie den Changelog-Eintrag des Vertrags; sonst hält er fest, dass der Vertrag unverändert bleibt. |
| Sicherheit | Ist deine Installation betroffen, und welche korrigierte Version oder Übergangslösung hilft? |
| Bekannte Probleme | Sind die Einschränkungen akzeptabel und die Übergangslösungen praktikabel? |
| Neuerungen und vollständige Änderungsliste | Welche Funktionen und Korrekturen sollten deine Benutzer kennen? |

Tale ist ein fortlaufend aktualisiertes 0.x-Projekt. Auch Patch-Releases können additive Migrationen und Verhaltensänderungen enthalten. Sicherheitskorrekturen erscheinen in der neuesten Version, ohne Rückportierung auf ältere Versionen. Maßgeblich ist die [Sicherheitsrichtlinie](https://github.com/tale-project/tale/security/policy).

## Die Änderung vorbereiten

1. Notiere Ausgangs- und Zielversion sowie die genauen Quell-Referenzen bei verwalteten Deployments.
2. Lies die dazwischenliegenden Release-Hinweise. Achte auf Konfiguration, Anmeldung, Datenspeicherung und Integrationen.
3. Plane Backup, Wiederherstellung und Wartungsfenster anhand der [Upgrade-Anleitung](https://docs.tale.dev/de/self-hosted/operate/upgrades).
4. Erprobe das Ziel in einer getrennten Umgebung mit deinen wichtigen Abläufen, einschließlich API-Clients und Freigaberegeln.
5. Prüfe nach dem Deployment den Systemzustand und wiederhole diese Abläufe. Bewahre die Release-Hinweise beim Deployment-Protokoll auf.

Ein erfolgreich heruntergeladenes Image belegt nicht, dass die Anwendung nach einer Migration funktioniert. Prüfe die laufende Plattform, bevor du das Upgrade abschließt. Unter [Sicherheitsmeldungen](https://docs.tale.dev/de/self-hosted/operate/security/advisories) erfährst du, wie du eine Schwachstelle bewertest und meldest.

# Sicherheitsmeldungen verfolgen
Source: https://docs.tale.dev/de/self-hosted/operate/security/advisories

Prüfe bei einem Sicherheitsupdate die [GitHub Security Advisories von Tale](https://github.com/tale-project/tale/security/advisories) und die [Release-Hinweise](https://github.com/tale-project/tale/releases) der Zielversion. Die [Sicherheitsrichtlinie](https://github.com/tale-project/tale/security/policy) des Repositorys legt Meldeweg und unterstützte Versionen fest.

## Eine Meldung bewerten

Lies zuerst, welche Versionen betroffen und welche korrigiert sind. Vergleiche sie mit dem laufenden System und seinen aktivierten Komponenten, nicht nur mit der CLI auf deinem Rechner.

| Information | Was du klären solltest |
| --- | --- |
| Betroffene Versionen und Komponenten | Ob der verwundbare Code in deiner Installation vorhanden ist. |
| Voraussetzungen und Auswirkungen | Ob deine Konfiguration den betroffenen Pfad zugänglich macht und welcher Zugriff möglich wäre. |
| Korrigierte Versionen | Welches Release die Korrektur enthält. |
| Schweregrad und gegebenenfalls CVSS-Vektor | Welche Auswirkungen und Annahmen bewertet wurden; ergänze deine eigene Expositionsanalyse. |
| Übergangslösungen | Welche vorübergehenden Einschränkungen helfen, wenn das Update nicht sofort möglich ist. |
| Kennung und Referenzen | Welchen dauerhaften Nachweis du im Vorfalls- und Deployment-Protokoll verwendest. |

Ein privates Netzwerk allein beweist nicht, dass deine Installation sicher ist. Anmeldung, Connector-Verhalten und interne Zugriffe können weiterhin relevant sein. Bestimme die Dringlichkeit anhand der Meldung und deines Ablaufs für Sicherheitsvorfälle.

## Die Korrektur einspielen und prüfen

Tale ist ein fortlaufend aktualisiertes 0.x-Projekt. Sicherheitskorrekturen erscheinen nur in der neuesten Version; ältere Versionen erhalten keine Rückportierungen. Lies alle Release-Hinweise bis zum Ziel und folge der [Upgrade-Anleitung](https://docs.tale.dev/de/self-hosted/operate/upgrades), einschließlich Backup und Wiederherstellungsvorbereitung.

Dokumentiere die installierte Korrektur und prüfe das betroffene Verhalten nach dem Deployment. Hebe eine vorübergehende Schutzmaßnahme erst auf, wenn die korrigierte Runtime läuft und deine Prüfungen erfolgreich sind.

## Eine Schwachstelle vertraulich melden

Öffne im Repository den Tab **Security** und wähle **Report a vulnerability**. Falls du GitHub nicht nutzen kannst, schreibe an `security@tale.dev`. Veröffentliche eine noch nicht korrigierte Schwachstelle nicht in einem öffentlichen Issue.

Nenne Komponente und Version, Schritte zur Reproduktion und vermutete Auswirkungen. Nutze ein möglichst kleines Beispiel ohne Zugangsdaten, personenbezogene Daten oder unnötige Produktionsdatensätze. Auf Wunsch nennt die spätere Sicherheitsmeldung den Reporter.

Die Sicherheitsrichtlinie sieht Bestätigung und erste Bewertung innerhalb von 72 Stunden vor, eine vertraulich mit dem Reporter geteilte Korrektur oder Übergangslösung innerhalb von 14 Tagen sowie ein GitHub Security Advisory zur korrigierten Version. Stimme die Untersuchung über die vertrauliche Meldung ab.

## Die Prüfung regelmäßig durchführen

Speichere die Seiten für Sicherheitsmeldungen und Releases und nimm sie in deine regelmäßige Update-Prüfung auf. Halte fest, wer sie prüft, welche Installationen betroffen sind und wohin dringende Befunde eskaliert werden. Die [Release-Prüfung](https://docs.tale.dev/de/self-hosted/operate/release-notes/format) enthält den übergreifenden Ablauf; [Härtung](https://docs.tale.dev/de/self-hosted/operate/security/hardening) beschreibt Schutzmaßnahmen zwischen Updates.

# Die Integrität des Audit-Protokolls untersuchen
Source: https://docs.tale.dev/de/self-hosted/operate/security/audit-log-integrity

Nutze diese Anleitung, wenn **Ketten-Integrität** einen Bruch meldet oder du eine Benachrichtigung zur Audit-Integrität erhältst. Für den beschriebenen Weg durch die Einstellungen brauchst du ein Admin- oder Inhaberkonto. Ziehe für die Untersuchung der Datenbank den Betreiber deiner Installation hinzu.

## Den geprüften Bereich feststellen

1. Öffne **Einstellungen > Richtlinien > Protokolle** und suche **Ketten-Integrität**.
2. Notiere Status und Zeitpunkt der letzten automatischen Prüfung. **Noch nicht geprüft** bedeutet, dass noch kein Ergebnis vorliegt; es bestätigt keine erfolgreiche Prüfung.
3. Wähle **Jetzt prüfen**. Das Ergebnis nennt die Zahl der geprüften Einträge. Ein Aufruf prüft höchstens 1.000 Einträge ab dem Anfang der noch vorhandenen Kette.
4. Ist das Ergebnis unvollständig, bitte den Betreiber, den restlichen Bereich zu prüfen. Ein erneuter Klick beginnt wieder am selben Anfang. Eine fehlerfreie erste Seite belegt nicht die Integrität des gesamten Verlaufs.

Das Ergebnis dieses Aufrufs und der Status der geplanten Prüfung sind getrennt. **Jetzt prüfen** aktualisiert den Zeitpunkt der letzten automatischen Prüfung nicht.

## Verstehen, was die Prüfung abdeckt

Das aktuelle PostgreSQL-Backend prüft den SHA-256-Hash jedes noch vorhandenen, nicht bereinigten Audit-Eintrags und die Verknüpfungen zwischen den Einträgen. Die erste erhaltene Zeile liefert den Ausgangswert. So lassen sich viele Änderungen innerhalb der Kette erkennen. Die Prüfung liefert jedoch keinen unabhängig signierten Nachweis aller früheren Daten.

Die Aufbewahrungsregel kann den Anfang der Kette entfernen. Die geplante Prüfung setzt an ihrem gespeicherten Fortschritt fort. Wurde dieser Ausgangspunkt regulär durch die Aufbewahrung gelöscht, beginnt sie bei der ersten erhaltenen Verknüpfung. Fehlt ein Ausgangspunkt innerhalb des Aufbewahrungszeitraums, wird das nicht auf diese Weise akzeptiert.

Bei Einträgen, deren personenbezogene Inhalte gelöscht wurden, prüft das Backend die Verknüpfung, ohne den Hash aus den gelöschten Inhalten neu zu berechnen. Es zählt außerdem bereinigte Zeilen ohne passenden Löschantrag. Untersuche eine solche Warnung anhand der Löschvorgänge. Das aktuelle Backend prüft keine HMAC-signierten Prüfpunkte; ein Audit-Signaturschlüssel behebt diese Befunde nicht.

<Warning title="Unabhängige Nachweise aufbewahren">
Eine Hash-Kette verhindert weder Datenbankänderungen noch belegt sie, dass jede Aktion protokolliert wurde. Schütze den Datenbankzugriff und bewahre geeignete unabhängige Nachweise auf. Eine vollständig neu geschriebene Kette lässt sich mit dieser Prüfung allein nicht zuverlässig erkennen.
</Warning>

## Einen Fehler dokumentieren

Bei einem abweichenden Hash oder einer fehlerhaften Verknüpfung zeigt das Panel **Ketten-Integrität verletzt**, die **Eintrags-ID**, den Zeitpunkt sowie **Erwarteter Hash** und **Gespeicherter Hash**. Über **Diesen Eintrag öffnen** untersuchst du das Ereignis.

1. Sichere den Befund zusammen mit Organisation, Eintrags-ID, Zeitpunkt und bereitgestellter Version. Übernimm die Werte unverändert.
2. Bewahre vor Reparaturen Datenbank-Snapshots sowie relevante Deployment-, Zugriffs- und Backup-Protokolle auf. Beschränke den Zugriff auf Kopien mit personenbezogenen Daten.
3. Vergleiche den Zeitpunkt mit Aufbewahrung, Löschung, Wiederherstellung und Wartung. Zeitliche Nähe ist ein Ermittlungsansatz, kein Beweis für einen harmlosen Fehler.
4. Folge deinem Ablauf für Sicherheitsvorfälle, wenn der Befund ungeklärt bleibt. Ändere oder lösche die betroffene Zeile nicht, nur damit die Prüfung erfolgreich wird.

Die Anleitung zu [Audit-Protokollen](https://docs.tale.dev/de/platform/admin/governance/audit-logs) erklärt Felder und Export. Ein gefilterter Export mit Zeilenlimit ist weder ein vollständiges Backup noch zwingend eine vollständige Kette.

## Die geplante Prüfung verfolgen

Ein täglicher Job prüft Organisationen mit Audit-Einträgen schrittweise. Ein erkannter Hash-Bruch aktiviert eine Integritätswarnung und benachrichtigt die Admins der Organisation. Wiederholte Prüfungen führen für denselben Befund nicht zu doppelten Benachrichtigungen. Ein veränderter Befund kann eine neue auslösen.

Prüfe nach Reparatur oder Wiederherstellung, ob der betroffene Bereich wieder gültig ist. Eine anschließende erfolgreiche geplante Prüfung hebt die aktive Warnung auf. Einem Kollegen den Fehler zu erklären oder eine Benachrichtigung zu schließen repariert die Kette nicht.

Weitere Schutzmaßnahmen findest du unter [Härtung](https://docs.tale.dev/de/self-hosted/operate/security/hardening). Welche alten Nachweise entfernt werden, regelt die [Aufbewahrung](https://docs.tale.dev/de/self-hosted/configuration/retention).

# Kryptografie und Schlüsselverantwortung
Source: https://docs.tale.dev/de/self-hosted/operate/security/cryptography

Diese Übersicht zeigt, welcher Schlüssel welche Daten schützt und was ein Schlüsseltausch bewirkt. Anwendungsgeheimnisse, Datenbankvolumes, Netzwerkverkehr und Audit-Nachweise haben getrennte Schutzmechanismen. Unterscheide sie bei Backups und bei der Prüfung einer Bereitstellung.

## Verschlüsselte Daten zuordnen

Aktuelle Anbieterzugangsdaten verwenden die Secret Box der Datenbank: AES-256-GCM mit einem zweckgebundenen Schlüssel, den HKDF-SHA256 aus `ENCRYPTION_SECRET_HEX` ableitet. Andere Datenbankzugangsdaten, darunter OAuth-Token von Connectors, können den JWE-Pfad `dir`/`A256GCM` mit demselben Bereitstellungsschlüssel verwenden. Die Formate sind nicht austauschbar.

Unterstützte Geheimnisdateien der Konfiguration verwenden SOPS mit age-Empfängern. Dazu gehören Zugangsdaten für externe Wissensdatenbanken und Objektspeicher. `SOPS_AGE_KEY` oder `SOPS_AGE_KEY_FILE` aktiviert die Verschlüsselung; ohne beide unterstützt der Helfer Klartextdateien mit eingeschränkten Rechten. Lies [Geheimnisse mit SOPS](https://docs.tale.dev/de/self-hosted/configuration/secrets-with-sops) vor einer Änderung.

Namen, Adressen, Gespräche und Dokumentinhalte werden durch diese Verfahren nicht pauschal auf Feldebene verschlüsselt. Schütze Datenbank, Objektspeicher und Backups mit der für deine Bereitstellung erforderlichen Speicherverschlüsselung und Zugriffskontrolle. TLS schützt den Transport, keine von der Festplatte kopierte Datenbankdatei.

## Netzwerkverkehr schützen

Der öffentliche Reverse Proxy beendet HTTPS-Verbindungen. Richte Domain und Zertifikat gemäß [TLS und Domains](https://docs.tale.dev/de/self-hosted/configuration/tls-and-domains) ein und prüfe danach Zertifikat und akzeptierte TLS-Versionen am bereitgestellten Endpunkt.

Ein internes Docker-Netz trennt Dienste, verschlüsselt sie aber nicht selbst mit TLS. Überschreiten Datenbank-, Speicher- oder andere Verbindungen Host- oder Vertrauensgrenzen, richte auch für diese Verbindungen einen passenden Transportschutz ein und prüfe ihn.

## Passwort- und Sitzungsschutz erhalten

Lokale Passwörter werden mit bcrypt gehasht. `BETTER_AUTH_SECRET` schützt den Authentifizierungszustand. Halte es stabil und über alle Backend-Replikate hinweg gleich. Eine Änderung kann Sitzungen ungültig machen und laufende Anmeldungen unterbrechen.

Ein Identitätsanbieter besitzt eigene Signaturschlüssel und einen eigenen Rotationsablauf. Hinterlege aktuelle Metadaten und Zertifikate über [Unternehmens-SSO](https://docs.tale.dev/de/platform/admin/enterprise-sso). Der Austausch eines Tale-Sitzungsgeheimnisses rotiert keinen IdP-Schlüssel.

## Audit-Nachweise prüfen

Audit-Einträge bilden eine SHA-256-Kette. Das aktuelle PostgreSQL-Backend prüft erhaltene Zeilen und ihre Verknüpfungen ab der ersten noch vorhandenen gespeicherten Verbindung. Es berücksichtigt die Aufbewahrung und gleicht bereinigte Zeilen mit Löschanträgen ab. Signierte Prüfpunkte werden nicht geprüft.

Die Kette macht Manipulationen erkennbar; sie verhindert keine Änderungen am Speicher. Schütze den Datenbankzugriff, bewahre Nachweise bei Bedarf unabhängig auf und untersuche Alarme gemäß [Audit-Protokollintegrität](https://docs.tale.dev/de/self-hosted/operate/security/audit-log-integrity). Das getrennte `TALE_AUDIT_PEPPER` pseudonymisiert sensible Kennungen fehlgeschlagener Anmeldungen. Seine Rotation verändert die Vergleichbarkeit über diesen Zeitpunkt hinweg.

## Schlüsselwiederherstellung planen

Verwende diese Tabelle für deinen Wiederherstellungsplan:

| Schutzmechanismus | Benötigte Wiederherstellungsdaten | Folge bei Änderung oder Verlust |
| --- | --- | --- |
| Verschlüsselung von Datenbankgeheimnissen | Zum Snapshot passendes `ENCRYPTION_SECRET_HEX` | Vorhandene Zugangsdaten lassen sich möglicherweise nicht entschlüsseln. |
| SOPS-Geheimnisdateien | Passende private age-Schlüssel, auch für ältere Backups | Nur an einen verlorenen Empfänger verschlüsselte Dateien sind nicht lesbar. |
| Authentifizierung | `BETTER_AUTH_SECRET` und konsistente Bereitstellungskonfiguration | Sitzungen und laufende Anmeldungen können ausfallen. |
| Audit-Prüfung | Erhaltene Audit-Zeilen, Löschvorgänge und unabhängige Nachweise | Verlorene oder neu geschriebene Historie lässt sich aus der aktuellen Kette allein nicht belegen. |
| Verschlüsselung von Host und verwaltetem Speicher | Wiederherstellungsdaten und Zugriff des Speicheranbieters | Anwendungsschlüssel allein entsperren kein Volume und keinen Bucket. |

Bewahre Schlüssel in einem Secret-Manager oder geschützten Wiederherstellungsspeicher auf, getrennt von öffentlich zugänglichem Quellcode und Build-Artefakten. Behalte alte Entschlüsselungsschlüssel für alte Backups auch nach einer Rotation. Teste eine Wiederherstellung mit dem tatsächlichen Schlüsselmaterial in einer isolierten Umgebung.

Zertifizierungen und Nachweise findest du unter [Vertrauen und Compliance](https://docs.tale.dev/de/cloud/trust-and-compliance). Diese Übersicht erklärt die technischen Schutzmechanismen. Beziehe bei deiner Bewertung auch die konkrete Konfiguration deiner Installation ein.

# Eine Produktionsinstallation absichern
Source: https://docs.tale.dev/de/self-hosted/operate/security/hardening

Prüfe diese Schutzmaßnahmen vor dem Start und nach Änderungen an Host, Netzwerk oder Anmeldung. Du brauchst Betreiberzugriff und einen Wiederherstellungsweg, der auch während Änderungen an den Zugriffsregeln erreichbar bleibt.

## Den Hostzugriff beschränken

Nutze persönliche Betreiberkonten, SSH-Schlüssel und ein unterstütztes, aktuell gehaltenes Betriebssystem. Beschränke den Zugriff auf Host, Konfigurationsverzeichnis, Backups und Docker-Socket auf die zuständigen Betreiber.

Die Mitgliedschaft in der Gruppe `docker` gewährt über den Docker-Daemon Befugnisse auf Root-Ebene. Die CLI unter einem anderen Konto auszuführen hebt diese Befugnisse nicht auf. Behandle Docker-Zugriff als privilegierte Administration. Die [Docker-Dokumentation](https://docs.docker.com/engine/install/linux-postinstall/) erklärt diesen Zusammenhang.

## Die öffentliche Erreichbarkeit prüfen

Öffne die vorgesehenen Proxy-Ports und beschränke administrative Zugriffe auf vertrauenswürdige Quellen. Datenbank, Speicherverwaltung, interne Backend- und Sandbox-Dienste gehören nicht ins öffentliche Netz, sofern keine gesondert geprüfte Architektur das erfordert.

Prüfe die veröffentlichten Ports deiner tatsächlichen Compose-Konfiguration und teste die Erreichbarkeit von außerhalb des Hosts. Host-Firewallregeln allein können täuschen: Docker verwaltet eigene Regeln für Weiterleitung und veröffentlichte Ports. Beachte die [Docker-Hinweise zu Firewalls](https://docs.docker.com/engine/network/packet-filtering-firewalls/).

Bei Anmeldung über vertrauenswürdige Header darf nur der vorgelagerte Proxy die Anwendung erreichen. Er muss vom Aufrufer gelieferte Identitätsheader entfernen, bevor er eigene setzt. Mehr dazu unter [Authentifizierung](https://docs.tale.dev/de/self-hosted/configuration/authentication).

Die `robots.txt` der Plattform rät Crawlern von der Indexierung der Anwendung ab, erlaubt aber öffentliche Entwickler- und Statuspfade wie `/docs`, `/openapi.json`, `/llms.txt`, `/llms-full.txt` und `/status`. Diese Anweisungen ersetzen keine Zugriffskontrolle. Schütze vertrauliche Daten durch Authentifizierung und prüfe, welche Informationen dein öffentlicher Statusbericht zeigt.

## TLS an der öffentlichen Adresse prüfen

Nutze ein vertrauenswürdiges Zertifikat für die Adresse, die deine Benutzer öffnen. Wähle `TLS_MODE=letsencrypt` für den mitgelieferten öffentlichen TLS-Zugang oder `TLS_MODE=external`, wenn dein vorgelagerter Proxy TLS terminiert. Ein selbst signiertes lokales Zertifikat schafft kein öffentliches Zertifikatsvertrauen.

Prüfe Zertifikatskette, Ablaufdatum und Erneuerung. Teste danach Anmeldung und Rückleitungen über die öffentliche Adresse. Die Konfiguration erklärt [TLS und Domains](https://docs.tale.dev/de/self-hosted/configuration/tls-and-domains).

## Geheimnisse und Schlüssel schützen

Ersetze die Beispielwerte vor dem Produktivbetrieb. Jede Installation braucht ein eigenes Datenbankpasswort, eigene Authentifizierungsgeheimnisse und einen eigenen Verschlüsselungsschlüssel. Beschränke den Zugriff auf `.env` und Geheimnisdateien auf den Betreiber. Bewahre Wiederherstellungskopien in deiner Geheimnisverwaltung auf.

Nutze bei Bedarf [SOPS](https://docs.tale.dev/de/self-hosted/configuration/secrets-with-sops) für unterstützte Geheimnisdateien. SOPS verschlüsselt nicht sämtliche Anwendungsdaten oder die ganze Festplatte. Erhalte die passenden Schlüssel für aufbewahrte Backups. Plane Rotationen nach [Kryptografie](https://docs.tale.dev/de/self-hosted/operate/security/cryptography); ein beliebiger Schlüsseltausch kann Sitzungen ungültig machen oder gespeicherte Zugangsdaten unlesbar werden lassen.

Setze `TALE_AUDIT_PEPPER`, um Daten fehlgeschlagener Anmeldungen zu pseudonymisieren. Die Audit-Aufbewahrung gilt pro Organisation. Prüfe deren angewandte Regeln und den benötigten Nachweiszeitraum anhand der [Aufbewahrungsreferenz](https://docs.tale.dev/de/self-hosted/configuration/retention).

## Die Wiederherstellung erproben

Wähle Backup-Häufigkeit und Aufbewahrung danach, welchen Datenverlust deine Organisation verkraften kann. Sichere Datenbank, Konfiguration, Objektspeicher und die zur Wiederherstellung nötigen Geheimnisse. Externe Speicher benötigen eine eigene abgestimmte Sicherung.

Bewahre geschützte Kopien außerhalb des Deployment-Hosts auf und stelle sie regelmäßig an einem isolierten Ziel wieder her. Prüfe danach Anmeldung, Dateien und wichtige Abläufe. [Backups und Wiederherstellung](https://docs.tale.dev/de/self-hosted/operate/backups-and-restore) erklärt den Umfang der CLI-Snapshots und die Dienstunterbrechungen.

## Sandbox-Ziele begrenzen

Der Egress-Proxy der Sandbox erlaubt standardmäßig öffentliche HTTPS-Ziele und blockiert private Adressen sowie Metadatenadressen. Mit `SANDBOX_EGRESS_ALLOWLIST` begrenzt du zusätzlich die Hostnamen. Dieses Beispiel gehört in die `.env` des Projekts und erlaubt zwei Python-Pakethosts:

```dotenv .env
SANDBOX_EGRESS_ALLOWLIST=^pypi\.org$|^files\.pythonhosted\.org$
```

Erstelle den Egress-Dienst mit der geänderten Umgebung neu. Prüfe, ob benötigte Ziele erreichbar sind und ein nicht aufgeführtes Ziel abgelehnt wird. Ergänze weitere Registries oder Quellcode-Hosts nur bei Bedarf. Die integrierten Dokument-Skills brauchen keine, um Word-, PowerPoint-, Excel- und PDF-Dateien zu erstellen und zu lesen, denn ihre Bibliotheken sind im Sandbox-Image enthalten. Texterkennung (OCR) für gescannte PDFs ist nicht enthalten. Modellanfragen laufen über das getrennte Modell-Gateway der Sandbox. Die Liste regelt daher nicht alle ausgehenden Verbindungen von Tale.

Prüfe Freigaben privater Netze getrennt. `TALE_ALLOW_PRIVATE_PROVIDER_HOSTS=1` erlaubt Modellanbieterziele einschließlich des Sandbox-Modellgateways, öffnet aber keinen allgemeinen Sandbox-Netzzugriff. `TALE_ALLOW_PRIVATE_CRAWL_HOSTS=1` erlaubt Intranet-Crawl-Ziele und private Produktbild-URLs. Aktiviere nur den benötigten Zugriff und behalte die Konfiguration unter Betreiberkontrolle. [Anbieter](https://docs.tale.dev/de/self-hosted/configuration/providers) beschreibt die Modellprüfungen; die [Umgebungsreferenz](https://docs.tale.dev/de/self-hosted/configuration/environment-reference) unterscheidet beide Variablen.

## Überwachen und untersuchen

Richte mit `METRICS_BEARER_TOKEN` authentifizierten Metrikzugriff ein und verbinde deine Überwachung. Prüfe, ob eine Warnung den zuständigen Betreiber erreicht. [Betriebsüberwachung](https://docs.tale.dev/de/self-hosted/operate/observability/operations) beschreibt hilfreiche Signale.

Ein täglicher Job prüft die erhaltenen Audit-Zeilen schrittweise und meldet erkannte Hash-Brüche an Admins. **Jetzt prüfen** unter **Einstellungen > Richtlinien > Protokolle > Ketten-Integrität** prüft höchstens 1.000 Einträge. Grenzen und Beweissicherung erklärt [Audit-Protokollintegrität](https://docs.tale.dev/de/self-hosted/operate/security/audit-log-integrity).

## Die bereitgestellte Antwort prüfen

Prüfe die Sicherheitsheader an der öffentlichen Adresse nach Proxy-Änderungen. Ein Proxy kann die von Tale gelieferten Header verändern; die Quellkonfiguration allein reicht als Nachweis nicht aus. Prüfe die Content-Security-Policy, Einbettungsbeschränkungen, HTTPS-Transportregeln und Inhaltstypbehandlung sowie den tatsächlichen Anmeldeablauf.

Übernimm Regeln für Cross-Origin-Isolation oder HSTS-Preload nicht ungeprüft von einer anderen Installation. Berücksichtige Rückleitungen, externe Dateien und Subdomains. Bewahre die Ergebnisse beim Deployment-Protokoll auf und wiederhole die Prüfung nach Upgrades.

# Bereitstellung aktualisieren und wiederherstellen
Source: https://docs.tale.dev/de/self-hosted/operate/upgrades

Bei einer Workspace-Bereitstellung ändert `tale update` CLI und Workspace-Dateien; `tale deploy` ändert die laufenden Dienste. Wähle Zielversion und Wiederherstellungspunkt vor beiden Schritten. Ein Blue-Green-Rollout lässt Anwendungsreplikate überlappen, doch Snapshots, Entleerungsphasen und der Austausch zustandsbehafteter Dienste können Arbeit unterbrechen.

Verwaltete Bereitstellungen verwenden feste Quellrevisionen und vorbereitete Bundles statt dieses Workspace-Ablaufs. Folge dafür [Verwaltete Bereitstellungen](https://docs.tale.dev/de/self-hosted/install/cli-install#managed-deployments). Wenn sich nur Client-Inhalte ändern, nutze [Konfigurations-Releases](https://docs.tale.dev/de/self-hosted/configuration/config-releases).

## Upgrade vorbereiten

1. Führe `tale status` im vorgesehenen Workspace aus. Halte laufende Version, Workspace-Version und aktuellen Bereitstellungszustand fest.
2. Lies die Release Notes der Zielversion zu Kompatibilität, erforderlicher Konfiguration und bekannten Einschränkungen. Für Instanzen vor 0.5 gilt der getrennte Umstieg weiter unten.
3. Prüfe eine wiederherstellbare Sicherung außerhalb des Hosts, passende Schlüssel und den Sicherungsumfang externer Datenbanken und Buckets. [Backups und Wiederherstellung](https://docs.tale.dev/de/self-hosted/operate/backups-and-restore) beschreibt die benötigten Bestandteile.
4. Plane Kapazität für alte und neue Anwendungsreplikate gleichzeitig. Vereinbare ein Wartungsfenster, wenn Snapshots, Sandbox-Austausch oder zustandsbehaftete Dienste benötigte Arbeit unterbrechen können.
5. Prüfe die Vorschau von Update und Bereitstellung. Ein erfolgreicher Probelauf beweist nicht, dass eine echte Migration gelingt; lies alle Warnungen.

## Version auswählen

Workspace-Befehle versuchen, die CLI an die Version aus `tale.json` anzupassen. Schlägt der Download fehl, warnt die CLI und verwendet das vorhandene Programm weiter. Kläre eine unerwartete Abweichung, bevor du die Bereitstellung änderst.

Ohne Versionsargument wählt `tale update` das neueste Release innerhalb der aktuellen `major.minor`-Linie. Eine andere Linie wählst du ausdrücklich:

```bash
tale update --dry-run
tale update --version <target-version> --dry-run
tale update --version <target-version>
```

Das Update ersetzt die CLI und gleicht Workspace-Vorlagen ab; laufende Container bleiben bestehen. Scheitert der Dateiabgleich, versucht die CLI, zur vorherigen Workspace-Version zurückzukehren. Prüfe danach Dateien und Ausgabe vor der Bereitstellung.

## Vorschau prüfen und bereitstellen

```bash
tale deploy --dry-run
tale deploy
tale status
```

Ein Versionswechsel oder eine Überschreibung der Host-Konfiguration erstellt vor Änderungen einen lokalen Snapshot, sofern du nicht `--skip-backup` angibst. Dieser Snapshot ist ein zusätzlicher Schutz und ersetzt keine externe Sicherung.

| Dienstgruppe | Normale Bereitstellung | Wann zusätzliche Unterbrechung einplanen? |
| --- | --- | --- |
| `platform`, `backend-api`, `backend-worker` | Gemeinsam als neue Anwendungsfarbe ausrollen. | Alte und neue Replikate überlappen; das Entleeren kann neue Turns verweigern. |
| `sandbox`, `sandbox-egress`, `sandbox-llm-gateway` | Nach dem Entleeren betroffener Arbeit an Ort und Stelle ersetzen. | Es sind gemeinsame Ausführungsdienste, keine zweite Blue-Green-Anwendungsgruppe. |
| `db`, `object-store`, `proxy` | Laufende Dienste behalten; die CLI meldet ausgelassene Updates. | Verwende `--stop`, wenn diese Dienste ersetzt werden müssen. |

```bash
tale deploy --stop
```

`TALE_PLATFORM_REPLICAS`, `TALE_BACKEND_API_REPLICAS` und `TALE_BACKEND_WORKER_REPLICAS` erlauben 1–16 Replikate. Erhöhe die Rolle, deren Engpass du gemessen hast. Mehr Worker beheben weder einen Datenbankausfall noch ein ausgeschöpftes Anbieterlimit.

## Die Übergabe verstehen

Die CLI startet die freie Farbe und wartet auf erfolgreiche Zustandsprüfungen ihrer Replikate, bevor sie die Übergabe abschließt. Während der Überlappung können beide Versionen Anfragen bedienen. Releases müssen daher während der Migration mit der vorherigen Anwendungsversion zusammenarbeiten können.

Vor dem Entfernen wird die alte API geleert: Neue Chat-Turns können eine Drain-Verweigerung erhalten, während laufende Turns Zeit zum Abschluss bekommen. Die Chat-Phase wartet bis zu drei Minuten; die Web-Phase nutzt `DRAIN_TIMEOUT`, standardmäßig 30 Sekunden. Die Web-Zustandsroute bleibt gesund, solange ihr Alias gemeinsam verwendet wird. Das Trennen der alten Container von den bedienenden Netzwerken entfernt sie aus DNS und kann übrige Verbindungen kappen. Deshalb erfolgt es nach den Entleerungsphasen.

Browser-Tabs, die vor der Übergabe geöffnet wurden, laufen weiter mit der vorherigen Version. Braucht ein solcher Tab zum ersten Mal einen Teil der Anwendung, den die neue Version ersetzt hat, etwa eine Dokumentvorschau, lädt er sich einmal neu und arbeitet mit der neuen Version weiter. Lässt sich dieser Teil auch nach dem Neuladen nicht laden, zum Beispiel weil der Tab erneut die alte Farbe erreicht hat, lädt er kein zweites Mal neu. Stattdessen zeigt er **Eine neue Version ist verfügbar** mit der Aktion **Neu laden**. Ein Tab, der Tale gar nicht erreicht, lädt nicht neu; er zeigt seinen Verbindungshinweis, bis Tale wieder antwortet.

Wird die neue Gruppe nicht innerhalb von `HEALTH_CHECK_TIMEOUT` gesund, schließt die CLI den Wechsel nicht ab. Prüfe gespeicherten Bereitstellungszustand und Protokolle vor einem erneuten Versuch. Ein unterbrochener Rollout kann beide Gruppen oder eine ausstehende Übergabe hinterlassen. Folge den Wiederherstellungshinweisen der CLI, statt Container oder Zustandsdateien von Hand zu löschen.

## Migrationen und Nutzerergebnis prüfen

Beim Start wendet das Backend seine nummerierten Migrationen in der Reihenfolge ihrer Dateinamen unter einem sitzungsgebundenen Advisory Lock an. SQL-Migrationen ändern das Schema, TypeScript-Datenmigrationen aktualisieren bestehende Zeilen nach den Regeln der Anwendung. Die Tabelle `app_migrations` verzeichnet beide Arten mit ihrem Dateinamen, sodass jede Migration pro Datenbank nur einmal läuft. Andere Replikate warten darauf. Ein Migrationsfehler verhindert den regulären Start des neuen Backends. Prüfe Fehler und Datenbank vor einem neuen Versuch. Vorwärtsgerichtete Migrationen werden durch einen anderen Image-Tag nicht rückgängig gemacht.

`tale migrate` aktualisiert mitgelieferte Organisationsstandards und rollt keine Datenbankmigration zurück. Prüfe vor einer Überschreibung der Host-Konfiguration, ob lokale Anpassungen tatsächlich ersetzt werden sollen.

Prüfe nach der Bereitstellung öffentliches Zertifikat und Anmeldung, öffne ein vorhandenes Projekt oder einen Chat und lade eine bekannte Datei herunter. Teste kontrolliert die genutzten Wissens- und Automatisierungsfunktionen. Kontrolliere Worker-Fortschritt, Speicherzustand und die tatsächlich laufende Version. Bewahre die Sicherung von vor dem Upgrade bis zur Abnahme auf.

## Rollback-Weg wählen

| Situation | Wiederherstellung |
| --- | --- |
| Zur gespeicherten vorherigen Version derselben `major.minor`-Linie zurückkehren | `tale rollback` prüft diese Grenze und fragt vor der erneuten Bereitstellung nach Bestätigung. Lies zusätzlich die Kompatibilitätshinweise des Releases. |
| Über eine Minor- oder Major-Grenze zurückkehren | Stelle den abgestimmten Datenstand vor dem Upgrade und dessen passende Version wieder her. `tale rollback` verweigert dieses reine Image-Downgrade. |
| Zielversion oder Datenkompatibilität unbekannt | Kläre Version und Herkunft der Sicherung vor dem Start eines älteren Programms. |

```bash
tale rollback
```

`--yes` überspringt die Bestätigung für einen bereits genehmigten unbeaufsichtigten Lauf. Die Prüfung derselben Versionslinie ist eine Schranke, kein eigenständiger Nachweis der Kompatibilität aller externen Integrationen und lokalen Anpassungen. Eine ältere Migrationsliste als Präfix der neuen macht ein Downgrade allein nicht sicher.

`tale rollback` tauscht nur die Anwendungs-Images von `platform`, `backend-api` und `backend-worker` aus. Es stellt kein Volume wieder her und lässt Datenbank, Speicher, Proxy, Sandbox-Dienste und Modell-Gateway, wie sie sind. Auch sonst stellt kein Bereitstellungsschritt von selbst Daten wieder her: Scheitert ein gewöhnlicher Deploy (ohne `--services`) an seinen Zustandsprüfungen, bleibt die bisherige Anwendungsfarbe in Betrieb, doch was er bereits an Ort und Stelle ersetzt hat, bleibt ersetzt. Nur `tale restore` spielt die Volumes eines Snapshots zurück.

## Bifrost 1.6 → 2.2: Der Speicher des Modell-Gateways wird migriert

Ein Release nach 0.5.64 stellt das Modell-Gateway (`sandbox-llm-gateway`) von Bifrost 1.6 auf Bifrost 2.2 um; seine Release Notes nennen den Wechsel. Beim ersten Start migriert das neue Gateway seinen Speicher in `llm-gateway-data` an Ort und Stelle und behält Anbieter, Schlüssel, Budgets und Admin-Konto; von Hand ist nichts zu tun. Die Migration indiziert auch das Anfrageprotokoll des Gateways, daher kann dieser Start bei einer Instanz mit langer Anfragehistorie länger dauern.

`tale deploy` ersetzt das Gateway, bevor es die neue Anwendungsfarbe startet. Scheitert die Bereitstellung danach, kann der Speicher also schon migriert sein. Der Snapshot, den ein `tale deploy` mit Versionswechsel vorher erstellt, enthält `llm-gateway-data` zusammen mit den anderen Volumes und ist damit auch der Wiederherstellungspunkt des Gateways. Snapshots, die entstanden sind, bevor die CLI den Speicher des Gateways erfasste, enthalten kein solches Archiv; `tale restore` führt sie als `without gateway`. Stellst du mit `--skip-backup` bereit, kopiere das Volume vorher selbst: Stoppe das Gateway, was laufende Agent-Turns und Modellaufrufe beendet, kopiere das Volume und stelle dann bereit. `<id>` ist die `id` in `tale.json`:

```bash
docker stop <id>-sandbox-llm-gateway
docker run --rm -v <id>_llm-gateway-data:/from:ro -v "$PWD/llm-gateway-data-backup:/to" alpine:3.22 cp -a /from/. /to/
```

Das Gateway eines Releases vor dem Wechsel startet auf dem migrierten Speicher und bedient Tale, protokolliert aber Fehler `no such column: oauth_configs.token_id`, und Bifrost unterstützt dieses Downgrade nicht. `tale rollback` startet dieses Gateway nicht: Das Gateway bleibt bei dem neueren Image und seinem Speicher. Gestartet wird es, sobald wieder ein Release vor dem Wechsel bereitgestellt wird, etwa mit `tale update --version` und `tale deploy` nach einer Snapshot-Wiederherstellung. Bring deshalb zuerst den Speicher zurück. Stellst du den Snapshot von vor dem Upgrade wieder her, kommt `llm-gateway-data` mit den anderen Volumes zurück. Führt `tale restore` diesen Snapshot als `without gateway`, stoppe das Gateway und spiele deine Kopie zurück, bevor du das ältere Release bereitstellst:

```bash
docker stop <id>-sandbox-llm-gateway
docker run --rm -v "$PWD/llm-gateway-data-backup:/from:ro" -v <id>_llm-gateway-data:/to alpine:3.22 sh -c 'find /to -mindepth 1 -delete && cp -a /from/. /to/'
```

Ein Gateway ohne Admin-Konto, bei einer neuen Installation oder nachdem sein Volume ersetzt wurde, legt das Konto jetzt nur für einen Aufrufer an, der sein Setup-Token vorweist; das Image übernimmt es aus `SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD`. `tale deploy`, die Compose-Datei im Repository und die Kubernetes-Manifeste dieser Dokumentation geben dem Gateway diese Variable bereits. Eine selbst geschriebene Compose-Datei oder ein Manifest, das sie nur dem Backend gibt, muss sie auch dem Gateway geben.

Zwei Verhaltensweisen ändern sich. Legt ein Aufrufer auf, beendet das Gateway jetzt den Modellaufruf, ob er eine ganze Antwort oder einen Stream angefordert hat. Eine abgebrochene Anfrage hält ein selbst betriebenes Modell also nicht mehr beschäftigt; die Modell-Endpunkte verbuchen einen solchen Aufruf mit seinem Prompt und der Ausgabe, die den Aufrufer erreicht hatte. Und ein Upstream, der die Antwort-Header einer gestreamten Antwort zurückhält, etwa ein Router, der Anfragen bis zu einem freien Modell in eine Warteschlange stellt, muss seine Antwort innerhalb des Anfrage-Timeouts des Gateways beginnen: 600 Sekunden, oder länger, wenn `SANDBOX_LLM_GATEWAY_STREAM_IDLE_TIMEOUT_SECONDS` es anhebt.

## 0.4 → 0.5: eine separate Installation

Mit 0.5 ersetzte Postgres den früheren Convex-Anwendungsspeicher. Es gibt keinen Importer für einen direkten Wechsel dieser Datenbanken. Halte alte Instanz und Backups intakt, während du eine neue Bereitstellung mit separatem Workspace und Datenbestand vorbereitest.

Erstelle Organisationen und Nutzer neu, prüfe und übertrage kompatible Konfiguration und importiere benötigte Dokumente erneut. Dateien in einem externen Bucket erhalten nicht automatisch Referenzen in der neuen Anwendungsdatenbank. Nimm die Ersatzumgebung ab, bevor du die alte stilllegst.

Die CLI verweigert den nicht unterstützten Umstieg standardmäßig. Die Expertenoption `--accept-data-loss` ist kein Migrationswerkzeug und erhält keine alten Anwendungsdaten. Historische Volumes oder Datenbanken können nach früheren Upgrades verbleiben. Ihr Vorhandensein allein ist kein Grund, sie bei diesem Ablauf zu löschen.

## 0.3 → 0.4: die OpenAI-kompatible API entfällt

Von 0.2.10 bis 0.3 bot Tale unter `/api/v1` eine OpenAI-kompatible Schicht: `POST /api/v1/chat/completions` und `POST /api/v1/images/generations` mit Anfragen und Antworten im OpenAI-Format sowie ein `GET /api/v1/models` im OpenAI-Format. Ihr Feld `model` konnte einen Agenten nennen. Mit dem Neuaufbau in 0.4 ist diese Schicht entfallen. Aufrufer dieser Routen, auch OpenAI-SDKs, die auf die Instanz zeigen, funktionieren danach nicht mehr, denn 0.4 bedient keine der drei Routen, und spätere Versionen bringen sie nicht zurück. Eine aktuelle Version beantwortet Chat Completions und Bildgenerierung mit `404 NOT_FOUND`, oder mit `400 ORG_SLUG_REQUIRED`, wenn der Schlüsselinhaber mehreren Organisationen angehört und die Anfrage keinen `X-Organization-Slug` mitschickt, den ein OpenAI-SDK standardmäßig nicht sendet. Ihr `GET /api/v1/models` liefert die eigene Liste von Tale mit Modellen und Agent-Laufzeiten, die ein OpenAI-Client nicht lesen kann.

Finde diese Aufrufer vor dem Upgrade und plane ihren Ersatz. Ein Aufrufer, der die Antwort eines Modells braucht, kann auf die Modell-Endpunkte umsteigen, die Versionen ab API-Vertrag 3.7.0 anbieten. Sie unterscheiden sich von der Schicht aus 0.3: Die Basis-URL ist `/api/v1/openai`, für Anthropic-Clients `/api/v1/anthropic`, statt `/api/v1`; `model` nennt ein Modell als `<providerSlug>/<modelId>`, nie einen Agenten; Bildgenerierung wird nicht bedient; und die Endpunkte sind ausgeschaltet, bis ein Admin unter **Einstellungen > Richtlinien > Modelle** den Schalter **Modell-Endpunkte für API-Schlüssel** einschaltet. Danach durchläuft jeder Aufruf Modellzugriff, Eingabe-Guardrails und Budgets. Die Modell-Endpunkte erreichen die Modelle über dasselbe Modell-Gateway wie verwaltete Agenten. Fragen aus Skripten an den eingebauten Assistenten wandern zur asynchronen REST-Chat-API, die als Assistent antwortet und nicht als reines Modell. Editor-Integrationen, die das Wissen von Tale brauchen, nutzen den MCP-Endpoint, und Arbeit, die in Tale laufen soll, in einer Sandbox und mit Prüfung durch eine Person, geht an einen Projektagenten an einer Aufgabe. [Tale aus deinem Editor oder einem Skript nutzen](https://docs.tale.dev/de/develop/use-tale-from-your-editor) beschreibt jeden dieser Wege.

# Architektur beim Selbsthosting
Source: https://docs.tale.dev/de/self-hosted/overview

Bei einer selbst gehosteten Tale-Instanz betreibst du Anwendung, Speicher und Sandbox-Dienste auf deiner Infrastruktur. Eine Instanz kann mehrere Organisationen enthalten; Datensätze und Konfiguration bleiben jeweils der zugehörigen Organisation zugeordnet.

Diese Übersicht hilft bei der Kapazitätsplanung und bei der Auswahl der zu sichernden Daten. [Compose selbst betreiben](https://docs.tale.dev/de/self-hosted/install/own-compose) beschreibt die erforderlichen Netzwerke, Mounts und Zustandsprüfungen. [Container-Architektur](https://docs.tale.dev/de/self-hosted/operate/container-architecture) hilft dir, Fehler im laufenden Betrieb einzugrenzen.

## Zusammenspiel der Dienste

Die mitgelieferte Bereitstellung auf einem Host umfasst zehn Dienste, bevor Replikate und vorübergehende Sandbox-Sitzungen hinzukommen. Der Stack für die Entwicklung kann eine eigene Wissensdatenbank verwenden. Vergleiche daher die Aufgaben der Dienste statt nur die Anzahl der Container.

| Ebene | Dienste | Aufgabe |
| --- | --- | --- |
| Öffentlicher Zugang | `proxy` | Caddy beendet TLS und leitet Browseranfragen an Web-Oberfläche, APIs und Dateispeicher weiter. |
| Anwendung | `platform`, `backend-api`, `backend-worker` | Die Web-Ebene liefert die Oberfläche. Die API authentifiziert Anfragen und führt Anwendungsoperationen aus. Worker bearbeiten Aufgaben, Automatisierungen und Importe aus der Warteschlange. |
| Dauerhafter Speicher | `db`, `object-store` | Postgres speichert Anwendungs- und Wissensdaten; der S3-kompatible Speicher enthält Originaldateien und erzeugte Medien. |
| Sandbox-Ausführung | `sandbox`, `sandbox-egress`, `sandbox-llm-gateway` | Der Spawner erstellt Ausführungssitzungen, der Egress-Proxy kontrolliert ausgehende Anfragen und das Modell-Gateway stellt begrenzten Modellzugriff bereit. |
| Video-Unterstützung | `bgutil-provider` | Liefert Proof-of-Origin-Tokens für den Videoimport. Seine Verfügbarkeit kann den Abruf von Transkripten beeinflussen. |

Der Browser verbindet sich über den öffentlichen Proxy. Datenbank-, Gateway- und Sandbox-Ports sollten nicht öffentlich erreichbar sein. Bei einem externen Bucket können vorsignierte Dateianfragen direkt vom Browser an dessen öffentlichen Endpunkt gehen.

Die Anwendungsrollen verwenden dasselbe Tale-Platform-Image. `TALE_ROLE=api` startet die API, `TALE_ROLE=worker` einen Worker. Worker stellen keinen HTTP-Server bereit. Die Sandbox-Laufzeit ist ein separates Image für vorübergehende Sitzungscontainer und kein zusätzlicher dauerhaft laufender Compose-Dienst.

## Wo dauerhafte Daten liegen

| Speicherort im mitgelieferten Stack | Zu erhaltende Daten |
| --- | --- |
| `db-data` | `tale_app`: Nutzer, Chats, Läufe, Audit-Einträge und verschlüsselte Datenbankgeheimnisse. `tale_knowledge`: extrahierte Inhalte, Embeddings, Suchindizes und abgerufene Webseiten. |
| `config-data` | Konfigurationsdateien der Organisationen, darunter Agenten, Skills, Anbieterdefinitionen, Richtlinien, SSO-Einstellungen und Branding. |
| `object-store-data` | Hochgeladene Dokumente, Anhänge, Audio und erzeugte Dateien. |
| `caddy-data`, `caddy-config` | Zertifikate und Proxy-Zustand. |
| `llm-gateway-data` | Gateway-Konfiguration, Zugangsdaten für Sitzungen und das Anfrageprotokoll des Gateways mit Modell, Tokens und Dauer, ohne Prompts oder Antworten. |

Im mitgelieferten Stack liegen beide Datenbanken in einem Postgres-Dienst. Der Netzwerkalias `knowledge-db` führt zur Wissensverbindung. Es bleiben zwei getrennte Datenbanken. Eine Bereitstellung aus dem Quellcode mit eigenem Wissensdienst besitzt zusätzlich `knowledge-db-data`.

Beim Ersetzen eines Containers bleiben Daten nur erhalten, wenn seine dauerhaften Volumes oder externen Speicher weiter eingebunden sind. Sichere auch den Bereitstellungsordner, die Umgebung, Verschlüsselungsschlüssel und Kopien außerhalb des Hosts. Die Snapshots der CLI erfassen diese Volumes, aber keine externen Speicher, und lassen das Datei-Volume aus, wenn der Bereitstellungsstandard auf einen externen Bucket zeigt; prüfe den Umfang unter [Backups und Wiederherstellung](https://docs.tale.dev/de/self-hosted/operate/backups-and-restore).

## Geheimnisse und Anmeldung

`ENCRYPTION_SECRET_HEX` schützt Anbieterzugangsdaten und andere verschlüsselte Werte in der Anwendungsdatenbank. SOPS und age schützen unterstützte Begleitdateien mit Geheimnissen, etwa Passwörter für externe Speicher. Sichere die benötigten Schlüssel getrennt von den geschützten Daten. Ein neuer Schlüssel entschlüsselt keine vorhandenen Geheimnisse.

Better Auth läuft im Backend. Lokale Anmeldung, Zwei-Faktor-Authentifizierung, Passkeys, Unternehmens-SSO und die Anmeldung über vertrauenswürdige Header haben unterschiedliche Voraussetzungen. [Authentifizierung](https://docs.tale.dev/de/self-hosted/configuration/authentication) erklärt die Einrichtung; [Mitglieder und Rollen](https://docs.tale.dev/de/platform/admin/members-and-roles) beschreibt die Organisationsrechte.

## Kapazität und Isolation planen

Anwendungsrollen können mehrere Replikate haben. Die CLI aktualisiert sie als gemeinsame Versionsgruppe. Während eines Upgrades laufen alte und neue Gruppe vorübergehend gleichzeitig; plane diese zusätzliche Kapazität ein. Datenbank, Objektspeicher und Sandbox-Dienste brauchen eine eigene Kapazitäts- und Wiederherstellungsplanung.

Anwendungsdatenbank, Wissensdatenbank und Dateispeicher können auf externe Infrastruktur umziehen. Eine Organisation kann außerdem eine eigene Wissensdatenbank und einen eigenen Bucket wählen. Eine geänderte Verbindung überträgt keine vorhandenen Inhalte. Plane Kopie, Umschaltung, Prüfung und Sicherungsumfang anhand von [Datenresidenz](https://docs.tale.dev/de/self-hosted/configuration/data-residency).

Selbsthosting bestimmt, wo Tale läuft. Anbieteraufrufe, Konnektoren, Webabrufe und Netzwerkzugriffe der Sandbox hängen weiterhin von deiner Konfiguration ab. Prüfe diese Ziele zusammen mit den Speicherorten unter [Härtung](https://docs.tale.dev/de/self-hosted/operate/security/hardening).

# Einen lokalen Modellserver verbinden
Source: https://docs.tale.dev/de/tutorials/admin/connect-local-provider

Verbinde einen lokalen Modellserver, wenn deine Organisation ein Modell auf eigener Infrastruktur verwenden möchte. Du brauchst einen laufenden Inferenzendpunkt, die genaue Modell-ID, Zugriff auf **Einstellungen > KI-Anbieter** und einen Betreiber, der die Netzwerkrichtlinie der Installation konfigurieren kann. Tale installiert oder lädt den Modellserver nicht für dich.

Ein lokaler Chatanbieter bestimmt das Ziel dieser Modellanfrage. Embeddings, Sprache, Werkzeuge und andere Anbieter haben eigene Wege. Diese Verbindung hält deshalb nicht automatisch den gesamten Organisationsverkehr lokal.

## Den Endpunkt mit dem Betreiber abstimmen

Lass dir Anbietername, kompatibles API-Format, Basis-URL, Modell-IDs und Anmeldemethode geben. Die Adresse muss aus den Backend-Prozessen erreichbar sein, nicht nur aus deinem Browser. Innerhalb eines Containers bezeichnet `localhost` diesen Container.

Für eine selbst gehostete Installation folgt der Betreiber [Lokale Anbieterendpunkte](https://docs.tale.dev/de/self-hosted/configuration/providers#lokale-anbieterendpunkte). Den Anbieter kannst du auch selbst unter **Einstellungen > KI-Anbieter** über **Zugangsdaten hinzufügen** > **Eigener Anbieter** anlegen ([Einen eigenen Anbieter definieren](https://docs.tale.dev/de/platform/admin/providers#einen-eigenen-anbieter-definieren)); die Schritte des Betreibers für Netzwerkzugriff und Richtlinie bleiben. Private Hosts brauchen eine ausdrückliche Freigabe in der Bereitstellung. Öffentliche Endpunkte erfordern HTTPS; unterstützte private Adressen dürfen HTTP verwenden, wenn der Betreiber diese Netzwerkkonfiguration freigibt. Ein Proxyhostname umgeht die Richtlinie für private Hosts nicht.

Ollama, LM Studio und vLLM können kompatible APIs anbieten. Entscheidend sind aber die aktivierten Serverfunktionen und das Modell. Prüfe die tatsächliche Modellliste und eine unterstützte Chatanfrage, bevor du Tale einrichtest.

## Zugangsdaten für die Organisation hinzufügen

1. Öffne **Einstellungen > KI-Anbieter** und wähle **Zugangsdaten hinzufügen**.
2. Wähle die vom Betreiber vorbereitete Anbieterdefinition oder **Eigener Anbieter**, um selbst eine anzulegen; ein von dir angelegter Anbieter trägt die Kennzeichnung **Eigener**.
3. Gib den Zugangsdaten einen passenden Namen und wähle eine unterstützte Anmeldemethode.
4. Trage den echten Servertoken oder die vom Betreiber genannte Umgebungsvariablenreferenz ein. Ignoriert der Inferenzserver die Anmeldung, stimme den nötigen Platzhalter mit seinem Betreiber ab; verwende kein fremdes Geheimnis dafür.
5. Prüfe die **Modell-Freigabeliste** und speichere. Lege die Zugangsdaten als Standard des Anbieters fest, wenn normale Aufrufe sie verwenden sollen.

<Frame caption="Anbieterzugangsdaten gehören zur Organisation; Standardauswahl und Modell-Freigabeliste beeinflussen die Modellauswahl.">

![Die Seite KI-Anbieter zeigt Zugangsdaten eines Anbieters mit Standardkennzeichnung.](https://docs.tale.dev/images/get-started/settings-providers.webp)

</Frame>

Bei vorhandenem Modellkatalog erlaubt eine leere Freigabeliste dessen Modelle. Ohne Katalog sind konkrete Modell-IDs nötig. Nutze **Kataloge aktualisieren**, wenn sich die auf dem Server verfügbaren Modelle ändern. Die Modellzugriffsrichtlinie der Organisation gilt zusätzlich.

## Eine Anfrage auf dem Server nachweisen

Beginne einen Chat und wähle das lokale Modell ausdrücklich aus. Verwende **Auto** erst später: Für diesen Test müssen Anbieter und Modell feststehen. Sende eine kurze, harmlose Anfrage, etwa „Antworte mit bereit.“

Lass den Betreiber die Anfrage im Protokoll des gewünschten Inferenzservers bestätigen. Prüfe, ob Tale eine vollständige Antwort zeigt. Gespeicherte Zugangsdaten oder eine gefüllte Modellliste beweisen weniger als eine abgeschlossene Generierung. Die Dauer hängt von Modellgröße, Hardware und Auslastung ab.

Sollen Coding-Agenten den Anbieter nutzen, wiederhole die Prüfung in einer neuen Sandbox-Sitzung mit dem gewünschten Modell und einer kompatiblen Laufzeit. Lass den Betreiber DNS, Erreichbarkeit und TLS-Vertrauen des Gateways ebenso prüfen wie beim Backend. Allgemeine Webzugriffsregeln der Sandbox richten den Modellzugriff nicht ein. Eine Chatantwort und eine Agentenantwort prüfen unterschiedliche Verbindungen.

## Einen fehlgeschlagenen Test eingrenzen

| Symptom | Prüfen |
| --- | --- |
| Anbieter fehlt in der Auswahl | Speicherort und Validierung der Definition sowie Organisationszuordnung. |
| Privater Host wird abgewiesen | Ausdrückliche Freigabe privater Anbieter in der Bereitstellung; ein DNS-Name allein ändert die Regel nicht. |
| Leere Modellliste | Modellerkennung des Servers, geladene Modelle, Freigabeliste und Modellrichtlinie. |
| Verbindungs- oder Zertifikatsfehler | Erreichbarkeit aus dem Backend, Containerhostname und TLS-Vertrauen. |
| Modell abgewiesen oder keine Antwort | Genaue Modell-ID, Anmeldung, API-Kompatibilität und Serverkapazität. |
| Chat funktioniert, aber der Agent erreicht sein Modell nicht | DNS, Erreichbarkeit und TLS-Vertrauen des Gateways, Freigabe privater Anbieter und Laufzeitkompatibilität. |

[KI-Anbieter](https://docs.tale.dev/de/platform/admin/providers) erklärt Austausch und Standardauswahl der Zugangsdaten. Halte Endpunkt und Modell-ID in der Betriebsübergabe fest, damit ein anderer Admin diesen Test nach einer Serveränderung wiederholen kann.

# Ein Besprechungsprotokoll durchsuchbar machen
Source: https://docs.tale.dev/de/tutorials/admin/meeting-transcription

Mache ein exportiertes Besprechungstranskript zur Projektquelle, die sich im Chat abfragen lässt. Beginne mit einer geprüften Textdatei und kontrolliere Zugriff und Indexierung, bevor du die Übernahme automatisierst. Du brauchst Bearbeitungsrechte im Zielprojekt und die Erlaubnis, das Transkript mit dessen Mitgliedern zu teilen.

Tale enthält weder einen eigenen Meetily-Konnektor noch einen überwachten Transkriptordner. Exportiere aus deinem Transkriptionswerkzeug und nutze anschließend den Dokumentupload oder die API von Tale. Diese Anleitung beginnt nach der Transkription; sie zeichnet keine Besprechung auf und richtet kein Transkriptionswerkzeug ein.

## Das Transkript vorbereiten

Exportiere lesbaren Text, für den ersten Test am besten als `.txt`. Prüfe Namen, Sprecherzuordnung, wichtige Zahlen und Entscheidungen anhand der Besprechungsaufzeichnung. Automatische Transkripte können gerade die Details falsch erkennen, auf die sich andere später verlassen.

Wähle einen eindeutigen Namen wie `2026-09-14-projektbesprechung.txt`. Nenne Datum, Thema und Teilnehmende auch im Text. Entferne Inhalte, die nicht für die Projektmitglieder bestimmt sind. Für den Textimport musst du die Audiodatei nicht hochladen.

## Den Leserkreis wählen

Lade das Transkript im Projektreiter **Wissen** hoch, wenn es zu diesem Projekt gehört. Die Projektmitgliedschaft steuert den Zugriff; die Suche erfolgt aus den Chats dieses Projekts. Nutze **Wissen > Dokumente** nur, wenn es unter dem passenden Teamzugriff zum Organisationswissen gehören soll.

Prüfe den Leserkreis vor dem Upload. Eine Projektdatei erscheint nicht automatisch in der Dokumentbibliothek der Organisation oder im Chat eines anderen Projekts.

## Hochladen und kontrollieren

1. Öffne das Zielprojekt und wähle **Wissen**.
2. Wähle den Zielordner und lade das Transkript über **Datei hinzufügen** hoch.
3. Öffne die Datei und prüfe Titel und lesbaren Inhalt.
4. Warte vor dem Suchtest auf **Indexiert**. **In Warteschlange** und **Wird indexiert** bedeuten, dass die Datei noch vorbereitet wird.

<Frame caption="Prüfe in der Projektdateiliste den Ablageort und den Indexierungsstatus.">

![Der Projektreiter Wissen zeigt hochgeladene Dateien mit ihrem Indexierungsstatus.](https://docs.tale.dev/images/platform/project-knowledge-files.webp)

</Frame>

Prüfe bei **Fehlgeschlagen** den Fehler und nutze nach der Behebung **Indexierung erneut versuchen**. Bei **Nicht indexiert** kannst du, sofern angeboten, **Jetzt indexieren** wählen. Anhaltende Fehler erfordern möglicherweise eine Prüfung von Speicher, Textextraktion und Embedding-Anbieter durch einen Admin. [Projektdateien verwalten](https://docs.tale.dev/de/platform/projects/manage-files) erklärt Status und Grenzen.

## Die Suche im Projekt prüfen

Öffne einen Chat im selben Projekt. Frage nach einem konkreten, zuvor geprüften Detail, etwa: „Wer hat in der Besprechung vom 14. September den nächsten Entwurf übernommen?“ Öffne die zitierte Quelle und vergleiche die Antwort mit dem Original. Ein abgeschlossener Upload beweist noch keine funktionierende Suche; eine Antwort ersetzt den Quellenvergleich nicht.

Prüfe bei vertraulichen Transkripten die Anbieterwege: Die Indexierung kann Text an einen Embedding-Anbieter senden, die Beantwortung gefundene Passagen an ein Chatmodell. Eine lokale Transkription hält diese späteren Schritte nicht automatisch lokal. Lass beide Wege vom Admin oder Betreiber prüfen.

## Die Übernahme wiederholbar machen

Für gelegentliche Besprechungen reicht die Upload-Checkliste. Für regelmäßige Übernahmen kann ein Entwickler die [Projektupload-API](https://docs.tale.dev/de/develop/api-reference) oder einen [Automatisierungs-Webhook](https://docs.tale.dev/de/tutorials/developer/trigger-automation-via-webhook) mit einer eigens eingerichteten Importautomatisierung nutzen. Ein Webhook startet diese Automatisierung; allein speichert er kein Transkript.

Die Integration muss das Projekt auswählen, doppelte Zustellungen vermeiden, die Indexierung anfordern und deren Ergebnis prüfen. Projektdateien aus der REST-API überspringen die Indexierung standardmäßig; beim Verknüpfen fordert `skipRagIndexing: false` sie an. Ein gleicher Dateiname erzeugt keine Revision. Nutze für geprüfte Versionsverläufe den vorgesehenen Ersetzungsablauf.

# Tale aus einem Skript aufrufen
Source: https://docs.tale.dev/de/tutorials/developer/call-tale-from-a-script

Sende eine Nachricht an Tale und gib die Antwort im Terminal aus. Diese Anleitung erstellt einen persönlichen Chat-Thread, prüft jede HTTP-Antwort und wartet auf den Abschluss. Du brauchst Python 3 mit seiner Standardbibliothek und curl; zusätzliche Python-Pakete sind nicht nötig.

## Zugriff vorbereiten

Du brauchst eine erreichbare Tale-Instanz, die Berechtigung zum Erstellen eines API-Schlüssels, den Slug deiner Organisation und ein direkt aufrufbares Modell. Admins und Entwickler können Schlüssel erstellen. Ein aufgelistetes Modell kann trotzdem scheitern, wenn dem Anbieterkonto Guthaben oder die nötige Freischaltung fehlt.

Öffne **Einstellungen > API > REST**, wähle **API-Schlüssel erstellen**, vergib einen Namen wie `Reporting script` und wähle ein Ablaufdatum. Wähle **Schlüssel erstellen** und kopiere den einmal angezeigten Wert. Lade ihn über deinen Secret-Manager oder eine private Shell-Umgebung in `TALE_API_KEY`; speichere ihn weder im Python-Skript noch in Git.

<Frame caption="Gib dem Schlüssel einen erkennbaren Zweck, damit du ihn gezielt widerrufen kannst.">

![Im Dialog zum Erstellen eines API-Schlüssels legst du vor der Erstellung einen Namen und die Gültigkeitsdauer fest.](https://docs.tale.dev/images/get-started/settings-api-keys.webp)

</Frame>

Setze die folgenden nicht geheimen Verbindungswerte. Verwende den Slug, nicht die Organisations-ID. Sende die Kopfzeile bei jeder Anfrage, damit das Ziel auch nach dem Beitritt zu einer weiteren Organisation eindeutig bleibt.

```bash
export TALE_BASE_URL="https://your-host.example.com"
export TALE_ORG_SLUG="your-org-slug"
export TALE_MODEL="model-id-from-the-catalog"
```

## Ein aufrufbares Modell finden

Liste die für den Schlüsselinhaber verfügbaren Modelle auf:

```bash
curl --fail-with-body --silent --show-error "$TALE_BASE_URL/api/v1/models" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG"
```

Eine `200`-Antwort enthält ein Array `models`. Setze `TALE_MODEL` auf die `id` eines Eintrags. Erscheint dieselbe ID bei mehreren Anbietern, setze zusätzlich `TALE_PROVIDER` auf den gewünschten `providerSlug`. Ein leeres Array bedeutet, dass dieses Konto kein direkt aufrufbares Modell hat. Bitte einen Admin, Zugangsdaten und Modellzugriff zu prüfen.

## Eine Nachricht senden und abwarten

Speichere den Code als `tale-chat.py` und starte `python3 tale-chat.py` in der vorbereiteten Umgebung. Das Skript erstellt einen Eintrag in deinem persönlichen Chatverlauf und kann Kosten für Modellnutzung verursachen.

```python
import json
import os
import time
from urllib.error import HTTPError
from urllib.request import Request, urlopen

base = os.environ["TALE_BASE_URL"].rstrip("/")
headers = {
    "Authorization": f"Bearer {os.environ['TALE_API_KEY']}",
    "X-Organization-Slug": os.environ["TALE_ORG_SLUG"],
    "Content-Type": "application/json",
}

def request(method, path, body=None):
    data = None if body is None else json.dumps(body).encode()
    req = Request(f"{base}/api/v1{path}", data=data, headers=headers, method=method)
    try:
        with urlopen(req, timeout=30) as response:
            raw = response.read()
            return json.loads(raw) if raw else None
    except HTTPError as error:
        detail = error.read().decode(errors="replace")
        raise SystemExit(f"HTTP {error.code}: {detail}") from error

models = request("GET", "/models")["models"]
model_id = os.environ["TALE_MODEL"]
provider = os.environ.get("TALE_PROVIDER")
candidates = [m for m in models if m["id"] == model_id
              and (not provider or m["providerSlug"] == provider)]
if len(candidates) != 1:
    raise SystemExit("Choose one available model/provider pair from GET /api/v1/models")

thread = request("POST", "/threads", {})
path = f"/threads/{thread['id']}"
sent = request("POST", f"{path}/messages", {
    "content": "In one sentence: what is Tale?",
    "model": candidates[0]["id"],
    "providerSlug": candidates[0]["providerSlug"],
})
reply_id = sent["messageId"]
deadline = time.monotonic() + 600
while True:
    generation = request("GET", f"{path}/generation")
    if generation["status"] == "idle":
        break
    if time.monotonic() >= deadline:
        request("DELETE", f"{path}/generation")
        raise SystemExit("Stopped the turn after the local 10-minute deadline")
    time.sleep(2)

if generation.get("lastMessageId") != reply_id:
    raise SystemExit("The accepted turn did not finish in this thread scope")
reply = request("GET", f"{path}/messages/{reply_id}")
if reply["status"] != "complete":
    raise SystemExit(f"Turn {reply['status']}: {reply.get('errorCode', '')} {reply.get('error', '')}")
if reply.get("finishReason") == "length":
    raise SystemExit("The reply reached its output limit; inspect it before using it")
text = "".join(part["text"] for part in reply["parts"] if part.get("type") == "text")
if not text:
    raise SystemExit("The turn completed without a text answer")
print(text)
```

Der Nachrichtenendpunkt liefert `202` und eine `messageId`, bevor die Generierung endet. Der Zustand `idle` bestätigt nur, dass der Vorgang beendet ist. Das Skript liest danach genau diese Assistentennachricht und prüft Status, Ausgabelimit und Text vor der Ausgabe.

<Tip>

Bewahre für eine weiterführende Integration die Thread-ID auf. Sende spätere Nachrichten an denselben Thread, um den Gesprächskontext zu erhalten. Ein neuer Thread bei jedem Aufruf beginnt ein neues Gespräch.

</Tip>

## Fehlgeschlagene Anfragen eingrenzen

| Ergebnis | Nächste Aktion |
| --- | --- |
| `401` | Prüfe, ob der Schlüssel abgelaufen, widerrufen oder falsch kopiert ist. |
| `400` mit `ORG_SLUG_REQUIRED` | Gib den Slug der gewünschten Organisation aus `data.organizations` an. |
| `404` mit `ORG_SLUG_INVALID` | Der Slug benennt gar keine Organisation — prüfe auf einen Tippfehler, und setze nie die Organisations-ID aus der Dashboard-URL ein. Wähle einen Slug aus `data.organizations`. |
| `403` mit `ORG_FORBIDDEN` | Die Organisation existiert, aber der Schlüsselbesitzer ist dort kein Mitglied — wähle einen Slug aus `data.organizations`. |
| `403` | Prüfe die Rechte des Schlüsselinhabers für die Aktion. |
| Kein passendes Modell | Lies `/models` erneut und wähle das genaue Paar aus Modell-ID und Anbieter. |
| `429` | Beachte `Retry-After`; siehe [Ratenlimits](https://docs.tale.dev/de/develop/rate-limits). |
| Nachrichtenstatus `failed` | Prüfe `errorCode` und behebe Konto- oder Modellprobleme vor einem erneuten Versuch. |
| Netzwerkzeitüberschreitung | Prüfe Instanz und vorhandenen Thread, bevor du erneut sendest. |

Ein POST mit Zeitüberschreitung kann bereits angenommen worden sein. Sende ihn nicht ungeprüft erneut, sondern lies zuerst Generierungsstatus und Nachrichten des Threads.

Die Frist von zehn Minuten ist eine Entscheidung dieses Beispiels, kein Serverlimit. Ein eingereihter Antwortlauf kann hinter anderen Clients warten; Reasoning kann das Modell schon vor sichtbarem Text aktiv halten. Das Skript wiederholt einen fehlgeschlagenen Versand nicht automatisch. Für unbeaufsichtigte Wiederholungen speicherst du einen `Idempotency-Key` mit 1–255 druckbaren ASCII-Zeichen zusammen mit dem Body, verwendest nach einer verlorenen Antwort beides erneut und beachtest bei `429` den Header `Retry-After`. Siehe [Nachrichten sicher erneut senden](https://docs.tale.dev/de/develop/api-reference#eine-nachricht-sicher-erneut-senden).

## Die Integration erweitern

Verwende für Projektgespräche durchgehend `/api/v1/projects/{id}/threads`: beim Erstellen sowie für Nachrichten, Generierungsstatus und Lesezugriffe. Du brauchst Zugriff auf das aktive Projekt. Ein `projectId` im Inhalt einer persönlichen Thread-Anfrage ändert den Geltungsbereich nicht.

Die [API-Referenz](https://docs.tale.dev/de/develop/api-reference) beschreibt Projektzugriff, Nachrichtenteile und Automationsläufe. Für Arbeit, die durch externe Ereignisse startet, lies [Eine Automation per Webhook auslösen](https://docs.tale.dev/de/tutorials/developer/trigger-automation-via-webhook).

# Eine Automation per Webhook auslösen
Source: https://docs.tale.dev/de/tutorials/developer/trigger-automation-via-webhook

Verbinde ein externes Ereignis mit einer veröffentlichten Automation und prüfe Annahme und fertigen Lauf. Diese Anleitung verwendet einen Projekt-Webhook, einen API-Schlüssel für Einrichtung und Abfragen sowie curl für die Zustellung. Das externe System braucht nur die Webhook-URL.

## Eine unkritische Testautomation vorbereiten

Wähle eine veröffentlichte Automation mit bestandenen Tests, deren erster Lauf weder Nachrichten sendet noch Kundendaten verändert oder andere externe Folgen hat. Eine Transformation, die ihre Eingabe zurückgibt, reicht aus. Erstelle und veröffentliche sie in der App oder über [MCP](https://docs.tale.dev/de/develop/mcp-endpoint). REST erstellt und veröffentlicht keine Automationsdefinitionen.

Nutze ein aktives Projekt mit Bearbeitungszugriff und einen API-Schlüssel mit Entwicklerrechten. Setze `TALE_BASE_URL`, `TALE_API_KEY`, `TALE_ORG_SLUG`, `TALE_PROJECT_ID` und `TALE_AUTOMATION`. Der Organisationswert ist ein Slug, der Projektwert eine ID. Ersetze `/` innerhalb von Automationsnamen in URLs durch `__`.

## Die Automation im Projekt installieren

Für Webhook-Zustellungen muss die Automation in dem Projekt installiert sein, das die URL nennt. Installiere sie mit dem Namen im Pfad und einem leeren Anfrageinhalt:

```bash
curl --fail-with-body --silent --show-error --request POST \
  "$TALE_BASE_URL/api/v1/projects/$TALE_PROJECT_ID/automations/$TALE_AUTOMATION" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG" \
  -H "Content-Type: application/json" --data '{}'
```

Die erste Installation liefert `201`, eine Wiederholung `200`. Eine Anfrage an die Sammlung `/automations` installiert nichts. Lies vor der Zustellung den Eingabevertrag der veröffentlichten Version.

## Den Trigger erstellen und schützen

Binde für die neue Testautomation einen Webhook-Trigger:

```bash
curl --fail-with-body --silent --show-error --request PUT \
  "$TALE_BASE_URL/api/v1/automations/$TALE_AUTOMATION/triggers" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG" \
  -H "Content-Type: application/json" --data '{"kind":"webhook"}'
```

Kopiere das zurückgegebene `token` in die private Umgebungsvariable `TALE_WEBHOOK_TOKEN`. Tale zeigt den Klartext nur beim Erstellen oder Rotieren. Ein späterer Lesezugriff kann ihn nicht wiederherstellen.

<Warning>

Die URL ist ein Zugangsmittel. Wer sie kennt, kann Zustellungen senden. Halte sie aus Quellcode, Screenshots und öffentlichen Protokollen heraus. Ein Webhook ersetzt eine vorhandene Trigger-Art derselben Automation; verwende dafür die ausgewählte Testautomation.

</Warning>

Der Trigger folgt dem Automationsnamen und nutzt die veröffentlichte Version. Ein späterer Release kann deshalb ändern, was dieselbe URL ausführt. Rotiere oder entferne einen geleakten Trigger. Deaktivieren pausiert ihn nur; erneutes Aktivieren stellt dasselbe Token wieder her.

## Eine Zustellung senden

Sende das Testereignis mit einer stabilen Zustellungs-ID:

```bash
curl --fail-with-body --silent --show-error \
  "$TALE_BASE_URL/api/projects/$TALE_PROJECT_ID/automations/webhook/$TALE_WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-paid" \
  --data '{"orderId":"12345","amount":199.0}'
```

Die Annahme liefert `202` mit `runId`. Speichere die ID als `TALE_RUN_ID`. Die Automation erhält `{"trigger":"webhook","payload":<body>}`; die Bestell-ID liegt also unter `input.payload.orderId`. Ein Eingabeschema muss diese Hülle beschreiben.

Wiederhole denselben Befehl. Innerhalb des Deduplizierungsfensters bleibt `runId` gleich und `duplicate: true` kommt hinzu; kein zweiter Lauf startet. IDs bleiben 24 Stunden gespeichert. Ohne ID-Kopfzeile werden identische Anfragebytes nur innerhalb von zwei Minuten zusammengefasst. Verwende für ein neues Ereignis eine neue ID.

## Das Laufergebnis prüfen

Lies den Lauf mit deinem API-Schlüssel im selben Projekt:

```bash
curl --fail-with-body --silent --show-error \
  "$TALE_BASE_URL/api/v1/projects/$TALE_PROJECT_ID/runs/$TALE_RUN_ID" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG"
```

Warte auf einen Endstatus und prüfe `output` und `trace`. Bei der Testautomation, die Eingaben zurückgibt, müssen Bestell-ID und Betrag mit deiner Zustellung übereinstimmen. Die `202`-Antwort allein bestätigt dieses Ergebnis nicht.

Lies bei einem fehlgeschlagenen Lauf `failureCode` und `detail`, den betroffenen Knoten sowie bereits ausgeführte Aktionen. Dieselbe Zustellungs-ID liefert den ursprünglichen Lauf zurück, auch wenn er fehlgeschlagen ist; sie wiederholt seine Arbeit nicht. Eine andere ID startet neue Arbeit. Prüfe deshalb zuerst, ob bereits abgeschlossene Knoten gefahrlos erneut laufen dürfen.

## Zustellungen wiederaufnehmen

| Antwort | Behebung |
| --- | --- |
| `400` | Lies `code` und Eingabeprobleme. Korrigiere die Datenhülle oder entferne einen Query-Parameter `projectId`. |
| `403` | Prüfe aktives Projekt und Installation der Automation darin. |
| `404` | Prüfe Token und Aktivierung. Der Endpunkt verrät nicht, welches davon falsch ist. |
| `409` | Lies `code`: Veröffentliche eine Version, korrigiere den URL-Kontext oder löse den Zustellungskonflikt. |
| `413` | Verkleinere den Inhalt auf unter 256 KiB oder sende eine Referenz. |
| `429` | Warte gemäß `Retry-After` und wiederhole mit derselben Zustellungs-ID. |

Wiederhole Netzwerkfehler und vorübergehende Serverfehler mit begrenztem Backoff und derselben ID. Behebe andere Clientfehler zuerst; wiederholte ungültige Anfragen reparieren keine Konfiguration. Entferne den Testtrigger, wenn du seine URL nicht mehr brauchst. Die [Webhook-Referenz](https://docs.tale.dev/de/develop/webhooks) nennt alle ID-Kopfzeilen, Rotationsregeln und Limits.

# Deinen ersten Agenten erstellen
Source: https://docs.tale.dev/de/tutorials/editor/first-agent-end-to-end

Erstelle einen Agenten, der eine Kontaktnachricht zusammenfasst und einen nächsten Schritt empfiehlt. Diese Übung nutzt die Aufgabenbeschreibung als Eingabe. So kannst du den gesamten Ablauf prüfen, bevor Connectoren oder gemeinsames Wissen hinzukommen: Agent einrichten, eine Aufgabe starten und das Ergebnis prüfen.

## Bevor du beginnst

Du brauchst ein Projekt mit Bearbeitungszugriff, einen verfügbaren Coding-Agent-Harness mit passenden Modellzugangsdaten und eine funktionierende Sandbox-Zuteilung. Ein Administrator verwaltet [KI-Anbieter](https://docs.tale.dev/de/platform/admin/providers) und [Sandboxes](https://docs.tale.dev/de/platform/admin/sandboxes). Dass ein Modell im Chat funktioniert, genügt allein nicht: Der gewählte Harness muss seine Zugangsdaten verwenden können.

Fehlen die Agentenseite oder die Modellauswahl, kläre zuerst Zugriff und Einrichtung. Für diese Übung sind keine Skills, Connectoren, Plattform-Tools oder eingeblendeten Secrets nötig.

## Den Agenten erstellen

Öffne **Agenten** im Projekt und klicke auf **Neuer Agent**.

<Frame caption="Die Agententabelle zeigt Harness, Provider und Modell jedes Agenten.">

![Website relaunch listet Content editor mit Claude Code und Redirect auditor mit Codex samt Provider und Modell neben Neuer Agent.](https://docs.tale.dev/images/platform/project-agents-models.webp)

</Frame>

1. Gib unter **Name** `Triage-Assistent` ein.
2. Wähle eine **Agent-Laufzeit**, die dein Administrator eingerichtet hat.
3. Suche unter **Modell** nach Modellname oder API-ID und wähle den Eintrag des gewünschten Providers. Dasselbe Modell kann von mehreren Providern angeboten werden.
4. Entferne unter **Skills, Connectors & Tools** die Häkchen bei vorausgewählten Dokument-Skills und lass **Secrets** für diese Übung leer.
5. Füge die folgenden Anweisungen unter **Anweisungen** ein und klicke auf **Agent erstellen**.

```text
Lies die Kontaktnachricht in der Aufgabenbeschreibung. Antworte in zwei Zeilen:
Zusammenfassung: ein Satz darüber, was die Person benötigt.
Nächster Schritt: antworten, eskalieren oder schließen, mit kurzer Begründung.
Enthält die Nachricht kein verwertbares Anliegen, nenne die fehlende Information.
Kontaktiere niemanden und ändere keine Datensätze.
```

Der neue Agent kann sofort einer Aufgabe zugewiesen werden. Eine gesonderte Veröffentlichung gibt es nicht. Seine Anweisungen beschreiben die wiederkehrende Arbeit; die einzelne Nachricht gehört in die Aufgabe.

## Eine Aufgabe mit prüfbarer Antwort übergeben

Öffne **Aufgaben**, erstelle `Anfrage nach Rechnungskopie einordnen` und füge diese Beschreibung ein:

```text
Kontaktnachricht:
„Hallo, ich habe die Bestellbestätigung erhalten, finde aber die Rechnung
nicht. Könnt ihr mir eine Kopie schicken? Die Bestellnummer ist A-1042.“

Abnahmekriterien:
- Fasse das Anliegen in einem Satz zusammen.
- Empfiehl antworten, eskalieren oder schließen und begründe die Wahl.
- Behaupte nicht, dass die Rechnung bereits verschickt wurde.
```

Weise die Aufgabe `Triage-Assistent` zu. Lege in den Details einen **Reviewer** fest, wenn jemand anderes prüfen soll; andernfalls erhält der Ersteller der Aufgabe die Prüfanfrage. Klicke auf **Agent starten**. Die Zuweisung allein startet keine Arbeit.

Die Aufgabe wechselt zu **In Bearbeitung**. Ein erfolgreicher Lauf veröffentlicht seinen Bericht als Kommentar und verschiebt sie nach **In Prüfung**. Damit er abschließen kann, müssen Sandbox und Provider funktionieren.

## Das Ergebnis prüfen und verbessern

Vergleiche den Agentenkommentar mit den Abnahmekriterien. Eine passende Antwort erkennt die Bitte um eine Rechnungskopie und empfiehlt eine Antwort. Sie darf nicht behaupten, eine E-Mail sei verschickt worden. Die Formulierung kann je nach Modell abweichen.

Setze die Aufgabe auf **Erledigt**, wenn du das Ergebnis akzeptierst. Fehlt etwas, erwähne den zugewiesenen Agenten in einem Aufgabenkommentar und formuliere eine konkrete Korrektur: „Fasse das Anliegen in nur einem Satz zusammen und begründe, warum eine Antwort nötig ist.“ Die Nacharbeit setzt das Aufgabengespräch fort und liefert ein neues Ergebnis zur Prüfung.

<Tip>

Nutze einen Aufgabenkommentar für eine einmalige Korrektur. Ändere die Agentenanweisungen, wenn dieselbe Regel auch für künftige Aufgaben gelten soll. Ergänze Tools erst, wenn eine spätere Übung das Lesen oder Ändern von Informationen außerhalb der übergebenen Eingabe braucht.

</Tip>

## Wenn der Lauf nicht startet oder abschließt

Bei einem fehlenden Modell müssen Provider und Harness geprüft werden. Bei einem Sandbox-Fehler prüft ein Administrator Kapazität und Infrastruktur. Ein fehlgeschlagener Aufgabenlauf bleibt zur Untersuchung sichtbar. Behebe die Ursache, bevor du ihn wiederholst, und starte nicht erneut, solange bereits ein Lauf aktiv ist.

[Aufgaben automatisieren](https://docs.tale.dev/de/platform/projects/task-automation) erklärt Wiederholung, Abbruch, Übergabe zur Prüfung und Nacharbeit. [Projektagenten](https://docs.tale.dev/de/platform/projects/project-agents) beschreibt die Ausstattung, die du nach dieser ersten erfolgreichen Aufgabe ergänzen kannst.

# Einen Workflow mit Freigabe erstellen
Source: https://docs.tale.dev/de/tutorials/editor/workflow-with-approvals

Diese Übung erstellt einen Workflow mit zwei Schritten: eine Nachricht vorbereiten und die Erlaubnis zum Senden anfordern. Du prüfst Empfänger und Text im wartenden Lauf und lehnst die Aktion ab. So lernst du den vollständigen Freigabeablauf kennen, ohne eine echte Nachricht zustellen zu müssen.

## Bevor du beginnst

Nutze ein Konto mit der Rolle Entwickler, Admin oder Inhaber. Prüfe, dass die Freigaberichtlinie deiner Organisation für `imap-smtp.send` eine Entscheidung verlangt. Das ist die Standardeinstellung. Eine eigene Richtlinie kann sie ändern. Lies deshalb vor dem Live-Teil [Freigaben konfigurieren](https://docs.tale.dev/de/platform/approvals/configure).

Der Mock-Test braucht keine Postfach-Zugangsdaten. Für einen tatsächlich freigegebenen Versand wären ein eingerichteter IMAP-/SMTP-Connector und ein beabsichtigter Empfänger nötig. Diese Übung endet mit **Ablehnen**.

## Das Beispiel importieren

Speichere den folgenden Inhalt als `workflow.yml`. Der Knoten `draft` liefert festen Text, damit das Ergebnis leicht prüfbar ist. `send` liest ihn; diese Referenzen erzeugen die Verbindung auf dem Canvas.

```yaml
version: 1
name: docs/approval-check
description: Practice reviewing an outgoing message before it is sent.
nodes:
  - id: draft
    type: transform
    code: |
      return {
        subject: "Approval practice",
        text: "This is a test message for the approval walkthrough."
      };
  - id: send
    type: imap-smtp.send
    input:
      to: reviewer@example.com
      subject: '{{ nodes.draft.output.subject }}'
      text: '{{ nodes.draft.output.text }}'
output:
  messageId: '{{ nodes.send.output.messageId }}'
tests:
  - name: prepares the outgoing message
    input: {}
    expect:
      effects:
        - connector: imap-smtp.send
```

1. Öffne **Automatisierungen > Automatisierung erstellen > Paket hochladen**.
2. Wähle `workflow.yml` und belasse **Installieren in** auf **Organisation**.
3. Klicke auf **Paket hochladen**. Tale validiert das Dokument und speichert `docs/approval-check` als Entwurf.
4. Wähle in der Veröffentlichungsfrage **Später** und öffne anschließend **Approval check** in der Liste. Die Automatisierung öffnet sich im Tab **Editor**.

Existiert der Name bereits, fügt der Upload eine weitere Version hinzu. Wähle einen anderen Workflow-`name`, wenn die Übung getrennt bleiben soll.

<Frame caption="Paket hochladen nimmt die Workflow-Datei an und bietet Organisation oder Projekt als Ziel an.">

![Der Dialog Paket hochladen zeigt die Dateiauswahl und den Zielwähler mit Organisation.](https://docs.tale.dev/images/platform/automations-upload-dialog.webp)

</Frame>

## Den Datenfluss testen

Klicke im **Editor** auf **Testlauf**. Dieses Beispiel braucht keine Laufzeiteingabe und kann mit einem leeren Objekt laufen. Wechsle zu **Läufe**. Dort sollte ein **Erfolgreich** abgeschlossener Test erscheinen.

Öffne den Lauf und prüfe auf dem Canvas, ob beide Knoten ausgeführt wurden. Wähle `send` und prüfe die aufgelöste Eingabe. Der Empfänger muss `reviewer@example.com` sein, der Betreff `Approval practice` und der Text der Satz aus `draft`. In diesem Modus antwortet ein deterministischer Mock des Connectors. Es wird keine E-Mail gesendet und keine Freigabekarte angezeigt.

Der Workflow enthält einen Test, der den Effekt `imap-smtp.send` erwartet. Ein erfolgreicher Mock prüft Ablauf und vorgesehenen Aufruf. Er belegt weder gültige Postfach-Zugangsdaten noch die Zustellung.

## Die Live-Freigabe prüfen

Kehre zum **Editor** zurück und klicke auf **v1 live schalten**, um die getestete Version live zu schalten. Lass den Trigger unkonfiguriert; diese Übung startet einmal von Hand.

Wähle **Live ausführen**, lies Bestätigung und Organisationsumfang und bestätige. Wechsle zu **Läufe** und öffne den neuen wartenden Lauf. Die Freigabekarte sollte die ausstehende Entscheidung, `imap-smtp.send`, den Knoten `send` sowie dessen geplante Eingabe zeigen. Empfänger, Betreff und Text müssen dem Mock-Test entsprechen.

Wartet der Lauf nicht, prüfe Status und Richtlinie, bevor du fortfährst. Ein fehlgeschlagener Connector-Aufruf beweist nicht, dass eine Freigabe angefordert wurde.

## Ablehnen und das Ergebnis prüfen

Klicke auf der Karte auf **Ablehnen**. Die Aktion wird verweigert und der Lauf endet als **Fehlgeschlagen**. Das ist das erwartete Ergebnis dieser Übung: Der Workflow hat die menschliche Entscheidung erreicht und die Nachricht nicht gesendet.

Die Parameter eines wartenden Aufrufs lassen sich auf der Karte nicht ändern. Ist eine echte vorgeschlagene Nachricht falsch, lehne sie ab, korrigiere Definition oder Eingabe und starte einen neuen Lauf. Die spätere Freigabe eines korrekten Aufrufs erlaubt die tatsächliche Aktion; sie bestätigt nicht nur, dass du die Karte gelesen hast.

Braucht ein Agent eine Antwort statt einer Erlaubnis, nutzt er `ask_human`. Diese andere Form des Wartens erklärt [Freigaben in Workflows](https://docs.tale.dev/de/platform/automations/approvals-in-workflows). [Ausführungsprotokolle](https://docs.tale.dev/de/platform/automations/execution-logs) hilft, beide von einem noch arbeitenden Agenten zu unterscheiden.

# Eine nützliche Chat-Antwort erhalten
Source: https://docs.tale.dev/de/tutorials/member/chat-effectively

Eine nützliche Chat-Antwort beginnt mit einer klaren Frage und endet mit einer Quellenprüfung. Nutze für diese Übung ein kurzes Dokument, das du hochladen darfst. Frage nach einer enthaltenen Information und prüfe anschließend, ob der Assistent zwischen belegten Aussagen und offenen Punkten unterscheidet.

Du brauchst Zugriff auf Chat und ein verfügbares Modell. Für Dokumentfragen muss außerdem die Wissensindexierung der Organisation funktionieren. Ein geeignetes, bereits indexiertes Dokument kannst du statt des Beispiels verwenden.

## Eine kleine Quelle vorbereiten

Speichere diesen Text auf deinem Gerät als `launch-brief.txt`:

```text
Briefing zur neuen Website
Die Kundenprüfung findet am 18. September 2026 statt.
Maya Chen ist für die Prüfliste zuständig.
Der Veröffentlichungstermin ist noch nicht freigegeben.
Die Prüfung muss Barrierefreiheit, Weiterleitungen und das Kontaktformular abdecken.
```

Öffne einen neuen Chat und hänge die Datei über **Fotos & Dateien hinzufügen** im Menü des Nachrichtenfelds an. Warte auf das Ende von Upload und Indexierung, bevor du zum Text fragst. [Chat-Anhänge](https://docs.tale.dev/de/platform/chat/attachments) erklärt die angezeigten Zustände.

## Nach einem konkreten Ergebnis fragen

Sende:

```text
Nenne anhand von launch-brief.txt den Prüftermin, die zuständige Person und
die drei Prüfthemen. Belege die Antwort mit der Quelle. Nutze vier Stichpunkte.
```

Die Frage nennt Quelle, benötigte Informationen und Ergebnisform. Dadurch lässt sich die Antwort leichter prüfen als bei „Erzähl mir etwas über die neue Website“. **Auto** eignet sich als Ausgangspunkt. Wähle ein Modell ausdrücklich, wenn du sein Verhalten mit einem anderen vergleichen möchtest.

<Frame caption="Behalte die Frage im Blick, während du prüfst, ob die Antwort sie erfüllt.">

![Ein Chat zeigt eine gezielte Frage zum Onboarding-Feedback und eine tabellarisch gegliederte Antwort.](https://docs.tale.dev/images/platform/chat-thread-reply.webp)

</Frame>

## Die Antwort mit der Datei vergleichen

Der Prüftermin muss der **18. September 2026** sein, die zuständige Person **Maya Chen**. Die Themen sind **Barrierefreiheit, Weiterleitungen und das Kontaktformular**. Öffne die zitierte Quelle und vergleiche diese Angaben. Die Formatierung darf variieren, die Fakten nicht.

Fehlt ein Beleg, bitte um eine Quellenangabe zum Dokument, statt anzunehmen, dass der Anhang gelesen wurde. Findet der Assistent den Inhalt nicht, prüfe den Indexierungsstatus und versuche es erneut, sobald die Datei bereit ist. Eine flüssige Antwort beweist keinen Quellenabruf.

## Mit einer Rückfrage Unsicherheit sichtbar machen

Frage im selben Gespräch:

```text
Wann ist der freigegebene Veröffentlichungstermin? Falls das Briefing
keinen nennt, sage das ausdrücklich.
```

Die Quelle nennt **keinen** freigegebenen Veröffentlichungstermin. Eine gute Antwort bewahrt diesen Unterschied, statt den Prüftermin als Veröffentlichungstermin zu übernehmen. Macht die Antwort eine unbelegte Annahme, verweise auf den widersprechenden Satz und bitte um Korrektur.

<Tip>

Ändere jeweils einen Teil deiner Frage. „Kürzer“ prüft die Länge; „Trenne bestätigte Termine von offenen Entscheidungen“ prüft das Verständnis. Wenn du Quelle, Modell, Frage und Format gleichzeitig änderst, lässt sich kaum erkennen, was die Antwort verbessert hat.

</Tip>

## Den nützlichen Kontext behalten

Setze verwandte Fragen im selben Chat fort. Beginne bei einem neuen Thema einen neuen Chat, damit frühere Annahmen nicht ablenken. Brauchen mehrere Gespräche dasselbe Briefing, lege es in einem [Projekt](https://docs.tale.dev/de/tutorials/member/use-projects) ab und nutze Projektchats.

Lies vor dem [Teilen eines Chats](https://docs.tale.dev/de/platform/chat/shared-threads) die Nachrichten und Quellenzitate in der Antwort durch. Soll als Nächstes ein Ergebnis mit Zuständigkeit und Prüfung entstehen, erstelle eine [Projektaufgabe](https://docs.tale.dev/de/platform/projects/tasks) mit den geprüften Angaben und Abnahmekriterien.

# Ein Projekt für gemeinsamen Kontext nutzen
Source: https://docs.tale.dev/de/tutorials/member/use-projects

Ein Projekt hält Dateien, Anweisungen, Gespräche und Aufgaben zu einer Arbeit zusammen. In dieser Anleitung stellst du eine Frage, die eine Referenzdatei des Projekts beantwortet, teilst das hilfreiche Gespräch und übergibst das daraus folgende Ergebnis einem Agenten des Projekts. Plane etwa fünfzehn Minuten ein, zuzüglich der Zeit für die Indexierung und den Lauf des Agenten.

## Bevor du beginnst

Als **Mitglied** arbeitest du in den Projekten, die mit dir geteilt sind: Du stellst Fragen in ihren Chats, teilst Gespräche und legst Aufgaben für die Agenten des Projekts an. Nimm ein Projekt, das du öffnen kannst, mit einer indexierten Referenzdatei, und beginne bei [Eine Frage stellen und die Quelle prüfen](https://docs.tale.dev/de/tutorials/member/use-projects#eine-frage-stellen-und-die-quelle-pruefen). Ein Projekt ohne eigene Agenten übergibt seine Aufgaben dem [Standard-Agenten](https://docs.tale.dev/de/platform/projects/project-agents#standard-agent) der Organisation, sofern ein Admin ihn nicht ausgeschaltet hat. Um ein Projekt zu erstellen, Dateien hochzuladen, Anweisungen zu speichern und Agenten anzulegen, brauchst du die Rolle **Redakteur** oder höher; richtest du das Projekt ein, beginne bei [Das Projekt einrichten](https://docs.tale.dev/de/tutorials/member/use-projects#das-projekt-einrichten). Du brauchst ein kurzes Textdokument, eine PDF mit auswählbarem Text oder eine Datei in einem modernen Office-Format. Wähle eine Quelle, deren Angaben du nachprüfen kannst, etwa ein Projektbriefing mit einer verantwortlichen Person und einem Prüftermin. Ein Admin muss den Dateispeicher und ein Embedding-Modell für durchsuchbare Uploads eingerichtet haben.

Neue Projekte sind **Organisationsweit** sichtbar. Verwende für diese Anleitung keine vertraulichen Unterlagen. Soll das spätere Projekt nur bestimmten Teams zugänglich sein, lege das zuständige Team unter **Allgemein > Freigabe** fest, bevor du Dateien hochlädst. Projektchats bleiben persönlich, bis du sie teilst.

## Das Projekt einrichten

Redakteure und höhere Rollen erledigen das einmal pro Projekt. Mitglieder springen zu [Eine Frage stellen und die Quelle prüfen](https://docs.tale.dev/de/tutorials/member/use-projects#eine-frage-stellen-und-die-quelle-pruefen).

### Das Projekt erstellen

1. Klicke im Bereich **Start** auf **Neues Projekt**, das Ordnersymbol neben **Projekte**.
2. Gib unter **Projektname** einen eindeutigen Namen ein, etwa `Website-Relaunch`.
3. Prüfe das **Projektkürzel**. Es bildet den Anfang von Aufgabenkennungen wie `WEB-1` und lässt sich nach dem Erstellen nicht mehr ändern.
4. Ergänze bei Bedarf eine **Beschreibung** und klicke auf **Projekt erstellen**.

Das neue Projekt öffnet sich unter **Aufgaben** und erscheint im Bereich **Start** unter **Projekte**. Neben **Aufgaben** findest du im Projekt **Allgemein**, **Chats**, **Wissen** und **Agenten**. Für einen Projektchat musst du keinen Agenten anlegen.

### Eine Referenzdatei hochladen

Öffne **Wissen** im Projekt und klicke auf **Datei hinzufügen** oder ziehe die Datei auf die Upload-Fläche. Die Datei erscheint im Projektdateibaum. Warte auf **Indexiert**, bevor du dich auf die Suche verlässt. **In Warteschlange** und **Wird indexiert…** bedeuten, dass die Vorbereitung noch läuft.

<Frame caption="Unter Wissen liegen die Referenzdateien des Projekts. Der Status neben jeder Datei zeigt, ob sie durchsuchbar ist.">

![Im Bereich Wissen des Projekts Website relaunch stehen zwei indexierte Dateien sowie Schaltflächen zum Hinzufügen von Dateien und Ordnern.](https://docs.tale.dev/images/platform/project-knowledge-files.webp)

</Frame>

Eine hier hochgeladene Datei gehört zu diesem Projekt. Stelle Fragen dazu in einem Projektchat. Der allgemeine Chat der Organisation durchsucht keine Projektdateien.

### Anweisungen für alle Projektchats hinterlegen

Öffne **Allgemein** und beschreibe unter **Anweisungen** den Kontext oder die Regeln, die für jeden Chat gelten sollen. Zum Beispiel:

> Nutze bei Fragen zu diesem Launch die Projektdateien. Nenne die Quelle für Termine und Entscheidungen. Falls kein Launch-Termin genehmigt wurde, kennzeichne ihn als unbestätigt.

Klicke oben auf **Speichern**. Die Anweisungen gehören zum Kontext der Projektchats. Die zugrunde liegenden Dokumente musst du trotzdem hochladen; der Assistent muss sie für seine Antwort abrufen.

<Frame caption="Die Anweisungen stehen unter Allgemein neben Projektname und Beschreibung.">

![Die Registerkarte Allgemein enthält Projektname, Beschreibung, den Editor für Anweisungen und den Bereich Freigabe sowie Speichern und Verwerfen in der Kopfzeile.](https://docs.tale.dev/images/platform/project-general-tab.webp)

</Frame>

Im letzten Teil dieser Anleitung geht eine Aufgabe an einen Agenten: an einen eigenen des Projekts oder, solange es keinen hat, an den [Standard-Agenten](https://docs.tale.dev/de/platform/projects/project-agents#standard-agent) der Organisation. [Projekt-Agenten](https://docs.tale.dev/de/platform/projects/project-agents) erklärt, wie du einen anlegst.

## Eine Frage stellen und die Quelle prüfen

Öffne **Chats** und klicke auf **Neuer Chat**. Lass die Modellauswahl auf **Auto**, sofern verfügbar, und stelle eine Frage, die deine Datei beantwortet. Bei einem Launch-Briefing etwa:

> Lies das Launch-Briefing. Wer ist für die Prüfung zuständig, und welche Termine stehen fest? Nenne die Datei als Quelle und unterscheide bestätigte Termine von offenen Entscheidungen.

Prüfe die Such- und Leseschritte über der Antwort und vergleiche die Angaben mit der Datei. Eine flüssige Antwort ohne passende Quelle belegt nicht, dass Tale das Dokument verwendet hat. Öffne bei Bedarf das Original unter **Wissen**.

<Tip>

Nenne die Datei und eine konkrete Frage. „Welcher Prüftermin ist im Launch-Briefing bestätigt?“ gibt dem Assistenten ein klareres Suchziel als „Erzähl mir etwas über das Projekt“.

</Tip>

## Einen hilfreichen Chat teilen

Die Registerkarte **Chats** unterscheidet **Deine Chats** und **Mit Projekt geteilt**. Aktiviere **Mit Projekt teilen**, wenn die Personen mit Projektzugriff den Chat lesen sollen. Das Hochladen von Projektdateien gibt deine Chats nicht automatisch frei.

Für einen einzelnen Link zu einer Momentaufnahme für Organisationsmitglieder lies [Geteilte Chats](https://docs.tale.dev/de/platform/chat/shared-threads). Prüfe den Text vor der Freigabe: Er kann Angaben aus Quellen enthalten, die nur einem kleineren Personenkreis zugänglich sind.

## Die Folgearbeit einem Projekt-Agenten übergeben

Der Chat beantwortet Fragen, erstellt aber keine Dateien. Soll aus der Antwort ein Dokument werden, etwa eine einseitige Launch-Zusammenfassung, übergib die Arbeit mit einer Aufgabe einem Agenten des Projekts.

1. Wähle im Kopf des Gesprächs **Aufgabe erstellen**. Weil der Chat zu diesem Projekt gehört, öffnet sich **Aufgabe erstellen** dort, mit deiner letzten Frage als Beschreibung, einem Link zurück zum Chat und den Dateien, die du angehängt hast.
2. Formuliere die Beschreibung als gewünschtes Ergebnis, zum Beispiel: `Erstelle aus dem Briefing eine einseitige Launch-Zusammenfassung als Word-Dokument. Nenne für jeden Termin das Briefing als Quelle.`
3. Wähle unter **Zuständig** einen Agenten des Projekts, falls noch keiner eingetragen ist; in einem Projekt ohne eigene Agenten ist der Standard-Agent schon eingetragen. Klicke dann auf **Erstellen und Agent starten**.
4. Verfolge den Lauf über dem Nachrichtenfeld des Chats; **Öffnen** führt dich dort zur Aufgabe.

Wenn der Lauf endet, steht der Bericht des Agenten in den Kommentaren der Aufgabe, die Datei unter **Ergebnisdateien**, und die Aufgabe wartet auf **In Prüfung**. Erwähne den Agenten mit `@` in einem Kommentar, um Änderungen zu erbitten, und setze die Aufgabe auf **Erledigt**, wenn das Ergebnis der Beschreibung entspricht.

Wer ein Projekt öffnen kann, legt darin Aufgaben an. Ein Lauf, den ein Mitglied startet, bleibt bei dieser Aufgabe und ihren Unteraufgaben und arbeitet ohne die Secrets des Agenten; [Agentenläufe, die ein Mitglied startet](https://docs.tale.dev/de/platform/projects/tasks#agentenlaeufe-die-ein-mitglied-startet) zählt die Grenzen auf.

## Wenn die Datei in der Antwort fehlt

| Beobachtung | Prüfung |
| --- | --- |
| Der Upload scheitert, bevor eine Zeile erscheint | Versuche es mit einer kleinen Datei in einem unterstützten Format. Scheitert auch das, bitte einen Admin, Dateispeicher und Upload-Regeln zu prüfen. |
| **In Warteschlange** oder **Wird indexiert…** | Warte auf das Ende der Verarbeitung und stelle die Frage erneut. |
| **Fehlgeschlagen** | Nutze **Indexierung erneut versuchen**. Wiederholt sich der Fehler, sollte ein Admin Embedding-Modell und Wissensdienst prüfen. |
| **Nicht indexiert** | Nutze **Jetzt indexieren**, sofern angeboten. Hat eine alte Office-Datei keinen unterstützten Textextraktor, speichere sie im modernen Format neu. |
| **Indexiert**, aber keine passende Quelle in der Antwort | Prüfe, ob der Chat zu diesem Projekt gehört. Nenne die Datei und frage nach einer einzelnen Angabe. Vergleiche die Antwort mit dem Original. |

Das Projekt hält jetzt Quellen, Gespräche und Aufgaben zusammen. [Aufgaben auf dem Projektboard verwalten](https://docs.tale.dev/de/platform/projects/tasks) beschreibt Board, Prüfung und wiederkehrende Arbeit.

# Tutorials
Source: https://docs.tale.dev/de/tutorials/overview

Wähle eine Aufgabe, die du in deinem Arbeitsbereich ausprobieren möchtest. Jedes Tutorial nennt den Ausgangspunkt, liefert Beispiele und zeigt, woran du den Erfolg erkennst. Wenn du Tale noch nicht kennst, beginne mit [deinem ersten Chat](https://docs.tale.dev/de/get-started/quickstart).

## Beginne mit der täglichen Arbeit

<CardGroup cols="2">

<Card title="Eine hilfreiche Chatantwort erhalten" icon="message-circle" href="https://docs.tale.dev/de/tutorials/member/chat-effectively">

Gib dem Modell den nötigen Kontext, verfeinere die Antwort und prüfe das Ergebnis vor der Verwendung.

</Card>

<Card title="Arbeit in einem Projekt organisieren" icon="folder" href="https://docs.tale.dev/de/tutorials/member/use-projects">

Führe eine Aufgabe, eine Quelldatei und Projektanweisungen zusammen. Entscheide, was dein Team sehen soll.

</Card>

</CardGroup>

## Abläufe erstellen und Systeme verbinden

Für diese Tutorials brauchst du zusätzliche Rechte oder einen eingerichteten Dienst. Prüfe zuerst die Voraussetzungen auf der jeweiligen Seite. Ein gewöhnlicher Chat benötigt keine Agent-Laufzeit.

| Dein Ziel | Tutorial | Voraussetzungen |
| --- | --- | --- |
| Eine Projektaufgabe delegieren | [Den ersten Agenten ausführen](https://docs.tale.dev/de/tutorials/editor/first-agent-end-to-end) | Rechte zum Einrichten von Projektagenten, ein Modell und eine funktionierende Agent-Laufzeit |
| Eine Workflow-Aktion vor der Ausführung prüfen | [Einen Workflow mit Freigaben erstellen](https://docs.tale.dev/de/tutorials/editor/workflow-with-approvals) | Bearbeitungsrechte für Automatisierungen und eine freigabeberechtigte Person |
| Eine Nachricht aus einem eigenen Programm senden | [Tale per Skript aufrufen](https://docs.tale.dev/de/tutorials/developer/call-tale-from-a-script) | Eine laufende Instanz, ein Modell, ein API-Schlüssel und Python |
| Eine Automatisierung aus einem anderen System starten | [Eine Automatisierung per Webhook auslösen](https://docs.tale.dev/de/tutorials/developer/trigger-automation-via-webhook) | Eine veröffentlichte Automatisierung und sicher gespeicherte Webhook-Zugangsdaten |
| Einen lokalen Modellserver verbinden | [Einen lokalen Anbieter verbinden](https://docs.tale.dev/de/tutorials/admin/connect-local-provider) | Verwaltungsrechte und ein von Tale erreichbarer Modellserver |
| Ein Besprechungstranskript durchsuchbar machen | [Transkripte einem Projekt hinzufügen](https://docs.tale.dev/de/tutorials/admin/meeting-transcription) | Ein geprüftes Transkript, Bearbeitungsrechte im Projekt und eine funktionierende Dokumentindexierung |

## Während der Arbeit nachschlagen

Die [Plattformanleitungen](https://docs.tale.dev/de/platform) erklären einzelne Funktionen und ihre Grenzen. Die [Self-hosted-Dokumentation](https://docs.tale.dev/de/self-hosted) behandelt Betrieb und Serverkonfiguration. Die [Entwicklerdokumentation](https://docs.tale.dev/de/develop/overview) beschreibt APIs und Beiträge zum Quellcode.

# Episode 5 — Automatisierungen & Freigaben
Source: https://docs.tale.dev/de/tutorials/videos/automations-and-approvals

Am Ende dieser Episode hast du eine Automatisierung wirklich benutzt: Du liest den installierten Triage-Workflow, bevor du ihm vertraust, erstellst eine Aufgabe und siehst zu, wie sie vor der Kamera bewertet und zugewiesen wird, verfolgst diesen Lauf in seinem Journal, öffnest den fehlgeschlagenen und gehst ihm bis zu seinem Schritt nach — und gibst eine ausgehende Kundenmail mit deinem eigenen Klick frei. Sekunden später findest du die Entscheidung im Audit-Log. Schritt für Schritt, in einem Tempo zum Mitmachen. Die Freigabe-Szene wurde auf der früheren Version aufgenommen, wo die Karte im Chat saß und vor dem Absenden angepasst werden konnte; in dieser Version parkt ein abgefangener Connector-Schreibzugriff den Lauf, und die Karte — **Freigeben** oder **Ablehnen**, ohne Bearbeiten — sitzt auf der Detailseite des Laufs.

<Video src="https://docs.tale.dev/videos/de/tutorials/ep5-automations/ep5-automations.de.mp4" poster="https://docs.tale.dev/videos/de/tutorials/ep5-automations/ep5-automations.de.webp" captions="https://docs.tale.dev/videos/de/tutorials/ep5-automations/ep5-automations.de.vtt" lang="de" title="Episode 5 — Automatisierungen & Freigaben" caption="Episode 5 — Automatisierungen & Freigaben (7:04, mit Untertiteln)">

</Video>

## Was die Episode zeigt

| Ab   | Szene                                                      |
| ---- | ---------------------------------------------------------- |
| 0:28 | Der Job: ein Board voller Aufgaben ohne Besitzer           |
| 0:51 | Der Katalog, und was dir ein Paket-Panel zeigt             |
| 1:59 | Den Workflow lesen: Auslöser, Bewertungsschritt, Schema    |
| 3:09 | Der Tester — und der ehrliche Weg zu einem echten Lauf     |
| 3:30 | Eine echte Aufgabe, vor der Kamera erstellt und zugewiesen |
| 4:26 | Der rote Lauf, bis zu seinem Schritt untersucht            |
| 5:16 | Die Freigabekarte: lesen, ergänzen, absenden               |
| 6:08 | Die Entscheidung im Audit-Log                              |

## Wie es weitergeht

[Automatisierungs-Konzepte](https://docs.tale.dev/de/platform/automations/concepts) und der [Katalog](https://docs.tale.dev/de/platform/automations/catalog) behandeln die Pakete; [Editor](https://docs.tale.dev/de/platform/automations/editor), [Auslöser](https://docs.tale.dev/de/platform/automations/triggers) und [Ausführungsprotokolle](https://docs.tale.dev/de/platform/automations/execution-logs) vertiefen das Gesehene. Zur Karte selbst: [Freigabe-Konzepte](https://docs.tale.dev/de/platform/approvals/concepts) und [Freigaben in Workflows](https://docs.tale.dev/de/platform/automations/approvals-in-workflows) — und dann bau eine mit dem Tutorial [ein Workflow mit Freigaben](https://docs.tale.dev/de/tutorials/editor/workflow-with-approvals).

# Episode 2 — Chat, im Detail
Source: https://docs.tale.dev/de/tutorials/videos/chat-in-depth

Episode 1 war der Rundgang; diese Episode zieht in den Raum ein, in dem dein Team wirklich arbeiten wird — und fährt eine komplette Arbeitssitzung. Das Kernstück ist ein kontrolliertes Experiment: dieselbe Onboarding-Frage, zweimal gestellt — einmal ohne Kontext, einmal mit angehängtem Q2-Support-Bericht. So siehst du zu, wie eine flüssige Antwort und eine verankerte Antwort aufhören, dasselbe zu sein. Danach wird die verankerte Antwort hinterfragt („Welches Dokument sagt das?"), ein Arena-Urteil mit Begründung gefällt — und ein Briefing landet im Canvas und schrumpft mit einem Satz auf drei Punkte.

<Video src="https://docs.tale.dev/videos/de/tutorials/ep2-chat/ep2-chat.de.mp4" poster="https://docs.tale.dev/videos/de/tutorials/ep2-chat/ep2-chat.de.webp" captions="https://docs.tale.dev/videos/de/tutorials/ep2-chat/ep2-chat.de.vtt" lang="de" title="Episode 2 — Chat, im Detail" caption="Episode 2 — Chat, im Detail (6:25, mit Untertiteln)">

</Video>

## Was die Episode zeigt

| Ab   | Szene                                                          |
| ---- | -------------------------------------------------------------- |
| 0:30 | Die drei Entscheidungen im Eingabefeld: Agent, Modell, Kontext |
| 0:53 | Das Experiment, Teil eins: fragen, ohne etwas anzuhängen       |
| 1:14 | Die Falle, gemeinsam gelesen — flüssig, souverän, geraten      |
| 1:34 | Teil zwei: dieselbe Frage, verankert in einem echten Dokument  |
| 2:12 | Die Antwort hinterfragen: „Welches Dokument sagt das?"         |
| 2:34 | Eine Antwort bewerten — wo die Feedback-Analysen beginnen      |
| 3:22 | Arena-Modus: zwei Modelle, ein Prompt, ein begründetes Urteil  |
| 4:20 | Das Canvas: ein Briefing landet als Datei und wird gekürzt     |
| 5:13 | Tiefenrecherche, und wo sie wohnt                              |

## Wie es weitergeht

[Chat-Grundlagen](https://docs.tale.dev/de/platform/chat/basics) behandelt die Eingabezeile, die drei Abruf-Tools und den Denkverlauf in Referenztiefe. Zur Modellseite: [Modelle](https://docs.tale.dev/de/platform/models) und der [Arena-Modus](https://docs.tale.dev/de/platform/chat/arena-mode); für Arbeit, die in einem Arbeitsergebnis endet, übergibt der Chat an die [Agent-Konzepte](https://docs.tale.dev/de/platform/agents/concepts).

# Episode 7 — Connectors & die Außenwelt
Source: https://docs.tale.dev/de/tutorials/videos/connectors

Dein Arbeitsbereich lebt nicht allein. Diese Episode geht die Türen zur Außenwelt ab und die Disziplin in jeder einzelnen: ein Connector, den du lesen kannst, bevor du ihn öffnest, die Fähigkeit, die aufleuchtet, wenn eine Connector angebunden ist, die MCP-Tür, wie die frühere Version sie zeigte, und ein Sandbox-Netz, das standardmäßig Nein sagt.

<Video src="https://docs.tale.dev/videos/de/tutorials/ep7-connectors/ep7-connectors.de.mp4" poster="https://docs.tale.dev/videos/de/tutorials/ep7-connectors/ep7-connectors.de.webp" captions="https://docs.tale.dev/videos/de/tutorials/ep7-connectors/ep7-connectors.de.vtt" lang="de" title="Episode 7 — Connectors & die Außenwelt" caption="Episode 7 — Connectors & die Außenwelt (2:52, mit Untertiteln)">

</Video>

<Note>

Der MCP-Abschnitt (1:09–1:45) wurde im Panel **MCP-Server** der früheren Version aufgenommen. Einen externen Server zu registrieren und seine Freigabe-Flags pro Werkzeug gibt es in dieser Version nicht — Tales einzige MCP-Oberfläche ist der eingehende Endpoint unter **Einstellungen > API > MCP**, an dem dein Client Tale steuert. Sieh ihn dir für das Muster an jeder Tür an; [MCP-Server](https://docs.tale.dev/de/platform/connectors/mcp-servers) sagt, was an die Stelle des Panels getreten ist.

</Note>

## Was die Episode zeigt

| Ab   | Szene                                                                      |
| ---- | -------------------------------------------------------------------------- |
| 0:15 | Der Katalog: einmal verbinden, der ganze Arbeitsbereich leiht              |
| 0:34 | Die Tür lesen: Operationen und erlaubte Hosts, bevor etwas läuft           |
| 0:52 | Der Gewinn: Tiefenrecherche gibt es, weil Tavily angebunden ist            |
| 1:09 | MCP: eure eigenen Werkzeuge, den Agenten wie eingebaute serviert           |
| 1:27 | Freigabe-Flags pro Werkzeug — eingebaut aussehen heißt nicht vertrauen     |
| 2:07 | Das Muster an jeder Tür                                                    |

## Wie es weitergeht

Der [Connectors-Überblick](https://docs.tale.dev/de/platform/connectors/overview) behandelt Verbinden und Teilen; [MCP-Server](https://docs.tale.dev/de/platform/connectors/mcp-servers), was in dieser Version an der MCP-Tür steht. Zur Netzgrenze lies [Hardening](https://docs.tale.dev/de/self-hosted/operate/security/hardening) — und was ein angebundener Connector freischaltet, zeigen die [Automatisierungs-Konzepte](https://docs.tale.dev/de/platform/automations/concepts).

# Episode 9 — Richtlinien, Kosten & Vertrauen
Source: https://docs.tale.dev/de/tutorials/videos/governance-and-trust

Das Finale gehört denen, die für KI in der Organisation geradestehen. Es durchquert den Kontrollraum von vorne bis hinten — welche Modelle für wen laufen, die Leitplanken, die in beide Richtungen prüfen, das Audit-Protokoll, in dem die Freigabe aus Episode fünf tatsächlich gelandet ist, die Kosten- und Qualitätsdiagramme mit den Arena-Urteilen aus Episode zwei und den Regions-Regler — und schließt die Serie mit ihren fünf Gewohnheiten: verankern, absichern, begrenzen, protokollieren, messen.

<Video src="https://docs.tale.dev/videos/de/tutorials/ep9-governance/ep9-governance.de.mp4" poster="https://docs.tale.dev/videos/de/tutorials/ep9-governance/ep9-governance.de.webp" captions="https://docs.tale.dev/videos/de/tutorials/ep9-governance/ep9-governance.de.vtt" lang="de" title="Episode 9 — Richtlinien, Kosten & Vertrauen" caption="Episode 9 — Richtlinien, Kosten & Vertrauen (3:31, mit Untertiteln)">

</Video>

## Was die Episode zeigt

| Ab   | Szene                                                             |
| ---- | ----------------------------------------------------------------- |
| 0:21 | Anbieter: ein Gateway, eigene Schlüssel oder eigene Hardware      |
| 0:39 | Modell-Richtlinie: wer welches Modell nutzen darf                 |
| 0:56 | Leitplanken: PII maskiert, Unsicheres blockiert, beide Richtungen |
| 1:20 | Das Audit-Protokoll — die Freigabe aus Episode fünf, aktenkundig  |
| 1:43 | Nutzungsanalysen: Kosten mit Namen daran, Budgets, die warnen     |
| 1:59 | Feedback-Analysen: Qualität gemessen, Arena-Urteile inklusive     |
| 2:17 | Datenresidenz: eine Einstellung, keine Verhandlung                |
| 2:34 | Die fünf Gewohnheiten guten KI-Einsatzes                          |

## Wie es weitergeht

[Anbieter](https://docs.tale.dev/de/platform/admin/providers) und [Modelle](https://docs.tale.dev/de/platform/models) behandeln die Maschinerie; [Content-Modelle](https://docs.tale.dev/de/platform/admin/governance/content-models) und [Richtlinien und Limits](https://docs.tale.dev/de/platform/admin/governance/policies-and-limits) die Richtlinien-Schicht; [Leitplanken](https://docs.tale.dev/de/platform/admin/governance/guardrails), [Audit-Protokolle](https://docs.tale.dev/de/platform/admin/governance/audit-logs), [Nutzungsanalysen](https://docs.tale.dev/de/platform/admin/governance/usage-analytics) und [Feedback-Analysen](https://docs.tale.dev/de/platform/admin/governance/feedback-analytics) die besichtigten Kontrollen. Zur Residenz: [Cloud-Datenresidenz](https://docs.tale.dev/de/cloud/data-residency).

# Video-Tutorials
Source: https://docs.tale.dev/de/tutorials/videos

Die Videoserie zeigt dir die Plattform so, wie ein Kollege sie dir zeigen würde: am Bildschirm, Bereich für Bereich, mit den ehrlichen Einschränkungen laut ausgesprochen. Die Episoden sind kurz — drei bis vier Minuten — und jede nimmt nebenbei ein Stück allgemeiner KI-Kompetenz mit: was Verankerung bedeutet, warum Halluzinationen entstehen, wo der Mensch in den Ablauf gehört.

Jede Episodenseite trägt das Video mit Untertiteln in der Seitensprache, eine Kapitelliste und Links in die tieferen Referenzseiten.

<CardGroup cols="1">

<Card title="Episode 1 — Willkommen bei Tale" icon="play" href="https://docs.tale.dev/de/tutorials/videos/welcome-to-tale">

Die geführte Tour: eine verankerte Frage stellen, die zitierte Datei im Wissen finden, den antwortenden Agenten kennenlernen und das Journal einer laufenden Automatisierung lesen. Gut vier Minuten.

</Card>

<Card title="Episode 2 — Chat, im Detail" icon="play" href="https://docs.tale.dev/de/tutorials/videos/chat-in-depth">

Eine echte Arbeitssitzung: dieselbe Frage ohne und mit Verankerung, ein Quellen-Check, ein begründetes Arena-Urteil und ein Briefing, das im Canvas entsteht und dort schrumpft. Gut sechs Minuten.

</Card>

<Card title="Episode 3 — Wissen" icon="play" href="https://docs.tale.dev/de/tutorials/videos/knowledge">

Arbeit in der Bibliothek: einen Eintrag anlegen und zitiert zurückhören, verstehen, was „Indexiert" bedeutet, einen Datensatz nachschlagen, die Crawler-Grenze lesen — und die Falle veralteten Wissens live erleben. Knapp sieben Minuten.

</Card>

<Card title="Episode 4 — Dein erster Agent" icon="play" href="https://docs.tale.dev/de/tutorials/videos/your-first-agent">

Ein Agent, im früheren Agenten-Editor vor der Kamera gebaut — Anweisungen, Wissensbereich, Werkzeuge, Modell — und live getestet; die Ansichten haben sich seither geändert, die Überlegung nicht. Fähigkeit ist Angriffsfläche: fang klein an. Gut drei Minuten.

</Card>

<Card title="Episode 5 — Automatisierungen & Freigaben" icon="play" href="https://docs.tale.dev/de/tutorials/videos/automations-and-approvals">

Nutze eine laufende Automatisierung von Anfang bis Ende: Lies den Triage-Workflow, löse mit einer vor der Kamera erstellten Aufgabe einen echten Lauf aus, untersuche den fehlgeschlagenen Lauf und gib eine ausgehende Mail selbst frei. Sieben Minuten.

</Card>

<Card title="Episode 6 — Projekte mit KI" icon="play" href="https://docs.tale.dev/de/tutorials/videos/projects-with-ai">

Das Board mitten im Flug, Dateien als begrenzter Kontext und eine vor der Kamera angelegte Aufgabe, die ein Agent sichtbar übernimmt. Die Initiative bleibt beim Menschen. Knapp drei Minuten.

</Card>

<Card title="Episode 7 — Connectors & die Außenwelt" icon="play" href="https://docs.tale.dev/de/tutorials/videos/connectors">

Connectoren zum Lesen vor dem Öffnen, die MCP-Tür, wie die frühere Version sie zeigte, und Egress, der im Zweifel schließt. Jede Tür bewusst geöffnet. Knapp drei Minuten.

</Card>

<Card title="Episode 8 — Menschen, Rollen & Teams" icon="play" href="https://docs.tale.dev/de/tutorials/videos/people-roles-and-teams">

Die menschliche Hälfte des Vertrauens: die Rollenleiter, Teams als Wissenswände und Identitäts-Hygiene. Zugriff wird entworfen, nicht angenommen. Gut zwei Minuten.

</Card>

<Card title="Episode 9 — Richtlinien, Kosten & Vertrauen" icon="play" href="https://docs.tale.dev/de/tutorials/videos/governance-and-trust">

Das Finale: Anbieter und Modell-Richtlinien, Leitplanken, das Audit-Protokoll, Kosten- und Qualitätsdiagramme, Residenz — und die fünf Gewohnheiten guten KI-Einsatzes. Gut drei Minuten.

</Card>

<Card title="Bonus — Tale für Entwickler" icon="play" href="https://docs.tale.dev/de/tutorials/videos/tale-for-developers">

Die Runde für die Bauenden: begrenzte Schlüssel, vier API-Türen, Webhooks und Harnesses, die im Zweifel schließen. Gut zwei Minuten.

</Card>

</CardGroup>

## Die Serie danach

Damit ist die Serie vollständig: der Rundgang, sieben Vertiefungen und ein Entwickler-Bonus — jeweils auf Englisch, Deutsch und Französisch. Die Dokumentation rund um jede Episode geht weiter; starte dort, wo deine Rolle beginnt.

# Episode 3 — Wissen
Source: https://docs.tale.dev/de/tutorials/videos/knowledge

Die verankerten Antworten aus Episode 2 kamen alle aus einem Ort — in dieser Episode arbeitest du darin. Du legst einen echten Fakt als Wissenseintrag an, lernst, was „Indexiert" wirklich bedeutet (und warum Indexieren kein Training ist), schlägst einen Preis in einem typisierten Datensatz nach, liest das Scan-Intervall des Crawlers, öffnest den Schalter, der ein Dokument auf ein Team begrenzt — und triffst dann den Fehler, der dich wirklich erwartet: keinen fehlenden Fakt, sondern einen veralteten. Am Ende zitiert ein frischer Chat den Eintrag, den du Minuten zuvor angelegt hast.

<Video src="https://docs.tale.dev/videos/de/tutorials/ep3-knowledge/ep3-knowledge.de.mp4" poster="https://docs.tale.dev/videos/de/tutorials/ep3-knowledge/ep3-knowledge.de.webp" captions="https://docs.tale.dev/videos/de/tutorials/ep3-knowledge/ep3-knowledge.de.vtt" lang="de" title="Episode 3 — Wissen" caption="Episode 3 — Wissen (6:46, mit Untertiteln)">

</Video>

## Was die Episode zeigt

| Ab   | Szene                                                               |
| ---- | ------------------------------------------------------------------- |
| 0:32 | Die Karte: Dokumente, Einträge, Websites, Produkte — eine Tab-Zeile |
| 1:04 | Eintrag, Dokument oder Datensatz — die richtige Form wählen         |
| 1:33 | Ein Wissenseintrag, live angelegt: Thema, Inhalt, speichern         |
| 1:59 | Was „Indexiert" bedeutet — Abruf zur Antwortzeit, kein Training     |
| 2:32 | Ein echter Blick in einen typisierten Datensatz                     |
| 3:05 | Der Crawler: eine Domain, ein Scan-Intervall, eine ehrliche Grenze  |
| 3:44 | Wer liest was: ein Dokument einem Team zugewiesen                   |
| 4:22 | Die Falle des veralteten Wissens, live gefragt                      |
| 5:22 | Der Beweis: ein frischer Chat zitiert deinen neuen Eintrag          |

## Wie es weitergeht

Der [Wissens-Überblick](https://docs.tale.dev/de/platform/knowledge/overview) kartiert die ganze Bibliothek; [Dokumente](https://docs.tale.dev/de/platform/knowledge/documents) behandelt die Indexierung, [Wissenseinträge](https://docs.tale.dev/de/platform/knowledge/knowledge-entries) die gepflegten Fakten, [strukturierte Daten](https://docs.tale.dev/de/platform/knowledge/structured-data) die typisierten Datensätze und [Crawling](https://docs.tale.dev/de/platform/knowledge/crawling) die Websites. Wie ein Projekt-Agent darauf zugreift, steht in [Projekt-Agenten](https://docs.tale.dev/de/platform/projects/project-agents).

# Episode 8 — Menschen, Rollen & Teams
Source: https://docs.tale.dev/de/tutorials/videos/people-roles-and-teams

Episode fünf hat die Maschinen eingehegt; diese Episode die Menschen. Sie geht die Besetzung des Arbeitsbereichs und die vierstufige Rollenleiter durch, öffnet den Mitglied-hinzufügen-Dialog gerade lange genug, um ihn zu lernen, zieht die Teamgrenzen, die entscheiden, wer was liest, und schließt mit den langweiligen Leitplanken, die am meisten zählen: Zwei-Faktor und Single Sign-on.

<Video src="https://docs.tale.dev/videos/de/tutorials/ep8-people/ep8-people.de.mp4" poster="https://docs.tale.dev/videos/de/tutorials/ep8-people/ep8-people.de.webp" captions="https://docs.tale.dev/videos/de/tutorials/ep8-people/ep8-people.de.vtt" lang="de" title="Episode 8 — Menschen, Rollen & Teams" caption="Episode 8 — Menschen, Rollen & Teams (2:35, mit Untertiteln)">

</Video>

## Was die Episode zeigt

| Ab   | Szene                                                               |
| ---- | ------------------------------------------------------------------- |
| 0:15 | Die Besetzung: fünf Personen, vier Rollen                           |
| 0:30 | Jemanden hinzufügen — und die Rollenleiter, auf die es ankommt      |
| 0:57 | Rollen sind Wirkungsradius, kein Status                             |
| 1:14 | Teams: die Wände der kleinsten Bibliothek                           |
| 1:33 | Identitäts-Hygiene: 2FA und Enterprise-SSO                          |
| 1:51 | Ein Prinzip, beide Seiten: Zugriff wird entworfen, nicht angenommen |

## Wie es weitergeht

[Mitglieder und Rollen](https://docs.tale.dev/de/platform/admin/members-and-roles) ist die volle Referenz zur Leiter; [Teams](https://docs.tale.dev/de/platform/admin/teams) behandelt die gesehenen Grenzen. Zur Identität: [Zwei-Faktor-Authentifizierung](https://docs.tale.dev/de/platform/admin/two-factor-authentication) und [Enterprise-SSO](https://docs.tale.dev/de/platform/admin/enterprise-sso).

# Episode 6 — Projekte mit KI
Source: https://docs.tale.dev/de/tutorials/videos/projects-with-ai

Im Chat fragst du; in Projekten wohnt die Arbeit. Diese Episode geht durch das Relaunch-Projekt, das das Team wirklich betreibt — und legt dann vor der Kamera eine Aufgabe an, ganz normal, damit du zusehen kannst, wie die Triage sie bewertet und ein Agent sie übernimmt. Das Backlog schließt den Kreis: Agenten schlagen vor, Menschen befördern.

<Video src="https://docs.tale.dev/videos/de/tutorials/ep6-projects/ep6-projects.de.mp4" poster="https://docs.tale.dev/videos/de/tutorials/ep6-projects/ep6-projects.de.webp" captions="https://docs.tale.dev/videos/de/tutorials/ep6-projects/ep6-projects.de.vtt" lang="de" title="Episode 6 — Projekte mit KI" caption="Episode 6 — Projekte mit KI (2:47, mit Untertiteln)">

</Video>

## Was die Episode zeigt

| Ab   | Szene                                                                  |
| ---- | ---------------------------------------------------------------------- |
| 0:16 | Das Relaunch-Board mitten im Flug — Avatare zeigen, wer was hält       |
| 0:33 | Projektdateien: das Regal, das Agenten zuerst lesen                    |
| 0:48 | Diskussionen wohnen neben der Arbeit                                   |
| 1:04 | Eine Aufgabe, ganz normal angelegt                                     |
| 1:21 | Der Agent übernimmt: bewertet, zugewiesen, die Begründung im Kommentar |
| 1:43 | Das Backlog: Agenten schlagen vor, ein Mensch befördert                |
| 2:01 | Jedes Projekt besetzt seine eigene Crew aus Agenten und Modellen       |

## Wie es weitergeht

[Projekt-Konzepte](https://docs.tale.dev/de/platform/projects/concepts) und der [Überblick](https://docs.tale.dev/de/platform/projects/overview) kartieren die Oberfläche; [Aufgaben-Automatisierung](https://docs.tale.dev/de/platform/projects/task-automation) erklärt die Bewerten-Zuweisen-Berichten-Schleife von eben, [Backlog](https://docs.tale.dev/de/platform/projects/backlog) den Vorschlagsfluss und [Projekt-Agenten](https://docs.tale.dev/de/platform/projects/project-agents) die Crew pro Projekt.

# Bonus — Tale für Entwickler
Source: https://docs.tale.dev/de/tutorials/videos/tale-for-developers

Alles, was die Serie gezeigt hat, trägt eine API darunter. Die Bonus-Episode geht die Entwickler-Oberfläche ab: benannte, widerrufbare API-Schlüssel; REST, MCP, WebDAV und Sandbox-Runtimes; Webhooks, die Agenten aus jedem System auslösen; die Harnesses — Claude Code, Cursor — in isolierten Containern. Starke Werkzeuge, eingehegter Wirkungsradius.

<Video src="https://docs.tale.dev/videos/de/tutorials/ep10-developers/ep10-developers.de.mp4" poster="https://docs.tale.dev/videos/de/tutorials/ep10-developers/ep10-developers.de.webp" captions="https://docs.tale.dev/videos/de/tutorials/ep10-developers/ep10-developers.de.vtt" lang="de" title="Bonus — Tale für Entwickler" caption="Bonus — Tale für Entwickler (2:38, mit Untertiteln)">

</Video>

## Was die Episode zeigt

| Ab   | Szene                                                       |
| ---- | ----------------------------------------------------------- |
| 0:18 | API-Schlüssel: benannt, begrenzt, widerrufbar, auditiert    |
| 0:36 | Vier Türen: REST, MCP, WebDAV, Sandbox-Runtimes             |
| 0:56 | Webhooks: jedes System kann einen Agenten auslösen          |
| 1:16 | Harnesses: Claude Code, Cursor und Kollegen                 |
| 1:59 | Starke Werkzeuge, eingehegter Wirkungsradius                |

## Wie es weitergeht

Der [Develop-Überblick](https://docs.tale.dev/de/develop/overview) kartiert die ganze Oberfläche; die [API-Referenz](https://docs.tale.dev/de/develop/api-reference) und [Webhooks](https://docs.tale.dev/de/develop/webhooks) tragen die Verträge. Zu Harness-Zügen: [Harnesses](https://docs.tale.dev/de/platform/agents/harnesses); zur Netzgrenze der Sandbox: [Hardening](https://docs.tale.dev/de/self-hosted/operate/security/hardening).

# Episode 1 — Willkommen bei Tale
Source: https://docs.tale.dev/de/tutorials/videos/welcome-to-tale

Die Auftaktepisode geht den Arbeitsbereich Bereich für Bereich durch — in einem Tempo zum Mitschauen. Du stellst eine echte Frage, verankert in einem Firmendokument, siehst die Antwort ihre Quellen benennen und schließt dann den Kreis: die zitierte Datei im Wissen finden, den Assistenten kennenlernen, der geantwortet hat, und das Journal einer Automatisierung lesen, die die ganze Zeit lief. Jede Station zeigt ein echtes Artefakt — nichts wird behauptet, was nicht auf dem Bildschirm steht.

<Video src="https://docs.tale.dev/videos/de/tutorials/ep1-welcome/ep1-welcome.de.mp4" poster="https://docs.tale.dev/videos/de/tutorials/ep1-welcome/ep1-welcome.de.webp" captions="https://docs.tale.dev/videos/de/tutorials/ep1-welcome/ep1-welcome.de.vtt" lang="de" title="Episode 1 — Willkommen bei Tale" caption="Episode 1 — Willkommen bei Tale (4:21, mit Untertiteln)">

</Video>

## Was die Episode zeigt

| Ab   | Szene                                                       |
| ---- | ----------------------------------------------------------- |
| 0:20 | Die Seitenleiste lesen: jede Station der Tour, eine Leiste  |
| 0:42 | Die erste Frage — ein Dokument als Kontext angehängt        |
| 1:20 | Warum Verankerung zählt (und was eine Halluzination ist)    |
| 1:40 | Der Kreis schließt sich: die zitierte Datei im Wissen       |
| 1:58 | Der Assistent — ein Agent ist KI mit Stellenprofil          |
| 2:21 | Automatisierungen: der Katalog und ein Journal echter Läufe |
| 3:08 | Projekte: deine Leute und deine Agenten an einem Board      |
| 3:26 | Kontrolle: Anbieter, Datenresidenz und das Audit-Log        |

## Wie es weitergeht

Der [Schnellstart](https://docs.tale.dev/de/get-started/quickstart) baut den ersten Chat der Episode in etwa fünf Minuten in deinem eigenen Arbeitsbereich nach. Für die Konzepte in der Tiefe: [Chat](https://docs.tale.dev/de/platform/chat/overview), [Wissen](https://docs.tale.dev/de/platform/knowledge/overview), [Agenten](https://docs.tale.dev/de/platform/agents/concepts), [Automatisierungen](https://docs.tale.dev/de/platform/automations/concepts) und [Freigaben](https://docs.tale.dev/de/platform/approvals/concepts).

# Episode 4 — Dein erster Agent
Source: https://docs.tale.dev/de/tutorials/videos/your-first-agent

Der Chat hat dir das Fragen beigebracht, das Wissen die Grundlage der Antworten. Diese Episode baut das Ding, das beides einsetzt: einen Agenten, von Null vor der Kamera. Der rote Faden ist die Vertrauensgrenze — jedes gewährte Werkzeug erweitert, was der Agent tun kann. Der kleinste Agent, der den Job erledigt, ist der sicherste.

<Video src="https://docs.tale.dev/videos/de/tutorials/ep4-agent/ep4-agent.de.mp4" poster="https://docs.tale.dev/videos/de/tutorials/ep4-agent/ep4-agent.de.webp" captions="https://docs.tale.dev/videos/de/tutorials/ep4-agent/ep4-agent.de.vtt" lang="de" title="Episode 4 — Dein erster Agent" caption="Episode 4 — Dein erster Agent (3:18, mit Untertiteln)">

</Video>

<Note>

Die Episode wurde im früheren Agenten-Editor aufgenommen. Die Agentenliste, den Anlege-Dialog, die Tabs **Wissen** und **Werkzeuge** und den Schritt „im Chat sichtbar“ gibt es in dieser Version nicht — die Agenten, die du heute anlegst, wohnen im Tab **Agenten** eines Projekts und erledigen Board-Aufgaben, und der Chat hat keine Agentenauswahl. Sieh sie dir für die Überlegung an; die Schritte nimmst du aus [Deinen ersten Agent bauen](https://docs.tale.dev/de/tutorials/editor/first-agent-end-to-end).

</Note>

## Was die Episode zeigt

| Ab   | Szene                                                         |
| ---- | ------------------------------------------------------------- |
| 0:17 | Die Agentenliste — die eingebauten, und wo deiner wohnen wird |
| 0:32 | Anlegen: technischer Name, Anzeigename, weiter                |
| 0:51 | Anweisungen — die Stellenbeschreibung samt Übergabe-Regel     |
| 1:12 | Wissensbereich: die kleinste Bibliothek, die den Job erledigt |
| 1:29 | Werkzeuge: Fähigkeit ist Angriffsfläche — starte ohne         |
| 1:53 | Das Modell und sein Fallback                                  |
| 2:10 | Im Chat sichtbar, dann die erste echte Frage                  |
| 2:32 | Mutig verbessern: die Historie behält jede Version            |

## Wie es weitergeht

[Agenten-Konzepte](https://docs.tale.dev/de/platform/agents/concepts) liefert das Denkmodell hinter den vier Entscheidungen, und [Deinen ersten Agent bauen](https://docs.tale.dev/de/tutorials/editor/first-agent-end-to-end) geht sie auf den Ansichten durch, die diese Version ausliefert — ein Projekt-Agent mit Agent-Laufzeit, Modell und Anweisungen, an einer Aufgabe eingesetzt. [Projekt-Agenten](https://docs.tale.dev/de/platform/projects/project-agents) ist die Referenz Feld für Feld. Den Erstellen-Dialog und die Tabs Tools, Wissen und Verlauf, die die Episode zeigt, gibt es in dieser Version nicht; ihre Einstellungen liegen heute im Dialog des Projekt-Agenten.

# Offres, factures et utilisation
Source: https://docs.tale.dev/fr/cloud/billing

Ton contrat Cloud définit les frais d’hébergement, d’assistance, de places et de stockage. L’utilisation des modèles est un poste distinct : le fournisseur et le modèle choisis influencent le coût de chaque requête IA.

## Distinguer les frais

Tale propose Community, gratuit en auto-hébergement, et Enterprise pour le Cloud géré ou les installations auto-hébergées avec assistance. Les deux éditions incluent les mêmes fonctions. Enterprise ajoute des prestations professionnelles et de l’assistance ; les contrôles du produit ne dépendent pas d’un déblocage payant.

La [page des tarifs](https://tale.dev/pricing) indique les prix actuels des places et du stockage, les périodes de facturation et les services inclus. Elle présente l’utilisation IA aux tarifs des fournisseurs, sans majoration. Le devis accepté et le contrat de service définissent les conditions de ton organisation.

## Obtenir une facture ou modifier tes coordonnées

Contacte l’équipe Tale par ton canal d’assistance Enterprise pour les factures, les coordonnées de facturation, les changements de places ou une question sur un montant. L’interface commune du produit ne comporte pas de page **Paramètres > Facturation**. Les vues d’utilisation servent au suivi opérationnel, pas à consulter les factures.

Indique la période, l’organisation et la référence de facture dans ta demande. N’envoie jamais de clé de fournisseur ni de clé API.

## Comprendre l’utilisation des modèles

Ouvre [l’analyse de l’utilisation](https://docs.tale.dev/fr/platform/admin/governance/usage-analytics) pour consulter l’activité enregistrée. Choisis une période, puis examine les répartitions par modèle ou par personne pour en trouver l’origine.

Le coût affiché dans une vue d’utilisation et le montant d’une facture répondent à des besoins différents. Ton contrat et les règles de facturation du fournisseur déterminent le montant à payer. Le total du Dashboard ne remplace ni une facture définitive ni un justificatif fiscal.

<Tip>

Avant de proposer un nouveau modèle à toute l’équipe, teste une tâche représentative et compare la qualité du résultat avec l’utilisation enregistrée. Une requête moins chère n’est utile que si son résultat convient au travail attendu.

</Tip>

## Définir des limites

Configure les contrôles nécessaires dans [les politiques et les limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits). Vérifie la portée de chaque règle et teste-la avec un compte concerné. Les limites de la plateforme s’appliquent à l’activité qu’elles couvrent ; elles ne modifient pas ton contrat d’hébergement.

Avec Community en auto-hébergement, tu exploites l’infrastructure et paies directement tes fournisseurs. Les mêmes pages d’utilisation et de politiques t’aident à suivre cette activité.

# Comprendre la résidence des données Cloud
Source: https://docs.tale.dev/fr/cloud/data-residency

La résidence des données concerne leur stockage et leur traitement. Choisir une région Cloud définit l’emplacement du service hébergé, mais ne détermine pas à lui seul où chaque fournisseur de modèles ou service connecté traite tes données.

## Confirmer l’hébergement

Avant la configuration, confirme avec Tale la région principale, les emplacements de sauvegarde, la conservation, les objectifs de reprise et le processus d’assistance. Le contrat de service et les accords de traitement précisent les engagements de ton déploiement. Un libellé de région dans le produit ne permet pas de déduire une ville de sauvegarde ni une garantie de reprise.

Tale exploite le service Cloud. Les fichiers de configuration, les identifiants de base de données et les variables d’environnement de l’hôte relèvent de l’opérateur. La [référence d’auto-hébergement](https://docs.tale.dev/fr/self-hosted/configuration/data-residency) explique ce modèle technique.

## Suivre les données d’une requête

Un message de chat arrive sur ton instance Tale. Quand l’assistant utilise les connaissances, il récupère les contenus pertinents dans le stockage de l’organisation. Le message et le contexte sélectionné sont ensuite envoyés au fournisseur du modèle utilisé pour la réponse. Un outil peut contacter un autre service, comme un site web ou une application connectée.

| Flux de données | Point à vérifier |
| --- | --- |
| Chats, documents et configuration stockés | Emplacements d’hébergement et de sauvegarde convenus |
| Indexation des connaissances | Fournisseur d’embeddings qui reçoit les documents |
| Inférence du modèle | Point d’accès, conditions de traitement et conservation du fournisseur |
| Connecteurs et outils web | Systèmes externes qui reçoivent requêtes et contenus |
| Données d’exploitation | Traitement convenu des journaux, sauvegardes et accès d’assistance |

Un fournisseur peut proposer des points d’accès régionaux ou locaux. Vérifie celui qui est configuré : son nom commercial ne suffit pas à établir le lieu du traitement.

<Tip>

Vérifie le fournisseur d’embeddings en plus du modèle de chat. Un document peut lui être envoyé pendant l’indexation, avant même qu’une question soit posée à son sujet.

</Tip>

## Examiner une nouvelle intégration

Avant de connecter un service, identifie les données envoyées par la tâche prévue et le compte utilisé par le connecteur. Vérifie les conditions de traitement, limite les accès et teste avec des exemples non sensibles. Consigne la décision dans ta [revue de sécurité](https://docs.tale.dev/fr/cloud/trust-and-compliance).

## Changer de région

Organise le changement avec Tale. Le plan de migration doit couvrir les données stockées, les sauvegardes, les points d’accès externes, l’interruption et la validation. Créer une deuxième organisation ne déplace pas les données de la première.

Le [guide de préparation d’une migration](https://docs.tale.dev/fr/cloud/migrate-to-self-hosted) présente des questions et des vérifications utiles aussi pour un déplacement entre régions Cloud.

# Tale Cloud
Source: https://docs.tale.dev/fr/cloud

Tale Cloud te permet d’utiliser Tale comme service géré. Ton équipe retrouve les mêmes fonctions que dans l’édition open source, tandis que Tale exploite le service selon ton contrat Enterprise.

## Choisir ta prochaine tâche

<CardGroup cols="2">

<Card title="Accéder à ton instance" href="https://docs.tale.dev/fr/cloud/onboarding">

Demander une instance ou rejoindre celle de ton organisation.

</Card>

<Card title="Comprendre les frais et les factures" href="https://docs.tale.dev/fr/cloud/billing">

Distinguer les frais du service de l’utilisation des modèles et trouver le bon contact.

</Card>

<Card title="Examiner les flux de données" href="https://docs.tale.dev/fr/cloud/data-residency">

Vérifier l’hébergement et les fournisseurs et outils qui traitent les contenus.

</Card>

<Card title="Préparer une revue de sécurité" href="https://docs.tale.dev/fr/cloud/trust-and-compliance">

Réunir les preuves de certification et vérifier tes responsabilités.

</Card>

<Card title="Préparer le passage à ton infrastructure" href="https://docs.tale.dev/fr/cloud/migrate-to-self-hosted">

Coordonner une migration accompagnée et valider la destination.

</Card>

</CardGroup>

Pour les chats, les projets, les agents et les paramètres, consulte les [guides Plateforme](https://docs.tale.dev/fr/platform). Les pages Cloud couvrent l’hébergement et les responsabilités ; les parcours du produit restent communs.

# Préparer le passage à l’auto-hébergement
Source: https://docs.tale.dev/fr/cloud/migrate-to-self-hosted

Passer du Cloud à une instance auto-hébergée confie l’infrastructure à ton équipe. Prépare le déplacement avec Tale et l’opérateur de destination pour garder cohérents les données applicatives, les connaissances, les fichiers, la configuration et les clés de chiffrement.

Prévois avec l’opérateur le transfert des bases de données, des fichiers, de la configuration et des secrets nécessaires. Les exports API couvrent des ressources précises ; ils ne remplacent pas une sauvegarde cohérente de l’instance.

## Définir ce qui doit être conservé

Liste les organisations et les données concernées, l’interruption acceptable, la version cible et les personnes chargées de la validation. Vérifie les prérequis d’infrastructure dans le [guide d’installation](https://docs.tale.dev/fr/self-hosted/install/quickstart).

| Domaine | Questions à résoudre avant le déplacement |
| --- | --- |
| Base applicative | Quelle sauvegarde constitue une source cohérente, et quelles versions peuvent la restaurer ? |
| Stockages de connaissances | Quels stockages, index et paramètres d’embeddings de chaque organisation faut-il déplacer ? |
| Fichiers et configuration | Quelles données du stockage objet et quels répertoires appartiennent au déploiement ? |
| Chiffrement | Quelles clés de chiffrement et de signature faut-il conserver en sécurité ? |
| Services externes | Quelles URL de rappel, destinations de webhooks, règles réseau ou identifiants changent ? |
| Travail en arrière-plan | Quelles exécutions doivent se terminer ou être suspendues avant la copie finale ? |

Prépare le déplacement avec ton opérateur à l’aide du [guide de sauvegarde et de restauration](https://docs.tale.dev/fr/self-hosted/operate/backups-and-restore). Un ensemble d’exports API ne remplace pas ce plan.

## Répéter la restauration sur une destination isolée

Restaure une copie dans un environnement isolé avant la bascule. Contrôle les automatisations sortantes et les tâches planifiées pour éviter les messages en double ou les modifications externes involontaires pendant l’essai.

Vérifie la connexion, les rôles, des documents représentatifs, les fichiers de projet, une réponse de chat et les intégrations critiques. Compare les nombres et quelques enregistrements avec la source. Le démarrage du service n’est que la première vérification.

## Prévoir la bascule et le retour arrière

Précise qui bloque les écritures, prend la dernière copie, change le routage et valide la destination. Définis les conditions de retour arrière et empêche les deux instances d’accepter des modifications simultanément. Conserve la source et les sauvegardes vérifiées jusqu’à l’acceptation.

Adapte les origines publiques, TLS, les URL de rappel SSO et les destinations des intégrations à la nouvelle adresse. Les sessions et les identifiants externes peuvent nécessiter un renouvellement : teste-les sans supposer qu’ils sont transférés.

## Transmettre l’exploitation

Confirme la supervision, les sauvegardes, les responsables des restaurations, les mises à niveau et les contacts d’assistance. Consigne les vérifications acceptées et communique l’adresse à utiliser. Les tâches régulières comprennent ensuite les [mises à niveau](https://docs.tale.dev/fr/self-hosted/operate/upgrades), [l’observabilité](https://docs.tale.dev/fr/self-hosted/operate/observability/operations) et les exercices de restauration.

# Démarrer sur Tale Cloud
Source: https://docs.tale.dev/fr/cloud/onboarding

La mise en route Cloud commence par l’instance que ton organisation utilisera. Une fois l’accès obtenu, les mêmes guides de chat, de projets et d’administration s’appliquent qu’en auto-hébergement.

## Rejoindre une instance existante

Demande à ton admin l’adresse de l’instance et la méthode de connexion. Ouvre cette adresse avec ton propre compte. Si l’organisation utilise le SSO, suis ce parcours au lieu de créer un deuxième compte.

Après la connexion, suis le guide pour [envoyer ton premier message](https://docs.tale.dev/fr/get-started/quickstart). Si l’organisation ou le projet attendu manque, demande à l’admin de vérifier ton appartenance, ton rôle et le partage du projet.

## Configurer un nouveau service Cloud

<Steps>

<Step title="Préparer l’instance">

[Demande une démo](https://tale.dev/request-demo) ou contacte l’équipe Tale. Convenez de la région d’hébergement, des conditions de service, des besoins d’identité et de la personne qui administrera l’espace. Prépare ces décisions avec [la résidence des données](https://docs.tale.dev/fr/cloud/data-residency) et [la sécurité et la conformité](https://docs.tale.dev/fr/cloud/trust-and-compliance).

</Step>

<Step title="Configurer l’espace de travail">

Utilise l’adresse et les instructions fournies par Tale. Si l’assistant de première configuration apparaît, crée le compte initial et l’organisation. Si une organisation est déjà présente, ouvre-la. En créer une autre produit un espace séparé.

Si l’opérateur gère la création des organisations, le sélecteur d’organisation ne propose pas cette action. Un lien direct vers la configuration explique cette restriction. Contacte l’opérateur pour demander un autre espace de travail.

<Frame caption="Le nom de l’organisation identifie l’espace que ton équipe utilisera.">

![L’assistant de création d’organisation affiche le champ du nom de l’organisation.](https://docs.tale.dev/images/get-started/org-create-wizard.webp)

</Frame>

</Step>

<Step title="Connecter un fournisseur et ajouter l’équipe">

Suis [configurer un espace de travail](https://docs.tale.dev/fr/get-started/admins) pour ajouter les identifiants du fournisseur, vérifier une réponse de modèle et créer les comptes avec les bons rôles. L’espace peut exister avant que le fournisseur soit prêt. Un chat qui répond permet de vérifier l’accès aux modèles.

</Step>

</Steps>

## Valider un premier parcours utile

Choisis une tâche réelle de l’équipe : discuter d’un document, organiser le travail d’un projet ou tester un agent. Vérifie le résultat avec le rôle prévu. [Utiliser Tale en équipe](https://docs.tale.dev/fr/get-started/members) et [créer un agent de projet](https://docs.tale.dev/fr/get-started/editors) proposent les étapes suivantes.

<Tip>

Teste avec un petit échantillon non sensible avant d’importer une grande collection. Tu peux ainsi vérifier les accès et les flux de données tant que la configuration reste facile à examiner.

</Tip>

## Obtenir de l’aide

Pour les accès au compte et aux projets, contacte d’abord ton admin. Pour la disponibilité de l’instance, la configuration du service ou le contrat, utilise le canal d’assistance Tale convenu. Indique l’adresse, l’heure, l’action et l’erreur affichée, sans transmettre de mot de passe ni de clé.

# Sécurité et conformité
Source: https://docs.tale.dev/fr/cloud/trust-and-compliance

Ruler GmbH, l’entreprise qui développe Tale, est certifiée ISO/IEC 27001. Cette certification couvre son offre Tale Enterprise et ses services. Pour une revue de sécurité, demande à ton contact Tale le certificat applicable, son périmètre et les justificatifs correspondant au service souscrit par ton organisation.

Les contrôles du produit accompagnent les procédures de ton organisation. Le respect de tes obligations dépend aussi de la configuration, des fournisseurs connectés et des pratiques d’exploitation.

## Préparer une revue

Rassemble le contrat de service, l’accord de traitement des données, les preuves de certification et une description du déploiement. La [politique de confidentialité](https://docs.tale.dev/fr/legal/privacy) et les informations sur les [sous-traitants](https://docs.tale.dev/fr/legal/subprocessors) complètent cet ensemble. Note la version et le périmètre de chaque document.

Précise l’organisation et le déploiement concernés. Une déclaration de certification ne remplace pas la vérification qu’un service ou une configuration entre dans le périmètre du rapport.

## Répartir les responsabilités

| Domaine | Tale sur le Cloud | Ton organisation |
| --- | --- | --- |
| Hébergement et maintenance | Exploite le service convenu | Choisit le service et coordonne les changements |
| Identité et accès | Fournit les comptes, rôles et contrôles SSO | Ajoute les membres et réexamine leurs droits |
| Fournisseurs et connecteurs | Fournit les contrôles d’intégration | Choisit les services, identifiants et usages autorisés |
| Politiques d’utilisation et de contenu | Fournit les règles et les enregistrements | Configure les règles et traite les événements |
| Demandes de données et conservation | Fournit les procédures prises en charge | Fixe les exigences et autorise les actions |

En auto-hébergement, ton opérateur assume aussi les responsabilités d’infrastructure. L’assistance Enterprise dépend de ton contrat.

## Examiner les contrôles du produit

- [Membres et rôles](https://docs.tale.dev/fr/platform/admin/members-and-roles) définissent les accès. Vérifie les comptes inactifs et les droits élevés.
- Le [SSO Enterprise](https://docs.tale.dev/fr/platform/admin/enterprise-sso) connecte ton fournisseur d’identité. Teste la connexion et la récupération avant de le rendre obligatoire.
- Les [journaux d’audit](https://docs.tale.dev/fr/platform/admin/governance/audit-logs) aident à analyser les actions enregistrées. Consulte [l’intégrité des journaux](https://docs.tale.dev/fr/self-hosted/operate/security/audit-log-integrity) pour comprendre les preuves de modification et leurs limites.
- Les [garde-fous](https://docs.tale.dev/fr/platform/admin/governance/guardrails), la [conservation légale](https://docs.tale.dev/fr/platform/admin/governance/legal-hold) et les [demandes des personnes concernées](https://docs.tale.dev/fr/platform/admin/governance/data-subject-requests) couvrent des procédures précises. Vérifie leur portée avant de t’y fier.

## Signaler un incident

Utilise ton canal d’assistance Enterprise pour un incident de service. Signale une vulnérabilité présumée avec [le signalement privé GitHub](https://github.com/tale-project/tale/security) ou à `security@tale.dev`. Indique la version et les étapes de reproduction sans publier d’identifiants ni de données personnelles dans une issue.

Pour examiner les flux de données, poursuis avec [la résidence des données Cloud](https://docs.tale.dev/fr/cloud/data-residency).

# Configurer Tale avec un agent de programmation
Source: https://docs.tale.dev/fr/develop/ai-assisted-development

Un agent de programmation peut t’aider à modifier un projet de configuration Tale géré par la CLI. Le projet fournit des instructions, des exemples et une sélection de code source de référence. Il reste nécessaire de relire la proposition et d’identifier les organisations concernées.

Modifier le code applicatif de Tale suit un autre parcours. Pour cela, commence par [Préparer l’environnement de développement](https://docs.tale.dev/fr/develop/contributor-setup) et le fichier `AGENTS.md` du dépôt.

## Préparer un projet

Installe la [CLI Tale](https://docs.tale.dev/fr/self-hosted/install/cli-install), puis crée le projet de configuration dans un nouveau répertoire :

```bash
tale init agent-config-example --no-env
cd agent-config-example
ls -a
```

Voici un extrait des chemins générés :

```text
AGENTS.md
CLAUDE.md
default/
.gitignore
.tale/
tale.json
```

`--no-env` saute la préparation de l’environnement : il ne crée ni installation prête à démarrer ni fichier `.env`. Cette option permet d’examiner la configuration avant de lancer des conteneurs. `tale dev` prépare l’environnement lorsque tu démarres ensuite en local. Vérifie d’abord les [prérequis du démarrage rapide](https://docs.tale.dev/fr/self-hosted/install/quickstart).

Ouvre ce répertoire dans ton éditeur. Demande à l’agent de lire `AGENTS.md`, les configurations existantes pertinentes et les sources sous `.tale/reference/` avant de proposer un changement.

## Les deux fichiers d’instructions

`AGENTS.md` contient les consignes de configuration Tale. `CLAUDE.md` y renvoie pour conserver une seule version des instructions. La CLI reconnaît aussi un fichier `AGENT.md` existant ou un `CLAUDE.md` déjà placé dans `.claude/`.

La CLI gère la section comprise entre les commentaires `tale:begin` et `tale:end`. Place tes conventions propres au projet en dehors de cette section ; l’initialisation et les mises à jour conservent ce texte environnant. N’inscris d’identifiants dans aucun de ces fichiers.

La CLI ne génère pas de règles distinctes pour Cursor, Windsurf ou Copilot. Si l’éditeur ne charge pas automatiquement les instructions du projet, ajoute-les explicitement au contexte de l’agent. Consulte les schémas réels au lieu de te fier à sa connaissance d’une ancienne version.

## Comprendre les répertoires

| Chemin | Utilisation |
| --- | --- |
| `default/agents/` | Catalogue de configurations d’agents, avec l’exemple d’agent de programmation fourni. |
| `default/automations/` | Automatisations disponibles à installer ou à déployer. Un fichier présent sur disque n’est pas nécessairement actif. |
| `default/skills/` | Bundles de skills pour les documents et l’analyse visuelle ; chaque bundle occupe un répertoire. |
| `default/branding/` | Configuration de marque et images du modèle. |
| `default/governance/` | Exemples de politiques et de conservation. Respecte les formats produits par ta CLI. |
| `default/README.md` | Explique le modèle et les éléments du catalogue installés automatiquement. |
| `.tale/reference/` | Sélection de sources embarquées dans la CLI. Consulte-la sans y maintenir de modifications : la régénération les remplace. Ce n’est pas une copie complète du dépôt. |
| `.tale/orgs/<slug>/<domain>/` | Configuration d’exécution des organisations réellement créées dans l’application. |
| `.tale/checksums.json` | Empreintes des fichiers générés, utilisées pour reconnaître tes modifications lors des mises à jour. |

`default/` est le modèle des nouvelles organisations, pas une organisation à déployer. Le modifier ne met pas automatiquement à jour une organisation existante. Git ignore `.tale/` et les fichiers secrets ; les modèles publics sont destinés à la gestion de versions.

## Actualiser la référence

`tale update` actualise la CLI dans sa série de versions et renouvelle les contenus générés. La commande régénère la référence, met à jour les sections d’instructions gérées, ajoute les nouveaux fichiers du catalogue et remplace ceux dont l’empreinte ne révèle aucune modification locale. Les fichiers du catalogue que tu as modifiés restent inchangés, sauf avec `--force`.

Examine le plan avec `tale update --dry-run`. Versionne la configuration publique et conserve des sauvegardes protégées de la configuration d’exécution et des secrets. Ne maintiens pas un fork dans `.tale/reference/`. Actualiser la CLI ne remplace pas les conteneurs en service ; suis [Mises à jour](https://docs.tale.dev/fr/self-hosted/operate/upgrades) pour changer la version déployée.

## Cursor dans l’éditeur et dans Tale

Un agent de l’éditeur modifie les fichiers de configuration locaux. Un [agent de projet](https://docs.tale.dev/fr/platform/projects/project-agents) Tale utilisant le harness Cursor travaille dans une sandbox gérée par Tale. Ces contextes d’exécution ont des identifiants et des conséquences distincts.

Le harness de la sandbox utilise son compte fournisseur et son modèle configurés. Ajouter les instructions à ton éditeur ne configure pas ce compte. Consulte [Harnesses](https://docs.tale.dev/fr/platform/agents/harnesses) pour préparer l’exécution dans Tale.

## Examiner et appliquer une proposition

1. Demande un changement précis et indique s’il vise le modèle des nouvelles organisations ou une organisation existante.
2. Vérifie chaque chemin, champ de schéma, slug et référence d’identifiants. Garde les secrets hors du prompt et du diff public.
3. Valide ou teste dans la surface produit correspondante. Pour une automatisation, examine la validation et les tests simulés avant de la déployer.
4. Contrôle le plan de déploiement et l’organisation cible. `tale deploy --override` peut remplacer la configuration d’exécution par la copie locale ; réserve-le à un remplacement délibéré et relu.
5. Relis la configuration enregistrée et teste le comportement après le déploiement.

Si l’agent propose un champ absent du schéma installé, corrige la proposition avant d’appliquer le changement. Si modifier `default/` ne change pas une organisation existante, vérifie la destination au lieu de redéployer le modèle à répétition.

# Référence API
Source: https://docs.tale.dev/fr/develop/api-reference

L’API REST permet de lire et modifier les ressources Tale avec une clé API : projets, fichiers, tâches, automatisations, exécutions et fils de conversation. Vérifie l’accès avec [ta première requête API](https://docs.tale.dev/fr/get-started/developers), puis utilise les sections consacrées aux opérations.

Ton instance sert le schéma OpenAPI détaillé sur `/openapi.json` et une référence interactive sur `/docs`. Utilise son schéma pour générer un client. Cette page explique les droits, le périmètre, les traitements asynchrones et les erreurs communs à ces opérations.

## Une première requête

Définis `TALE_URL` comme origine de l'application, `TALE_API_KEY` comme ta clé et `TALE_ORG_SLUG` comme l'organisation visée. Conserve les secrets dans l'environnement. Vérifie d'abord l'identité avant de créer des ressources :

```bash
curl --fail-with-body --compressed "$TALE_URL/api/v1/me" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG"
```

Une réponse `200` contient `user`, l'`organization` sélectionnée, toutes les `organizations` actuelles, les `capabilities` du déploiement et le nom et l’expiration de la clé sous `key`. Vérifie l’organisation et le rôle avant de continuer. Les exemples suivants emploient des IDs de projet, fichier et exécution fictifs : reprends les vrais IDs dans les réponses précédentes, sans copier un nom affiché ni deviner une valeur.

### Lire toutes les pages d’une liste

Les réponses contiennent des collections nommées, pas un tableau nu. Les schémas OpenAPI `200` de l'instance déclarent `x-tale-pagination` pour choisir la bonne boucle.

| Famille | Requête | Réponse et condition d'arrêt |
| --- | --- | --- |
| Keyset | `cursor`, `limit` | Éléments, `isDone` et `continueCursor` ; arrêter à `isDone: true` |
| Offset : pages de sites uniquement | `cursor` ou `offset`, jamais les deux | `pages`, `total`, `offset`, `hasMore`, plus `isDone` et `continueCursor` signé |
| Sans pagination | Ni `cursor` ni `limit` | Tableau nommé contenant l'ensemble complet ou la sélection bornée annoncée |

Pour les listes keyset, renvoie `continueCursor` sans le modifier. Ne le décode pas et ne l'incrémente pas. À la dernière page, il est vide ; le renvoyer produit `400 INVALID_QUERY`, pas un retour à la première page. Chaque opération indique son plafond : généralement 100 ou 200, et 500 pour les commentaires de tâche. Les valeurs de `limit` supérieures au plafond sont ramenées à ce maximum.

Contacts, produits, documents, entrées de connaissance, fils, messages, sites et exports de notifications placent leurs lignes keyset sous `page`. Exécutions, livraisons, commentaires de tâche, projets et fichiers de projet utilisent le nom de leur ressource, comme `runs` ou `files`. Les exécutions sont classées de la plus récente à la plus ancienne, par 50 par défaut, avec une limite de 1–200. `GET /api/v1/runs` couvre les exécutions visibles de toutes les automatisations.

Automatisations, agents, skills, dossiers, modèles, sessions navigateur, versions et déclencheurs ne sont pas paginés. Une requête de pages de site contenant `cursor` et `offset` reçoit `400 INVALID_QUERY`. Le curseur signé du prochain offset fonctionne aussi avec la boucle keyset habituelle.

Les contacts et produits sont triés par `updatedAt`, puis `id`, dans l’ordre décroissant. Modifier une ligne pendant le parcours peut la déplacer avant ton curseur : ce passage peut donc manquer la modification. Pour un rapprochement complet, compare le `updatedAt` de chaque ligne et répète des parcours entiers. Un curseur ne garantit pas un instantané d’un répertoire qui évolue. Les documents du centre, projets, fichiers de projet et sites sont triés par `createdAt`, du plus récent au plus ancien.

## Authentification

Crée les clés dans **Paramètres > API > REST** en tant que propriétaire, admin ou développeur, ou en tant que membre à qui un admin a attribué une compétence qui s’utilise avec une clé (`tale:models.api`, `tale:notifications.export` ou `tale:rest.act-as`) ; toute autre personne est refusée avec `403 API_KEY_CREATE_FORBIDDEN` ; [Clés API](https://docs.tale.dev/fr/platform/admin/api-keys) explique l’interface. Une clé n’apparaît qu’une fois et agit comme la personne qui l’a créée. Cette surface REST ne crée, liste, renouvelle ni révoque les clés.

| En-tête | Règle |
| --- | --- |
| `Authorization: Bearer <key>` | Seul emplacement accepté ; conserver toute la chaîne opaque, y compris son préfixe `tale` |
| `X-Organization-Slug: <slug>` | Sélectionner une appartenance actuelle ; toujours l'envoyer dans une intégration réutilisable |
| `x-api-key` | Refusé avec `401`, même avec un Bearer valide ; ne transforme pas la clé en session applicative. Sur l’[endpoint de modèles](https://docs.tale.dev/fr/develop/api-reference#model-endpoints) compatible Anthropic, le refus indique la marche à suivre : passer la clé comme jeton d’authentification, avec `ANTHROPIC_AUTH_TOKEN` pour Claude Code ou `authToken` et `auth_token` pour les SDK Anthropic, et laisser `ANTHROPIC_API_KEY` non définie (contrat 3.6.0) |

Une personne appartenant à une seule organisation peut omettre l'en-tête d'organisation. Avec plusieurs appartenances, il est nécessaire à chaque appel, lectures comprises. L'organisation ouverte dans le tableau de bord ne sélectionne jamais le périmètre API. La casse du slug est ignorée ; une valeur vide ou composée d'espaces compte comme absente.

| Sélection d'organisation | Résultat |
| --- | --- |
| Plusieurs appartenances, aucun slug | `400 ORG_SLUG_REQUIRED` |
| Slug inconnu, ou valeur qui ne peut pas être un slug | `404 ORG_SLUG_INVALID` |
| Organisation existante sans appartenance, ou avec une appartenance désactivée | `403 ORG_FORBIDDEN` |
| Appartenance valide | La requête continue avec cette organisation et ce rôle |

Chacun de ces trois refus liste dans `data.organizations` les organisations que tu peux sélectionner, sous forme de paires `slug` et `name`. Les appartenances désactivées en sont exclues ; s'il n'en reste aucune, la liste est vide. Relance la requête avec l'un des slugs listés.

`GET /api/v1/me` renvoie aussi les appartenances sous `organizations`. `key.expiresAt` est un horodatage Unix en millisecondes, ou `null` pour une clé sans expiration. Renouvelle les identifiants des traitements autonomes avant que l'expiration provoque `401`. `key.name` identifie la clé utilisée.

Avant de proposer une opération, vérifie le rôle et l’accès à la ressource. Un lecteur de projet peut discuter, commenter et créer des tâches, puis modifier et démarrer celles qu’il a créées ou qui lui sont attribuées ; les modifications des autres ressources et des tâches des autres demandent un accès en écriture.

| Capacité renvoyée par `/me` | Autorisation |
| --- | --- |
| `developer` | Les rôles Propriétaire, Admin et Développeur peuvent démarrer des exécutions réelles arbitraires, annuler ou supprimer des exécutions, lier ou retirer des déclencheurs, supprimer des automatisations et installer ou retirer celles d’un projet. Sinon, ces opérations REST donnent `403 ROLE_FORBIDDEN`. MCP vérifie aussi cette capacité pour enregistrer, déployer et utiliser d’autres outils privilégiés, avec son propre format d’erreur. La validation et les outils de simulation restent accessibles aux membres. L’accès au projet est vérifié séparément. |
| `deploymentEditor` | La liste d’autorisation de l’opérateur permet d’importer ou de révoquer des sessions de navigateur. Un rôle administratif seul ne donne pas cette capacité. |
| `notificationExport` | La clé peut exporter les notifications des membres avec `GET /api/v1/notifications/sync`. Les Propriétaires et Admins disposent de cette capacité par leur rôle ; les autres membres seulement tant qu’une attribution `tale:notifications.export` accordée par un Admin est active. Voir [Déléguer l’export sans rôle Admin](https://docs.tale.dev/fr/develop/api-reference#deleguer-lexport-sans-role-admin). Sinon, l’export renvoie `403 ROLE_FORBIDDEN`. |
| `skillPublish` | La clé peut partager un skill avec toute l’organisation par `PUT /api/v1/skills/{slug}`. Sans politique de partage des skills, chaque membre le peut ; avec elle, seulement les rôles qu’elle admet et les membres qui détiennent une attribution `tale:skills.publish` active — voir [Enregistrer et synchroniser les bundles de skills](https://docs.tale.dev/fr/develop/api-reference#enregistrer-et-synchroniser-les-bundles-de-skills). Sans ce droit, un tel enregistrement renvoie `403 SKILL_PUBLISH_FORBIDDEN`. |
| `actAs` | La clé peut nommer un `actor` — le membre vérifié pour lequel un geste relayé est enregistré — sur `POST …/runs/{runId}/asks/{askId}` et `POST …/tasks/{taskId}/review`. Les Propriétaires et les Admins l’ont par leur rôle ; tout autre membre seulement tant qu’une attribution `tale:rest.act-as` faite par un Admin est active — voir [Nommer le membre pour lequel on agit](https://docs.tale.dev/fr/develop/api-reference#nommer-le-membre-pour-lequel-on-agit). Sans ce droit, un `actor` envoyé donne `403 ROLE_FORBIDDEN`. |
| `modelApi` | La clé peut appeler les [endpoints de modèles compatibles](https://docs.tale.dev/fr/develop/api-reference#model-endpoints) : l’organisation les a activés et le détenteur de la clé peut les appeler. Les Propriétaires, Admins et Développeurs le peuvent par leur rôle ; tout autre membre seulement tant qu’une attribution `tale:models.api` faite par un Admin est active. Sinon, ces routes répondent `403 MODEL_API_DISABLED` ou `403 MODEL_API_FORBIDDEN` (contrat 3.6.0). |

## Ce que chaque requête doit respecter

### Valider le JSON et les paramètres de requête

Envoie du JSON en UTF-8. L’API refuse l’UTF-8 invalide, les caractères NUL, les substituts UTF-16 non appariés dans les clés ou les valeurs et les entiers au-delà de 2^53 − 1 avec `400 INVALID_BODY`. Représente les grands identifiants par des chaînes. Les erreurs imbriquées donnent le chemin complet, comme `messages.0.createdAt`. Les IDs sont des chaînes et les dates des horodatages Unix en millisecondes. Un horodatage envoyé est un nombre entier de millisecondes de `0` à `8640000000000000` (13/09/275760, le dernier instant qu’une `Date` JavaScript peut représenter) ; toute autre valeur renvoie `400 INVALID_BODY`. Le `updatedAt` d’un skill correspond à l’écriture de son `SKILL.md`.

| Entrée | Règle |
| --- | --- |
| Clé inconnue dans le corps | `400 INVALID_BODY`, avec le nom de la clé dans le détail de l’erreur |
| Clé JSON répétée | La dernière valeur gagne |
| Paramètre de requête inconnu, répété ou vide | `400 INVALID_QUERY` |
| Paramètres d’URL sur une écriture | Refusés ; les écritures n’acceptent aucun paramètre de requête |
| `limit` dans l’URL hors plage | Ramené à la plage de l'opération |
| Valeur numérique hors plage dans le corps | `400 INVALID_BODY`, par exemple `limit` de recherche ou `maxOutputTokens` |
| `Content-Type` | Le corps est lu comme du JSON indépendamment de cet en-tête ; pas de `415` sur cette surface |

Les opérations JSON renvoient du JSON quel que soit `Accept`, même si cet en-tête demande un autre format ou exclut JSON. Elles ne renvoient pas de `406`.

### Limites de taille et de réception

| Corps | Maximum |
| --- | --- |
| Requête JSON ordinaire | 1 Mio |
| Contenu de document intégré | 32 Mio |
| Requête vers un endpoint de modèles | 32 Mio |
| Import groupé de contacts | 8 Mio |
| Instantané de conversation | 8 Mio |
| Chargement préparé pour une conversation | 30 Mio |
| Enregistrement de skill | 4 Mio |
| Réservation, signalement d’échec ou confirmation de livraison | 64 Kio |

Un corps trop grand reçoit `413 BODY_TOO_LARGE`. Si la longueur déclarée dépasse déjà la limite, la plateforme refuse sans lire le corps ; sinon elle s'arrête au premier bloc qui la dépasse. Elle ne garde jamais le corps trop volumineux en entier. Les règles d'envoi peuvent imposer un plafond inférieur à ces limites de transport.

En-têtes et corps doivent arriver en moins de 15 minutes. Un corps de 30 Mio demande environ 35 Ko/s pour respecter ce délai. Une requête plus lente reçoit `408 REQUEST_TIMEOUT` et la connexion se ferme. Utilise une connexion plus rapide, de plus petites requêtes prises en charge ou l'envoi de projet en deux étapes, qui transfère les octets hors de cette fenêtre JSON.

### Méthodes et identifiants de réponse

Les routes de lecture existantes acceptent `HEAD`, avec la taille du `GET` non compressé et sans corps. `HEAD` n'est jamais compressé. `OPTIONS` est sans clé et renvoie `204` avec `Allow`. Une méthode non prise en charge sur une route existante reçoit `405 METHOD_NOT_ALLOWED` et les méthodes permises. Une barre oblique finale est tolérée.

La surface REST de production est destinée aux appels serveur à serveur et n'active pas CORS. Conserve les clés API dans ton propre backend. Le JSON de statut sans clé est une surface distincte avec CORS.

Chaque réponse API contient `X-Request-Id`. Pour relier un appel aux logs, envoie jusqu'à 255 caractères parmi lettres, chiffres, `_`, `-` et `=`. Une valeur invalide est remplacée par un UUID neuf ; la réponse indique la valeur réellement utilisée. Les réponses `429`, `500`, `413` et `414` ajoutent aussi `requestId` à l'enveloppe JSON. Deux refus font exception, parce que l’analyseur HTTP du frontal y répond avant qu’une requête existe à journaliser : le `431` nu pour des en-têtes au-delà du budget de 64 Kio et le `400` nu pour un caractère de contrôle dans une valeur d’en-tête ne portent ni `X-Request-Id`, ni enveloppe, ni `X-Tale-Api-Version` — il n’y a rien à citer, et c’est la requête elle-même qu’il faut changer.

`Idempotency-Key` n’est lu que par les opérations qui déclarent l’en-tête — un démarrage d’exécution, un envoi de chat ; le document OpenAPI les liste, et les portes webhook le lisent comme id de livraison selon leur propre règle. Toute autre opération ignore l’en-tête : sa garantie au-plus-une-fois est la clé naturelle que nomme son corps — l’`externalId` d’un contact, le `(externalSystem, externalId)` d’une tâche, l’`externalItemId` d’un projet. Un `Expect: 100-continue` obtient un `100 Continue` du frontal dès qu’il commence à transmettre le corps ; le verdict de la plateforme — un `413` pour une longueur déclarée au-delà du plafond — arrive quand même avant qu’un octet du corps soit lu.

Les réponses de `/api/v1` et des webhooks portent `X-Tale-Api-Version` ; voir [Versionnage](https://docs.tale.dev/fr/develop/api-reference#versionnage). Les routes sans clé `/api/health`, `/status`, `/status.json` et `/openapi.json` n'implémentent pas ce contrat et n'ont pas cet en-tête.

<Accordion title="Détails HTTP et comportement du proxy">

L’URL, paramètres de requête compris, est limitée à 32 Kio ; au-delà, elle reçoit `414 URI_TOO_LONG` avant recherche de route. Le proxy accorde 64 Kio aux en-têtes. HTTP/1.1 laisse quelques Kio de marge avant un `431` sans enveloppe ; une URL de 66 Kio peut donc atteindre la plateforme et recevoir `414`. HTTP/2 applique exactement la limite en fermant la connexion sans réponse.

Les caractères de contrôle inférieurs à 0x20, sauf tabulation, et DEL dans les en-têtes sont refusés avant la plateforme : HTTP/1.1 renvoie un `400` en texte brut, sans `X-Request-Id` ; HTTP/2 réinitialise le flux ou ferme une connexion portant un corps.

Pour un corps dont la longueur déclarée dépasse la limite, le proxy HTTP/1.1 peut évacuer jusqu'à 256 Kio avant de transmettre le refus, bien que la plateforme ne lise rien. Si le corps finit avant sa longueur déclarée, HTTP/2 renvoie `400 BODY_LENGTH_MISMATCH`, sauf si le `413` de dépassement est arrivé en premier. HTTP/1.1 attend les octets manquants jusqu'au délai de 15 minutes.

Les refus du proxy ont leur propre identifiant et aucun `X-Tale-Api-Version` : le proxy ne connaît pas le contrat applicatif. Cela inclut les `404` sur des segments de chemin comme `..`, `BODY_LENGTH_MISMATCH` et `502`/`503`/`504 UPSTREAM_UNAVAILABLE` lors d'un redémarrage. Un `503 DATABASE_UNAVAILABLE` vient en revanche de la plateforme elle-même, pendant le redémarrage de sa base de données : comme toute réponse de la plateforme, il porte son identifiant de requête et `X-Tale-Api-Version`. Ne suppose pas que chaque intermédiaire renvoie l'enveloppe JSON de l'API.

Une requête HTTP/1.1 dont le découpage en chunks est mal formé, par exemple une taille non hexadécimale ou un CRLF manquant, reçoit `400 BODY_CHUNK_MALFORMED` au proxy. Corrige le client HTTP ou l’intermédiaire qui encode la requête ; renvoyer les mêmes octets ne résout pas le problème. Ce refus porte sa propre `requestId` et aucun `X-Tale-Api-Version`.

</Accordion>

## Cache, compression et lectures partielles

### Réutiliser les réponses inchangées

Une lecture JSON réussie (`GET`, **200**) inclut un `ETag` calculé à partir du corps de la réponse et `Cache-Control: private, no-cache`. Conserve cette réponse et envoie son tag dans `If-None-Match` à la lecture suivante. Si elle n’a pas changé, le serveur répond **304**, sans corps. Tu peux ainsi suivre une exécution, un fil inactif ou une indexation sans retransférer les mêmes données.

Renvoie le tag sans le modifier. Le proxy ajoute `-gzip` ou `-zstd` au tag des réponses compressées ; l’API reconnaît ces formes et la forme faible `W/"…"`. Sa réponse **304** contient le tag qu’elle a calculé.

Les téléchargements `GET /api/v1/projects/{id}/files/{documentId}/content` et `GET /api/v1/documents/{id}/content` acceptent aussi `If-None-Match` et `If-Modified-Since`. Utilise les valeurs `ETag` et `Last-Modified` qu’ils ont renvoyées.

Les dates sont comparées à la seconde près, conformément au format HTTP. Si les deux en-têtes conditionnels sont présents, seul `If-None-Match` détermine le résultat. Pour un document dont le contenu est stocké directement dans `content`, `Last-Modified` correspond à `updatedAt` : modifier le titre ou les métadonnées change donc aussi cette date. Privilégie l’`ETag` pour détecter uniquement une modification des octets. Une **304** compte dans les [limites de débit](https://docs.tale.dev/fr/develop/rate-limits).

```bash
# La première lecture répond 200 et son ETag ; la répétition avec ce tag répond 304
curl -sS --compressed -D - -o /dev/null "https://your-host.example.com/api/v1/projects/<projectId>/runs/<runId>?fields=status,finishedAt" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG" \
  -H 'If-None-Match: "<ETag de la réponse précédente>"'
```

### Demander la compression

Demande `gzip` ou `zstd` dans `Accept-Encoding`, par exemple avec `curl --compressed`. Le serveur compresse les réponses JSON et texte à partir d’environ 512 octets ; il ne sert pas `br`.

Lorsqu’il est présent, `Content-Length` indique la taille compressée. Les réponses volumineuses transmises en flux peuvent l’omettre. L’`ETag` reçoit le suffixe `-gzip` ou `-zstd`. Une réponse `HEAD` reste non compressée et indique la longueur non compressée.

Active cette option pour réduire le volume transféré par les listes et les réponses contenant beaucoup de données répétées. La compression ne réduit pas le nombre de requêtes décomptées de ton quota.

### Lire uniquement les champs nécessaires

Certaines opérations permettent de limiter les données renvoyées. Pour une exécution, `?fields=status,finishedAt` retourne uniquement ces deux champs ; tu peux demander d’autres clés de l’exécution en les séparant par des virgules.

Les listes d’exécutions qui demandent des lignes complètes avec `?include=` sont limitées à 25 lignes et 8 Mio par page. Si la limite de taille est atteinte, la page s’arrête à la dernière ligne qui tient et renvoie `isDone: false` avec son `continueCursor`. Continue jusqu’à `isDone: true`, même si une page contient moins de 25 lignes.

## Se connecter à une application avec Tale

Tale peut servir de fournisseur d’identité OpenID Connect pour une application enregistrée. L’utilisateur s’authentifie dans Tale et donne son consentement. L’application reçoit une identité signée, une adresse e-mail vérifiée et l’appartenance à l’organisation associée au client. Ce parcours utilise une connexion personnelle, pas une clé API.

Pour enregistrer l’application, utilise une session active de Propriétaire ou d’Admin dont l’organisation sélectionnée correspond à `TALE_ORG_ID`. Définis `TALE_ORIGIN` avec l’origine de ton instance et `TALE_SESSION_COOKIE` avec l’en-tête Cookie de cette session. Fournis l’URL de rappel HTTPS exacte ; HTTP est accepté uniquement sur la boucle locale, pour le développement.

```bash
curl -sS --compressed -X POST "$TALE_ORIGIN/api/app/identity/clients?orgId=$TALE_ORG_ID" \
  -H "Cookie: $TALE_SESSION_COOKIE" \
  -H "Origin: $TALE_ORIGIN" \
  -H "Content-Type: application/json" \
  -d '{"key":"office-app","name":"Office application","redirectUri":"https://office.example.com/api/auth/oauth2/callback/tale"}'
```

La création répond **201** avec `{ "created": true, "client": { "client_id": "…", "client_secret": "…", … } }`. Stocke le secret dans l’environnement protégé de l’application. Répéter la requête avec la même clé et la même configuration répond **200**, `created: false`, avec le même identifiant client mais sans secret. Si l’URL de rappel ou la politique diffère, la réponse est **409** : une nouvelle tentative ne peut pas modifier silencieusement une intégration existante.

| Usage             | Endpoint ou exigence                                                         |
| ----------------- | ---------------------------------------------------------------------------- |
| Émetteur          | `https://your-host.example.com/api/auth`                                     |
| Découverte        | `GET /api/auth/.well-known/openid-configuration`                             |
| Autorisation      | `GET /api/auth/oauth2/authorize`                                             |
| Échange du code   | `POST /api/auth/oauth2/token`, `client_secret_basic` ou `client_secret_post` |
| Clés de signature | `GET /api/auth/jwks`                                                         |
| Identité actuelle | `GET /api/auth/oauth2/userinfo`, jeton d'accès Bearer                        |
| Scopes demandés   | `openid profile email tale:organization`                                     |

Utilise une bibliothèque OIDC maintenue avec le flux Authorization Code, PKCE S256, un paramètre `state` à usage unique et un nonce. Vérifie l’émetteur, l’audience, la signature RS256, l’expiration et le nonce du jeton d’identité, puis exige `email_verified: true`. Le claim `https://tale.dev/organization` contient `{ "id", "slug", "role" }` pour l’organisation du client.

Le jeton d’identité contient les claims standard des scopes demandés, avec les valeurs que renvoie Userinfo : tu n’as donc pas besoin d’appeler Userinfo pour les lire. `email` ajoute `email` et `email_verified`. `profile` ajoute `name`, ainsi que `given_name` (tous les mots sauf le dernier) et `family_name` (le dernier mot) quand le nom compte au moins deux mots, et `picture` si le compte a une image.

Le jeton contient toujours `acr: "0"`. La découverte annonce `"0"` dans `acr_values_supported` et `acr` dans `claims_supported`. Elle ne prouve pas un niveau d’authentification plus fort, notamment une authentification MFA. N’en déduis aucune autorisation supplémentaire. Les versions à partir de v0.5.45 documentaient `urn:mace:incommon:iap:bronze` alors que le jeton portait déjà `"0"` ; une application cliente figée sur cette URN doit accepter `"0"`.

La découverte annonce `none`, `login` et `consent` dans `prompt_values_supported`. `select_account` et `create` ne sont pas pris en charge. Tale vérifie l’appartenance actuelle à l’organisation et l’exigence MFA native avant d’émettre les jetons, puis à chaque appel à Userinfo. L’application applique sa propre politique d’accès.

Un code d’autorisation, un jeton d’accès et un jeton d’identité expirent après cinq minutes, et un code ne peut être échangé qu’une fois. L’enregistrement dynamique, le flux implicite et les jetons de renouvellement sont désactivés.

Les jetons d’accès servent uniquement au point de terminaison natif `userinfo` ; les audiences de ressources externes sont désactivées. Pour appeler l’API REST, utilise une clé API Tale.

### Traiter les erreurs du fournisseur d’identité

Les erreurs suivent les RFC 6749 et 6750. Sur `userinfo` :

- Un jeton invalide ou expiré donne **401**, `invalid_token`, avec `WWW-Authenticate: Bearer`. Après son expiration à cinq minutes, relance la connexion : réessayer avec le même jeton ne suffit pas.
- Sans jeton, la réponse est **401** avec le défi Bearer sans détail d’erreur.
- Sans scope `openid`, la réponse est **403**, `insufficient_scope`.

Les endpoints d’autorisation et de jeton renvoient `{ "error", "error_description" }`. Un type de flux autre que `authorization_code` donne `unsupported_grant_type`. Une requête mal formée donne `invalid_request`, notamment si `grant_type` manque. La description précise le paramètre concerné : `grant_type is required`, `client_id is required` ou `response_type must be one of "code"`.

Un type de contenu incorrect, par exemple un formulaire envoyé à l’endpoint JSON `register`, donne **400**, `invalid_request`, avec le type attendu. Cette interface ne renvoie pas **415** dans ce cas.

Si `client_id` est inconnu, Tale redirige vers sa propre page d’erreur, jamais vers la `redirect_uri` fournie. Le paramètre `error=invalid_client` et sa description distinguent un client inconnu d’un identifiant manquant.

La découverte inclut `https://tale.dev/organization` dans `claims_supported`. Elle annonce également les endpoints d’introspection, de révocation et de fin de session ; le parcours décrit ici n’en a pas besoin.

### Renouveler ou désactiver un client applicatif

Les opérations suivantes exigent les mêmes conditions que l’enregistrement : une session administrateur, l’organisation active correspondante, l’en-tête Origin et un corps JSON.

- `POST /api/app/identity/clients/office-app/rotate-secret?orgId=<orgId>` avec `{}` renvoie le nouveau `client_secret` une seule fois et invalide l’ancien.
- `POST /api/app/identity/clients/office-app/status?orgId=<orgId>` avec `{ "disabled": true }` bloque les nouvelles autorisations. Envoie `false` pour réactiver le même client.

La suppression d’une organisation supprime aussi ses clients et leurs consentements.

## Groupes d'endpoints

Pour une ressource de projet sous `/api/v1`, place l’ID du projet dans son URL. Ces corps de requête n’acceptent pas `projectId` : les schémas stricts le refusent avec **400**. La ressource doit appartenir au projet nommé et être visible pour le détenteur de la clé ; sinon, l’appel donne **404**. Les réponses peuvent contenir `projectId` comme métadonnée. Les catalogues de l’organisation, comme les définitions d’automatisations et les bundles de skills, gardent leurs chemins d’organisation.

Chaque **201** qui crée une ressource adressable porte `Location` — le chemin propre de la ressource, relatif à l’URL de la requête —, si bien qu’un client générique la suit quelle que soit la forme du corps (`{id}` pour un contact, `{project}` pour un projet, `{task}` pour une tâche) ; l’import en masse de contacts en crée plusieurs et n’en porte aucune.

| Ressource | Chemin et portée |
| --- | --- |
| Automatisations | `/api/v1/automations/...`<br>Consulter les définitions, versions, déclencheurs et projets associés ; supprimer une définition ; démarrer et lister les exécutions sans projet. |
| Automatisations du projet | `/api/v1/projects/{id}/automations/...`<br>Lister, installer ou désinstaller les automatisations ; démarrer et lister leurs exécutions dans ce projet. |
| Exécutions | `/api/v1/runs/...` ou `/api/v1/projects/{id}/runs/...`<br>Lister les exécutions ; lire leur statut, sortie, trace et effets ; annuler avec `POST .../{runId}/cancel` ou supprimer une exécution terminée avec `DELETE .../{runId}` ; lire la question d’une exécution en attente avec `GET .../ask` et y répondre avec `POST .../asks/{askId}`. |
| Fils de conversation | `/api/v1/projects/{id}/threads/...` ou `/api/v1/threads/...`<br>Gérer les chats du détenteur de la clé, dans un projet ou sans projet : lister, créer, lire, archiver, restaurer et supprimer ; envoyer un message, suivre ou annuler son tour. |
| Modèles | `GET /api/v1/models`<br>Consulter les modèles de chat configurés et accessibles au détenteur de la clé dans l’organisation, leurs capacités et leurs tarifs ; `harnesses` liste les harness de code sur lesquels un agent de projet peut tourner. |
| Équipes | `GET /api/v1/teams`<br>Chaque équipe de l’organisation — `id`, `name` et `member`, qui dit si le détenteur de la clé en fait partie — en une liste complète : ce sont les identifiants qu’attend une audience d’équipes (`teamIds` sur un projet ou un document du Hub, `teams` sur un skill). Les équipes se créent et se composent dans l’application (Paramètres > Équipes) ou par un fournisseur d’identité ; rien sur cette surface n’en écrit une. |
| Agents | `/api/v1/projects/{id}/agents/...`<br>Lister, lire, créer, modifier ou supprimer les agents du projet ; protéger une modification avec `expectedUpdatedAt`. Un `PUT` qui reprend exactement la configuration enregistrée n’écrit rien et laisse `updatedAt` intact. |
| Skills | `/api/v1/skills/...`<br>Lister, lire, créer, modifier ou supprimer les bundles de l’organisation ; lire leurs fichiers — une lecture validée (`ETag` et `Last-Modified` sur les octets ; `If-None-Match` / `If-Modified-Since` répondent **304**) ; protéger une écriture avec `If-Match`. Un skill n’a pas d’historique de versions sur cette surface : la lecture répond le bundle courant, rien d’autre. |
| Entrées de connaissances | `/api/v1/knowledge-entries/...`<br>Lister avec `?topic=` et `?status=`, créer, remplacer ou supprimer une entrée ; lire l’historique d’un sujet avec `GET .../{id}/versions`. |
| Recherche de connaissances | `POST /api/v1/projects/{id}/knowledge/search` ou `POST /api/v1/knowledge/search`<br>Rechercher dans les fichiers indexés d’un projet, ou dans les documents visibles de la base de connaissances hors projet et les sites web. |
| Documents | `/api/v1/documents/...`<br>Créer, lire, modifier et supprimer les documents de la base de connaissances ; télécharger leur contenu avec `GET .../content` ; relancer l’indexation avec `POST .../retry-indexing`. Les fichiers de projet ont leurs propres routes. |
| Sites web | `/api/v1/websites/...`<br>Créer, lire, modifier et supprimer les sources web ; consulter leurs pages avec `.../pages` (`?state=failed` ou `?state=skipped` limite la fenêtre aux pages dans cet état : `total`, `hasMore` et le curseur ne comptent alors que cet état, un curseur émis sous un état est refusé sous un autre, et chaque fenêtre porte `counts`, le nombre de pages en échec et de pages ignorées), les synchroniser avec `.../sync` et y rechercher du contenu avec `.../search`. La découverte respecte les règles `Disallow` du `robots.txt` sur chaque chemin par lequel une URL peut entrer — les URL listées exceptées — et une page qu’une règle couvre quitte l’index à l’analyse suivante ; les compteurs de pages sont posés par la synchronisation corpus → ligne (`metadata.lastStatusSyncAt` dit quand, `POST .../sync` la force) et `lastScannedAt` est la fin de la dernière analyse ; `POST /api/v1/websites` refuse un domaine en `http://` (`WEBSITE_DOMAIN_INVALID` — le crawler ne compose qu’en https) et laisse tomber un point final ; le `lastError` d’une page est une ligne qui nomme la cause, jamais le journal d’appels d’un framework. |
| Sessions de navigateur | `/api/v1/browser-sessions/...`<br>Consulter une liste masquée, importer avec `POST .../import` et révoquer avec `DELETE .../{id}` les sessions utilisées pour l’[ingestion vidéo](https://docs.tale.dev/fr/self-hosted/configuration/video-ingestion). |
| Produits | `/api/v1/products/...`<br>Créer, lire, modifier et supprimer les entrées du catalogue produit. |
| Contacts | `/api/v1/contacts/...`<br>Créer, lire, modifier et supprimer les contacts ; importer un ensemble avec `POST /api/v1/contacts/bulk`. |
| Conversations | `/api/v1/conversations/...`<br>Synchroniser des instantanés externes dans la boîte de réception et lire leurs reçus ; consulter la file de livraison, réserver les réponses, confirmer ou signaler un échec de livraison, relancer un échec définitif et confier une conversation synchronisée à une équipe. |
| Notifications | `GET /api/v1/notifications/sync`<br>Export en lecture seule du flux personnel ou d’organisation d’un membre vérifié ; réservé aux Propriétaires/Admins et aux membres auxquels un Admin a accordé `tale:notifications.export`. Pagination signée, textes localisés, IDs stables et empreintes du contenu et de l’état de lecture. |
| Projets | `/api/v1/projects/...`<br>Lister les projets ou en chercher un par identifiant externe ; créer, archiver, restaurer ou supprimer un projet ; gérer ses dossiers et charger, télécharger, supprimer ou indexer ses fichiers. |
| Tâches | `/api/v1/projects/{id}/tasks/...`<br>Créer une tâche depuis une référence externe sans doublon, lire son état, démarrer un workflow, commenter, et traiter sa relecture : `GET .../review` la lit, `POST .../review` la décide pour un membre. Le démarrage renvoie le `runId` à suivre. |
| MCP | `POST /api/v1/mcp`<br>Appeler l’[endpoint MCP](https://docs.tale.dev/fr/develop/mcp-endpoint) avec la même clé, en JSON-RPC. |
| Endpoints de modèles | `/api/v1/openai/...` et `/api/v1/anthropic/...`<br>Appels compatibles OpenAI et Anthropic aux modèles de l’organisation, désactivés tant qu’un admin ne les a pas activés ; voir [Endpoints de modèles compatibles](https://docs.tale.dev/fr/develop/api-reference#model-endpoints). |
| Déclencheur webhook | `POST /api/projects/{id}/automations/webhook/{token}` ou `POST /api/automations/webhook/{token}`<br>Démarrer une automatisation déployée avec son jeton ; voir [Webhooks](https://docs.tale.dev/fr/develop/webhooks) pour les URL avec ou sans projet. |

**Exécutions.** `GET /api/v1/runs` liste les exécutions visibles de toutes les automatisations. Pour lire une exécution de projet, utilise `/api/v1/projects/{id}/runs/{runId}`, y compris pour l’annuler ou la supprimer. `/api/v1/runs/{runId}` expose uniquement une exécution sans projet.

**Modèles.** Chaque modèle expose `contextWindow` et ses capacités. `pricing` est présent lorsque le catalogue renseigne les tarifs. `maxOutputTokens` est absent si le catalogue ne déclare aucun plafond ; dans ce cas, l’API ne contrôle pas ce plafond à l’envoi. Le modèle choisi par défaut dans l’organisation porte `default: true` s’il est configuré et accessible.

**Exploration des sites web.** Une page porte `status: discovered` jusqu’à ce qu’une récupération en stocke le contenu, puis `status: active`. Elle expose `failCount` et, si sa dernière tentative a échoué, `lastError`, `lastErrorKind` et `lastErrorAt`. Ces champs distinguent une page encore jamais récupérée d’une tentative refusée, par exemple après une redirection vers une adresse privée. Au niveau du site, `crawledPageCount` compte toutes les pages dont la récupération a été tentée, qu’elles aient été stockées ou non. `failedPageCount` compte celles dont la dernière tentative a échoué.

**Recherche dans un site.** `.../search` renvoie `{results, total}`. Chaque résultat contient `url`, `title`, `content`, `chunkIndex` et `score`. Cette réponse diffère de `{hits, diagnostics}`, utilisé par la recherche de connaissances. Le champ `limit` se trouve dans le corps et accepte 1 à 100, avec 10 par défaut. Une valeur hors plage donne **400**, `INVALID_BODY` ; elle n’est pas ramenée au plafond.

**Sessions de navigateur.** Les membres peuvent consulter la liste masquée des sessions de leur organisation. L’import et la révocation exigent les droits d’administration de l’instance et l’inscription sur la liste d’autorisation du déploiement. Vérifie `capabilities.deploymentEditor` dans `GET /api/v1/me` avant ces écritures. Une session expire après 14 jours par défaut et peut durer au maximum 180 jours.

Pour enregistrer, valider, tester et déployer des définitions d’automatisation, utilise le [point d’accès MCP](https://docs.tale.dev/fr/develop/mcp-endpoint) ou l’éditeur de l’application. Cette interface REST ne propose pas ces opérations de création. `tale deploy` publie la configuration d’un déploiement ; ce n’est pas une route REST de création de définitions.

### Préserver une modification concurrente

Si ta modification dépend de la dernière ligne lue, transmets son `updatedAt` dans `expectedUpdatedAt` lors du `PATCH` d’un contact, produit ou document. Une valeur périmée donne `409 CONTACT_STALE`, `PRODUCT_STALE` ou `DOCUMENT_STALE`. Recharge la ressource, fusionne ta modification avec celle survenue entre-temps, puis envoie la nouvelle précondition.

Pour les documents du centre, `If-Match` protège aussi la représentation lue : envoie l’`ETag` fort reçu lors du `GET`. La comparaison se fait dans la transaction d’écriture du document. Un tag qui ne correspond plus donne `412 PRECONDITION_FAILED`, avec le tag courant dans `data.etag`, sans écriture. Une liste de tags ou `*` est acceptée ; un tag faible `W/` ne correspond jamais. Le tag couvre toute la réponse, y compris `indexing` : l’avancement de l’indexation peut le changer sans modifier le `updatedAt` de la ligne du document.

Un `PATCH` réussi sur un contact, produit, document ou site renvoie `200` avec la ressource actualisée ; un `PATCH` de document porte aussi l’`ETag` de la nouvelle représentation, la valeur que le prochain `If-Match` envoie. Pour les contacts, produits, documents et projets, si toutes les valeurs enregistrées restent identiques, aucune écriture n’a lieu et `updatedAt` est conservé. Les préconditions sont vérifiées d’abord : un corps sans changement ne contourne pas un `expectedUpdatedAt` ou un `If-Match` périmé.

### Modifier contacts, produits et identité des sites

Les espaces en début et fin de chaîne sont supprimés. L’`email` d’un contact est enregistré en minuscules et sa partie avant `@` est limitée à 64 caractères. Les doublons sont détectés à la création comme à la modification :

- Même `email` ou `externalId` de contact : **409**, `CONTACT_DUPLICATE_EMAIL` ou `CONTACT_DUPLICATE_EXTERNAL_ID`.
- Même `name` de produit, sans distinction de casse, ou même `externalId` : **409**, `DUPLICATE_PRODUCT_NAME` ou `DUPLICATE_PRODUCT_EXTERNAL_ID`.

La valeur `null` efface un champ facultatif. Sur `PATCH`, une chaîne vide produit le même effet. Un champ requis vide, comme le `name` d’un produit, donne **400**, `INVALID_BODY`. À la création ou à l’import en masse, une chaîne vide — ou `null` — est traitée comme un champ omis, ce qui permet de reprendre les cellules vides d’un CSV ou un export JSON (le document OpenAPI déclare pour cette raison les champs facultatifs de la création comme nullables).

Un import de contacts doit contenir au moins une ligne : `contacts: []` donne **400**, `INVALID_BODY`. Un contact doit garder au moins un identifiant parmi `name`, `email` et `externalId`. Effacer le dernier donne **400**, `CONTACT_IDENTITY_REQUIRED`.

Lis le résultat d’un import de contacts ligne par ligne. `POST /api/v1/contacts/bulk` attend un objet contenant un seul champ, `contacts`, dont la valeur est un tableau de 1 à 500 lignes. Chaque ligne est validée séparément ; la réponse reste `201` même si certaines échouent :

| Champ de réponse | Utilisation |
| --- | --- |
| `success`, `failed` | Nombre de lignes acceptées et refusées |
| `created[]` | `id` de chaque contact créé et son `index` initial, à partir de zéro |
| `errors[]` | `index` et `contact` d’origine, `error` lisible, `errorCode` stable et `issues` par champ pour les erreurs de schéma |

Un e-mail mal formé, une clé inconnue ou une identité absente produit une erreur de ligne `INVALID_BODY`. Les doublons ont leurs propres codes. Corrige et renvoie uniquement les lignes en échec. Une structure globale invalide, un dépassement des limites de transport ou un encodage JSON invalide refuse toujours la requête entière avant le traitement des lignes.

Le filtre `source` de la liste des contacts accepte la même énumération que les écritures, notamment `manual_import`, `api_import`, `shopify`, `hubspot`, `webhook` et `custom`. Consulte l’énumération complète dans le schéma OpenAPI de l’instance. Une valeur inconnue donne `400 INVALID_QUERY`.

Pour les contacts, produits et documents, `PATCH` fusionne `metadata` selon la RFC 7396 : il conserve les clés omises, ajoute ou remplace les valeurs fournies et supprime les clés envoyées à `null`. Envoyer `metadata: null` efface l’ensemble. En revanche, `address` est remplacé entièrement. `address` et `metadata` sont limités à 64 Kio de JSON, 8 niveaux d’imbrication et 500 clés au total. Un dépassement donne **400**, `INVALID_BODY`, avec le chemin du champ concerné.

Le `price` et le `stock` d’un produit sont des nombres dans la plage des entiers sûrs, valeurs négatives comprises (une correction passée par l’API) ; le formulaire produit et l’import de fichier de l’application refusent les valeurs négatives et un stock non entier. La `currency` d’un produit est un code ISO 4217, comme `USD` ou `EUR`, accepté sans distinction de casse et enregistré en majuscules. Son `imageUrl` doit être une URL absolue HTTP ou HTTPS avec un hôte public. Un chemin relatif, un autre protocole, une adresse IP privée ou de boucle locale, un nom sans domaine ou un hôte de métadonnées cloud donne `400 INVALID_BODY`. La validation examine l’URL sans résolution DNS et ne télécharge pas l’image. Le réglage opérateur `TALE_ALLOW_PRIVATE_CRAWL_HOSTS=1` autorise les cibles de réseau privé, mais jamais les hôtes de métadonnées.

Une image importée depuis le formulaire produit suit un autre parcours. L’application accepte les fichiers PNG, JPEG, WebP, GIF ou SVG jusqu’à 5 Mio, vérifie leur contenu et renvoie une URL protégée qui reste utilisable. Les réponses de lecture REST donnent cette adresse sous forme d’URL absolue. Tu peux la renvoyer dans `imageUrl`, même sur un déploiement privé, si l’image appartient à cette organisation et que tu l’as importée ou qu’un produit existant l’utilise déjà. Une image absente ou inaccessible donne `404 FILE_NOT_FOUND` ; une URL gérée modifiée donne `400 INVALID_BODY`. L’accès aux octets exige une session autorisée dans l’application. L’URL n’est pas un lien de partage public et une clé API REST ne donne pas accès à cette route de l’application. Envoie `imageUrl: null` dans PATCH pour retirer l’image du produit. L’import du fichier passe par le formulaire de l’application ; il n’existe pas de route REST d’import d’image produit.

Le `domain` d’un site web est immuable. `PATCH /api/v1/websites/{id}` accepte la valeur déjà enregistrée, pour permettre de renvoyer une ressource lue auparavant. Toute autre valeur donne **400**, `WEBSITE_DOMAIN_IMMUTABLE`.

À la création, `POST /api/v1/websites` conserve l’hôte fourni, préfixe `www.` compris. Il considère toutefois les formes avec et sans `www.` comme le même site. Un doublon donne **409**, `WEBSITE_DUPLICATE_DOMAIN`, avec l’ID et le domaine existants dans `data.websiteId` et `data.domain`.

Une exception permet d’étendre une liste d’URL existante : si le site est déjà de type liste et que le domaine est écrit exactement de la même manière, l’ajout répond **200** avec l’ID existant. Envoyer une liste à un site configuré pour une exploration complète donne **409**, sans changer son type ni lancer d’exploration. Vérifie `kind` avant l’appel et utilise la forme du domaine indiquée dans le **409**.

Le `status` d’un site décrit le cycle de son exploration. `GET /api/v1/websites?status=` accepte `scanning` (un site enregistré commence ici), `active`, `error` ou `deleting` ; une autre valeur donne `400 INVALID_QUERY`, comme `?scanInterval=` hors de ses sept valeurs. `active` signifie qu’après l’exploration terminée, au moins une page est enregistrée, sans garantir leur actualisation à toutes. `error` signale une exploration en échec ou l’absence de pages enregistrées après les tentatives de récupération ; consulte `metadata.lastSyncError`. Un échec du modèle d’embedding commence par `The embedding model could not embed the pages [<class>]:`, où la classe est `credential`, `credit`, `unresolved`, `dimension`, `throttled` ou `upstream`, suivie de la phrase du fournisseur.

Le `lastErrorKind` d’une page distingue notamment réseau ou TLS (`network_error`, `tls_error`), cible refusée (`private_ip`), échec HTTP (`http_error`), extraction ou rendu en échec, contenu impossible à convertir en texte (`unsupported_content`) et le refus `robots_noindex` — l’origine a répondu `X-Robots-Tag: noindex` ou la page porte une balise `<meta name="robots" content="noindex">`. Une actualisation ratée peut conserver l’ancien contenu indexé. Lis donc les erreurs de pages en plus du statut du site.

`POST /api/v1/websites/{id}/search` cherche des mots-clés dans les passages enregistrés de ce site. Son `score` BM25 n’a pas de plafond et se compare uniquement au sein d’une réponse. Sans ParadeDB, l’instance recherche des sous-chaînes et renvoie `0` pour chaque résultat. Pour la similarité sémantique et `minSimilarity`, utilise `POST /api/v1/knowledge/search` avec `corpus: "web"`. Cette route cherche dans le corpus web visible, pas dans un seul site choisi.

### Enregistrer et synchroniser les bundles de skills

`PUT /api/v1/skills/{slug}` crée un skill si le slug est libre (**201**) ou le met à jour (**200**). Une synchronisation peut donc envoyer le bundle sans lecture préalable et distinguer le résultat grâce au statut HTTP. `description` et `body` sont obligatoires.

À la mise à jour, omettre `icon`, `labels`, `teams`, `visibility` ou `disableModelInvocation` conserve la valeur enregistrée. `null` efface `icon` ou `labels` ; `disableModelInvocation: false` retire ce drapeau.

Le corps Markdown est limité à 507 893 octets UTF-8. Ce plafond laisse la place au frontmatter dans la limite de 512 Kio du `SKILL.md` complet. Il s’agit d’octets, pas de caractères. Un saut de ligne final est ajouté s’il manque ; la lecture du corps renvoie alors un octet de plus.

L’opération réécrit uniquement `SKILL.md`. Elle conserve les autres fichiers et les clés de frontmatter non exposées dans la requête, comme `license`, `recommended-packages` et les clés communautaires. Pour remplacer un bundle complet, utilise l’import ZIP dans l’application.

Chaque skill expose `etag`, le SHA-256 de son `SKILL.md` entre guillemets, et `updatedAt`, la date de dernière écriture de ce fichier. Une requête qui produit exactement les mêmes octets répond **200** sans écrire le fichier ni ajouter d’historique ; les deux valeurs restent inchangées. Les préconditions sont vérifiées auparavant : même pour un contenu identique, un `If-Match` périmé donne **412**.

`GET /api/v1/skills/{slug}` renvoie ce tag dans `ETag`. Si `If-None-Match` correspond, il répond **304**. Les formes faibles `W/"…"` et les tags suffixés `"…-gzip"` sont reconnus pour cette lecture. Les réponses **200** et **304** portent `Cache-Control: private, no-cache`.

`GET /api/v1/skills` inclut un tableau `failures`, normalement vide. Chaque bundle illisible y figure avec `slug`, `path` et `message` ; un bundle défectueux ne fait pas échouer la liste entière.

Protège une modification ou une suppression avec `If-Match` et le dernier `etag` lu. Si le document a changé, la réponse est **412**, `SKILL_STALE`, avec le tag courant dans `data.etag`. Rien n’est écrit. Un `PUT` protégé sur un skill qui n’existe pas donne le même **412** avec `data.etag: null` ; un `DELETE` protégé sur un tel skill donne simplement **404**, `SKILL_NOT_FOUND` — ce qui est déjà parti est fait. Recharge le skill et fusionne les modifications avant de réessayer. Pour une écriture, un tag faible (`W/"…"`) ne correspond jamais, et le corps est validé avant la précondition.

Pour créer uniquement, envoie `If-None-Match: *`. Si le bundle existe déjà, la réponse est **412**, `SKILL_EXISTS`, sans écriture.

`GET /api/v1/skills/{slug}/files/{path}` renvoie les octets bruts d’un fichier, `SKILL.md` compris, avec son nom dans `Content-Disposition`. Reprends `path` depuis `files[].path` ; les barres obliques peuvent rester `/` ou être encodées `%2F`. La lecture est validée : l’`ETag` est celui des octets du fichier, `Last-Modified` sa date de modification, et `If-None-Match` ou `If-Modified-Since` répond **304**. Un chemin absent de la liste donne **404**, `SKILL_FILE_NOT_FOUND`. Un bundle refusé par la validation des fichiers, par exemple à cause d’un lien symbolique ou d’un fichier dépassant 4 Mio lors de la préparation, donne **422**, `SKILL_MALFORMED`.

Les segments `../` et `%2e%2e/` sont interceptés avant la route. La réponse est alors **404**, `NOT_FOUND`, avec un `X-Request-Id` propre à cette couche et sans `X-Tale-Api-Version`. Si les barres obliques sont aussi encodées (`%2e%2e%2f…`), la requête atteint la route et reçoit `SKILL_FILE_NOT_FOUND`.

Vérifie `canEdit` avant une écriture : ce champ indique si le détenteur de la clé peut modifier le bundle. Les skills fournis sont des bundles d’organisation qu’un administrateur peut remplacer.

Chaque skill indique aussi qui l’a créé et qui l’a modifié en dernier. `origin` vaut `release` pour un skill installé par une release de configuration gérée, `builtin` quand aucun créateur n’est enregistré (les skills de documents fournis à la création de l’organisation), et `member` sinon ; `owner` contient alors l’ID utilisateur du créateur. `ownerName` est son nom d’affichage tant qu’il est membre de l’organisation ; il disparaît après son départ. `updatedBy` et `updatedByName` désignent le membre dont l’enregistrement dans Tale a produit le `SKILL.md` actuel. Ils sont absents si personne n’a modifié le skill depuis sa création, ou si le fichier a changé en dehors de Tale depuis la dernière modification. Un enregistrement qui modifie le skill est consigné dans le journal d’audit de l’organisation au nom du détenteur de la clé : `skill.created`, `skill.updated`, et `skill.sharing_changed` quand `visibility` ou `teams` change (contrat 3.4.0).

Une organisation peut réserver les skills partagés avec toute l’organisation grâce à sa [politique de partage des skills](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits#skill-sharing) : aux éditeurs et au-delà, ou aux propriétaires et aux admins, ainsi qu’aux membres qui détiennent une attribution `tale:skills.publish` active. Un détenteur de clé en dehors de ce cercle reçoit **403**, `SKILL_PUBLISH_FORBIDDEN`, pour un enregistrement qui créerait un skill `visibility: org`, en étendrait un à `org` ou modifierait sur place un skill `org` ; rien n’est écrit, et le refus est consigné dans le journal d’audit sous `skill.publish_denied`. Restent possibles un enregistrement avec `visibility: team` et ses propres `teams`, un enregistrement identique octet pour octet et `DELETE`. `capabilities.skillPublish` dans `GET /api/v1/me` répond à la question avant le premier enregistrement (contrat 3.5.0).

Les visibilités autorisées sont `org` et `team` ; les IDs de `teams` doivent appartenir à l’organisation. `private` ne peut plus être attribué. Un ancien bundle qui utilise cette valeur la conserve uniquement si la mise à jour omet `visibility`.

Un slug contient au maximum 64 caractères : lettres minuscules, chiffres et tirets simples. `anthropic` et `claude` sont réservés. Un slug invalide donne **400**, `INVALID_SKILL_SLUG`, sur `PUT`, avec la règle enfreinte. Sur `GET` et `DELETE`, il est traité comme absent : **404**, `SKILL_NOT_FOUND`.

### Refléter les conversations et livrer les réponses

La synchronisation d’une conversation utilise des instantanés versionnés. Crée d’abord son contact avec `POST /api/v1/contacts` : `externalContactId` doit correspondre à l’`externalId` d’un contact de l’organisation.

Un contact introuvable donne **404**, `CONTACT_NOT_FOUND` ; plusieurs contacts correspondants donnent **409**, `CONTACT_AMBIGUOUS`. Aucun changement n’est appliqué. Une conversation déjà synchronisée ne peut pas être réaffectée à un autre contact : un `externalContactId` différent donne **409**, `CONVERSATION_CONTACT_CONFLICT`.

`POST /api/v1/conversations/sync` compare la `version` entière reçue à celle enregistrée. Il applique une version plus récente, ignore une version plus ancienne et refuse un contenu différent portant la même version avec **409**, `CONVERSATION_SNAPSHOT_CONFLICT`.

La fermeture avec `deleted: true` suit une règle distincte : elle est acceptée à la version courante ou à une version supérieure. La répéter après fermeture n’a aucun effet. La source peut ainsi fermer son miroir sans produire de nouvelle version. La conversation et ses messages restent dans la boîte de réception ; ils ne sont pas supprimés définitivement.

Pour récupérer une réponse écrite dans Tale, appelle `POST /api/v1/conversations/deliveries/claim`. Lorsque la source renvoie ensuite ce message dans un instantané, elle doit inclure `taleMessageId` avec le `messageId` natif. La livraison doit déjà avoir été confirmée sous son `externalId`, sinon la réponse est **409**, `DELIVERY_UNACKNOWLEDGED`. Sans `taleMessageId`, le message est considéré comme provenant de la source, quelle que soit la valeur d’`isCustomer`.

La source demandée doit avoir été synchronisée auparavant. Une source inconnue donne **404**, `CONVERSATION_SOURCE_NOT_FOUND`. Une source détenue uniquement par d’autres utilisateurs de service donne **403**, `INTEGRATION_NOT_OWNED`. Une faute dans son nom ne produit donc pas une file vide trompeuse.

Une livraison récupérée expose `attempts`, `leaseExpiresAt`, `lastErrorCode` et `firstClaimedAt`. Pour consulter la file sans réserver de livraison, utilise `GET /api/v1/conversations/deliveries?source=`. La liste contient les statuts `queued`, `leased`, `failed` ou `delivered`, les tentatives et les horodatages, sans jeton de réservation ni corps de message. Elle commence par la livraison due depuis le plus longtemps.

La pagination utilise `{ "deliveries": [...], "isDone": ..., "continueCursor": ... }` et le paramètre `?cursor=`. Filtre avec `?status=failed` pour trouver les livraisons en échec définitif. `POST /api/v1/conversations/deliveries/{id}/retry` en relance une, avec la même trace d’audit que **Réessayer** dans la boîte de réception. Pour tout autre état, la réponse est **409**, `DELIVERY_RETRY_UNAVAILABLE`.

Confie une conversation synchronisée à une équipe avec `POST /api/v1/conversations/assignment` : `{source, externalId, teamId}`, où `teamId` provient de `GET /api/v1/teams` et `null` retire l’équipe. Les membres de l’équipe peuvent alors ouvrir la conversation dans la boîte de réception, et chacun est notifié. Comme dans la boîte de réception, seules les clés des admins et des propriétaires peuvent assigner ; une clé d’éditeur reçoit **403**, `ROLE_FORBIDDEN`, et peut à la place acheminer sa source avec une [règle de routage](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits). Une équipe hors de l’organisation renvoie **400**, `TEAM_NOT_IN_ORG`, une synchronisation qu’aucun instantané n’a créée **404**, `CONVERSATION_NOT_FOUND`, et une appartenant à un autre utilisateur de service **403**, `INTEGRATION_NOT_OWNED`.

Prépare les pièces jointes avec `POST /api/v1/conversations/uploads` avant de les inclure dans un instantané. Aucune partie de l’instantané n’est appliquée si une pièce jointe est refusée :

- Préparation absente ou expirée, `storageId` mal formé, non délivré par cet endpoint ou provenant d’une autre organisation : **400**, `ATTACHMENT_NOT_STAGED`.
- Préparation effectuée par un autre utilisateur de service de la même organisation : **403**, `ATTACHMENT_NOT_OWNED`.
- `size` déclarée différente du nombre d’octets reçus : **400**, `ATTACHMENT_SIZE_MISMATCH`.

Les `replyConstraints` limitent les futures réponses écrites dans la boîte de réception : longueur du texte, nombre de pièces jointes, taille et extensions des fichiers. Elles sont contrôlées lors de la rédaction de la réponse et ne provoquent jamais le rejet de l’instantané lui-même.

Pour `GET .../deliveries/{id}/attachments/{index}`, une livraison qui n’a pas été récupérée sous cet ID donne `DELIVERY_NOT_FOUND`. Une pièce jointe absente, ou un index qui n’est pas un entier de 0 à 9, donne `ATTACHMENT_NOT_FOUND`.

Les fichiers préparés par `POST /api/v1/conversations/uploads` n’ont pas d’opération de suppression dédiée. Un fichier jamais lié est nettoyé lors d’un chargement ultérieur dans l’organisation, après sa fenêtre de deux heures et 24 heures de grâce. Une référence liée suit la durée de vie de son message.

Tous les corps de conversation sont stricts. Une clé inconnue, y compris dans un message ou une pièce jointe, donne **400**, `INVALID_BODY`, avec le nom de cette clé.

`GET /api/v1/conversations/sync` renvoie aussi l’`externalContactId` lié, le `contactId` de la ligne liée et `contactStatus` : `active`, `trashed` ou `missing` — ainsi que `sourceDeleted` avec le `status` de l’Inbox, pour qu’un moteur qui reprend depuis le reçu sache qu’un démontage a eu lieu : un instantané de contenu sur un miroir démonté répond **409** `CONVERSATION_CLOSED` quelle que soit la version (reflète la conversation source sous un nouvel `externalId` pour recommencer). La liaison conserve la ligne du contact initial. Supprimer ce contact l’envoie à la corbeille et libère son e-mail et son identifiant externe ; un nouveau contact portant ces identifiants ne récupère jamais l’ancien historique. Un contact dont le CRM a changé la clé (un `PATCH` de son `externalId`) garde en revanche ses conversations : un instantané qui nomme l’id courant s’applique et le reçu le suit, tandis que l’id qu’il ne porte plus répond **409** `CONVERSATION_CONTACT_CONFLICT` en nommant l’id auquel la conversation est liée. `GET /api/v1/conversations?source=` liste chaque conversation que tu as reflétée sous une source — `conversationId`, `externalId`, `externalContactId`, `contactId`, `contactStatus`, `version`, `sourceDeleted`, `status`, `subject` —, la plus récente d’abord, en page keyset sous `conversations` (la même boucle `?cursor=` que pour chaque liste), et `?contactStatus=trashed` retrouve les miroirs qu’un contact supprimé a gelés.

Un instantané de contenu plus récent destiné au contact supprimé donne `409 CONVERSATION_CONTACT_TRASHED`. Restaure le contact — avec `POST /api/v1/contacts/{id}/restore`, qui applique la règle de la création (un contact vivant qui a pris entre-temps son e-mail ou son `externalId` refuse la restauration avec le **409** de la création), ou depuis la corbeille de l’application — avant d’envoyer du contenu, ou ferme le miroir avec `deleted: true` et une version égale ou supérieure ; un miroir fermé n’est pas rouvert par la restauration, un instantané de contenu ultérieur répond donc le même 409 tant que le contact reste dans la corbeille. Les versions anciennes restent ignorées, et les répétitions de même version suivent toujours les règles ci-dessus : la suppression ne transforme pas chaque répétition en erreur.

### Créer des connaissances indexées et des documents du centre

`POST /api/v1/documents` crée un document dans la base de connaissances de l’organisation. Tu peux fournir son texte dans `content` : il reste stocké et lisible, mais n’est pas indexé. Seuls les documents associés à un fichier chargé peuvent être indexés.

Pour envoyer du texte dans le corpus de recherche depuis REST, utilise plutôt `POST /api/v1/knowledge-entries`. Cette opération crée une entrée active par sujet et son document associé à un fichier (`sourceProvider: knowledge`, contenu limité à 8 000 caractères). La réponse **201** contient `{ "id", "documentId" }`. Interroge ensuite `GET /api/v1/documents/{documentId}` pour suivre `indexing` ; aucune lecture intermédiaire de l’entrée n’est nécessaire.

Un `PATCH` d’entrée crée une nouvelle version, renvoie ses IDs et relance l’indexation sous le même `documentId`. Si `topic` et `content` sont identiques après suppression des espaces en début et fin de chaîne, aucune version n’est créée et l’ID actif est conservé. Un `PATCH` sur une ligne remplacée donne **409**, `KNOWLEDGE_ENTRY_SUPERSEDED`, avec la ligne active du sujet dans `data.activeId` (et sa remplaçante directe dans `data.supersededBy`) : modifie cette ligne-là, sans remonter la chaîne. Une entrée créée ou remplacée par cette porte porte `source: "api"` (le formulaire de l’application écrit `manual`, la capture de l’assistant `chat`), ce qui permet au tableau des entrées de connaissances de distinguer les trois. Supprimer l’entrée met son document à la corbeille.

Ces écritures nécessitent le droit de modifier les connaissances. Un Membre en lecture seule reçoit **403**, `KNOWLEDGE_ENTRY_FORBIDDEN`. Si le stockage objet n’accepte pas le contenu en 30 secondes, la réponse est **503**, `KNOWLEDGE_ENTRY_STORE_TIMEOUT`, sans écriture.

Modifie ou supprime ce document par son entrée de connaissances. Un `DELETE /api/v1/documents/{id}` direct, ou un `PATCH` de son titre ou de son contenu, donne **409**, `DOCUMENT_HAS_KNOWLEDGE_ENTRY`, avec `data.entryId`.

Pour consulter l’historique, `GET /api/v1/knowledge-entries?topic=<topic>&status=superseded` liste les versions remplacées et leur `supersededAt`. `GET /api/v1/knowledge-entries/{id}/versions` accepte l’ID de n’importe quelle version et retourne la chaîne complète, de la plus récente à la plus ancienne.

Pour relancer une indexation, appelle `POST /api/v1/documents/{id}/retry-indexing`. Les résultats permettent de distinguer les cas suivants :

- `{"status": "skipped", "reason": "content-only"}` : le document contient uniquement du texte dans `content`, sans fichier.
- `untracked-blob` : le fichier n’est pas suivi par le processus d’indexation.
- `unsupported` : échec définitif d’indexation ; consulte `indexing.errorCode`.
- `in-progress` : une indexation récente est déjà en attente ou en cours ; suis l’état du document.
- `indexing` : l’indexation est demandée, y compris si elle avait été désactivée au chargement.

Un fichier de projet utilise `POST /api/v1/projects/{id}/files/{documentId}/retry-indexing`. Cet appel retire le choix `skipRagIndexing` fait lors de la liaison. Les fichiers de projet et les autres IDs hors de la base de connaissances donnent **404**, `DOCUMENT_NOT_FOUND`, sur la route des documents.

Les deux routes de relance appliquent les mêmes contrôles que **Indexer maintenant** dans l’application, avec une limite de 10 demandes par utilisateur et par minute. Un dépassement donne **429**, `RATE_LIMITED`.

L’autre mode de création de document, avec `fileId`, exige un fichier chargé depuis l’application par le détenteur de la clé, dans l’organisation sélectionnée, et encore sans liaison. REST ne crée pas ce chargement. Un fichier déjà lié à un document, un fil ou une conversation ne peut pas être réutilisé. Un fichier absent, détenu par un autre utilisateur ou déjà lié donne **404**, `FILE_NOT_FOUND`. Cette route ne convertit pas les chargements de projet, de chat ou de conversation en documents de l’organisation.

`GET /api/v1/documents` liste les documents du Hub du plus récent au plus ancien. Pour reproduire la vue par dossier de l’application, précise le périmètre :

| Paramètre de requête `folderId` | Documents renvoyés |
| --- | --- |
| Omis | Tous les documents visibles du Hub, y compris ceux rangés dans des dossiers. |
| `root` | Uniquement les documents qui ne sont dans aucun dossier. |
| Un identifiant de dossier | Les documents directement contenus dans ce dossier. |

`GET /api/v1/documents/{id}/content` télécharge les octets avec `Content-Disposition`, `Range` et `HEAD`, comme pour un fichier de projet. Il sert aussi le texte stocké directement dans `content`, avec le `mimeType` du document. La lecture JSON `GET /api/v1/documents/{id}` inclut ce texte dans `content`, ou `null` pour un document associé à un fichier.

Le champ `contentHash` contient le SHA-256 calculé par Tale pour les octets, par exemple ceux d’une entrée de connaissances ou d’un fichier synchronisé. Il vaut `null` lorsqu’aucun hash n’a été calculé. C’est un champ de premier niveau, pas une clé de tes `metadata`.

Un `PATCH` de document sans changement, qu’il soit vide ou qu’il répète les valeurs enregistrées, ne modifie pas `updatedAt`. Il ne rend donc pas périmée la précondition `expectedUpdatedAt` d’un autre client.

Pour un document soumis au contrôle des enregistrements, modifier le contenu, le type MIME, l’extension ou le fournisseur source donne **400**, `DOCUMENT_RECORD_FROZEN`, s’il est en revue ou approuvé. S’il est en brouillon, la réponse est **400**, `DOCUMENT_RECORD_REPLACEMENT_REQUIRED` : utilise le parcours de remplacement. Une entrée de `teamIds` désignant une équipe dont le détenteur de la clé n’est pas membre donne **403**, `TEAM_ACCESS_DENIED` ; une équipe qui n’appartient pas à l’organisation donne **400**, `TEAM_NOT_IN_ORG`, et un identifiant répété est réduit à un seul.

Un document associé à un fichier expose `indexing.status` : `pending`, `queued`, `running`, `completed`, `failed`, `unsupported` ou `skipped`. `indexedAt`, `error` et `errorCode` sont présents lorsqu’ils sont disponibles. Après une création ou une relance, interroge cet état pour constater le résultat.

Les documents à la corbeille ou expirés sont absents de cette interface, y compris les fichiers supprimés avec leur projet. Si tu conserves les fichiers lors de la suppression du projet, ils sont détachés de celui-ci et restent dans la bibliothèque de connaissances. Les corps `POST` et `PATCH` sont stricts : envoyer `projectId` donne **400**. Utilise les routes du projet pour créer ses fichiers.

Branche ton client sur `indexing.errorCode`, pas sur le texte d’`error`. Le schéma OpenAPI énumère cet ensemble fermé :

| Statut et codes | Action |
| --- | --- |
| `unsupported` : `unsupported_type`, `image_no_vision`, `empty`, `not_text`, `malformed` | Remplace ou réexporte la source dans un format pris en charge. Pour `not_text`, fournis du véritable texte UTF-8. `malformed` désigne actuellement un PDF illisible ; un fichier Office corrompu peut plutôt donner `indexer_error`. La route de relance ignore ces codes définitifs, y compris sur une ancienne ligne encore marquée `failed`. |
| `failed` : `embedding_upstream`, `indexer_error`, `index_rebuilding` | Le traitement de fond réessaie. Consulte le statut avant de demander un nouvel essai. |
| `failed` : `embedding_not_configured`, `embedding_provider_refused`, `index_repair_failed` | Fais corriger la configuration du fournisseur, les autorisations ou l’état de l’index par l’opérateur, puis réessaie. `embedding_provider_refused` couvre aussi un modèle qui renvoie des vecteurs d’une autre largeur que celle indiquée dans les réglages, ainsi que des identifiants d’embedding que la plateforme ne peut pas utiliser (aucun configuré, supprimés, désactivés ou illisibles) ; enregistrer des réglages d’embedding corrigés, ou ajouter ou réparer les identifiants qu’utilise le modèle d’embedding, remet en file d’attente chaque document qui a échoué sur le modèle d’embedding. |
| `failed` : `secret_detected`, `pii_blocked` | Corrige la source ou la politique de contenu approuvée de l’organisation avant de réessayer. |
| `failed` sans `errorCode` | La plateforme a clôturé l’échec sans le classer, le plus souvent parce que l’indexation s’est arrêtée avant la fin (une tâche perdue ou un worker arrêté). N’attends pas de nouvel essai automatique : demande un `retry-indexing`. |

## Synchroniser les notifications d’un membre

`GET /api/v1/notifications/sync`, disponible depuis le contrat API 1.8.0, exporte les notifications visibles par un membre précis. Utilise cette route pour en maintenir une copie dans une autre application. La clé API doit appartenir à un Propriétaire ou un Admin de l’organisation sélectionnée, ou à un membre auquel un Admin a accordé la capacité `tale:notifications.export` (contrat API 1.14.0). Un autre rôle seul ne suffit pas, pas même Développeur.

### Déléguer l’export sans rôle Admin

Un service qui synchronise les notifications n’a pas besoin d’un compte Admin. Le rôle Admin permet aussi de gérer les membres, d’administrer l’authentification unique et SCIM, et de réinitialiser le mot de passe des membres de rang inférieur. Exécute plutôt le service sous un compte de membre ordinaire et accorde à ce membre la seule capacité que vérifie l’export. L’attribution est une entrée du registre des compétences de l’organisation : elle ne vaut que dans cette organisation, elle est journalisée, elle peut expirer et elle est révoquée automatiquement quand un Admin retire le membre ou que ton fournisseur d’identité supprime son adhésion via SCIM.

Un Propriétaire ou un Admin l’accorde dans **Paramètres > Gouvernance > Compétences** ([Compétences](https://docs.tale.dev/fr/platform/admin/governance/competences)), ou par HTTP depuis une session active. Définis `TALE_ORIGIN` avec l’origine de ton instance et `TALE_SESSION_COOKIE` avec l’en-tête Cookie de cette session. `TALE_ORG_ID` et `TALE_WORKER_USER_ID` sont les valeurs `organization.id` et `user.id` que renvoie `GET /api/v1/me` avec la clé du service :

```bash
GRANT_BODY=$(jq -n --arg user "$TALE_WORKER_USER_ID" \
  '{userId:$user,competence:"tale:notifications.export",evidence:"Notification mirror worker"}')
curl -sS --compressed -X POST "$TALE_ORIGIN/api/app/governance/competences?orgId=$TALE_ORG_ID" \
  -H "Cookie: $TALE_SESSION_COOKIE" \
  -H "Origin: $TALE_ORIGIN" \
  -H "Content-Type: application/json" \
  -d "$GRANT_BODY"
```

La réponse est **201** avec `{ "recordId": "…" }`. Ajoute `expiresAt`, un instant futur en millisecondes Unix entières jusqu’à `8640000000000000` au plus, pour que l’attribution prenne fin d’elle-même ; sans ce champ, elle n’expire pas. Un instant passé renvoie **400** `COMPETENCE_EXPIRY_IN_PAST`, et une valeur qui n’est pas un entier dans cette plage **400** `invalid body`. Tant qu’une attribution est active, l’accorder de nouveau renvoie **409** `COMPETENCE_ALREADY_GRANTED`. Tout autre nom sous `tale:` renvoie **400** `COMPETENCE_CAPABILITY_UNKNOWN`, un utilisateur extérieur à l’organisation **400** `COMPETENCE_USER_NOT_MEMBER`, et une session sans rôle Propriétaire ou Admin **403** `COMPETENCE_FORBIDDEN`. Avant la première page, vérifie avec la clé du service que `GET /api/v1/me` indique `capabilities.notificationExport: true`.

Pour retirer ce droit, trouve l’`id` de l’attribution dans `GET /api/app/governance/competences?orgId=<orgId>&userId=<userId>` avec la même session, puis envoie `POST /api/app/governance/competences/<recordId>/revoke?orgId=<orgId>`. La requête d’export suivante du service renvoie `403 ROLE_FORBIDDEN`. Une attribution révoquée reste dans la liste comme piste d’audit ; accorde de nouveau la capacité pour rétablir l’export.

### Choisir le destinataire et le flux

Définis `TALE_RECIPIENT_EMAIL` avec l’adresse e-mail vérifiée du membre concerné. Cette adresse doit correspondre à un seul membre actif de l’organisation. La route vérifie à nouveau l’appartenance et l’adresse confirmée à chaque page. Pour les notifications d’organisation, la visibilité dépend du rôle du destinataire : une clé d’Admin n’exporte pas de notifications de sécurité que cette personne ne pourrait pas voir dans Tale.

| Paramètre de requête | Règle |
| --- | --- |
| `recipientEmail` | Adresse e-mail valide obligatoire, de 320 caractères au maximum. La recherche ignore la casse. |
| `stream` | Obligatoire : `personal` pour les notifications personnelles ou `organization` pour celles de l’organisation visibles par ce membre. Parcours les deux séparément pour obtenir une copie complète. |
| `locale` | Facultatif : `en`, `de` ou `fr`. Sans valeur, la langue de l’organisation s’applique, avec repli sur les textes anglais. |
| `limit` | Valeur par défaut et maximum : 100 ; minimum : 1. Les entiers hors plage sont ramenés à la limite. |
| `cursor` | À omettre sur la première requête, puis à remplir avec le `continueCursor` précédent, inchangé. Aucun `offset` numérique n’est accepté. |

```bash
curl --fail-with-body --silent --show-error --compressed --get \
  "$TALE_URL/api/v1/notifications/sync" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --data-urlencode "recipientEmail=$TALE_RECIPIENT_EMAIL" \
  --data-urlencode 'stream=personal' \
  --data-urlencode 'locale=fr' \
  --data-urlencode 'limit=100'
```

Une requête réussie renvoie `200` avec `{recipientId, page, isDone, continueCursor}`. Un destinataire absent, désactivé, non vérifié ou ambigu produit `recipientId: null`, `page: []`, `isDone: true` et un curseur vide. Cet appel n’invite personne et ne crée aucun compte.

### Lire les lignes et terminer un parcours

| Champ d’une ligne | Signification |
| --- | --- |
| `id` | Identifiant source stable au format `<organizationId>:<stream>:<notificationId>`. Utilise-le pour retrouver et mettre à jour la copie de ce destinataire. Une notification d’organisation peut avoir le même ID pour plusieurs personnes ; conserve leurs copies séparément. |
| `version` | Empreinte SHA-256 de 64 caractères hexadécimaux, calculée sur la ligne exportée avant ajout de l’empreinte. Elle change avec le contenu ou l’état de lecture, et peut aussi changer avec les textes traduits. Ce n’est pas un numéro croissant. |
| `title`, `body` | Textes issus des catalogues de notifications Tale et de leurs paramètres, limités respectivement à 500 et 8 000 unités de code UTF-16. Conserve la même langue entre les synchronisations. |
| `path` | Destination sous `/dashboard/...` utilisée par la cloche de notifications, avec les identifiants encodés et les paramètres de requête. Résous ce chemin depuis l’origine web de Tale, pas depuis l’adresse interne de transport de l’API. La personne doit toujours disposer de l’accès et, si nécessaire, rejoindre le réseau privé. |
| `createdAt` | Date de création en millisecondes depuis l’époque Unix. |
| `read` | Indique si le destinataire a lu la notification dans Tale. |

Les notifications personnelles sont classées par numéro de séquence décroissant ; celles de l’organisation, par date de création puis ID décroissants. Les deux flux utilisent des curseurs keyset signés. Un curseur est lié à son organisation, à son destinataire et à son flux : ne le réutilise pas pour une autre personne ou pour l’autre flux.

Pour maintenir une copie cohérente :

1. Commence chaque flux sans curseur. Retrouve les lignes par `id` et compare `version` pour détecter les changements.
2. Tant que `isDone` vaut `false`, renvoie le curseur reçu. Arrête-toi à `true` ; n’envoie pas le curseur final vide.
3. Termine les deux flux avec succès avant de retirer des lignes absentes de ce parcours dans l’application destinataire. Si une page échoue, conserve la copie précédente et résous l’échec.
4. Repars de la première page lors des synchronisations suivantes pour repérer les changements de texte ou de lecture sur les anciennes notifications. Un curseur est une position de pagination, pas un point de reprise d’un flux de changements.

L’export ne marque aucune notification Tale comme lue et n’en supprime aucune. Il ne fournit pas d’opération d’accusé de réception ou de modification. Changer l’état de lecture dans l’autre application ne change pas celui de Tale.

### Résoudre un échec d’export

| Réponse | Action |
| --- | --- |
| `401 UNAUTHORIZED` | Remplacer la clé API absente, invalide ou expirée. |
| `403 ROLE_FORBIDDEN` | Utiliser une clé de Propriétaire ou d’Admin de l’organisation sélectionnée, ou faire accorder `tale:notifications.export` à l’utilisateur de la clé par un Admin ; `capabilities.notificationExport` dans `GET /api/v1/me` le confirme. Une attribution expirée ou révoquée ne permet plus l’export. L’appartenance du destinataire ne donne aucun droit d’export à l’appelant. |
| `400 INVALID_QUERY` | Corriger les champs destinataire, flux ou langue, les paramètres inconnus ou répétés, ou les paramètres `cursor` et `limit` vides. Consulter `data.issues`. |
| `400 INVALID_LIMIT` | Fournir un entier. |
| `400 INVALID_CURSOR` | Recommencer le flux concerné sans curseur. Une appartenance supprimée ou modifiée peut invalider le curseur précédent. |
| `200`, `recipientId: null` | Vérifier l’appartenance actuelle et l’e-mail confirmé. Une page vide terminée ne confirme pas l’existence d’un compte. |
| `429 RATE_LIMITED` | Respecter `Retry-After` et le [budget API partagé](https://docs.tale.dev/fr/develop/rate-limits), en conservant la copie précédente pendant l’attente. |

Les erreurs habituelles de sélection d’organisation s’appliquent aussi. Ne transforme jamais un export en échec en une liste vide considérée comme correctement synchronisée.

## Gérer les agents d’un projet

Chaque agent appartient à un projet. L’ID du projet est obligatoire dans l’URL de chaque opération ; les réponses incluent `projectId` et l’`id` de l’agent. Ce sont les mêmes agents que dans l’onglet **Agents** du projet, avec les mêmes droits d’accès.

| Opération                          | Route                                           | Réussite       |
| ---------------------------------- | ----------------------------------------------- | -------------- |
| Lister les agents                  | `GET /api/v1/projects/{id}/agents`              | `200 {agents}` |
| Créer                              | `POST /api/v1/projects/{id}/agents`             | `201 {agent}`  |
| Lire                               | `GET /api/v1/projects/{id}/agents/{agentId}`    | `200 {agent}`  |
| Enregistrer toute la configuration | `PUT /api/v1/projects/{id}/agents/{agentId}`    | `200 {agent}`  |
| Supprimer                          | `DELETE /api/v1/projects/{id}/agents/{agentId}` | `204`          |

Choisis un projet existant, un harness que `GET /api/v1/models` liste sous `harnesses` — ceux que la plateforme fait tourner avec ses propres identifiants — et un modèle qu’il peut utiliser. Cet exemple crée un agent Claude Code et relit sa configuration ; il ne lance aucune tâche.

```bash
: "${BASE:?Set BASE to your Tale origin}"
: "${TALE_API_KEY:?Set TALE_API_KEY}"
: "${ORG_SLUG:?Set ORG_SLUG}"
: "${PROJECT_ID:?Set PROJECT_ID to an existing project ID}"
: "${MODEL_ID:?Set MODEL_ID to a model served by your harness}"
AGENT_URL="$BASE/api/v1/projects/$PROJECT_ID/agents"
AGENT_BODY=$(jq -n --arg model "$MODEL_ID" \
  '{name:"Reviewer",harness:"claude-code",model:$model,skills:[],connectors:[]}')
AGENT_ID=$(curl -fsS "$AGENT_URL" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $ORG_SLUG" \
  -H 'Content-Type: application/json' -d "$AGENT_BODY" | jq -er '.agent.id')
curl -fsS "$AGENT_URL/$AGENT_ID" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $ORG_SLUG" \
  | jq '.agent | {name, harness, skills, connectors}'
```

```json
{
  "name": "Reviewer",
  "harness": "claude-code",
  "skills": [],
  "connectors": []
}
```

### Enregistrer la configuration complète d’un agent

`POST` et `PUT` exigent `name`, `harness`, `model`, `skills` et `connectors` ; un `harness` hors de l’ensemble admis répond **400**, `PROJECT_AGENT_HARNESS_INVALID`, avec l’ensemble dans `data.harnesses`. `modelProvider`, `tools`, `secrets` et `instructions` sont facultatifs.

`PUT` remplace toute la configuration d’un agent existant. Omettre le fournisseur ou les instructions les remet à `null` ; omettre les outils ou les secrets vide ces listes. Cette opération ne crée pas d’agent si l’ID n’existe pas.

Pour éviter d’écraser une modification concurrente, fournis le dernier `updatedAt` lu dans `expectedUpdatedAt`. Si l’agent a changé, la réponse est **409**, `PROJECT_AGENT_STALE`, avec son `updatedAt` courant dans `data`. Rien n’est écrit : recharge la configuration et fusionne les changements avant de réessayer.

Un agent dont `managed` vaut `true` est l’[agent standard](https://docs.tale.dev/fr/platform/projects/project-agents#standard-agent) de l’organisation : Tale l’a mis en place dans un projet sans agents propres et aligne son environnement, son modèle et ses instructions sur les réglages de l’organisation. Un `PUT` sur cet agent renvoie **409**, `PROJECT_AGENT_MANAGED`, et n’écrit rien ; `DELETE` le supprime comme tout autre agent (contrat 3.9.0).

### Valider modèles, autorisations et limites

Un projet peut contenir au maximum 50 agents. Les noms sont limités à 120 caractères et doivent être uniques dans le projet, sans distinction de casse. Chaque liste de ressources attribuées accepte 25 entrées ; les instructions sont limitées à 20 000 caractères.

Une configuration invalide ou un dépassement de limite donne **400**. Un nom déjà utilisé donne **409**, `PROJECT_AGENT_NAME_TAKEN`, comme les autres conflits de doublon sur cette interface. Retrouve l’agent existant ou choisis un autre nom avant de réessayer.

Choisis `model` dans le catalogue de l’organisation et précise `modelProvider` si plusieurs fournisseurs servent ce modèle. `tools` doit contenir uniquement des autorisations connues. Une valeur invalide donne **400** avec `PROJECT_AGENT_MODEL_INVALID`, `PROJECT_AGENT_PROVIDER_UNKNOWN` ou `PROJECT_AGENT_TOOL_UNKNOWN`. `task_start_agent` permet à l’agent de mettre au travail un autre agent du même projet sur une tâche (contrat 3.8.0).

`task_update_metadata` est une autorisation facultative pour les agents de projet (contrat 3.10.0). Elle permet de modifier la priorité et l’agent assigné à une tâche existante sans lancer d’exécution. La demande indique `taskId`, `priority` et/ou `agentId`, avec la valeur actuelle de chaque champ concerné dans `expected` ; `null` efface une valeur et les champs omis restent inchangés. Construis `expected.assignee` sous la forme `{type, id}` à partir de `assigneeType` et `assigneeId` renvoyés par `task_get`, ou utilise `null` sans assignation ; une priorité absente vaut également `null`. Une valeur périmée entraîne le refus de toute la demande. Le [guide des agents de projet](https://docs.tale.dev/fr/platform/projects/project-agents) explique la protection des exécutions actives et des revues en attente. `task_upsert_by_external_ref` continue d’utiliser `priority` uniquement lors de la création d’une tâche.

`task_review` ajoute une permission facultative pour les agents de projet dans le contrat 3.11.0. Elle décide uniquement d’une relecture native en attente attribuée à l’agent relecteur actif, pour une exécution terminée d’un autre agent du même projet. Transmets `taskId`, `expected: {approvalId, runId, evidenceRevision}` depuis le `task_get.pendingReview` actuel, `decision: "approve" | "request_changes"`, un `feedback` non vide et `evidence: {checks, pullRequests}`. Chaque vérification indique son résultat (`passed` ou `failed`) et des précisions ; une Pull Request GitHub fournie indique son URL, le `headSha` exact et l’état de ses contrôles. L’approbation exige la réussite de toutes les vérifications fournies. Les éléments GitHub sont attestés par l’agent ; Tale ne les vérifie pas auprès du service distant.

L’outil vérifie à nouveau la permission actuelle, les droits de l’exécution active qui l’appelle, le relecteur enregistré, l’exécution de réalisation et la révision des éléments locaux. Un résultat périmé exige une nouvelle lecture ; changer l’assignation actuelle ne rend pas le relecteur indépendant. L’approbation passe la tâche à `done` ; `request_changes` la passe à `todo` avec un retour, sans démarrer d’exécution, même si ce retour contient une mention. Les compétences humaines requises et les approbations de workflows restent hors de cet outil. Il n’existe aucun point d’entrée REST public pour une décision d’agent.

Depuis le contrat 3.15.0, le `task_get.agentRuns` natif contient un booléen explicite `retryPending`. Seule la dernière exécution en échec d’un agent encore présent peut avoir la valeur `true`, selon les mêmes vérifications de tentative prévue, de refus définitif et de quota restant que la carte de tâche. Laisse cette tentative se poursuivre. `false` n’autorise pas une relance et ne donne pas l’heure de réinitialisation du fournisseur ; si le champ manque sur une ancienne plateforme, cet état est inconnu. Avant toute action, relis la tâche, son responsable, ses exécutions et sa revue, puis respecte les délais du fournisseur et tout `retryAfter` renvoyé lors d’un refus de démarrage. Aucun point d’accès REST public ni texte d’erreur brut n’est ajouté.

Le contrat 3.13.0 ajoute un démarrage protégé de correction au droit natif `task_start_agent` existant : passe `{taskId, resumeFrom: {kind: "review_repair", approvalId, runId}, feedback?}` pour une décision native `request_changes` enregistrée. Le serveur détermine l’agent de réalisation, les commentaires et leur identifiant. Il vérifie atomiquement que la même réalisation terminée est toujours la dernière, que l’assignation est inchangée, que le statut est `todo`, qu’aucune revue plus récente ni décision intermédiaire de statut, d’assignation ou d’archivage n’existe et que les limites de démarrage restent respectées. Une `agentId` explicite doit correspondre à cette réalisation ; `moveToInProgress: false` est refusé. La forme `{approvalId, runId}` sans `kind` conserve son sens distinct pour une question en attente. `stale_repair` ne lance rien ; ne réessaie pas sans cette vérification.

Un démarrage réussi renvoie `started`, `runId` et `repairReceipt` avec `taskId`, `approvalId`, `sourceRunId`, `feedbackCommentId`, `implementationAgentId`, le `runId` admis, `managerAgentId`, l’`issuerRunId` d’origine et `admittedAt`. Le même agent coordinateur peut récupérer ce reçu depuis une exécution ultérieure active et autorisée avec `replayed: true`. Chaque appel revérifie le droit de déléguer et l’accès au projet ; une répétition n’a aucun autre effet. `task_get.reviewDecision` expose le dernier reçu natif validé, ou `null` en présence d’une revue en attente, humaine ou liée à un workflow plus récente, ou de métadonnées indisponibles. Il s’agit d’un historique, pas de l’état actuel de la tâche ; `null` ne prouve pas l’absence d’une décision enregistrée. Ces ajouts ne créent aucun point d’accès REST public pour la correction et ne déclenchent aucun travail par le verdict lui-même.

Le contrat 3.12.0 étend aussi les outils natifs de tâches. `task_find` accepte `reviewerAgentId` et renvoie, pour chaque tâche, `pendingReview: null` ou `{approvalId, runId, reviewer}`. Le filtre porte sur l’agent enregistré pour la relecture en attente et fait partie de l’identité de requête du curseur signé ; conserve-le lors du parcours des pages. Il ne filtre pas sur l’agent chargé de la réalisation.

Pour une relecture d’agent enregistrée avec une source exploitable, `task_get.reviewFiles` renvoie `{expected, files, page, maxStageBytes}`. Il liste jusqu’à 50 pièces jointes et livrables par page. Passe `page.continueCursor` comme `reviewFileCursor` tant que `page.isDone` vaut false. Le curseur est lié à la tâche, au relecteur, à la demande de relecture, à l’exécution source et à la révision des éléments examinés. Chaque entrée contient ses métadonnées enregistrées et `unavailableReason`, ou une raison explicite de métadonnées invalides lorsqu’aucune identité de fichier sûre n’existe. Une `runId` absente des données n’est pas déduite.

La même permission `task_review` accepte `{operation: "stage_file", taskId, expected: {approvalId, runId, evidenceRevision}, fileId}` pour copier un fichier listé et disponible de 20 Mio au plus. Aucun chemin, référence de stockage ou URL fourni par l’appelant n’est accepté. La réponse indique le `path` local choisi par le serveur et le nombre d’octets `bytes` ; l’agent doit lire le fichier avant d’attester de son contenu. L’appartenance à la tâche, la relecture enregistrée, l’exécution appelante active, les droits et la politique sont vérifiés avant le transfert, puis avant le succès. Les liens avec des documents protégés conservent leurs règles d’accès ; les fichiers indisponibles ou non pris en charge sont refusés. Une révocation ou un transfert simultané peut laisser des octets précédemment autorisés dans l’espace de travail tout en refusant le succès et une décision obsolète. Il s’agit d’une opération d’outil natif, pas d’un nouveau point d’entrée REST public pour les fichiers ou les décisions.

`secrets` contient des noms de secrets de l’organisation, jamais leurs valeurs. Un nom inconnu donne **400**, `PROJECT_AGENT_SECRET_UNKNOWN`, et figure dans `data.secrets`. Le formulaire de l’application filtre les noms inconnus ; l’API les refuse explicitement.

Seuls les Propriétaires et Admins peuvent modifier les autorisations de secrets. Un Éditeur qui enregistre la configuration complète doit conserver celles qui existent déjà.

Le droit de lire un projet permet de consulter ses agents. Les écritures exigent un projet actif et le droit de le modifier. Un projet absent ou invisible, ou l’ID d’un agent d’un autre projet, donne **404**. Si le détenteur de la clé appartient à plusieurs organisations, inclus `X-Organization-Slug` dans chaque requête.

[Agents de projet](https://docs.tale.dev/fr/platform/projects/project-agents) explique leur travail sur les tâches. Le chat direct utilise l’assistant intégré.

## Les noms d'automatisation dans les URL

Un nom d’automatisation peut contenir des `/`, par exemple `billing/dunning`. Dans chaque URL `.../automations/{name}/...`, remplace ces séparateurs par `__` pour garder le nom dans un seul segment.

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/automations/billing__dunning/versions" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG"
```

Les réponses portent toujours le vrai nom (`"name": "billing/dunning"`) ; la forme `__` n'existe que dans les URL. Les slugs de skills ne contiennent pas de `/` et n’ont pas besoin de cette transformation. Les agents de projet utilisent l’ID du projet et celui de l’agent.

### Lire la version qui sera exécutée

`GET /api/v1/automations` fournit les informations nécessaires pour choisir et lancer une automatisation :

- `latestVersion` et `deployedVersion` distinguent la dernière version enregistrée de celle utilisée en production.
- `projectIds` indique les projets où l’automatisation est installée.
- `description` décrit son rôle.
- `inputs` contient le schéma d’entrée de la version déployée ou, à défaut, de la dernière version enregistrée.
- `trigger` contient le type de déclencheur, son activation et `lastFiredAt`, `lastSkippedAt`, `lastSkipReason`. Il vaut `null` si aucun déclencheur n’est configuré. Ces données sont également disponibles dans `GET .../triggers`.

`GET /api/v1/automations/{name}` lit par défaut la dernière version enregistrée (`?version=latest` explicite ce défaut), qui peut être un brouillon. Utilise `?version=deployed` pour lire celle qu’une exécution réelle utilisera, ou un numéro pour lire une version précise. Une version absente, y compris `deployed` si rien n’est déployé, donne **404**, `AUTOMATION_VERSION_UNKNOWN`. Une automatisation inconnue donne `AUTOMATION_NOT_FOUND`.

`GET /api/v1/automations/{name}/versions` expose `deployedVersion` et marque chaque ligne avec `deployed`. Il indique aussi le résultat des tests de chaque version :

- `testsPassed: null` : les tests n’ont pas été exécutés. Une version sans tests conserve cette valeur.
- `testsPassed: true` ou `false` : résultat de la dernière exécution des tests, soit lors d’un enregistrement par `save_automation` sur MCP, soit lors de la vérification préalable au déploiement. Un refus de déploiement est également enregistré.
- `testsCheckedAt` : date de cette vérification. Elle peut être `null` pour un résultat antérieur à la version 0.5.24. Lis le verdict dans `testsPassed` et utilise la date uniquement pour en évaluer l’ancienneté.

`DELETE /api/v1/automations/{name}` exige la capacité développeur. Il supprime la définition, ses versions, ses déclencheurs et ses associations aux projets. Une exécution active bloque la suppression avec **409**, `AUTOMATION_HAS_ACTIVE_RUNS`.

Les anciennes exécutions sont conservées. `GET /api/v1/runs` continue de les lister, elles restent lisibles par ID, et `GET /api/v1/automations/{name}/runs` (comme son jumeau de projet) les renvoie toujours sous le nom utilisé à leur lancement. En revanche, lire la définition supprimée, ses versions ou ses déclencheurs donne **404**.

REST permet de consulter les automatisations, de les installer, de les exécuter et de configurer leurs déclencheurs. Pour créer, enregistrer ou déployer une définition, utilise `save_automation` et `deploy_automation` sur [MCP](https://docs.tale.dev/fr/develop/mcp-endpoint), l’éditeur visuel de l’application ou une release de configuration via `tale deploy`.

## Déclencheurs

Un déclencheur lance une automatisation selon une planification, un appel webhook ou un événement de la plateforme. Configure-le avec `PUT /api/v1/automations/{name}/triggers`. Une automatisation possède au maximum un déclencheur : `PUT` remplace celui qui existe.

```bash
curl -sS --compressed -X PUT "https://your-host.example.com/api/v1/automations/billing__dunning/triggers" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "event", "event": "contact.created" }'
# → 200 { "name": "billing/dunning", "deployed": true }
```

### Choisir le type de déclencheur

Choisis `kind` selon le mode de démarrage :

- `schedule` exige un `cron` à cinq champs et accepte un `timezone` IANA facultatif.
- `webhook` renvoie une seule fois le `token` utilisé dans l’URL. Voir [Webhooks](https://docs.tale.dev/fr/develop/webhooks).
- `event` exige le nom d’un événement émis par la plateforme.

Une configuration impossible à déclencher donne **400**, `AUTOMATION_TRIGGER_INVALID`, avec une explication : expression cron sans occurrence, comme `0 0 30 2 *`, fuseau non IANA ou événement non pris en charge.

Chaque type accepte uniquement ses propres champs : `cron` et `timezone` pour `schedule`, `event` pour `event`, `rotateToken` pour `webhook`. Un champ d’un autre type donne **400**, `INVALID_BODY`, et figure dans `data.issues`. Un webhook ne peut donc pas conserver implicitement une planification.

Pour un déclencheur d’événement, l’entrée de l’exécution est `{ "trigger": "event", "event": "<name>", "payload": <les données de l'événement> }`. Les événements disponibles sont :

| Événement                                               | Émis quand                                                                                                                                                       |
| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `contact.created`, `contact.updated`, `contact.deleted` | un contact est créé, modifié ou supprimé — par l’API, l’application ou un import                                                                                         |
| `conversation.created`                                  | une conversation s’ouvre dans la boîte de réception — un e-mail qui arrive, ou une conversation externe reflétée                                                 |
| `conversation.message_received`                         | un message arrive sur une conversation existante                                                                                                                 |
| `project.created`                                       | un projet est créé                                                                                                                                               |
| `task.created`                                          | une tâche est créée — sur un tableau, par l’API ou par un formulaire de collecte                                                                                                   |
| `task.status_changed`                                   | une personne déplace une tâche vers un autre statut (les déplacements d’un agent n’émettent rien, une automatisation ne peut donc pas se redéclencher elle-même) |
| `comment.created`                                       | un commentaire arrive sur une tâche                                                                                                                              |
| `comment.mentioned`                                     | un commentaire de tâche mentionne quelqu’un avec `@`                                                                                                             |

### Vérifier le déclencheur et le suspendre

`GET .../triggers` renvoie `triggers`, une liste contenant au maximum un élément. Les horodatages distinguent les exécutions réellement lancées des occurrences ignorées :

- `lastFiredAt` et `lastRunId` correspondent à la dernière exécution lancée. Ils restent `null` tant qu’aucune exécution n’a démarré.
- `lastSkippedAt` et `lastSkipReason` décrivent la dernière occurrence qui n’a rien lancé. Une livraison de webhook que le schéma `inputs` de la version déployée refuse est un autre cas : l’expéditeur reçoit **400** `AUTOMATION_INPUT_INVALID`, rien ne démarre et aucun de ces horodatages ne bouge — la liaison n’était pas due, un webhook dont chaque livraison est refusée se lit donc comme un webhook jamais appelé. Vérifie les livraisons côté expéditeur.

Les motifs d’occurrence ignorée sont `not_deployed` si aucune version n’est déployée, `unusable_cron` si l’expression ou le fuseau ne peut pas être interprété, `start_refused` si le schéma `inputs` déployé refuse l’entrée, et `paused_after_failures` si une planification s’est mise en pause d’elle-même après des échecs répétés (voir ci-dessous). Dans le cas `unusable_cron`, le planificateur cesse de traiter ce déclencheur jusqu’à sa modification.

Compare `lastFiredAt` à la cadence attendue. Si `lastSkippedAt` est plus récent, consulte la raison avant de relancer. Changer le type de déclencheur réinitialise ces horodatages.

`enabled: false` suspend le déclencheur en conservant sa configuration. `DELETE .../triggers` le retire et, s’il s’agit d’un webhook, révoque son URL.

Remplacer un webhook par un autre type révoque également son URL. Le `PUT` répond **200** avec `"revoked": "webhook"` à côté du nom. Configurer ensuite un nouveau webhook produit un nouveau jeton ; l’ancienne URL reste invalide.

Une planification dont les exécutions échouent sans cesse se met en pause d’elle-même. `consecutiveFailures` compte les exécutions lancées par cette liaison qui ont échoué d’affilée avec un `failureCode` que la prochaine occurrence répéterait : `node_error`, `connector_error`, `llm_output_invalid`, `auth_error`, `missing_api_key`, `credit_exhausted` ou `model_not_found`. `lastFailedAt`, `lastFailureCode` et `lastFailedRunId` décrivent le dernier de ces échecs. Une réussite remet le compteur à `0` ; tout autre échec ne compte pas et ne le remet pas à zéro. Une planification qui s’est mise en pause d’elle-même (`enabled: false` avec `lastSkipReason: "paused_after_failures"`) fait exception : elle garde le compteur qui a provoqué la pause, même si une exécution encore en cours à ce moment-là réussit ensuite, et seul un `PUT` le remet à zéro.

Quand le compteur d’une planification atteint cinq, la plateforme passe `enabled: false` et `lastSkipReason: "paused_after_failures"`, écrit une ligne d’audit `automation.trigger.paused` et prévient les Propriétaires et Admins de l’organisation. Corrige l’automatisation, puis envoie un `PUT` du déclencheur avec `enabled: true`. Chaque `PUT` remet le compteur à zéro et efface ce motif ; un `PUT` sans `enabled` réactive le déclencheur, car `enabled` vaut `true` par défaut. Les liaisons webhook et événement continuent de compter, mais ne sont jamais mises en pause (contrat 3.1.0).

La réponse `PUT` indique aussi `deployed`. Il est possible de configurer le déclencheur avant le déploiement, mais ses occurrences sont ignorées avec `not_deployed` jusqu’à ce qu’une version soit déployée. Le champ `trigger` de `GET /api/v1/automations` permet de constater cet état.

## Démarrer une exécution, puis la suivre

Le démarrage d’une exécution répond **202** avec son identité. Le travail continue ensuite, éventuellement pendant plusieurs minutes ; cette réponse ne contient pas encore son résultat.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/automations/billing__dunning/runs" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "customerId": "cus_123" } }'
# → 202 { "runId": "...", "version": 2, "name": "billing/dunning", "mode": "live" }
```

### Interpréter les états en cours et en attente

Interroge `GET /api/v1/projects/{id}/runs/{runId}?fields=status,finishedAt` tant que `status` vaut `queued`, `running` ou `waiting`. La sélection de champs évite de transférer toute l’exécution. Avec `If-None-Match`, une réponse inchangée devient une **304** sans corps ; voir [Cache](https://docs.tale.dev/fr/develop/api-reference#cache-compression-et-lectures-partielles).

Une fois l’exécution terminée, lis-la en entier pour obtenir `output`, la `trace` de chaque nœud et les `effects` produits.

`status: waiting` ne signifie pas nécessairement qu’une personne doit intervenir. Consulte `waitingFor` :

- `approval` attend une décision humaine ; `ask` attend une réponse à une question.
- `agent` attend la fin d’un tour d’agent ; `room` attend qu’un tour d’agent trouve une place de sandbox pour démarrer (depuis le contrat 3.14.0) ; `repeat` attend qu’un nœud atteigne sa condition `repeatUntil`. Ces trois états peuvent durer plusieurs minutes sans anomalie.

Pour repérer les exécutions qui nécessitent une personne, filtre donc sur `waitingFor` égal à `approval` ou `ask`. `detail` identifie le point d’attente, par exemple `approval:<approvalId>`, `agent:<nodeId>`, `room:<nodeId>` ou `repeat:<nodeId>`. Après un échec, il contient l’explication de cet échec.

`POST /api/v1/projects/{id}/runs/{runId}/cancel` arrête l’exécution à la prochaine limite entre nœuds. Il n’annule pas les effets déjà produits.

Une exécution en échec expose un `failureCode` stable en plus du message lisible dans `detail`. Les autres états renvoient `null` ; une ancienne exécution en échec peut aussi ne pas avoir de code. Les résumés omettent un code non renseigné.

Une exécution lancée par un déclencheur (`startedBy: "trigger:<id>"`) porte aussi `startedVia` — `schedule`, `webhook` ou `event` —, lu dans l’entrée de l’exécution elle-même : une liste distingue ainsi une exécution planifiée d’une livraison webhook, et une ancienne exécution garde son type même si la liaison change ensuite. Les exécutions lancées par une personne ou une clé API omettent ce champ (contrat 2.1.0).

| Origine de l’échec | Exemples et action |
| --- | --- |
| Automatisation | `node_error`, `connector_error`, `llm_output_invalid`, `approval_rejected`, `execution_limit`, `automation_deleted` : examine le nœud en échec et sa trace. Corrige les données ou la définition. Si une opération a été refusée, tiens compte du motif du refus avant de demander une nouvelle exécution. |
| Fournisseur de modèle | Par exemple `credit_exhausted` ou `rate_limited` : résous le problème du fournisseur avant un nouvel essai. |
| Exécution d’agent | Par exemple `harness_error`, `session_gone`, `deadline` ou `budget_exceeded` : examine le détail et les limites de l’agent. L’énumération complète figure dans OpenAPI. |

Le code identifie la cause sans garantir qu’un redémarrage complet soit sans effet indésirable : des nœuds précédents peuvent déjà avoir modifié un système externe. `startedAt` indique l’acceptation du démarrage, avant sa prise en charge par un worker. Aucun horodatage distinct ne marque cette prise en charge ; `finishedAt - startedAt` inclut donc la file et les autres attentes.

La réponse de `POST .../cancel` contient `cancelled` et le `status` obtenu. Une annulation effective donne `cancelled: true`, `status: "cancelled"` et remet le `detail` de l’exécution à `null`. Si elle était déjà terminée, `cancelled: false` accompagne son état final : `success`, `failed` ou `cancelled`.

### Relancer un démarrage sans créer une seconde exécution

Envoie `Idempotency-Key: <ta clé>` pour pouvoir répéter une demande après un délai dépassé ou une réponse perdue. Pendant 24 heures, la même clé et le même corps renvoient **202** avec l’exécution initiale et `"duplicate": true`, sans en créer une deuxième.

La même clé avec un corps différent donne **409**, `IDEMPOTENCY_KEY_REUSED`. Sa portée est limitée à l’automatisation et au projet de l’URL. Une demande refusée ne réserve pas la clé : tu peux la réutiliser après avoir corrigé le refus.

L’en-tête facultatif `Idempotency-Key` doit contenir de 1 à 255 caractères ASCII imprimables après suppression des espaces extérieurs. S’il est présent mais vide, trop long ou contient d’autres caractères, la réponse est `400 INVALID_HEADER` ; `data.issues` nomme l’en-tête et rien ne démarre. Pour une répétition, conserve la même valeur normalisée et le même corps. Omets l’en-tête seulement si tu ne souhaites pas cette protection contre une double exécution.

### Choisir une exécution réelle ou simulée

`mode` vaut `live` par défaut. Les exécutions réelles à entrée libre et les annulations exigent la capacité développeur. Dans un projet, une exécution exige aussi le droit de modifier ce projet et un projet actif, même en `mode: "mock"`. Sans projet, une exécution simulée exige seulement l’appartenance à l’organisation. Les simulations utilisent des réponses fictives déterministes. Le démarrage d’une exécution, réelle ou simulée, ne nécessite aucun déclencheur.

Une automatisation inconnue donne **404**. Une exécution réelle utilise uniquement la version déployée : demander une autre version enregistrée donne **409**. Pour tester cette version, précise `mode: "mock"`. Sans version déployée, le démarrage donne également **409**, sauf si une simulation choisit explicitement une version enregistrée.

Sans corps de requête, l’entrée vaut `{}`. Un JSON mal formé donne **400**, sans démarrage. Si la définition expose un schéma `inputs`, il est validé avant la création de l’exécution. Un écart donne **400**, `AUTOMATION_INPUT_INVALID`, avec les `path` et `message` des problèmes dans `data.issues`.

Le champ `input` vaut `{}` uniquement lorsqu’il est omis. `input: null` transmet réellement `null`, que le schéma peut accepter ou refuser.

### Choisir le périmètre et consulter l’historique

Le projet de l’URL fournit le contexte des outils de tâches et de documents. Une automatisation associée à des projets peut s’exécuter uniquement dans l’un d’eux. Sans association, elle peut s’exécuter dans tout projet que le détenteur de la clé peut modifier.

`POST /api/v1/projects/{id}/automations/{name}` installe l’automatisation dans le projet et limite ses exécutions à ses projets associés. Une automatisation encore sans association n’a donc pas besoin d’être installée pour être exécutée dans un projet.

Lis l’historique d’une automatisation avec `GET /api/v1/projects/{id}/automations/{name}/runs`, ou celui du projet entier avec `GET /api/v1/projects/{id}/runs`. Les réponses sont paginées sous `{ "runs": [...], "isDone": ..., "continueCursor": ... }`, de la plus récente à la plus ancienne.

Chaque résumé contient l’identité, le périmètre, le statut et les horodatages. `id` et `runId` contiennent le même identifiant ; `runId` correspond au nom du champ reçu au démarrage.

- `?status=failed` filtre les statuts. Sépare plusieurs valeurs par des virgules.
- `?include=input,output` ajoute des champs détaillés. `trace`, `effects` et `checkpoints` sont aussi disponibles.
- `?cursor=` permet de poursuivre avec `continueCursor`, jusqu’à `isDone: true`.

Avec `include`, une page contient au maximum 25 lignes et 8 Mio. Elle peut s’arrêter avant 25 lignes, avec `isDone: false`, si la suivante dépasse le budget de taille.

`GET /api/v1/runs` rassemble toutes les exécutions visibles pour le détenteur de la clé, celles de l’organisation comme celles des projets accessibles. Chaque ligne indique `projectId`.

Une automatisation sans association à un projet peut démarrer sans projet via `POST /api/v1/automations/{name}/runs`. Une automatisation associée donne **409** sur cette route. `GET /api/v1/automations/{name}/runs` et `/api/v1/runs/{runId}` exposent uniquement les exécutions sans projet. Pour lire, annuler ou supprimer une exécution de projet, utilise toujours la route de ce projet.

`DELETE /api/v1/projects/{id}/runs/{runId}`, ou `/api/v1/runs/{runId}`, exige la capacité développeur et supprime une exécution terminée, entrée et sortie comprises. Une exécution active donne **409**, `RUN_ACTIVE` : annule-la d’abord.

## Agir pour un membre : répondre à la question d’une exécution, décider la relecture d’une tâche

Une exécution en pause sur `waitingFor: "ask"` attend une personne ; une tâche en `in_review` peut attendre une personne ou un agent désigné. Ces deux points d’entrée REST relaient le geste d’une personne depuis une autre application en la nommant comme `actor` : Tale enregistre cette personne, pas la clé. Ils demandent le contrat API 1.16.0 ; le contrat 3.11.0 ajoute le refus explicite d’une approbation humaine tant que la relecture appartient à un agent.

### Répondre à la question qu’attend une exécution

`GET /api/v1/projects/{id}/runs/{runId}/ask` renvoie la question ouverte sous la forme `PendingAsk` — la phrase, un ensemble structuré `questions` facultatif, le nœud qui a posé la question et l’échéance `expiresAt` — ou `ask: null` quand personne n’est sollicité. La lecture demande le même accès que la lecture de l’exécution.

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/projects/<projectId>/runs/<runId>/ask" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "ask": { "askId": "...", "question": "...", "expiresAt": 1758210000000, "taskId": "..." } }
```

Envoie la réponse à `POST /api/v1/projects/{id}/runs/{runId}/asks/{askId}`. Tale l’enregistre, reprend l’exécution dans la même transaction et dépose la réponse sur la chronologie de la tâche comme commentaire de la personne qui a répondu. Pour un ensemble `questions`, envoie une ligne par question, comme le fait l’application : `<question> → <option choisie>; <texte saisi> (in their own words)`.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/runs/<runId>/asks/<askId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "answer": "Comptabiliser en février.", "actor": { "email": "reviewer@example.com" } }'
# → 200 { "ok": true, "askId": "...", "runId": "...", "answeredBy": "<userId>", "actorUserId": "<userId>", "taskId": "..." }
```

Une exécution de projet demande l’accès en écriture à un projet actif ; une exécution d’organisation demande l’appartenance à l’organisation. Sans `actor`, la clé répond en son propre nom et `answeredBy` vaut `api-key:<userId>`. Une question déjà traitée ou fermée donne **409** `HUMAN_ASK_NOT_PENDING`, une question expirée **409** `HUMAN_ASK_EXPIRED` — l’exécution échoue alors avec `failureCode: "ask_expired"` — et une question que cette exécution n’a pas posée **404** `HUMAN_ASK_NOT_FOUND`. Une réponse vide donne **400** `EMPTY_ANSWER`.

### Décider la relecture d’une tâche

`GET /api/v1/projects/{id}/tasks/{taskId}/review` renvoie l’état de la tâche et sa relecture en attente sous la forme `TaskReview`, sinon `review: null`. Depuis le contrat 3.11.0, `reviewer` vaut `{kind: "user", userId}`, `{kind: "agent", agentId}` ou `null`. `implementationAgentId` identifie l’agent qui a réellement produit le résultat et `evidenceRevision` la révision actuelle des éléments locaux ; ces deux champs peuvent valoir `null`. `requestedFor` reste le champ de compatibilité pour une personne et vaut `null` pour un agent ; `agentSlug` est un texte d’affichage, jamais l’identité de l’agent source. Un `POST` sur ce chemin relaie une décision humaine et exige `actor` :

Le contrat 3.12.0 ajoute `agentReviewBlockedReason` : `null`, `reviewer_unavailable`, `permission_missing`, `source_required`, `source_changed`, `self_review`, `human_policy` ou `policy_unavailable`. Le même diagnostic figure dans le champ natif `task_get.pendingReview`. Il découle des droits et de la source actuels, sans créer un nouvel état de relecture ni transférer automatiquement la responsabilité. Les soumissions sans exécution native source et les nouvelles relectures soumises à une politique d’indépendance humaine ou de compétences suivent la chaîne humaine ; les relectures déjà attribuées à un agent exigent un transfert explicite.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/tasks/<taskId>/review" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "decision": "approve", "actor": { "email": "reviewer@example.com", "userId": "<userId>" } }'
# → 200 { "task": { "id": "...", "status": "done" }, "decision": "approve", "approvalId": "...", "actorUserId": "<userId>" }
```

`approve` correspond au passage en Terminé sur le tableau : le droit du membre de modifier la tâche (en tant qu’Éditeur ou rôle supérieur, ou parce qu’il l’a créée ou qu’elle lui est attribuée) et la `review_policy` de l’organisation s’appliquent exactement comme là (**403** `REVIEW_INDEPENDENT_REVIEWER_REQUIRED` ou `REVIEW_COMPETENCE_REQUIRED` si la politique refuse la personne), la relecture est enregistrée comme approuvée par le membre et la tâche passe à `done` ; une tâche avec des sous-tâches ouvertes donne **409** `TASK_HAS_OPEN_SUBTASKS`. `request_changes` exige `comment` et `workflowSlug` : la relecture est retirée, le commentaire est déposé sur la chronologie et le workflow redémarre sur la tâche en lisant ce commentaire comme retour ; la réponse contient le `runId` à suivre, avec `started: false` si une exécution en cours a été réutilisée. Une tâche qui n’est pas en relecture donne **409** `TASK_NOT_IN_REVIEW`. Chaque décision est auditée sous `task.review_relayed`, avec le membre et la clé qui a relayé pour lui.

Un `approve` humain lit lui aussi strictement la politique actuelle. Une configuration `review_policy` invalide ou illisible renvoie **409** `TASK_REVIEW_POLICY_UNAVAILABLE`, même après un transfert explicite d’un agent à une personne ; aucune approbation ni clôture n’est enregistrée. Rétablis une configuration valide et relis la relecture. L’absence réelle de cette politique facultative reste acceptée. Ce refus n’ajoute pas de contrôle d’approbation de politique à `request_changes` ni au retrait d’une relecture.

Approuver une relecture attribuée à un agent renvoie **409**, `TASK_AGENT_REVIEW_REQUIRED`. Un Éditeur doit d’abord [transférer explicitement la relecture en attente](https://docs.tale.dev/fr/platform/projects/tasks#transfer-review) à une personne autorisée avant que ce point d’entrée accepte son approbation humaine. Ne présente pas l’agent comme `actor` et ne traite pas l’absence d’un `requestedFor` humain comme une relecture sans responsable.

### Nommer le membre pour lequel on agit

`actor.email` désigne le membre par son adresse e-mail. Tale la résout dans l’organisation selon la même règle que l’export des notifications : exactement une appartenance active dont l’adresse est vérifiée. Aucun membre correspondant donne **404** `ACTOR_NOT_FOUND`, deux membres **409** `ACTOR_AMBIGUOUS`, une adresse non vérifiée **403** `ACTOR_UNVERIFIED`, une appartenance désactivée **403** `ACTOR_DISABLED`. Chaque réponse renvoie l’`actorUserId` résolu ; fixe-le comme `actor.userId` lors des appels suivants. Une adresse passée depuis à un autre compte donne alors **409** `ACTOR_REBOUND` au lieu d’agir pour son nouveau titulaire. Un membre qui ne peut pas voir le projet – ou, sur la porte de revue, modifier sa tâche – donne **403** `ACTOR_FORBIDDEN` ; l’accès du détenteur de la clé est vérifié d’abord, ce code parle donc toujours de l’acteur.

Nommer un `actor` est un droit à part entière. Une clé de Propriétaire ou d’Admin l’a par son rôle ; tout autre titulaire de clé a besoin de la capacité `tale:rest.act-as`, attribuée et révoquée exactement comme la capacité d’export dans [Déléguer l’export sans rôle Admin](https://docs.tale.dev/fr/develop/api-reference#deleguer-lexport-sans-role-admin), avec `"competence":"tale:rest.act-as"` dans le corps de l’attribution. `GET /api/v1/me` la renvoie sous `capabilities.actAs` ; un `actor` envoyé sans ce droit donne **403** `ROLE_FORBIDDEN` avant toute recherche de membre. Ce que le geste relayé peut faire reste décidé par les propres droits du membre.

## Envoyer un message, puis suivre le tour

Le chat de projet utilise le même principe : l’envoi est accepté avec **202**, puis tu suis son résultat. Choisis un projet accessible en lecture, crée un fil, envoie un message et conserve l’ID de la réponse à suivre.

### Choisir un modèle utilisable

Commence par `GET /api/v1/models`. Chaque entrée expose `contextWindow`, `maxOutputTokens`, `capabilities` (`tools`, `vision`, `reasoning`), `tags` et, si le catalogue fournit des tarifs, `pricing`. `default: true` indique le modèle par défaut de l’organisation lorsqu’il est configuré et accessible au détenteur de la clé. Ce marqueur peut être absent.

`maxOutputTokens` est absent lorsque le catalogue ne déclare aucun plafond. La route d’envoi n’applique alors aucune limite issue du catalogue. Ton client doit accepter l’absence de ce champ dans la liste des modèles.

Reprends l’`id` dans `model`. Précise `providerSlug` si plusieurs fournisseurs proposent le même ID. La liste respecte les règles d’accès de l’organisation et inclut uniquement les modèles que REST peut appeler directement.

Une liste vide signifie qu’aucun modèle de chat n’est disponible pour le détenteur de la clé.

`capabilities` et `tags` décrivent le modèle, mais ne changent pas les entrées acceptées par cet endpoint. L’envoi REST prend uniquement du texte dans `content`, même pour un modèle doté de vision. Une URI de données envoyée dans ce champ est traitée comme du texte, sans indication particulière dans la requête ou la réponse.

L’ajout d’images par REST n’est pas disponible dans cette version. Pour qu’un modèle de vision lise une image dans ce fil, poursuis-le depuis l’application et joins l’image au message.

La présence d’un modèle dans le catalogue ne garantit pas que le compte fournisseur puisse l’utiliser. Dans Paramètres, un opérateur peut l’exclure au moyen de la liste des modèles autorisés des identifiants du fournisseur.

La paire modèle/fournisseur est validée dès l’envoi :

- Modèle inconnu : **400**, `CHAT_MODEL_UNKNOWN`.
- Modèle proposé par plusieurs fournisseurs, sans fournisseur précisé : **400**, `CHAT_MODEL_AMBIGUOUS`, avec les candidats dans `data.providers`.
- `providerSlug` inconnu : **400**, `CHAT_PROVIDER_UNKNOWN`.
- Modèle absent du fournisseur choisi : **400**, `CHAT_MODEL_NOT_ON_PROVIDER`.

La réponse **202** indique le fournisseur retenu. Le tour ne bascule pas automatiquement vers un autre fournisseur.

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/models" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# Aucun modèle disponible → 200 { "models": [] }
```

```bash
# 1. Un thread à toi
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/threads" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" -d '{}'
# → 201 { "id": "<threadId>" }

# 2. Envoyer un message — sur cette API le modèle est toujours explicite, jamais choisi pour toi
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/threads/<threadId>/messages" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Résume-moi ce trimestre.", "model": "<model-id>", "providerSlug": "<provider-slug>" }'
# → 202 { "threadId": "...", "status": "accepted", "model": "...", "providerSlug": "...", "messageId": "<assistantMessageId>", "poll": "/api/v1/projects/<projectId>/threads/<threadId>/generation" }

# 3. Interroger jusqu'à idle, puis lire
curl -sS --compressed "https://your-host.example.com/api/v1/projects/<projectId>/threads/<threadId>/generation" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "status": "queued", "messageId": "..." } … puis { "status": "streaming", "messageId": "...", "text": "Le trimestre…", "textOffset": 0, "textLength": 13, "reasoning": "", "reasoningOffset": 0, "reasoningLength": 0, "cancelRequested": false, "updatedAt": 1774... } … puis { "status": "idle", "lastMessageId": "<assistantMessageId>", "lastStatus": "complete" }

# 4. Lire la réponse par l'id que le 202 a nommé
curl -sS "https://your-host.example.com/api/v1/projects/<projectId>/threads/<threadId>/messages/<assistantMessageId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "id": "<assistantMessageId>", "role": "assistant", "status": "complete", "finishReason": "stop", "parts": [ … ], "usage": { … }, … }
```

### Suivre le message accepté

Les messages de chat acceptés partagent une file commune aux organisations et aux clés de l’instance, traitée des plus anciens aux plus récents. Le worker prend des lots de `WORKER_CONCURRENCY` tours au maximum, 5 par défaut ; le lot suivant attend la fin du précédent. Une acceptation ne signifie donc pas une exécution immédiate : ton fil peut attendre derrière d’autres clients. L’API ne donne ni position dans la file ni heure de démarrage estimée.

Conserve le `messageId` reçu dans la réponse **202** : il identifie le message d’assistant qui recevra le résultat. Le suivi de génération expose trois états :

- `queued` : le message est accepté et attend un worker. Tant qu’un worker n’a pas ouvert le tour, cette interrogation en est la seule vue : `GET .../messages` ne liste pas encore le tour (la page se lit comme complète sans lui) et `.../messages/{messageId}` peut répondre **404** pour l’id nommé par l’envoi.
- `streaming` : le modèle produit la réponse. `text` et `reasoning` contiennent les données reçues jusque-là.
- `idle` : aucun tour n’est en cours. `lastMessageId` et `lastStatus` décrivent le message d’assistant le plus récent.

Si `lastMessageId` correspond à l’ID conservé, `lastStatus` décrit le résultat de ton tour. Un ID différent ne prouve pas que ton tour n’a pas démarré : un autre tour peut avoir remplacé ce résumé. Lis directement ton message avec `GET /api/v1/projects/{id}/threads/{threadId}/messages/{messageId}`, ou consulte l’historique.

`GET .../messages?order=desc` parcourt les messages du plus récent au plus ancien. Un curseur reste lié à l’ordre choisi lors de sa création ; ne change pas de direction en le réutilisant.

Interroge le statut toutes les deux à cinq secondes. Fixe un délai par requête, par exemple 30 secondes, et une durée maximale distincte pour ta boucle. Le serveur n’impose pas de durée totale fixe au tour. Il abandonne une requête au fournisseur après 180 secondes sans activité ; chaque octet reçu, raisonnement compris, remet ce délai à zéro. Un raisonnement poussé peut donc garder le tour actif sans texte de réponse visible. Pour l’arrêter, appelle `DELETE .../generation` au lieu de simplement cesser le suivi.

Pour recevoir uniquement ce qui est arrivé depuis, envoie `?since=<textLength>` et `?reasoningSince=<reasoningLength>` à partir des longueurs précédentes. L’unité est l’unité de code UTF-16 — le `String.length` de JavaScript, un emoji comptant deux ; pas le point de code —, renvoie donc les longueurs que l’interrogation a répondues plutôt que de compter les caractères toi-même. `textOffset` et `reasoningOffset` indiquent le début de chaque fragment : la valeur que tu as envoyée, un de moins quand elle aurait coupé une paire de substitution (le fragment renvoie alors le caractère entier), ou 0 quand une étape d’outils réglée a remis le flux à zéro. Réassemble par une seule règle, `held = held.slice(0, textOffset) + text`, et aucun des trois cas n’a besoin d’un traitement à part.

Si la connexion coupe avant réception du **202**, consulte `.../generation`. Les états `queued` et `streaming` indiquent un tour actif, mais ne suffisent pas à identifier une demande dont tu as perdu l’ID. Vérifie le dernier message utilisateur et son `content`, ou rejoue la demande avec sa clé d’idempotence pour retrouver le même `messageId`.

### Relancer un envoi sans doublon

Envoie `Idempotency-Key: <ta clé>` pour retrouver le résultat d’une demande après un délai dépassé ou une réponse perdue. Une répétition avec la même clé et le même corps pendant 24 heures renvoie **202** avec la réponse initiale, le même `messageId` et `"duplicate": true`. Elle ne crée ni second tour ni consommation supplémentaire liée à un second tour.

Réutiliser la clé avec un autre corps donne **409**, `IDEMPOTENCY_KEY_REUSED`. La clé est limitée au fil et au projet de l’URL. Un envoi refusé, par exemple parce qu’un tour est déjà actif, ne la réserve pas. Tu peux la réutiliser une fois le refus corrigé.

L’en-tête facultatif `Idempotency-Key` doit contenir de 1 à 255 caractères ASCII imprimables après suppression des espaces extérieurs. S’il est présent mais vide, trop long ou contient d’autres caractères, la réponse est `400 INVALID_HEADER` ; `data.issues` nomme l’en-tête et rien ne démarre. Pour une répétition, conserve la même valeur normalisée et le même corps. Omets l’en-tête seulement si tu ne souhaites pas cette protection contre une double exécution.

### Comprendre l’assistant et les limites de tokens

Chaque tour utilise l’assistant intégré de l’espace de travail, avec ses instructions, ses règles de sécurité et ses trois outils de recherche. Il ne s’agit pas d’un appel direct au modèle sans instructions. Les demandes de livrables, comme un document ou un rapport, sont orientées vers les tâches.

Ces instructions représentent environ 3 000 tokens d’entrée par appel au modèle et sont incluses dans `usage.inputTokens`. Un tour qui utilise des outils peut effectuer jusqu’à cinq appels au modèle ; chacun compte à nouveau son prompt complet.

Le périmètre dépend de l’URL. Dans `/api/v1/projects/{id}/threads`, `rag_search` et `rag_fetch` peuvent consulter les fichiers de ce projet et les connaissances de l’organisation, mais aucun autre projet. Dans `/api/v1/threads`, ils consultent uniquement les connaissances de l’organisation. Le même fil garde ce comportement dans l’application.

L’assistant décide s’il doit chercher selon la question. Nommer un fichier, demander une information interne ou écrire « cherche dans les fichiers… » l’oriente vers une recherche. Une réponse disponible dans la conversation ou les connaissances du modèle peut ne pas nécessiter d’outil. Aucun champ de cette requête n’impose une consultation.

Deux champs facultatifs règlent le raisonnement et la sortie :

- `reasoningEffort` accepte `low`, `medium`, `high`, `extra` ou `max`, comme l’application. Il est ignoré si le modèle n’a pas `capabilities.reasoning`.
- `maxOutputTokens` limite la sortie du tour entier, cumulée sur tous les appels au modèle. Il ne peut pas dépasser le plafond publié par `GET /api/v1/models`. Sinon, l’envoi donne **400**, `INVALID_BODY`, avec la limite concernée.

Chaque appel au modèle reçoit le budget restant ; aucun nouvel appel ne démarre une fois celui-ci épuisé. Les tokens de raisonnement comptent dans ce budget et dans `usage.outputTokens`, au prix des tokens de sortie. Ils peuvent consommer toute l’enveloppe et produire un résultat facturé avec `status: complete`, `finishReason: length`, mais sans texte de réponse. Augmente le budget de sortie ou réduis `reasoningEffort` pour laisser de la place à une réponse visible.

Le mode à budget de réflexion, comme l’extended thinking d’Anthropic, impose un minimum de 2 048 tokens : 1 024 pour le raisonnement et autant pour la réponse. Un plafond inférieur est relevé à cette valeur. Les modèles dont le raisonnement utilise un niveau d’effort, comme les familles GLM et DeepSeek, n’ont pas ce minimum ; le plafond demandé s’applique exactement.

Une réponse arrêtée à la limite peut avoir `status: complete`. Lis `finishReason: length` pour la reconnaître. Quand un appel au modèle atteint cette limite, tous les appels d’outils de cette étape sont retenus, même si certains arguments sont complets. Chaque `tool-result` porte `status: invalid_args` ; son message distingue les arguments complets de ceux tronqués. Vérifie la raison d’arrêt et les résultats d’outils, même si le texte final semble complet.

Sur un message d’assistant terminé, `finishReason` peut valoir `stop`, `length`, `tool-calls`, `content-filter`, `cancelled` ou `other`. Il est absent si le fournisseur n’a transmis aucune raison.

Une réponse vide, ou une annulation avant tout texte, ne contient aucune partie textuelle. `parts` peut être vide ou ne contenir que du raisonnement et des outils. Vérifie la présence de texte avant d’afficher ou d’exporter une réponse.

Les listes, détails, messages et statuts sont limités aux fils du détenteur de la clé dans le projet. Les fils d’un autre utilisateur restent invisibles, même dans un projet partagé. Utilise `GET /api/v1/projects/{id}/threads` pour lister les tiens et `GET /api/v1/projects/{id}/threads/{threadId}` pour en lire un.

### Lire langue, état, consommation et parties du message

Les espaces en début et fin de `content` sont supprimés avant validation. Un prompt vide — rien que des blancs et des caractères de format invisibles, comme les espaces sans chasse — donne **400** sans consommer de tour (du Markdown qui ne rend rien, un bloc de code vide par exemple, reste un prompt).

`locale` accepte une balise BCP 47, comme `de` ou `en-GB`. Elle demande une langue de réponse, indépendamment de celle du prompt. Cette consigne est ajoutée aux instructions système et au message, mais le modèle peut ne pas la respecter. Aucune propriété de la réponse ne signale cet écart. Si la langue est une exigence de ton application, vérifie le texte reçu et prévois sa correction.

Les instructions obligatoires de l’organisation priment sur `locale`. Si ce champ est omis, l’assistant reçoit la consigne de répondre dans la langue du prompt.

Le message d’assistant existe dès le traitement du tour avec `status: pending` et `parts: []`. Son ID correspond à celui de `.../generation`. Il devient ensuite `complete`, `cancelled` avec la sortie partielle déjà reçue, ou `failed` avec `error` et `errorCode`.

Le champ `usage` décrit les tokens et le coût estimé :

- `reasoningTokens` est la part d’`outputTokens` consacrée au raisonnement. Le champ est absent si le fournisseur ne l’a pas communiqué ; `0` signifie qu’un zéro a été communiqué.
- `cachedInputTokens` est la part d’`inputTokens` servie depuis le cache du fournisseur.
- `costEstimateCents` est l’estimation du catalogue, en centimes de dollar américain, arrondie au millionième de centime. C’est la même estimation que dans le registre d’usage de l’organisation. Le champ est absent si le modèle n’a pas de tarif publié. Les entrées en cache utilisent le tarif d’entrée normal ; l’estimation représente donc une borne haute pour un tour bénéficiant du cache.
- `estimated: true` indique que Tale a estimé les compteurs faute de données du fournisseur, notamment après une annulation ou un échec en cours de flux. Le prompt complet, outils de l’assistant compris, est inclus.
- `stepLimitHit: true` indique que la boucle d’outils a atteint son nombre maximal d’appels au modèle.

Un tour en échec porte aussi un `usage` pour ce qu’il a consommé : ses appels au modèle terminés et, si le fournisseur avait déjà accepté la requête, l’appel qui a échoué, estimé là où le fournisseur n’a transmis aucun compteur. Un appel refusé par le fournisseur ne compte pas, qu’il ait répondu par un statut d’erreur HTTP ou signalé un refus, comme une limite de requêtes, avant toute réponse ou consommation positive déclarée. Si le premier appel est refusé, `usage` est absent.

`parts` est une liste ordonnée dont les éléments sont distingués par `type` : `text`, `reasoning`, `attachment`, `tool-call`, `tool-result` ou `approval`. Le document OpenAPI décrit chaque forme comme un schéma nommé (`TextPart`, `ReasoningPart`, `AttachmentPart`, `ToolCallPart`, `ToolResultPart`, `ApprovalPart`) derrière un discriminant `type` à mapping explicite, un client généré obtient donc une classe par type. Traite un type inconnu comme un élément opaque : de nouveaux types peuvent être ajoutés.

Affiche une partie `reasoning` séparément de la réponse. Elle peut reprendre des instructions reçues par le modèle : guide de l’assistant, règles sur les sources, instructions obligatoires de l’organisation ou instructions du projet. Ne la diffuse pas à un public qui ne doit pas connaître ces instructions.

### Respecter le périmètre et l’accès au fil

Pour un chat personnel sans projet, utilise `/api/v1/threads` et ses routes de détail, de messages et de génération. Elles ne donnent pas accès aux fils des projets. Un projet incorrect dans l’URL donne **404**.

Les deux types de chat utilisent l’assistant intégré. Ajouter `projectId`, `agentSlug` ou `agentId` au corps de création ou d’envoi donne **400**. Les lecteurs du projet, y compris les Membres, peuvent créer un fil et envoyer des messages. Un projet archivé refuse ces écritures avec **403**.

Un envoi peut aussi être refusé sans mise en file :

- Fil archivé : **409**, `CHAT_THREAD_ARCHIVED`.
- Fil de sandbox : **409**, `CHAT_THREAD_NOT_DIRECT`.
- Tour actif ou envoi encore en attente : **409**, `CHAT_TURN_IN_PROGRESS`. Le tour existant conserve son `messageId`.

Seul le dernier cas se résout en attendant `idle` avant de réessayer. Les deux autres nécessitent de choisir ou restaurer un fil adapté.

### Renommer, archiver, supprimer ou arrêter un fil

`PATCH .../threads/{threadId}` accepte `{ "archived": true }` pour archiver, `false` pour restaurer, ou `{ "title": "Q3 review" }` pour renommer. Un fil dont le tour tourne, ou dont l’envoi attend encore, refuse l’archivage avec **409** `CHAT_TURN_IN_PROGRESS`, comme la suppression — annule d’abord ; restaurer et renommer restent ouverts en plein tour. Fournis au moins l’un de ces champs. Le titre, nettoyé de ses espaces en début et fin, doit contenir de 1 à 120 caractères à la création comme au renommage. Sans titre initial, l’assistant nomme le fil après le premier message ; le résultat figure toujours dans `title`.

L’archivage renseigne `archivedAt` et conserve `updatedAt`, qui suit l’activité des messages. Pour détecter archivage et restauration, une synchronisation doit donc lire `archived` et `archivedAt`, pas uniquement `updatedAt`.

`DELETE .../threads/{threadId}` met le fil à la corbeille. Un tour actif ou encore en file bloque cette opération avec **409**, `CHAT_TURN_IN_PROGRESS`.

Pour arrêter le tour, appelle `DELETE .../threads/{threadId}/generation`. La réponse est **202**, `{ "status": "cancelling", "messageId": "..." }`. Continue le suivi jusqu’à `idle`. Le message final porte `status: cancelled` et conserve les données déjà reçues.

Un envoi encore `queued` s’annule de la même manière. Le **202** reprend le message d’assistant annoncé lors de l’envoi. Aucun appel au modèle n’a lieu et ce message devient `cancelled` avec `parts: []`.

Si rien ne tourne ni n’attend, l’annulation donne **404**, `CHAT_TURN_NOT_RUNNING`. `data.lastMessageId` et `data.lastStatus` décrivent alors le dernier message d’assistant, comme le suivi `idle`. Tu peux ainsi reconnaître une réponse déjà terminée sans requête supplémentaire.

Un projet archivé refuse la modification, la suppression et l’annulation avec **403**.

### Résoudre les erreurs de modèle et d’accès

Un message d’assistant en échec contient un `error` lisible et, lorsqu’il est disponible, un `errorCode`. Deux codes signalent un problème de compte fournisseur : `credit_exhausted` pour un solde épuisé et `model_not_entitled` pour un modèle non inclus dans le forfait.

Base le traitement automatique sur `errorCode`, pas sur la phrase ni sur le seul statut HTTP du fournisseur. `error` reprend la réponse du fournisseur précédée de ce statut ; un **429** peut ainsi correspondre à `model_not_entitled` si le refus concerne le forfait. Ces deux codes ne sont pas `rate_limited` : attendre ne suffit pas. Choisis un autre modèle ou corrige le compte.

Avant de traiter un envoi accepté, le worker vérifie à nouveau le fil et l’accès au projet. Si le fil a changé de projet ou si l’accès a été retiré pendant l’attente, il n’exécute pas le tour et n’ajoute pas d’erreur dans le nouveau contexte.

## Endpoints de modèles compatibles {#model-endpoints}

Trois routes répondent aux interfaces d’OpenAI et d’Anthropic pour les modèles de l’organisation : un SDK ou un outil de code qui parle l’une d’elles peut ainsi utiliser Tale comme fournisseur de modèles (contrat 3.7.0). Il s’agit d’un accès direct au modèle : la requête va au modèle qu’elle nomme et la réponse revient telle que le modèle l’a envoyée, sans assistant, fil ni outil de Tale entre les deux. Ces routes restent désactivées tant qu’un admin n’a pas activé **Endpoints de modèles pour les clés API**. Les propriétaires, admins et développeurs peuvent ensuite les appeler ; tout autre membre a besoin d’une attribution `tale:models.api` active. [Utiliser Tale depuis ton éditeur ou un script](https://docs.tale.dev/fr/develop/use-tale-from-your-editor#model-endpoints) explique la configuration des clients.

| Route | Sert |
| --- | --- |
| `POST /api/v1/openai/chat/completions` | OpenAI Chat Completions, en flux d’événements envoyés par le serveur (SSE) ou en réponse complète, avec outils et `tool_calls`, images et fichiers. Un flux se termine par `data: [DONE]` ; son dernier fragment, qui porte la consommation, n’arrive que si `stream_options.include_usage` le demande. |
| `GET /api/v1/openai/models` | Les identifiants des modèles que le détenteur de la clé peut appeler, en liste OpenAI : `owned_by` est le slug du fournisseur, et `created` vaut toujours `0`. |
| `POST /api/v1/anthropic/v1/messages` | Anthropic Messages, en flux ou en réponse complète, avec outils, images et documents. `anthropic-version` et `anthropic-beta` sont transmis. |

L’authentification est la même que pour toute autre opération : `Authorization: Bearer <key>` et, pour un détenteur de plusieurs appartenances, `X-Organization-Slug`. Ces routes partagent le budget de débit général et répondent avec `X-Request-Id` comme les autres. Elles ignorent les paramètres de requête, y compris le `?beta=true` d’un SDK Anthropic, et acceptent des corps jusqu’à 32 Mio. Tale lit les champs qu’il encadre et relaie le reste du corps tel quel : les règles strictes de corps et de paramètres des autres opérations ne s’appliquent pas ici.

`model` prend la forme `<providerSlug>/<modelId>` sur les deux interfaces : le slug du fournisseur, une barre oblique et l’identifiant du modèle dans le catalogue de ce fournisseur, par exemple `openrouter/anthropic/claude-sonnet-4.6`. Comme un identifiant de catalogue peut contenir des barres obliques, le fournisseur est la partie avant la première. Les réponses nomment l’identifiant envoyé par la requête. Le détenteur de la clé peut appeler les modèles de chat de l’organisation que servent des identifiants avec clé API ou variable d’environnement, restreints par les modèles autorisés de ces identifiants et par son accès aux modèles ; les modèles servis par des identifiants d’abonnement et les fournisseurs dont l’adresse est définie pour chaque identifiant, comme Azure, ne sont pas servis. `GET /api/v1/models` donne pour chacun de ces modèles sa fenêtre de contexte, ses capacités et ses prix, sous les mêmes `providerSlug` et `id`.

Chaque requête est soumise à l’accès aux modèles du détenteur de la clé, vérifiée par rapport à chaque plafond de budget qui s’applique à lui, à ses équipes, à l’organisation et à la clé, puis imputée à la personne et à la clé. Les garde-fous d’entrée de l’organisation examinent chaque texte qu’elle porte avant qu’elle soit relayée ; les réponses ne sont pas filtrées. Une personne, et chaque clé, peuvent avoir huit requêtes en cours en même temps.

### Lire un refus au format de l’interface

Chaque refus sur ces routes, y compris ceux liés à l’authentification, à l’organisation, à la limite de débit et à la taille du corps, arrive au format d’erreur de l’interface, si bien qu’un SDK du fournisseur le lit comme le sien. `code` porte le code stable de Tale. Sur les routes OpenAI :

```json
{ "error": { "message": "The model endpoints are not enabled for this organization. An admin turns them on under Settings → Governance → Models → Model access.", "type": "permission_error", "param": null, "code": "MODEL_API_DISABLED" } }
```

Sur la route Anthropic, qui ajoute l’en-tête `request-id` :

```json
{ "type": "error", "error": { "type": "permission_error", "message": "The model endpoints are not enabled for this organization. An admin turns them on under Settings → Governance → Models → Model access.", "code": "MODEL_API_DISABLED" }, "request_id": "<X-Request-Id>" }
```

| Statut | `code` | Signification |
| --- | --- | --- |
| **403** | `MODEL_API_DISABLED` | L’organisation n’a pas activé les endpoints. |
| **403** | `MODEL_API_FORBIDDEN` | Le rôle du détenteur de la clé ne peut pas les appeler, et il n’a pas d’attribution `tale:models.api` active. |
| **403** | `MODEL_API_MODEL_FORBIDDEN` | L’accès aux modèles de l’organisation bloque ce modèle pour le détenteur de la clé. |
| **404** | `MODEL_API_MODEL_UNKNOWN` | Aucun modèle que le détenteur peut appeler ne porte cet identifiant ; `GET /api/v1/openai/models` les liste. |
| **400** | `MODEL_API_VISION_UNSUPPORTED` | La requête contient des images, et le modèle ne les lit pas. |
| **400** | `MODEL_API_TOOLS_UNSUPPORTED` | La requête propose des outils, et le modèle n’en accepte pas. |
| **400** | `MODEL_API_VENDOR_TOOL_UNSUPPORTED` | La requête demande au fournisseur du modèle d’exécuter lui-même un outil : chez OpenAI, `web_search_options` ou un outil dont le type n’est ni `function` ni `custom` ; chez Anthropic, la recherche web, la récupération web, l’exécution de code, un ensemble d’outils MCP, `mcp_servers` ou `container`. |
| **400** | `MODEL_API_GUARDRAIL_BLOCKED` | Un garde-fou d’entrée a bloqué un texte de la requête ; rien n’a été envoyé au modèle. |
| **403** | `MODEL_API_GUARDRAIL_UNSUPPORTED` | La protection PII de l’organisation tokenise, ce qu’une réponse relayée ne permet pas de respecter. |
| **503** | `MODEL_API_GUARDRAIL_UNAVAILABLE` | Une étape de modération a échoué sous une politique fail-closed, ou un réglage de garde-fou est illisible. Réessaie plus tard. |
| **413** | `MODEL_API_TEXT_TOO_LARGE` | Un garde-fou est actif, et la requête porte plus de 2 Mo de texte. |
| **429** | `BUDGET_EXCEEDED` | Un plafond de budget qui s’applique au détenteur de la clé ou à la clé est atteint, ou le pire cas de la requête, son prompt et son plafond de sortie au prix du modèle, ne tient pas dans ce qui reste ; un `max_tokens` plus bas passe plus facilement. Le message nomme le plafond, `Retry-After` indique le temps restant avant la réinitialisation d’un plafond atteint, et `x-should-retry: false` indique aux SDK de ne pas réessayer. |
| **429** | `MODEL_API_CONCURRENCY_EXCEEDED` | Le détenteur de la clé, ou la clé, a déjà huit requêtes en cours. `Retry-After` demande d’attendre deux secondes. |
| **503** | `MODEL_API_UNAVAILABLE` | Tale ne peut pas servir la requête pour le moment, par exemple parce que la passerelle de modèles ne peut pas servir ce modèle. Réessaie sous peu. |
| **400**, **413**, **422**, **429**, **503**, **529** ou **502** | `MODEL_API_UPSTREAM_ERROR` | Le fournisseur du modèle a refusé la requête. Les six premiers statuts reprennent celui du fournisseur ; tout autre refus est renvoyé en **502**. |
| **400** | `INVALID_BODY` | Le corps n’est pas une requête que la route peut relayer, par exemple avec de l’audio en entrée ou en sortie, un rôle qu’elle ne relaie pas, une URL d’image qui n’est ni `data:` ni `https:`, plus de huit réponses (`n`), un fichier stocké dans le compte du fournisseur (`file_id`, une source de type `file`), un `service_tier` autre que celui par défaut ou `store: true`. Le message nomme le champ, tout comme `param` au format OpenAI. |
| **413** | `BODY_TOO_LARGE` | Le corps dépasse 32 Mio. |

## Rechercher dans les fichiers d’un projet

Utilise l’URL du projet pour limiter les résultats à ses fichiers indexés. L’accès en lecture suffit, même si le projet est archivé. Les documents de l’organisation ou des équipes, les autres projets, les sites web et les pièces jointes d’e-mails sont exclus.

Omets `corpus` ou fournis `"documents"`. Une autre valeur, ou un champ `projectId` dans le corps, donne **400**.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/knowledge/search" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "query": "Date limite de déclaration du premier trimestre", "limit": 10 }'
```

### Interpréter les scores et les erreurs de recherche

Le corps exige `query`, dont les espaces en début et fin sont supprimés avant validation. Il accepte `limit` de 1 à 50, avec 10 par défaut, et `minSimilarity` de 0 à 1.

`limit` détermine le nombre de résultats retournés. Tale recherche dans un ensemble plus large de candidats, vérifie leur accès et l’état de leur document avant de fusionner les classements, puis sélectionne les premiers résultats. Un candidat inaccessible n’occupe donc aucun rang. `limit: 1` retourne le meilleur passage accessible, sans limiter la recherche initiale à un seul candidat. À `fusedScore` égal, un passage que la branche par mots-clés a classé passe avant un passage que seule la branche vectorielle a trouvé, puis la plus petite identité de ligne — un terme exact est une preuve plus forte qu’un plus proche voisin.

`minSimilarity` filtre uniquement la recherche vectorielle avant fusion. Cette API n’applique aucun seuil par défaut : sans ce champ, elle peut renvoyer des passages dont la similarité est faible. La recherche par mots-clés n’a pas ce seuil.

L’assistant intégré utilise, lui, le seuil de l’organisation : `minSimilarity` dans [`embedding.json`](https://docs.tale.dev/fr/self-hosted/configuration/data-residency#le-modele-dembedding-de-lorganisation), avec 0,45 par défaut. Ce réglage ne s’applique pas automatiquement à cet appel REST.

Les résultats sont ordonnés par `fusedScore`. Ce score combine les classements des branches : somme de `1/(60+rang)` pour les branches ayant retenu le passage, normalisée par le meilleur score possible pour ce nombre de branches. Il sert à comparer les résultats d’une même réponse, pas à mesurer une probabilité de pertinence. Le premier résultat d’une recherche à une seule branche peut avoir 1,0 même si sa pertinence est faible. Le score n’est pas directement comparable entre deux recherches.

Les autres champs permettent d’examiner pourquoi un passage a été retenu :

- `similarity` contient la similarité cosinus de la branche vectorielle, sur l’échelle 0..1 du modèle d’embedding. Il vaut `null` si seule la recherche par mots-clés a trouvé le passage — garde ces résultats, une correspondance exacte d’identifiant ou d’expression est une preuve plus forte que n’importe quel cosinus (en code : `hits.filter(h => h.similarity === null ? h.keywordScore !== null : h.similarity >= floor)`).
- `keywordScore` contient le score BM25, non borné. Il vaut `null` si seule la recherche vectorielle a trouvé le passage.
- `matchedLegs` indique les branches correspondantes : `documents:keyword`, `documents:dense`, `web:keyword` ou `web:dense` selon le corpus recherché.
- `legs` est leur nombre : par exemple 2 si les branches par mots-clés et vectorielle ont toutes deux retenu le passage.
- `score` conserve le score propre à la première branche retenue.

Une similarité élevée ne garantit pas la pertinence. Un terme inventé ou mal orthographié peut obtenir un score inattendu. Examine le passage lui-même ; si `matchedLegs` ne contient pas `documents:keyword`, la recherche par mots-clés n’a pas confirmé ce résultat de document.

Chaque résultat inclut le passage et sa `source`. Pour un document, `source.documentId` identifie le document, tandis que `source.ref` contient la référence du fichier utilisée par l’index :

- Si `source.projectId` vaut `null`, lis le document avec `GET /api/v1/documents/{id}`.
- Pour un fichier de projet, utilise les routes du projet, comme `GET /api/v1/projects/{projectId}/files/{documentId}/content` ou `DELETE .../files/{documentId}`. La route `/api/v1/documents/{id}` répond **404** pour ce fichier.

`diagnostics.cached` et `diagnostics.reranked` valent toujours `false` : Tale ne fournit ni cache sémantique ni reclassement des résultats, et ces deux champs restent présents pour la compatibilité. `diagnostics.legs` nomme chaque branche qui a tourné avec les candidats admis qu’elle a apportés — `0` quand elle a tourné sans que rien survive (`documents:dense: 0` est une branche vectorielle qui n’a rien trouvé dans le périmètre, jamais une branche absente) —, et `diagnostics.dense` ne vaut `false` que quand le corpus n’a pas pu servir la branche vectorielle du tout, comme `diagnostics.bm25` pour l’index par mots-clés. Les passages ne portent aucun caractère de contrôle hors tabulation, saut de ligne et retour chariot, et un passage répété au sein d’un même document — un export d’une seule ligne, un rapport issu d’un gabarit — est indexé une fois, par sa première occurrence, si bien qu’un fichier plein de doublons n’encombre pas la branche vectorielle et ne classe pas ses copies une par une.

Les erreurs d’embedding demandent des traitements distincts :

- **409**, `EMBEDDING_NOT_CONFIGURED` : aucun modèle d’embedding n’est configuré.
- **409**, `EMBEDDING_CREDIT_EXHAUSTED` : le fournisseur refuse pour une raison de compte, comme un solde épuisé, un plafond de dépenses ou un forfait sans accès au modèle.
- **409**, `EMBEDDING_CREDENTIAL_REJECTED` : le fournisseur rejette la clé ou son accès au modèle. Le même code répond quand la plateforme n’a aucun identifiant utilisable à envoyer : le fournisseur n’a pas d’identifiants par défaut, ou ceux que nomment les réglages d’embedding ont été supprimés, désactivés ou sont illisibles ; `error` en donne la raison.
- **503**, `EMBEDDING_UPSTREAM_ERROR` : autre panne du fournisseur, avec `Retry-After`. Réessaie en espaçant progressivement les tentatives.

Les refus liés au compte ou aux identifiants ne sont pas des limites de débit. Ils nécessitent une correction par un administrateur, pas une simple attente.

Pour rechercher dans les documents visibles de l’organisation et des équipes hors projet, ou dans les sites web enregistrés, utilise `POST /api/v1/knowledge/search`. Son `corpus` accepte `"documents"`, `"web"` ou `"all"`, qui est la valeur par défaut. Cette route exclut les fichiers de projet et les pièces jointes d’e-mails.

Dans les deux cas, la recherche de documents porte uniquement sur ceux associés à un fichier. Un texte stocké directement dans `content` n’entre pas dans l’index.

## Refléter un système externe dans un projet

Utilise les routes Projets pour synchroniser automatiquement un système externe, comme un CRM ou un logiciel de gestion de cabinet, avec Tale. Ton processus peut retrouver ou créer le projet d’un client, préparer ses dossiers, importer des fichiers, puis vérifier leur présence.

Les appels utilisent les droits de la personne qui a créé la clé. Un projet auquel elle n’a pas accès renvoie la même réponse qu’un projet inexistant. Pour écrire par ces routes, il faut le rôle Rédacteur ou supérieur et l’accès en édition au projet. Le rôle Membre permet uniquement la lecture.

Les routes Projets et Tâches exigent une organisation explicite lorsque la personne associée à la clé appartient à plusieurs organisations. Envoie alors `X-Organization-Slug` à chaque appel ; sans cet en-tête, la réponse est **400**.

Un compte dédié à l’intégration, membre d’une seule organisation, évite cette ambiguïté. Les exemples conservent néanmoins l’en-tête : lorsqu’il est présent, Tale vérifie toujours l’appartenance à l’organisation indiquée.

### Trouver ou créer le projet

Un projet porte son audience dans `teamIds` : les équipes qui peuvent le voir ; une liste vide désigne toute l’organisation. Lis les identifiants dans `GET /api/v1/teams` (chaque équipe avec son nom, et `member: true` sur celles dont le détenteur de la clé fait partie — sans le rôle d’administrateur de l’organisation, il ne peut nommer que celles-là), envoie-les avec `POST /api/v1/projects` ou remplace tout l’ensemble avec `PATCH /api/v1/projects/{id} { "teamIds": [...] }` (un verbe d’administrateur). Un identifiant répété est réduit à un seul, réaffirmer l’audience que le projet porte déjà ne change rien et laisse `updatedAt` intact, et un projet archivé refuse la modification comme toute autre écriture (**403**, `PROJECT_ARCHIVED`), sauf si le même corps le restaure.

`externalItemId` contient l’identifiant du projet dans ton système externe, par exemple celui de la fiche CRM. Tale traite cette chaîne comme une valeur opaque, unique dans l’organisation.

Avant de stocker ou comparer la valeur, Tale retire les espaces de début et de fin et applique la normalisation Unicode NFC. Un identifiant transmis en NFD par macOS retrouve donc celui enregistré en NFC depuis un CSV. Un saut de ligne final provenant d’une variable shell ne crée pas de doublon.

Si d’anciens projets avaient des identifiants différents uniquement par leur normalisation Unicode, la migration a conservé l’identifiant du projet portant la forme canonique et effacé celui des doublons. Pour réattribuer un identifiant à l’un de ces projets, utilise `PATCH /api/v1/projects/{id}`.

Commence par rechercher l’identifiant externe. La réponse contient au maximum un projet. Un projet inaccessible à la personne associée à la clé n’apparaît pas dans les résultats :

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/projects?externalItemId=crm-4711" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "projects": [] } — ou [ { "id": "...", "name": "ACME Ltd", "externalItemId": "crm-4711" } ]
```

Un projet archivé possède une valeur `archivedAt`. Prévois le traitement de cet état dans ton intégration avant de poursuivre avec une écriture.

Sans `externalItemId`, la route liste les projets accessibles, du plus récent au plus ancien. La réponse paginée contient `{projects, isDone, continueCursor}`. Tant que `isDone` vaut `false`, transmets `continueCursor` dans `?cursor=` pour obtenir la page suivante. La pagination repose sur les derniers éléments lus, sans décalage numérique.

L’ancien champ `cursor`, déprécié depuis la version 1.5, contient le même jeton lorsqu’une autre page existe. Lis désormais `continueCursor`. Une recherche par identifiant externe renvoie directement `isDone: true` et un curseur vide.

Les projets archivés sont exclus par défaut. Utilise `?archived=include` pour les inclure, ou `?archived=only` pour ne lire qu’eux. Chaque projet fournit `createdAt` et `updatedAt` pour faciliter le rapprochement avec ton système :

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/projects?limit=50" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "projects": [ { "id": "...", "name": "ACME Ltd", "externalItemId": "crm-4711", "createdAt": 1774..., "updatedAt": 1774... } ], "isDone": true, "continueCursor": "" }
```

Si aucun projet ne correspond et que le compte dispose des accès attendus, crée le projet :

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ACME Ltd", "externalItemId": "crm-4711" }'
# → 201 { "project": { "id": "...", "name": "ACME Ltd", "key": "ACME", "externalItemId": "crm-4711" } }
```

`key`, le préfixe des identifiants de tâches, et `description` sont facultatifs. Sans `key`, Tale essaie de former le préfixe à partir du nom.

Créer deux projets avec le même `externalItemId` normalisé renvoie **409**. La même valeur reste autorisée dans une autre organisation. Un identifiant devenu vide après retrait des espaces renvoie **400**, `INVALID_BODY`.

Un `key` explicite doit contenir de 2 à 6 lettres ou chiffres et commencer par une lettre. Tale le convertit en majuscules. Une valeur invalide renvoie **400** ; elle n’est pas tronquée.

Si le nom ne permet pas de former un préfixe valide, le projet est créé sans `key`. Si un préfixe dérivé est déjà pris, Tale en génère un autre jusqu’à en trouver un libre. Un préfixe explicite déjà utilisé renvoie **409**, `PROJECT_KEY_TAKEN` : choisis-en un autre. Un `externalItemId` déjà utilisé renvoie **409**, `PROJECT_DUPLICATE_EXTERNAL_ID`.

### Créer les dossiers

Créer un dossier retrouve d’abord un dossier de même nom sous le même parent. La comparaison ignore la casse : `inbox` et `INBOX` désignent donc le même dossier. S’il existe, Tale renvoie son nom enregistré avec **200** et `created: false`. Sinon, la réponse est **201** et `created: true`.

Tu peux répéter cette étape après une interruption. Deux processus qui demandent simultanément le même dossier obtiennent également un seul dossier.

Le champ `name` contient un nom de dossier, jamais un chemin. Les séparateurs `/` et `\`, les caractères de contrôle et les valeurs `.` ou `..` provoquent **400**, `FOLDER_NAME_INVALID`. Le message décrit la règle enfreinte et `data.issues` désigne le champ `name`.

Comme pour les fichiers, Tale retire les espaces de début et de fin et normalise le nom en NFC. `parentId` doit désigner un dossier du même projet ; omets-le pour créer un dossier racine. Une chaîne vide renvoie **400**, `INVALID_BODY`. Aucun nom de dossier n’a de rôle réservé dans la plateforme :

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/folders" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "2026-Q1" }'
# → 201 { "folder": { "id": "<folderId>", "name": "2026-Q1" }, "created": true }
```

Utilise `parentId` pour créer un sous-dossier. Le nom, après retrait des espaces, ne peut pas dépasser 128 caractères. Un chemin comme `a/b`, `.` ou `..` renvoie **400**, `FOLDER_NAME_INVALID`. Un dossier situé au niveau 20 ne peut plus recevoir de sous-dossier : Tale renvoie **400**, `FOLDER_DEPTH_EXCEEDED`.

Parcours l’arborescence un niveau à la fois :

- `GET .../folders` liste les dossiers racine.
- `GET .../folders?parentId=<folderId>` liste les enfants du dossier indiqué.
- `GET .../folders/{folderId}` lit un dossier précis, notamment à partir du `folderId` renvoyé par `GET .../files`.

Chaque dossier possède un `parentId`, égal à `null` à la racine. Remonte cette chaîne pour reconstituer le chemin, même si ton intégration n’a pas créé l’arborescence. Un `parentId` ou `folderId` qui ne correspond pas à un dossier de ce projet renvoie **404**, `FOLDER_NOT_FOUND`.

### Charger un fichier en deux étapes

Deux appels REST encadrent un envoi direct au stockage objet : préparer le transfert, envoyer les octets, puis les rattacher au projet. L’exemple shell demande `jq`, un dossier de projet existant et un fichier local dont l’extension et le type MIME sont autorisés. N’exécute la commande suivante qu’après la réussite de la précédente.

```bash
: "${TALE_URL:?Set TALE_URL to your Tale origin}"
: "${TALE_API_KEY:?Set TALE_API_KEY}"
: "${TALE_ORG_SLUG:?Set TALE_ORG_SLUG}"
: "${TALE_PROJECT_ID:?Set TALE_PROJECT_ID}"
: "${TALE_FOLDER_ID:?Set TALE_FOLDER_ID to a folder in this project}"
: "${FILE_PATH:?Set FILE_PATH to an existing local file}"
: "${FILE_MIME:?Set FILE_MIME, for example application/pdf}"

FILE_NAME=$(basename "$FILE_PATH")
FILE_SIZE=$(wc -c < "$FILE_PATH" | tr -d ' ')
UPLOAD_BODY=$(jq -n --arg name "$FILE_NAME" --arg type "$FILE_MIME" \
  --argjson size "$FILE_SIZE" '{fileName:$name,contentType:$type,size:$size}')
UPLOAD_JSON=$(curl --fail-with-body --silent --show-error \
  "$TALE_URL/api/v1/projects/$TALE_PROJECT_ID/uploads" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --header 'Content-Type: application/json' --data "$UPLOAD_BODY")
UPLOAD_ID=$(printf '%s' "$UPLOAD_JSON" | jq -er '.uploadId')
UPLOAD_URL=$(printf '%s' "$UPLOAD_JSON" | jq -er '.url')
FILE_REF=$(printf '%s' "$UPLOAD_JSON" | jq -er '.s3Ref')
printf '%s' "$UPLOAD_JSON" | jq '{uploadId,method,expiresAt,maxBytes}'
```


#### Envoyer les octets avant de lier le fichier

L’URL `url` autorise un `PUT` direct vers le stockage objet. Envoie les octets avec cette méthode, sans en-tête `Authorization` : l’URL est déjà signée et le stockage refuse une double authentification.

Si tu as déclaré `contentType` lors de la préparation, le `Content-Type` du `PUT` doit être strictement identique. Cette valeur fait partie de la signature. Si tu as omis `contentType`, l’en-tête n’est pas imposé par la signature. Après le transfert, utilise la `s3Ref` reçue comme `fileId` lors du rattachement.

Fournis `fileName` dès la préparation, par exemple `"fileName": "ledger-2026-q1.pdf"`. Tale vérifie le nom et l’extension avant de signer l’URL. Un format refusé par la plateforme ou la politique d’import de l’organisation renvoie **400**, `UPLOAD_POLICY_REJECTED` ou `UNSUPPORTED_FILE_TYPE`.

Un nom sans extension est également refusé, quelle que soit la valeur de `contentType`. Tu peux ainsi corriger le problème avant de transférer les octets.

La préparation renvoie aussi `maxBytes`, la taille maximale autorisée pour le type déclaré. Le plafond de la plateforme est de 100 Mio, soit 104 857 600 octets ; une limite d’organisation plus basse s’applique en priorité.

Le champ facultatif `size` permet d’annoncer la taille prévue. Une taille supérieure au plafond de la plateforme renvoie **400**, `FILE_TOO_LARGE`. Le dépassement de la limite d’organisation ou de ton quota total renvoie **400**, `UPLOAD_POLICY_REJECTED`, avec la limite dans `data.limitBytes`.

Déclarer `size` évite un transfert inutile lorsque le fichier est trop volumineux. Ce contrôle ne remplace pas celui du rattachement : Tale vérifie alors la taille des octets réellement reçus selon les mêmes plafonds. La taille annoncée n’a pas à correspondre exactement à la taille reçue ; la sous-estimer ne permet pas de contourner les limites.

Envoie les octets à l’URL reçue. N’y ajoute pas la clé API Tale : la signature authentifie déjà la requête au stockage objet. Attends la réussite de l’envoi avant le rattachement.

```bash
curl --fail-with-body --silent --show-error --request PUT "$UPLOAD_URL" \
  --header "Content-Type: $FILE_MIME" \
  --upload-file "$FILE_PATH"
```

```bash
BIND_BODY=$(jq -n --arg upload "$UPLOAD_ID" --arg ref "$FILE_REF" \
  --arg folder "$TALE_FOLDER_ID" --arg name "$FILE_NAME" \
  '{uploadId:$upload,fileId:$ref,folderId:$folder,fileName:$name}')
curl --fail-with-body --silent --show-error \
  "$TALE_URL/api/v1/projects/$TALE_PROJECT_ID/files" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --header 'Content-Type: application/json' --data "$BIND_BODY"
```

Le rattachement renvoie `201 {file}` avec l’ID du nouveau document. Conserve `file.id` pour lire, télécharger, indexer ou supprimer le fichier ; il est distinct de `uploadId` et de `s3Ref`.

#### Gérer expiration, formats et envois abandonnés

L’`uploadId` est utilisable une seule fois. Il expire après 30 minutes, en même temps que l’URL présignée : `expiresAt` donne leur échéance commune. Après expiration, prépare un nouveau transfert.

Une interruption n’impose pas à elle seule de changer d’`uploadId`. Tant qu’il reste valide et que le rattachement n’a pas réussi, un transfert manquant peut être envoyé puis rattaché avec le même identifiant, comme décrit pour `BLOB_NOT_FOUND` ci-dessous.

`fileName` doit être un simple nom de fichier. Tale retire les espaces de début et de fin et le normalise en NFC. Un séparateur de chemin ou un caractère de contrôle provoque **400**.

Le nom doit se terminer par une extension autorisée. `CON` et `attachment-4711`, par exemple, provoquent `UNSUPPORTED_FILE_TYPE` à la préparation comme au rattachement. Déclarer `contentType` ne remplace jamais l’extension.

Tale vérifie de nouveau la politique d’import au rattachement. Un fichier trop volumineux ou d’un type interdit renvoie **400** avec un code de raison.

La plateforme accepte les extensions `pdf`, `doc`, `docx`, `odt`, `ppt`, `pptx`, `xls`, `xlsx`, `csv`, `txt`, `md`, `json`, `yaml`, `yml`, `py`, `jpg`, `jpeg`, `png`, `gif`, `webp` et `ac2` pour les fichiers comptables Banana. La politique de l’organisation peut restreindre cette liste. Le message `UNSUPPORTED_FILE_TYPE` énumère les formats autorisés dans l’ordre alphabétique.

Si les octets ne sont pas arrivés à l’URL présignée, le rattachement renvoie **404**, `BLOB_NOT_FOUND`. La réservation du rattachement est annulée, sans consommer l’identifiant : effectue le `PUT`, puis réessaie le rattachement avec le même `uploadId` encore valide.

Sans stockage objet configuré, la préparation et le rattachement renvoient **503**, `OBJECT_STORE_UNCONFIGURED`.

Des octets transférés mais jamais rattachés peuvent rester après un refus, une interruption ou l’expiration du transfert. Tale prend en charge leur nettoyage : 24 heures après l’expiration de l’autorisation de 30 minutes, une prochaine préparation dans l’organisation supprime un lot d’objets abandonnés et leurs autorisations associées. Ton intégration n’a pas à les supprimer elle-même.

Jusqu’à ce nettoyage, les objets restent dans le stockage. Sans rattachement, ils ne sont pas des fichiers du projet, ne comptent pas dans les quotas et n’apparaissent pas dans les listes.

#### Choisir d’indexer le fichier

Les fichiers rattachés par ces routes appartiennent au projet. Ils ne sont pas ajoutés à la bibliothèque de connaissances de l’organisation et n’apparaissent pas dans `/api/v1/documents`.

Par défaut, le rattachement utilise `skipRagIndexing: true` et ne lance pas l’indexation. Envoie `skipRagIndexing: false` pour indexer le fichier dès son rattachement.

Un fichier non indexé reste visible dans la liste du chat de projet et porte le statut **Non indexé** dans l’onglet Connaissances. La recherche ne le retrouve pas avant son indexation.

Pour l’indexer ensuite, utilise **Indexer maintenant** sur sa ligne ou `POST /api/v1/projects/{id}/files/{documentId}/retry-indexing`. Cette route utilise le même traitement et le même plafond de 10 demandes par personne et par minute que la relance d’un document de la bibliothèque. Elle renvoie `{"status": "indexing"}` quand elle lève l’exclusion de l’indexation, ou `skipped` avec un `reason`.

L’assistant peut néanmoins lire à la demande un fichier texte brut jusqu’à 4 Mio : `rag_fetch` avec son identifiant renvoie les octets comme texte, même sans indexation.

Le `mimeType` enregistré est déterminé par l’extension du fichier et devient le `Content-Type` du téléchargement. Le type multimédia d’un transfert multipart ou une indication d’upload ne remplace pas cette règle.

### Vérifier ce qui est arrivé

Le paramètre `folderId` détermine les fichiers renvoyés : omets-le pour obtenir tous les fichiers du projet, utilise `folderId=root` pour ceux qui sont à la racine, ou indique l’identifiant d’un dossier pour obtenir son contenu. Un dossier qui n’appartient pas au projet renvoie **404**, `FOLDER_NOT_FOUND`.

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/projects/<projectId>/files?folderId=<folderId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "files": [ { "id": "...", "fileName": "ledger-2026-q1.pdf", "folderId": "<folderId>", "mimeType": "application/pdf", "size": 48213, "indexing": { "status": "skipped" }, "createdAt": 1774... } ], "isDone": true, "continueCursor": "" }
```

Chaque fichier fournit sa taille réelle dans `size` et son état `indexing`, avec les mêmes statuts que `GET /api/v1/documents`. Un rattachement conservant `skipRagIndexing: true` produit le statut `skipped`.

Pour rendre le fichier recherchable, appelle `POST .../files/{documentId}/retry-indexing`, puis consulte son état dans cette liste jusqu’à `completed`.

La liste renvoie `{files, isDone, continueCursor}`. Tant que `isDone` vaut `false`, transmets `continueCursor` tel quel dans `?cursor=`. Ce jeton signé est opaque. `?limit=` fixe la taille de la page, avec un maximum de 100.

Lorsqu’une autre page existe, la réponse inclut aussi l’ancien champ `cursor`, déprécié depuis la version 1.5. Il contient le même jeton ; utilise `continueCursor` dans les nouveaux clients.

Pour surveiller un seul fichier, utilise `GET /api/v1/projects/{id}/files/{documentId}`. La réponse `{file}` contient `id`, `fileName`, `folderId`, `mimeType`, `createdAt` et `size` en octets (`null` si inconnue), ainsi que l’état d’indexation lorsqu’il existe. Renvoie l’`ETag` dans `If-None-Match` pour obtenir `304` tant que rien ne change. Après `POST .../retry-indexing`, suis cette ligne jusqu’à la fin de l’indexation, sans reparcourir la liste entière. Un enregistrement absent, supprimé, hors du projet ou sans fichier donne le même `404 FILE_NOT_FOUND`.

```bash
curl --fail-with-body --compressed "$TALE_URL/api/v1/projects/<projectId>/files/<documentId>" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG"
```

### Supprimer ce dont tu n’as plus besoin

`DELETE .../files/{documentId}` supprime définitivement le fichier : son document, ses passages dans le corpus de recherche et son objet stocké. La réponse est **204** si la suppression aboutit, sinon une erreur explique le refus :

```bash
curl -sS --compressed -X DELETE "https://your-host.example.com/api/v1/projects/<projectId>/files/<documentId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 204
```

`DELETE .../folders/{folderId}` supprime tout le sous-arbre. Tale purge d’abord les fichiers du dossier et de ses sous-dossiers ainsi que leurs passages de recherche, puis retire les dossiers. Les fichiers supprimés ne sont plus retrouvés par la recherche du projet.

Si le sous-arbre contient un document maîtrisé protégé ou des données sous conservation légale, toute la suppression est refusée avec **409**, avant le retrait du moindre élément. Si le stockage objet ne peut pas terminer la purge, la réponse est **503**, `PURGE_INCOMPLETE`, sans retrait des enregistrements ; réessaie après résolution du problème.

Les suppressions de fichier et de dossier exigent l’accès en édition à un projet actif. Un élément absent, déjà supprimé ou rattaché à un autre projet renvoie **404**, avec `FILE_NOT_FOUND` ou `FOLDER_NOT_FOUND`.

#### Archiver, renommer ou supprimer le projet

L’archivage, la restauration et la suppression du projet sont réservés aux administrateurs de l’organisation. Les autres rôles reçoivent **403**, `ROLE_FORBIDDEN`.

`PATCH /api/v1/projects/{id}` avec `{ "archived": true }` archive le projet. Il reste lisible, mais ses écritures sont refusées avec **403**, `PROJECT_ARCHIVED`, et son `externalItemId` reste réservé. Envoie `{ "archived": false }` pour le restaurer.

Pour actualiser les informations du projet, le même `PATCH` accepte `name`, `description` et `externalItemId`. Ces modifications demandent un rôle d’édition et l’accès en édition à un projet actif. Chaque champ est facultatif, mais il faut en envoyer au moins un.

- `name` est nettoyé de ses espaces de début et de fin et ne peut pas être vide.
- `description: null` efface la description.
- `externalItemId` est nettoyé et normalisé en NFC. `null` libère l’identifiant. Un identifiant déjà utilisé par un autre projet provoque **409**, `PROJECT_DUPLICATE_EXTERNAL_ID`, avec la valeur concernée dans `data`.

Lorsqu’une requête combine restauration et renommage, Tale restaure d’abord le projet. Lorsqu’elle combine renommage et archivage, l’archivage intervient en dernier. Renommer un projet archivé sans le restaurer dans la même requête provoque **403**, `PROJECT_ARCHIVED`.

Si « ACME Ltd » devient « ACME Group » dans le CRM, envoie `{ "name": "ACME Group" }`. Le contenu du projet reste inchangé.

`DELETE /api/v1/projects/{id}` supprime le projet et libère son identifiant externe. Deux modes sont disponibles :

- Par défaut, la suppression en cascade fait expirer les documents dans le traitement de rétention, place tes propres chats dans la corbeille et retire les tâches en annulant leurs exécutions en cours.
- Avec `{ "mode": "detach" }`, les documents et chats sont détachés du projet et conservés dans l’organisation.

Dans les deux cas, les agents et dossiers du projet sont supprimés, et son historique d’exécutions part avec lui, exécutions terminées comprises — à la différence de la suppression d’une automatisation, qui conserve ses exécutions. La cascade partage avec la suppression dans l’application un plafond de 5 opérations par personne et par minute :

```bash
curl -sS --compressed -X DELETE "https://your-host.example.com/api/v1/projects/<projectId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 204
```

La suppression du projet renvoie **409**, avant toute écriture, dans les cas suivants :

- Une automatisation est encore installée dans le projet : `PROJECT_HAS_BOUND_AUTOMATIONS`, avec les noms dans `data.automations`. Désinstalle chacune avec `DELETE /projects/{id}/automations/{name}` avant de réessayer.
- La cascade supprimerait un document maîtrisé en relecture, approuvé ou conservant une version approuvée : `PROJECT_HAS_PROTECTED_RECORDS`, avec les documents dans `data.documents`.
- Une conservation légale couvre un document du projet : `PROJECT_LEGAL_HOLD`.

## Créer une tâche, puis l'exécuter

Les routes Tâches permettent de représenter un élément externe sur le tableau d’un projet, de lancer un workflow déployé pour le traiter et de lire ses résultats.

Si l’automatisation est liée à des projets, installe-la d’abord dans celui où tu veux l’utiliser. L’installation est idempotente : **201** lors du premier appel, **200** si la liaison existe déjà. Elle exige la capacité développeur et l’accès en édition à un projet actif. Si le compte de l’intégration n’a pas ces droits, fais préparer cette liaison avant son premier appel :

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/automations/vat-return" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{}'
# → 201 { "name": "vat-return", "added": true }
```

`GET /api/v1/projects/{id}/automations` liste les automatisations installées dans le projet. Une automatisation sans aucune liaison peut aussi s’exécuter dans un projet accessible à un appelant disposant des droits d’édition requis. Elle n’apparaît toutefois pas dans cette liste.

Pour désinstaller une automatisation, utilise `DELETE /api/v1/projects/{id}/automations/{name}`. La réponse est **204**, ou **404**, `AUTOMATION_NOT_INSTALLED`, si elle n’était pas installée. Les mêmes droits de développeur et d’édition du projet sont requis.

### Créer ou actualiser la tâche reflétée

La combinaison `(projectId, externalSystem, externalId)` identifie la tâche de façon unique. Le premier appel la crée avec **201** et `created: true`, dans `backlog` — la colonne d’entrée du miroir, alors que l’application place une tâche créée à la main dans « À faire ». Un nouvel appel retrouve la même tâche avec **200** et `created: false`.

Tale retire les espaces de début et de fin des deux identifiants externes et les normalise en NFC, comme l’`externalItemId` d’un projet. Des différences de normalisation ou d’espacement ne créent donc pas de doublon. Un identifiant devenu vide provoque **400**.

Le `projectId` vient de l’URL : le répéter dans le corps provoque **400**. Tout détenteur de clé qui peut lire un projet actif peut créer une tâche, Membres compris (contrat 3.6.0). Un nouvel appel modifie la tâche qu’il désigne et exige donc le droit de la modifier : en tant qu’Éditeur ou rôle supérieur, ou en tant que membre qui a créé la tâche ou à qui elle est attribuée. Les autres reçoivent **403**, `RBAC_FORBIDDEN`, et rien n’est écrit.

Avec `externalSystem: "github"` ou `"glitchtip"`, `externalState` ne modifie jamais le statut de la tâche Tale. Les nouvelles tâches arrivent dans `backlog` ; fermer, résoudre ou rouvrir l’issue à la source ne change pas leur avancement local. Les automatisations d’import affichent l’état de la source séparément sur la tâche.

Pour les autres systèmes sources, `externalState` synchronise l’état de l’élément source :

- `closed` place la tâche en `in_review` pour qu’une personne puisse la terminer. Dans ce parcours de synchronisation, seul un appel du moteur de workflow lui-même peut directement la placer en `done`.
- `open` ramène en `backlog` une tâche que la synchronisation avait placée en `in_review`, ou une tâche en `done`.

Une relecture en attente attribuée à un agent conserve son statut et son relecteur. La synchronisation d’une telle source enregistre séparément la fermeture ou la réouverture, sans approuver ni retirer cette relecture.

Une mise en revue décidée par une personne ou un agent reste inchangée. Dès qu’un déplacement est effectué depuis le tableau, la synchronisation ne peut plus annuler sa propre mise en revue en envoyant `open`.

Une tâche annulée reste annulée dans les deux cas.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/tasks" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "externalSystem": "crm", "externalId": "case-991", "title": "Prepare the Q1 filing" }'
# → 201 { "task": { "id": "<taskId>", "created": true } }
```

Un nouvel appel pour une tâche active ayant la même référence externe actualise son titre et sa description. Omettre `description` l’efface. Les libellés changent uniquement si tu les envoies. Une tâche archivée reste inchangée.

L’identifiant de la tâche reste stable et `runWorkflowSlug` ne relance pas de workflow lors de cet appel répété. Après une réponse perdue, conserve les mêmes données pour réessayer.

### Lier un dossier de préparation et attribuer l’automatisation

`description`, `labels`, `externalUrl` et `setupFolderName` sont facultatifs. `title` accepte au maximum 200 unités de code UTF-16 et `description` 20 000 ; la plupart des emojis en comptent 2. `labels` accepte jusqu’à 50 noms de 50 unités au plus chacun. `externalUrl` doit être une URL absolue en `http` ou `https`. Une valeur hors de ces limites ou un autre schéma d’URL provoque **400**, sans modification silencieuse de la valeur.

`setupFolderName` désigne un dossier racine du projet par son nom, sans tenir compte de la casse. Tale enregistre l’identifiant de ce dossier dans le champ `externalUrl` de la tâche. Une automatisation conçue pour travailler à partir d’un dossier peut alors retrouver cette référence dans son entrée `{task: ...}`. Le dossier est résolu à nouveau à chaque appel de synchronisation.

Si aucun dossier racine ne correspond au nom, Tale renvoie **400**, `SETUP_FOLDER_MISSING`, sans créer la tâche. Envoyer à la fois `setupFolderName` et `externalUrl` provoque **400**, `INVALID_BODY`.

Les noms de libellés sont nettoyés de leurs espaces de début et de fin, puis normalisés en NFC. La comparaison avec les libellés du projet ignore la casse. Un nouveau libellé conserve l’orthographe envoyée ; un libellé existant conserve celle déjà enregistrée.

La réponse respecte l’ordre de ta liste. Ainsi, `["Bug", "P1"]` reste `["Bug", "P1"]`. Si le projet possède déjà `Bug`, envoyer `["bug"]` réutilise ce libellé au lieu d’en créer un second. Seul un Éditeur ou un rôle supérieur du projet crée ainsi de nouveaux libellés ; les autres détenteurs de clé nomment des libellés que le catalogue possède déjà, et un nom nouveau donne **400**, `TASK_LABEL_UNKNOWN`, sans rien écrire.

Envoie `automationSlug` pour attribuer la tâche à une automatisation. Cette attribution alimente le panneau de travail de la tâche : démarrage, progression de l’exécution et questions adressées à l’opérateur. Un appel ultérieur peut compléter une attribution manquante, mais ne remplace pas un responsable déjà défini.

`runWorkflowSlug` demande le démarrage d’un workflow déployé dans le même appel, uniquement si la tâche vient d’être créée. La réponse contient son `runId` ; l’ancien champ `executionId`, déprécié, contient la même valeur.

La tâche reste créée si le démarrage échoue ensuite. La réponse contient alors `runId: null`, notamment si `runWorkflowSlug` ne désigne aucune automatisation déployée. Vérifie donc la référence d’exécution même après une réponse de création réussie. Tu peux aussi lancer le workflow explicitement dans un appel distinct.

L’attribution par `automationSlug` a des exigences plus strictes : l’automatisation doit exister, sinon Tale renvoie **404**, `AUTOMATION_NOT_FOUND`, et posséder une version déployée, sinon **409**, `AUTOMATION_NOT_DEPLOYED`.

Une automatisation liée uniquement à d’autres projets ne peut pas s’exécuter ici : la réponse est **403**.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/tasks/<taskId>/start" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "workflowSlug": "vat-return" }'
# → 200 { "started": true, "runId": "<runId>", "executionId": "<runId>" }
```

### Vérifier si une exécution de tâche a démarré

Le démarrage exige le droit de modifier la tâche — en tant qu’Éditeur ou rôle supérieur, ou en tant que membre qui l’a créée ou à qui elle est attribuée (sinon **403**, `RBAC_FORBIDDEN`) —, un projet actif et une tâche active. Une tâche archivée provoque **403**, `TASK_ARCHIVED`. La lecture de la tâche porte `archivedAt` tant qu’elle l’est ; `PATCH …/tasks/{taskId}` avec `{ "archived": false }` la restaure — voir ci-dessous.

L’exécution reçoit la tâche dans `{task: ...}`. Aucune capacité développeur supplémentaire n’est requise pour ce démarrage. Le journal l’attribue à la clé utilisée. Suis ensuite `GET /api/v1/projects/{id}/runs/{runId}` avec `runId` ; `executionId` est son ancien alias déprécié.

Une réponse **200** ne prouve pas qu’une nouvelle exécution a commencé. Lis `started`. Si la réponse contient `started: false` et `reason: "already_running"`, elle fournit le `runId` de l’exécution déjà en cours — une tâche ne tient qu’une exécution vivante à la fois, quelle que soit l’automatisation qui l’a démarrée, cette exécution peut donc appartenir à une autre automatisation (son `name` dit laquelle) : suis celle-ci. Un workflow lié à d’autres projets répond **403**, `AUTOMATION_PROJECT_FORBIDDEN`.

Si un agent de projet travaille déjà sur la tâche, le démarrage du workflow est refusé avec **409** `TASK_HAS_LIVE_RUN`. Attends que l’agent termine ou annule son exécution avant de lancer le workflow. De même, aucun agent ne peut démarrer tant qu’un workflow travaille sur la tâche.

Une nouvelle exécution est aussi refusée avec **403** `TASK_AUTOMATION_DISABLED` si l’automatisation des tâches est désactivée, ou **409** `TASK_AUTOMATION_UNAVAILABLE` si sa politique est illisible. Demande à un administrateur de l’activer ou de rétablir la politique. Les exécutions en cours peuvent se terminer et les commentaires restent enregistrés.

`workflowSlug` nomme l’automatisation telle que `GET /api/v1/automations` la liste — la forme avec `/` (`billing/dunning`), jamais l’orthographe `__` du chemin d’URL — et doit désigner une automatisation existante et déployée. Sinon, la route renvoie respectivement **404**, `AUTOMATION_NOT_FOUND`, ou **409**, `AUTOMATION_NOT_DEPLOYED`. Ce sont les mêmes exigences que pour l’attribution d’une tâche avec `automationSlug`.

Ces vérifications précèdent la facturation du budget de démarrage. `reason: "not_started"` couvre le cas résiduel où le déploiement disparaît entre la vérification et le démarrage.

Des démarrages simultanés de la même tâche avec la même automatisation retrouvent la même exécution active. Ce mécanisme ne correspond pas à une prise en charge d’`Idempotency-Key` pour les tâches : après sa fin, un nouvel appel peut créer une autre exécution. Conserve le `runId` renvoyé et consulte-le avant de répéter un démarrage au résultat incertain.

### Archiver ou restaurer une tâche

`PATCH /api/v1/projects/{id}/tasks/{taskId}` avec `{ "archived": true }` archive la tâche — comme depuis le tableau : elle reste lisible ici et refuse les commentaires et les démarrages avec **403**, `TASK_ARCHIVED` — et `{ "archived": false }` la restaure. Les deux sont idempotents ; un miroir qui remplace une tâche (une nouvelle livraison qui en a ouvert une autre, un enregistrement source annulé) classe l’ancienne sans la lire d’abord. Il faut un projet **actif** et le droit de modifier la tâche, en tant qu’Éditeur ou rôle supérieur, ou en tant que membre qui l’a créée ou à qui elle est attribuée (**403**, `PROJECT_ARCHIVED` ou `RBAC_FORBIDDEN`) ; la tâche elle-même peut être archivée, c’est à cela que sert la restauration. Le corps contient exactement `archived` ; le titre, la description et les libellés passent par la répétition de l’admission. La réponse est la tâche dans son nouvel état.

```bash
curl -sS --compressed -X PATCH "https://your-host.example.com/api/v1/projects/<projectId>/tasks/<taskId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "archived": true }'
# → 200 { "task": { "id": "<taskId>", "status": "in_progress", "archivedAt": 1789921403000, ... } }
```

### Commenter et lire l’état de la tâche

Les commentaires sont publiés au nom de la personne qui a créé la clé, avec le même comportement que dans l’application, y compris pour les @mentions. Toute personne pouvant lire le projet, même avec le rôle Membre, peut commenter une tâche active dans un projet actif.

Une tâche archivée refuse les nouveaux commentaires avec **403**, `TASK_ARCHIVED`. Un projet archivé les refuse avec `PROJECT_ARCHIVED`. La tâche et ses commentaires restent lisibles après archivage.

L’API vérifie d’abord le projet indiqué dans l’URL. Un projet absent ou inaccessible provoque **404**, `PROJECT_NOT_FOUND`. Elle vérifie ensuite la tâche : `TASK_NOT_FOUND` signifie que celle-ci n’existe pas ou appartient à un autre projet.

```bash
curl -sS --compressed -X POST "https://your-host.example.com/api/v1/projects/<projectId>/tasks/<taskId>/comments" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Filed. Confirmation 2026-8842." }'
# → 201 { "comment": { "id": "..." } }

curl -sS --compressed "https://your-host.example.com/api/v1/projects/<projectId>/tasks/<taskId>" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "task": { "id": "<taskId>", "title": "...", "status": "in_progress", "externalId": "case-991", "labels": [], "dueDate": 1790719200000, "repeat": null, ... } }
```

La lecture d’une tâche renvoie aussi son calendrier, en lecture seule sur cette API. `startDate` et `dueDate` sont des horodatages Unix en millisecondes. Ils ne figurent dans la réponse que lorsqu’ils sont renseignés. Quand tu choisis ces dates dans l’application, elle enregistre minuit au début du jour choisi, dans le fuseau horaire de ton navigateur. `repeat` est toujours présent : `null` si la tâche ne se répète pas, sinon un `TaskRepeat` comme `{ "frequency": "weekly", "interval": 2, "weekdays": [2, 4], "timezone": "Europe/Zurich", "createOn": "dueDate" }`. `frequency` vaut `daily`, `weekly`, `monthly` ou `yearly`, et `interval` va de 1 à 99 ; `weekly` liste des `weekdays` de 0 (dimanche) à 6 (samedi), `monthly` prend un `monthDay` et `yearly` un `month` et un `monthDay`. `createOn` n’apparaît, sous la forme `"dueDate"`, que si la tâche suivante est aussi créée au début du jour d’échéance ; sans lui, la tâche suivante arrive quand celle-ci est terminée ou annulée. Quand une tâche récurrente est clôturée, dans l’application ou par une relecture approuvée ici, ou quand son jour d’échéance commence avec `createOn: "dueDate"`, sa tâche suivante est créée en `todo`, et `repeatNextTaskId` la désigne dès lors. Si cette tâche suivante est supprimée, `repeatNextTaskId` disparaît, mais la tâche n’en crée pas d’autre pour autant (contrat 3.3.0).

### Lire les commentaires et télécharger les livrables

Lors de l’écriture d’un commentaire, le texte d’origine `body`, sans ses espaces de début et de fin, doit compter de 1 à 10 000 unités de code UTF-16 (la plupart des emojis en comptent 2). Tu peux lui ajouter `bodyByLocale`. La lecture le renvoie lorsqu’il existe. Fournis des traductions équivalentes et non vides pour `en`, `de` et `fr` ; d’autres clés de langue ou de région, comme `nl`, `it` et `de-CH`, sont acceptées. Chaque valeur est nettoyée et limitée de la même façon, avec au plus 16 langues par commentaire. Affiche la variante exacte choisie par le lecteur, puis la langue de base, puis `en`, puis `body`. L’auteur reste le titulaire de la clé. Une modification du texte seul dans Tale efface les anciennes traductions pour qu’elles ne masquent pas la modification.

Les agents de tâche et de workflow reçoivent la consigne de conserver la langue du titre et de la description de la tâche. Si aucune langue ne s’en dégage, ils utilisent celle définie par défaut pour les agents de l’organisation. Les mots fixes d’un modèle de titre, les identifiants de trimestre, la langue des documents sources et celle de l’interface de la personne qui démarre l’exécution ne déterminent pas la langue de la tâche. Cette règle couvre aussi les questions, les reprises et la création de tâches associées. Il s’agit de consignes au modèle ; les traductions enregistrées des commentaires de progression permettent aux clients de choisir la langue affichée indépendamment de celle de la tâche.

Consulte la sortie de l’exécution et les commentaires de la tâche pour connaître le résultat. Certaines automatisations créent aussi des fichiers ; leur présence et leur dossier de destination dépendent du workflow. Ne suppose pas que chaque exécution dépose un livrable dans le dossier de préparation ou du trimestre.

Les commentaires sont paginés, avec la page la plus récente en premier. Chaque page est ordonnée chronologiquement. `limit` vaut 200 par défaut et accepte au maximum 500. Tant que `isDone` vaut `false`, retransmets `continueCursor` tel quel dans `cursor` pour lire les commentaires plus anciens. Ce jeton signé est opaque, pas numérique.

La route de contenu renvoie directement les octets avec **200**, sans redirection. L’en-tête `Content-Disposition`, conforme à la RFC 6266, indique le nom du fichier.

Utilise `curl -o` pour enregistrer les octets. Ajoute `--fail-with-body` pour qu’un refus produise un code de sortie non nul ; ton script peut ainsi distinguer un téléchargement réussi d’une réponse d’erreur JSON.

La route accepte une plage d’octets unique dans `Range`, par exemple `bytes=0-1023`, `bytes=1024-` ou `bytes=-512`. Elle renvoie alors **206** avec `Content-Range`.

Une plage commençant à la fin du fichier ou au-delà renvoie **416**, avec un corps vide et `Content-Range: bytes */<size>`. C’est notamment ce qu’envoie `curl -C -` lorsque la copie locale est déjà complète : la taille permet de reconnaître ce cas. Plusieurs plages ou un en-tête illisible sont ignorés ; le fichier entier est alors renvoyé avec **200**.

`HEAD` renvoie les mêmes en-têtes que `GET`, dont `Content-Length`, `Content-Type`, `ETag`, `Last-Modified` et `Accept-Ranges`, sans corps. Il ignore `Range`.

Utilise `curl -I`, plutôt que `curl -X HEAD` qui peut attendre un corps. Pour vérifier si le contenu a changé, retransmets l’`ETag` dans `If-None-Match` : la réponse est **304** tant que le fichier reste identique.

```bash
curl -sS --compressed "https://your-host.example.com/api/v1/projects/<projectId>/tasks/<taskId>/comments?limit=100" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>"
# → 200 { "comments": [ { "id": "...", "authorType": "agent", "body": "…", ... } ], "isDone": false, "continueCursor": "<jeton opaque>" }

curl -sS --compressed --fail-with-body "https://your-host.example.com/api/v1/projects/<projectId>/files/<documentId>/content" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: <org-slug>" \
  -o report.md
# → les octets du fichier (Content-Disposition porte le nom du fichier)
```

## Modèle d'erreur

Les erreurs ordinaires produites par l’API utilisent un objet JSON plat :


```json
{ "error": "Automation not found", "code": "AUTOMATION_NOT_FOUND" }
```

Les [endpoints de modèles compatibles](https://docs.tale.dev/fr/develop/api-reference#model-endpoints) font exception : sous `/api/v1/openai` et `/api/v1/anthropic`, chaque refus, y compris ceux liés à l’authentification et à la limite de débit, prend le format d’erreur d’OpenAI ou d’Anthropic et y porte le même `code`.

`error` contient un message destiné à une personne. `code` fournit l’identifiant stable à utiliser dans ton programme. Les refus émis par l’API possèdent ce code ; OpenAPI en énumère les valeurs dans `Error.code`.

De nouveaux codes peuvent être ajoutés dans une version mineure. Prévois donc un traitement générique selon le statut HTTP pour les codes inconnus. Certains refus ajoutent `data`, par exemple `issues` pour un corps invalide, `retryAfterMs` pour une limite de débit ou `providers` pour un modèle ambigu.

Ne suppose pas que toute réponse hors 2xx contient ce JSON. Les réponses conditionnelles **304** et les réponses à `HEAD` n’ont pas de corps. Certains refus du serveur frontal, notamment **400** ou **431**, peuvent également arriver sans enveloppe JSON. Vérifie le statut et la présence d’un corps avant de le parser.

Les principaux statuts sont décrits ci-dessous. Utilise le `code` pour distinguer les cas lorsqu’il est disponible :

- **400** — la requête n’est pas valide. Le code précise le contrôle à corriger :

  - `INVALID_BODY` couvre un champ requis manquant, un mauvais type, une clé inconnue, un corps illisible ou non UTF-8, un caractère NUL, un substitut UTF-16 non apparié, un entier supérieur à 2^53 − 1 ou une valeur hors des bornes du champ. Un `limit` envoyé dans un corps de recherche au-dessus du plafond est refusé, sans être ramené à la limite.
  - `data.issues` indique chaque champ concerné, par exemple `price` ou `contacts.2.email`, et sa raison. Une clé inconnue possède son propre problème, à son nom. Les raisons restent des textes affichables, tels que `is required`, `must be a string`, `must not be blank`, `must be at most 200 UTF-16 code units` ou `must be one of "a", "b"`. Corrige le champ indiqué par `path` ; ton programme doit utiliser `code`, pas analyser ces phrases.
  - Les corps sont interprétés comme JSON, quelle que soit la valeur de `Content-Type`. Ces routes ne renvoient pas 415.
  - Pour les paramètres de requête, un curseur jamais fourni par la liste donne `INVALID_CURSOR`, un `limit` non entier donne `INVALID_LIMIT` et un autre paramètre refusé donne `INVALID_QUERY`. La réponse désigne aussi le paramètre dans `data.issues`. Ces erreurs ne sont pas traitées comme une demande de première page. Un `limit` entier hors des bornes, lui, est ramené dans la plage autorisée.
  - Une entrée refusée par le schéma `inputs` de l’automatisation donne `AUTOMATION_INPUT_INVALID`, avec `data.issues`. Un déclencheur impossible donne `AUTOMATION_TRIGGER_INVALID`, par exemple le 30 février dans `0 0 30 2 *`.
  - Un patch supprimant le dernier champ d’identité d’un contact donne `CONTACT_IDENTITY_REQUIRED`. Modifier le contenu d’un document maîtrisé gelé ou sans suivre son remplacement donne `DOCUMENT_RECORD_FROZEN` ou `DOCUMENT_RECORD_REPLACEMENT_REQUIRED`.
  - Une clé associée à plusieurs organisations sans organisation explicite donne `ORG_SLUG_REQUIRED`. Un `Idempotency-Key` vide après normalisation, de plus de 255 caractères ou contenant des caractères hors ASCII imprimable donne `INVALID_HEADER`, avec le nom de l’en-tête dans `data.issues`.
  - Un octet NUL dans l’URL, comme `%00` dans le chemin ou la chaîne de requête, donne `INVALID_URL` avant le routage et la vérification de la clé.
  - En HTTP/2, un corps terminé avant la longueur annoncée dans `Content-Length` donne `BODY_LENGTH_MISMATCH`. Cette réponse vient du serveur frontal, avec un nouveau `requestId` et sans `X-Tale-Api-Version`.
- **401** — la clé API est absente ou invalide : `UNAUTHORIZED`, avec `WWW-Authenticate: Bearer`.
- **403** — l’action dépasse les droits du compte : rôle insuffisant (`ROLE_FORBIDDEN`, `KNOWLEDGE_ENTRY_FORBIDDEN`), accès en édition manquant, tâche d’un autre membre que le compte ne peut pas modifier (`RBAC_FORBIDDEN`) ou `teamIds` d’un document ou d’un projet désignant une équipe dont la personne n’est pas membre (`TEAM_ACCESS_DENIED`), ou enregistrement d’un skill partagé avec toute l’organisation alors que celle-ci le réserve (`SKILL_PUBLISH_FORBIDDEN`). Ce statut couvre aussi les écritures sur un projet ou une tâche archivé (`PROJECT_ARCHIVED`, `TASK_ARCHIVED`), y compris les `teamIds` d’un projet, une automatisation interdite dans le projet et un `X-Organization-Slug` désignant une organisation inaccessible (`ORG_FORBIDDEN`).
- **404** — la ressource est absente, inaccessible ou rattachée à un autre fil ou projet. Chaque famille utilise son code, par exemple `PROJECT_NOT_FOUND`, `DOCUMENT_NOT_FOUND` ou `THREAD_NOT_FOUND`. Un `X-Organization-Slug` inconnu donne `ORG_SLUG_INVALID`.

  Une route inconnue donne `NOT_FOUND` après vérification de la clé. Sans clé, **401** reste prioritaire : `/api/v1/openapi.json`, qui n’existe pas, répond **401** sans clé et **404** avec une clé valide. Le document public est disponible à `/openapi.json`, sans clé.
- **405** — la route existe mais ne prend pas en charge cette méthode : `METHOD_NOT_ALLOWED`. L’en-tête `Allow` énumère les méthodes acceptées.
- **409** — l’état de la ressource empêche l’opération. Les causes comprennent une automatisation non déployée, une automatisation liée appelée sans URL de projet, une exécution encore active à sa suppression (`RUN_ACTIVE`), un `Idempotency-Key` réutilisé avec un autre corps (`IDEMPOTENCY_KEY_REUSED`), un fil archivé ou un tour déjà en cours.

Un instantané de contenu plus récent lié à un contact dans la corbeille donne également `409 CONVERSATION_CONTACT_TRASHED`. Restaure le contact ou ferme le miroir avant de poursuivre.

  Les doublons ont des codes propres à la ressource : `CONTACT_DUPLICATE_EMAIL` et `CONTACT_DUPLICATE_EXTERNAL_ID` pour `email` et `externalId` d’un contact ; `DUPLICATE_PRODUCT_NAME` et `DUPLICATE_PRODUCT_EXTERNAL_ID` pour `name` et `externalId` d’un produit ; `KNOWLEDGE_ENTRY_DUPLICATE` pour le sujet d’une entrée ; `PROJECT_DUPLICATE_EXTERNAL_ID` pour l’`externalItemId` d’un projet.

  Ce statut couvre aussi une entrée de connaissances remplacée (`KNOWLEDGE_ENTRY_SUPERSEDED`), un `expectedUpdatedAt` périmé (`CONTACT_STALE`, `PRODUCT_STALE`, `DOCUMENT_STALE`), un document portant une entrée active (`DOCUMENT_HAS_KNOWLEDGE_ENTRY` : modifie ou supprime l’entrée), une livraison qui ne peut pas être relancée car elle n’est pas en lettre morte (`DELIVERY_RETRY_UNAVAILABLE`) et une recherche sans modèle d’embedding.
- **412** — une précondition échoue, sans écriture. Pour un skill, `If-Match` provoque `SKILL_STALE` si le `SKILL.md` a changé ou si aucun bundle n’est stocké. `data.etag` contient l’ETag courant, ou `null` en l’absence de bundle. `If-None-Match: *` provoque `SKILL_EXISTS` si le slug possède déjà un bundle.
- **413** — le corps dépasse la taille autorisée : `BODY_TOO_LARGE`, avec le plafond dans le message. La limite habituelle des corps JSON est de 1 Mio, sauf indication différente pour l’opération dans les sections précédentes. Le webhook accepte au maximum 256 Kio, soit 262 144 octets. Un fichier dépassant la politique de taille ou de type est, lui, refusé au rattachement avec **400** et un code de raison.
- **422** — le bundle de skill stocké n’est pas lisible : lien symbolique, fichier dépassant le plafond de préparation de 4 Mio ou `SKILL.md` impossible à parser (`SKILL_MALFORMED`). Les lectures peuvent produire cette réponse. Pour un `PUT`, elle concerne uniquement le bundle déjà présent : le corps envoyé est validé avec **400**, `INVALID_BODY` ou `INVALID_SKILL`, et ne provoque pas à lui seul **422**.
- **429** — le débit autorisé est dépassé (`RATE_LIMITED`). `error` décrit l’attente et `requestId` identifie la requête. Respecte `Retry-After` en secondes entières ou `data.retryAfterMs` en millisecondes avant de réessayer ; consulte [Limites de débit](https://docs.tale.dev/fr/develop/rate-limits).

| Statut | Sens et action |
| --- | --- |
| **414** | l’URL, chemin et chaîne de requête compris, dépasse 32 Kio : `URI_TOO_LONG`. L’enveloppe contient un `requestId`. |
| **408** | la réception complète des en-têtes et du corps a dépassé 15 minutes : `REQUEST_TIMEOUT`. La réponse contient un nouveau `requestId`, car la requête expirée n’en avait pas encore reçu. La connexion est fermée ; utilise une connexion plus rapide ou des transferts plus petits pour réessayer. |
| **431** | les en-têtes dépassent ensemble le plafond de 64 Kio du serveur frontal. En HTTP/1.1, la réponse n’a ni enveloppe JSON ni `X-Request-Id` — l’analyseur du frontal l’écrit avant qu’une route tourne. Le frontal tolère quelques Kio de marge : une URL ou un en-tête légèrement trop long peut encore atteindre la plateforme et y être refusé selon ses règles. Une URL de 66 Kio reçoit ainsi **414**. En HTTP/2, le plafond de 64 Kio est strict et son dépassement entraîne la fermeture de la connexion. |
| **500** | une erreur interne est survenue : `INTERNAL_ERROR`. Fournis le `requestId` de l’enveloppe lorsque tu la signales. |
| **503** | une dépendance nécessaire est indisponible. La base de données de la plateforme peut elle-même redémarrer ou être injoignable (`DATABASE_UNAVAILABLE`, avec `Retry-After` et un `requestId`) : toute opération peut alors répondre ainsi, y compris le déclencheur webhook et la vérification de la clé, si bien qu’une clé valide n’est jamais refusée avec **401** pendant ce temps. Cela comprend aussi le fournisseur d’embedding (`EMBEDDING_UPSTREAM_ERROR`, avec `Retry-After`), le stockage d’un téléchargement (`OBJECT_STORE_UNAVAILABLE`, avec `Retry-After`), un stockage non configuré (`OBJECT_STORE_UNCONFIGURED`) ou une purge inachevée (`PURGE_INCOMPLETE`). `KNOWLEDGE_ENTRY_STORE_TIMEOUT` signifie que le stockage a accepté l’écriture d’une entrée de connaissances sans répondre dans les 30 secondes ; aucun enregistrement n’est créé. Réessaie avec un délai croissant. |
| **502**, **503**, **504** | le serveur frontal ne peut pas joindre la plateforme, par exemple pendant son redémarrage : `UPSTREAM_UNAVAILABLE`. Il fournit `Retry-After` et un nouveau `requestId`, sans `X-Tale-Api-Version`. Ce comportement concerne les routes destinées aux programmes : `/api/*`, `/events`, `/status.json`, `/openapi.json` et `/.well-known/*`. Une navigation dans le navigateur reçoit la page de maintenance. Réessaie avec un délai croissant. |

Un `If-Match` de document qui ne correspond plus à sa représentation lue donne aussi `412 PRECONDITION_FAILED`, avec le tag courant dans `data.etag` et aucune écriture.


Retirer le déclencheur d’une automatisation existante avec `DELETE .../triggers` renvoie **204**, même si aucun déclencheur n’était configuré. Une automatisation inconnue renvoie **404**.

Supprimer une ressource absente renvoie aussi **404**, y compris un contact déjà dans la corbeille, un produit déjà supprimé ou une entrée de connaissances déjà supprimée. Le `DELETE` d’un contact le déplace dans la corbeille (`POST /api/v1/contacts/{id}/restore` le rétablit) ; celui d’un produit est définitif — les produits n’ont ni corbeille ni restauration, et le nom comme l’`externalId` redeviennent disponibles aussitôt pour un nouveau produit, qui est une nouvelle ligne avec un nouvel id. Il emporte l’image téléversée du produit (comme un `PATCH` qui remplace ou retire `imageUrl`), sauf si un autre produit affiche encore le même téléversement ; sous une conservation légale active — au niveau de l’organisation, ou d’un membre dépositaire qui a téléversé l’image — la suppression est refusée avec **409**, `LEGAL_HOLD_ACTIVE`, et un patch conserve l’image remplacée. Supprimer une entrée active retire toutes les versions de son sujet, place son document dans la corbeille et retire immédiatement les passages correspondants du corpus de recherche. La suppression directe de ce document est refusée.

Annuler une exécution inconnue renvoie **404**. Une réponse `{cancelled: false}` indique qu’elle existe mais est déjà terminée.

Tu peux lire l’énumération exacte des erreurs sans clé :

```bash
curl --fail --silent --show-error "$TALE_URL/openapi.json" \
  | jq -r '.components.schemas.Error.properties.code.enum[]'
```

## Versionnage

Distingue trois versions lorsque tu connectes un client à une instance :

- Le build renvoyé par `GET /api/health` identifie la version du déploiement.
- Le préfixe `/api/v1/` désigne la génération compatible de l’API REST.
- `info.version` dans `/openapi.json` identifie la version du contrat d’échange.

Le retrait des routes `/api/v1/` nécessite une génération `/api/v2/` et une annonce au moins deux versions mineures à l’avance. Pendant ce préavis, les routes concernées portent les en-têtes `Deprecation` et `Sunset`.

Le contrat suit le versionnage sémantique. Une version mineure peut ajouter une opération, un champ, un en-tête ou un code d’erreur. Un retrait ou un changement de sens exige une version majeure.

Les réponses de l’API indiquent dans `X-Tale-Api-Version` la version implémentée, ce qui permet à un client utilisant une version précise de détecter une évolution. Le document OpenAPI décrit les routes et schémas de l’instance en cours d’exécution ; son champ `servers` désigne cette instance. La page `/docs` permet de le consulter.

Utilise ce document comme contrat de ton client. Consulte aussi **Changements du contrat API** dans les notes de version : chaque changement des échanges y indique le comportement précédent et le nouveau. Le [format des notes de version](https://docs.tale.dev/fr/self-hosted/operate/release-notes/format) décrit cette convention.

Certaines routes et certains protocoles sont décrits séparément :

- `GET /api/health` est une sonde de fonctionnement sans authentification. Elle renvoie `{"status":"ok","version":"<build>"}`.
- `GET /status` et `/status.json` décrivent l’état du déploiement dans la [page de statut](https://docs.tale.dev/fr/develop/status-page).
- `/openapi.json` et `/docs` servent le contrat lui-même.
- [WebDAV](https://docs.tale.dev/fr/develop/webdav-api) et OpenID Connect, décrit plus haut, suivent leurs propres protocoles.

Les notes publiées sont disponibles sur [GitHub Releases](https://github.com/tale-project/tale/releases).

## Où ça se place

Utilise cette référence pour intégrer Tale depuis une application externe via REST. Le [point d’accès MCP](https://docs.tale.dev/fr/develop/mcp-endpoint) donne accès à la plateforme aux clients MCP et permet d’écrire les automatisations, une opération absente de REST.

Les [webhooks](https://docs.tale.dev/fr/develop/webhooks) démarrent des exécutions entrantes sans clé API. Pour configurer le travail directement dans Tale, notamment les agents de projet et les automatisations, consulte la documentation [Plateforme](https://docs.tale.dev/fr/platform). Pour utiliser Tale dans opencode, Claude Code ou un script shell, comme fournisseur de modèles par les [endpoints de modèles compatibles](https://docs.tale.dev/fr/develop/api-reference#model-endpoints) ou comme source de connaissances et d’outils, lis [Utiliser Tale depuis ton éditeur ou un script](https://docs.tale.dev/fr/develop/use-tale-from-your-editor).

# Fichiers Compose pour contribuer
Source: https://docs.tale.dev/fr/develop/compose-files

Utilise les fichiers Compose du dépôt pour développer ou tester Tale à partir du code source. Dans le parcours local habituel, [l’application et le backend tournent sur la machine, avec leurs dépendances dans Docker](https://docs.tale.dev/fr/develop/contributor-setup). Choisis le parcours ci-dessous pour tester les images de développement elles-mêmes.

Les installations auto-hébergées utilisent le déploiement généré par la CLI, décrit dans le [démarrage rapide](https://docs.tale.dev/fr/self-hosted/install/quickstart). Les fichiers du dépôt contiennent des ports et des montages de développement. Examine-les avant d’exposer un hôte publiquement.

Choisis un seul parcours pour la modification à tester. Démarrer le frontend natif et celui en conteneur sur le même port crée un conflit, pas une seconde instance isolée.

## Démarrer le développement en conteneurs

Depuis la racine du dépôt, utilise la version de Bun prévue et Docker Compose :

```bash
bun install
bun run docker:dev
bun run docker:dev:logs
```

`docker:dev` prépare l’image et le réseau de la sandbox, génère un complément d’environnement et démarre ensemble les configurations de base, de développement et de documentation. Utilise cette commande plutôt que de copier uniquement son dernier appel Compose : la préparation fait partie du parcours. Le complément généré transmet la plupart des variables de l’hôte au conteneur de la plateforme. Vérifie donc l’environnement depuis lequel tu le lances.

`Ctrl-C` arrête le suivi des journaux. `bun run docker:dev:down` arrête ce déploiement. Conserve les volumes de données et l’environnement existant pour reprendre avec la même instance. Un second worktree a besoin de ports, de noms de conteneurs et de stockage distincts pour fonctionner indépendamment.

## Choisir un fichier complémentaire

| Fichier | Fonction |
| --- | --- |
| `compose.yml` | Services de base construits depuis le code et leurs dépendances. |
| `compose.dev.yml` | Montages du code et commandes de développement. |
| `compose.docs.yml` | Site de documentation et routage du proxy. |
| `compose.web.yml` | Site marketing et routage du proxy. |
| `compose.test.yml` | Configuration des tests de conteneur de la plateforme. |
| `compose.docs.test.yml` | Configuration des tests de conteneur de la documentation. |
| `compose.web.test.yml` | Configuration des tests de conteneur du site marketing. |
| `compose.test.mock.yml` | Configuration d’intégration avec services simulés. |

Lis le script qui utilise un fichier de test avant de l’appeler directement : il peut préparer les images, les ports et les données de test. [Contribuer à Docker](https://docs.tale.dev/fr/develop/contributing-docker) décrit les contrôles adaptés.

## Examiner la fusion Compose

Les fichiers s’appliquent de gauche à droite. Selon les règles de fusion de Compose, les suivants remplacent ou complètent la configuration précédente. Affiche les noms des services sans imprimer l’environnement résolu et ses secrets :

```bash
docker compose -f compose.yml -f compose.dev.yml -f compose.docs.yml config --services
```

Cette commande examine les fichiers statiques. `docker:dev` ajoute aussi son complément d’environnement généré. Une sortie complète de `docker compose config` peut contenir des identifiants interpolés ; garde-la hors des journaux publics et des rapports de bug.

## Comprendre les principaux services

Le déploiement du dépôt sépare `backend-api` et `backend-worker`. L’API traite les requêtes et l’authentification ; le processus de traitement exécute les tâches, les appels de modèles et le traitement des connaissances. `platform` sert l’application web. `proxy` dirige le trafic ; `db`, `knowledge-db` et `object-store` stockent les données applicatives, les connaissances et les fichiers.

`sandbox`, `sandbox-egress` et `sandbox-llm-gateway` fournissent l’exécution isolée et ses accès réseau et modèles. Le dépôt comprend aussi le service auxiliaire d’import vidéo. La topologie de production peut différer : le déploiement généré pour un seul hôte combine les bases applicative et de connaissances. Consulte [Architecture des conteneurs](https://docs.tale.dev/fr/self-hosted/operate/container-architecture) pour les responsabilités et la [référence d’environnement](https://docs.tale.dev/fr/self-hosted/configuration/environment-reference) pour leur configuration.

## Comprendre le premier échec

Si la préparation échoue, lis d’abord la première erreur du script. Pour une erreur d’image, vérifie Docker et la construction ; pour un réseau sandbox absent, sa création ; pour un second checkout, les ports occupés et les conteneurs existants. Consulte `docker compose ps` et les journaux du service avant de modifier sa configuration. Ne supprime pas les volumes pour résoudre un problème de démarrage : tu perdrais l’état nécessaire pour le reproduire.

# Connectors
Source: https://docs.tale.dev/fr/develop/connectors

Un connecteur donne à Tale un moyen réutilisable d'appeler un service. Sa définition décrit l'authentification, les destinations autorisées et les actions ; chaque organisation fournit ses propres identifiants. Cette page t'aide à examiner ce contrat ou à contribuer un nouveau connecteur.

Pour connecter un compte dans l'application, consulte [Identifiants des connecteurs](https://docs.tale.dev/fr/platform/admin/connectors). Pour choisir une intégration existante, parcours le [catalogue](https://docs.tale.dev/fr/platform/connectors/overview).

## Comment un connecteur est déclaré

Les définitions se trouvent dans `configs/platform/system/connectors/<slug>/connector.yml`, avec l'icône du connecteur. Le slug du dossier doit correspondre à `name`. Une automatisation appelle une action avec `<connector>.<action>`, par exemple `tavily.search`. Les connecteurs de fournisseurs apparaissent dans les paramètres ; les connecteurs internes utilisant l'authentification de la plateforme n'y figurent pas.

Cet extrait de la définition Tavily fournie montre l'identité et l'authentification. Ce n'est pas un connecteur complet : les définitions d'actions doivent aussi figurer dans le fichier.

```yaml
name: tavily
displayName: Tavily
description: Real-time web search and page extraction for AI research.
tags:
  - Search
allowedHosts:
  - api.tavily.com
auth:
  - method: api-key
```

### Définir les destinations autorisées

| Champ | Signification |
| --- | --- |
| `endpointMode: fixed` | Valeur par défaut. Les appels HTTP réels utilisent des URL fixes ; `allowedHosts` contient les hôtes exacts |
| `endpointMode: per-credential` | Chaque identifiant fournit une `endpointUrl` HTTPS ; les actions lisent son origine sans barre oblique finale via `ctx.endpoint` |
| `allowedHosts` en mode per-credential | Suffixes d'hôtes : `atlassian.net` autorise ses sous-domaines |
| `configFields` | Valeurs non secrètes propres à l'identifiant : hôte, port, région ou version d'API |

Confluence, GlitchTip et Shopify utilisent des origines propres à chaque identifiant. Les secrets n'ont pas leur place dans `configFields` : conserve-les dans les données d'identification chiffrées. Pour les actions JavaScript, `ctx.http` applique la restriction des destinations HTTP. Les backends natifs, comme les protocoles de messagerie, appliquent leurs propres contrôles ; une liste HTTP ne décrit pas toute leur sécurité réseau.

<Info>

Ajouter un connecteur demande une contribution au code source. L'exécution lit le catalogue de la plateforme ; une organisation ne peut pas importer sa propre définition. Commence par [l'environnement de contribution](https://docs.tale.dev/fr/develop/contributor-setup), puis étudie un connecteur existant utilisant une authentification et un transport similaires.

</Info>

## Ce qu’une action déclare

| Champ | Contrat pour l'auteur et l'appelant |
| --- | --- |
| `name`, `description` | Nom stable en snake_case et explication de l'usage de l'action |
| `input` | Schéma JSON objet, validé avant exécution ; décrire les champs et signaler ceux requis |
| `output` | Signature du résultat au style TypeScript ; documentation, pas validation des sorties à l'exécution |
| `effects` | `read` ou `write` ; les écritures passent par la politique d'approbation |
| `mock` | JavaScript déterministe obligatoire : même entrée, même sortie, sans accès réseau |
| `backend` | Implémentation réelle facultative : `yaml-js` avec `live`, ou `native` avec un identifiant `impl` |
| `exampleInput` | Petit exemple facultatif utile à la découverte et aux tests |

Sans backend réel, le connecteur fonctionne en simulation mais refuse l'exécution réelle. Une écriture n'a pas lieu si la plateforme ne peut pas obtenir une décision d'approbation. La [référence de politique](https://docs.tale.dev/fr/self-hosted/configuration/approvals) explique la priorité des règles et les décisions en attente.

Pour comprendre un résultat, lis aussi l'implémentation réelle. Par exemple, la recherche Tavily décrit l'entrée `max_results`, mais l'action fournie limite les résultats renvoyés à cinq. La signature de sortie seule ne précise pas cette limite.

### Sélectionner le bon compte

L'identifiant est choisi au moment de l'appel : celui nommé explicitement, sinon celui par défaut du connecteur. Modifier le défaut peut donc changer le compte d'une exécution ultérieure. Nomme l'identifiant explicitement lorsque le compte fait partie du contrat de ton intégration.

La découverte des boîtes mail fait exception : `conversation.sync_mailbox` et `conversation.list_mailbox_messages` parcourent tous les identifiants actifs du connecteur. Ces actions couvrent ainsi toutes les boîtes connectées, sans se limiter au compte par défaut.

## Les méthodes d’authentification

Un connecteur peut accepter plusieurs méthodes ; un identifiant enregistré en utilise exactement une.

| Méthode   | Libellé dans l’interface          | Ce que porte l’identifiant                                                                                                     |
| --------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `api-key` | Clé API                           | Un secret unique que le corps de l’action place lui-même — un en-tête du fournisseur, un paramètre d’URL ou un champ du corps. |
| `bearer`  | Jeton                             | Un jeton envoyé dans l’en-tête Authorization, sous le schéma que le connecteur nomme.                                          |
| `basic`   | Nom d’utilisateur et mot de passe | Un nom d’utilisateur et un mot de passe en HTTP Basic, la forme que prend aussi un login de boîte mail.                        |
| `oauth2`  | OAuth                             | Une autorisation par code : jeton d’accès, jeton de rafraîchissement, expiration et portées accordées.                         |

La méthode interne `platform` n'a pas d'identifiant enregistré et ne peut pas être combinée avec les méthodes de fournisseurs. Elle est réservée aux capacités natives de Tale, comme les actions sur les tâches ou les documents.

Les secrets sont chiffrés au repos. Les listes renvoient un aperçu masqué et des métadonnées, pas le secret en clair ; l'exécution autorisée résout le secret au moment de l'action. Un enregistrement réussi confirme le stockage, pas la validité chez le fournisseur ni les permissions nécessaires.

## Enregistrer une application OAuth

Le connecteur déclare les URL d'autorisation et de jeton, ainsi que les permissions demandées. Configure d'abord l'application du fournisseur, puis connecte un compte par son intermédiaire.

| Source | Priorité et configuration |
| --- | --- |
| Application d'organisation | Prioritaire. Un administrateur renseigne ID client et secret dans **Paramètres > Connecteurs > Applications OAuth** |
| Application de déploiement | Défaut sans application d'organisation : `CONNECTOR_OAUTH_<SLUG>_CLIENT_ID` et `CONNECTOR_OAUTH_<SLUG>_CLIENT_SECRET` |

Dans les variables d'environnement, mets le slug en majuscules et remplace ses tirets par des traits de soulignement. Pour une application Microsoft à locataire unique, configure aussi l'ID d'annuaire afin de cibler ce locataire plutôt que `/common`. Les secrets d'organisation sont chiffrés et ne sont plus affichés ensuite.

### Enregistrer exactement l'URL de retour

Tous les connecteurs OAuth d'organisation utilisent cette URI de redirection :

```text
${SITE_URL}${BASE_PATH}/api/connectors/oauth2/callback
```

Le schéma, l'hôte et le chemin doivent correspondre exactement, sans barre oblique finale. Tale refuse de commencer le consentement si `SITE_URL` manque ; il ne déduit pas une URL publique de la requête reçue. Un refus `redirect_uri` sur l'écran du fournisseur indique généralement une différence entre l'URI enregistrée et celle envoyée.

Les imports personnels OneDrive/Google Drive pour les connaissances suivent un parcours distinct. Google Drive partage son application OAuth entre connecteur et import : enregistre les deux URI de redirection sur ce client Google. Le retour d'import est décrit dans la [référence d'environnement](https://docs.tale.dev/fr/self-hosted/configuration/environment-reference).

### Configurer le point d'accès aux événements Slack

L'application Slack se configure uniquement au niveau du déploiement : `CONNECTOR_OAUTH_SLACK_*` et `CONNECTOR_SLACK_SIGNING_SECRET`. L'événement entrant doit être vérifié avant que Tale connaisse l'organisation ; une application d'organisation ne peut donc pas fournir ce secret.

Enregistre `${SITE_URL}${BASE_PATH}/api/connectors/slack/events` comme Events Request URL. Sans secret de signature, même la validation initiale renvoie `503`. Avec une configuration valide, Tale vérifie les signatures et identifie l'organisation à partir de l'espace Slack. Le point d'accès accuse actuellement réception des événements ; il ne transforme pas les messages Slack entrants en conversations et ne lance pas automatiquement d'automatisation.

## Choisir une surface

| Besoin | Solution |
| --- | --- |
| Action fournisseur prise en charge | Connecteur fourni et identifiant d'organisation |
| Action réutilisable absente du catalogue | Contribution avec schéma, mock déterministe, backend réel et tests |
| Appels propres au projet vers ton service | Secrets et code dans la sandbox d'un agent de projet, selon ses permissions réseau |
| Logique personnalisée dans une automatisation | Nœud `transform`, selon les capacités et règles réseau du moteur |

Un secret permet l'authentification ; il ne rend pas joignable un service privé inaccessible. Vérifie le réseau depuis la sandbox ou le moteur réellement utilisé avant de concevoir ton intégration autour de cet accès.

L'enregistrement de serveurs MCP externes n'est pas disponible. Le [point d'accès MCP de Tale](https://docs.tale.dev/fr/develop/mcp-endpoint) permet à un client externe d'appeler Tale ; il n'ajoute pas de connecteur sortant vers un autre serveur MCP.

## Où cela s’inscrit

Pour une contribution, teste séparément la validation du schéma, le comportement déterministe du mock et les appels réels au fournisseur. Vérifie aussi les échecs : identifiant absent, permission insuffisante, destination refusée, entrée invalide, refus fournisseur et approbation en attente pour une écriture. Le [guide de contribution](https://docs.tale.dev/fr/develop/contributor-setup) décrit l'environnement local ; le [guide des identifiants](https://docs.tale.dev/fr/platform/admin/connectors) décrit la configuration par l'administrateur.

# Construire et maintenir les images Tale
Source: https://docs.tale.dev/fr/develop/contributing-docker

Construis une image lorsque tu changes les dépendances d’un conteneur, son démarrage ou le code applicatif qu’il contient. Il te faut les sources préparées selon [Environnement de développement](https://docs.tale.dev/fr/develop/contributor-setup), un daemon Docker actif et l’accès aux registres d’images et de paquets utilisés par le Dockerfile.

Une construction réussie prouve que l’image peut être assemblée. Lance-la dans un environnement de développement séparé et teste le comportement modifié avant de la déployer.

## Identifier les images

Les Dockerfiles utilisent la racine du dépôt comme contexte de construction. Consulte chacun pour les versions de base et arguments exacts. Le tableau précise le rôle des images.

| Image | Répertoire du Dockerfile | Contenu et rôle |
| --- | --- | --- |
| `tale-platform` | `services/platform/` | Image Debian avec le client web construit et le backend natif. Les étapes de construction utilisent Bun et Node ; les rôles API et worker partagent cette image. |
| `tale-db` | `services/db/` | PostgreSQL et ses extensions de recherche et de vecteurs, sur une base ParadeDB. Les bases applicative et de connaissances utilisent cette image. |
| `tale-proxy` | `services/proxy/` | Configuration Caddy et démarrage du proxy. |
| `tale-sandbox` | `services/sandbox/` | Gestion des sandboxes avec Bun et la CLI Docker. |
| `tale-sandbox-runtime` | `services/sandbox-runtime/` | Environnement Python avec harnesses de programmation, Node, Bun, navigateurs et outils documentaires. |
| `tale-sandbox-egress` | `services/sandbox-egress/` | Proxy de sortie et prise en charge DNS sur Alpine. |
| `tale-sandbox-buildkitd` | `services/sandbox-buildkitd/` | BuildKit avec les réglages réseau et de démarrage de la sandbox. |
| `tale-sandbox-llm-gateway` | `services/sandbox-llm-gateway/` | Passerelle de modèles construite à partir de Bifrost. |

Le stockage objet et le service auxiliaire d’ingestion vidéo utilisent directement des images amont, sans Dockerfile Tale. Les images d’exécution de sandbox et de BuildKit sont lancées à la demande. Construire les seuls services déclarés dans Compose ne les construit pas automatiquement.

## Construire en local

Pour construire le proxy isolément, lance cette commande à la racine du dépôt :

```bash
docker build -f services/proxy/Dockerfile -t tale-proxy:docs-review .
```

Le tag local `docs-review` distingue le résultat d’une version publiée. Attends que la construction réussisse avant de tester l’image ou de la préparer pour sa distribution.

Pour un service disposant d’une définition `build:` dans le fichier Compose du dépôt :

```bash
docker compose build platform
```

Sans nom de service, `docker compose build` sélectionne tous les services dotés d’une définition de construction. La durée dépend du cache, du réseau, de la plateforme cible et de l’image. Une image de navigateur ou d’application n’a pas les mêmes besoins que le proxy.

Le fichier Compose du dépôt utilise `PULL_POLICY=build` par défaut. Les fichiers de production générés récupèrent normalement les images publiées. [Fichiers Compose](https://docs.tale.dev/fr/develop/compose-files) décrit le lancement de développement prévu, qui prépare aussi les services et images supplémentaires.

## Choisir où intervenir

Commence par le changement le plus limité qui répond au besoin :

| Besoin | Point de départ |
| --- | --- |
| Routage, TLS ou en-têtes publics | `services/proxy/Caddyfile` et configuration du proxy. Teste ensuite les retours d’authentification et le streaming. |
| Interface, backend ou extraction | Sources sous `services/platform/`, puis construction de l’image et tests concernés. |
| Paquet ou navigateur dans les sessions d’agents | `services/sandbox-runtime/Dockerfile`. Teste l’image dans une nouvelle session. |
| Connexions sortantes de la sandbox | Options d’environnement existantes d’abord ; modèles du proxy et code de démarrage seulement si nécessaire. |
| Comportement de BuildKit | `services/sandbox-buildkitd/`, avec ses hypothèses réseau. |

Les points d’entrée, contrôles d’état et chemins internes font partie du contrat d’implémentation. Un fork doit maintenir et tester leurs modifications au fil des versions. Une modification de configuration seule peut ne pas nécessiter d’image ; voir [Exploiter Compose soi-même](https://docs.tale.dev/fr/self-hosted/install/own-compose).

## Publier dans ton registre

Après les tests, choisis ton espace de noms et un tag immuable. Cet exemple publie uniquement l’image du proxy construite plus haut, pas toutes les images d’un déploiement. L’authentification au registre et le droit d’y publier sont nécessaires.

```bash
export REGISTRY=registry.internal.example.com/tale
export IMAGE_TAG=reviewed-build-1
docker tag tale-proxy:docs-review "$REGISTRY/tale-proxy:$IMAGE_TAG"
docker push "$REGISTRY/tale-proxy:$IMAGE_TAG"
```

Note l’empreinte, le commit source et la plateforme de construction. Distribue toutes les images nécessaires à la destination, dont celles des sandboxes et les dépendances amont. Un environnement hors ligne doit aussi prévoir paquets, téléchargements de navigateurs et accès aux modèles. Transférer une seule image ne rend pas le système autonome.

La CLI lit l’espace de noms des images Tale dans `GHCR_REGISTRY`. La version sélectionnée détermine toujours le tag. Publie donc les noms et tags attendus par le déploiement. Pour fixer séparément les images et commits source, consulte la [référence des déploiements gérés](https://docs.tale.dev/fr/self-hosted/install/cli-install#managed-deployments).

## Suivre les évolutions amont

Versionne tes changements et examine les évolutions amont avant de reconstruire. Conserve les versions ou empreintes des images de base avec le compte rendu de construction. Mets ces références à jour délibérément : reconstruire avec une référence inchangée ne récupère pas automatiquement une nouvelle version.

Avant le déploiement, vérifie rôle de démarrage, contrôles d’état, routes publiques et fonctionnalité modifiée. Pour une sandbox, teste une nouvelle session et ses appels réseau. Propose les correctifs d’intérêt général au projet amont lorsque possible pour réduire le code propre à ton fork.

## Diagnostiquer un échec

| Symptôme | Vérification suivante |
| --- | --- |
| Une source de `COPY` manque | Lance la construction depuis la racine avec le contexte prévu ; vérifie `.dockerignore` et le chemin source. |
| Le téléchargement d’un paquet ou d’une image échoue | Vérifie l’accès au registre, l’authentification et la première étape en échec. |
| L’image construite s’arrête au démarrage | Lis les journaux du conteneur et contrôle environnement, montages et rôle. |
| Une sandbox utilise encore d’anciens paquets | Vérifie l’image d’exécution configurée et crée une nouvelle session. Changer un tag ne remplace pas un conteneur existant. |

L’[architecture des conteneurs](https://docs.tale.dev/fr/self-hosted/operate/container-architecture) explique les dépendances ; [Mises à jour](https://docs.tale.dev/fr/self-hosted/operate/upgrades) couvre le déploiement et la restauration.

# Démarrer Tale depuis les sources
Source: https://docs.tale.dev/fr/develop/contributor-setup

Démarre Tale depuis les sources pour modifier le produit ou tester une contribution. L’application web et le backend tournent sur ta machine, avec les bases de données et les services sandbox dans Docker. Pour installer une version prête à l’emploi, suis le [démarrage auto-hébergé](https://docs.tale.dev/fr/self-hosted/install/quickstart).

## Préparer ta machine

Utilise un clone local du [dépôt Tale](https://github.com/tale-project/tale). Exécute les commandes suivantes à sa racine.

| Prérequis | Rôle | Vérification |
| --- | --- | --- |
| Version de Bun fixée dans le `package.json` à la racine | Workspaces, dépendances, Vite et scripts de développement | `bun --version` |
| Node.js 22.21.1 ou plus récent dans la branche 22.x | Backend de l’application ; l’image utilise 22.21.1 | `node --version` |
| Docker avec Compose | Bases applicative et documentaire, stockage objet et services sandbox | `docker info` et `docker compose version` |
| Ports locaux libres | Application sur 3000, backend sur 3005 | `bun run setup:check` |

Le dépôt fixe la version du gestionnaire de paquets. Utilise-la pour reproduire un problème ou modifier le lockfile ; la vérification de démarrage ne contrôle qu’une version minimale.

La vérification préalable contrôle Bun et les deux ports. Vérifie Node et Docker séparément : un résultat positif ne les valide pas. Le premier démarrage nécessite aussi un accès réseau pour télécharger les dépendances et les images. Un fournisseur de modèles est nécessaire pour obtenir de vraies réponses AI, mais pas pour te connecter et explorer l’application.

## Installer et démarrer

Installe les dépendances, vérifie les ports, puis démarre l’environnement :

```bash
bun install
bun run setup:check
bun run dev
```

Le script à la racine crée les secrets manquants dans le fichier `.env`, ignoré par Git, et conserve les valeurs existantes. Garde ce fichier privé et conserve-le entre les redémarrages : le backend et la sandbox doivent partager les mêmes secrets.

L’orchestrateur démarre les services Docker, lance le backend Node, attend ses routes API et d’authentification, puis démarre Vite. Si l’image d’exécution de la sandbox manque, par exemple au premier démarrage ou après la suppression des images locales, l’orchestrateur la construit depuis les sources avant de lancer le backend. Cette seule étape peut prendre plusieurs minutes ; les sessions d’agents et l’exécution de code restent indisponibles tant qu’elle n’est pas terminée. Le backend applique les migrations au démarrage. Attends le message `READY` avant d’ouvrir `http://localhost:3000` ; les téléchargements et la préparation initiale peuvent prolonger le premier démarrage.

<Check>

Ouvre l’application et connecte-toi. Le Dashboard confirme la liaison entre navigateur et backend. Envoie un message avec un fournisseur configuré pour vérifier aussi un appel au modèle.

</Check>

Arrête les processus au premier plan avec `Ctrl-C`. Les volumes Docker persistent ; l’arrêt ne supprime pas les données de l’instance.

## Se connecter au workspace local

L’initialisation de développement crée le compte `dev@tale.test`, le mot de passe `TaleDev!Passw0rd` et l’organisation **Dev Workspace**. Elle ne modifie pas un compte existant et ne fonctionne que si `SITE_URL` désigne une adresse de boucle locale.

Définis `TALE_DEV_SEED_USER=0` pour tester la première configuration. Pour une autre identité locale, fournis `TALE_DEV_SEED_USER_EMAIL` et `TALE_DEV_SEED_USER_PASSWORD` dans l’environnement. Modifier ces valeurs ne réinitialise pas le mot de passe d’un compte existant.

## Choisir les services à lancer

Pour travailler sur le produit, conserve `bun run dev`. Il démarre ensemble le backend et l’application avec leur configuration commune.

Si les services nécessaires tournent déjà avec les bons ports et identifiants, ignore uniquement leur démarrage Docker :

```bash
TALE_DEV_SKIP_DOCKER=1 bun run dev
```

Cette commande démarre toujours un backend local. Postgres, le stockage objet et la sandbox restent nécessaires. Consulte les [fichiers Compose de développement](https://docs.tale.dev/fr/develop/compose-files) pour tester une compilation complète en conteneurs.

Pour travailler uniquement sur le frontend avec un backend existant, lance Vite directement depuis `services/platform` et indique son adresse :

```bash
cd services/platform
TALE_BACKEND_URL=http://localhost:3005 bunx --bun vite --host 127.0.0.1 --port 3000
```

Cette commande ne démarre aucun service, ne crée aucun compte et n’applique aucune migration. Le backend doit déjà accepter l’origine du navigateur que tu utilises.

## Résoudre les problèmes de démarrage

| Symptôme | Vérification suivante |
| --- | --- |
| `node` est absent ou refuse une option | Installe la version Node indiquée et vérifie celle que trouve ton shell. |
| Docker ne se connecte pas | Démarre Docker et exécute `docker info` dans le même shell. |
| Le port 3000 ou 3005 est occupé | Identifie le processus avant de l’arrêter ; il peut appartenir à un autre clone. |
| Le backend échoue avant Vite | Lis la première erreur et vérifie la connexion à la base et ses identifiants. |
| La connexion fonctionne, mais pas le modèle | Vérifie l’identifiant du fournisseur, le modèle choisi et les services sandbox. |
| Tes changements apparaissent dans la mauvaise application | Vérifie l’URL et le clone auquel appartient le processus. |

Sur macOS ou Linux, identifie les processus à l’écoute :

```bash
lsof -nP -iTCP:3000 -sTCP:LISTEN
lsof -nP -iTCP:3005 -sTCP:LISTEN
```

Arrête un processus de développement connu depuis son terminal d’origine. N’arrête pas un processus uniquement parce qu’il occupe un port.

## Conserver ou réinitialiser les données locales

Les bases et fichiers téléversés persistent hors du clone. Un second worktree Git n’isole pas automatiquement les noms de services Docker, les ports, les volumes ou les identifiants `.env`. Donne à chaque instance ses propres services et sa propre configuration avant de les lancer en parallèle.

Une réinitialisation détruit les données de développement et peut toucher un autre clone qui utilise le même projet Compose. Inspecte les conteneurs et volumes du projet, sauvegarde ce qui compte et arrête les services avant de supprimer leur état. Les fichiers sous `TALE_CONFIG_DIR` sont indépendants : supprimer une base ne les réinitialise pas.

## Réutiliser les composants d’interface

Pour modifier une interface, commence par les [guides du design system](https://ui.tale.dev). Ils présentent `@tale/ui` pour l’application et `@tale/marketing-ui` pour les pages marketing, avec des exemples interactifs, des tokens et des modèles de mise en page. Cherche un composant existant dans ces packages avant d’en créer un. Ces guides sont en anglais.

## Vérifier une contribution

Lis `AGENTS.md` et `.agents/repo.md` avant de modifier le code. Exécute les vérifications adaptées pendant ton travail, puis la vérification commune depuis la racine :

```bash
bun run check
```

Elle couvre le formatage, le lint, les types et les tests automatisés. Le formatage Python utilise aussi `uvx` ; installe cet outil avant le passage complet. Vérifie également les comportements web dans un navigateur. Pour une modification de base de données, le contrat du dépôt exige le test d’intégration sur un vrai Postgres.

Mets à jour la documentation concernée et toutes les langues livrées avec ta modification. Pour les conteneurs, poursuis avec [Construire les images Docker](https://docs.tale.dev/fr/develop/contributing-docker) ; pour une intégration externe, commence par [Appeler Tale depuis un script](https://docs.tale.dev/fr/tutorials/developer/call-tale-from-a-script).

# Endpoint MCP
Source: https://docs.tale.dev/fr/develop/mcp-endpoint

Connecte un client MCP lorsqu'un agent doit découvrir les outils Tale, récupérer des connaissances ou concevoir et exécuter des automatisations. La connexion utilise la même clé API et le même périmètre d'organisation que [REST](https://docs.tale.dev/fr/develop/api-reference). Tale joue le rôle de serveur : ton client externe appelle Tale.

Commence par `initialize`, consulte `tools/list`, puis appelle `get_docs` avant d'écrire une automatisation. L'installation fournit sa propre grammaire prise en charge ; le client n'a donc pas à inventer des types de nœuds ou des champs.

## Connecter un client

### Préparer la connexion

Crée une [clé API](https://docs.tale.dev/fr/platform/admin/api-keys) et conserve-la dans la configuration sécurisée de ton client. La page **Paramètres > API > MCP** affiche le point d'accès, le slug d'organisation et une requête de découverte à copier.

| Paramètre | Valeur |
| --- | --- |
| Point d'accès | `https://your-host.example.com/api/v1/mcp` |
| Transport | HTTPS POST avec JSON-RPC ; réponses JSON simples |
| Autorisation | `Authorization: Bearer <api-key>` |
| Organisation | `X-Organization-Slug: <slug>` |
| Révisions du protocole | `2025-06-18`, ou `2025-03-26` si le client la propose |

Le client doit accepter un point d'accès HTTP distant avec des en-têtes personnalisés. Il n'y a ni flux SSE, ni session à supprimer, ni parcours d'autorisation OAuth. Les URL de découverte OAuth renvoient du JSON avec `404` ; un client qui exige ce parcours doit être configuré autrement. Un client limité aux serveurs stdio locaux ne peut pas utiliser directement cette URL. [Utiliser Tale depuis ton éditeur ou un script](https://docs.tale.dev/fr/develop/use-tale-from-your-editor) fournit des configurations prêtes pour opencode et Claude Code.

Envoie toujours l'en-tête d'organisation dans une intégration réutilisable. Il n'est facultatif que si le titulaire de la clé appartient à une seule organisation. Avec plusieurs appartenances, son absence produit `400 ORG_SLUG_REQUIRED`. Un slug inconnu produit `404 ORG_SLUG_INVALID`, et une organisation dont le titulaire n'est pas membre produit `403 ORG_FORBIDDEN`. Chacun de ces refus liste dans `data.organizations` les slugs que tu peux envoyer.

### Initialiser et récupérer la référence

Les exemples supposent que `TALE_URL`, `TALE_API_KEY` et `TALE_ORG_SLUG` sont déjà définis dans ton environnement. `TALE_URL` est l'origine de l'application, sans `/api/v1`.

```bash
curl --fail-with-body "$TALE_URL/api/v1/mcp" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"docs-client","version":"1.0.0"}}}'
```

Le serveur s'identifie comme `tale-platform`. Lis `result.protocolVersion` puis envoie la valeur négociée dans `MCP-Protocol-Version` lors des appels suivants. L'exemple ci-dessous utilise `2025-06-18` ; remplace-la si l'initialisation a négocié l'ancienne révision. Une valeur d'en-tête non prise en charge renvoie `400`.

```bash
curl --fail-with-body "$TALE_URL/api/v1/mcp" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG" \
  --header 'MCP-Protocol-Version: 2025-06-18' \
  --header 'Content-Type: application/json' \
  --data '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_docs","arguments":{}}}'
```

Un résultat `get_docs` réussi contient la référence des automatisations en texte et ne porte pas d'indicateur d'erreur. Pour consulter les schémas des outils, envoie plutôt `method: "tools/list"`. L'inventaire actuel compte 22 outils. Conserve l'`id` JSON-RPC pour associer chaque résultat à sa requête.

### Transport et lots

| Requête | Réponse |
| --- | --- |
| Un message JSON-RPC | Un résultat ou une erreur JSON-RPC |
| Lot de 20 messages au maximum | Tableau de réponses ; les notifications n'ont pas d'entrée de réponse |
| Notifications uniquement | HTTP `202` |
| `OPTIONS` | HTTP `204`, `Allow: POST, OPTIONS` ; aucune clé requise |
| Autre méthode HTTP | HTTP `405`, `Allow: POST, OPTIONS` |

Chaque appel d'outil supplémentaire d'un lot consomme le même budget qu'un appel séparé. Si le lot épuise son budget, l'entrée refusée contient JSON-RPC `-32000` avec `data.retryAfterMs`. La réponse HTTP reste `200`, sans `Retry-After`. Une requête unique refusée à l'entrée HTTP reçoit le `429` REST. Gère les deux cas selon les [limites de débit](https://docs.tale.dev/fr/develop/rate-limits).

Le point d'accès ne fournit pas d'en-têtes CORS pour utiliser une clé dans une page web. Conserve la clé sur un serveur de confiance ou dans le stockage d'identifiants du client MCP.

## Les outils

`tools/list` fournit le schéma d'entrée de chaque outil. Un argument manquant, vide, mal typé ou inattendu reçoit JSON-RPC `-32602` avant exécution. Le document passé à `validate_automation`, `run_automation`, `test_automation` ou `save_automation` garde volontairement une enveloppe ouverte : `get_docs` en explique la grammaire et le moteur valide son contenu.

Les outils exposent aussi `readOnlyHint`, `destructiveHint`, `idempotentHint` et `openWorldHint`. Un hôte peut s'en servir pour expliquer un appel, mais ces indications n'accordent aucun droit et ne garantissent pas sa sûreté. Les lectures sont marquées comme telles ; enregistrer écrit une version ; déployer ou modifier un déclencheur peut remplacer un état existant. Les exécutions réelles peuvent joindre de vrais services.

### Écriture

| Outil                 | Ce qu'il fait                                                        |
| --------------------- | -------------------------------------------------------------------- |
| `get_docs` | Lire la référence d'automatisation : grammaire, types de nœuds, nœuds de capacité et méthodes au format `tools/call`. |
| `get_catalog` | Lister les types de nœuds disponibles ; `kind` filtre le type, `compact: true` omet les schémas d'entrée. |
| `search_catalog`      | Chercher dans le catalogue de types de nœuds par mot-clé.            |
| `validate_automation` | Valider un document d'automatisation sans l'enregistrer.             |
| `run_automation` | Exécuter un document avec les mocks déterministes. |
| `test_automation`     | Lancer les tests d'acceptation propres à une automatisation.         |
| `save_automation`     | Enregistrer un document comme nouvelle version immuable.             |
| `get_automation`      | Lire une version enregistrée — la dernière sans précision, `version: "deployed"` pour celle qui est en ligne (`AUTOMATION_VERSION_UNKNOWN` tant que rien n’est déployé). |
| `list_automations`    | Les automatisations de l'organisation avec leur dernière version, leur version déployée et les projets où chacune est installée (`projectIds`). |
| `deploy_automation` | Déployer une version enregistrée pour les exécutions réelles. |

Suis cet ordre : lire la grammaire et le catalogue, valider le document, l'exécuter avec les mocks, lancer ses tests d'acceptation, enregistrer une version, puis la déployer. Un test simulé réussi vérifie le chemin simulé. Il ne valide ni les identifiants du fournisseur, ni le réseau, ni les effets réels.

### Gestion des exécutions & déclencheurs

| Outil            | Ce qu'il fait                                                                                                  |
| ---------------- | -------------------------------------------------------------------------------------------------------------- |
| `run_deployed` | Exécuter la version déployée et attendre jusqu'à 30 secondes sa sortie, sa trace et ses effets. Si elle continue, suivre le `runId` renvoyé. Prend le même `idempotencyKey` facultatif que `start_run`, dans le même registre que la porte REST : une répétition renvoie la première exécution avec `duplicate: true` et ne démarre rien, quelle que soit la porte qui l'a lancée. |
| `start_run` | Démarrer la version déployée en arrière-plan, puis suivre l'identifiant renvoyé avec `get_run`. Prend un `idempotencyKey` facultatif — l’`Idempotency-Key` de la porte REST, le même registre : la même clé avec les mêmes arguments répond la poignée de la première exécution avec `duplicate: true` et ne démarre rien, la même clé avec d’autres arguments est refusée (`IDEMPOTENCY_KEY_REUSED`). L’en-tête HTTP `Idempotency-Key` est refusé sur cet endpoint (**400**, `INVALID_HEADER`) : un lot porte jusqu’à 20 appels, la clé voyage donc dans les arguments de l’outil. |
| `list_runs` | Lister les exécutions accessibles d'une automatisation ou de plusieurs projets, les plus récentes d'abord, avec leur `projectId`. |
| `get_run` | Lire le statut, la sortie, la trace, les effets et le `projectId`. L'identifiant d'une exécution de projet s'utilise aussi dans `GET /api/v1/projects/{id}/runs/{runId}`. |
| `cancel_run` | Arrêter une exécution lors du prochain passage d'un nœud à l'autre. |
| `list_versions`  | L'historique de versions immuable d'une automatisation ; chaque ligne dit si elle est la version `deployed`, et `deployedVersion` la nomme à côté de la liste (`null` tant que rien n’est déployé).                                                        |
| `list_triggers` | Lire les déclencheurs sans révéler le secret du webhook. |
| `delete_trigger` | Supprimer le déclencheur ; conserver les versions et l'historique des exécutions. |
| `set_trigger` | Configurer un déclencheur planifié, webhook ou événement. Le `token` d’un webhook est répondu une fois, ici, et plus jamais — conserve-le ; `deployed` dit si les livraisons tourneront : un déclencheur lié à une automatisation sans version déployée est enregistré et ne déclenche rien tant qu’une version n’est pas déployée. |

| Outil | Quand le choisir |
| --- | --- |
| `run_automation` | Essayer un document non enregistré avec les mocks déterministes ; `mode: "live"` est refusé |
| `run_deployed` | Exécuter réellement la version déployée et attendre jusqu'à 30 secondes ; suivre ensuite le `runId` si elle continue |
| `start_run` | Démarrer la version déployée en arrière-plan puis suivre `get_run` ; passe `idempotencyKey` pour qu’une répétition soit sûre |

Les deux outils de version déployée utilisent le même moteur durable, avec les mêmes contrôles d'accès et traces d'exécution. `start_run` accepte un `projectId` facultatif. Une automatisation liée à des projets doit s'exécuter dans un projet où elle est installée ; une liaison unique peut être choisie automatiquement. Sans liaison, omettre le champ sélectionne le périmètre de l'organisation. Lis `projectIds` dans `list_automations` et le véritable `projectId` du résultat au lieu de deviner l'URL REST de suivi.

### Capacités & connaissances

| Outil                 | Ce qu'il fait                                                                                                                                      |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `search_capabilities` | Rechercher les automatisations déployées de l'organisation par nom et description. |
| `invoke_capability` | Appeler une capacité par son `id`. Si une approbation est nécessaire, renvoyer son état en attente au lieu d'exécuter l'action. |
| `get_knowledge` | Récupérer des passages des documents et sites web explorés de l'organisation. `corpus` vaut `private` (documents), `public-web` (pages explorées) ou `all` ; les orthographes REST `documents` et `web` sont acceptées aussi. `query` est plafonné à 2000 caractères. Chaque passage porte `text`, `source` (un titre), `ref`, `corpus`, `chunkIndex`, `score`, `similarity` quand la recherche dense l’a classé, `url` pour une page web et — pour un document — le `documentId` qu’attend `GET /api/v1/documents/{id}` (l’id du fichier pour un résultat de projet) ainsi que son `projectId` : la même citation que renvoie la recherche REST. |

Le registre de capacités contient actuellement les automatisations déployées. Il n'inclut ni outils intégrés, ni actions de connecteurs, ni skills, ni serveurs MCP externes. Appeler une automatisation déployée correspond à la même opération réelle que `run_deployed`. Si une approbation est nécessaire, le résultat `pending` permet au client d'expliquer qu'une personne doit décider avant la poursuite.

## Ce que la clé peut faire

| Opération | Accès nécessaire |
| --- | --- |
| Lectures, validation, simulations et tests d'acceptation, recherche de capacités, récupération de connaissances | Appartenance à l'organisation, puis règles habituelles de la ressource |
| Enregistrer, déployer, définir/supprimer un déclencheur, annuler ou exécuter réellement | Capacité développeur, puis règles habituelles de la ressource |

La clé identifie son titulaire ; elle n'élargit ni son rôle ni son accès aux projets. Les appels réels via `invoke_capability` passent aussi par les contrôles d'exécution.

Avant de configurer des outils privilégiés, lis `GET /api/v1/me` : `capabilities.developer` indique le droit lié au rôle actuel. `deploymentEditor` correspond à une liste opérateur distincte et n’autorise pas la création par MCP. Les erreurs d’outils gardent le format MCP décrit ci-dessous ; la lecture d’une capacité REST ne change pas leur traitement JSON-RPC.

### Distinguer une erreur de protocole d'un refus d'outil

| Résultat | Traitement |
| --- | --- |
| JSON-RPC `-32601` | Corriger la méthode inconnue |
| JSON-RPC `-32602` | Corriger le nom de l'outil ou ses arguments à partir de `tools/list` ; une valeur hors d’un ensemble énuméré est refusée et le message nomme l’ensemble |
| Résultat avec `isError: true` | Lire le `code` stable, l'`error` explicative et le `hint` dans le texte ; `data` peut détailler les champs invalides |
| `validate_automation` avec `valid: false` | Verdict normal de validation ; examiner `errors`, même si `isError` reste false |
| Capacité avec `pending` | Résultat normal d'approbation ; ni une fin d'exécution, ni un échec à relancer |
| Capacité avec `refused` | Résultat d'erreur ; corriger la cause indiquée |

Les codes de refus comprennent `AUTOMATION_NOT_FOUND`, `AUTOMATION_VERSION_UNKNOWN`, `AUTOMATION_NOT_DEPLOYED`, `RUN_NOT_FOUND`, `AUTOMATION_INVALID`, `AUTOMATION_TESTS_FAILING`, `LIVE_MODE_UNAVAILABLE` et `NOT_SUPPORTED`. Ce dernier indique que l'hôte ne prend pas en charge l'opération sur les exécutions, versions ou déclencheurs. `start_run` refuse un `idempotencyKey` réutilisé avec d’autres arguments par `IDEMPOTENCY_KEY_REUSED` ; `invoke_capability` refuse un id que le registre ne tient pas — une automatisation seulement enregistrée n’y est pas — par `CAPABILITY_NOT_FOUND` et une entrée que son schéma rejette par `CAPABILITY_INPUT_INVALID` ; `get_knowledge` transmet les codes propres de la porte des connaissances (`KNOWLEDGE_UNAVAILABLE` quand la recherche elle-même a échoué). Les erreurs de plateforme conservent leur code, leur conseil et leurs données éventuelles ; par exemple, l'absence d'accès développeur renvoie `FORBIDDEN_DEVELOPER_SETTINGS`.

Un nom d'automatisation inconnu est aussi une erreur pour `list_versions`, `list_runs` et `list_triggers`. Une liste vide signifie qu'une automatisation existante n'a pas d'éléments correspondants. La seule exception est l’historique des exécutions : une automatisation supprimée conserve ses exécutions, `list_runs {name}` les renvoie donc tant qu’elles existent, et seul un nom qui n’a jamais tourné donne `AUTOMATION_NOT_FOUND`. `get_catalog` restreint à un type de nœud de base (`transform`, `llm`, `agent`, `subautomation`) répond une liste vide accompagnée d’un `hint` renvoyant à `get_docs`, comme le fait `search_catalog`. Un document invalide soumis à un outil qui exige un document valide, une recherche échouée ou un déploiement absent produisent `isError: true`. Seul l'outil de validation présente un document invalide comme son verdict normal.

## Où ça se place

REST et MCP partagent les clés, le périmètre d'organisation et les objets d'exécution durables. Choisis REST pour des routes HTTP explicites, et MCP pour un client capable de découvrir et d'appeler des outils. Tale n'enregistre ni n'appelle de serveurs MCP externes par ce point d'accès.

# Développer avec Tale
Source: https://docs.tale.dev/fr/develop/overview

Ces guides t’aident à écrire un client, à connecter un système externe ou à modifier Tale. Commence par une requête simple qui fonctionne, puis ajoute l’authentification, le périmètre d’accès et la gestion des erreurs nécessaires à ton intégration.

## Choisir une tâche de développement

| Ton objectif | Guide |
| --- | --- |
| Écrire un script qui envoie un message et lit la réponse | [Appeler Tale depuis un script](https://docs.tale.dev/fr/tutorials/developer/call-tale-from-a-script) |
| Construire un client pour les projets, tâches, fichiers ou autres ressources | [Référence de l’API](https://docs.tale.dev/fr/develop/api-reference) |
| Connecter un client MCP | [Point d’accès MCP](https://docs.tale.dev/fr/develop/mcp-endpoint) |
| Une aide IA dans ton éditeur, avec les connaissances ou les modèles de Tale | [Utiliser Tale depuis ton éditeur ou un script](https://docs.tale.dev/fr/develop/use-tale-from-your-editor) |
| Déclencher une automatisation depuis un autre système | [Webhooks](https://docs.tale.dev/fr/develop/webhooks) |
| Accéder aux documents avec un client de système de fichiers | [API WebDAV](https://docs.tale.dev/fr/develop/webdav-api) |
| Développer un Connector | [Développement de Connectors](https://docs.tale.dev/fr/develop/connectors) |
| Modifier le code applicatif de Tale | [Configurer l’environnement de développement](https://docs.tale.dev/fr/develop/contributor-setup) |

## Fiabiliser la première requête

Choisis l’identifiant adapté à la surface : REST, MCP et les endpoints de modèles utilisent des clés API, WebDAV un mot de passe d’application et un webhook une URL secrète de déclencheur. Ces identifiants ne sont pas interchangeables.

Crée une clé API distincte pour chaque intégration. Envoie-la uniquement à l’instance prévue et ne la conserve pas dans le dépôt de code. [Effectuer ta première requête API](https://docs.tale.dev/fr/get-started/developers) explique les URL d’instance et le contexte d’organisation. Pour une opération longue, distingue l’acceptation de la requête de son résultat : consulte la ressource ou l’exécution et traite aussi les échecs.

Lis les [limites de requêtes](https://docs.tale.dev/fr/develop/rate-limits) avant d’ajouter des tentatives automatiques. En cas de problème de connexion, vérifie la [disponibilité de l’instance](https://docs.tale.dev/fr/develop/status-page). La référence de l’API décrit le format des erreurs et la spécification générée pour la version actuelle du code.

## Développer dans la plateforme

Pour les agents, les projets et l’éditeur d’automatisations, consulte le [guide développeur](https://docs.tale.dev/fr/platform/developer/overview). Le guide du [développement assisté par IA](https://docs.tale.dev/fr/develop/ai-assisted-development) explique comment associer les outils de création à la validation et à la revue.

<Video src="https://docs.tale.dev/videos/fr/tutorials/ep10-developers/ep10-developers.fr.mp4" poster="https://docs.tale.dev/videos/fr/tutorials/ep10-developers/ep10-developers.fr.webp" captions="https://docs.tale.dev/videos/fr/tutorials/ep10-developers/ep10-developers.fr.vtt" lang="fr" title="Bonus — Tale pour les développeurs" caption="Bonus — Tale pour les développeurs (2:04)">

</Video>

# Gérer les limites de requêtes
Source: https://docs.tale.dev/fr/develop/rate-limits

Tale limite le trafic API par détenteur de clé. Toutes les clés d’une même personne partagent son budget. Compte donc l’ensemble des intégrations et processus de suivi utilisant cette identité, plutôt que chaque clé séparément.

Les limites ci-dessous décrivent le backend actuel. Un proxy de l’opérateur ou un fournisseur en aval peut ajouter ses propres limites.

## Les budgets

Un seau de jetons se remplit en continu jusqu’à sa capacité de rafale. Une courte série peut utiliser cette réserve ; le débit soutenu doit rester inférieur au rythme de remplissage.

| Trafic | Débit soutenu | Rafale | Budget attribué à |
| --- | --- | --- | --- |
| Appels généraux `/api/v1`, MCP et endpoints de modèles compris | 120/minute | 200 | Détenteur de la clé |
| Démarrages d’exécution, messages au modèle et démarrages de tâche | 20/minute | 40 | Détenteur de la clé |
| Autorisation de téléversement et rattachement de fichier au projet | 240/minute | 300 | Détenteur de la clé |
| Authentification par clé API échouée | 20/minute | 40 | IP source |
| Livraisons webhook avant validation du jeton | 120/minute | 240 | Adresse de l’expéditeur |
| Livraisons à un déclencheur webhook vérifié | 20/minute | 40 | Déclencheur |

Les appels REST d’exécution et de téléversement consomment aussi le budget général. Un fichier de projet nécessite par exemple une autorisation de téléversement puis un rattachement. Chacun de ces appels compte dans les deux budgets. Le budget de téléversement plus large ne contourne pas la limite générale.

L’exécution comprend les démarrages d’automatisation avec ou sans projet, les messages de fil et les démarrages explicites de tâche. La création ou mise à jour d’une tâche consomme aussi ce budget si `runWorkflowSlug` est fourni. Une requête qui démarre du travail est facturée une fois que son corps et ses en-têtes ont passé les vérifications propres de la porte — un `400 INVALID_BODY` ou `INVALID_HEADER` ne coûte rien — et avant que quoi que ce soit soit cherché, si bien qu’un `404` pour un fil, une tâche ou une automatisation que tu ne peux pas voir coûte un jeton, comme un `409` que l’état répond. Certaines mutations, comme les commentaires de tâche ou les changements de dossier, ont des limites supplémentaires partagées avec l’application.

Dans un lot MCP, les appels d’outil supplémentaires consomment du budget supplémentaire. Le [point d’accès MCP](https://docs.tale.dev/fr/develop/mcp-endpoint) distingue une réponse HTTP `429` d’un message refusé à l’intérieur du lot. Les webhooks ont des budgets séparés ; les limites de l’expéditeur et du déclencheur doivent toutes deux permettre la livraison.

Les appels aux [endpoints de modèles](https://docs.tale.dev/fr/develop/api-reference#model-endpoints) sous `/api/v1/openai` et `/api/v1/anthropic` ne comptent que dans le budget général, pour une requête chacun, en flux ou non ; ce qu’un appel peut dépenser est plafonné à part par les règles de budget. Une personne, et chaque clé API, peuvent en outre avoir huit de ces appels en cours en même temps : un neuvième reçoit `429` avec le `code` `MODEL_API_CONCURRENCY_EXCEEDED` et `Retry-After: 2`.

Le budget d’exécution limite la vitesse d’acceptation des messages, pas le nombre de tours simultanés. Les messages acceptés partagent une file entre toutes les organisations et les clés de l’instance. Chaque lot traite au maximum `WORKER_CONCURRENCY` tours, 5 par défaut ; le suivant attend la fin du lot en cours. Un envoi accepté peut donc attendre derrière d’autres clients. L’API n’expose ni position dans la file ni heure de démarrage estimée.

## La réponse 429

Un refus HTTP pour dépassement de limite indique `Retry-After` en secondes entières. Le corps JSON exprime la même attente en millisecondes. Cet exemple impose au moins deux secondes de pause :

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json

{
  "error": "Too many requests — retry after 1500 ms",
  "code": "RATE_LIMITED",
  "requestId": "example-request-id",
  "data": {"retryAfterMs": 1500}
}
```

Branche ta logique sur `code`. `error` décrit l’attente dans une phrase et `requestId` identifie la requête pour une investigation. Ce format est celui de REST. Les refus de débit de `/api/app` et des webhooks conservent le code machine dans `error` ; ne traite donc pas ce texte comme un format commun aux interfaces. Tale ne fournit pas de compteur de budget restant : mesure ton trafic et respecte l’attente indiquée.

1. Arrête la boucle de relance immédiate.
2. Attends au moins `Retry-After`. Si plusieurs processus partagent l’identité, coordonne leur pause.
3. Si les refus continuent, augmente le délai exponentiellement avec une borne et une variation aléatoire. Par exemple, passe d’une à soixante secondes en respectant toujours une attente serveur plus longue.
4. Conserve la clé d’idempotence initiale pour les opérations qui la prennent en charge. Un timeout au démarrage peut survenir après l’acceptation du travail.

Un plafond de dépenses répond aussi par `429`, avec le `code` `BUDGET_EXCEEDED` : une règle de budget qui s’applique au propriétaire de la clé — la sienne, celle d’une équipe, de l’organisation ou de la clé API — est atteinte. Attendre quelques secondes ne suffit pas. `Retry-After` indique le temps restant avant la réinitialisation de la période, et `data` décrit le plafond : `scope`, `period`, `limitCode`, `used`, `limit` et `resetsAt` en millisecondes epoch. Rien n’est mis en file d’attente ; suspends le travail jusqu’à `resetsAt` ou demande à un administrateur de relever la limite dans [Politiques et limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits). Sur les endpoints de modèles, les deux `429` arrivent au format d’erreur d’OpenAI ou d’Anthropic, avec le même `code` et `Retry-After`. Un budget épuisé y nomme son plafond dans le message plutôt que dans `data` et porte `x-should-retry: false`, pour que les SDK des fournisseurs ne réessaient pas d’eux-mêmes.

Les autres réponses `4xx` nécessitent généralement une correction de requête, d’identifiants ou de droits. Ne traite pas tout échec comme une limite ; consulte le [modèle d’erreur](https://docs.tale.dev/fr/develop/api-reference#modele-derreur).

## Planifier le suivi et les relances

Une réponse `304` après vérification d’`ETag` compte toujours comme une requête. Elle économise des octets, pas du budget. Suivre une exécution toutes les cinq secondes consomme douze lectures par minute avant les relances et les autres opérations. Réserve de la capacité pour ces appels supplémentaires.

Demande uniquement les champs nécessaires, comme `?fields=status,finishedAt` pour une exécution. Espace les lectures lorsqu’une décision humaine est attendue et arrête-les une fois l’exécution terminée. [Démarrer puis suivre une exécution](https://docs.tale.dev/fr/develop/api-reference#demarrer-une-execution-puis-la-suivre) explique les états et les démarrages idempotents.

Pour les imports importants, utilise les opérations groupées prises en charge, telles que `POST /api/v1/contacts/bulk`, et répartis les lots dans le temps. Créer d’autres clés pour la même personne n’augmente pas le budget. Si un traitement nécessite sa propre identité de service, prépare-la par le processus habituel de comptes et de permissions. Changer de clé n’est pas une stratégie de relance.

# Vérifier la disponibilité de l’instance
Source: https://docs.tale.dev/fr/develop/status-page

Ouvre `/status` sur ton hôte Tale pour vérifier la disponibilité sans te connecter. Les outils de supervision lisent le même résumé sur `/status.json`. Il couvre le backend et les stockages du déploiement, sans garantir chaque modèle ni chaque connexion propre à une organisation.

## Interroger le document de statut

Définis `TALE_BASE_URL` avec l’URL de l’instance, puis demande son statut :

```bash
curl --fail-with-body --silent --show-error \
  "$TALE_BASE_URL/status.json"
```

Examine le contenu JSON, pas seulement le statut HTTP. Lors de la vérification locale avec un stockage objet indisponible, l’endpoint a renvoyé HTTP `200` et ce résultat dégradé :

```json
{
  "status": "degraded",
  "checkedAt": "2026-09-14T04:31:20.847Z",
  "components": [
    { "id": "backend", "status": "operational" },
    { "id": "database", "status": "operational" },
    { "id": "object-store", "status": "outage" }
  ]
}
```

L’application répond et atteint sa base, mais les opérations sur les fichiers demandent une investigation. Une supervision qui considère tout HTTP `200` comme sain manquerait cette panne.

## Interpréter les composantes

| Champ ou composante | Signification |
| --- | --- |
| `status: operational` | Toutes les composantes signalées sont disponibles. |
| `status: degraded` | Certaines sont indisponibles. |
| `status: outage` | Toutes sont indisponibles. |
| `checkedAt` | Heure du contrôle en UTC. |
| `backend` | Accessibilité du backend applicatif. |
| `database` | État combiné de la base applicative et de la base documentaire du déploiement. |
| `object-store` | État du stockage de fichiers du déploiement. |

Les composantes indiquent `operational` ou `outage`. Si le backend ne répond pas, l’état des stockages qui en dépendent ne peut pas être établi ; ils apparaissent aussi indisponibles. Accepte les nouveaux IDs de composantes sans casser ton analyseur.

## Configurer la supervision

Pour un contrôle automatique, installe `jq` et fais porter le verdict par le code de sortie. Cet exemple échoue en cas d’erreur réseau, de JSON invalide ou d’état global différent de `operational` :

```bash
set -o pipefail
curl --fail-with-body --silent --show-error --max-time 10 \
  "$TALE_BASE_URL/status.json" | jq -e '.status == "operational"'
```


L’endpoint JSON ne demande aucune clé API et ne consomme pas son budget. Le résultat reste en cache cinq secondes ; les sondes de stockage se rafraîchissent séparément. Chaque lecture ne déclenche donc pas une nouvelle transaction de contrôle. Définis un délai de requête et alerte sur des échecs répétés ou un état dégradé selon les besoins du service.

`/status.json` autorise les lectures depuis d’autres origines avec `Access-Control-Allow-Origin: *`. `HEAD` renvoie les en-têtes sans corps et `OPTIONS` annonce `GET, HEAD, OPTIONS`. Utilise `GET` pour examiner le verdict des composantes.

## Distinguer réponse du processus et disponibilité réelle

L’endpoint `/api/health` du serveur web de production vérifie le processus à faible coût. Il convient aux sondes de conteneur, mais ne remplace pas les contrôles de dépendances. Le serveur Vite de développement peut router ce chemin autrement et renvoyer `404` ; utilise `/status.json` pour l’application locale.

En production, `/health` vérifie uniquement le proxy frontal : celui-ci répond lui-même `OK`, même pendant un redémarrage de l’application. Une route inconnue comme `/healthz` peut renvoyer la page de l’application avec HTTP `200`. Aucune des deux ne vérifie sa disponibilité réelle. Choisis `/status.json` ou `/api/health` selon ce que ta sonde doit établir.

Un statut sain ne vérifie ni le crédit, ni les droits, ni la disponibilité d’un modèle externe. Il n’exécute pas non plus un téléversement, une recherche, un chat ou une automatisation complets. Ajoute un test contrôlé de bout en bout pour l’opération dont dépend ton intégration.

## Examiner un échec

Pour une composante dégradée, le [dépannage](https://docs.tale.dev/fr/self-hosted/operate/observability/troubleshooting) indique les logs concernés. Pour un appel API en échec alors que l’instance est saine, lis le [code d’erreur API](https://docs.tale.dev/fr/develop/api-reference). `429` signale une [limite de débit](https://docs.tale.dev/fr/develop/rate-limits), pas un verdict de panne de l’instance.

Les instances Cloud exposent les mêmes chemins sur leur propre hôte. Les communications d’incident et documents d’assurance sont décrits dans [Confiance et conformité](https://docs.tale.dev/fr/cloud/trust-and-compliance).

# Utiliser Tale depuis ton éditeur ou un script
Source: https://docs.tale.dev/fr/develop/use-tale-from-your-editor

Tale s’intègre à ton travail de développement de quatre façons. Elles diffèrent par le modèle de langage qui répond et par la part du travail que Tale encadre :

| Tu veux | Voie | Modèle | Ce que Tale encadre |
| --- | --- | --- | --- |
| Les modèles de ton organisation comme fournisseur de modèles d’opencode, de Claude Code ou d’un script SDK | [Les endpoints de modèles](https://docs.tale.dev/fr/develop/use-tale-from-your-editor#model-endpoints) | Un modèle de l’organisation que tu nommes par son identifiant dans chaque requête | Chaque appel au modèle : accès aux modèles, garde-fous d’entrée, budgets, consommation à ton nom et à celui de ta clé ; pas les réponses |
| Interroger l’assistant de l’espace de travail depuis un script | [L’API REST de chat](https://docs.tale.dev/fr/develop/use-tale-from-your-editor#interroger-le-chat-rest-depuis-un-script) | Un modèle de l’organisation que tu nommes dans chaque requête | Tout le tour : accès aux modèles, budgets, consommation à ton nom |
| Les connaissances et les outils d’automatisation de Tale dans opencode ou Claude Code | [L’endpoint MCP](https://docs.tale.dev/fr/develop/use-tale-from-your-editor#connecter-opencode-ou-claude-code) | Le modèle configuré dans ton éditeur | Seulement les appels d’outils ; les appels au modèle de l’éditeur échappent à Tale |
| Faire modifier un script avec les modèles de ton organisation | [Un agent de projet sur une tâche](https://docs.tale.dev/fr/develop/use-tale-from-your-editor#confier-tes-scripts-a-un-agent-de-projet) | Le modèle de l’organisation configuré sur l’agent | Toute l’exécution : sandbox, budgets, consommation, revue |

Un éditeur peut en combiner deux avec la même clé : les endpoints de modèles comme fournisseur de modèles et l’endpoint MCP pour les connaissances de Tale. [La dernière section](https://docs.tale.dev/fr/develop/use-tale-from-your-editor#ce-qui-remplace-le-point-dacces-compatible-openai) explique en quoi les endpoints de modèles diffèrent de la couche compatible OpenAI de Tale 0.3.

## Créer une clé API

Tout accès depuis l’extérieur de l’application commence par une clé API personnelle. Les propriétaires, admins et développeurs la créent dans **Paramètres > API > REST** avec **Créer une clé API**, en choisissant un nom et une expiration ; un membre à qui un admin a attribué une compétence qui s’utilise avec une clé, comme **Appeler les modèles par l'API**, le peut aussi. La valeur secrète ne s’affiche qu’une fois : copie-la dans ton gestionnaire de secrets ou un environnement de shell privé avant de fermer la boîte de dialogue. [Clés API](https://docs.tale.dev/fr/platform/admin/api-keys) décrit la création, le renouvellement et la révocation.

Une clé agit en ton nom. Elle porte ton rôle et tes accès aux projets actuels, et la consommation qu’elle entraîne t’est attribuée. Les tours de chat, les appels aux modèles et les exécutions d’automatisation que tu lances avec la clé enregistrent aussi la clé, si bien que les limites de clé API s’y appliquent également ; une exécution d’agent de projet n’est attribuée qu’à toi. Un admin peut plafonner tes dépenses avec un budget personnel, d’équipe ou de rôle dans [Politiques et limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits) ; une requête qui dépasse un plafond est refusée avec `429 BUDGET_EXCEEDED`.

Les exemples de cette page lisent trois variables d’environnement. `TALE_URL` est l’origine de ton instance, sans `/api/v1`. `TALE_ORG_SLUG` est le slug de l’organisation, affiché dans **Paramètres > API > MCP**, dans **Paramètres > API > Modèles** une fois les endpoints de modèles activés, et renvoyé par `GET /api/v1/me`. Exporte les trois dans ton shell, et ne mets `TALE_API_KEY` dans aucun fichier que tu versionnes.

## Utiliser les modèles de ton organisation depuis tes outils {#model-endpoints}

Les endpoints de modèles permettent à opencode, à Claude Code et aux scripts écrits avec les SDK OpenAI ou Anthropic d’utiliser les modèles approuvés par ton organisation comme fournisseur de modèles. Tale parle les interfaces OpenAI Chat Completions et Anthropic Messages que ces outils utilisent déjà : tu changes une URL de base, une clé et un nom de modèle, pas ton code. Chaque requête est un simple appel au modèle : ni l’assistant de l’espace de travail, ni un fil, ni un outil de Tale n’interviennent, et la réponse revient telle que le modèle l’a envoyée.

### Avant de commencer

Les endpoints restent désactivés tant qu’un admin n’a pas activé **Endpoints de modèles pour les clés API** dans **Paramètres > Gouvernance > Modèles** ; [Modèles](https://docs.tale.dev/fr/platform/admin/governance/content-models#model-endpoints) décrit ce réglage. Les propriétaires, admins et développeurs peuvent ensuite les appeler grâce à leur rôle ; tout autre membre a besoin de la compétence **Appeler les modèles par l'API**, qu’un admin attribue dans [Compétences](https://docs.tale.dev/fr/platform/admin/governance/competences). `GET /api/v1/me` répond `capabilities.modelApi: true` dès que ta clé peut les appeler.

**Paramètres > API > Modèles** rassemble ce dont tes outils ont besoin : les deux URL de base, le slug de l’organisation, les modèles que tu peux appeler avec un bouton de copie pour chaque identifiant, et des configurations à copier pour opencode, Claude Code et le SDK OpenAI pour Python. Tant que ton organisation n’a pas activé les endpoints, l’onglet affiche **Les endpoints de modèles ne sont pas activés pour ton organisation**, et les propriétaires et les admins y trouvent **Ouvrir l'accès aux modèles**.

<Frame caption="Paramètres > API > Modèles — les URL de base, le slug de l’organisation et les modèles que tu peux appeler.">

![L’onglet Modèles sous Paramètres > API avec les URL de base compatibles OpenAI et Anthropic, l’en-tête Authorization pour une clé API, le slug d’organisation northlight-labs et cinq identifiants de modèles, chacun avec un bouton de copie.](https://docs.tale.dev/images/develop/settings-api-models.webp)

</Frame>

### Paramètres de connexion

| Réglage | Valeur |
| --- | --- |
| URL de base compatible OpenAI | `https://<host>/api/v1/openai` ; les SDK OpenAI et opencode ajoutent `/chat/completions` |
| URL de base compatible Anthropic | `https://<host>/api/v1/anthropic` ; les SDK Anthropic et Claude Code ajoutent `/v1/messages` |
| Clé | Ta clé API personnelle, en `Authorization: Bearer <key>`. Tale refuse l’en-tête `x-api-key` avec `401` : un client Anthropic doit donc envoyer la clé comme jeton d’authentification |
| Organisation | `X-Organization-Slug: <slug>`, obligatoire quand tu appartiens à plusieurs organisations |
| Modèle | `<providerSlug>/<modelId>` : le slug du fournisseur, une barre oblique et l’identifiant du modèle dans le catalogue de ce fournisseur, par exemple `openrouter/anthropic/claude-sonnet-4.6` ou `deepseek/deepseek-v4-flash` |

Le même identifiant vaut pour les deux endpoints. Vérifie la clé et liste les identifiants que tu peux appeler, avec ton hôte et ton slug à la place de `tale.example.com` et `acme` :

```bash
curl https://tale.example.com/api/v1/openai/models \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: acme"
```

La réponse est une liste de modèles au format OpenAI : `owned_by` est le slug du fournisseur, et `created` vaut toujours `0`. Elle ressemble à ceci, avec les identifiants que ton organisation te propose :

```json
{
  "object": "list",
  "data": [
    { "id": "openrouter/anthropic/claude-sonnet-4.6", "object": "model", "created": 0, "owned_by": "openrouter" },
    { "id": "deepseek/deepseek-v4-flash", "object": "model", "created": 0, "owned_by": "deepseek" }
  ]
}
```

La liste contient les modèles de chat de ton organisation que servent des identifiants de fournisseur de type **Clé API** ou **Variable d'environnement**, restreints par les modèles autorisés de chaque identifiant et par ton accès aux modèles. Les modèles servis par des identifiants d’abonnement n’y figurent pas, pas plus que ceux d’un fournisseur dont l’adresse est définie pour chaque identifiant, comme Azure, ni les modèles qui n’appellent des tools que via l’API Responses d’OpenAI, comme GPT-6.1 Sol, car ces endpoints ne les relaient pas. `GET /api/v1/models` donne pour chacun de ces modèles sa fenêtre de contexte, ses capacités et ses prix, sous les mêmes `providerSlug` et `id`.

### Brancher opencode sur Tale

Ajoute Tale comme fournisseur dans ton `opencode.json` global ou dans celui du projet. opencode le joint par son paquet compatible OpenAI et lit la clé dans `TALE_API_KEY`. Liste sous `models` chaque modèle que tu veux pouvoir choisir, sous son identifiant ; `model` définit le modèle par défaut, sous la forme `tale/` suivi de cet identifiant.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "tale": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Tale",
      "options": {
        "baseURL": "https://tale.example.com/api/v1/openai",
        "apiKey": "{env:TALE_API_KEY}",
        "headers": { "X-Organization-Slug": "acme" }
      },
      "models": {
        "openrouter/anthropic/claude-sonnet-4.6": { "name": "Claude Sonnet 4.6" }
      }
    }
  },
  "model": "tale/openrouter/anthropic/claude-sonnet-4.6"
}
```

Le bloc `provider` peut côtoyer le bloc `mcp` de la [configuration MCP](https://docs.tale.dev/fr/develop/use-tale-from-your-editor#opencode) dans le même fichier. Lance opencode depuis un shell où `TALE_API_KEY` est définie.

### Brancher Claude Code sur Tale

Claude Code lit son fournisseur de modèles dans des variables d’environnement. Définis-les dans le shell depuis lequel tu le lances :

```bash
export ANTHROPIC_BASE_URL="https://tale.example.com/api/v1/anthropic"
export ANTHROPIC_AUTH_TOKEN="$TALE_API_KEY"
export ANTHROPIC_CUSTOM_HEADERS="X-Organization-Slug: acme"
export ANTHROPIC_MODEL="openrouter/anthropic/claude-sonnet-4.6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="openrouter/anthropic/claude-haiku-4.5"
unset ANTHROPIC_API_KEY
claude
```

`ANTHROPIC_AUTH_TOKEN` envoie la clé comme jeton Bearer. Laisse `ANTHROPIC_API_KEY` non définie : Claude Code l’enverrait en `x-api-key`, un en-tête que Tale refuse. `ANTHROPIC_DEFAULT_HAIKU_MODEL` est le modèle que Claude Code utilise pour ses tâches de fond ; les deux variables de modèle doivent nommer des identifiants de ta liste. L’outil WebSearch de Claude Code fait exécuter la recherche par le fournisseur du modèle lui-même : Tale refuse donc ces requêtes. Les outils que Claude Code exécute sur ta machine fonctionnent normalement.

### Appeler les modèles depuis un script

Le SDK OpenAI pour Python a besoin d’une autre URL de base et de l’en-tête d’organisation. Cet exemple lit la clé dans `TALE_API_KEY`, demande une réponse complète, puis en reçoit une seconde en flux :

```python
import os

from openai import OpenAI

client = OpenAI(
    base_url="https://tale.example.com/api/v1/openai",
    api_key=os.environ["TALE_API_KEY"],
    default_headers={"X-Organization-Slug": "acme"},
)
MODEL = "openrouter/anthropic/claude-sonnet-4.6"

reply = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "Que signifie l’expression cron 0 3 * * 1 ?"}],
)
print(reply.choices[0].message.content)

stream = client.chat.completions.create(
    model=MODEL,
    messages=[{"role": "user", "content": "Écris un message de commit pour la correction d’une coquille."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)
print()
```

Les outils, `tool_calls` et les images fonctionnent comme avec OpenAI, et le `model` de la réponse est l’identifiant que tu as envoyé. Un flux se termine par `data: [DONE]` ; son dernier fragment, qui porte la consommation, n’arrive que si tu passes `stream_options={"include_usage": True}`.

Le SDK Anthropic pour Python prend la clé comme jeton d’authentification. Exécute-le avec `ANTHROPIC_API_KEY` non définie, car le SDK enverrait la valeur de cette variable en `x-api-key`, un en-tête que Tale refuse :

```python
import os

import anthropic

client = anthropic.Anthropic(
    base_url="https://tale.example.com/api/v1/anthropic",
    auth_token=os.environ["TALE_API_KEY"],
    default_headers={"X-Organization-Slug": "acme"},
)

message = client.messages.create(
    model="openrouter/anthropic/claude-sonnet-4.6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explique l’erreur ECONNRESET en un paragraphe."}],
)
print(message.content[0].text)
```

### Ce que Tale vérifie à chaque appel

Chaque appel est encadré comme une requête de chat, pour la personne dont la clé l’a envoyé :

- **L’interrupteur et ton droit.** L’organisation a activé les endpoints, et ton rôle ou ta compétence t’autorise à les appeler.
- **Le modèle.** Il doit figurer dans ta liste, et l’accès aux modèles de l’organisation doit te l’autoriser au moment de l’appel. Les modèles autorisés des identifiants du fournisseur s’appliquent aussi.
- **Ce que le modèle sait lire.** Les images exigent un modèle capable de lire des images, et les outils un modèle qui les accepte. Les images passent en parties OpenAI `image_url` avec une URL `data:` ou `https:`, ou en blocs Anthropic `image` en base64 ou avec une URL `https:`, y compris dans les résultats d’outils. Les documents passent en parties OpenAI `file` ou en blocs Anthropic `document`.
- **Les garde-fous d’entrée.** La sécurité du contenu, la protection PII et le fournisseur de modération de l’organisation lisent chaque texte de la requête avant sa transmission : les instructions système et développeur, tes tours et ceux de l’assistant, les appels d’outils, leurs résultats et les définitions d’outils, ainsi que les documents fournis en texte. Un blocage refuse la requête, un masquage envoie au modèle le texte masqué. Ne sont pas filtrés : les réponses du modèle, ainsi que les images et les documents qui ne sont pas du texte. Les détails se trouvent dans [Garde-fous](https://docs.tale.dev/fr/platform/admin/governance/guardrails#model-endpoints).
- **Les budgets.** Avant l’appel, Tale calcule le pire cas, l’estimation du prompt plus la sortie maximale possible, au prix catalogue du modèle. Si ce pire cas ne tient pas dans ce qui reste sous un plafond de budget qui s’applique à toi, à tes équipes, à l’organisation ou à la clé, Tale refuse l’appel avec `429 BUDGET_EXCEEDED` ; sinon, il le réserve sur ces plafonds tant que l’appel tourne. Un `max_tokens` plus bas passe plus facilement. Ensuite, Tale impute à ton nom et à la clé le coût mesuré par la passerelle de modèles et les tokens déclarés. Un appel que tu interromps pendant que Tale le vérifie encore n’est ni transmis ni imputé. Si tu l’interromps une fois transmis, Tale annule aussi sa requête au fournisseur, et l’appel est quand même imputé : au moins pour son prompt et la sortie qui t’était déjà parvenue, au prix catalogue du modèle. Chaque appel compte pour une requête et apparaît comme **Appel API direct** dans l’analyse de l’usage.
- **Huit appels à la fois.** Toi et chacune de tes clés pouvez avoir huit appels en cours en même temps. Un neuvième est refusé avec `429 MODEL_API_CONCURRENCY_EXCEEDED` et un `Retry-After` de deux secondes.

Tes outils ne voient jamais de clé de fournisseur. Tale relaie chaque appel par sa passerelle de modèles, avec une clé créée pour cette seule requête et ce seul modèle. Révoquer ta clé API dans **Paramètres > API > REST** met fin à son accès dès la requête suivante ; une réponse déjà en cours de flux se termine.

### Ce que les endpoints ne servent pas

- **Les outils que le fournisseur du modèle exécute lui-même.** `web_search_options` d’OpenAI et tout outil dont le type n’est ni `function` ni `custom`, ainsi que la recherche web, la récupération web, l’exécution de code et les ensembles d’outils MCP d’Anthropic, avec les champs `mcp_servers` et `container`, sont refusés avec `400 MODEL_API_VENDOR_TOOL_UNSUPPORTED` : Tale ne pourrait ni les mesurer ni les auditer. Tes propres outils sont relayés et reviennent en `tool_calls` ou `tool_use`, y compris les outils client `bash`, `text_editor`, `computer` et `memory` d’Anthropic.
- **L’audio en entrée.** Les requêtes avec des parties `input_audio` sont refusées.
- **Les requêtes que Tale ne peut ni facturer ni garder dans ton organisation.** Plus de huit réponses par requête (`n`), les fichiers stockés dans le compte du fournisseur (un `file_id` OpenAI, une source Anthropic de type `file`), un `service_tier` autre que `auto` ou `default` (`auto` ou `standard_only` chez Anthropic), la sortie audio et `store: true` sont refusés avec `400 INVALID_BODY`.
- **Les autres routes.** `count_tokens` et toutes les autres routes d’Anthropic ne sont pas servies, pas plus que les routes OpenAI au-delà des chat completions et de la liste des modèles, comme les embeddings, Responses ou la génération d’images.
- **L’assistant et les outils de Tale.** Pour eux, utilise [l’API REST de chat](https://docs.tale.dev/fr/develop/use-tale-from-your-editor#interroger-le-chat-rest-depuis-un-script) ou [l’endpoint MCP](https://docs.tale.dev/fr/develop/use-tale-from-your-editor#connecter-opencode-ou-claude-code).

### Diagnostiquer un appel refusé

Chaque refus arrive dans le format d’erreur de l’interface appelée, si bien que ton SDK le signale comme une erreur OpenAI ou Anthropic. Son champ `code` porte le code stable de Tale ; la [référence de l’API](https://docs.tale.dev/fr/develop/api-reference#model-endpoints) les liste tous.

| Statut et code | Que faire |
| --- | --- |
| `401 UNAUTHORIZED` | Envoie la clé en `Authorization: Bearer`, jamais en `x-api-key`. Pour Claude Code, définis `ANTHROPIC_AUTH_TOKEN` et retire `ANTHROPIC_API_KEY` ; pour les SDK Anthropic, passe la clé en `auth_token` ou `authToken`. Une clé révoquée ou expirée répond aussi `401`. |
| `400 ORG_SLUG_REQUIRED` | Tu appartiens à plusieurs organisations. Envoie `X-Organization-Slug`. |
| `403 MODEL_API_DISABLED` | L’organisation n’a pas activé les endpoints. Adresse-toi à un admin. |
| `403 MODEL_API_FORBIDDEN` | Ton rôle ne peut pas les appeler. Demande à un admin de t’attribuer **Appeler les modèles par l'API**. |
| `404 MODEL_API_MODEL_UNKNOWN` | L’identifiant ne figure pas dans ta liste. Copie-en un depuis `GET /api/v1/openai/models` ou l’onglet **Modèles**, slug du fournisseur compris. |
| `403 MODEL_API_MODEL_FORBIDDEN` | L’accès aux modèles bloque ce modèle pour toi. Choisis-en un autre ou adresse-toi à un admin. |
| `400 MODEL_API_VISION_UNSUPPORTED`, `400 MODEL_API_TOOLS_UNSUPPORTED` | Choisis un modèle qui lit les images ou accepte les outils, ou envoie la requête sans eux. |
| `400 MODEL_API_VENDOR_TOOL_UNSUPPORTED` | Retire l’outil que le fournisseur exécuterait lui-même, comme une recherche web. Dans Claude Code, c’est l’outil WebSearch qui provoque ce refus. |
| `400 MODEL_API_GUARDRAIL_BLOCKED` | Un garde-fou a refusé le prompt système ou un message, et rien n’a atteint le modèle. Reformule, ou interroge un admin sur la règle. |
| `403 MODEL_API_GUARDRAIL_UNSUPPORTED` | La protection PII de l’organisation tokenise, ce que les endpoints de modèles ne peuvent pas respecter. Un admin peut la passer en masquage ou en blocage. |
| `429 RATE_LIMITED` | Tu as envoyé plus de requêtes que le budget partagé de tes clés API ne le permet. Attends la durée de `Retry-After` ; voir [les limites de débit](https://docs.tale.dev/fr/develop/rate-limits). |
| `429 BUDGET_EXCEEDED` | Un plafond de budget est atteint. `Retry-After` indique le temps restant avant sa réinitialisation, et la réponse porte `x-should-retry: false` pour que les SDK ne réessaient pas d’eux-mêmes. Attends, ou demande à un admin de relever le plafond. |
| `503 MODEL_API_UNAVAILABLE`, `503 MODEL_API_GUARDRAIL_UNAVAILABLE` | Un service nécessaire à l’appel est indisponible, comme la passerelle de modèles ou le fournisseur de modération. Réessaie plus tard ; si le problème persiste, demande à un admin de vérifier les identifiants du fournisseur ou le fournisseur de modération. |
| `MODEL_API_UPSTREAM_ERROR` | Le fournisseur du modèle a refusé l’appel, et le message vient de lui. `400`, `413`, `422`, `429`, `503` et `529` gardent leur statut ; tout autre refus arrive en `502`. |

## Interroger le chat REST depuis un script

L’API REST de chat donne à un script le même assistant que celui du chat de l’application. Ce n’est pas un appel direct au modèle : chaque tour passe par l’assistant intégré de l’espace de travail, qui cherche dans les connaissances de ton organisation quand la question le demande et renvoie vers les tâches toute demande de document ou d’autre livrable. L’API est asynchrone. Un envoi répond `202` avec l’identifiant de la réponse, puis tu interroges l’état jusqu’à la fin du tour.

Les exemples partagent une fonction qui envoie la clé et l’en-tête d’organisation à chaque requête. Enregistre-la sous `tale-api.sh` :

```bash
# tale-api.sh : à charger avec source depuis ton shell ou depuis un script
: "${TALE_URL:?Définis TALE_URL sur l’origine de Tale, sans /api/v1}"
: "${TALE_API_KEY:?Définis TALE_API_KEY}"
: "${TALE_ORG_SLUG:?Définis TALE_ORG_SLUG}"
tale_api() {
  curl --fail-with-body -sS \
    -H "Authorization: Bearer $TALE_API_KEY" \
    -H "X-Organization-Slug: $TALE_ORG_SLUG" \
    -H 'Content-Type: application/json' "$@"
}
```

Charge-la dans ton shell, vérifie la clé et liste les modèles que tu peux appeler. Les exemples ont besoin de curl et de `jq`.

```bash
source ./tale-api.sh

# Au nom de qui la clé agit, et dans quelle organisation
tale_api "$TALE_URL/api/v1/me" | jq '{email: .user.email, organization: .organization.slug, role: .organization.role}'

# Les modèles que tu peux nommer : id et providerSlug
tale_api "$TALE_URL/api/v1/models" | jq -r '.models[] | "\(.id)\t\(.providerSlug)"'
```

Exporte `MODEL_ID` et `PROVIDER` d’après une ligne de cette liste. La conversation est un script, `ask-tale.sh`, enregistré à côté de la fonction et lancé avec `bash ask-tale.sh`. Il crée un fil personnel, pose une question, attend la fin du tour et affiche le texte de la réponse. `set -euo pipefail` l’arrête à la première requête en échec, si bien qu’il ne continue jamais avec un identifiant vide.

```bash
#!/usr/bin/env bash
set -euo pipefail
source "$(dirname "$0")/tale-api.sh"
: "${MODEL_ID:?Définis MODEL_ID sur un id de /models}"
: "${PROVIDER:?Définis PROVIDER sur le providerSlug indiqué avec lui}"

THREAD_ID=$(tale_api -X POST "$TALE_URL/api/v1/threads" -d '{"title":"Aide pour un script"}' | jq -er '.id')

BODY=$(jq -n --arg model "$MODEL_ID" --arg provider "$PROVIDER" \
  '{content: "Que dit notre runbook sur la rotation des mots de passe de base de données ?", model: $model, providerSlug: $provider}')
MESSAGE_ID=$(tale_api -X POST "$TALE_URL/api/v1/threads/$THREAD_ID/messages" -d "$BODY" | jq -er '.messageId')

# Interroger toutes les trois secondes, jusqu’à dix minutes, jusqu’à la fin du tour
STATUS=queued
for _ in $(seq 200); do
  STATUS=$(tale_api "$TALE_URL/api/v1/threads/$THREAD_ID/generation" | jq -r '.status')
  [ "$STATUS" = idle ] && break
  sleep 3
done
if [ "$STATUS" != idle ]; then
  echo "Aucune réponse en dix minutes ; arrêt du tour." >&2
  tale_api -X DELETE "$TALE_URL/api/v1/threads/$THREAD_ID/generation" > /dev/null
  exit 1
fi

# Lire la réponse annoncée par l’envoi, puis vérifier comment elle s’est terminée
REPLY=$(tale_api "$TALE_URL/api/v1/threads/$THREAD_ID/messages/$MESSAGE_ID")
if [ "$(jq -r '.status' <<< "$REPLY")" != complete ]; then
  jq -r '"Turn \(.status): \(.errorCode // "") \(.error // "")"' <<< "$REPLY" >&2
  exit 1
fi
if [ "$(jq -r '.finishReason // ""' <<< "$REPLY")" = length ]; then
  echo "La réponse a atteint sa limite de sortie et peut être tronquée." >&2
fi
jq -r '[.parts[] | select(.type == "text") | .text] | join("")' <<< "$REPLY"
```

Tant que l’envoi attend un worker, `GET .../messages/$MESSAGE_ID` peut encore répondre `404 MESSAGE_NOT_FOUND` ; le script ne lit donc la réponse qu’une fois le fil au repos. Un tour qui n’est pas terminé au bout de dix minutes est arrêté avec `DELETE .../generation`. Envoie les questions suivantes au même `THREAD_ID` pour garder le contexte de la conversation. L’envoi n’accepte que du texte, et il est refusé avec `409 CHAT_TURN_IN_PROGRESS` tant que le tour précédent du fil tourne encore.

Quand un script a besoin des passages correspondants plutôt que d’une réponse, `POST /api/v1/knowledge/search` les renvoie sans passer par l’assistant ; voir [Rechercher dans les fichiers d’un projet](https://docs.tale.dev/fr/develop/api-reference#rechercher-dans-les-fichiers-dun-projet). [Appeler Tale depuis un script](https://docs.tale.dev/fr/tutorials/developer/call-tale-from-a-script) construit la même conversation en Python avec la gestion des erreurs, et [Envoyer un message, puis suivre le tour](https://docs.tale.dev/fr/develop/api-reference#envoyer-un-message-puis-suivre-le-tour) couvre les nouvelles tentatives, les limites de jetons et les échecs.

## Utiliser les outils de Tale dans opencode ou Claude Code {#connecter-opencode-ou-claude-code}

L’[endpoint MCP](https://docs.tale.dev/fr/develop/mcp-endpoint) de Tale, `/api/v1/mcp`, met les outils de Tale à la disposition d’un agent d’éditeur. Le plus utile pour travailler sur des scripts est `get_knowledge`, qui récupère des passages dans les documents et les pages web explorées de ton organisation. L’endpoint expose aussi les outils d’automatisation : valider, tester, enregistrer, déployer et exécuter des automatisations, puis lire leurs exécutions. L’enregistrement, le déploiement, la définition ou la suppression d’un déclencheur, l’annulation d’une exécution et les exécutions réelles exigent la capacité développeur. Il n’y a ni outil de chat ni outil de skills ; pour copier les skills de ton organisation dans un dossier local, lis-les avec `GET /api/v1/skills` comme l’explique [Enregistrer et synchroniser les bundles de skills](https://docs.tale.dev/fr/develop/api-reference#enregistrer-et-synchroniser-les-bundles-de-skills).

Sur cette voie, le modèle de langage est celui configuré dans ton éditeur. Tale authentifie les appels d’outils et leur applique tes droits, mais les prompts, ton code et chaque passage renvoyé par un outil de Tale partent chez le fournisseur de modèle de cet éditeur. Si ce fournisseur est un autre service, les budgets, le suivi de consommation et les règles d’accès aux modèles de Tale ne s’appliquent pas à ses appels ; vérifie avant de te connecter que ton organisation autorise l’envoi de ses connaissances à ce fournisseur. Si l’éditeur utilise [les endpoints de modèles](https://docs.tale.dev/fr/develop/use-tale-from-your-editor#model-endpoints) comme fournisseur, les passages ne vont qu’à des modèles approuvés par ton organisation, et chaque appel au modèle est encadré comme décrit plus haut.

L’endpoint s’authentifie avec la clé API dans un en-tête et ne propose pas de connexion OAuth. Désactive la détection OAuth d’un client lorsqu’il le permet.

### opencode

Ajoute un serveur distant dans ta configuration globale d’opencode, `~/.config/opencode/opencode.json`, ou dans un `opencode.json` du projet. Avec `{env:TALE_API_KEY}`, opencode lit la clé dans ton environnement, si bien que le fichier ne contient jamais le secret. Remplace l’hôte et le slug par les tiens.

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "tale": {
      "type": "remote",
      "url": "https://your-host.example.com/api/v1/mcp",
      "oauth": false,
      "timeout": 60000,
      "headers": {
        "Authorization": "Bearer {env:TALE_API_KEY}",
        "X-Organization-Slug": "your-org-slug"
      }
    }
  }
}
```

`timeout` relève le délai par défaut d’opencode pour les requêtes MCP, cinq secondes, qu’une recherche de connaissances sous charge ou un appel à `run_deployed`, qui attend jusqu’à 30 secondes, peut dépasser. Lance opencode depuis un shell où `TALE_API_KEY` est définie. `opencode mcp list` indique si le serveur est configuré ; opencode préfixe les outils du nom du serveur, comme dans `tale_get_knowledge`.

### Claude Code

Enregistre l’endpoint comme serveur HTTP. La commande ci-dessous stocke la clé développée dans ta configuration privée de Claude Code pour le projet en cours :

```bash
claude mcp add --transport http tale "$TALE_URL/api/v1/mcp" \
  --header "Authorization: Bearer $TALE_API_KEY" \
  --header "X-Organization-Slug: $TALE_ORG_SLUG"
```

Pour partager le serveur avec une équipe dans un `.mcp.json` versionné, fais référence à la clé par une variable d’environnement afin que chacun fournisse la sienne :

```json
{
  "mcpServers": {
    "tale": {
      "type": "http",
      "url": "https://your-host.example.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${TALE_API_KEY}",
        "X-Organization-Slug": "your-org-slug"
      }
    }
  }
}
```

`claude mcp list` indique si Claude Code joint le serveur.

## Confier tes scripts à un agent de projet

Pour que la modification se fasse dans Tale, dans une sandbox et avec la revue d’une personne, confie le script à un [agent de projet](https://docs.tale.dev/fr/platform/projects/project-agents). Tale exécute alors un environnement de code comme OpenCode dans une sandbox, avec le modèle configuré sur l’agent. L’exécution compte dans les budgets du membre qui l’a démarrée et lui est attribuée ; une exécution que tu lances en REST t’est imputée, pas à la clé API. Les fichiers modifiés reviennent comme résultats de la tâche, qui attend ensuite la revue d’une personne. [Choisir un environnement d’agent](https://docs.tale.dev/fr/platform/agents/harnesses) compare les environnements ; OpenCode passe uniquement par la passerelle de modèles de Tale et ne reçoit donc jamais de clé de fournisseur.

Pour créer l’agent, il te faut le droit de modifier le projet, donc au moins le rôle Éditeur ; toute personne qui peut ouvrir le projet peut ensuite créer la tâche et y démarrer l’agent. L’organisation doit disposer d’un modèle utilisable par l’environnement et de capacité de sandbox libre. Dans l’application, ouvre l’onglet **Agents** du projet, choisis **Nouvel agent**, sélectionne OpenCode comme harness et un modèle, puis crée une tâche avec le script en pièce jointe, affecte-la à l’agent et démarre-le.

La même boucle fonctionne en REST depuis un terminal, avec `tale-api.sh` de l’exemple de chat. Vérifie d’abord que ce déploiement exécute OpenCode pour les agents de projet :

```bash
tale_api "$TALE_URL/api/v1/models" | jq -r '.harnesses[] | "\(.harness)\t\(.label)"'
```

Enregistre ensuite le script ci-dessous sous `hand-to-agent.sh` à côté de la fonction et lance-le avec `bash hand-to-agent.sh`. Il réutilise l’agent Assistant scripts du projet ou le crée au premier lancement, car les noms d’agents sont uniques dans un projet, sans tenir compte de la casse. Il dépose ensuite le script comme tâche et met l’agent au travail avec un commentaire qui le mentionne.

```bash
#!/usr/bin/env bash
set -euo pipefail
source "$(dirname "$0")/tale-api.sh"
: "${PROJECT_ID:?Définis PROJECT_ID sur un projet que tu peux modifier}"
: "${MODEL_ID:?Définis MODEL_ID sur un modèle utilisable par l’environnement}"
: "${PROVIDER:?Définis PROVIDER sur le providerSlug indiqué avec lui}"
AGENT_NAME="Assistant scripts"

AGENT_ID=$(tale_api "$TALE_URL/api/v1/projects/$PROJECT_ID/agents" \
  | jq -r --arg name "$AGENT_NAME" 'first(.agents[] | select((.name | ascii_downcase) == ($name | ascii_downcase)) | .id) // ""')
if [ -z "$AGENT_ID" ]; then
  AGENT_ID=$(tale_api -X POST "$TALE_URL/api/v1/projects/$PROJECT_ID/agents" \
    -d "$(jq -n --arg name "$AGENT_NAME" --arg model "$MODEL_ID" --arg provider "$PROVIDER" '{name: $name, harness: "opencode", model: $model, modelProvider: $provider, skills: [], connectors: [], instructions: "Modifie le script de la description de la tâche. Renvoie le script modifié sous forme de fichier et liste chaque modification dans ton compte rendu."}')" \
    | jq -er '.agent.id')
fi

TASK_ID=$(tale_api -X POST "$TALE_URL/api/v1/projects/$PROJECT_ID/tasks" \
  -d "$(jq -n --rawfile script backup.ps1 '{externalSystem: "terminal", externalId: "backup-ps1-hardening", title: "Fiabiliser backup.ps1", description: ("Ajoute la gestion des erreurs et une option de simulation à ce script PowerShell :\n\n" + $script)}')" \
  | jq -er '.task.id')

tale_api -X POST "$TALE_URL/api/v1/projects/$PROJECT_ID/tasks/$TASK_ID/comments" \
  -d "$(jq -n --arg agent "$AGENT_ID" '{body: ("@" + $agent + " prends cette tâche, s’il te plaît.")}')" > /dev/null
echo "TASK_ID=$TASK_ID"
```

`externalSystem` et `externalId` rendent la tâche idempotente : un nouvel envoi de la même paire renvoie la tâche existante. Une description contient jusqu’à 20 000 caractères ; pour un script plus long, charge-le dans le projet comme l’explique [Charger un fichier en deux étapes](https://docs.tale.dev/fr/develop/api-reference#charger-un-fichier-en-deux-etapes). Un agent répond à son identifiant et à son nom en minuscules, les espaces remplacés par des points ou supprimés ; `@assistant.scripts` fonctionne donc aussi.

La mention affecte la tâche à l’agent et démarre une exécution ; la tâche passe à `in_progress`. Une mention qui ne peut pas démarrer d’exécution reste un simple commentaire, sans message d’erreur, par exemple quand tu ne peux pas modifier la tâche, que l’automatisation des tâches est désactivée ou qu’une autre exécution occupe déjà la tâche. Définis `TASK_ID` sur la valeur affichée par le script, vérifie la tâche, puis lis le compte rendu de l’agent une fois la tâche arrivée à `in_review` :

```bash
tale_api "$TALE_URL/api/v1/projects/$PROJECT_ID/tasks/$TASK_ID" | jq -r '.task.status'
tale_api "$TALE_URL/api/v1/projects/$PROJECT_ID/tasks/$TASK_ID/comments?limit=20" \
  | jq -r '.comments[] | select(.authorType == "agent") | .body'
```

Examine les fichiers modifiés dans les résultats de la tâche, dans l’application, avant de valider la tâche. Pour renvoyer l’agent au travail avec des corrections, publie un nouveau commentaire qui le mentionne.

## Ce qui a changé depuis Tale 0.3 {#ce-qui-remplace-le-point-dacces-compatible-openai}

De la 0.2.10 à la 0.3, Tale proposait une couche compatible OpenAI : `POST /api/v1/chat/completions`, `POST /api/v1/images/generations` et un `GET /api/v1/models` au format OpenAI, dont le champ `model` pouvait désigner un agent. Tale 0.4 a reconstruit la plateforme sans elle. Les [endpoints de modèles](https://docs.tale.dev/fr/develop/use-tale-from-your-editor#model-endpoints) prennent sa place pour les appels aux modèles, avec des différences qu’un client écrit pour la 0.3 doit suivre :

- L’URL de base est `/api/v1/openai`, ou `/api/v1/anthropic` pour un client Anthropic, et non `/api/v1`. Un SDK OpenAI pointé sur `/api/v1` reçoit toujours `404 NOT_FOUND` pour les chat completions, et `GET /api/v1/models` renvoie la liste propre à Tale, avec les modèles et les environnements d’agents, pas le format OpenAI.
- `model` désigne un modèle sous la forme `<providerSlug>/<modelId>`, jamais un agent. Pour l’assistant de l’espace de travail, utilise l’API REST de chat ; pour faire travailler un agent, un agent de projet.
- La génération d’images n’est pas servie.
- Les endpoints restent désactivés tant qu’un admin ne les a pas activés, et chaque appel passe par l’accès aux modèles, les garde-fous d’entrée et les budgets.

[Mettre à niveau et rétablir un déploiement](https://docs.tale.dev/fr/self-hosted/operate/upgrades#03-04-lapi-compatible-openai-a-ete-retiree) signale ce retrait aux opérateurs qui quittent la 0.3.

# API WebDAV
Source: https://docs.tale.dev/fr/develop/webdav-api

Utilise WebDAV lorsqu'un client de fichiers a besoin de dossiers, de téléchargements, d'envois et de verrous d'édition sur HTTP. Le point d'accès expose le centre de documents de l'organisation ; les fichiers des projets restent hors de cette arborescence. Pour Finder, l'Explorateur de fichiers ou un autre client existant, commence par [Configurer WebDAV](https://docs.tale.dev/fr/platform/connectors/webdav).

Cette référence s'adresse aux développeurs de clients. Vérifie d'abord une lecture de dossier authentifiée, puis l'envoi d'un petit fichier. Une réponse `207` confirme l'accès ; retrouver exactement les mêmes octets au téléchargement confirme aussi le chemin de stockage.

## Schéma d’URL

| Chemin | Accès | Contenu |
| --- | --- | --- |
| `/dav/<orgSlug>/documents/<path>` | Lecture et écriture | Documents et dossiers actifs du centre de documents |
| `/dav/<orgSlug>/.trash/<path>` | Lecture seule | Documents dans la corbeille |
| `/dav/<orgSlug>/` | Lecture seule | Les deux collections ci-dessus |

Encode chaque segment séparément. L'analyseur normalise Unicode en NFC et retire les espaces en début et fin de nom. Il refuse les noms vides, `.` et `..`, `/`, `\`, les caractères de contrôle et les noms de plus de 255 unités de code UTF-16. Il ne s'agit donc pas d'une limite de 255 octets. Le slug d'organisation respecte `[a-zA-Z0-9_-]{1,64}`. Un segment `.` ou `..` dans la ligne de requête, brut ou encodé (`%2e%2e`, `.%2e`), est refusé avec `404` avant le routage et n'est jamais résolu vers le dossier parent. Une barre oblique inverse brute compte comme séparateur de segment pour ce contrôle (`a\..\x` se lit comme `a/../x`) ; encodée (`%5C`), c'est un caractère de nom ordinaire, refusé.

Ajoute une barre oblique finale aux dossiers, mais pas aux fichiers. Les réponses renvoient des URL canoniques. Pour accéder à un élément existant, reprends son `href` au lieu de le reconstruire à partir du nom affiché, surtout si plusieurs documents d'un dossier portent le même titre.

## Authentification

Génère un mot de passe d'application dans **Paramètres > API > WebDAV** avec un compte autorisé à accéder aux paramètres développeur. Le mot de passe complet n'apparaît qu'une fois. Donne un libellé distinct à chaque client pour pouvoir révoquer son accès séparément.

| Champ | Valeur |
| --- | --- |
| Schéma HTTP | Basic |
| Nom d'utilisateur | L'adresse e-mail de ton compte ; le serveur accepte toute valeur non vide |
| Mot de passe | Le mot de passe d'application WebDAV généré |
| Organisation | Le slug dans l'URL, vérifié avec l'appartenance actuelle |

Le mot de passe d'application identifie l'utilisateur. Le mot de passe du compte et les clés API REST ne sont pas acceptés. Un mot de passe valide ne remplace pas l'appartenance à l'organisation : si tu n'en es plus membre, la réponse est `403`. Seul `OPTIONS` est accessible sans authentification.

### Vérifier une lecture de dossier

Renseigne l'URL de ton installation et ton e-mail ci-dessous. Chaque commande `curl --user` demande le mot de passe d'application de manière interactive, sans l'inscrire dans la commande ni dans l'historique du terminal.

```bash
export TALE_DAV_URL="https://your-host.example.com/dav/acme/documents"
export TALE_DAV_USER="you@example.com"

curl --user "$TALE_DAV_USER" --request PROPFIND \
  --header 'Depth: 1' "$TALE_DAV_URL/"
```

La réponse attendue est `207 Multi-Status`, avec du XML décrivant la collection et ses enfants directs. Même un dossier vide possède son propre bloc de réponse. Lis le résultat comme du XML, et non du JSON ; un `207` ne garantit pas la réussite de chaque statut qu'il contient.

### Vérifier un envoi et un téléchargement

Choisis un nom de dossier encore inutilisé pour préserver les fichiers existants. Ces commandes créent un dossier, envoient un petit fichier texte puis le téléchargent :

```bash
curl --user "$TALE_DAV_USER" --request MKCOL "$TALE_DAV_URL/Client%20test/"
printf 'Hello from WebDAV.\n' > webdav-test.txt
curl --user "$TALE_DAV_USER" --upload-file webdav-test.txt \
  --header 'Content-Type: text/plain' "$TALE_DAV_URL/Client%20test/webdav-test.txt"
curl --user "$TALE_DAV_USER" "$TALE_DAV_URL/Client%20test/webdav-test.txt"
```

Les réponses attendues sont `201` pour le dossier, `201` pour le fichier, puis le texte `Hello from WebDAV.` au téléchargement. Un envoi sur un fichier existant remplace son contenu et renvoie `204`. Le fichier apparaît aussi dans le centre de documents sans synchronisation supplémentaire.

## Méthodes

Toutes les méthodes sauf `OPTIONS` exigent le mot de passe d'application.

| Méthode | Rôle | Réponse réussie |
| --- | --- | --- |
| `OPTIONS` | Découvrir les capacités et les méthodes autorisées sur la cible | `200`, `DAV: 1, 2`, `Allow` |
| `PROPFIND` | Lire les propriétés ; `Depth: 0` pour la cible seule, `Depth: 1` avec ses enfants directs | `207` en XML |
| `PROPPATCH` | Soumettre des modifications de propriétés ; voir les limites de persistance ci-dessous | `207`, avec un statut par propriété |
| `GET`, `HEAD` | Télécharger un fichier ou lire ses en-têtes | `200` ; les requêtes conditionnelles et par plage peuvent modifier le statut |
| `PUT` | Créer ou remplacer un fichier | `201` créé, `204` remplacé |
| `DELETE` | Mettre les documents à la corbeille ; traiter récursivement un dossier et supprimer ses lignes de dossiers | `204` |
| `MKCOL` | Créer un dossier sous un parent existant | `201` |
| `MOVE` | Renommer ou déplacer un document ou un dossier | `201` nouvelle destination, `204` remplacement |
| `COPY` | Copier côté serveur un document ou une arborescence ; les copies de fichiers partagent les octets stockés | `201` nouvelle destination, `204` remplacement |
| `LOCK` | Obtenir ou renouveler un verrou d'écriture | `200`, avec un jeton de verrou |
| `UNLOCK` | Libérer un verrou appartenant à l'utilisateur appelant | `204` |

`GET` sur un dossier renvoie `405` : utilise `PROPFIND`. Sans en-tête `Depth`, la valeur est `1` ; `Depth: infinity` est refusé avec `403`. Le corps de `MKCOL` doit être vide. `PUT` exige `Content-Length` : envoie un fichier de taille connue plutôt qu'un transfert chunked.

`MOVE` et `COPY` utilisent `Destination` et respectent `Overwrite: T/F` ainsi que `If`. La destination doit rester sur le même hôte et dans la même organisation. Un parent absent produit `409` ; `Overwrite: F` vers une destination existante produit `412`. Le déplacement d'un document est atomique ; celui d'un dossier change son parent. Les opérations destructives respectent aussi les gels juridiques et les restrictions des documents contrôlés.

`Allow` décrit la cible : l'arbre de documents annonce toutes les méthodes ci-dessus, un fichier de la corbeille `OPTIONS, GET, HEAD, PROPFIND`, et la corbeille ou la racine de l'organisation `OPTIONS, PROPFIND`. Une sonde sur un chemin encore impossible à analyser reçoit la liste complète pour découvrir le service. Windows reçoit aussi `MS-Author-Via: DAV` et `Microsoft-Server-WebDAV-Extensions: 1`.

## Propriétés

| Propriété DAV | Signification |
| --- | --- |
| `resourcetype` | `<collection/>` pour un dossier, vide pour un fichier |
| `displayname` | Nom du dossier ou titre du document |
| `getlastmodified` | Horodatage RFC 1123 ; modification de la source, sinon création |
| `creationdate` | Date de création en ISO 8601 |
| `getcontenttype` | Type MIME du fichier |
| `getcontentlength` | Taille du fichier en octets |
| `getetag` | Le même validateur que dans `GET` et `HEAD` |
| `supportedlock` | Prise en charge des verrous d'écriture exclusifs |
| `lockdiscovery` | Informations disponibles sur les verrous actifs |

Les propriétés de fichier ne s'appliquent pas aux collections. L'ETag est le hachage du contenu entre guillemets lorsqu'il existe, sinon un validateur faible fondé sur la taille et la date de modification, par exemple `W/"42-1789373842855"`. Conserve les guillemets et le préfixe `W/`. Ne le remplace pas par l'ID du document et ne déduis pas une égalité octet par octet d'un validateur faible. `GET` accepte les requêtes conditionnelles et les plages d'octets.

<Warning>

Les propriétés personnalisées ne sont pas conservées. Un `PROPPATCH` ne contenant que des propriétés mortes reçoit un `200` par propriété pour la compatibilité des clients, mais une lecture ultérieure ne retrouve pas ces valeurs. Une propriété active protégée reçoit `403` ; les propriétés mortes de la même requête reçoivent alors `424 Failed Dependency`. N'y stocke pas de métadonnées métier.

</Warning>

## Sémantique des verrous

Utilise un verrou d'écriture exclusif et conserve son jeton `opaquelocktoken:<uuid>`. C'est le mode annoncé par le serveur. L'analyseur accepte aussi une portée partagée, mais le stockage n'autorise qu'un verrou actif par ressource. Ne fonde donc pas une édition simultanée sur les verrous partagés.

| Action du client | Requête nécessaire |
| --- | --- |
| Acquérir | `LOCK` avec un corps XML de verrou d'écriture et `Timeout: Second-N` |
| Écrire sous verrou | Ajouter `If: (<opaquelocktoken:...>)` |
| Renouveler | `LOCK` avec un corps vide et le même jeton `If` |
| Libérer | Envoyer `UNLOCK` avec `Lock-Token: <opaquelocktoken:...>` en tant que propriétaire |

La durée est bornée entre 1 et 3600 secondes. Renouvelle le verrou avant son expiration si l'édition dure plus longtemps. Une écriture protégée sans jeton reçoit `423` ; un jeton incorrect ou inconnu lors du renouvellement reçoit `412`. Un verrou peut couvrir les descendants : celui d'un dossier parent peut donc bloquer une écriture en dessous.

Les verrous sont stockés dans Postgres et nettoyés à la demande après expiration. Un verrou expiré ne protège plus la ressource, même si sa ligne existe encore. Révoquer un mot de passe d'application supprime immédiatement ses verrous. Cela permet aussi de débloquer un client qui a disparu pendant une édition, mais déconnecte tous les montages utilisant ce mot de passe.

## Codes de statut

| Statut | Signification et action |
| --- | --- |
| `200`, `201`, `204` | Lecture, création ou modification réussie ; voir le tableau des méthodes |
| `207` | Examiner chaque résultat de ressource ou de propriété dans le XML |
| `400` | Corriger un en-tête `Destination`, `If`, `Lock-Token` ou `Timeout` mal formé |
| `401` | Fournir un mot de passe d'application valide et non révoqué avec Basic |
| `403` | Vérifier appartenance, zone en lecture seule, règles de conservation/document, profondeur, propriétaire et destination |
| `404` | Vérifier le `href` reçu, le slug d'organisation et l'existence de la ressource |
| `405` | Consulter `Allow` ; un dossier ne se télécharge ni ne s'écrase comme un fichier |
| `409` | Créer d'abord le dossier parent de destination |
| `411` | Ajouter `Content-Length` à `PUT` |
| `412` | Relire la ressource ou le verrou ; vérifier `If`, `If-Match`, `If-None-Match` et `Overwrite` |
| `413` | Réduire le fichier ou le XML, ou revoir la limite avec l'opérateur |
| `415` | Envoyer un corps `MKCOL` vide ; le MKCOL étendu n'est pas pris en charge |
| `423` | Obtenir le bon jeton ou attendre/libérer le verrou |
| `502` | Vérifier une destination sur un autre hôte et la connexion au stockage objet |
| `503` | Libérer les verrous inutilisés de ce mot de passe et respecter `Retry-After` |
| `507` | Fractionner l'opération sur l'arborescence |

Ne relance pas automatiquement tous les refus. Un parent absent ou un mauvais identifiant exige une correction ; un conflit de verrou exige de se coordonner avec l'autre personne qui édite.

## Conformité

Le point d'accès annonce `DAV: 1, 2`. Les méthodes et limites de cette page constituent le contrat d'implémentation ; cette annonce ne garantit pas chaque fonction facultative de WebDAV. En particulier, les propriétés personnalisées ne persistent pas et les verrous d'édition partagée ne sont pas disponibles. Les extensions de calendrier, de contacts, de recherche et d'ACL ne sont pas fournies.

Consulte la [RFC 4918](https://www.rfc-editor.org/rfc/rfc4918) pour la syntaxe réseau. La classe de conformité DAV 3 concerne une révision du protocole, et non les extensions de calendrier ou de contacts.

## Limites

| Périmètre | Limite ou comportement |
| --- | --- |
| Liste récursive | `Depth: infinity` refusé ; parcourir un niveau à la fois |
| Durée d'un verrou | 1–3600 secondes |
| Verrous actifs | 200 par mot de passe d'application |
| Taille d'envoi | 5 Go par défaut ; `WEBDAV_MAX_PUT_BYTES` fixe la limite en octets |
| Corps XML | 64 Kio pour `PROPFIND`, `PROPPATCH`, `MKCOL` et `LOCK` |
| Mots de passe | Jusqu'à 50 actifs par utilisateur dans une organisation |
| Dernière utilisation | Mise à jour au plus une fois par minute et par mot de passe |

Les envois sont transmis en flux au stockage objet avec régulation du débit. Le serveur a besoin de la taille avant de créer la requête d'envoi ; un transfert chunked reçoit `411`. Les opérations sur des dossiers disposent d'un budget de parcours limité et peuvent recevoir `507`. Fractionne les grandes arborescences plutôt que de répéter la même opération trop volumineuse.

## Prérequis réseau

Le backend dessert `/dav/*` ; le proxy de la plateforme l'expose sur le même hôte public que Tale. En développement local, Vite relaie `/dav` du port 3000 vers le backend. Les clients peuvent donc utiliser l'origine habituelle de l'application locale. Aucun service WebDAV séparé n'est à déployer.

Une liste peut fonctionner alors qu'un téléchargement ou un envoi échoue : les dossiers dépendent de la base de données, les octets des fichiers dépendent aussi du stockage objet. Teste les deux chemins après une modification du proxy ou du stockage. Aligne la limite du proxy sur `WEBDAV_MAX_PUT_BYTES`.

## Sécurité

Utilise HTTPS pour les montages distants. Basic transmet le mot de passe d'application à chaque requête ; Base64 est un encodage, pas un chiffrement. Le HTTP en clair convient seulement à un test contrôlé sur localhost. Saisis les identifiants dans l'invite du client ou le trousseau du système, jamais dans une URL telle que `https://user:password@host/`.

Le backend conserve des hachages HMAC-SHA256 et un préfixe de recherche de quatre caractères, puis compare les hachages en temps constant. La configuration de démarrage dérive `WEBDAV_APP_PASSWORD_HMAC_KEY` de `INSTANCE_SECRET`, sauf valeur explicite. Conserve ces secrets stables et sauvegardés : changer la clé HMAC invalide les mots de passe existants.

La liste affiche libellé, préfixe, date de création et dernière utilisation. Ces informations aident à repérer et révoquer le mot de passe d'un appareil perdu. La dernière utilisation est une métadonnée actualisée à fréquence limitée, pas un journal complet de chaque requête.

## Comment ça s’intègre

Utilise [REST](https://docs.tale.dev/fr/develop/api-reference) pour les imports rattachés à un projet, les IDs explicites et la recherche. WebDAV convient aux clients du centre de documents qui attendent des chemins et des verrous. Les deux accèdent aux documents Tale, mais WebDAV n'expose ni l'arbre de fichiers d'un projet ni toutes les opérations REST.

# Webhooks
Source: https://docs.tale.dev/fr/develop/webhooks

Un webhook permet à un système externe de démarrer une automatisation déployée en envoyant une requête à une URL secrète. Il convient aux événements de commande, formulaires et autres notifications envoyées vers une destination fixe. Une réponse `202` confirme l'acceptation et fournit un ID d'exécution ; elle ne confirme pas la fin du travail.

Pour une première configuration guidée, suis [Déclencher une automatisation par webhook](https://docs.tale.dev/fr/tutorials/developer/trigger-automation-via-webhook). Cette référence détaille la livraison, son périmètre, le cycle de vie du jeton et les relances.

## Un déclencheur, de bout en bout

### Préparer une automatisation déployée

Enregistre puis déploie une automatisation dont les tests passent. Lie un webhook dans l'éditeur, ou envoie `PUT /api/v1/automations/{name}/triggers` avec `{"kind":"webhook"}` et une clé API autorisée. Copie immédiatement le nouveau jeton : il n'est renvoyé qu'une fois.

Choisis l'URL selon le périmètre voulu :

| Travail à démarrer | URL | Condition |
| --- | --- | --- |
| Exécution de projet | `/api/projects/{id}/automations/webhook/{token}` | Projet actif dans l'organisation du jeton, avec l'automatisation installée |
| Exécution d'organisation | `/api/automations/webhook/{token}` | Automatisation sans liaison à un projet |

Une automatisation liée à un projet refuse l'URL globale avec `409 AUTOMATION_PROJECT_SCOPE_REQUIRED`. N'ajoute pas de paramètre de requête `projectId` : les deux URL le refusent avec `400 INVALID_QUERY`. Un champ du corps fournisseur reste une donnée d'entrée, pas un sélecteur de projet.

### Envoyer une livraison

Conserve l'URL secrète complète dans `TALE_WEBHOOK_URL` via la configuration sécurisée de l'émetteur. Cette requête utilise un ID stable pour un même événement métier :

```bash
curl --fail-with-body --request POST "$TALE_WEBHOOK_URL" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-12345-paid' \
  --data '{"orderId":"12345","status":"paid"}'
```

L'acceptation renvoie HTTP `202` et une réponse de forme `{"runId":"..."}`. Conserve cet ID avec l'ID de livraison de l'émetteur. Tale transmet le corps à l'automatisation dans cette enveloppe :

```json
{
  "trigger": "webhook",
  "payload": { "orderId": "12345", "status": "paid" }
}
```

Lis la commande via `input.payload.orderId`. Si l'automatisation déclare un schéma `inputs`, il doit décrire cette enveloppe. Un corps qui n'est pas du JSON devient du texte dans `payload`. La limite est de 256 Kio (262 144 octets), comptés pendant la réception ; une requête plus grande reçoit `413`.

### Suivre le résultat

| Périmètre de livraison | Route de suivi authentifiée |
| --- | --- |
| Projet | `GET /api/v1/projects/{id}/runs/{runId}` |
| Organisation | `GET /api/v1/runs/{runId}` |

Interroge la route avec une clé API dont le titulaire peut lire ce périmètre, ou ouvre l'exécution dans Tale. Le jeton webhook autorise les livraisons, pas la lecture des résultats REST. Attends un état terminal avant d'annoncer que le travail a réussi.

### Interpréter les réponses

| Statut | Code/résultat | Action |
| --- | --- | --- |
| `202` | `runId` | Accepté ; suivre l'exécution |
| `202` | `runId`, `duplicate: true` | Déjà accepté ; suivre l'exécution d'origine, aucune nouvelle exécution |
| `400` | `INVALID_QUERY` | Retirer `projectId` de la chaîne de requête |
| `400` | `AUTOMATION_INPUT_INVALID` | Corriger l'enveloppe ou le schéma avec `data.issues` |
| `403` | `AUTOMATION_PROJECT_FORBIDDEN` | Vérifier projet actif, bonne organisation et installation |
| `404` | Jeton inconnu, désactivé ou mal saisi ; aussi toute méthode autre que POST | Vérifier l'URL enregistrée et l'état du déclencheur |
| `409` | `AUTOMATION_NOT_DEPLOYED` | Déployer une version dont les tests passent |
| `409` | `AUTOMATION_PROJECT_SCOPE_REQUIRED` | Utiliser l'URL du projet d'installation |
| `409` | `AUTOMATION_DELIVERY_SCOPE_MISMATCH` | Vérifier le périmètre de l'ID de livraison d'origine |
| `413` | Corps trop volumineux | Réduire les données sous 256 Kio |
| `429` | Budget de l'émetteur ou du déclencheur épuisé | Attendre au moins `Retry-After` |

Une entrée refusée ne crée aucune exécution. Un refus de projet ne distingue volontairement pas un projet absent, archivé ou sans installation, et ne révèle pas le nom de l'automatisation. `GET`, `HEAD` et `OPTIONS` reçoivent le même `404` qu'un jeton invalide, sans en-tête `Allow`.

## Le jeton est l'identifiant

Le secret dans l'URL autorise la livraison. Ce point d'accès ne vérifie pas de signature HMAC du fournisseur et n'utilise pas d'en-tête `Authorization`. Garde l'URL hors des tickets publics, journaux partagés et captures d'écran. Tale stocke son hachage et le compare en temps constant ; le texte en clair n'est fourni qu'à la création.

| Modification | Effet sur le jeton |
| --- | --- |
| `PUT` webhook avec `rotateToken: true` | Nouveau jeton renvoyé une fois ; ancienne URL immédiatement invalide |
| Supprimer/délier le déclencheur | Jeton révoqué ; versions et historique conservés |
| Remplacer le webhook par une planification/un événement | Jeton révoqué ; réponse avec `revoked: "webhook"` |
| Relier ensuite un webhook | Nouveau jeton ; l'ancien ne revient pas |
| Définir `enabled: false` | URL suspendue avec `404`, jeton conservé |
| Réactiver, y compris par un `PUT` ultérieur sans `enabled` | La même URL suspendue redevient active |

<Warning>

Après une fuite, renouvelle le jeton ou délie le déclencheur. Désactiver suspend temporairement l'accès, sans révocation définitive. Coordonne la rotation avec l'émetteur et remplace son URL enregistrée avant de reprendre les livraisons.

</Warning>

Lis `revoked` dans les changements de déclencheur scriptés pour éviter qu'un changement de type coupe discrètement un partenaire qui utilise toujours l'ancienne URL.

## Idempotence et relances

La déduplication porte sur le déclencheur et le projet de son URL. Le même ID de livraison peut démarrer une exécution dans chaque projet d'installation. Tale vérifie encore l'activité du projet et l'installation avant de renvoyer un doublon mémorisé.

| Identité | Fenêtre de doublon | Ce qui doit rester identique |
| --- | --- | --- |
| En-tête d'ID de livraison | 24 heures | Valeur de l'ID et périmètre ; même un corps différent compte comme la même livraison |
| Aucun en-tête d'ID | 2 minutes | Corps identique octet par octet et même URL |

Pour les en-têtes, le premier présent dans cet ordre de priorité l'emporte :

```text
Idempotency-Key
X-Idempotency-Key
webhook-id
X-GitHub-Delivery
X-Gitlab-Event-UUID
X-Shopify-Webhook-Id
Linear-Delivery
X-Atlassian-Webhook-Identifier
X-Request-UUID
I-Twilio-Idempotency-Token
X-Webhook-Id
```

Les noms d'en-têtes sont des alternatives, pas des espaces d'identité séparés. Transmettre l'ID du fournisseur dans `Idempotency-Key` conserve son identité. Sans ID, une mise en forme JSON différente change les octets et peut créer une nouvelle livraison. Préfère un ID d'événement explicite et stable si l'émetteur le permet.

Répéter l'exemple dans les 24 heures renvoie le `runId` d'origine avec `duplicate: true`. Cela ne réexécute pas une automatisation échouée. Décide séparément comment récupérer l'exécution en échec, sans changer aveuglément les IDs de livraison.

Relance les erreurs réseau et les réponses `5xx` temporaires avec une attente exponentielle bornée. Pour `429`, respecte `Retry-After`. Garde l'ID si une réponse a pu être perdue. Corrige les autres causes `4xx` avant de relancer. La déduplication évite les exécutions supplémentaires dans sa fenêtre ; elle ne garantit pas des effets appliqués exactement une fois dans un service externe.

## Budgets

| Budget | Recharge | Rafale | Décompté |
| --- | --- | --- | --- |
| IP de l'émetteur selon les proxys de confiance | 120/minute | 240 | Avant vérification du jeton |
| Déclencheur vérifié | 20/minute | 40 | À l'admission de la livraison |

Chacun peut provoquer `429` avec `Retry-After` en secondes entières et l'enveloppe d'erreur habituelle. Le jeton authentifie l'accès au déclencheur, mais il n'existe pas d'identité de compte émetteur distincte à limiter. Suis les [limites de débit](https://docs.tale.dev/fr/develop/rate-limits) et conserve l'ID de livraison pendant l'attente.

## Choisir entre webhook et clé API

Utilise un webhook si l'émetteur accepte une URL d'événement fixe. Choisis une clé API si ton client doit aussi découvrir les automatisations, sélectionner des projets ou lire les résultats. [Déclencheurs](https://docs.tale.dev/fr/platform/automations/triggers) explique la configuration dans l'application ; la [référence API](https://docs.tale.dev/fr/develop/api-reference) décrit les démarrages authentifiés et leur suivi.

# Configurer un espace pour ton équipe
Source: https://docs.tale.dev/fr/get-started/admins

Un espace utilisable nécessite une organisation, un fournisseur de modèles qui fonctionne et des comptes avec les bons accès. Mets ces bases en place, puis configure les contrôles adaptés au travail prévu.

## Avant de commencer

Utilise un compte Propriétaire ou Admin sur la bonne instance. La configuration initiale crée le premier compte et l’organisation. Si ton organisation apparaît déjà dans le Dashboard, ouvre ses paramètres au lieu d’en créer une autre.

Prépare les identifiants du fournisseur dans ton gestionnaire de mots de passe. Le fournisseur doit prendre en charge le modèle et les tâches souhaités. La page [Fournisseurs IA](https://docs.tale.dev/fr/platform/admin/providers) explique les identifiants, les catalogues et les environnements d’exécution des agents.

## Connecter un fournisseur et tester le chat

<Steps>

<Step title="Ajouter les identifiants">

Ouvre **Paramètres > Fournisseurs IA**, sélectionne **Ajouter des identifiants**, puis choisis le fournisseur. Renseigne les champs de sa méthode d’authentification et enregistre. Donne aux identifiants un nom qui permette à un autre admin de comprendre leur usage.

<Frame caption="Les identifiants connectés rendent les modèles du fournisseur disponibles dans l’espace.">

![Les paramètres des fournisseurs IA présentent les identifiants de fournisseurs connectés.](https://docs.tale.dev/images/get-started/settings-providers.webp)

</Frame>

</Step>

<Step title="Vérifier le modèle dans un nouveau chat">

Ouvre **Accueil**, choisis **Nouveau chat**, puis un modèle disponible. Envoie une demande autonome, par exemple « Rédige une liste de trois points pour préparer une réunion ». Attends la réponse complète. L’enregistrement des identifiants ne prouve pas à lui seul que le compte a accès au modèle choisi.

Si la liste reste vide ou si le fournisseur refuse la requête, suis les étapes de dépannage de la page [Fournisseurs IA](https://docs.tale.dev/fr/platform/admin/providers).

</Step>

</Steps>

## Ajouter les personnes avec les bons accès

Ouvre **Paramètres > Membres** et sélectionne **Ajouter un membre**. Pour un nouveau compte, le formulaire définit un mot de passe initial ; un compte existant conserve ses identifiants. Ce parcours n’envoie pas d’invitation par e-mail. [Membres et rôles](https://docs.tale.dev/fr/platform/admin/members-and-roles) détaille les champs et la remise sécurisée des premiers identifiants.

<Frame caption="Vérifie le rôle de chaque membre avant de lui transmettre l’accès.">

![La page Membres présente les personnes de l’organisation et le rôle attribué à chacune.](https://docs.tale.dev/images/get-started/settings-organization-members.webp)

</Frame>

Choisis le rôle selon le travail : les Membres utilisent l’espace, les Éditeurs maintiennent les contenus partagés, les Développeurs travaillent sur les intégrations et les automatisations, et les Admins gèrent l’organisation. Consulte le tableau détaillé des autorisations lorsque les tâches se recoupent. Les équipes et le partage des projets déterminent aussi les projets accessibles.

## Vérifier le premier parcours de l’équipe

Demande à un collègue de se connecter avec son propre compte, d’envoyer un message et d’ouvrir le projet nécessaire. Vérifie aussi les sources partagées avec ce compte. Tester uniquement comme Propriétaire peut masquer un manque de droits ou un accès trop large.

<Tip>

Commence avec un projet représentatif et quelques documents sources. Vérifie que les personnes trouvent le travail et que les comptes prévus accèdent aux fichiers avant d’importer une grande bibliothèque.

</Tip>

## Définir les règles d’exploitation

Examine selon tes besoins [les politiques et les limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits), [les journaux d’audit](https://docs.tale.dev/fr/platform/admin/governance/audit-logs) et [le SSO](https://docs.tale.dev/fr/platform/admin/enterprise-sso). Désigne les responsables des identifiants, des revues d’accès et des tâches en échec. En auto-hébergement, prévois aussi un processus testé de [sauvegarde et de restauration](https://docs.tale.dev/fr/self-hosted/operate/backups-and-restore).

# Ta première requête API
Source: https://docs.tale.dev/fr/get-started/developers

Commence une intégration en vérifiant trois points : la clé permet de s’authentifier, la requête vise la bonne organisation et les ressources nécessaires y sont disponibles. Ce guide effectue ces vérifications avec curl. Il te faut une instance en cours d’exécution et le droit de créer des clés API, généralement avec le rôle Développeur, Admin ou Propriétaire.

## Créer une clé pour l’intégration

Ouvre **Paramètres > API > REST** et choisis **Créer une clé API**. Donne-lui un nom qui décrit son usage, choisis une expiration, puis **Créer la clé**. Copie immédiatement la valeur ; Tale n’affiche le secret qu’une fois.

<Frame caption="Utilise une clé identifiable par intégration pour la remplacer ou la révoquer indépendamment.">

![La boîte de création d’une clé API permet de choisir un nom et une durée de validité avant sa génération.](https://docs.tale.dev/images/get-started/settings-api-keys.webp)

</Frame>

Charge le secret dans `TALE_API_KEY` depuis un gestionnaire de secrets ou un environnement shell privé. Définis `TALE_BASE_URL` avec l’adresse de ton instance, par exemple `https://your-host.example.com`. N’ajoute pas encore `/api/v1` ; les commandes le font.

## Identifier le compte et l’organisation

Appelle `/me` sans en-tête d’organisation. Avec une seule appartenance à une organisation, la réponse contient l’identité de la clé et son organisation. Avec plusieurs appartenances, elle renvoie `400 ORG_SLUG_REQUIRED` et propose les organisations dans `data.organizations` :

```bash
curl --fail-with-body --silent --show-error "$TALE_BASE_URL/api/v1/me" \
  -H "Authorization: Bearer $TALE_API_KEY"
```

Définis `TALE_ORG_SLUG` avec le slug choisi, puis rappelle `/me` dans ce périmètre. L’URL du tableau de bord contient un identifiant d’organisation ; ne l’utilise pas comme slug. Une réponse `400` au premier appel fait terminer curl avec le code 22, tout en affichant le contenu JSON.

```bash
curl --fail-with-body --silent --show-error "$TALE_BASE_URL/api/v1/me" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG"
```

Vérifie le compte, l’organisation, les capacités et `key.expiresAt` dans la réponse réussie avant de continuer.

La clé agit avec les appartenances et droits actuels de son titulaire. Plusieurs clés pour un compte ne créent pas des rôles ou budgets de débit indépendants. Prépare le remplacement avant expiration ; `/api/v1` ne gère pas les clés API à ta place.

## Trouver un modèle disponible

Indique explicitement l’organisation lorsque tu listes les modèles :

```bash
curl --fail-with-body --silent --show-error "$TALE_BASE_URL/api/v1/models" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG"
```

<Check>

Une réponse `200` contenant un tableau `models` confirme cette requête authentifiée dans l’organisation. Le tableau peut être vide : cela prouve l’accès à l’endpoint, pas la possibilité de générer une réponse.

</Check>

Utilise l’`id` du modèle dans les requêtes de chat et son `providerSlug` si plusieurs fournisseurs proposent le même ID. Un modèle peut figurer dans la liste sans être accessible au compte du fournisseur, faute de crédit ou d’abonnement adapté. Si la liste est vide, demande à un admin de vérifier les identifiants et les accès.

## Résoudre la première erreur

| Réponse | Action |
| --- | --- |
| `401` | Vérifie la clé bearer, son expiration et sa révocation éventuelle. |
| `400` avec `ORG_SLUG_REQUIRED` | Choisis un slug dans `data.organizations` de cette erreur et envoie `X-Organization-Slug`. |
| `404` avec `ORG_SLUG_INVALID` | L’en-tête ne désigne aucune organisation du tout : une faute de frappe, ou l’identifiant d’organisation de l’URL du tableau de bord collé à la place du slug. Envoie le slug donné dans `data.organizations`. |
| `403` avec `ORG_FORBIDDEN` | L’organisation existe, mais le détenteur de la clé n’en est pas membre. Choisis un slug dans `data.organizations`. |
| `403` | Vérifie le droit nécessaire à l’opération. |
| `429` | Attends selon `Retry-After` ; consulte les [limites de débit](https://docs.tale.dev/fr/develop/rate-limits). |

Si curl signale une erreur TLS ou réseau avant de recevoir du JSON, vérifie l’hôte et le certificat. Ne désactive pas la vérification des certificats dans un script de production.

## Choisir la tâche suivante

| Tu veux… | Poursuis avec |
| --- | --- |
| Afficher une réponse complète | [Appeler Tale depuis un script](https://docs.tale.dev/fr/tutorials/developer/call-tale-from-a-script). |
| Lancer une automation depuis un autre système | [Déclencher une automation par webhook](https://docs.tale.dev/fr/tutorials/developer/trigger-automation-via-webhook). |
| Connecter un client MCP | [Endpoint MCP](https://docs.tale.dev/fr/develop/mcp-endpoint). |
| Utiliser Tale depuis opencode, Claude Code ou un script shell | [Utiliser Tale depuis ton éditeur ou un script](https://docs.tale.dev/fr/develop/use-tale-from-your-editor). |
| Utiliser les fichiers, tâches ou exécutions d’un projet | [Référence API](https://docs.tale.dev/fr/develop/api-reference). |

Utilise les routes `/api/v1/projects/{id}/...` pour les opérations d’un projet. L’ID du projet appartient au chemin ; le slug de l’organisation appartient à l’en-tête. Garde les deux valeurs explicites dans ta configuration.

# Créer et tester un agent de projet
Source: https://docs.tale.dev/fr/get-started/editors

Crée un agent de projet pour un travail récurrent, comme la revue de documents ou la préparation d’un rapport opérationnel. Tu choisis ses instructions, son environnement d’exécution, son modèle et ses outils, puis tu lui donnes une tâche dont tu peux examiner le résultat. Ce guide prend la revue d’un brief de lancement comme exemple. Tant qu’un projet n’a pas d’agent propre, ses tâches peuvent aller à l’[agent standard](https://docs.tale.dev/fr/platform/projects/project-agents#standard-agent) de l’organisation.

## Avant de commencer

Il te faut des droits de modification sur un projet, un fournisseur de modèles adapté et un environnement d’exécution disponible avec l’infrastructure requise. Un chat qui répond valide l’accès au fournisseur pour le chat. Il ne prouve pas que l’environnement d’un agent ou sa sandbox est prêt. Demande à un admin de vérifier [les environnements d’exécution](https://docs.tale.dev/fr/platform/agents/harnesses) si aucun n’est disponible.

Crée ou ouvre d’abord un projet. Le guide [utiliser les projets](https://docs.tale.dev/fr/tutorials/member/use-projects) explique le partage et les sources de connaissances.

## Définir un travail précis

<Steps>

<Step title="Créer un agent dans le projet">

Ouvre l’onglet **Agents** du projet et sélectionne **Nouvel agent**. Nomme-le selon son travail, par exemple « Relecteur de lancement ». Choisis un **Harness** et un **Modèle** pris en charge par ton espace. Si le même modèle apparaît avec plusieurs fournisseurs, choisis aussi celui que tu souhaites utiliser.

<Frame caption="Un agent de projet associe un travail nommé à un environnement d’exécution et un modèle.">

![L’onglet Agents du projet présente les agents avec leur environnement d’exécution et leur modèle configurés.](https://docs.tale.dev/images/platform/project-agents-models.webp)

</Frame>

</Step>

<Step title="Écrire des instructions vérifiables">

Dans **Instructions**, décris le travail, les sources, le résultat attendu et les limites. Par exemple :

> Examine le brief de lancement joint à la tâche. Liste les décisions manquantes, les responsabilités floues et les contradictions. Cite le passage concerné pour chaque constat. Ne modifie aucun fichier et ne contacte aucun service externe. Si le brief manque, demande-le.

Accorde seulement les **Skills, connectors & outils** et les **Secrets** nécessaires. Sélectionne **Créer l’agent** pour enregistrer. Tu pourras revoir les instructions après avoir examiné un résultat.

</Step>

<Step title="Attribuer une tâche concrète et lancer l’agent">

Crée une tâche avec une description précise et les fichiers d’entrée requis. Attribue-la à l’agent, puis sélectionne **Démarrer l’agent**. L’attribution et le démarrage sont deux actions distinctes. Observe le statut et l’activité pendant l’exécution.

Si le démarrage échoue, lis la cause affichée avant de réessayer. Un fournisseur absent, un environnement indisponible, une restriction de politique ou une entrée manquante demandent des corrections différentes.

</Step>

</Steps>

## Examiner le travail

Lis le commentaire de l’agent et les éventuels fichiers produits. Compare le résultat aux consignes : la bonne source a-t-elle été examinée, chaque constat est-il étayé et les limites ont-elles été respectées ? Une exécution terminée ne garantit pas un résultat correct.

Consigne explicitement la revue et l’acceptation. Utilise les commandes de la tâche pour donner un retour, demander un nouveau passage si nécessaire et terminer le travail accepté. [Les tâches de projet](https://docs.tale.dev/fr/platform/projects/tasks) expliquent les statuts et le champ de relecture.

<Tip>

Teste aussi le cas où une entrée manque. Un agent qui demande le brief absent est plus utile qu’un agent qui en invente le contenu.

</Tip>

## Améliorer un point à la fois

Corrige l’instruction à l’origine d’un mauvais résultat, puis teste une tâche comparable. Ajoute des outils seulement lorsque le travail le nécessite. Avant d’autoriser des écritures externes, examine [les approbations](https://docs.tale.dev/fr/platform/approvals/concepts). Pour un exemple plus complet, suis [ton premier agent de bout en bout](https://docs.tale.dev/fr/tutorials/editor/first-agent-end-to-end).

Lorsque tu sais évaluer le résultat d’une tâche de façon fiable, utilise le même agent pour des travaux similaires. Si le processus nécessite des exécutions planifiées, des étapes définies ou des approbations pour les actions des connecteurs, crée une [automatisation](https://docs.tale.dev/fr/platform/automations/concepts) qui répond à ces besoins.

# Utiliser Tale avec ton équipe
Source: https://docs.tale.dev/fr/get-started/members

Ton travail quotidien dans Tale commence par une conversation ou un projet. Ce guide t’aide à choisir le bon endroit pour une question, un document et un travail à partager avec ton équipe.

## Comprendre tes accès

Commence avec un compte connecté et un [premier chat](https://docs.tale.dev/fr/get-started/quickstart) qui répond. Ton rôle et ton accès au projet déterminent ce que tu peux lire ou modifier. Les Membres peuvent discuter et travailler dans les projets accessibles. Modifier les connaissances de l’organisation nécessite le rôle Éditeur ou supérieur ; le travail de projet suit les règles d’accès du projet. Si une commande manque, consulte [les membres et les rôles](https://docs.tale.dev/fr/platform/admin/members-and-roles).

## Donner assez de contexte à ta question

Ouvre **Accueil**, puis **Nouveau chat**. Décris la tâche, fournis les informations nécessaires et précise la forme du résultat. Par exemple, colle des notes de réunion et demande les décisions, les responsables et les questions ouvertes.

Lis le résultat avant de l’utiliser. Lorsqu’une réponse cite une source, ouvre-la et vérifie qu’elle étaye l’affirmation. Une réponse bien rédigée ne prouve pas que le modèle a utilisé le bon document. [Bien utiliser le chat](https://docs.tale.dev/fr/tutorials/member/chat-effectively) montre comment affiner le résultat avec des questions complémentaires.

## Ranger les informations au bon endroit

| Tu veux… | Utilise… |
| --- | --- |
| Discuter d’un fichier dans cette conversation | Une [pièce jointe du chat](https://docs.tale.dev/fr/platform/chat/attachments) |
| Garder les sources avec un projet | L’[onglet Connaissances du projet](https://docs.tale.dev/fr/platform/projects/manage-files) |
| Rendre des contenus approuvés disponibles à l’organisation | Les [documents de connaissances](https://docs.tale.dev/fr/platform/knowledge/documents) |
| Maintenir un court article réutilisable | Une [entrée de connaissances](https://docs.tale.dev/fr/platform/knowledge/knowledge-entries) |

Choisis le public concerné avant le chargement. Les connaissances de l’organisation et les fichiers d’un projet n’ont pas les mêmes limites d’accès. Charger un fichier et le rendre consultable sont deux étapes distinctes : attends l’indexation avant de tester la recherche.

<Frame caption="La liste Documents affiche les fichiers chargés et leur état d’indexation. Le filtre ne conserve que les fichiers chargés et indexés.">

![Le tableau des documents présente les fichiers sources et leur état d’indexation.](https://docs.tale.dev/images/get-started/documents-list.webp)

</Frame>

Si tu ne peux pas ajouter une source partagée, demande à une personne disposant des droits de modification. Précise le public visé et l’emplacement souhaité.

## Travailler dans un projet

Dans **Accueil**, choisis un projet accessible sous **Projets**. Consulte **Tâches** pour le travail à réaliser, **Connaissances** pour les fichiers et **Chats** pour les conversations. Les chats de projet restent personnels jusqu’à leur partage avec le projet.

<Frame caption="Le tableau regroupe le travail par statut ; chaque carte ouvre les détails de la tâche.">

![Un tableau de projet regroupe les cartes dans les colonnes Backlog, À faire, En cours, En revue, Terminé et Annulé.](https://docs.tale.dev/images/platform/projects-task-board.webp)

</Frame>

Ouvre une tâche pour lire sa description, son attribution et la discussion. Dans tout projet que tu peux ouvrir, tu crées des tâches et modifies celles que tu as créées ou qui te sont attribuées, par exemple pour confier le travail à l’un des agents du projet ou, dans un projet sans agents propres, à l’[agent standard](https://docs.tale.dev/fr/platform/projects/project-agents#standard-agent) de l’organisation. [Gérer les tâches du projet](https://docs.tale.dev/fr/platform/projects/tasks) explique le travail courant ; [utiliser les projets](https://docs.tale.dev/fr/tutorials/member/use-projects) propose un exemple complet.

## Reprendre ton travail

Chaque section s’ouvre sur sa première page, quoi que tu y aies fait auparavant. Sur ordinateur, **Accueil** fait exception : il rouvre le chat que tu as lu en dernier, et le choisir à nouveau démarre un nouveau chat. Le [guide de navigation](https://docs.tale.dev/fr/platform#navigation) décrit les commandes sur ordinateur et téléphone.

**Accueil** affiche tes chats avec les tâches ouvertes qui te sont attribuées ou qui attendent ta relecture ; choisis **Chats** ou **Tâches** au-dessus de la liste pour n’afficher que tes chats ou que tes tâches. Si le panneau latéral est masqué, **Afficher le panneau latéral**, au début de l’en-tête, le fait revenir. Commence un nouveau chat pour un nouveau sujet et partage volontairement une conversation de projet lorsque tes collègues en ont besoin.

La langue et le thème sont accessibles dans **Gérer le compte**. Le [guide des préférences](https://docs.tale.dev/fr/platform/member/preferences) explique les autres réglages et les fonctions qui les utilisent.

# Envoyer ton premier message
Source: https://docs.tale.dev/fr/get-started/quickstart

Commence ici si tu as accès à un espace Tale et souhaites obtenir une première réponse. Tu vas envoyer un court prompt, lire la réponse, puis retrouver la conversation.

## Avant de commencer

Il te faut l’adresse de ton instance, un compte et un espace avec un fournisseur IA connecté. Demande l’accès à la personne qui gère cet espace. Pour installer Tale, suis le [démarrage en auto-hébergement](https://docs.tale.dev/fr/self-hosted/install/quickstart). Pour une instance gérée, consulte [la mise en route Cloud](https://docs.tale.dev/fr/cloud/onboarding).

Ton compte te permet de te connecter. L’organisation est l’espace qui regroupe les membres, les projets et la configuration de ton équipe. Ton rôle détermine les actions que tu peux y effectuer.

## Lancer une conversation

<Steps>

<Step title="Te connecter et démarrer un chat">

Ouvre ton instance et utilise la méthode de connexion indiquée par ton admin. Si tu appartiens à plusieurs organisations, choisis celle où tu veux travailler. Ouvre **Accueil**, puis choisis **Nouveau chat**, le crayon en haut de la liste d’**Accueil**.

</Step>

<Step title="Vérifier le modèle et écrire un prompt">

La commande de modèle sous le champ de message affiche les choix disponibles. Elle peut indiquer **Auto** ; sélectionne un modèle précis si tu veux choisir lequel répond. Les options dépendent des fournisseurs connectés et des règles d’accès de ton espace.

<Frame caption="Le champ de message et le choix du modèle se trouvent dans la même zone de saisie.">

![La zone de saisie du chat contient le champ de message, le sélecteur de modèle, les commandes de pièces jointes et le bouton d’envoi.](https://docs.tale.dev/images/platform/chat-composer.webp)

</Frame>

Pour ce premier test, utilise une demande autonome : « Rédige une liste de trois points pour préparer une réunion d’équipe. Limite chaque point à une phrase. » Elle ne dépend ni de documents chargés ni d’outils connectés.

</Step>

<Step title="Envoyer et lire la réponse">

Sélectionne **Envoyer le message** ou appuie sur Entrée. Ton message apparaît dans la conversation, suivi de la réponse de l’assistant. Un indicateur de réflexion peut précéder la réponse. Attends qu’elle soit terminée avant de l’évaluer.

Vérifie le respect de la longueur et du format demandés. Pose une question complémentaire, par exemple : « Ajoute qui devrait préparer chaque point. » La même conversation conserve le contexte des messages précédents.

</Step>

</Steps>

## Retrouver le chat

**Accueil** range la conversation sous **Aujourd’hui** ; choisis-la pour la rouvrir. Un nouveau chat démarre une conversation séparée, utile lorsque tu changes de sujet. Les [bases du chat](https://docs.tale.dev/fr/platform/chat/basics) expliquent les noms, l’historique et les commandes des réponses.

<Tip>

Précise l’objectif, les informations à utiliser et le format attendu. « Résume ces notes en décisions et questions ouvertes » définit mieux la tâche que « Aide-moi avec ceci ».

</Tip>

## Si tu n’obtiens pas de réponse

| Ce que tu observes | Action à prendre |
| --- | --- |
| La connexion échoue | Vérifie l’adresse de l’instance et la méthode de connexion avec ton admin. |
| Aucun modèle n’est disponible | Demande à un admin de vérifier les [fournisseurs IA](https://docs.tale.dev/fr/platform/admin/providers) et ton accès aux modèles. |
| Une erreur de fournisseur ou de modèle apparaît | Essaie un autre modèle disponible et transmets l’erreur affichée à l’admin. |
| Une limite d’utilisation est atteinte | Demande à l’admin de vérifier la [politique](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits) concernée. |
| La réponse n’utilise pas tes documents | Le premier prompt ne contenait pas de source. Ajoutes-en avec les [pièces jointes du chat](https://docs.tale.dev/fr/platform/chat/attachments) ou les [connaissances](https://docs.tale.dev/fr/platform/knowledge/overview). |

Poursuis avec [Tale en équipe](https://docs.tale.dev/fr/get-started/members) ou [les prompts efficaces](https://docs.tale.dev/fr/tutorials/member/chat-effectively).

<Video src="https://docs.tale.dev/videos/fr/tutorials/ep1-welcome/ep1-welcome.fr.mp4" poster="https://docs.tale.dev/videos/fr/tutorials/ep1-welcome/ep1-welcome.fr.webp" captions="https://docs.tale.dev/videos/fr/tutorials/ep1-welcome/ep1-welcome.fr.vtt" lang="fr" title="Épisode 1 — Bienvenue dans Tale" caption="Épisode 1 — Bienvenue dans Tale (2:46)">

</Video>

# Documentation Tale
Source: https://docs.tale.dev/fr

Prends tes repères dans Tale, confie une première tâche à un agent ou construis une intégration. Si tu as déjà un compte, [envoie ton premier message](https://docs.tale.dev/fr/get-started/quickstart). Sinon, tu peux [installer ton propre espace de travail](https://docs.tale.dev/fr/self-hosted/install/quickstart).

## De la tâche au résultat

1. [Décris le travail](https://docs.tale.dev/fr/platform/projects/tasks). Donne à la tâche un objectif, des fichiers sources et un résultat attendu.
2. [Confie la tâche à un agent](https://docs.tale.dev/fr/get-started/editors). Choisis ses consignes et ses outils, puis lance le travail.
3. [Examine le résultat](https://docs.tale.dev/fr/platform/projects/task-automation). Vérifie le rapport et les fichiers, puis approuve le résultat ou demande des modifications.

Chaque guide précise les accès et la configuration nécessaires. Un chat fonctionnel ne prouve pas que le moteur d’agent ou la sandbox est prêt.

## Que souhaites-tu faire ?

<CardGroup cols="2">

<Card title="Créer et tester un agent de projet" icon="bot" href="https://docs.tale.dev/fr/get-started/editors">

Configure un agent pour une tâche précise, lance-le sur une tâche de projet et examine son premier résultat.

</Card>

<Card title="Travailler avec ton équipe" icon="users" href="https://docs.tale.dev/fr/get-started/members">

Retrouve tes conversations, consulte les sources et rejoins un projet.

</Card>

<Card title="Configurer un espace de travail" icon="shield" href="https://docs.tale.dev/fr/get-started/admins">

Connecte un fournisseur, invite des personnes et définis leurs accès.

</Card>

<Card title="Connecter un autre système" icon="code" href="https://docs.tale.dev/fr/get-started/developers">

Envoie ta première requête API et vérifie la réponse.

</Card>

</CardGroup>

## Apprendre en pratiquant

Réalise une tâche complète avec des exemples et des points de contrôle. Vérifie les prérequis avant de commencer ou [consulte tous les tutoriels](https://docs.tale.dev/fr/tutorials/overview).

<CardGroup cols="3">

<Card title="Organiser le travail dans un projet" icon="folder" href="https://docs.tale.dev/fr/tutorials/member/use-projects">

Réunis une tâche, des fichiers sources et les consignes du projet.

</Card>

<Card title="Lancer ton premier agent" icon="bot" href="https://docs.tale.dev/fr/tutorials/editor/first-agent-end-to-end">

Lance une tâche déléguée et examine le rapport et les fichiers livrés.

</Card>

<Card title="Créer un workflow avec approbations" icon="check-check" href="https://docs.tale.dev/fr/tutorials/editor/workflow-with-approvals">

Vérifie une action avant que le workflow ne l’exécute.

</Card>

</CardGroup>

## Trouver la référence utile

- Les [guides de la plateforme](https://docs.tale.dev/fr/platform) expliquent les commandes, les autorisations, le comportement attendu et le dépannage.
- La [référence API](https://docs.tale.dev/fr/develop/api-reference) décrit le contrat d’intégration avec un autre système.
- Les guides d’[auto-hébergement](https://docs.tale.dev/fr/self-hosted) couvrent l’installation, la configuration, les sauvegardes et les mises à niveau.
- [Tale Cloud](https://docs.tale.dev/fr/cloud) explique l’hébergement géré et les responsabilités d’exploitation.

Les mêmes guides produit s’appliquent aux instances Cloud et auto-hébergées. Les captures montrent l’interface anglaise ; les pages allemandes et françaises utilisent les libellés de leur langue.

# Administrer les agents de projet
Source: https://docs.tale.dev/fr/platform/admin/agents

Administre un agent à travers son projet et les ressources de l’organisation. Il n’existe pas de liste d’agents supplémentaire à configurer pour toute l’organisation. Ouvre le projet sous **Projets** dans **Accueil**, puis **Agents** pour examiner ou modifier ses agents.

## Vérifier qui peut modifier l’agent

Toute personne qui peut lire le projet voit ses agents. Les personnes autorisées à modifier un projet actif peuvent créer, modifier ou supprimer ses agents. Un projet archivé reste consultable. Vérifie les [rôles des membres](https://docs.tale.dev/fr/platform/admin/members-and-roles) et les [accès des équipes](https://docs.tale.dev/fr/platform/admin/teams) lorsqu’une personne possède un accès inattendu ou ne peut pas gérer les agents.

Un agent appartient à un seul projet. Son identifiant et l’accès à un second projet ne permettent pas à une intégration de l’utiliser comme agent de ce second projet. Chaque projet accepte jusqu’à 50 agents, avec des noms uniques dans le projet.

## Examiner les ressources avant le démarrage

Ouvre le dialogue de modification et vérifie l’ensemble de la configuration, au-delà du modèle :

| Vérification | Pourquoi elle compte | Où résoudre le problème |
| --- | --- | --- |
| Harness, modèle et fournisseur | Les identifiants doivent permettre ce mode d’exécution. | [Fournisseurs d’IA](https://docs.tale.dev/fr/platform/admin/providers). |
| Skills et partage | Les équipes du projet déterminent les bundles disponibles. | [Bibliothèque de skills](https://docs.tale.dev/fr/platform/workspace/skills) et accès au projet. |
| Connectors et outils de la plateforme | Ils autorisent des services et des opérations sur les données. | [Identifiants des connectors](https://docs.tale.dev/fr/platform/admin/connectors) et équipement de l’agent. |
| Secrets | La session en cours peut lire les valeurs accordées. | Les commandes **Secrets** de l’agent, réservées aux Propriétaires et Admins. |
| Capacité des sandboxes et dépenses | Le travail nécessite un environnement disponible et un budget autorisé. | [Sandboxes](https://docs.tale.dev/fr/platform/admin/sandboxes) et [Politiques et limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits). |

Un agent de revue peut se contenter de lire le dépôt et de produire un compte rendu. Un outil d’écriture autorise ses opérations dans les limites de ses règles d’accès. Une instruction demandant de solliciter un accord ne remplace pas le retrait d’une permission inutile.

## Maîtriser les changements de secrets

Seuls un Propriétaire ou un Admin peuvent modifier les secrets accordés. Un Éditeur peut changer les autres champs en conservant ces autorisations. Les valeurs sont chiffrées dans le stockage de l’organisation et ne sont pas renvoyées avec la configuration. L’agent en cours d’exécution reçoit toutefois celles qui lui sont accordées.

Utilise des identifiants limités et remplaçables. Plusieurs agents ou nœuds d’automatisation peuvent partager un même nom de secret. Sa rotation ou suppression affecte donc chaque future exécution qui le référence. Examine ces usages avant de le modifier.

## Appliquer la même vérification aux clients API

L’API publique lit et modifie la même liste d’agents et applique les droits sur le projet du détenteur de la clé. Chaque opération inclut un identifiant de projet. Une mise à jour fournit la configuration complète, y compris les secrets à conserver. Les omettre demande leur retrait et exige donc les mêmes droits administratifs.

L’[exemple API des agents de projet](https://docs.tale.dev/fr/develop/api-reference#gerer-les-agents-dun-projet) décrit l’intégration. Après une modification, rouvre l’agent pour vérifier le modèle, l’équipement et les autorisations enregistrés. Confie-lui ensuite une petite tâche dont une personne peut examiner le résultat. [Agents de projet](https://docs.tale.dev/fr/platform/projects/project-agents) explique ce parcours.

# Clés API
Source: https://docs.tale.dev/fr/platform/admin/api-keys

Crée une clé API lorsqu’un script ou un service doit appeler l’API REST de Tale. Une clé appartient à la personne qui l’a créée, pas à l’organisation depuis laquelle elle a été créée : elle agit au nom de cette personne, suit ses permissions actuelles et fonctionne dans chaque organisation dont elle est membre. Une requête REST nomme l’organisation visée dans l’en-tête `X-Organization-Slug` ; si le détenteur n’appartient qu’à une seule organisation, l’en-tête peut être omis. Les propriétaires, admins et développeurs gèrent leurs clés dans **Paramètres > API > REST**, tout comme un membre à qui un admin a attribué une compétence qui s’utilise avec une clé : **Appeler les modèles par l'API**, **Exporter les notifications** ou **Agir pour un autre membre**. Tale refuse une nouvelle clé à toute autre personne avec `403 API_KEY_CREATE_FORBIDDEN`.

<Frame caption="Paramètres > API > REST — là où les clés sont créées, renouvelées et révoquées.">

![La boîte de création d’une clé API permet de choisir un nom et une durée de validité avant sa génération.](https://docs.tale.dev/images/get-started/settings-api-keys.webp)

</Frame>

## Créer une clé

1. Sélectionne **Créer une clé API**.
2. Saisis un **Nom de la clé** qui identifie le logiciel, par exemple `Synchronisation facturation` ou `Import de documents`.
3. Choisis l’**Expiration** : 7, 30 ou 90 jours, un an, ou jamais. La valeur initiale est 30 jours.
4. Crée la clé et copie sa valeur secrète dans le gestionnaire de secrets prévu pour le logiciel avant de fermer la confirmation.

La valeur complète n’apparaît qu’une fois. Le tableau affiche ensuite un fragment masqué, la date de création et la dernière utilisation. Il présente tes clés, pas celles de tes collègues.

<Warning>

Toute personne qui possède une clé peut agir avec les permissions de son propriétaire. Ne la place pas dans le code source, les chats, les captures d’écran ou les journaux. Utilise un compte dont les accès correspondent aux besoins de l’intégration.

</Warning>

## Vérifier l’appel

Suis la requête authentifiée du [démarrage rapide de l’API](https://docs.tale.dev/fr/get-started/developers). Vérifie l’identité et l’organisation renvoyées avant de lancer une écriture ou un import. Consulte ensuite **Dernière utilisation** dans le tableau des clés.

Une authentification réussie n’autorise pas l’accès à toutes les ressources. Les droits sur les projets et le rôle actuel du propriétaire de la clé restent applicables. En cas d’échec, lis l’erreur de l’API pour distinguer une clé expirée ou révoquée d’une permission manquante sur une ressource.

## Renouveler une clé sans interruption

1. Crée une clé de remplacement avant l’expiration de l’ancienne.
2. Mets à jour le gestionnaire de secrets du logiciel, puis redémarre-le ou recharge sa configuration si nécessaire.
3. Vérifie une requête authentifiée avec la nouvelle clé.
4. Révoque l’ancienne seulement après avoir migré tous les logiciels qui en dépendent.

Tale ne renouvelle pas les clés automatiquement. La création et la révocation passent par cette interface, pas par `/api/v1`. Un logiciel peut consulter le nom et l’expiration de sa clé avec `GET /api/v1/me` et prévenir la personne responsable avant son échéance.

## Révoquer une clé

Dans le menu de sa ligne, sélectionne **Révoquer la clé**, puis confirme. Les requêtes suivantes ne peuvent plus s’authentifier avec cette clé, appels aux endpoints de modèles compris ; une réponse déjà en cours de flux se termine. La révocation est irréversible ; crée une nouvelle clé si tu as révoqué la mauvaise. La création et la révocation d’une clé laissent chacune une entrée dans le journal d’audit, sous **Paramètres > Gouvernance > Journaux**, dans chaque organisation dont tu fais partie.

Une ancienne date de **Dernière utilisation** ne suffit pas à justifier une révocation. Une tâche mensuelle ou une procédure de récupération peut rester longtemps inactive. Vérifie d’abord le logiciel indiqué par le nom de la clé.

## Comprendre les permissions et les limites

Un changement de rôle s’applique aux requêtes suivantes des clés existantes. Désactiver l’adhésion de leur propriétaire retire ses accès ; la clé ne conserve pas le rôle qu’elle avait à sa création. Perdre le rôle ou la compétence qui te permettait de créer des clés laisse en place celles que tu détiens : **Paramètres > API > REST** continue de les lister pour que tu les révoques, mais n’en propose plus de nouvelle.

Donne à une intégration uniquement les accès dont elle a besoin. Un service qui synchronise les notifications n’a par exemple pas besoin d’un compte Admin : un Admin peut accorder à un membre ordinaire la capacité `tale:notifications.export`. Elle permet cet export sans aucun autre droit du rôle Admin, ne vaut que dans l’organisation, peut expirer et prend fin quand le membre est retiré. Attribue-la dans [Compétences](https://docs.tale.dev/fr/platform/admin/governance/competences), où une intégration qui relaie les réponses et les décisions de relecture de personnes reçoit de la même façon `tale:rest.act-as` ; [Déléguer l’export sans rôle Admin](https://docs.tale.dev/fr/develop/api-reference#deleguer-lexport-sans-role-admin) décrit le côté API.

Les limites de débit REST s’appliquent au propriétaire authentifié de la clé. Plusieurs clés d’une même personne ne donnent pas de quotas de débit distincts. Consulte [les limites de débit](https://docs.tale.dev/fr/develop/rate-limits). Une [règle de budget](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits) peut aussi plafonner ce que les requêtes authentifiées par une clé précise peuvent dépenser : leur usage est imputé à la clé, et un envoi ou un appel de modèle au-delà du plafond est refusé avec `429 BUDGET_EXCEEDED`. Les exécutions d’automatisation lancées avec la clé comptent aussi pour elle, en plus des limites personnelles du membre pour lequel la clé agit. [Comment l’usage est compté](https://docs.tale.dev/fr/platform/admin/governance/usage-attribution) décrit la règle complète.

Une clé peut aussi appeler les modèles de l’organisation depuis des outils comme opencode ou Claude Code, par les [endpoints de modèles](https://docs.tale.dev/fr/develop/use-tale-from-your-editor#model-endpoints), dès qu’un admin les a activés dans [Modèles](https://docs.tale.dev/fr/platform/admin/governance/content-models#model-endpoints). La personne qui la détient doit être propriétaire, admin ou développeur, ou détenir **Appeler les modèles par l'API**. Ces appels comptent pour les règles de budget de la clé comme ses messages de chat, et ils apparaissent comme **Appel API direct** dans l’analyse de l’usage, au nom de la personne et de la clé.

Les clés API authentifient les logiciels qui appellent Tale. Les [identifiants des connecteurs](https://docs.tale.dev/fr/platform/admin/connectors) servent dans l’autre sens : ils permettent à Tale d’appeler un service externe. [Utiliser Tale depuis ton éditeur ou un script](https://docs.tale.dev/fr/develop/use-tale-from-your-editor) montre où placer une clé dans opencode, Claude Code et un script shell.

# Personnalisation visuelle
Source: https://docs.tale.dev/fr/platform/admin/branding

Donne à une organisation son logo, ses icônes d’onglet et sa couleur d’accentuation dans **Paramètres > Branding**. Les propriétaires et les admins peuvent modifier ces réglages. Ils concernent l’organisation ouverte : vérifie son nom avant de changer l’apparence partagée.

<Frame caption="Paramètres > Branding — les contrôles de logo, favicon et couleur d’accentuation à côté d’un aperçu en direct de la barre latérale.">

![La page de paramètres Branding avec les téléversements de logo et favicon, un champ de couleur d’accentuation, et un panneau d’aperçu en direct à droite.](https://docs.tale.dev/images/platform/settings-branding.webp)

</Frame>

## Préparer les éléments visuels

| Réglage | Élément à préparer |
| --- | --- |
| **Logo** | Un symbole lisible à la taille de la barre latérale, sur fond clair comme sur fond sombre. SVG est préférable ; une image matricielle devrait mesurer au moins 64 × 64 pixels. |
| **Favicon** | Une petite icône d’onglet reconnaissable. Tu peux fournir une variante claire et une variante sombre. |
| **Couleur d'accentuation** | La couleur hexadécimale de ta marque, à vérifier dans les deux thèmes. Tale en dérive la palette affichée pour le thème courant. |

En l’absence de logo, le nom de l’organisation sert de marque textuelle. Modifie-le dans **Paramètres > Organisation** ; la page de personnalisation n’a pas de champ distinct pour le nom de l’application.

## Charger un logo ou une favicon

Sélectionne l’image dans le champ correspondant. Le chargement ou le retrait d’une image prend effet immédiatement, sans attendre Enregistrer. L’aperçu et l’apparence de l’organisation se mettent à jour lorsque l’opération aboutit.

Sans favicon explicite, Tale peut en créer une à partir du logo chargé. Fournis une icône dédiée si le logo complet devient difficile à reconnaître dans un onglet. Après le chargement, vérifie l’icône et la barre latérale, y compris dans l’autre thème.

<Note>

L’action Abandonner de l’en-tête concerne les modifications du formulaire encore en attente. Elle ne rétablit pas une image déjà chargée ou retirée.

</Note>

## Changer la couleur d’accentuation

Modifie **Couleur d'accentuation** et examine l’aperçu. Sélectionne **Enregistrer** dans l’en-tête pour conserver la modification, ou **Abandonner** pour revenir à la valeur enregistrée. Le champ reflète le thème courant : la couleur dérivée du thème sombre peut donc différer de la valeur stockée pour le thème clair. L’aperçu montre la couleur telle qu’elle apparaîtra une fois enregistrée. Dans le thème sombre, elle peut donc différer de la valeur du champ. Enregistrer une modification, charger une image ou en retirer une laisse chaque fois une entrée dans le journal d’audit, sous **Paramètres > Gouvernance > Journaux**.

Les boutons conservent ta couleur aussi fidèlement que la lisibilité le permet. Les autres repères tracés dans l’accent n’utilisent ta couleur que si elle se lit comme du texte sur la page. Sinon, Tale en prend une nuance plus foncée, ou plus claire dans le thème sombre. Ces repères comprennent un lien, une mention, un renvoi vers une source, l’élément de navigation sélectionné, un point de non-lu, le contour du focus clavier, un interrupteur activé et une barre de progression. Sur un lien ou un interrupteur, une couleur de ton moyen peut donc paraître légèrement différente de celle d’un bouton.

Après l’enregistrement, recharge la page et vérifie un élément de navigation sélectionné, un bouton et le focus au clavier. Une couleur convaincante sur une grande surface peut être difficile à distinguer sur un petit contrôle.

## Vérifier où l’apparence s’applique

La personnalisation s’applique à l’intérieur de l’espace de travail. Changer d’organisation charge l’apparence de la destination. Les pages de connexion s’affichent avant le choix d’une organisation et utilisent l’apparence par défaut de la plateforme.

Si le navigateur montre encore une ancienne icône, recharge la page et vérifie les champs de favicon. Une favicon explicite a priorité sur celle dérivée du logo. Utilise **Réinitialiser** seulement pour retirer la personnalisation enregistrée de l’organisation, après avoir lu la confirmation. La confirmation prend effet immédiatement : les images sont supprimées et la couleur d’accent effacée est enregistrée, sans autre **Enregistrer** et sans rien laisser de non enregistré.

# Nouveautés
Source: https://docs.tale.dev/fr/platform/admin/changelog

Ouvre **Nouveautés** pour lire les notes de version de Tale. Tous les membres connectés peuvent les consulter, sans rôle d’administrateur.

## Ouvrir les notes de version

Utilise **Nouveautés** dans le menu utilisateur ou **Voir** dans une notification de mise à jour. Ouvrir les notes marque la mise à jour comme lue et retire son indicateur. La page présente les versions concernées, ou indique que tu es à jour.

Déplie une version pour lire son numéro, sa date, son titre et ses notes. Repère les changements qui touchent les tâches de ton équipe, puis consulte les guides liés pour retrouver les instructions actuelles.

## Trouver des notes anciennes ou indisponibles

Utilise le lien vers les anciennes versions sur GitHub si le changement recherché dépasse la période affichée. La page récupère les informations publiques de GitHub et les met en cache. Sans accès réseau, un déploiement peut ne pas charger les notes absentes de son cache.

Une version encore non publiée peut ne pas avoir d’entrée correspondante. Consulte l’historique lié : une vue vide ne prouve pas qu’aucun changement n’a eu lieu.

## Distinguer versions et activité de l’organisation

Les notes décrivent les changements de Tale lui-même. Pour savoir qui a modifié les paramètres ou le contenu de ton organisation, consulte plutôt [les journaux d’audit](https://docs.tale.dev/fr/platform/admin/governance/audit-logs).

Si tu exploites un déploiement, suis [le guide de mise à jour](https://docs.tale.dev/fr/self-hosted/operate/upgrades), puis lis les notes pour identifier ce que ton équipe doit savoir.

# Identifiants des connecteurs
Source: https://docs.tale.dev/fr/platform/admin/connectors

Ajoute des identifiants de connecteur pour que Tale utilise une messagerie, un espace de fichiers ou un outil de suivi. Les propriétaires, admins et développeurs les gèrent dans **Paramètres > Connectors**. Choisis le service et le compte nécessaires ; le [catalogue des connecteurs](https://docs.tale.dev/fr/platform/connectors/overview) présente les actions disponibles.

## Connecter un compte

1. Sélectionne **Ajouter des identifiants**, puis le connecteur. Les connecteurs déjà configurés apparaissent en premier et peuvent recevoir d’autres identifiants.
2. Vérifie le champ **Nom**. Il est prérempli avec le nom du connecteur, suivi d’un numéro si d’autres identifiants de ce connecteur portent déjà ce nom : `GitHub`, puis `GitHub 2`. Un nom comme `Boîte support` ou `Boutique UE` est plus facile à reconnaître pour la personne qui prépare l’automatisation. Une connexion OAuth n’a pas de champ de nom : Tale la nomme de la même façon une fois l’accès autorisé (un deuxième espace Slack prend le nom de l’espace), et **Modifier les identifiants** permet de la renommer.
3. Complète la méthode d’authentification proposée. Pour OAuth, sélectionne **Connecter** et autorise l’accès chez le fournisseur. Chaque **Connecter** ajoute de nouveaux identifiants pour le compte autorisé, sans jamais remplacer ceux qui existent. Connecte-toi donc chez le fournisseur avec le compte que tu veux ajouter.
4. Termine le formulaire, puis vérifie la ligne créée : connecteur, compte ou instance, et statut.

Slack associe un seul jeu d’identifiants à chaque espace Slack. Si tu autorises à nouveau un espace déjà connecté, Tale renouvelle ses identifiants au lieu d’en ajouter d’autres.

Le connecteur détermine les champs. Utilise les identifiants du compte externe, pas une clé API Tale.

| Méthode | Informations nécessaires |
| --- | --- |
| Clé API | La clé fournie par le service, par exemple Tavily ou Shopify. Jev decisions demande une clé API OpenRouter. |
| Token | Un jeton du service, comme un token d’accès personnel GitHub, un token de bot Discord ou un token d’API GlitchTip avec `project:read` et `event:read`. |
| Nom d’utilisateur et mot de passe | La paire attendue par le service : connexion et mot de passe d’application, ou identifiant et token propres au fournisseur. |
| OAuth | Une autorisation dans le navigateur du fournisseur, ensuite conservée par Tale. |

Certains connecteurs demandent aussi l’adresse de l’instance. Pour Confluence, utilise l’adresse de base du site Atlassian. Pour GlitchTip, utilise l’origine de l’instance, par exemple `https://app.glitchtip.com` ; une instance auto-hébergée doit aussi être autorisée par la politique des hôtes du connecteur. Pour Shopify, utilise l’adresse `myshopify.com` de la boutique, pas son domaine public destiné aux clients.

## Choisir les identifiants par défaut

Le tableau contient une ligne par jeu d’identifiants et se met à jour sans rechargement tant qu’il est ouvert : ce qu’un autre admin ajoute, modifie ou supprime y apparaît aussitôt. Le badge **Par défaut** indique ceux utilisés lorsqu’une action n’en nomme pas. **Définir par défaut**, dans le menu d’une ligne, change ce choix. Chaque connecteur a un seul choix par défaut.

Sans choix par défaut, un connecteur qui possède plusieurs identifiants peut toujours servir les appels qui les nomment explicitement. Les autres appels ont besoin d’un choix par défaut. Nomme les comptes clairement avant de les utiliser dans des automatisations, pour que leur destination reste compréhensible.

La synchronisation des boîtes et le triage peuvent examiner tous les identifiants actifs d’un connecteur de messagerie. Une deuxième boîte n’a pas besoin de devenir le choix par défaut pour être trouvée par ces opérations. Quand tu rédiges un nouvel e-mail, le champ **Boîte** liste chaque boîte sous son nom, et l’e-mail part de celle que tu choisis. Les réponses dans cette conversation partent de la même boîte, y compris quand tu relances un envoi qui a échoué.

## Renouveler un secret ou suspendre l’accès

Utilise l’action de remplacement adaptée à la méthode, par exemple **Remplacer la clé API** ou **Remplacer le jeton**. Le nouveau secret remplace l’ancien tout en conservant le nom, le choix par défaut et les références. Vérifie ensuite une action appropriée du service.

**Désactiver** suspend les identifiants sans retirer leur configuration ; **Activer** les remet en service. **Modifier les identifiants** permet de changer les autres informations prises en charge, comme le nom ou l’adresse de l’instance.

<Warning>

Supprimer des identifiants retire l’accès aux automatisations et agents qui en dépendent. Migre d’abord les appelants. Si tu supprimes les identifiants par défaut d’un connecteur, ses plus anciens identifiants actifs restants deviennent le choix par défaut, et la confirmation les nomme avant la suppression. Des identifiants désactivés ou à reconnecter ne prennent jamais le relais : s’il ne reste aucun identifiant actif, le connecteur n’a pas de choix par défaut tant que tu n’en choisis pas. Rouvrir la même ligne ne permet pas d’annuler la suppression.

</Warning>

## Préparer une application OAuth

Les propriétaires et les admins utilisent **Apps OAuth**, en bas de page, pour configurer les applications fournisseur utilisées pendant le consentement. Une application propre à l’organisation remplace celle du déploiement. Si aucune n’existe, le connecteur ne peut pas commencer l’autorisation et la page indique qu’il n’est pas configuré.

Sélectionne **Configurer**, renseigne l’identifiant client et le secret du fournisseur, puis enregistre chez celui-ci les URI de redirection exactes affichées dans le dialogue. Une application Microsoft peut aussi demander l’identifiant du répertoire ou du locataire. Lors d’une modification ultérieure, laisse le champ du secret enregistré vide pour le conserver.

L’application Google Drive sert aussi à l’import dans la base de connaissances. L’entrée OneDrive/SharePoint concerne cet import, sans connecteur distinct. L’opérateur du déploiement configure l’application Slack. Lis le [guide du connecteur](https://docs.tale.dev/fr/platform/connectors/overview) concerné avant d’attribuer les permissions fournisseur.

Pour OneDrive/SharePoint, **Utiliser l'app SSO Entra ID** peut copier une inscription SSO existante dans la configuration d’import. Cette copie est ponctuelle : après le renouvellement du secret SSO, refais-la et vérifie l’URI de redirection et les permissions déléguées indiquées dans la confirmation.

## Rétablir une connexion

**Reconnexion requise** signifie que l’autorisation OAuth enregistrée ne peut plus être renouvelée. Sélectionne **Reconnecter** dans le menu de cette ligne et autorise à nouveau le même compte. Tale renouvelle exactement ces identifiants : leur nom, le choix par défaut et les références restent les mêmes, et aucun autre identifiant ne change. **Reconnecter** ne réactive pas des identifiants volontairement désactivés ; **Activer** les remet en service.

Si les identifiants sont supprimés avant la fin de l’autorisation, ou si ton rôle ne te permet plus de gérer les identifiants, Tale n’enregistre rien et en indique la raison. Pour Slack, autorise l’espace que ces identifiants connectent déjà. Tale refuse un autre espace ; connecte-le plutôt avec **Ajouter des identifiants**.

Si la connexion ne démarre pas, vérifie l’application OAuth. Si le fournisseur refuse le retour vers Tale, compare son URI de redirection enregistrée à celle que Tale affiche. Si une action échoue après la connexion, vérifie les droits du compte et les permissions requises pour cette action.

Pour les services sans connecteur intégré, consulte [MCP et les intégrations personnalisées](https://docs.tale.dev/fr/platform/connectors/mcp-servers). Cette page d’identifiants ne permet pas d’enregistrer n’importe quel serveur MCP sortant.

# SSO d’entreprise et provisionnement
Source: https://docs.tale.dev/fr/platform/admin/enterprise-sso

Le SSO d’entreprise permet aux membres de se connecter via ton fournisseur d’identité (IdP). SCIM lui permet de créer, modifier et désactiver des membres sans attendre leur connexion. Une organisation possède une connexion. En tant qu’admin ou propriétaire, tu peux activer la connexion, le provisionnement ou les deux dans **Paramètres > SSO d'entreprise**.

## Avant de commencer

Il te faut l’autorisation d’enregistrer une application chez ton IdP, ses identifiants client ou métadonnées SAML, ainsi que l’adresse publique de Tale utilisée par les membres. Garde une session admin fonctionnelle ouverte pendant les tests pour corriger la configuration si la connexion échoue.

Choisis un **Nom affiché** reconnaissable. Lorsque plusieurs organisations du déploiement ont activé le SSO, il apparaît dans le choix d’organisation sur la page publique de connexion : évite les informations confidentielles ou purement internes.

<Frame caption="Choisis d'abord le protocole. Tale affiche les champs utiles et l'adresse de rappel à enregistrer chez ton fournisseur d'identité.">

![Paramètres SSO d’entreprise avec Microsoft Entra ID sélectionné, une URL de redirection et les champs de l’émetteur et des identifiants client.](https://docs.tale.dev/images/platform/settings-enterprise-sso.webp)

</Frame>

## Choisir le protocole

| Protocole | Quand l’utiliser | Informations à préparer |
| --- | --- | --- |
| **Microsoft Entra ID** | Ton organisation utilise Entra ; la synchronisation facultative des équipes passe par Microsoft Graph. | URL de l’émetteur du tenant, ID client, secret client. |
| **OIDC générique** | Ton fournisseur prend en charge la découverte OpenID Connect. | URL de l’émetteur, ID client, secret client. |
| **OAuth2** | Ton fournisseur n’a pas de document de découverte OIDC. | Identifiants client et URL d’autorisation, de jeton et userinfo. |
| **SAML 2.0** | Ton IdP utilise des assertions SAML. | Métadonnées IdP ou son identifiant d’entité, son URL de connexion et son certificat de signature. |

## Connecter un fournisseur OIDC ou OAuth2

1. Sélectionne le protocole dans Tale et ouvre le **Guide de configuration** pour trouver l’URL de rappel.
2. Enregistre une application web chez ton IdP. Copie exactement l’URL de rappel, avec son schéma, son hôte et son chemin. Enregistre aussi les URL supplémentaires affichées si les membres utilisent plusieurs domaines du déploiement.
3. Renseigne l’ID client et le secret dans Tale. Pour OIDC, saisis l’URL de l’émetteur ; Tale découvre les points de terminaison. Pour OAuth2, saisis toi-même leurs trois URL.
4. Vérifie **Scopes** et **Avancé**. Demande les claims d’identité nécessaires à tes règles de provisionnement. Associe les noms de claims non standard si besoin ; les chemins peuvent contenir des points, comme `realm_access.roles`.
5. Choisis **Tester la connexion**, corrige les erreurs, puis **Enregistrer** dans l’en-tête. Effectue ensuite un vrai test de connexion comme indiqué plus bas.

Pour Entra, utilise un émetteur propre au tenant, comme `https://login.microsoftonline.com/{tenant-id}/v2.0`, enregistre le rappel comme URI de redirection Web et copie la valeur du secret client, pas son ID. Le [guide Microsoft d’enregistrement d’application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) décrit la configuration côté fournisseur. La synchronisation groupes-équipes exige l’autorisation Microsoft Graph `GroupMember.Read.All` et le consentement admin. Les rôles d’application que tu définis dans l’inscription d’application et que tu attribues à des utilisateurs ou groupes dans l’application d’entreprise arrivent dans le jeton de connexion. Une règle **Rôle d'application** correspond donc à la **Valeur** (Value) du rôle, par exemple `Administrator`, sans autorisation Graph supplémentaire.

Pour Google, choisis **OIDC générique** avec l’émetteur `https://accounts.google.com` ; consulte la [configuration OpenID Connect de Google](https://developers.google.com/identity/openid-connect/openid-connect). L’OIDC standard de Google ne fournit pas les appartenances aux groupes. La connexion Google seule ne permet donc pas de synchroniser les groupes avec les équipes.

<Note>
L’import de fichiers Microsoft 365 possède son propre parcours de consentement dans les connaissances. N’ajoute pas `Files.Read` ou `Sites.Read.All` aux scopes SSO pour permettre une simple connexion. Configure l’accès à l’import via les [apps OAuth des connecteurs](/fr/platform/admin/connectors).
</Note>

## Connecter un fournisseur SAML

1. Choisis **SAML 2.0**. Copie l’**URL des métadonnées SP** et l’**URL ACS (réponse)** dans l’application SAML de ton IdP. Utilise les métadonnées du fournisseur de service pour son identifiant d’entité/audience et choisis l’adresse e-mail comme format Name ID.
2. Sous **Importer les métadonnées de l'IdP**, importe l’URL des métadonnées de l’IdP ou choisis **Téléverser le XML**. Vérifie l’identifiant d’entité, l’URL de connexion et le certificat de signature remplis par l’import. Tu peux aussi les saisir manuellement.
3. Sous **Avancé**, associe l’e-mail, le nom et les groupes si l’IdP utilise d’autres noms d’attributs. Garde **Exiger des assertions signées** activé.
4. Enregistre la connexion, puis teste une connexion via l’IdP.

Si ton IdP chiffre les assertions, ajoute un **Certificat SP (PEM)** et une **Clé privée SP (PEM)** correspondants sous **Avancé**. Le certificat est publié dans les métadonnées SP ; la clé privée est conservée comme secret et ne sera plus affichée. Configure le chiffrement dans l’IdP avant d’activer **Exiger des assertions chiffrées**. Tale refuse ce réglage sans clé de déchiffrement et rejette ensuite les assertions non chiffrées.

SAML peut être lancé par l’IdP ou par Tale. Pour une connexion commencée dans Tale, termine dans le même navigateur afin que le rappel puisse vérifier le cookie créé au départ.

## Attribuer les rôles et équipes à la connexion

| Réglage | Ce qu’il contrôle |
| --- | --- |
| **Rôle par défaut** | Rôle des nouveaux membres lorsqu’aucune règle ne correspond ; Membre au départ. |
| **Attribuer automatiquement les rôles depuis l'IdP** | Associe des groupes, rôles d’application, intitulés de poste ou claims aux rôles Tale. Vérifie qui pourrait correspondre à une règle admin avant de l’activer. |
| **Synchroniser les groupes de l'IdP avec les équipes** | Crée ou rejoint les équipes selon les groupes à la connexion. |
| **Exclure des groupes** | Noms de groupes séparés par des virgules à écarter de la synchronisation. |

Les règles de rôle sont vérifiées de haut en bas, et la première qui correspond détermine le rôle. Une personne qui correspond à plusieurs règles, par exemple avec les rôles d’application `Administrator` et `Employee`, reçoit le rôle de la règle placée le plus haut, pas forcément le rôle qui donne le plus de droits. Place donc en premier les règles les plus privilégiées : fais glisser une règle par sa poignée ou utilise ses flèches **Monter** et **Descendre**, puis enregistre.

Quand des groupes disparaissent, la synchronisation retire les appartenances qu’elle avait ajoutées et supprime les équipes qu’elle avait créées une fois vides. Elle préserve les appartenances créées manuellement ou par SCIM et laisse les groupes exclus tels quels. La page [Équipes](https://docs.tale.dev/fr/platform/admin/teams) décrit la gestion manuelle.

## Provisionner les membres par SCIM

1. Dans **Provisionnement SCIM**, choisis **Générer un jeton** et copie-le immédiatement : il n’est affiché qu’une fois.
2. Renseigne ce jeton comme identifiant Bearer et l’**URL de base SCIM** affichée dans la configuration de provisionnement de ton IdP.
3. Provisionne un utilisateur et un groupe de test. Vérifie que le membre et l’équipe apparaissent dans Tale, puis teste les modifications et la désactivation avant d’élargir le déploiement.

Les Users SCIM correspondent aux membres et les Groups aux équipes. La désactivation (`active: false`) bloque l’accès du membre ; la réactivation restaure son rôle précédent. Supprimer un utilisateur SCIM retire son appartenance à l’organisation mais conserve son compte. Un nouveau provisionnement lui attribue le rôle par défaut de la connexion.

Le propriétaire de l’organisation ne peut pas être désactivé ni retiré par SCIM. Les groupes ne peuvent contenir que des membres de cette organisation. Un changement de nom d’utilisateur est refusé si la nouvelle adresse e-mail est déjà utilisée ou si le compte appartient à plusieurs organisations, afin de protéger son identité de connexion partagée.

## Connecter les membres via un proxy d’authentification

Une application qui authentifie déjà ses utilisateurs peut les faire entrer dans cette organisation via son reverse proxy, sans que les membres voient le formulaire de connexion de Tale. La carte **En-têtes de confiance**, sur la même page, regroupe l’interrupteur, le plafond de rôle et les clés que le proxy présente.

1. Active **Accepter les connexions d’un proxy de confiance** et choisis le **Rôle le plus élevé qu’un proxy peut attribuer**. L’en-tête de rôle est plafonné à ce rôle ; le rôle Propriétaire ne peut jamais être attribué. À chaque connexion, le siège du membre suit le rôle attribué ; un siège Propriétaire ne change jamais.
2. Sélectionne **Créer une clé**, nomme-la d’après le proxy qui la détiendra et copie-la immédiatement : elle ne s’affiche qu’une fois. Une organisation détient au plus 10 clés actives.
3. Configure le proxy pour qu’il envoie ses connexions à l’**URL de passage**, avec la clé dans l’en-tête de clé et les en-têtes d’identité listés sous **Noms des en-têtes**. Un membre qui arrive par le proxy est connecté dès la première requête de l’application et ne voit jamais de page de connexion ; l’application ne lui propose pas de déconnexion, puisque le proxy possède cette session. Faire pointer `/log-in` du proxy vers la même adresse reste possible.

Pour afficher les pages dans la page de l’application elle-même, active **Autoriser l’affichage dans un cadre** sous **Intégration dans un cadre** et liste l’origine de la page sous **Origines autorisées** ; Tale admet alors cette origine comme ancêtre de cadre. Un cadre ne porte la session connectée que si la page englobante est sur le même site que Tale.

La clé détermine l’organisation : un membre est connecté, une adresse que Tale n’a jamais vue devient un nouveau membre avec le rôle attribué, et un compte existant d’une autre organisation est refusé. Désactiver l’interrupteur refuse toutes les clés sans en révoquer aucune. **Révoquer** marque une clé afin que le proxy ne puisse plus connecter personne ; les sessions déjà ouvertes restent connectées. La [configuration de l’authentification](https://docs.tale.dev/fr/self-hosted/configuration/authentication) côté opérateur décrit les noms d’en-têtes et les exigences du proxy.

## Vérifier et résoudre les problèmes

Ouvre une session de navigateur séparée et choisis **Continuer avec SSO**. Le choix d’organisation n’apparaît que si plusieurs organisations du déploiement ont activé le SSO ; sélectionnes-y l’organisation grâce à son nom d’affichage. Sinon, le bouton ouvre directement le fournisseur d’identité de la seule organisation activée, et une adresse saisie dans le champ e-mail n’est transmise que comme indice de connexion : Tale n’oriente pas selon le domaine de l’e-mail. Termine la connexion et vérifie le rôle et les équipes obtenus. **Tester la connexion** vérifie les paramètres de connexion, sans prouver qu’une personne reçoit les bons accès.

| Symptôme | Points à vérifier |
| --- | --- |
| Redirection incorrecte, notamment `AADSTS50011` | Compare le rappel enregistré à l’URL exacte de Tale : domaine, schéma, chemin et barre oblique finale. |
| Échec du test de connexion | Vérifie l’émetteur/les points de terminaison, l’ID client, la valeur et l’expiration du secret, ainsi que le consentement requis chez le fournisseur. |
| Erreur de liaison au navigateur | Recommence dans le même navigateur et autorise les cookies nécessaires aux redirections. |
| Mauvais rôle ou équipe absente | Vérifie les claims réellement fournis, les règles de rôles et leur ordre, les exclusions et les autorisations de groupes. Une règle **Rôle d'application** correspond à la valeur du rôle d’application, pas à son nom d’affichage ni à son ID. |
| SCIM ne se connecte pas | Vérifie l’URL de base, le jeton Bearer et l’activation du provisionnement. |
| La connexion par proxy est refusée | Vérifie que la carte est activée, que la clé n’est pas révoquée et que le proxy envoie l’en-tête d’e-mail et la clé dans la requête de passage. |
| URL de rappel absente ou avertissement de configuration serveur | Demande à l’opérateur de vérifier la [configuration de l’authentification](https://docs.tale.dev/fr/self-hosted/configuration/authentication). |

**Désactiver la connexion** empêche les nouvelles connexions SSO mais conserve les sessions actives. **Supprimer** efface la configuration de la connexion et ses identifiants. Prévois une autre méthode de connexion fonctionnelle avant d’utiliser l’une de ces actions.

# Journaux d’audit
Source: https://docs.tale.dev/fr/platform/admin/governance/audit-logs

En tant qu’admin ou propriétaire, ouvre **Paramètres > Gouvernance > Journaux** pour examiner les actions enregistrées dans ton organisation. Repère d’abord l’événement et sa date, puis son acteur, sa cible, son résultat et les détails disponibles.

## Retrouver un changement

1. Choisis **Journaux d'audit** et ouvre **Filtre**.
2. Sélectionne une catégorie adaptée, comme les changements de membres, la sécurité ou les données.
3. Repère l’événement par sa date, son action et sa cible. Ouvre sa ligne pour consulter les détails.
4. Vérifie le statut : une tentative refusée ou échouée ne prouve pas que le changement a eu lieu.

L’onglet actif et la catégorie figurent dans l’URL : tu peux enregistrer la vue dans tes favoris. L’accès dépend toujours de tes permissions dans l’organisation.

<Frame caption="Gouvernance > Journaux : l’onglet Journaux d’audit limité à la catégorie Membre. Tout effacer retire le filtre.">

![La page Journaux avec l’onglet Journaux d’audit filtré sur la catégorie Membre : onze événements où Alex Rivera a ajouté des membres, créé trois équipes et ajouté un membre à chacune, chaque ligne indiquant la ressource, la cible, la catégorie et le statut Success.](https://docs.tale.dev/images/platform/governance-audit-logs.webp)

</Frame>

## Lire un événement

| Champ | Ce qu’il faut examiner |
| --- | --- |
| Horodatage | Quand Tale a enregistré l’action. |
| Action | L’opération tentée ou terminée. Certaines actions récentes apparaissent sous leur nom technique. |
| Utilisateur | La personne ou l’acteur système responsable. |
| Ressource et cible | Le type d’élément et l’enregistrement concerné. |
| Catégorie | Le groupe utilisé par le filtre. |
| Statut | Réussite, échec ou refus. |
| Vue détaillée | États précédent/nouveau, champs modifiés, métadonnées et erreurs disponibles. Tous les événements ne contiennent pas tous les champs. |

Le journal atteste les événements qu’il enregistre. Il ne constitue pas une copie complète des conversations, des réponses des fournisseurs ou de l’activité des services externes.

## Choisir le bon onglet

**Journaux d'audit** contient les événements individuels ; le tableau en charge davantage au défilement, et son pied de page indique combien d’événements sont chargés jusque-là, si bien qu’un total ne représente tout l’historique que lorsque le pied de page le dit. La vue des blocages de connexion aide à examiner les verrouillages. Les journaux d’activité résument les actions et leurs résultats sur une période : la période choisie dans le **Filtre** (7, 30 ou 90 jours) est nommée au-dessus des totaux, et chaque nombre de l’onglet ne couvre que cette période. Les journaux d’erreurs se concentrent sur les échecs et peuvent être filtrés par catégorie.

Si un membre ne peut pas se connecter, commence par les blocages et le [guide de sécurité du compte](https://docs.tale.dev/fr/platform/admin/two-factor-authentication). Pour un changement de configuration inattendu, consulte l’événement d’audit et ses détails.

## Exporter les résultats

Définis le filtre de catégorie, puis ouvre **Exporter** et choisis CSV ou JSON. Le CSV fournit des colonnes pour tableur : horodatages UTC, identifiants des acteurs et ressources, statuts et erreurs. Le JSON conserve les objets d’événement plus complets, dont les détails de changement et les empreintes d’intégrité disponibles.

Les exports respectent le filtre de catégorie et contiennent au maximum 10 000 lignes, des plus récentes aux plus anciennes. Ils sont générés sur le serveur et téléchargés via un lien temporaire. Un export filtré ou plafonné reste une sélection : ce n’est pas forcément tout l’historique d’audit ni une chaîne d’empreintes complète.

## Rétention et intégrité

Choisis **Vérifier maintenant** dans la section d’intégrité de la chaîne pour contrôler la chaîne d’audit stockée. Le panneau affiche son statut et la dernière vérification automatique. Si une rupture est signalée, conserve ses détails et examine-la avec l’opérateur avant de t’appuyer sur cette partie de l’historique.

Une vérification réussie couvre les enregistrements conservés qu’elle a examinés. Elle n’établit pas une origine de l’historique signée de façon indépendante. Le [guide d’intégrité pour l’exploitation](https://docs.tale.dev/fr/self-hosted/operate/security/audit-log-integrity) décrit les contrôles et leurs limites.

Le chaînage par empreintes aide à détecter les changements des enregistrements stockés. Il ne prouve pas que toute action possible a été enregistrée. La rétention de l’audit se configure dans [Politiques et limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits). Vérifie la règle active et les bornes du déploiement sans supposer une durée fixe. Des entrées d’audit récupérables peuvent apparaître dans la [Corbeille](https://docs.tale.dev/fr/platform/admin/governance/trash). Le nettoyage définitif limite l’historique disponible ici.

Le nettoyage de rétention planifié consigne ici chacun de ses cycles sous forme d’événements système de la catégorie **Données** : son démarrage, le nombre d’éléments supprimés dans chaque catégorie, et s’il s’est terminé ou a échoué.

# Compétences
Source: https://docs.tale.dev/fr/platform/admin/governance/competences

En tant qu’admin ou propriétaire, tiens le registre des compétences de ton organisation dans **Paramètres > Gouvernance > Compétences**. Une compétence est l’une de ces deux choses :

- Une **capacité de la plateforme** permet à un membre une seule action bien délimitée qui demanderait sinon un rôle plus élevé. Attribue-la au compte qui se trouve derrière une intégration plutôt que d’en faire un admin, ce qui lui permettrait aussi de gérer les membres, l’authentification unique et les mots de passe.
- Une **qualification** est un nom que la politique de relecture de ton organisation peut exiger de la personne qui approuve une relecture.

Une attribution ne s’applique que dans cette organisation. Tale enregistre chaque attribution et chaque révocation dans le journal d’audit, et retirer un membre de l’organisation révoque ses attributions.

## Capacités de la plateforme

| Capacité                                                     | Ce qu’elle permet                                                                                                                                                                                                    |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Exporter les notifications** (`tale:notifications.export`) | Lire par l’API REST les notifications qu’un autre membre peut voir, pour qu’une autre application les reflète.                                                                                                       |
| **Agir pour un autre membre** (`tale:rest.act-as`)           | Nommer, dans un appel d’API, le membre pour qui une question reçoit une réponse ou une relecture est décidée. La chronologie de la tâche et le journal d’audit indiquent alors cette personne plutôt que la clé API. |
| **Publier des skills pour l'organisation** (`tale:skills.publish`) | Partager un skill avec toute l’organisation, même quand la [politique de partage des skills](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits#skill-sharing) le réserve aux éditeurs ou aux admins. |
| **Appeler les modèles par l'API** (`tale:models.api`) | Appeler les modèles de l’organisation depuis ses propres outils avec une clé API personnelle, par les [endpoints de modèles](https://docs.tale.dev/fr/develop/use-tale-from-your-editor#model-endpoints), une fois que l’organisation les a activés. Ouvre aussi **Paramètres > API** avec ses onglets **REST** et **Modèles**, pour créer la clé et consulter la configuration. |

Les propriétaires et les admins ont les quatre par leur rôle ; les développeurs ont aussi **Appeler les modèles par l'API** par le leur. Tout autre membre a besoin de l’attribution ici, par exemple un compte Développeur dont une intégration utilise la clé API pour un export. Sans elle, l’API REST répond à un export ou à un `actor` par `403 ROLE_FORBIDDEN`, et les endpoints de modèles répondent `403 MODEL_API_FORBIDDEN`. La [référence de l’API](https://docs.tale.dev/fr/develop/api-reference#nommer-le-membre-pour-lequel-on-agit) décrit les requêtes d’export et d’`actor`.

**Exporter les notifications**, **Agir pour un autre membre** et **Appeler les modèles par l'API** s’utilisent avec une clé API personnelle ; chacune permet donc aussi à qui la détient d’en créer une dans **Paramètres > API > REST**. La clé agit avec le rôle de son détenteur ; la compétence n’ajoute que son propre droit.

**Publier des skills pour l'organisation** ne compte que tant que la politique de partage des skills réserve les skills partagés avec l’organisation. Avec **Éditeurs et au-delà**, les éditeurs et les développeurs l’ont déjà par leur rôle. Sans elle, un membre ne peut partager des skills qu’avec ses propres équipes ; l’éditeur de skills, les téléversements et l’API REST refusent un skill partagé avec l’organisation par `403 SKILL_PUBLISH_FORBIDDEN`.

**Appeler les modèles par l'API** ne prend effet que lorsque l’organisation a activé les endpoints de modèles dans [Modèles](https://docs.tale.dev/fr/platform/admin/governance/content-models#model-endpoints). Un membre qui la détient ouvre **Paramètres > API** avec les onglets **REST** et **Modèles**, pour créer une clé personnelle et copier la configuration ; les onglets **MCP** et **WebDAV** restent réservés aux propriétaires, admins et développeurs. Une fois l’attribution révoquée, Tale refuse l’appel de modèle suivant du membre.

## Attribuer une compétence

1. Choisis **Attribuer une compétence**.
2. Choisis le **Membre**.
3. Choisis la **Compétence** : une capacité de la plateforme, ou **Qualification**, puis saisis dans **Nom de la qualification** le nom utilisé par ta politique de relecture. Les noms qui commencent par `tale:` sont réservés aux capacités de la plateforme.
4. Choisis quand elle **Expire** : **Jamais**, **Dans 30 jours**, **Dans 90 jours** ou **Dans 1 an**.
5. Si tu le souhaites, note le **Justificatif** : pourquoi ce membre la détient, par exemple un certificat, un ticket ou le système qu’elle sert. Il reste dans le registre.
6. Choisis **Attribuer**.

L’attribution s’applique à la requête suivante du membre ; une intégration n’a pas besoin de redémarrer. Un membre détient chaque compétence une seule fois à la fois : pour en changer l’expiration ou le justificatif, révoque l’attribution et attribue-la à nouveau. Si le membre la détient déjà, la boîte de dialogue le signale et n’attribue rien.

## Révoquer une compétence

Choisis **Révoquer** sur la ligne et confirme avec **Révoquer**. Le membre perd la compétence immédiatement. L’attribution reste dans le registre comme historique, avec le statut **Révoquée** et la date de révocation ; survole la date pour voir qui l’a révoquée.

## Lire le registre

La liste s’ouvre sur les attributions **Active**. Utilise **Filtre > Statut** pour ajouter les attributions **Expirée** et **Révoquée**, ou choisis **Tout effacer** pour toutes les voir.

| Statut       | Signification                                                                                                                                                |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Active**   | Le membre détient la compétence. La ligne en dessous indique sa date d’expiration, ou **Sans expiration**.                                                   |
| **Expirée**  | La date d’expiration, affichée sous le statut, est passée. Attribue-la à nouveau si le membre en a encore besoin.                                            |
| **Révoquée** | Un admin ou un propriétaire l’a révoquée, ou une nouvelle attribution l’a remplacée après son expiration. La date de révocation est affichée sous le statut. |

Retirer un membre révoque chaque attribution active qu’il détient — capacités comme qualifications –, de sorte qu’un membre réintégré repart sans elles. Une attribution révoquée dont le titulaire a quitté l’organisation l’indique comme **Ancien membre**. Le registre liste toutes les attributions actives et expirées, et comme historique les 1 000 dernières révoquées.

<Tip>

Une intégration peut vérifier sa propre clé avec `GET /api/v1/me` : `capabilities.actAs`, `capabilities.notificationExport`, `capabilities.skillPublish` et `capabilities.modelApi` indiquent si la clé peut utiliser chaque capacité, par son rôle ou par une attribution ; `capabilities.modelApi` exige en plus que les endpoints de modèles soient activés.

</Tip>

# Modèles
Source: https://docs.tale.dev/fr/platform/admin/governance/content-models

En tant qu’admin ou propriétaire, utilise **Paramètres > Gouvernance > Modèles** pour choisir les modèles proposés au départ et ceux que les membres peuvent utiliser. Les valeurs par défaut orientent le choix ; les règles d’accès imposent une restriction. Configure d’abord les [identifiants fournisseur](https://docs.tale.dev/fr/platform/admin/providers) pour rendre les modèles souhaités disponibles.

## Définir un modèle par défaut

1. Sous **Modèles par défaut**, choisis **Ajouter une règle**.
2. Choisis la portée par défaut comme base, un rôle ou une équipe. Sélectionne la cible si nécessaire.
3. Choisis un fournisseur et un modèle, puis **Confirmer**. Enregistre les changements en attente dans l’en-tête.
4. Démarre un chat en tant que membre du groupe cible, avec le modèle sur **Auto**, puis vérifie le modèle effectivement choisi.

Le modèle par défaut s’applique lorsqu’aucun modèle n’a été choisi explicitement. Une règle d’équipe passe avant une règle de rôle, puis vient la valeur par défaut générale ; si une personne appartient à plusieurs équipes dotées d’une règle, la première règle d’équipe correspondante du tableau l’emporte (voir [Comment les règles se combinent](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits#how-rules-combine)). Elle n’empêche pas de sélectionner un autre modèle autorisé.

## Limiter l’accès aux modèles

Sous **Accès aux modèles**, choisis le mode et ajoute des règles pour les personnes, équipes, rôles ou la portée par défaut à couvrir.

| Mode | Effet d’une règle correspondante |
| --- | --- |
| Liste d’autorisation | Seuls les modèles autorisés dans la liste sont utilisables ; un modèle bloqué reste refusé. |
| Liste de blocage | Les modèles sont permis sauf s’ils figurent parmi les modèles bloqués. |

Les règles individuelles passent avant celles des équipes, puis des rôles et enfin la règle par défaut. Plusieurs règles d’équipe correspondantes combinent leurs listes ; un blocage explicite reste prioritaire pour le modèle. Si aucune règle ne correspond, la politique ne restreint pas cette personne. Ajoute une règle de base pour couvrir tout le monde.

Pour le chat, l’accès est vérifié à l’utilisation, même pour un modèle choisi explicitement ou fixé. Le modèle par défaut doit aussi passer cette vérification. S’il est refusé, la sélection automatique peut se rabattre sur un modèle autorisé. L’éditeur signale les contradictions entre modèle par défaut et accès. Corrige-les pour que le modèle par défaut prévu soit réellement utilisé.

<Tip>
Après un changement, teste les deux cas pour le membre concerné : un modèle autorisé doit fonctionner et un modèle interdit doit être refusé. Tester uniquement avec un compte admin ne prouve pas une règle propre à un rôle.
</Tip>

### Ouvrir les modèles de l’organisation aux clés API {#model-endpoints}

**Endpoints de modèles pour les clés API** permet aux personnes autorisées d’utiliser les modèles que cette politique autorise depuis leurs propres outils, comme opencode, Claude Code ou des scripts écrits avec les SDK OpenAI ou Anthropic, avec une clé API personnelle et via des endpoints compatibles OpenAI et Anthropic. Ce réglage est désactivé par défaut. Active l’interrupteur **Endpoints de modèles pour les clés API** ; la modification est enregistrée aussitôt.

- **Qui peut appeler.** Les propriétaires, admins et développeurs par leur rôle. Tout autre membre seulement avec la compétence **Appeler les modèles par l'API**, attribuée dans [Compétences](https://docs.tale.dev/fr/platform/admin/governance/competences).
- **Quels modèles.** Les modèles de chat que servent tes identifiants de fournisseur avec clé API ou variable d’environnement, restreints par les modèles autorisés de chaque identifiant. Les règles d’accès ci-dessus s’appliquent à chaque appel, pour la personne dont la clé l’a envoyé. L’interrupteur agit indépendamment de **Activer la politique d'accès aux modèles** : quand cette politique est désactivée, seuls les modèles autorisés des identifiants restreignent la liste.
- **Ce que chaque appel traverse.** Les budgets de [Politiques et limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits) et les garde-fous d’entrée de [Garde-fous](https://docs.tale.dev/fr/platform/admin/governance/guardrails#model-endpoints). Les réponses des modèles ne sont pas filtrées.
- **Où il apparaît.** Chaque appel est imputé à la personne et à la clé, comme **Appel API direct** dans l’[analyse de l’usage](https://docs.tale.dev/fr/platform/admin/governance/usage-analytics).

<Frame caption="Gouvernance > Modèles — les endpoints de modèles pour les clés API, activés.">

![La section Endpoints de modèles pour les clés API de la page Modèles, interrupteur activé, qui explique que les propriétaires, les admins, les développeurs et les membres ayant la compétence Appeler les modèles par l'API peuvent utiliser les modèles de l’organisation depuis leurs propres outils.](https://docs.tale.dev/images/platform/governance-model-endpoints.webp)

</Frame>

Désactiver l’interrupteur fait refuser l’appel suivant avec `403 MODEL_API_DISABLED`. [Utiliser Tale depuis ton éditeur ou un script](https://docs.tale.dev/fr/develop/use-tale-from-your-editor#model-endpoints) montre aux membres comment connecter leurs outils.

## Choisir le modèle qui lit les images

Un agent textuel a besoin d’aide pour lire une image, comme une capture d’écran ou une page scannée. La section du modèle de vision choisit celui qui la décrit pour l’agent. Un agent dont le propre modèle lit les images les lit lui-même ; le modèle de vision sert encore les outils d’image que les scripts et agents de code appellent dans leur bac à sable, comme la transcription par lots de pages scannées. Chaque agent géré en reçoit donc un dès qu’un modèle accessible existe.

Laisse la sélection du modèle de lecture sur automatique pour suivre le catalogue disponible. Tale préfère un modèle de vision recommandé, puis une option accessible peu coûteuse. Le texte sous la sélection indique le choix actuel et sa raison.

Fixe un modèle si tu souhaites un choix stable. La sélection propose des modèles capables de lire les images. Si le modèle fixé devient indisponible, rétablis son accès fournisseur ou choisis explicitement **Automatique**, puis enregistre. Tale ne remplace pas silencieusement un modèle fixé. Vérifie le choix après une rotation des identifiants ou un changement de disponibilité.

## Laisser les agents générer des images {#let-agents-generate-images}

La **génération d’images** permet aux [agents de projet](https://docs.tale.dev/fr/platform/projects/project-agents) qui traitent des tâches et aux nœuds agent des [automatisations](https://docs.tale.dev/fr/platform/automations/concepts) de créer des images, par exemple la couverture d’un rapport ou un visuel de campagne. Elle reste désactivée tant que tu ne l’actives pas. Le chat ne crée jamais d’images : un membre qui en a besoin confie une tâche à un agent de projet.

1. Active **Laisser les agents générer des images**. L’interrupteur enregistre aussitôt.
2. Laisse **Modèle d'images** sur **Automatique**, ou choisis un modèle et enregistre les modifications en attente dans l’en-tête de la page.
3. Vérifie la ligne sous la sélection. Elle nomme le modèle avec lequel les agents créent les images.

<Frame caption="Gouvernance > Modèles — la génération d’images activée, avec un modèle d’image fixé.">

![La section Génération d'images avec son interrupteur activé, le sélecteur Modèle d'images réglé sur OpenRouter · google/gemini-2.5-flash-image et la ligne en dessous qui nomme le modèle qu’utilisent actuellement les agents.](https://docs.tale.dev/images/platform/governance-image-generation.webp)

</Frame>

**Automatique** prend le premier modèle d’une courte liste recommandée que tes identifiants fournisseur atteignent : Gemini 2.5 Flash Image, GPT Image 1 Mini, GPT Image 1, puis FLUX.2 Pro. Tale tient compte pour cela des identifiants OpenRouter et OpenAI. La sélection liste chaque modèle d’images que tes identifiants peuvent servir, y compris ceux d’autres fournisseurs compatibles. Un modèle choisi reste fixé jusqu’à ce que tu le changes ; s’il devient indisponible, Tale le signale et ne passe pas à un autre modèle. Désactiver la génération d’images conserve le modèle choisi pour la prochaine activation.

Tant que la génération d’images est activée et qu’un modèle est disponible, chaque agent qui commence à travailler dans un environnement doté du canal MCP de Tale reçoit un outil pour les images. Les agents des autres environnements, et tous les agents quand la génération d’images est désactivée, ne voient pas du tout cet outil ; [Choisir un environnement d’agent](https://docs.tale.dev/fr/platform/agents/harnesses) indique quels environnements disposent de ce canal. La désactivation refuse aussi la prochaine demande d’image d’un agent déjà en cours. Un agent range ses images parmi ses fichiers : celles d’une tâche apparaissent dans ses fichiers produits, celles d’une étape d’automatisation dans la sortie de l’étape.

Les images existent en trois formats : carré, paysage en 3:2 et portrait en 2:3. Un agent qui demande un autre format, par exemple une bannière en 16:9, reçoit celui qui a la même orientation. Le modèle d’images fixe la taille exacte en pixels, et l’outil pour les images indique à l’agent la taille de chaque image qu’il a enregistrée.

Chaque image est facturée à ton organisation et compte, comme le reste de l’exécution, pour la personne qui l’a lancée. Un tour d’agent crée au plus 16 images, une requête à la fois, et ses images puisent dans la même enveloppe que l’usage du modèle pendant ce tour : le coût de chaque image est retiré de ce que le modèle peut encore dépenser, et une fois l’enveloppe épuisée, Tale refuse l’image suivante. Une limite de budget qui s’applique à cette personne refuse l’image avant l’appel au modèle d’images. Fixe des limites de coût ou de requêtes pour les images dans [Politiques et limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits) ; [Comment l’usage est compté](https://docs.tale.dev/fr/platform/admin/governance/usage-attribution) explique pour qui chaque image compte. Le fichier de politique et les endpoints d’images personnalisés sont décrits dans la [référence des fournisseurs auto-hébergés](https://docs.tale.dev/fr/self-hosted/configuration/providers#configure-image-generation).

## Fournir un agent standard {#standard-agent}

Seuls les éditeurs et les rôles supérieurs peuvent ajouter des agents à un projet. Pour qu’un projet sans agents puisse quand même confier du travail à un agent, Tale y propose l’**agent standard** de l’organisation : toute personne qui peut ouvrir le projet peut lui confier une tâche, membres compris. Il est activé par défaut.

<Frame caption="Gouvernance > Modèles — l’agent standard, activé, avec son harness et son modèle choisis automatiquement.">

![La section de l’agent standard : l’interrupteur est activé, le harness et le modèle sont réglés sur automatique, et le champ des instructions est vide et renvoie aux instructions intégrées. La dernière ligne indique qu’il fonctionne pour toi avec Claude Code et Claude Haiku 4.5.](https://docs.tale.dev/images/platform/governance-standard-agent.webp)

</Frame>

- **Où il apparaît.** Dans un projet sans agents, **Assigné à** propose l’option **Agent standard**, et [Créer une tâche depuis le chat](https://docs.tale.dev/fr/platform/chat/basics#create-task-from-chat) l’assigne pour toi. Tale le met en place dans un projet dès que quelqu’un l’y choisit ou y confie la tâche d’un chat. L’onglet **Agents** du projet l’affiche ensuite avec le badge **Standard** ; [L’agent standard](https://docs.tale.dev/fr/platform/projects/project-agents#standard-agent) explique son fonctionnement.
- **Avec quoi il fonctionne.** Quand **Harness** et **Modèle** sont sur **Automatique**, Tale choisit un modèle recommandé que la personne qui lance la tâche peut utiliser selon tes règles d’[accès aux modèles](https://docs.tale.dev/fr/platform/admin/governance/content-models#limiter-lacces-aux-modeles), et le fait tourner avec Claude Code, ou avec le harness auquel un modèle d’abonnement est lié. La ligne en bas de la section indique avec quoi il fonctionne pour toi. Choisis un harness ou un modèle pour l’imposer à tout le monde, puis enregistre les modifications en attente dans l’en-tête de la page.
- **Ce qu’il sait.** Ses instructions intégrées lui demandent de faire ce que la tâche demande avec ses fichiers et ses commentaires, de livrer comme résultat de la tâche le document, la présentation, le tableur ou le PDF demandé, d’écrire dans la langue de la tâche et de poser sa question dans un commentaire quand la tâche n’est pas claire. Le texte saisi sous **Instructions** les remplace.
- **Ce qu’il peut utiliser.** Les skills de documents `docx`, `pptx`, `xlsx` et `pdf` accessibles au projet, mais aucun des connecteurs, opérations de la plateforme ou secrets qu’un éditeur peut accorder à d’autres agents.

Chaque exécution démarre avec les réglages en vigueur à ce moment-là ; un agent en cours garde ceux avec lesquels il a démarré. Un modèle choisi reste en vigueur même s’il devient indisponible, tout comme un modèle que l’accès aux modèles d’une personne lui refuse : l’agent standard ne démarre alors pas pour elle et indique pourquoi, et Tale ne passe pas à un autre modèle. Choisis un autre modèle ou **Automatique** et enregistre. Si aucun modèle qu’une personne peut utiliser ne peut le faire fonctionner, il ne démarre pas non plus pour elle : ajoute un accès dans [Fournisseurs IA](https://docs.tale.dev/fr/platform/admin/providers), ou vérifie son accès aux modèles.

Désactive **Fournir un agent standard** pour ne plus le proposer ; la modification s’enregistre aussitôt et conserve tes choix. Les projets sans agents ne proposent alors aucun agent, et les tâches déjà confiées à un agent standard ne peuvent démarrer qu’une fois que tu le réactives. Le fichier de politique est décrit dans la [référence des fournisseurs auto-hébergés](https://docs.tale.dev/fr/self-hosted/configuration/providers#configure-the-standard-agent).

## Choisir le modèle de transcription audio

**Modèle de transcription audio** contrôle la transcription serveur des pièces jointes audio et vidéo, le recours à l’audio pour les liens vidéo sans sous-titres utilisables et la dictée dans les navigateurs sans reconnaissance vocale intégrée. La reconnaissance vocale du navigateur utilise son propre service et garde la priorité lorsqu’elle est prise en charge.

<Frame caption="La transcription audio a sa propre sélection à l’échelle de l’organisation, automatique ou fixée sur un modèle.">

![La section de transcription audio affiche la sélection automatique et indique le modèle actuellement utilisé par le serveur.](https://docs.tale.dev/images/platform/governance-content-models.webp)

</Frame>

Si ton accès OpenRouter par défaut est actif, ses modèles de reconnaissance vocale sont aussi disponibles ici. Tale les découvre dans le catalogue OpenRouter. Vérifie que les modèles autorisés pour cet accès incluent le modèle de transcription souhaité, puis utilise **Automatique** ou sélectionne ce modèle explicitement.

1. Dans **Modèle qui transcrit l'audio**, laisse **Automatique** pour que Tale choisisse un modèle compatible disponible, ou sélectionne un fournisseur et un modèle précis.
2. Enregistre les changements en attente dans l’en-tête. Avant l’enregistrement, la sélection reste un brouillon ; abandonne-le pour conserver le réglage enregistré.
3. Vérifie le modèle actuel affiché sous la sélection. Teste un court enregistrement avant de compter sur cette configuration pour importer un fichier plus long.

Un changement de modèle s’applique aux nouvelles transcriptions ; les pièces jointes déjà traitées conservent leur texte. Importer à nouveau les mêmes octets réutilise le travail terminé pour la même cible de transcription, mais relance la transcription si le fournisseur ou le modèle cible diffère.

Une sélection explicite reste fixe. Si ce modèle devient indisponible, Tale le signale et ne passe pas à un autre modèle. Choisis un autre modèle disponible ou **Automatique**, puis enregistre. Si aucun modèle compatible n’est disponible, configure un accès actif dans [Fournisseurs IA](https://docs.tale.dev/fr/platform/admin/providers) et vérifie les modèles autorisés pour cet accès. Si Tale ne peut momentanément pas vérifier la configuration, réessaie plutôt que de changer de modèle pour cette raison.

Si la transcription serveur indisponible empêche un membre de dicter ou de joindre de l’audio ou de la vidéo, une boîte de dialogue explique le problème et peut être fermée. Selon ses droits, un lien mène aux réglages ou un message lui demande de contacter un admin. Une vérification de disponibilité ayant échoué temporairement peut être relancée. Pour gérer ce choix par la configuration du déploiement ou utiliser un endpoint audio personnalisé, consulte la [référence des fournisseurs auto-hébergés](https://docs.tale.dev/fr/self-hosted/configuration/providers#configurer-la-transcription-audio).

## Expliquer un choix inattendu

Vérifie les rôles et équipes du membre, le choix explicite dans le chat, le modèle par défaut correspondant, la règle d’accès et la liste de modèles des identifiants fournisseur. Une entrée au catalogue ne prouve pas que l’organisation dispose d’identifiants utilisables. Les plafonds de coût et de tokens continuent de s’appliquer via [Politiques et limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits).

# Demandes des personnes concernées
Source: https://docs.tale.dev/fr/platform/admin/governance/data-subject-requests

En tant qu’admin ou propriétaire, utilise **Paramètres > Gouvernance > Personnes concernées** pour traiter une demande d’effacement. Tale suit la demande, son approbation, son délai d’attente et le résultat de la suppression. Vérifie d’abord l’identité de la personne et le bon périmètre selon la procédure de ton organisation.

<Frame caption="Gouvernance > Demandes des personnes concernées — la politique de gouvernance DSAR (fenêtre d’attente, double approbation, limite quotidienne), au-dessus de la liste des reçus de demandes avec Déposer une demande.">

![La page de gouvernance Demandes des personnes concernées montrant les champs de fenêtre d’attente, de bascule de double approbation et de limite quotidienne, au-dessus d’un tableau de demandes d’effacement qui porte une demande en attente — personne concernée Jordan Blake, code de motif Consentement retiré, 24 h avant exécution et 29 jours restants sur son SLA — à côté d’un bouton Déposer une demande.](https://docs.tale.dev/images/platform/governance-data-subject-requests.webp)

</Frame>

## Déposer une demande

1. Choisis **Déposer une demande** et recherche la **Personne concernée** par nom ou e-mail. Vérifie que tu as sélectionné le bon compte.
2. Choisis le **Fondement légal** et explique la demande dans **Motif détaillé**, avec une référence à ton dossier interne.
3. Saisis exactement `ERASE`, puis choisis **Déposer la demande**.
4. Ouvre le reçu et vérifie le statut, l’échéance et la prochaine action requise.

L’effacement supprime définitivement les données couvertes ; il ne les déplace pas vers la corbeille. Le reçu indique les catégories et les nombres concernés : chats, documents et imports, préférences, retours, notifications, usage et nettoyage des identifiants personnels dans l’audit. L’effacement supprime aussi les espaces de travail de sandbox propres aux [exécutions d’agent que la personne a démarrées](https://docs.tale.dev/fr/platform/projects/tasks#executions-demarrees-par-un-membre), même si du travail s’y exécute encore ; le reçu les compte sous **Espaces de travail de sandbox**. Un espace de travail n’est compté qu’une fois ses fichiers supprimés par le service de sandbox, ce qui peut prendre un moment pour un grand espace. D’ici là, ou tant que leur suppression échoue, le reçu indique **Partielle** et cite `sandboxWorkspaces` parmi les passes échouées ; choisis plus tard **Réessayer**, et l’effacement se termine dès que les fichiers ont disparu. Sous Kubernetes, un espace est compté une fois son volume remis au provisionneur de stockage du cluster ; avec une StorageClass dont la `reclaimPolicy` est `Retain`, les fichiers du volume restent jusqu’à ce qu’un opérateur supprime le volume, même si le reçu compte l’espace. Un service de sandbox ou un appareil qui n’est pas encore passé à cette version ne peut pas confirmer la suppression ; le reçu reste alors **Partielle** jusqu’à sa mise à jour.

Les tâches qui désignent la personne comme **Relecteur** perdent cette désignation. Une demande de revue qui l’attend encore passe à la première personne autorisée parmi celle qui a créé la tâche, puis celle qui a créé le projet. Cette personne reçoit une notification. Pour une tâche archivée, la demande passe sans notification. Les décisions de revue que la personne a déjà prises restent enregistrées sans son nom.

## Vérifier la règle avant le dépôt

| Réglage | Effet |
| --- | --- |
| **Délai de réflexion (heures)** | Attente de 0–72 heures avant l’exécution. Les admins peuvent annuler pendant ce délai. Zéro permet une exécution immédiate une fois les autres conditions remplies. |
| **Exiger une approbation à double signature** | Un autre admin doit approuver avant le début du délai de réflexion. La personne qui dépose ne peut pas s’approuver elle-même. |
| **Limite quotidienne par admin** | Limite chaque admin à 1–50 dépôts par jour. |

Seul le propriétaire peut modifier cette règle. Les protections renforcées s’appliquent immédiatement ; les assouplissements attendent 24 heures pour permettre à tout admin de les annuler. Vérifie les réglages effectifs et les éventuels changements en attente avant de compter sur une nouvelle valeur.

## Suivre le reçu

| État | Action utile |
| --- | --- |
| En attente / attend une approbation | Vérifie si un autre admin doit approuver ou si le délai doit se terminer. Annule ou rejette si la demande ne doit pas s’exécuter. |
| En cours | Attends les résultats par catégorie ; ne dépose pas de doublon. |
| Terminée | Vérifie les nombres enregistrés et conserve le reçu dans ton dossier. |
| Partielle | Examine les catégories ignorées et les erreurs. Résous la cause avant de réessayer. |
| Bloquée | Examine la [conservation juridique](https://docs.tale.dev/fr/platform/admin/governance/legal-hold). Les données couvertes restent protégées. Le reçu nomme la rétention encore en vigueur ; une fois levée, il l’indique, et l’effacement ne reprend que si tu choisis **Réessayer**. |
| Échouée | Lis les détails. Utilise **Réessayer** si disponible ; un dépassement du délai de surveillance peut exiger une nouvelle demande. |
| Annulée | Ce reçu ne prévoit plus d’exécution. Dépose une nouvelle demande si le dossier doit reprendre. |

Un reçu ouvert peut empêcher un second dépôt pour la même personne. Reprends ce reçu au lieu de multiplier les demandes. Une demande bloquée dès le dépôt doit à nouveau respecter la règle actuelle d’approbation et d’attente lors d’un nouvel essai. Un reçu en attente d’approbation conserve l’exigence d’approbation fixée à son dépôt : désactiver la double approbation ensuite ne le libère pas.

## Gérer l’échéance

La liste montre le délai suivi et les éventuels retards. Utilise **Prolonger le délai** pour une prolongation justifiée tant que l’action est disponible. L’application autorise une prolongation avant l’expiration du délai initial et enregistre le motif ainsi que l’admin.

Cette échéance facilite le suivi. Ton organisation reste responsable de l’examen et des échanges avec la personne. Terminer un reçu Tale ne confirme pas, à lui seul, une suppression dans des systèmes externes indépendants ou des sauvegardes.

## Vérifier le résultat

Ouvre les compteurs par catégorie, les erreurs et la chronologie d’audit du reçu. Une action terminée, une catégorie sous gel et une étape échouée n’ont pas le même résultat. Note ces distinctions dans ton dossier. Consulte les [journaux d’audit](https://docs.tale.dev/fr/platform/admin/governance/audit-logs) pour les événements administratifs associés.

# Analyse des retours
Source: https://docs.tale.dev/fr/platform/admin/governance/feedback-analytics

En tant qu’admin ou propriétaire, consulte **Paramètres > Métriques > Retours** pour examiner les retours soumis dans le chat. Les évaluations indiquent ce que les membres ont trouvé utile ; leurs commentaires aident à comprendre pourquoi.

## Trouver les retours utiles

Choisis une période, puis filtre par type de retour, assistant ou modèle. Les fenêtres disponibles sont 1, 7, 30 et 90 jours, ainsi que toute la période ; la vue initiale utilise 7 jours. Sélectionner un assistant ou un modèle dans une répartition filtre la vue. Efface les pastilles pour l’élargir à nouveau. Tale attribue chaque évaluation à partir de la réponse évaluée elle-même : le modèle et le fournisseur qui ont répondu, et l’assistant sous lequel la conversation se déroule. Il s’agit de l’assistant sous lequel la conversation se déroule au moment de l’évaluation, pas nécessairement de celui qui a écrit la réponse : après un changement d’assistant, l’évaluation d’une réponse antérieure compte pour le nouvel assistant. Une réponse dans un chat simple, hors de tout assistant, apparaît comme **Non attribué**.

Utilise **Commentaires uniquement** pour privilégier les explications écrites. Si aucun retour n’apparaît, vérifie la période et les filtres. Les évaluations sont volontaires : une réponse non évaluée n’est ni un vote positif ni un vote négatif.

## Distinguer les signaux

| Signal | Ce qu’il indique |
| --- | --- |
| Pouce vers le haut/bas | Si un membre a trouvé une réponse précise utile. Un commentaire facultatif apporte du contexte. |
| Verdict d’arène | Quelle réponse a été préférée dans une paire donnée, ou si les réponses sont à égalité ou toutes deux mauvaises. Un verdict rendu sur deux copies du même modèle est compté sous **Même modèle**, à part des verdicts et du tableau des paires. |

Les membres peuvent modifier ou retirer une évaluation. Le tableau de bord reflète l’état actuel, pas un compteur permanent de chaque clic. Le [mode arène](https://docs.tale.dev/fr/platform/chat/arena-mode) explique comment comparer deux réponses.

## Comparer les résultats équitablement

Lis le nombre d’évaluations avec la proportion de réponses utiles. Un seul vote positif apporte moins d’information que des retours répétés sur les tâches réellement traitées. Compare des périodes et des tâches similaires avant d’attribuer une variation au modèle ou à la configuration d’un assistant.

Utilise les tableaux par assistant et modèle pour localiser la variation, la tendance pour la dater, puis les commentaires des retours récents pour la comprendre. Pour l’arène, compare la même paire de modèles : une victoire contre l’un ne prouve pas une supériorité sur tous les autres.

<Tip>
Croise cette lecture avec l’[analyse de l’usage](/fr/platform/admin/governance/usage-analytics). Un modèle peut coûter moins par requête tout en demandant davantage d’essais pour obtenir une réponse utile.
</Tip>

## Comprendre les résultats partiels

Les grandes périodes peuvent atteindre la limite d’agrégation de 50 000 entrées. Si Tale signale des résultats partiels, réduis la période avant de conclure. La rétention et les suppressions déterminent aussi quels commentaires et évaluations restent disponibles. Cette vue n’est pas une archive permanente des retours.

# Garde-fous
Source: https://docs.tale.dev/fr/platform/admin/governance/guardrails

En tant qu’admin ou propriétaire, utilise **Paramètres > Gouvernance > Garde-fous** pour contrôler la vérification des textes avant et après un appel au modèle. Les couches actives s’exécutent dans cet ordre : sécurité du contenu, détection des données personnelles, puis modération externe. Commence par une règle claire et vérifie son effet avant de l’élargir.

<Frame caption="Gouvernance > Garde-fous — les trois cartes de statut des couches de filtres (sécurité du contenu, détection PII, fournisseur de modération), au-dessus du journal des événements récents.">

![La page de gouvernance Garde-fous montrant trois cartes de statut — Sécurité du contenu active avec deux catégories en entrée et en sortie, Détection DCP active en mode masquage et Fournisseur de modération non configuré — au-dessus du flux des événements récents, qui n’en signale encore aucun, et des instructions personnalisées de l’organisation.](https://docs.tale.dev/images/platform/governance-guardrails.webp)

</Frame>

## Ajouter une règle de contenu

1. Dans la sécurité du contenu, choisis de vérifier les saisies des utilisateurs, les réponses du modèle ou les deux.
2. Ajoute une catégorie, donne-lui un libellé reconnaissable et choisis son mode.
3. Ajoute les mots ou expressions à détecter, une entrée par ligne. Tu peux importer une liste texte ; relis-la avant de l’appliquer.
4. Enregistre la catégorie, active la catégorie et la couche voulues, puis enregistre les changements de la page.
5. Teste avec un texte fictif contenant une correspondance, puis un texte normal qui doit passer. Vérifie les événements récents et le résultat visible dans le chat.

| Mode | Effet d’une correspondance |
| --- | --- |
| Signaler | Enregistre la détection et laisse passer le message. Utile pour affiner une règle. |
| Masquer | Remplace le texte détecté par le substitut configuré. |
| Bloquer | Refuse le message. |

Si plusieurs catégories correspondent, bloquer passe avant masquer, puis signaler. La recherche de mots ignore la casse. Vérifie les variantes et faux positifs importants dans tes langues. Un test réussi ne démontre pas une couverture complète.

## Protéger les données personnelles

La protection PII détecte des formats configurés, comme les adresses e-mail, numéros de téléphone et identifiants. Sélectionne les types intégrés utiles et les motifs personnalisés, puis le comportement souhaité.

Le masquage retire les valeurs détectées du texte transmis. Dans un chat, Tale enregistre et affiche aussi le texte masqué comme message ; la formulation d’origine n’est pas conservée. Le blocage refuse une correspondance. La tokenisation remplace les valeurs par des tokens numérotés pour le modèle, puis les restaure dans sa réponse. Elle réduit l’exposition pendant le traitement, sans garantir une réponse finale dépourvue de données personnelles.

Un identifiant intégré composé uniquement de chiffres, comme un numéro de passeport suédois ou un identifiant fiscal ukrainien, n’est reconnu qu’à côté d’un mot qui le nomme, par exemple `passnummer` ou `ІПН`. Les numéros de commande, les dates compactes et les numéros de build passent tels quels. Chaque détection dans **Événements récents** nomme le motif déclenché, par exemple `se-passport`.

Teste tes formats réels avec des valeurs fictives. La détection peut manquer des formats inhabituels et signaler à tort du texte ordinaire. Vérifie séparément l’entrée et la sortie.

## Ajouter une modération externe

La couche de modération envoie du texte à un classificateur configuré, comme OpenAI, Azure, Perspective ou un point de terminaison personnalisé. Configure ses identifiants, catégories et actions, puis les directions à inspecter.

Décide du comportement si le fournisseur est indisponible : fail-open laisse passer le message, fail-closed le refuse. Examine les erreurs fournisseur et les événements de circuit ouvert en cas de refus inattendus ou de messages non filtrés. Cette couche ajoute un service qui traite le texte. Utilise le fournisseur et l’adresse approuvés pour ton organisation.

## Définir les instructions de l’organisation

Les instructions personnalisées de l’organisation sont ajoutées avant celles de l’assistant de chat et avant les instructions propres de chaque agent : les agents de projet qui traitent des tâches et les nœuds agent des automatisations. Les membres ne peuvent pas modifier cette règle d’organisation. Utilise-les pour le comportement et le vocabulaire communs. Pour les restrictions à imposer indépendamment du respect d’un texte par le modèle, utilise les règles d’accès et les filtres.

## Les garde-fous sur les endpoints de modèles {#model-endpoints}

Quand ton organisation active les [endpoints de modèles pour les clés API](https://docs.tale.dev/fr/platform/admin/governance/content-models#model-endpoints), le côté entrée de ces garde-fous examine aussi chaque requête qui leur est envoyée. La sécurité du contenu, la protection PII et le fournisseur de modération lisent chaque texte de la requête avant que Tale la transmette au modèle : les instructions système et développeur, les tours de la personne et de l’assistant, les appels d’outils, leurs résultats et les définitions d’outils, ainsi que les documents fournis en texte. L’appelant les écrit tous, donc aucun n’est plus digne de confiance qu’un autre :

- Un blocage refuse la requête avec `400 MODEL_API_GUARDRAIL_BLOCKED`, et rien n’atteint le modèle.
- Un masquage remplace la correspondance, et le modèle reçoit le texte masqué.
- La tokenisation ne peut pas être respectée, car Tale relaie la réponse du modèle telle quelle et ne peut pas y restaurer les valeurs. Tant que la protection PII est active en mode **Tokeniser**, chaque requête est refusée avec `403 MODEL_API_GUARDRAIL_UNSUPPORTED` ; choisis **Masquer** ou **Bloquer** si des membres utilisent les endpoints de modèles.
- Si un fournisseur de modération échoue en fail-closed, Tale refuse la requête avec `503 MODEL_API_GUARDRAIL_UNAVAILABLE`, tout comme quand il ne peut pas lire un réglage de garde-fou.
- Tant qu’un garde-fou est actif, une requête de plus de 2 Mo de texte est refusée avec `413 MODEL_API_TEXT_TOO_LARGE`.

La sortie n’y est pas filtrée : les règles qui vérifient la **Sortie modèle** ne s’appliquent pas, et les réponses du modèle, en flux ou non, passent sans contrôle, tout comme les images et les documents qui ne sont pas du texte. Tale n’ajoute pas non plus d’instructions personnalisées : le modèle reçoit la requête telle que l’outil de l’appelant l’a envoyée. Les détections apparaissent dans **Événements récents** comme celles du chat, chacune enregistrée sous `model-api:` suivi de l’identifiant que Tale attribue à la requête, avec à côté le `X-Request-Id` que l’appelant a reçu. Comme les outils renvoient toute la conversation à chaque requête, Tale réutilise son verdict sur un texte examiné dans les dernières minutes et n’enregistre une détection qu’une fois, pas à chaque renvoi.

## Examiner et ajuster

Les événements récents affichent les 50 dernières détections, blocages et erreurs fournisseur. Filtre par couche ou résultat et examine la catégorie, la direction et la date. Le texte brut détecté n’est pas conservé dans ces événements : la ligne explique la détection sans reproduire la valeur sensible.

Si une règle est trop large, ajuste sa catégorie ou ses motifs et répète les tests fictifs. Si une détection manque, vérifie l’activation de la couche, de la catégorie et de la direction voulue. La durée de conservation des événements dépend de la catégorie **Événements chat-filter** de la [règle de rétention](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits). Elle est désactivée par défaut, et les événements sont conservés jusqu’à ce qu’un admin l’active. Tant qu’elle est activée, le nettoyage planifié supprime les événements plus anciens que sa durée augmentée du délai de grâce, jusqu’à 50 000 par nuit ; un arriéré plus important, comme des mois d’événements lors de la première activation, se résorbe sur plusieurs nuits. Les événements récents et les chiffres des garde-fous sous **Paramètres > Métriques > Santé de l'assistant** n’affichent que les événements encore conservés : si la durée augmentée du délai de grâce reste inférieure à 30 jours, la partie la plus ancienne d’une vue sur 30 jours reste vide.

Une [conservation juridique](https://docs.tale.dev/fr/platform/admin/governance/legal-hold) protège les événements du nettoyage : un gel de l’organisation préserve tous les événements, un gel d’un membre préserve ceux déclenchés dans ses chats. Un événement dont le chat a été définitivement supprimé avant le gel n’a plus de propriétaire à protéger et n’est pas conservé.

# Conservation juridique
Source: https://docs.tale.dev/fr/platform/admin/governance/legal-hold

Une conservation juridique préserve les données couvertes pendant qu’un dossier est ouvert. Les admins et propriétaires gèrent ces gels dans **Paramètres > Gouvernance > Conservation légale**. Place le gel tant que les données existent : il ne récupère pas les enregistrements déjà supprimés définitivement.

<Frame caption="Gouvernance > Conservation légale — le tableau des conservations actives avec l’action Placer une conservation légale, au-dessus de la file à double contrôle des demandes de levée.">

![La page de gouvernance Conservation légale montrant une conservation active — de type Utilisateur sur marta.vogel, placée par Alex Rivera au titre de l’affaire Northstar contract — à côté d’un bouton Placer une conservation légale, au-dessus des deux files de demandes de levée, Approbation en attente et Approuvées, qui n’affichent aucune demande.](https://docs.tale.dev/images/platform/governance-legal-hold.webp)

</Frame>

## Placer un gel

1. Choisis **Placer une conservation**.
2. Choisis la cible : une personne comme dépositaire, ou toute l’organisation. Pour une personne, sélectionne le bon membre.
3. Indique un motif permettant à un autre admin de comprendre ce qui doit être préservé. Associe le gel à un dossier si tu suis une affaire.
4. Confirme, puis vérifie la cible et le motif dans les conservations actives.

Le gel prend effet immédiatement. Les données couvertes sont protégées de la rétention et de l’effacement ; les tentatives de suppression sont refusées. Détermine le bon périmètre selon la procédure de préservation de ton organisation.

## Regrouper les gels par dossier

Utilise **Créer un dossier** pour réunir les gels liés sous un nom et un numéro de dossier. Le nombre de gels associés aide à vérifier que les personnes prévues sont couvertes.

Fermer un dossier demande la libération de ses gels. Cela ne les libère pas immédiatement : chaque demande doit encore suivre l’examen décrit ci-dessous.

## Libérer un gel

1. Sur le gel actif, choisis **Demander la libération** et explique pourquoi la conservation n’est plus nécessaire.
2. Un autre admin examine la demande et choisit **Approuver** ou **Rejeter**. La personne qui demande la libération ne peut pas l’approuver elle-même.
3. Après l’approbation, vérifie le délai affiché dans les demandes de libération. Le gel reste actif pendant ce délai.
4. Vérifie le résultat terminé dans l’historique des libérations et les gels restants dans la liste active.

Un admin peut placer un gel. Sa libération exige deux personnes et un délai. Une approbation ne signifie donc pas encore que la libération est terminée.

## Comprendre une suppression bloquée

Un gel peut empêcher une demande d’effacement, la suppression des chats ou documents couverts, ou celle d’un dossier contenant des fichiers gelés. Tout gel actif au niveau de l’organisation ou d’un membre empêche aussi la suppression de l’organisation elle-même.

Si une suppression échoue, examine le gel concerné au lieu de répéter l’action. Libérer un gel ne retire pas un autre gel qui couvre les mêmes données. La libération permet à la rétention ou à l’effacement applicable de reprendre. Un reçu d’effacement bloqué par le gel ne reprend pas tout seul : ouvre-le dans Demandes des personnes concernées et choisis **Réessayer**.

## Examiner les demandes liées

Consulte [Demandes des personnes concernées](https://docs.tale.dev/fr/platform/admin/governance/data-subject-requests) pour examiner un reçu d’effacement bloqué par un gel, et les [journaux d’audit](https://docs.tale.dev/fr/platform/admin/governance/audit-logs) pour les actions enregistrées. La [règle de rétention](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits) détermine le nettoyage normal lorsque la conservation ne s’applique plus.

# Métriques d’exploitation
Source: https://docs.tale.dev/fr/platform/admin/governance/operations-metrics

À côté de [Utilisation](https://docs.tale.dev/fr/platform/admin/governance/usage-analytics) et [Retours](https://docs.tale.dev/fr/platform/admin/governance/feedback-analytics), **Paramètres > Métriques** propose aux admins et aux propriétaires quatre autres tableaux de bord. **Santé de l'assistant** montre si les réponses de l’assistant échouent ou sont bloquées, **Tours de harness** si les agents mènent leur travail à terme dans la sandbox, **Automatisations** comment se terminent les exécutions réelles et **Projets** comment avancent les tâches d’un projet. Chaque tableau recalcule ses chiffres pour la période choisie à partir des enregistrements que Tale conserve encore.

<Frame caption="Paramètres > Métriques > Santé de l’assistant : les compteurs et les taux, le graphique quotidien des résultats et la répartition par agent et par modèle.">

![Le tableau de bord Santé de l’assistant sur les sept derniers jours indique sept réponses de l’assistant, un taux d’erreur de 0 %, un taux de blocage de 0 % et aucun événement de garde-fou, une barre de sept réponses réussies le jour même et une répartition qui attribue toutes les réponses à des chats simples et les partage entre deux modèles.](https://docs.tale.dev/images/platform/metrics-chat-health.webp)

</Frame>

## Vérifier la santé de l’assistant

Ouvre **Santé de l'assistant** quand des membres signalent des réponses en échec ou refusées. Choisis 1, 7 ou 30 jours sous **Filtre** ; la page s’ouvre sur 7 jours.

Les cartes comptent les **Réponses de l'assistant** produites pendant la période. Le **Taux d'erreur** est la part de ces réponses qui se sont terminées par une erreur, et le **Taux de blocage** la part que Tale a refusé de fournir, par exemple parce qu’un garde-fou a bloqué le message. **Événements guardrails** compte les détections de la période et le nombre de messages qu’elles ont bloqués.

**Réponses au fil du temps** répartit les réponses de chaque jour entre **Réussies**, **Erreurs** et **Bloquées**, pour voir quand un problème a commencé. **Répartition** donne la part de chaque agent et de chaque modèle ; une réponse dans un chat simple, hors de tout agent, compte comme **Non attribué**.

Sous **Erreurs**, **Par type d'erreur** regroupe les échecs, par exemple **Limite de débit**, **Modèle introuvable**, **Crédits épuisés** ou **Limite d'utilisation atteinte**, et **Erreurs récentes** liste les plus récentes avec leur modèle et leur agent. Le type indique la vérification suivante : les identifiants d’un fournisseur ou son quota sous [Fournisseurs IA](https://docs.tale.dev/fr/platform/admin/providers), la disponibilité d’un modèle sous [Modèles](https://docs.tale.dev/fr/platform/admin/governance/content-models) ou une règle de budget sous [Politiques et limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits).

**Garde-fous** détaille les événements par type et par filtre, et trace chaque jour les détections, les blocages et les erreurs de filtre. Ces événements proviennent des filtres configurés dans [Garde-fous](https://docs.tale.dev/fr/platform/admin/governance/guardrails) et ne couvrent que ceux que la conservation garde encore.

## Suivre les tours de harness

Un tour de harness est une étape de travail qu’un harness, comme Claude Code ou Codex, accomplit dans la sandbox : un [agent de projet](https://docs.tale.dev/fr/platform/projects/project-agents) qui travaille sur une tâche, ou une étape d’agent dans une automatisation. **Tours de harness** montre si ces tours vont à leur terme. Choisis 7, 30 ou 90 jours ; la page s’ouvre sur 30 jours.

Les cartes indiquent les **Tours au total**, le **Taux de réussite**, le **Taux d'expiration**, la **Durée p95**, dans laquelle 95 % des tours se sont terminés, et, sous **Arrêtés par l'utilisateur**, les tours qu’une personne a interrompus. **Par harness** reprend les tours, le taux de réussite et les expirations pour chaque harness : si le taux d’expiration augmente, tu vois de quel harness il vient. [Choisir un environnement d’agent](https://docs.tale.dev/fr/platform/agents/harnesses) explique comment chaque harness fonctionne, et [Gérer la capacité des sandboxes](https://docs.tale.dev/fr/platform/admin/sandboxes) où leur capacité se règle.

## Suivre les exécutions d’automatisation

**Automatisations** compte les exécutions réelles des automatisations de ton organisation ; les exécutions de test apparaissent dans l’onglet **Exécutions** de chaque automatisation, mais pas ici. Choisis 7, 30 ou 90 jours ; la page s’ouvre sur 30 jours. Chaque carte compare son chiffre à la période de même durée qui précède.

Le **Taux de réussite** est la part des exécutions terminées qui ont réussi : les exécutions échouées ou arrêtées comptent contre lui, tandis que les exécutions en file d’attente, en cours ou en attente ne comptent pas encore. La **Durée moyenne** porte sur les exécutions terminées, et **Exécutions échouées** compte les échecs. **Exécutions au fil du temps** montre le volume quotidien, **Répartition des statuts** l’issue de toutes les exécutions de la période et **Automatisations les plus actives** les dix automatisations qui ont le plus d’exécutions, avec leur taux de réussite, leur durée moyenne, leurs échecs et leur dernière exécution. Ouvre l’onglet **Exécutions** d’une automatisation en échec pour trouver le nœud qui a échoué ; [Examiner les exécutions et corriger les échecs](https://docs.tale.dev/fr/platform/automations/execution-logs) te guide.

## Examiner l’avancement d’un projet

**Projets** affiche un projet à la fois : choisis-le sous **Sélectionner un projet**. Si l’organisation n’a qu’un projet, il est déjà sélectionné. Choisis 7, 30 ou 90 jours ; la page s’ouvre sur 30 jours.

| Indicateur | Ce qu’il mesure |
| --- | --- |
| **Terminées** | Les tâches passées à **Terminé** pendant la période, réparties selon leur assignation actuelle : les tâches assignées à un agent et toutes les autres. |
| **Temps de cycle moyen** | Le temps moyen entre le premier passage d’une tâche à **En cours** et son arrivée à **Terminé**. Une tâche qui n’est jamais passée par **En cours** n’a pas de temps de cycle. |
| **Taux d'intervention** | Les modifications demandées lors de la revue et les escalades (questions que des étapes d’agent d’automatisations ont posées à des personnes), rapportées aux exécutions d’agent lancées pendant la période. |
| **Dépenses** | Le coût des exécutions d’agent du projet, avec le nombre d’exécutions lancées et échouées. |

Les graphiques en dessous montrent les tâches ouvertes par statut à la fin de chaque jour, les tâches créées et terminées chaque jour, l’évolution du temps de cycle, les tâches terminées chaque jour réparties entre **Agents** et **Humains**, et les dépenses quotidiennes. Comme celle sous **Terminées**, cette répartition suit l’assignation actuelle de chaque tâche, et non la personne qui l’a terminée. Une tâche assignée à un agent compte pour les agents, bien qu’une personne l’ait passée à **Terminé** ; une tâche non assignée, ou assignée à une personne ou à une automatisation, compte pour les humains. Cela vaut aussi pour les jours passés : si une tâche est ensuite assignée à un agent ou perd son agent, par exemple parce qu’il a été supprimé, elle change de côté. Une tâche créée directement comme **Terminé** ou **Annulé** reçoit son horodatage de fin au moment de sa création. En revanche, le débit quotidien des tâches terminées ne compte que les événements de changement de statut : cette création directe ne compte donc pas comme un événement de fin.

Si le taux d’intervention augmente alors que le nombre d’exécutions reste stable, les personnes renvoient davantage de travail ou les agents posent davantage de questions. Les escalades viennent des étapes d’agent des automatisations qui travaillent sur le projet, et chacune compte le jour où elle est émise, qu’elle reçoive une réponse ou non. Pour le travail renvoyé, lis les tâches en revue avant de modifier les instructions d’un agent dans [Créer et gérer des agents de projet](https://docs.tale.dev/fr/platform/projects/project-agents) ; pour les questions, lis les exécutions de l’automatisation qui les a posées, comme l’explique [Examiner les exécutions et corriger les échecs](https://docs.tale.dev/fr/platform/automations/execution-logs).

## Bien lire les chiffres

- Chaque tableau de bord s’appuie sur les enregistrements que Tale conserve. Les règles de conservation et les suppressions raccourcissent l’historique : une période vide peut signifier que les enregistrements ont disparu, et non qu’il ne s’est rien passé.
- Une période chargée peut dépasser ce qu’un seul passage lit : Santé de l’assistant, Tours de harness, Automatisations et Projets comptent chacun au plus les 5 000 enregistrements les plus récents d’un même type sur la période. Si Tale affiche un avis sur l’activité récente, réduis la période avant de conclure.
- Les coûts sont l’usage enregistré par l’application, pas la facture d’un fournisseur ; l’[analyse de l’usage](https://docs.tale.dev/fr/platform/admin/governance/usage-analytics) explique la différence.

# Politiques et limites
Source: https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits

En tant qu’admin ou propriétaire, utilise **Paramètres > Gouvernance > Politiques et limites** pour contrôler les ressources et le traitement des données. Choisis la section adaptée au problème : dépenses, imports, rétention, fonctionnalités, avis affiché dans le chat, partage des skills avec toute l’organisation ou destinataires des conversations entrantes.

<Frame caption="Gouvernance > Politiques et limites — le tableau des règles de budget, au-dessus de la politique d’import et des contrôles de rétention.">

![La page de gouvernance Politiques et limites montrant trois règles de budget mensuelles — une pour l’organisation entière, une par défaut pour tous les utilisateurs et une pour le rôle Développeur, chacune plafonnant les tokens, le coût et les requêtes — au-dessus des champs de politique d’import pour les types de fichiers autorisés, les tailles et le volume.](https://docs.tale.dev/images/platform/governance-policies-limits.webp)

</Frame>

## Ajouter un budget

1. Dans les règles de budget, choisis **Ajouter une règle**.
2. Choisis la portée et sa cible : un rôle pour un groupe comme les rédacteurs, une équipe pour un travail commun, une personne pour une limite individuelle, une clé API pour un identifiant, ou l’organisation pour un plafond partagé. La liste des clés API propose chaque clé active d’un membre de l’organisation, avec le nom de la personne qui la détient : tu peux ainsi plafonner le script ou l’outil de code d’une seule personne.
3. Sélectionne une période quotidienne, hebdomadaire ou mensuelle. Renseigne au moins une limite positive de tokens, de coût ou de requêtes. Le coût est en USD ; un champ vide ne plafonne pas cette dimension par cette règle.
4. Définis si besoin le seuil d’alerte entre 0 et 100 pour avertir avant d’atteindre le plafond.
5. Choisis **Confirmer**, enregistre les changements de la page et vérifie la portée, la cible, la période et les limites enregistrées.

Par exemple, une règle mensuelle de rôle peut donner aux rédacteurs un budget personnel de 50 USD, tandis qu’une règle d’organisation plafonne les dépenses cumulées à 500 USD. Ce sont des exemples, pas des valeurs recommandées.

Une règle reste dans le tableau même quand sa clé API ne fonctionne plus. **Cible** indique toujours la clé et la personne qui la détient, avec un statut : **Expirée** tant que la clé expirée est encore conservée, **Désactivée**, **Révoquée** si cette organisation a enregistré sa révocation, ou **Ancien membre** lorsque cette personne a quitté l’organisation. **Indisponible** signifie que la clé est connue mais n’est plus conservée, sans motif enregistré ; le nettoyage des clés expirées peut produire cet état. **Clé inconnue** signale une clé sur laquelle cette organisation n’a aucune information. Supprime une telle règle, ou modifie-la pour choisir une clé active.

Les budgets concernent les nouveaux travaux facturables, dont le chat, la sortie vocale, les exécutions d’agents gérés, les images que créent les agents et les appels aux endpoints de modèles. Tale vérifie chaque requête de chat avant son exécution — un message envoyé, une réponse régénérée ou modifiée, les deux côtés d’une comparaison de modèles, un message en attente d’une pièce jointe et un envoi par l’API REST — et la refuse dès qu’un plafond applicable est atteint, en indiquant ce plafond et le moment de sa réinitialisation. Les réponses en cours de rédaction réservent ce qu’elles peuvent dépenser, afin que des requêtes envoyées au même moment ne franchissent pas ensemble un plafond presque atteint. La demande d’image d’un agent est vérifiée de la même façon avant l’appel au modèle d’images : pendant que ses images sont créées, elle réserve un coût estimé, et la vérification compte aussi ce que l’exécution de l’agent peut encore dépenser pour son modèle. Chaque image compte pour une requête. La génération d’images a besoin de limites de coût ou de requêtes, car son usage ne se mesure pas en tokens de texte. Une limite de tokens compte les tokens d’entrée et de sortie, et l’entrée comprend la partie d’un prompt qu’un fournisseur a lue dans son cache ou y a écrite. Cette partie est facturée autrement que le reste de l’entrée : un agent qui réutilise un long prompt peut donc atteindre une limite de tokens alors que son coût reste faible. Examine les alertes dans l’[analyse de l’usage](https://docs.tale.dev/fr/platform/admin/governance/usage-analytics).

## Comprendre les plafonds applicables

Pour chaque dimension, la limite personnelle vient de la règle la plus précise qui la définit : personne, équipe, rôle, puis valeur par défaut. Si une personne appartient à plusieurs équipes dotées d’une règle, le plafond le plus strict s’applique à elle. Les plafonds de l’organisation s’ajoutent. Un budget d’équipe plafonne aussi l’usage cumulé des membres actuels de l’équipe, même si un membre a une règle personnelle plus précise : l’usage d’un nouveau membre sur la période en cours compte aussitôt, et celui d’un membre parti ne compte plus. Les limites de clé API plafonnent séparément les requêtes authentifiées par cette clé, dont l’usage est imputé à la clé, pas les autres actions dans l’interface.

Les exécutions d’agents gérés comptent pour la personne qui les a lancées. Une exécution que tu démarres depuis une tâche, un commentaire, l’API REST ou le point d’accès MCP consomme tes plafonds personnels et d’équipe, et une exécution lancée avec une clé API compte aussi pour cette clé. Les exécutions démarrées par une planification, un webhook ou un événement n’ont personne derrière elles : seules les limites de l’organisation s’y appliquent, et l’[analyse de l’usage](https://docs.tale.dev/fr/platform/admin/governance/usage-analytics) les regroupe sous **Automatisations (déclencheurs)**. [Comment l’usage est compté](https://docs.tale.dev/fr/platform/admin/governance/usage-attribution) explique la règle pour chaque type de travail.

Un appel aux [endpoints de modèles](https://docs.tale.dev/fr/develop/use-tale-from-your-editor#model-endpoints) est vérifié comme une requête de chat. Avant son exécution, Tale calcule le pire cas, l’estimation du prompt plus la sortie maximale possible, au prix catalogue du modèle, et le refuse avec `429 BUDGET_EXCEEDED` quand ce pire cas ne tient pas dans ce qui reste sous un plafond qui s’applique au détenteur de la clé ou à la clé. Tant que l’appel tourne, ce pire cas est réservé sur ces plafonds. Ensuite, le coût mesuré par la passerelle de modèles est imputé à la personne et à la clé, et chaque appel compte pour une requête.

Si une requête est refusée de façon inattendue, vérifie tous les plafonds applicables et leurs périodes. Augmenter une limite personnelle ne retire pas un plafond d’organisation, d’équipe ou de clé API.

Les membres consultent leur propre situation sous [Paramètres > Utilisation](https://docs.tale.dev/fr/platform/member/preferences#usage-limits). Chaque plafond personnel, d’équipe ou d’organisation qui les concerne y figure avec l’utilisation actuelle et la prochaine réinitialisation, sans que les règles elles-mêmes soient affichées.

### Comment les règles se combinent {#how-rules-combine}

Chaque politique de cette page et de [Contenu et modèles](https://docs.tale.dev/fr/platform/admin/governance/content-models) lit ses règles de la même façon. La portée la plus précise l’emporte : une règle individuelle avant une règle d’équipe, une règle d’équipe avant une règle de rôle, une règle de rôle avant la valeur par défaut. Lorsqu’une personne appartient à plusieurs équipes dotées d’une règle, les règles d’équipe se combinent selon leur nature :

- Une limite, comme un plafond de budget ou de fenêtre de contexte, prend la valeur la plus stricte. Rejoindre une équipe généreuse n’augmente jamais le plafond de quelqu’un.
- Une liste d’autorisations, comme l’accès aux modèles, se combine par l’union des modèles autorisés ; un blocage dans l’une des règles reste prioritaire pour ce modèle.
- Un choix unique, comme le modèle par défaut, suit l’ordre des règles dans le tableau : la première règle d’équipe correspondante l’emporte.

## Contrôler les imports

La politique d’import définit les extensions autorisées et bloquées, les types MIME autorisés, la taille maximale par fichier en Mo et le volume total par personne en Go. Choisis les types nécessaires et teste un fichier autorisé et un fichier refusé après l’enregistrement.

L’extension, le type de contenu et la taille sont des vérifications distinctes. En cas d’échec, compare les trois avec la règle. Vérifie le stockage déjà utilisé si les fichiers respectent individuellement les limites mais que les nouveaux imports sont refusés.

## Définir la rétention et la récupération

Dans la règle de rétention, choisis **Modifier** et configure les catégories nécessaires. Le résumé montre les valeurs effectives, les catégories désactivées et le nettoyage des fichiers temporaires. Désactiver la rétention planifiée d’une catégorie n’empêche pas une suppression explicite ni une demande d’effacement.

Vérifie les bornes minimales et maximales du déploiement avant de modifier une durée. Les changements qui demandent une revue ou un délai apparaissent comme propositions ou changements en attente. Lis leur date d’effet sans supposer une application immédiate.

Le délai de grâce est la fenêtre de récupération des enregistrements supprimés provisoirement pris en charge. Une valeur positive laisse du temps pour les restaurer dans la [Corbeille](https://docs.tale.dev/fr/platform/admin/governance/trash) ; zéro permet un nettoyage définitif immédiat. Toutes les catégories ne sont pas restaurables. Une [conservation juridique](https://docs.tale.dev/fr/platform/admin/governance/legal-hold) protège les données couvertes du nettoyage.

Pour les déploiements autohébergés, la [configuration de rétention](https://docs.tale.dev/fr/self-hosted/configuration/retention) explique les contrôles opérateur et le comportement par catégorie. Ne déduis pas une garantie d’archivage d’une règle désactivée ou d’une durée affichée seule.

## Examiner les contrôles de fonctionnalités

Les contrôles comprennent les limites de fenêtre de contexte par portée et le commutateur de sortie vocale pour l’organisation. Une limite de contexte détermine la quantité de contexte transmise à une réponse d’IA ; elle diffère d’un budget. Une limite inférieure à 200 000 tokens s’applique aussi aux exécutions d’agents Claude Code, selon la limite de la personne qui a lancé l’exécution : l’agent condense sa conversation en un résumé avant qu’elle ne dépasse la limite, et Claude Code traite toute limite inférieure à 100 000 tokens comme 100 000. Désactiver la sortie vocale empêche les membres de l’activer par leurs réglages personnels ou leurs conversations.

Le commutateur par défaut des instructions personnalisées enregistre la valeur d’organisation pour les instructions personnelles des membres : tant qu’il est activé, les instructions personnalisées de chaque membre s’appliquent à ses réponses de chat, sauf si le membre a désactivé la fonction lui-même sous **Paramètres > Personnalisation**. Les instructions obligatoires de l’organisation sont un réglage séparé sous [Garde-fous](https://docs.tale.dev/fr/platform/admin/governance/guardrails).

## Afficher un avis de confidentialité dans le chat

**Avis de confidentialité** ajoute une courte ligne sous le champ de message du chat pour tous les membres de ton organisation, par exemple pour rappeler de ne pas partager de données sensibles. L’avis reste désactivé tant que tu ne l’actives pas.

1. Active le commutateur **Avis de confidentialité**. Les membres voient aussitôt l’avis dans le chat, dans leur langue, et les chats ouverts se mettent à jour sans rechargement.
2. Si tu le souhaites, saisis ton propre texte dans les onglets de langue **English**, **Deutsch** et **Français**, jusqu’à 280 caractères par langue. Enregistre ensuite les changements de la page.

<Frame caption="Gouvernance > Politiques et limites — l’avis de confidentialité activé, avec un texte anglais, une traduction allemande et le français encore non traduit.">

![La section Avis de confidentialité, commutateur activé et onglet English sélectionné, demande de ne pas coller de noms de clients, de montants de contrats ni de noms de code de projets non publiés dans le chat ; l’onglet Français est marqué non traduit.](https://docs.tale.dev/images/platform/governance-confidentiality-notice.webp)

</Frame>

Chaque membre voit le texte de sa langue. Un onglet marqué **non traduit** n’a pas de texte propre : les membres qui lisent cette langue voient ton texte anglais, ou l’avis par défaut si l’anglais est vide lui aussi, et le champ vide présente ce texte en aperçu. Un point rouge signale une langue dont le texte est trop long ; l’enregistrement reste impossible tant que tu ne l’as pas raccourci. Désactiver l’avis conserve tes textes pour la prochaine activation.

L’avis n’est qu’un rappel : il ne vérifie, ne bloque ni ne modifie les messages envoyés. Pour agir sur les contenus sensibles, configure les [Garde-fous](https://docs.tale.dev/fr/platform/admin/governance/guardrails).

## Décider qui partage des skills avec tout le monde {#skill-sharing}

Par défaut, chaque membre peut partager un skill avec toute l’organisation. **Partage des skills** permet de réserver ce droit à moins de personnes : choisis qui peut **Partager les skills avec l'organisation**, puis enregistre les modifications en attente de la page.

- **Tous les membres** conserve le comportement par défaut.
- **Éditeurs et au-delà** autorise les éditeurs, les développeurs, les admins et les propriétaires, c’est-à-dire les rôles qui équipent les agents.
- **Propriétaires et admins uniquement** n’autorise que les propriétaires et les admins.

<Frame caption="Gouvernance > Politiques et limites — le partage des skills décide qui peut partager un skill avec toute l’organisation.">

![La section Partage des skills avec Partager les skills avec l'organisation réglé sur Tous les membres, et l’indication que les propriétaires et les admins le peuvent toujours et qu’un membre de plus peut recevoir Publier des skills pour l'organisation dans Compétences.](https://docs.tale.dev/images/platform/governance-skill-sharing.webp)

</Frame>

Les propriétaires et les admins peuvent toujours partager avec tout le monde. Pour l’autoriser à une personne de plus sans lui donner un rôle plus élevé, attribue-lui **Publier des skills pour l'organisation** dans [Compétences](https://docs.tale.dev/fr/platform/admin/governance/competences).

Les autres membres peuvent toujours créer des skills et les partager avec leurs propres équipes. Ils ne peuvent ni créer un skill pour toute l’organisation, ni étendre l’un des leurs à **Organisation**, ni modifier sur place un skill partagé avec l’organisation. Ils peuvent restreindre un de leurs skills à leurs équipes, avec d’autres modifications dans le même enregistrement, ou le supprimer. La règle s’applique dans l’éditeur de skills, aux téléversements de zip et de dossier, aux paquets d’automatisation qui contiennent des skills et à l’API REST. Chaque refus apparaît dans les [journaux d’audit](https://docs.tale.dev/fr/platform/admin/governance/audit-logs) sous **Publication d'un skill refusée**.

Un réglage plus strict ne restreint pas les skills déjà partagés avec l’organisation. Pour les passer en revue, ouvre **Paramètres > Skills**, choisis **Filtre > Visibilité > Organisation** et consulte la colonne **Créé par**. Restreins ou supprime ceux qui ne doivent plus être partagés avec tout le monde.

<Note>

Une release de configuration gérée installe ses skills au nom du membre qui la déploie. Avant de choisir un réglage plus strict, vérifie que ce membre peut toujours partager avec tout le monde, par son rôle ou par la compétence ; sinon, la prochaine release qui contient un skill partagé avec l’organisation est refusée.

</Note>

## Routage des conversations

Utilise le **Routage des conversations** pour attribuer les nouvelles conversations selon leur point d’arrivée. Ajoute une règle, remplis ses champs, puis enregistre :

- **Arrive par** : **N'importe quelle boîte**, une boîte précise sous son nom, ou une app API. Une app API apparaît dès qu’elle a synchronisé une conversation.
- **Envoyé à** : l’adresse à laquelle la conversation a été envoyée. Elle est obligatoire pour **N'importe quelle boîte**, facultative pour une boîte précise et absente pour une app API. La comparaison des adresses ignore la casse.
- **Assigner à** : une équipe, une personne ou les deux.

Une règle pour `support@example.com` couvre aussi le courrier étiqueté comme `support+facturation@example.com`, et une règle pour l’adresse étiquetée l’emporte pour cette adresse. Si plusieurs règles correspondent, la plus précise s’applique : une boîte avec son adresse exacte, puis une boîte avec l’adresse de base, puis une adresse sur n’importe quelle boîte, enfin une boîte seule.

Une attribution d’équipe rend la conversation visible à ses membres ; une attribution individuelle la rend visible à cette personne. Avec les deux, l’une ou l’autre appartenance donne accès. Les conversations non attribuées sont réservées au triage des admins et propriétaires.

Les règles s’appliquent à l’arrivée d’une nouvelle conversation. Elles ne réattribuent pas une conversation existante lorsqu’une réponse la rejoint. Si une règle vise une personne, une équipe ou une boîte supprimée, la conversation arrive quand même sans cette attribution. Teste avec un nouveau message et vérifie la personne ou l’équipe obtenue.

## Configurer les limites de connexion séparément

Les exigences de mot de passe, limites de tentatives, délais d’inactivité de session et [règles de double facteur](https://docs.tale.dev/fr/platform/admin/two-factor-authentication) se trouvent dans **Paramètres > Gouvernance > Sécurité**. Le délai d’inactivité de l’organisation peut renforcer celui du déploiement. Avec l’authentification par en-têtes de confiance, coordonne l’expiration avec le proxy ou l’IdP, qui peut authentifier le membre à nouveau.

# Corbeille
Source: https://docs.tale.dev/fr/platform/admin/governance/trash

En tant qu’admin ou propriétaire, ouvre **Paramètres > Gouvernance > Corbeille** pour récupérer les enregistrements encore stockés après une suppression provisoire. Une suppression définitive ne peut pas être annulée ici, et toutes les suppressions de Tale ne passent pas par la corbeille.

## Restaurer un enregistrement

1. Ouvre la corbeille et utilise **Filtre > Catégorie** pour réduire la liste, ou garde la vue sans filtre pour voir tous les types pris en charge.
2. Vérifie le nom, le propriétaire, le type et la date de suppression pour distinguer les enregistrements similaires. Un chat apparaît sous son titre ; la réponse écartée lors d’une comparaison en [Arène](https://docs.tale.dev/fr/platform/chat/arena-mode) garde le titre de son chat.
3. Choisis **Restaurer** sur la ligne et lis la confirmation.
4. Pour un enregistrement expiré par rétention, saisis exactement `restore`. Confirme, puis retrouve l’enregistrement à son emplacement d’origine, par exemple dans sa liste de chats ou les connaissances.

La ligne restaurée disparaît de la corbeille. Tale consigne la restauration dans le journal d’audit. Si elle n’est plus disponible, actualise la liste : le nettoyage l’a peut-être déjà supprimée définitivement.

## Comprendre le statut

| Statut | Signification |
| --- | --- |
| **Mis à la corbeille** | L’enregistrement a été supprimé provisoirement et peut encore être restauré. |
| **Expiré** | La règle de rétention a fait expirer l’enregistrement. Le restaurer déroge à cette règle, d’où la confirmation avec le mot `restore`. |

**Expiré** ne signifie pas que le délai de récupération est déjà écoulé. La rétention marque les enregistrements comme expirés au début de leur délai de grâce ; le nettoyage définitif intervient après ce délai.

Le filtre de catégorie liste les types d’enregistrements qui passent par la corbeille : chats, documents, fichiers temporaires, retours sur les messages, contacts et conversations externes. Les versions antérieures d’un chat voyagent avec lui : elles sont mises à la corbeille et restaurées avec le chat et n’apparaissent jamais comme lignes à part. Les autres données, comme les exécutions d’automatisation, les données d’usage, les entrées d’audit et les événements de filtre de chat, sont supprimées directement ou avec leur parent et n’ont pas d’action de restauration ici.

## Vérifier le délai de récupération

La règle de rétention de l’organisation définit le délai de grâce. S’il est positif, les enregistrements expirés pris en charge restent récupérables jusqu’au nettoyage. Zéro autorise un nettoyage définitif immédiat. Vérifie la règle active dans [Politiques et limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits), sans supposer un nombre de jours fixe.

Une corbeille vide signifie qu’aucun enregistrement n’est récupérable dans cette vue. Elle ne prouve pas qu’aucune suppression n’a eu lieu. Efface les filtres de catégorie avant de conclure qu’un enregistrement manque.

La corbeille ne présente jamais un chargement échoué comme vide. Si la liste ne peut pas être chargée, une alerte le signale à la place du tableau et propose **Réessayer**, au lieu de l’état vide. Si des enregistrements sont déjà listés mais que les suivants ou une actualisation ne peuvent pas être chargés, une note au-dessus de la liste le signale et propose **Réessayer**. Le décompte sous la liste n’affirme alors plus afficher tous les enregistrements.

## Tenir compte des gels juridiques

Un [gel juridique](https://docs.tale.dev/fr/platform/admin/governance/legal-hold) empêche la rétention ou l’effacement de supprimer les données couvertes. Il préserve les données encore présentes, sans récupérer celles déjà supprimées définitivement. Vérifie l’historique des gels et de la rétention pour comprendre pourquoi un enregistrement est arrivé, ou non, dans la corbeille.

# Analyse de l’usage
Source: https://docs.tale.dev/fr/platform/admin/governance/usage-analytics

En tant qu’admin ou propriétaire, ouvre **Paramètres > Métriques > Utilisation** pour comprendre quelles tâches consomment des ressources d’IA. Choisis d’abord la période, puis les répartitions utiles pour expliquer une variation de coût ou de volume.

<Frame caption="Paramètres > Métriques > Utilisation : les totaux, le graphique des tokens et les assistants les plus sollicités sur les 30 derniers jours.">

![La page Métriques d’utilisation sur les 30 derniers jours indique 14 requêtes, 448 tokens, un coût enregistré de 0,00 dollar US et une personne active. Le graphique des tokens n’a de barre que pour le jour en cours, répartie entre entrée et sortie ; en dessous, le tableau des assistants les plus sollicités liste l’assistant et la génération des titres de chat.](https://docs.tale.dev/images/platform/metrics-usage.webp)

</Frame>

## Examiner une hausse d’usage

1. Ouvre **Filtre** et choisis une **Période** de 7, 30 ou 90 jours. La vue initiale couvre 30 jours.
2. Compare les requêtes, les tokens, le coût total et les utilisateurs actifs. Une hausse du nombre de requêtes et des réponses plus longues ont des causes différentes.
3. Choisis la mesure et la granularité du graphique dans le menu de filtre pour repérer le début du changement.
4. Examine les tableaux par assistant, par modèle et par personne. Sélectionne un assistant ou un modèle pour réduire la vue ; retire sa pastille de filtre pour revenir à la vue plus large.

Les noms d’assistants peuvent inclure des tâches auxiliaires, comme la création des titres de chat. Le nombre de requêtes ne correspond donc pas toujours au nombre de messages envoyés. La synthèse vocale possède son propre tableau de modèles vocaux.

**Utilisation par utilisateur** attribue chaque requête à une personne : le membre qui a envoyé le message de chat ou lancé l’exécution d’agent, y compris par l’API REST ou le point d’accès MCP. Les exécutions démarrées par une planification, un webhook ou un événement n’ont personne derrière elles. Leur usage apparaît sur une seule ligne nommée **Automatisations (déclencheurs)**, qui ne compte pas comme utilisateur actif. Dans le tableau des assistants, un agent de projet et une automatisation apparaissent chacun sous leur nom. [Comment l’usage est compté](https://docs.tale.dev/fr/platform/admin/governance/usage-attribution) explique la règle pour chaque type de travail.

## Lire les coûts avec les tokens

Le tableau de bord utilise les données d’usage et de consommation enregistrées. Les tokens d’entrée et de sortie sont séparés. Des services comme la sortie vocale ou la génération d’images peuvent utiliser d’autres unités de facturation. Le total de tokens ne suffit donc pas à expliquer tous les coûts. Les tokens d’entrée comprennent aussi la partie d’un prompt qu’un fournisseur a lue dans son cache ou y a écrite. Cette partie est facturée autrement que le reste de l’entrée : une exécution qui réutilise un long prompt peut donc afficher beaucoup de tokens d’entrée pour un coût faible.

Une image créée par un agent apparaît sous son modèle d’images dans **Principaux modèles** et sous l’agent ou l’automatisation dans **Principaux assistants**, à raison d’une requête par image et sans tokens. Son coût est le montant indiqué par OpenRouter ou, pour OpenAI, le tarif public des tokens d’image indiqués par OpenAI. Une requête facturée par le fournisseur sans image exploitable compte de la même façon.

Lis le coût affiché comme l’usage enregistré par l’application, pas comme une facture du fournisseur. Tarifs, abonnements, crédits et appels non mesurés peuvent modifier la comparaison. Un zéro affiché ne prouve pas que le fournisseur n’a rien facturé.

## Réagir à une alerte de budget

Utilise la même période et la tâche concernée pour examiner une alerte. Identifie la personne, l’assistant ou le modèle à l’origine de la hausse. Décide ensuite de modifier le fonctionnement, de choisir un autre modèle ou d’ajuster un plafond dans [Politiques et limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits).

Consulte l’[analyse des retours](https://docs.tale.dev/fr/platform/admin/governance/feedback-analytics) avant de changer de modèle uniquement pour son coût : dépenser moins reste utile si les résultats répondent toujours au besoin.

## Comprendre un historique incomplet

Les graphiques reflètent les données d’usage que Tale conserve encore. Les règles de l’organisation et du déploiement déterminent l’historique disponible ; il n’existe pas de garantie universelle de 365 jours. Vérifie la période, les filtres et la rétention du registre d’usage si une activité attendue manque.

Si les métriques ne peuvent pas être chargées, la page le signale et propose **Réessayer** au lieu d’afficher des zéros ou des tableaux vides. La période et les filtres choisis restent en place. Si une actualisation échoue, les chiffres déjà affichés restent, avec une note indiquant qu’ils ne sont peut-être plus à jour. Si **Réessayer** échoue encore, demande à l’opérateur du déploiement de vérifier que les services de Tale fonctionnent.

# Comment l’usage est compté
Source: https://docs.tale.dev/fr/platform/admin/governance/usage-attribution

Chaque requête d’IA que Tale émet pour ton organisation est enregistrée une fois, imputée à une personne et mesurée par rapport aux [règles de budget](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits) qui s’appliquent à cette personne. Cette page explique qui est cette personne pour chaque type de travail, quelles limites le travail consomme et où tu le retrouves dans l’[analyse de l’usage](https://docs.tale.dev/fr/platform/admin/governance/usage-analytics). Les membres voient leur propre part sous [Paramètres > Utilisation](https://docs.tale.dev/fr/platform/member/preferences#usage-limits).

## Ce qui compte comme usage

Tale enregistre une requête chaque fois qu’un modèle ou un service mesuré tourne pour ton organisation : une réponse de chat, y compris une réponse régénérée ou modifiée et les deux côtés d’une comparaison de modèles ; le court appel de modèle qui donne son titre à un nouveau chat ; un tour d’un agent géré qui travaille sur une tâche ou dans une automatisation ; une image que crée un tel agent ; une sortie vocale ; la transcription d’un enregistrement téléversé ; un appel de connecteur mesuré ; et un appel aux endpoints de modèles avec une clé API. Chaque enregistrement porte les tokens ou unités consommés et le coût estimé d’après le tarif public du fournisseur à ce moment-là ; pour un appel aux endpoints de modèles, c’est le coût mesuré par la passerelle de modèles.

## À qui une requête est imputée

La règle est la même partout : une requête compte pour la personne qui a demandé le travail. La porte par laquelle elle est arrivée, l’application, l’API REST, le point d’accès MCP ou les endpoints de modèles, n’y change rien.

| Travail | Compte pour | Compte aussi pour | Apparaît dans l’analyse de l’usage comme |
| --- | --- | --- | --- |
| Une réponse de chat, ou le titre d’un nouveau chat | Le membre qui a envoyé le message | La clé API, quand le message est passé par l’API REST | L’assistant utilisé ; un titre sous `thread-title` |
| Une exécution d’agent sur une tâche | Le membre qui a lancé l’exécution depuis la tâche, ou avec un commentaire ou une description de tâche qui mentionne l’agent ; pour une exécution lancée par un autre agent ou par une étape d’automatisation, le membre pour qui compte l’exécution de cet agent ou de cette automatisation | — | Le nom de l’agent sous **Principaux assistants** |
| Une exécution d’automatisation lancée par quelqu’un | Le membre qui l’a lancée depuis la liste des exécutions, le builder, un chat, une tâche, l’API REST ou le point d’accès MCP | La clé API, quand l’exécution a été lancée avec une clé | Le nom de l’automatisation sous **Principaux assistants** |
| Une exécution d’automatisation lancée par un déclencheur | Personne : une planification, un webhook ou un événement n’a personne derrière lui | — | La ligne **Automatisations (déclencheurs)** sous **Utilisation par utilisateur** |
| Une exécution d’agent de projet lancée par une planification, ou une exécution qu’un autre agent a lancée depuis une telle exécution | Personne, comme pour l’exécution lancée par la planification elle-même | — | La ligne **Automatisations (déclencheurs)** sous **Utilisation par utilisateur**, et le nom de l’agent sous **Principaux assistants** |
| Une image que crée un agent | La personne pour qui l’exécution de l’agent compte : celle qui l’a lancée, ou personne pour une exécution lancée par un déclencheur | La clé API, quand l’exécution a été lancée avec une clé | Le nom de l’agent ou de l’automatisation sous **Principaux assistants**, et le modèle d’images sous **Principaux modèles** |
| Une sortie vocale ou une transcription | Le membre qui l’a demandée | — | **Sortie vocale** ou **Transcription** sous **Principaux assistants** ; la sortie vocale aussi sous **Principaux modèles vocaux** |
| Un appel de connecteur mesuré | Le membre dont la requête a provoqué l’appel | — | L’assistant qui l’a fait, ou **Connector** |
| Un appel aux [endpoints de modèles](https://docs.tale.dev/fr/develop/use-tale-from-your-editor#model-endpoints) | Le membre dont la clé API l’a envoyé | La clé API | **Appel API direct** sous **Principaux assistants** |

Une nouvelle tentative d’une exécution d’agent poursuit l’exécution lancée par son initiateur ; son usage reste donc imputé à cette personne. Quand une intégration agit avec une clé API pour un autre membre, l’exécution compte pour ce membre, et la limite de la clé la compte aussi.

## Quelles limites s’appliquent

- **Les limites personnelles, d’équipe et de rôle** s’appliquent à la personne à qui une requête est imputée. Une exécution lancée par une planification, un webhook ou un événement n’a pas de telle personne et n’est mesurée par rapport à aucune d’elles.
- **Les limites de l’organisation** s’appliquent à toute requête, y compris aux exécutions lancées par un déclencheur.
- **Les limites de clé API** s’appliquent aux requêtes authentifiées par cette clé : les messages de chat qu’elle a envoyés, ses appels aux endpoints de modèles et les exécutions qu’elle a lancées.

Quand une limite est atteinte, Tale refuse la requête suivante avant de l’exécuter et nomme la limite. Un tour d’agent géré est refusé à son démarrage ; un tour déjà en cours conserve l’enveloppe qui lui a été accordée. Une image que l’agent demande pendant son tour est vérifiée à part, avant l’appel au modèle d’images : si une limite est atteinte, Tale refuse l’image et le tour continue. L’image puise aussi dans l’enveloppe du tour qui l’a demandée. [Comment les règles se combinent](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits#how-rules-combine) traite le cas où plusieurs règles visent la même personne.

## Trois situations à connaître

**Un collègue mentionne ton agent dans un commentaire ou dans la description d’une tâche.** Publier le commentaire ou enregistrer la description lance une exécution, et celle-ci compte pour le collègue qui en est l’auteur, pas pour toi en tant que créateur de l’agent.

**Une automatisation planifiée dépense chaque nuit.** Ses exécutions apparaissent sur la ligne **Automatisations (déclencheurs)**. Elles n’augmentent jamais l’usage personnel de quelqu’un ni le nombre d’utilisateurs actifs, et seules les limites de l’organisation peuvent les arrêter. Définis une limite de coût ou de requêtes pour l’organisation si tu as besoin d’un plafond pour elles.

**Une intégration utilise une clé API au nom d’un membre.** Les limites personnelles et d’équipe du membre voient l’exécution, et la limite de la clé aussi. Deux plafonds s’appliquent, et le plus strict refuse en premier.

## Ce que voient les membres

**Paramètres > Utilisation** liste chaque limite qui s’applique au membre connecté avec son utilisation actuelle : les chats envoyés, les sorties vocales demandées, les appels aux endpoints de modèles et les exécutions d’agents lancées, quelle que soit la façon de les lancer. Les limites partagées d’équipe et d’organisation y figurent aussi, parce qu’elles peuvent être atteintes avant une limite personnelle.

# Membres et rôles
Source: https://docs.tale.dev/fr/platform/admin/members-and-roles

Ajoute des personnes dans **Paramètres > Membres**, puis choisis le rôle adapté à leur travail. Le rôle détermine les actions autorisées. Les accès aux projets, les équipes et l’attribution des conversations déterminent les ressources accessibles.

<Video src="https://docs.tale.dev/videos/fr/tutorials/ep8-people/ep8-people.fr.mp4" poster="https://docs.tale.dev/videos/fr/tutorials/ep8-people/ep8-people.fr.webp" captions="https://docs.tale.dev/videos/fr/tutorials/ep8-people/ep8-people.fr.vtt" lang="fr" title="Épisode 8 — Personnes, rôles & équipes" caption="Épisode 8 — Personnes, rôles & équipes (2:06)">

</Video>

<Frame caption="Paramètres > Membres — chaque compte et le rôle qui le borne.">

![La page de paramètres Membres listant le propriétaire de l’espace de travail et quatre autres personnes, chacune avec son badge de rôle, à côté d’un bouton Ajouter un membre.](https://docs.tale.dev/images/get-started/settings-organization-members.webp)

</Frame>

## Ajouter une personne

Tu dois avoir le rôle Propriétaire ou Admin pour gérer les membres.

1. Ouvre **Paramètres > Membres** et sélectionne **Ajouter un membre**.
2. Saisis son **Courriel** et, si tu le souhaites, son **Nom**.
3. Choisis un **Rôle**. Membre convient à l’utilisation quotidienne ; le tableau ci-dessous précise quand donner davantage de droits.
4. Pour un nouveau compte Tale, définis un **Mot de passe** qui respecte les exigences affichées. Si l’adresse appartient déjà à un compte, Tale réutilise ses identifiants et masque le champ du mot de passe.
5. Sélectionne **Ajouter un membre**. Pour un nouveau compte, conserve les identifiants affichés dans la confirmation avant de la fermer, puis transmets-les par le canal prévu dans ton organisation.

La personne apparaît dans la liste. Ce parcours n’envoie ni invitation ni courriel de réinitialisation du mot de passe : en ajoutant quelqu’un, tu confirmes son adresse. Le compte fonctionne donc partout tout de suite, y compris dans les applications où l’on se connecte avec son compte Tale. Si l’adresse est déjà membre de cette organisation, le formulaire le signale sans créer de doublon.

<Tip>

Ajoute ensuite la personne aux équipes dont elle a besoin. Un rôle seul ne donne pas les accès aux projets d’une équipe ni à sa file de conversations.

</Tip>

## Choisir un rôle

| Rôle | Travail habituel | Administration de l’organisation |
| --- | --- | --- |
| **Propriétaire** | Toutes les tâches du produit et de son administration | Peut aussi transférer la propriété et supprimer l’organisation, ce qui efface également ses sandboxes et leurs fichiers ; la suppression demande de taper le nom de l’organisation avant d’activer le bouton. |
| **Admin** | Gérer les personnes, les services, les politiques et le travail de l’équipe | Tous les paramètres de l’organisation, sans transfert de propriété. |
| **Développeur** | Créer des agents, des automatisations et des intégrations | Paramètres techniques des fournisseurs, connecteurs et API ; pas de gestion des membres. |
| **Éditeur** | Entretenir les contenus et traiter le travail quotidien | Modification du contenu ; pas d’accès à **Automatisations** ; lecture seule des ressources de connecteurs. |
| **Membre** | Utiliser le chat, lire les ressources partagées et créer des tâches de projet, en confiant les siennes aux agents du projet | Pas d’administration ; peut donner un avis sur les messages. |
| **Désactivé** | Aucun accès actif | Conserve l’adhésion sans accorder de permissions. |

Seuls les propriétaires, les admins et les développeurs voient **Automatisations**, dans la navigation comme dans les projets ; pour les autres, un lien vers une automatisation affiche **Accès refusé**.

Les personnes qui ne sont ni propriétaires ni admins ne peuvent pas ouvrir **Paramètres > Membres** ; elles voient leur propre rôle dans [**Paramètres > Compte > Ton rôle**](https://docs.tale.dev/fr/platform/member/preferences#role).

Les tâches de projet suivent une règle qui leur est propre : toute personne qui peut ouvrir un projet y crée des tâches et modifie les siennes, celles qu’elle a créées ou qui lui sont attribuées, tandis que les Éditeurs et les rôles supérieurs modifient toutes les tâches. Les paramètres, les agents et les fichiers du projet restent réservés aux Éditeurs. [Gérer les tâches d’un projet](https://docs.tale.dev/fr/platform/projects/tasks#qui-peut-creer-et-modifier-les-taches) détaille ce qu’un Membre peut faire de ses propres tâches.

Ce tableau décrit les capacités des rôles, sans garantir l’accès à chaque élément. Les conversations suivent leur attribution : une personne voit le travail qui lui est attribué ou qui appartient à ses équipes. Les conversations non attribuées restent réservées aux propriétaires et aux admins pour le triage. Consulte [le routage des conversations](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits#routage-des-conversations).

Seuls les propriétaires et les admins peuvent lire les journaux d’audit. Les actions des autres rôles peuvent produire des entrées, sans leur donner accès au journal.

## Changer un rôle ou réinitialiser un mot de passe

Dans le menu de la ligne de la personne, sélectionne **Modifier**, puis change le **Rôle**. Sélectionne **Enregistrer** et vérifie le rôle dans la liste. Pour rétablir l’accès d’un membre désactivé, choisis explicitement le rôle à lui attribuer.

Le dialogue permet aussi de changer le nom affiché. Le courriel est en lecture seule. Pour définir un nouveau mot de passe, active **Mettre à jour le mot de passe**, saisis une valeur conforme aux exigences affichées, puis enregistre. Vérifie l’identité de la personne selon la procédure de ton organisation avant de réinitialiser son compte.

Ce menu ne permet pas de modifier ton propre rôle, d’attribuer Propriétaire dans la liste des rôles, ni de rétrograder le dernier administrateur. Les propriétaires existants et le créateur de l’organisation ont aussi des rôles protégés. Si une modification est refusée, vérifie le compte concerné avant d’essayer un autre rôle.

## Transférer la propriété

Un propriétaire peut sélectionner **Transférer la propriété** dans le menu d’un autre membre. Lis la confirmation : la personne choisie devient Propriétaire et le propriétaire qui effectue le transfert devient Admin. Utilise cette action pour transmettre la responsabilité de l’organisation, pas pour une promotion ordinaire.

## Retirer ou rétablir l’accès

Choisis **Désactivé** pour arrêter l’accès tout en conservant l’adhésion. L’action **Supprimer** de la ligne retire l’adhésion à cette organisation. Elle supprime aussi, avec leurs fichiers, les espaces de travail de sandbox propres aux [exécutions d’agent que la personne a démarrées](https://docs.tale.dev/fr/platform/projects/tasks#executions-demarrees-par-un-membre) ; **Désactivé** les conserve. Vérifie d’abord les travaux partagés et les responsabilités dans les équipes. Retirer une adhésion n’est pas une [demande d’effacement des données](https://docs.tale.dev/fr/platform/admin/governance/data-subject-requests).

Si un membre perd son authentificateur ou sa passkey, ouvre **Modifier** et utilise les contrôles de sécurité correspondants. [L’authentification à deux facteurs](https://docs.tale.dev/fr/platform/admin/two-factor-authentication) explique la récupération, la réinitialisation et leurs effets sur les sessions.

# Administration
Source: https://docs.tale.dev/fr/platform/admin/overview

Les paramètres de l’organisation servent à donner accès à Tale, à connecter les services utiles et à définir les règles de traitement du travail et des données. Commence par la tâche dont tu as besoin : tous les paramètres ne sont pas nécessaires pour que ton équipe puisse démarrer.

<Video src="https://docs.tale.dev/videos/fr/tutorials/ep9-governance/ep9-governance.fr.mp4" poster="https://docs.tale.dev/videos/fr/tutorials/ep9-governance/ep9-governance.fr.webp" captions="https://docs.tale.dev/videos/fr/tutorials/ep9-governance/ep9-governance.fr.vtt" lang="fr" title="Épisode 9 — Gouvernance, coûts & confiance" caption="Épisode 9 — Gouvernance, coûts & confiance (2:48)">

</Video>

## Préparer une organisation

1. [Ajoute les membres et choisis leurs rôles](https://docs.tale.dev/fr/platform/admin/members-and-roles), en fonction du travail de chacun.
2. [Crée des équipes](https://docs.tale.dev/fr/platform/admin/teams) lorsque plusieurs personnes ont besoin des mêmes accès aux projets ou aux conversations.
3. [Connecte un fournisseur IA](https://docs.tale.dev/fr/platform/admin/providers) pour rendre des modèles disponibles dans les chats et les agents.
4. [Ajoute les identifiants des connecteurs](https://docs.tale.dev/fr/platform/admin/connectors) utilisés par tes workflows.

Les propriétaires et les admins gèrent les paramètres de l’organisation. Les développeurs ont accès aux paramètres techniques des intégrations, mais ne peuvent ni gérer les membres ni ouvrir toute la partie gouvernance. Les paramètres personnels du compte restent distincts.

## Trouver le bon réglage

| Tu veux… | Ouvre… |
| --- | --- |
| Choisir les modèles par défaut ou limiter les modèles proposés | [Modèles](https://docs.tale.dev/fr/platform/admin/governance/content-models) |
| Limiter l’utilisation, les fichiers ou la conservation | [Politiques et limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits) |
| Filtrer les messages et définir les instructions de l’organisation | [Garde-fous](https://docs.tale.dev/fr/platform/admin/governance/guardrails) |
| Examiner des actions ou des dépenses | [Journaux d’audit](https://docs.tale.dev/fr/platform/admin/governance/audit-logs) ou [métriques d’utilisation](https://docs.tale.dev/fr/platform/admin/governance/usage-analytics) |
| Repérer les réponses de chat, tours d’agent ou exécutions d’automatisation qui échouent | [Métriques d’exploitation](https://docs.tale.dev/fr/platform/admin/governance/operations-metrics) |
| Récupérer des données conservées ou empêcher leur suppression | [Corbeille](https://docs.tale.dev/fr/platform/admin/governance/trash) ou [gel juridique](https://docs.tale.dev/fr/platform/admin/governance/legal-hold) |
| Traiter une demande d’effacement | [Demandes des personnes concernées](https://docs.tale.dev/fr/platform/admin/governance/data-subject-requests) |

## Connexion, intégrations et apparence

Configure [le SSO d’entreprise](https://docs.tale.dev/fr/platform/admin/enterprise-sso) pour ton fournisseur d’identité et [l’authentification à deux facteurs](https://docs.tale.dev/fr/platform/admin/two-factor-authentication) pour protéger les comptes. Les [clés API](https://docs.tale.dev/fr/platform/admin/api-keys) permettent à un logiciel d’appeler Tale.

La page [Personnalisation visuelle](https://docs.tale.dev/fr/platform/admin/branding) sert à modifier le logo et les couleurs. [Sandboxes](https://docs.tale.dev/fr/platform/admin/sandboxes) présente la capacité d’exécution et les limites par type de tâche ; avec les [appareils de sandbox](https://docs.tale.dev/fr/platform/admin/sandbox-devices), les sandboxes de ton organisation tournent sur tes propres machines. Pour les accès d’un agent de projet à ces ressources, consulte [Agents côté administration](https://docs.tale.dev/fr/platform/admin/agents).

Après une mise à jour, [les nouveautés](https://docs.tale.dev/fr/platform/admin/changelog) t’aident à repérer les changements qui concernent ton équipe.

# Fournisseurs IA
Source: https://docs.tale.dev/fr/platform/admin/providers

Connecte un fournisseur IA avant de lancer des chats ou des agents dans Tale. Dans **Paramètres > Fournisseurs IA**, les propriétaires, admins et développeurs gèrent les identifiants de l’organisation. Le fournisseur définit la connexion et les méthodes d’authentification ; les identifiants donnent à ton organisation accès à ce fournisseur.

<Frame caption="Chaque ligne correspond à des identifiants. Le badge Par défaut indique ceux utilisés lorsqu’un appel n’en désigne pas.">

![La page des fournisseurs IA présente des identifiants avec leur fournisseur, leur méthode d’authentification et le badge Par défaut.](https://docs.tale.dev/images/get-started/settings-providers.webp)

</Frame>

## Ajouter les premiers identifiants

1. Sélectionne **Ajouter des identifiants**, puis le fournisseur. Les fournisseurs déjà configurés apparaissent en premier ; les choisir à nouveau permet d’ajouter d’autres identifiants.
2. Choisis une **Méthode d'authentification** si le fournisseur en propose plusieurs.
3. Vérifie le champ **Nom**. Il est prérempli avec le nom du fournisseur, suivi d’un numéro si d’autres identifiants de ce fournisseur portent déjà ce nom : `OpenRouter`, puis `OpenRouter 2`. Un nom qui indique l’usage, comme `Clé de production` ou `Équipe finance`, permet de distinguer plusieurs identifiants d’un même fournisseur. Renseigne ensuite les champs requis par la méthode.
4. Vérifie la liste **Modèles autorisés**. Pour un fournisseur avec catalogue, une liste vide autorise les modèles du catalogue. Sans catalogue, tu dois préciser les identifiants des modèles.
5. Sélectionne **Ajouter**. Vérifie la ligne créée et définis-la par défaut pour ce fournisseur si les requêtes habituelles doivent l’utiliser.

Pour des identifiants de type **Clé API** ou **Variable d'environnement**, envoie un court message de test dans un chat avec le modèle prévu. Le modèle doit être disponible via des identifiants actifs et autorisé par les règles de l’organisation. Vérifie les identifiants d’abonnement avec un agent de tâche ou d’automatisation, comme indiqué ci-dessous. Enregistrer des identifiants ne prouve pas que le fournisseur acceptera les requêtes.

## Choisir la méthode d’authentification

| Méthode | Informations à fournir | Usage |
| --- | --- | --- |
| **Clé API** | La clé secrète du fournisseur | Accès API facturé à l’usage. Le secret enregistré est chiffré et seul un fragment masqué reste visible. |
| **Variable d'environnement** | Le nom d’une variable du déploiement | L’opérateur gère le secret hors de l’interface. Son nom doit commencer par `TALE_PROVIDER_KEY_`. |
| **Clé d'abonnement** | Un secret d’abonnement pris en charge | Exécution dans l’environnement d’agent du fournisseur, dans les tâches et les automatisations, jamais dans le chat. |
| **Courtier d'abonnement** | L’adresse du courtier et la configuration de sa réponse | Le déploiement obtient auprès du courtier des tokens d’abonnement pour l’environnement d’agent du fournisseur, dans les tâches et les automatisations, jamais dans le chat. |

Seules les méthodes du fournisseur sélectionné apparaissent. Référencer une variable ne la crée pas : demande à l’opérateur de la fournir selon le [guide de configuration des fournisseurs](https://docs.tale.dev/fr/self-hosted/configuration/providers).

## Utiliser les abonnements dans les tâches, pas dans le chat

Des identifiants de type **Clé d'abonnement** ou **Courtier d'abonnement** ne fonctionnent que dans l’environnement d’agent auquel ils sont liés : Claude Code pour un abonnement Anthropic et pour les forfaits de programmation de Moonshot et de Z.ai, Codex pour un abonnement ChatGPT, Gemini CLI pour Gemini et Hermes pour Nous Portal. Les fournisseurs n’autorisent pas les jetons d’abonnement dans d’autres applications, et Anthropic les refuse depuis tout client autre que Claude Code. Le chat appelle l’API du fournisseur depuis Tale même : il ne peut donc pas utiliser d’identifiants d’abonnement.

Tale exécute donc un abonnement dans les tâches et les automatisations, où son environnement travaille dans une sandbox. Le chat ne propose que les modèles servis par des identifiants de type **Clé API** ou **Variable d'environnement**. L’application l’indique à trois endroits : le formulaire d’ajout affiche **Tâches et automatisations uniquement** quand tu choisis une méthode d’abonnement, chaque ligne d’abonnement du tableau des identifiants porte la même mention, et la liste des modèles du chat nomme les abonnements qu’elle laisse de côté.

Pour discuter avec un modèle auquel tu accèdes par un abonnement, ajoute des identifiants par clé API ou variable d’environnement pour le même fournisseur, ou connecte un fournisseur comme OpenRouter qui sert ce modèle.

## Connecter un courtier d’abonnement

Les courtiers d’abonnement prennent en charge les abonnements Anthropic via Claude Code et les abonnements OpenAI ChatGPT via Codex. Ces identifiants servent aux agents de tâche et d’automatisation ; les chats nécessitent des identifiants d’accès direct à l’API, pour les [raisons expliquées plus haut](https://docs.tale.dev/fr/platform/admin/providers#utiliser-les-abonnements-dans-les-taches-pas-dans-le-chat).

| Fournisseur et agent | Variable cible |
| --- | --- |
| Anthropic · Claude Code | `CLAUDE_CODE_OAUTH_TOKEN` |
| OpenAI · Codex | `TALE_SUBSCRIPTION_TOKEN` |

À l’ajout des identifiants, choisis **Courtier d'abonnement** et demande à ton opérateur l’adresse du courtier et les paramètres d’authentification. Utilise une adresse qui ne fournit que les jetons du fournisseur choisi. Avec Tale AI Gateway, il s’agit de `/api/tokens/anthropic` ou de `/api/tokens/openai`.

Renseigne `$.tokens` dans **Chemin du tableau de jetons**, `access_token` dans **Champ du jeton** et la valeur du tableau ci-dessus dans **Variable d'environnement cible**. Sous **Avancé**, utilise `status` pour **Champ de statut**, `active` pour **Valeur de statut actif** et `expires_at` pour **Champ d'expiration**, et laisse **Marge de sécurité avant expiration (ms)** à sa valeur par défaut. Tale AI Gateway retient lui-même un compte dont le jeton va bientôt être actualisé tant qu’un autre compte peut prendre le travail ; Tale l’utilise quand même si aucun autre compte disponible ne peut prendre l’exécution, par exemple pendant que les autres sont en pause après avoir atteint une limite de requêtes. Les chemins peuvent différer avec un autre courtier. Un pool OpenAI doit aussi fournir l’`account_id` du fournisseur pour chaque jeton utilisable ; l’`id` propre au courtier est un identifiant de compte distinct.

Pour OpenAI, limite **Modèles autorisés** aux identifiants de modèles pris en charge par ton abonnement ChatGPT. Le catalogue de l’API OpenAI peut inclure des modèles auxquels cet abonnement ne donne pas accès.

Pour utiliser un modèle GPT-6 avec l’abonnement ChatGPT, enregistre les identifiants du courtier OpenAI, puis configure un [agent de projet](https://docs.tale.dev/fr/platform/projects/project-agents) en choisissant **Codex** sous **Harness**. Sous **Modèle**, recherche l’identifiant du modèle, par exemple `gpt-6.1-sol`, et sélectionne l’entrée **OpenAI · Abonnement**. [Utiliser les modèles GPT-6](https://docs.tale.dev/fr/platform/admin/providers#utiliser-les-modeles-gpt-6) indique où chaque modèle fonctionne par ailleurs.

Choisis **Sélection du jeton** selon la répartition souhaitée pour les nouveaux tours d’agent :

- **Aléatoire**, le choix initial, donne à chaque compte utilisable la même probabilité à chaque sélection.
- **Premier utilisable** prend toujours le premier compte utilisable dans l’ordre du courtier. Ce choix établit un ordre de préférence, sans répartir le travail.
- **Round-robin** choisit le compte utilisable dont la dernière sélection est la plus ancienne. Tous les processus backend partagent cet historique pour l’organisation et les identifiants concernés, y compris lors de requêtes simultanées. L’ordre des réponses et les redémarrages du backend conservent cet historique ; des identifiants de compte stables chez le courtier le préservent aussi lors des changements de jetons. Cela répartit les sélections, sans garantir une consommation de jetons ou un nombre d’agents en cours identiques.

Enregistre les identifiants, puis lance une courte tâche ou automatisation avec le fournisseur et l’environnement d’agent correspondants. Vérifie que l’agent termine sa réponse. Si aucun compte n’est utilisable, demande à l’opérateur de vérifier l’autorisation des comptes, l’expiration et les actualisations prévues des jetons, ainsi que les quotas signalés. La [référence de configuration du courtier](https://docs.tale.dev/fr/self-hosted/configuration/providers#connecter-un-courtier-dabonnement) décrit les métadonnées facultatives, les valeurs par défaut et les solutions aux erreurs.

## Utiliser les modèles GPT-6

Le catalogue OpenAI comprend GPT-6 Astra (`gpt-6-astra`), GPT-6 Sol (`gpt-6-sol`), GPT-6 Luna (`gpt-6-luna`) et GPT-6.1 Sol (`gpt-6.1-sol`).

- Le **chat** propose les quatre via des identifiants OpenAI de type **Clé API** ou **Variable d'environnement**, y compris pour la sélection automatique du modèle. Astra et GPT-6.1 Sol n’appellent des tools que via l’API Responses d’OpenAI : Tale les interroge donc par cette API. GPT-6 Sol et Luna n’acceptent les tools du chat qu’avec le raisonnement désactivé : le sélecteur ne propose donc pas de niveau d’**Effort de raisonnement** pour eux.
- Les **agents de projet et les automatisations** n’exécutent Astra et GPT-6.1 Sol que sur **Codex**, l’environnement qui parle l’API Responses, avec des identifiants par clé API, variable d’environnement ou abonnement ChatGPT. Le sélecteur de modèle ne les propose pour aucun autre environnement.

## Configurer Azure ou une adresse propre au compte

Azure OpenAI demande une **URL de l'endpoint**, généralement `https://<resource>.openai.azure.com/openai/v1`. Les identifiants appartiennent à cette ressource. Les identifiants de modèle Azure sont les noms de déploiement définis dans la ressource : saisis-les dans la liste **Modèles autorisés**. Sans catalogue, laisser cette liste vide ne rend aucun modèle disponible.

Utilise les adresses et identifiants documentés par le fournisseur. Le nom affiché sur une page commerciale n’est pas forcément celui que son API accepte.

## Définir un fournisseur personnalisé

Une organisation peut connecter un endpoint absent du catalogue livré : un serveur de modèles auto-hébergé comme vLLM ou Ollama, ou une passerelle interne qui parle l’API OpenAI ou Anthropic. Choisis **Ajouter des identifiants**, puis **Fournisseur personnalisé**, l’entrée fixée sous le catalogue :

1. Saisis un **Nom du fournisseur**. Il nomme le fournisseur et cet identifiant ; le nom technique du fournisseur en est dérivé.
2. Choisis le **Format d'API** que parle l’endpoint et saisis son **URL de base**, la racine d’API à laquelle la plateforme ajoute ses chemins. Un hôte public exige `https`.
3. Sous **Modèles**, garde **Découvrir depuis l'endpoint** pour lire la liste `/models` du serveur avec cette clé, ou choisis **Saisir les ID de modèles** et indique les ID exacts dans **Modèles autorisés** si l’endpoint ne sait pas lister ses modèles.
4. Renseigne la **Clé API** (ou la variable d’environnement), puis choisis **Ajouter**.

La ligne de l’identifiant affiche désormais le fournisseur avec le badge **Personnalisé**, et le fournisseur apparaît avec le même badge dans le catalogue d’**Ajouter des identifiants** ; le choisir là ajoute un autre identifiant pour lui. Une adresse privée ou de boucle locale exige en plus l’autorisation des hôtes privés dans le déploiement ; c’est l’opérateur qui la définit, et enregistrer l’identifiant ne l’accorde pas. Demande à l’opérateur de préparer l’accès réseau et la politique du déploiement, puis suis [Connecter un serveur de modèles local](https://docs.tale.dev/fr/tutorials/admin/connect-local-provider). Si des agents de programmation utiliseront le fournisseur, teste aussi une session d’agent : leur trafic passe par une passerelle distincte qui doit aussi disposer de l’accès réseau et faire confiance au certificat.

Dans le menu de la ligne, **Vérifier les modèles** relit la liste de modèles de l’endpoint avec cette clé, **Modifier les identifiants** change, à côté du nom, l’URL de base, le format d’API et la source des modèles, et **Supprimer** retire l’identifiant. Lors de la modification, **Enregistrer** change le fournisseur et l’identifiant ensemble : un nom déjà utilisé ou une version périmée est refusé avant toute modification. Si quelqu’un a enregistré le fournisseur ou cet identifiant après que tu as ouvert la boîte de dialogue, ton enregistrement est refusé au lieu d’écraser sa modification ; rouvre la boîte de dialogue pour charger les réglages actuels. Supprimer le dernier identifiant d’un fournisseur retire aussi le fournisseur lui-même ; la boîte de dialogue le dit avant. Chaque version enregistrée de la définition reste dans l’historique de configuration de l’organisation. Ce que le formulaire ne couvre pas, comme un endpoint pour les agents de programmation, se règle dans le fichier de définition que décrit le [guide de configuration des fournisseurs](https://docs.tale.dev/fr/self-hosted/configuration/providers).

Si la connexion est interrompue pendant l’enregistrement, le résultat peut être incertain. Recharge la page et vérifie les réglages du fournisseur et l’identifiant avant de réessayer : une erreur de connexion ne signifie pas que les modifications ont été annulées.

## Définir le choix par défaut et l’accès aux modèles

Sélectionne **Définir par défaut** dans le menu d’une ligne. Chaque fournisseur a un seul choix par défaut ; en sélectionner un autre déplace le badge. Des identifiants désactivés ne peuvent pas devenir le choix par défaut. En son absence, l’appelant doit nommer les identifiants à utiliser.

La liste **Modèles autorisés** limite seulement les identifiants concernés. [Modèles](https://docs.tale.dev/fr/platform/admin/governance/content-models) définit les modèles par défaut et les règles d’accès des personnes, équipes et rôles pour tous les fournisseurs. Les deux restrictions s’appliquent : élargir une liste ne contourne pas l’autre.

La section **Harnesses**, sous le tableau, est en lecture seule. Elle présente les modèles et abonnements disponibles pour chaque environnement d’exécution. Modifie les identifiants au-dessus pour changer cette configuration.

## Résoudre un modèle absent ou en échec

- S’il manque un choix par défaut, sélectionne les identifiants actifs prévus et définis-les par défaut.
- Si le catalogue n’a pas pu être chargé, utilise **Actualiser les catalogues** et examine le résultat du fournisseur. Les catalogues distants sont mis en cache ; les catalogues intégrés évoluent avec la plateforme.
- Si un modèle manque, vérifie la liste des modèles autorisés et les règles de l’organisation. Sans catalogue, vérifie les identifiants exacts des modèles.
- Si une requête est refusée, vérifie l’activation des identifiants, les droits du compte fournisseur, l’adresse et le quota fournisseur avant de modifier les règles des modèles.

## Renouveler ou retirer des identifiants

Utilise l’action de remplacement de la ligne pour changer le secret en conservant le nom et les références. **Désactiver** suspend les identifiants sans retirer leur configuration ; **Activer** les remet en service. Vérifie le remplacement avec le modèle prévu.

<Warning>

Supprimer des identifiants retire l’accès aux appelants qui en dépendent. Migre-les d’abord. Si tu supprimes le choix par défaut, désigne son remplacement pour que les appels sans sélection explicite puissent encore fonctionner. Les identifiants que le modèle d’embedding de la recherche de connaissances utilise — ceux choisis sous **Paramètres > Résidence des données > Modèle d’embedding**, ou le dernier identifiant par défaut actif de ce fournisseur — ne peuvent pas être supprimés : la boîte de dialogue nomme la dépendance et Tale refuse la suppression. Choisis d’abord d’autres identifiants pour le modèle d’embedding.

</Warning>

# Exécuter les sandboxes sur tes propres appareils
Source: https://docs.tale.dev/fr/platform/admin/sandbox-devices

Un appareil est une machine que tu connectes à ton organisation pour que ses sandboxes s’y exécutent au lieu du serveur Tale : un poste de travail inutilisé, un serveur de build ou un Mac qui a de la capacité à partager. Les Propriétaires et Admins ajoutent et retirent des appareils dans **Paramètres > Sandboxes**. Les Développeurs voient la liste.

## Vérifier ce dont la machine a besoin

- Linux sur x86_64 ou arm64, ou macOS sur Apple Silicon ou Intel.
- Docker : Docker Engine sous Linux ; Docker Desktop, OrbStack ou Colima sous macOS. Si Docker manque, la CLI Tale propose de l’installer.
- Un accès HTTPS sortant vers ton site Tale. C’est l’appareil qui se connecte à Tale ; rien ne doit joindre la machine depuis l’extérieur, donc cela fonctionne aussi derrière un routeur ou un pare-feu.
- De l’espace disque pour les images de sandbox, plusieurs gigaoctets, et pour les espaces de travail qu’il accueillera.

Par défaut, un appareil exécute une sandbox pour deux processeurs et pour 4 Gio de mémoire que Docker peut utiliser, jusqu’à 16 à la fois, car chaque sandbox d’agent reçoit 2 processeurs et 4 Gio. Tu peux choisir un autre nombre au moment de connecter la machine.

Ce nombre est un plafond. Avant de démarrer une sandbox, l’appareil vérifie aussi la mémoire disponible sur l’hôte et l’espace disque libre pour les espaces de travail. Une place libre ne suffit donc pas toujours à accueillir une sandbox de plus.

<Warning>

Un appareil exécute le travail de ton organisation. Les espaces de travail des agents, les fichiers qu’ils traitent et les identifiants de courte durée qu’une tâche utilise passent par la machine, et toute personne disposant d’un accès administrateur à celle-ci peut les lire. Ne connecte que des machines que tu contrôles et auxquelles tu fais autant confiance qu’au serveur Tale. À l’inverse, le site Tale décide de ce qui s’exécute sur l’appareil, y compris les mises à jour qu’il installe de lui-même : ne connecte une machine qu’à un site Tale auquel tu la confies.

</Warning>

## Ajouter un appareil

<Steps>

<Step title="Copier la commande">

Ouvre **Paramètres > Sandboxes** et choisis **Ajouter un appareil** dans la section **Appareils**. Sous **Installer et connecter**, choisis **Copier la commande**.

La commande ne fonctionne qu’une fois, dans l’heure. Elle contient un jeton à usage unique que la machine échange contre ses propres identifiants.

<Frame caption="Ajouter un appareil : la commande d’installation et de connexion, et la plus courte pour une machine où la CLI est déjà installée. Le jeton affiché est une valeur factice.">

![La boîte de dialogue Ajouter un appareil avec la commande Installer et connecter, qui installe la CLI Tale et lance tale sandbox connect avec l’adresse du déploiement et un jeton à usage unique, le bouton Copier la commande, les prérequis, la mention que la commande ne fonctionne qu’une fois dans l’heure, la commande plus courte pour une machine où la CLI est déjà installée et l’état qui attend la connexion de l’appareil.](https://docs.tale.dev/images/platform/sandbox-add-device.webp)

</Frame>

</Step>

<Step title="L’exécuter sur la machine">

Colle la commande dans un terminal sur la machine et exécute-la. Elle installe la CLI Tale et connecte la machine :

```text
Connecting this machine to https://your-org.tale.dev as "studio-mac"…
Starting the sandbox device (Tale 0.5.60). The first start downloads the sandbox images, which can take a few minutes…
```

Si la CLI Tale est déjà installée sur la machine, exécute la commande plus courte affichée sous **La CLI Tale est déjà installée ? Exécute plutôt ceci**.

</Step>

<Step title="Vérifier qu’il est en ligne">

Dès que la machine joint Tale, la boîte de dialogue affiche **studio-mac est connecté.** et l’appareil apparaît dans la liste **Appareils** avec le statut **En ligne**. Choisis **Terminé**.

</Step>

</Steps>

L’appareil continue de fonctionner après un redémarrage de la machine, tant que Docker démarre avec elle. Quand Tale est mis à jour, l’appareil passe tout seul à la même version.

## Comprendre où s’exécutent les sandboxes

Les nouveaux espaces de travail des agents et des automatisations démarrent sur un appareil connecté qui a de la place. S’il n’y en a aucun, ils démarrent sur le serveur Tale. Un espace de travail reste, avec ses fichiers, sur la machine où il a démarré : un agent qui a déjà un espace de travail sur le serveur continue donc de l’utiliser. Les pages rendues pour l’exploration des sites web restent toujours sur le serveur.

Quand plusieurs appareils ont de la place, Tale tient compte à la fois des places libres et de la marge de mémoire mesurée. Si un appareil refuse un démarrage faute de capacité, un autre appareil ou le serveur peut le prendre en charge. Si la réponse est perdue ou si l’appareil renvoie une erreur serveur, les nouvelles tentatives restent sur cet appareil : il a peut-être déjà créé l’espace de travail.

Dès que ton organisation a un appareil, la liste **Espaces de travail** indique où s’exécute chaque espace de travail : **Sur le serveur** ou sur un appareil désigné par son nom. Tant qu’un appareil est hors ligne, le travail qui a besoin d’un de ses espaces de travail échoue avec un message indiquant que l’appareil n’est pas connecté. Relance-le quand l’appareil est de nouveau en ligne ; un espace de travail ne passe jamais tout seul sur une autre machine.

Les sandboxes d’un appareil accèdent à Internet par la connexion de la machine, via le même proxy de sortie que sur le serveur. Le proxy bloque les adresses des réseaux privés, si bien que les sandboxes ne peuvent pas joindre les autres machines de ton réseau local.

Les appareils connectés relèvent aussi le plafond des [limites d’activité](https://docs.tale.dev/fr/platform/admin/sandboxes#modifier-une-limite-dactivite) de ton organisation : leur total peut utiliser la capacité du déploiement plus les sandboxes de tes appareils.

## Lire la liste des appareils

| Colonne | Ce qu’elle indique |
| --- | --- |
| **Appareil** | Le nom avec lequel la machine s’est connectée, et son système d’exploitation. |
| **Statut** | **En ligne**, **Mise à jour en cours**, **Mise à jour requise**, **Échec de la mise à jour** ou **Hors ligne**. |
| **Sandboxes** | Les sandboxes en cours d’exécution, et combien l’appareil en exécute à la fois. |
| **Machine** | Les processeurs et la mémoire que Docker peut utiliser sur la machine. |
| **Version** | La version de Tale qu’exécute l’appareil. |
| **Dernier contact** | **Maintenant** tant qu’il est connecté, sinon le moment de son dernier contact. |

Un appareil qui n’a pas la même version que le serveur ne prend plus de nouvelles sandboxes tant qu’il n’est pas mis à jour. **Mise à jour requise** signifie que l’appareil ne se met pas à jour tout seul ; **Échec de la mise à jour** signifie que sa dernière mise à jour automatique n’a pas abouti. Dans les deux cas, exécute `tale sandbox update` sur la machine.

## Gérer un appareil depuis la machine

Exécute ces commandes sur l’appareil lui-même :

| Commande | Ce qu’elle fait |
| --- | --- |
| `tale sandbox status` | Affiche la connexion, l’organisation, la version et les sandboxes en cours d’exécution. |
| `tale sandbox logs --follow` | Suit le journal de l’appareil. |
| `tale sandbox update` | Passe immédiatement l’appareil à la version du serveur, avec les adresses actuelles du serveur pour ses sandboxes. |
| `tale sandbox disconnect` | Retire l’appareil de son organisation, arrête ses sandboxes et supprime leurs espaces de travail de la machine. Ajoute `--keep-data` pour conserver les espaces de travail. |

## Retirer un appareil

Dans la liste **Appareils**, ouvre le menu de la ligne de l’appareil, choisis **Retirer** et confirme. L’appareil cesse immédiatement d’exécuter des sandboxes pour ton organisation. Ses espaces de travail restent sur la machine mais ne sont plus accessibles depuis Tale ; leurs agents repartent avec de nouveaux espaces de travail à leur prochaine exécution.

Pour nettoyer aussi la machine, exécute `tale sandbox disconnect` sur celle-ci.

## Dépanner un appareil qui ne se connecte pas

- **La commande a expiré ou a déjà été utilisée.** Choisis de nouveau **Ajouter un appareil** pour obtenir une nouvelle commande.
- **L’appareil a démarré mais n’a pas encore joint le serveur.** Exécute `tale sandbox logs --follow` sur la machine et vérifie qu’elle peut ouvrir des connexions HTTPS vers ton site Tale, y compris à travers un éventuel proxy.
- **La connexion échoue avec une erreur de certificat.** La machine doit faire confiance au certificat TLS de ton site Tale. Un déploiement qui utilise un certificat auto-signé ne peut pas accueillir d’appareils.
- **Ajouter un appareil est indisponible, et la section indique que le service de sandbox n’accepte pas d’appareils.** Le déploiement fonctionne sans son hub d’appareils. Sur un déploiement auto-hébergé, l’opérateur l’active comme décrit dans [Appareils de sandbox](https://docs.tale.dev/fr/self-hosted/configuration/environment-reference#sandbox-devices).

# Gérer la capacité des sandboxes
Source: https://docs.tale.dev/fr/platform/admin/sandboxes

Ouvre **Paramètres > Sandboxes** lorsqu’un agent ou une analyse de site ne peut pas obtenir d’environnement d’exécution. La page distingue les limites de travail de ton organisation de l’infrastructure réelle du déploiement. Les Propriétaires et Admins peuvent modifier les limites et décider quand les espaces de travail inutilisés sont supprimés. Les Développeurs lisent les limites et la capacité globale, sans accéder aux détails privés des espaces de travail.

## Identifier la limite concernée

| Activité | Valeur par défaut | Ce qui occupe une place |
| --- | --- | --- |
| Sessions d’agent de projet | 2 | Un espace de travail d’agent en démarrage ou au travail, réutilisé entre ses tâches. |
| Sessions de workflow | 2 | La sandbox d’une exécution. Des exécutions simultanées occupent des places distinctes. |
| Sessions de rendu | 2 | Une sandbox temporaire qui rend les pages pendant l’analyse des sites. |

Ces valeurs limitent le travail simultané, pas le nombre de tâches ni les dépenses. Un agent peut travailler sur plusieurs tâches dans son unique espace. Les limites ne réservent pas d’infrastructure : toutes les organisations partagent la capacité du déploiement.

<Frame caption="Le total des trois limites de travail se recalcule automatiquement. Il ne doit pas dépasser la capacité du déploiement.">

![La section des limites de l’organisation affiche trois limites de sessions modifiables et leur total calculé par rapport à la capacité du déploiement.](https://docs.tale.dev/images/platform/settings-sandboxes.webp)

</Frame>

## Modifier une limite d’activité

1. Vérifie les places allouées à l’activité et les mesures d’infrastructure en dessous.
2. Saisis un entier de 1 à 500 pour la limite concernée. Le total affiché recalcule la somme des trois champs.
3. Maintiens cette somme dans la capacité du déploiement, puis choisis **Enregistrer** dans l’en-tête. **Abandonner** rétablit les valeurs enregistrées.
4. Rouvre la page pour vérifier les limites enregistrées, puis observe si de nouvelles tâches obtiennent une allocation.

Les valeurs initiales totalisent 6. Avec une capacité de déploiement de 8, un total de 8 est accepté et 9 est refusé. Le serveur vérifie à nouveau la capacité à l’enregistrement ; sa valeur peut donc différer de la première observation. Les [appareils](https://docs.tale.dev/fr/platform/admin/sandbox-devices) connectés de ton organisation ajoutent au plafond les sandboxes qu’ils exécutent : avec un appareil qui en exécute 4, le total peut atteindre 12.

Une baisse concerne les prochains démarrages et n’interrompt pas le travail en cours. Si les mesures d’infrastructure manquent, les réductions restent possibles, mais une augmentation demande une nouvelle observation de capacité. Si l’opérateur a abaissé la capacité sous ton total actuel, réduis les limites avant d’enregistrer à nouveau. Lorsque les allocations de l’organisation elles-mêmes ne peuvent pas être chargées, les champs restent indisponibles au lieu de présenter des valeurs par défaut modifiables.

## Lire les mesures d’infrastructure

<Frame caption="Sandboxes du déploiement indique le nombre actuel et la capacité partagée. Sandboxes de ton organisation compte aussi les environnements inactifs conservés pour être réutilisés.">

![La section de capacité affiche le nombre de sandboxes de toutes les organisations par rapport à la capacité totale, le nombre propre à l’organisation et les mesures du CPU et de la mémoire de l’hôte.](https://docs.tale.dev/images/platform/sandbox-infrastructure-capacity.webp)

</Frame>

| Mesure | Signification |
| --- | --- |
| Sandboxes du déploiement | Environnements actifs ou au démarrage de toutes les organisations, rapportés à la capacité partagée. Kubernetes mesure le namespace. |
| Sandboxes de ton organisation | Environnements actifs ou au démarrage de ton organisation, y compris les environnements inactifs conservés pour réutilisation. C’est un nombre, pas une seconde limite. |
| Utilisation du CPU de l’hôte | Cœurs récemment utilisés et total des cœurs, autres services de l’hôte compris. |
| Mémoire de l’hôte utilisée | Mémoire utilisée et totale, autres services compris et cache récupérable pris en compte. |

Les mesures s’actualisent toutes les 15 secondes. **Actualiser** demande une nouvelle observation ; vérifie sa date avant de l’interpréter. L’utilisation du CPU est la différence entre deux relevés ; la première observation après une longue interruption prend environ une seconde de plus. Un hôte distant peut fournir les totaux sans l’utilisation. L’accès au namespace Kubernetes ne fournit pas les mesures de l’hôte. **Indisponible** signifie inconnu, pas zéro.

## Distinguer allocation et environnement inactif

Les Propriétaires et Admins peuvent examiner les espaces de travail. Chaque ligne identifie l’agent ou l’exécution, l’état de l’environnement, celui de l’allocation et les tâches en cours. Ces états répondent à des questions différentes : un conteneur peut rester actif pour être réutilisé après avoir libéré sa place dans l’organisation. L’espace de travail d’un agent de projet reste affiché tant que l’agent est inactif, avec l’état **Arrêtée** et **Quota libéré**, jusqu’à ce que tu le supprimes ou que Tale le supprime : quand personne ne l’a utilisé pendant [le nombre de jours fixé par ton organisation](https://docs.tale.dev/fr/platform/admin/sandboxes#delete-unused-workspaces-automatically), ou quand [son agent, son projet ou le membre concerné est retiré](https://docs.tale.dev/fr/platform/admin/sandboxes#explain-why-a-workspace-disappeared). Si l’agent lui-même a été supprimé, la ligne indique **Agent supprimé** jusqu’à ce que Tale ait supprimé l’espace. L’espace d’une exécution de workflow est récupéré peu après la fin de l’exécution.

Les dépenses additionnent le coût mesuré des échanges terminés. Un échange en cours est ajouté lorsqu’il se termine. Les environnements temporaires du crawler comptent dans la capacité même sans ligne d’espace de travail permanent.

Si le déploiement est plein, Tale peut récupérer un environnement inactif non épinglé, dont l’allocation est libérée et qui confirme n’avoir aucun travail en cours. Ses fichiers persistants restent disponibles au prochain démarrage. Les environnements occupés, épinglés ou sans réponse sont exclus. Sans candidat approprié, le nouveau travail doit attendre de la capacité. Un environnement dont la tâche ou l’exécution est terminée s’arrête après quelques minutes d’inactivité, si bien que sa place se libère peu après la fin du travail. Un environnement d’agent qui fait tourner Docker garde tout son délai d’inactivité, pour que le tour suivant n’ait pas à retélécharger ses images.

## Gérer un espace de travail existant

Les Propriétaires et Admins disposent du menu de chaque ligne :

| Action | Effet |
| --- | --- |
| **Arrêter la tâche** | Annule toutes les opérations en cours dans cet espace. Vérifie les tâches affichées : un agent peut en traiter plusieurs. |
| **Épingler** / **Détacher** | Exempte l’espace du nettoyage automatique pour inactivité ou expiration et de la suppression pour cause d’inutilisation, ou rétablit ce nettoyage. Une allocation épinglée peut continuer à occuper de la capacité. Si l’environnement d’un espace épinglé disparaît, par exemple après un redémarrage de l’hôte, Tale le relance avec ses fichiers, et l’espace reste épinglé. |
| **Supprimer** | Demande confirmation, puis retire la sandbox avec ses fichiers en arrière-plan : l’espace est d’abord détaché et le travail en cours annulé. Tant que l’espace n’a pas disparu, sa ligne indique **Suppression…** et tu peux continuer à utiliser la page. Si Tale ne parvient toujours pas à le retirer après plusieurs tentatives, il reste dans la liste, détaché, et indique **Non supprimée** ; choisis alors de nouveau **Supprimer** pour le retirer complètement. Tant que la ligne indique **Suppression…**, rien de nouveau ne démarre dans cet espace : l’exécution d’un agent attend et indique **En attente d’une place de sandbox**, et une étape d’exécution de workflow qui a besoin de l’espace échoue aussitôt en indiquant la raison, sans attendre ni réessayer, car les fichiers laissés par ses étapes précédentes sont en cours de suppression. Une fois la ligne disparue, le démarrage suivant crée un environnement neuf ; si elle indique **Non supprimée** à la place, le travail en attente reprend dans les anciens fichiers. |

Tale enregistre durablement les changements d’épinglage et réessaie de les transmettre si le runtime ne les confirme pas, même après un redémarrage du worker ou une panne de l’appareil. Chaque tentative applique la dernière valeur souhaitée à la même instance de session. Répéter le détachement ne repousse pas son expiration.

Arrête la tâche si le travail doit cesser mais que ses fichiers doivent rester. Avant une suppression, conserve les résultats nécessaires et lis la confirmation. La récupération automatique de capacité inactive préserve les fichiers ; la suppression explicite ou automatique les retire.

## Supprimer automatiquement les espaces de travail inutilisés {#delete-unused-workspaces-automatically}

Un agent de projet garde ses fichiers d’une exécution à l’autre dans des espaces de travail : celui qu’il réutilise pour toutes ses tâches, et un espace distinct pour chaque Membre qui [démarre ses exécutions](https://docs.tale.dev/fr/platform/projects/tasks#executions-demarrees-par-un-membre). Tale supprime un espace de travail que personne n’a utilisé pendant le nombre de jours fixé par ton organisation ; **Supprimer** retire toujours un espace immédiatement. Les Propriétaires et Admins définissent cette règle dans **Nettoyage des espaces de travail**, juste au-dessus de la liste **Espaces de travail**. Les Développeurs ne voient pas cette section.

<Frame caption="Quand Supprimer les espaces de travail inutilisés est activé, Tale supprime un espace de travail que personne n’a utilisé pendant le nombre de jours fixé. Les espaces épinglés sont conservés.">

![La section Nettoyage des espaces de travail montre l’interrupteur Supprimer les espaces de travail inutilisés activé et la valeur 30 dans Jours sans utilisation, chacun accompagné de l’explication de son effet.](https://docs.tale.dev/images/platform/sandbox-workspace-cleanup.webp)

</Frame>

1. Laisse **Supprimer les espaces de travail inutilisés** activé, comme par défaut. Tant que ce réglage est désactivé, Tale ne supprime aucun espace de travail pour cause d’inutilisation.
2. Dans **Jours sans utilisation**, saisis un entier de 1 à 3650 ; la valeur par défaut est 30. Les jours se comptent à partir de la dernière fois que l’agent a travaillé dans l’espace de travail, ou de son détachement.
3. Choisis **Enregistrer** dans l’en-tête. **Abandonner** rétablit les valeurs enregistrées.

Une modification ne fait jamais disparaître un espace de travail avant l’heure. Quand tu actives la suppression ou raccourcis la période, aucun espace de travail n’est supprimé pour cause d’inutilisation avant que ce nombre de jours ne se soit entièrement écoulé depuis la modification. La même attente suit la mise à jour qui a introduit ce réglage. Allonger la période ne relance pas cette attente ; désactiver puis réactiver la suppression la relance.

Dans la liste **Espaces de travail**, un espace d’agent arrêté affiche sous son état le jour de sa suppression : **Suppression prévue le …, sauf nouvelle utilisation**. Une nouvelle exécution dans l’espace relance le décompte. Un espace épinglé, ou protégé par une [conservation juridique](https://docs.tale.dev/fr/platform/admin/governance/legal-hold), n’affiche aucune date et n’est jamais supprimé pour cause d’inutilisation.

## Comprendre pourquoi un espace de travail a disparu {#explain-why-a-workspace-disappeared}

En plus des espaces inutilisés, Tale supprime un espace de travail dès que ce à quoi il appartient est retiré, quel que soit le réglage de nettoyage :

- La suppression d’un agent de projet efface tous ses espaces de travail, y compris ceux des Membres. La suppression d’un projet fait de même pour chacun de ses agents.
- [Retirer un membre](https://docs.tale.dev/fr/platform/admin/members-and-roles#retirer-ou-retablir-lacces) de l’organisation supprime ses propres espaces de travail avec tous les agents. Si tu le passes plutôt en **Désactivé**, ils sont conservés.
- [Effacer les données d’une personne](https://docs.tale.dev/fr/platform/admin/governance/data-subject-requests) supprime ses propres espaces de travail sans attendre la fin du travail qui s’y exécute.
- La suppression de l’organisation efface toutes ses sandboxes et leurs fichiers, révoque les clés de passerelle qui leur ont été remises, déconnecte ses [appareils](https://docs.tale.dev/fr/platform/admin/sandbox-devices) et retire les caches de compilation et de paquets conservés pour elle.

Cela se produit en une minute environ ou, si une tâche s’exécute encore dans l’espace, après la fin de celle-ci. Un espace épinglé est supprimé lui aussi, mais une [conservation juridique](https://docs.tale.dev/fr/platform/admin/governance/legal-hold) garde tous les espaces de travail qu’elle couvre : celle de l’organisation les garde tous, celle qui vise une personne garde les espaces de travail propres à cette personne. Un nettoyage exécuté toutes les heures supprime aussi les restes que plus rien ne possède, comme l’espace d’une exécution de workflow jamais récupéré.

Chaque espace de travail que Tale supprime de lui-même, pour l’une de ces raisons ou pour cause d’inutilisation, apparaît dans le [journal d’audit](https://docs.tale.dev/fr/platform/admin/governance/audit-logs), sous **Paramètres > Gouvernance > Journaux**, avec l’action **Espace de travail de sandbox supprimé**. C’est un événement système de la catégorie **Données**, dont les métadonnées indiquent la raison : `agent_deleted`, `member_removed`, `member_erased`, `unused` ou `orphaned`. L’événement est enregistré une fois que Tale a confirmé la suppression des fichiers de l’espace, ce qui peut prendre un moment pour un grand espace. Sous Kubernetes, il est enregistré une fois le volume de l’espace remis au provisionneur de stockage du cluster, qui le supprime selon la `reclaimPolicy` de sa StorageClass ; les métadonnées indiquent ce qui s’est produit (`deletion` : `done` ou `handed_off`). Si la suppression des fichiers échoue, l’événement apparaît avec le statut **Échec**, et la suppression est retentée jusqu’à ce que les fichiers aient disparu. Un service de sandbox ou un appareil qui n’est pas encore passé à cette version ne peut confirmer aucune suppression : Tale n’enregistre aucun événement pour ses espaces et continue d’essayer jusqu’à sa mise à jour. Un reste que plus rien ne possède peut se terminer sans événement : si ses fichiers sont encore en cours de suppression quand le nettoyage horaire passe à la suite, le service de sandbox termine de les supprimer, mais Tale ne les vérifie plus.

## Résoudre un démarrage bloqué

Un démarrage qui ne trouve pas de place attend. Quand les limites de ton organisation sont occupées, ou que le déploiement est plein ou manque de mémoire, le travail démarre de lui-même dès qu’une place se libère, sans rien te demander. L’espace disque fait exception : arrêter un travail inactif n’en libère pas, car un espace de travail arrêté garde ses fichiers. Tale supprime les caches de build qu’aucune session n’utilise, s’il y en a ; si cela ne suffit pas, le démarrage attend que des espaces de travail soient supprimés, par exemple ceux que tu supprimes parce que tu n’en as plus besoin, ou que l’opérateur libère de l’espace disque. Quand le déploiement lui-même est plein, sa place va au travail qui attend depuis le plus longtemps, quelle que soit son organisation, et chaque démarrage en attente sait quand vient son tour :

- Une exécution de tâche attend dans la file. Elle est relancée dès qu’une session se termine, dans ton organisation ou dans une autre du même déploiement. Quand le déploiement est plein, elle est aussi relancée quand vient son tour. Toutes les deux minutes, Tale relance aussi quelques exécutions en attente de chaque organisation, en commençant par celles qui attendent depuis le plus longtemps.
- L’étape d’agent d’une automatisation réessaie sans consommer ses nouvelles tentatives : quand vient son tour si le déploiement est plein, sinon après une pause qui s’allonge tant que l’étape attend, jusqu’à environ deux minutes. L’exécution affiche entre-temps **En attente d’une place de sandbox**. Après deux heures sans place, l’exécution échoue avec cette raison. Un espace de travail qu’un administrateur supprime n’est pas un manque de place : l’étape échoue alors aussitôt, comme décrit plus haut pour **Supprimer**.
- L’exploration attend son tour, puis reprend avec son lot suivant.

Augmente une limite uniquement lorsque ses allocations sont occupées et que le nouveau total tient dans la capacité partagée. Si le déploiement est plein, augmenter la limite de l’organisation ne crée pas d’infrastructure. Pour ajouter ta propre capacité, [connecte un appareil](https://docs.tale.dev/fr/platform/admin/sandbox-devices) : les nouveaux espaces de travail y démarrent. Sinon, demande à l’opérateur d’examiner la capacité et les ressources de l’hôte. Une place libre ne garantit pas assez de CPU, de mémoire ou d’espace disque.

Pour un refus d’identifiants ou de modèle, consulte [Fournisseurs IA](https://docs.tale.dev/fr/platform/admin/providers). Pour un refus de dépense, consulte [Politiques et limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits). Les opérateurs auto-hébergés trouveront le réglage du déploiement dans la [référence d’environnement](https://docs.tale.dev/fr/self-hosted/configuration/environment-reference#sandbox-infrastructure).

# Équipes
Source: https://docs.tale.dev/fr/platform/admin/teams

Une équipe est une étiquette posée sur le travail, pas un espace dans lequel on bascule. Un document, un dossier ou un projet porte les équipes qui peuvent le voir, et une conversation peut attendre dans la file d’une équipe. Le rôle détermine ce qu’une personne peut faire ; ses équipes déterminent quel travail restreint elle peut atteindre. Les propriétaires et les admins gèrent les équipes dans **Paramètres > Équipes**.

<Frame caption="Paramètres > Équipes — chaque équipe de l’organisation avec son nombre de membres, à côté de l’action Créer une équipe.">

![La page de paramètres Équipes listant trois équipes — Customer success, Growth et Platform engineering — chacune avec un membre et la date de son ajout, à côté d’un bouton Créer une équipe.](https://docs.tale.dev/images/platform/settings-teams.webp)

</Frame>

## Créer une équipe

1. Sélectionne **Créer une équipe** et renseigne le champ **Nom de l'équipe**, par exemple `Support client`.
2. Sélectionne les membres de l’organisation à ajouter. Si tu ne sélectionnes personne, Tale t’ajoute à l’équipe.
3. Sélectionne **Créer une équipe**. Vérifie la nouvelle ligne et le nombre de membres dans la liste.

Choisis un nom reconnaissable partout où les équipes apparaissent : dans l’audience d’un document ou d’un projet, comme file dans la boîte de réception, dans un filtre de liste. Le formulaire accepte jusqu’à 80 caractères. Un nom est unique au sein de l’organisation : un nom déjà utilisé par une autre équipe – quelle que soit la casse ou l’espacement – est refusé. Créer une équipe ne lui rattache pas le travail existant : sélectionne-la sur les documents, projets et conversations qu’elle doit couvrir.

## Modifier le nom ou les membres

Ouvre la ligne d’une équipe pour consulter ses membres. Son menu propose **Voir**, **Modifier** et **Supprimer**. Utilise **Modifier** pour changer le nom ou les membres, puis enregistre et vérifie le nombre de membres.

Une équipe conserve au moins un membre. Pour retirer le dernier, supprime plutôt l’équipe.

Une personne peut appartenir à plusieurs équipes. Elle peut conserver un accès grâce à une autre équipe ou à une attribution directe. La retirer d’une équipe ne supprime donc pas forcément tous ses accès à une ressource. Vérifie les autres voies d’accès lorsque tu retires des droits.

Les notifications suivent la même règle. Une personne qui ne peut plus ouvrir un projet ne reçoit plus de nouvelles notifications ni d’e-mails sur les tâches de ce projet, pas même sur celles qu’elle suit. Ce qu’elle a déjà reçu reste dans ses notifications. Si elle retrouve l’accès, elle est de nouveau notifiée des tâches qu’elle suit.

Une équipe provisionnée par ton fournisseur d’identité porte la mention **Synchronisée** dans la liste. Son nom et ses membres appartiennent au fournisseur : le dialogue de modification les affiche en lecture seule, car la prochaine synchronisation annulerait une modification locale. Tu peux tout de même supprimer une telle équipe localement ; le fournisseur peut la recréer.

<Tip>

Renomme une équipe existante si son objectif change mais que les mêmes personnes doivent garder leurs accès. La supprimer puis la recréer produit une autre équipe et modifie les attributions des ressources existantes.

</Tip>

## Ce qu’une équipe détermine

Toute ressource liée à des équipes suit la même règle. Une ressource sans équipe est visible par toute l’organisation. Une ressource avec des équipes est visible par les membres de l’une d’elles. Les propriétaires et les admins voient tout dans les deux cas : une équipe ne sert donc jamais à masquer du travail aux administrateurs.

| Ressource | Rôle de l’équipe |
| --- | --- |
| Projets | **Audience**, dans **Général**, liste les équipes qui peuvent ouvrir le projet ; vide signifie toute l’organisation. |
| Documents et dossiers | Un document ou un dossier porte les équipes qui peuvent le lire. Ce qui est rangé dans un dossier d’équipe reprend ses équipes et ne peut pas en nommer une autre. |
| Skills | La visibilité par équipe rend un skill disponible aux équipes choisies. |
| Conversations | L’attribution à une équipe place la conversation dans sa file. |

Lorsque tu restreins un travail à des équipes, tu ne peux choisir que celles dont tu fais partie ; les propriétaires et les admins choisissent n’importe quelle équipe de l’organisation. Appartenir à une équipe n’autorise pas une action interdite par le rôle : un Éditeur et un Membre de la même équipe peuvent avoir des droits de modification différents.

Chaque membre voit ses équipes dans **Paramètres > Compte > Tes équipes** et dans la ligne **Équipes** du menu de profil. Pour restreindre une liste à certains travaux, chaque liste propose un filtre **Équipes** avec **Toute l'organisation**, **Mes équipes** et chaque équipe par son nom ; la boîte de réception utilise plutôt un filtre **Responsable**, qui couvre les personnes comme les équipes. Consulte [Gérer ton compte](https://docs.tale.dev/fr/platform/member/preferences#teams).

Pour les conversations entrantes, [les règles de routage](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits#routage-des-conversations) peuvent choisir l’équipe dès l’arrivée. Sans attribution à une personne ou à une équipe, la conversation reste dans le triage des administrateurs.

## Retirer une équipe sans perdre de vue les accès

Sélectionne **Supprimer** dans le menu de la ligne. La confirmation compte les membres de l’équipe, les projets, dossiers et documents dont elle fait partie de l’audience, et les conversations dans sa file. Elle indique aussi combien de ces éléments n’ont pas d’autre équipe et deviendront visibles pour toute l’organisation. Réattribue d’abord le travail dont l’accès doit rester limité.

<Warning>

La suppression d’une équipe est irréversible. Chaque projet, dossier et document perd l’équipe et conserve ses autres équipes. Un élément dont c’était la seule équipe devient visible pour toute l’organisation, ce qui peut élargir son accès.

</Warning>

L’équipe, ses membres, sa présence sur chaque ressource et tout lien avec le fournisseur d’identité disparaissent en une seule opération ; aucune équipe à moitié supprimée ne peut subsister. Une conversation perd son attribution à l’équipe ; si personne ne lui est attribué non plus, elle revient au triage des administrateurs. Les configurations d’import perdent aussi cette association. Les comptes des membres ne sont pas supprimés.

Les équipes synchronisées par [SSO d’entreprise ou SCIM](https://docs.tale.dev/fr/platform/admin/enterprise-sso) dépendent aussi des règles du fournisseur d’identité. Vérifie cette source avant de faire une modification locale que tu souhaites conserver.

# Authentification à double facteur
Source: https://docs.tale.dev/fr/platform/admin/two-factor-authentication

Protège ton compte avec une application d’authentification ou un passkey. Chaque membre configure ses méthodes de connexion dans **Paramètres > Compte**. Les admins peuvent exiger un second facteur et aider un membre à récupérer son accès.

## Choisir une méthode de connexion

| Méthode | Ce qu’il te faut | Comment l’utiliser |
| --- | --- | --- |
| Application d’authentification | Un mot de passe Tale et une application compatible avec les codes temporels (TOTP) | Saisis ton mot de passe, puis le code à six chiffres de l’application. |
| Passkey | Un appareil compatible ou une clé de sécurité | Valide la demande du navigateur avec ton appareil ou ta clé. Tu peux aussi l’utiliser après une connexion par mot de passe. |
| Code de secours | Un code conservé lors de la configuration de l’application | Utilise-le une fois à la place d’un code d’authentification si tu n’as plus accès à l’application. |

Un passkey satisfait la règle de double facteur de Tale, même sans application d’authentification configurée. Les comptes qui utilisent uniquement le SSO ne voient pas la configuration de cette application, car elle exige un mot de passe Tale. L’exemption SSO de ton organisation détermine si tu as besoin d’un passkey Tale.

<Frame caption="Paramètres > Compte affiche ton mot de passe, l’authentification à double facteur et tes passkeys. C’est ici que tu configures ton application d’authentification ou que tu enregistres un autre passkey.">

![La page des paramètres du compte avec les sections Mot de passe, Authentification à double facteur et Passkeys ; la section Passkeys liste un passkey nommé « Work laptop ».](https://docs.tale.dev/images/platform/settings-account-security.webp)

</Frame>

## Configurer une application d’authentification

1. Ouvre **Paramètres > Compte**, repère **Authentification à double facteur** et choisis **Activer le double facteur**.
2. Saisis ton mot de passe Tale actuel et choisis **Confirmer**. Un mot de passe erroné compte pour le verrouillage temporaire, comme un échec de connexion.
3. Scanne le code QR avec ton application d’authentification. Si tu ne peux pas le scanner, saisis manuellement le secret de configuration affiché dans l’application.
4. Saisis son code à six chiffres actuel dans **Code de vérification**, puis choisis **Vérifier et activer**.
5. Télécharge ou copie les codes de secours avant de choisir **Terminé**. Tale ne les affichera plus.

La page du compte confirme maintenant que le double facteur est actif. À ta prochaine connexion par mot de passe, utilise un code provenant de la même entrée dans ton application.

<Tip>
Conserve tes codes de secours dans un endroit accessible sans ton appareil de connexion, par exemple un gestionnaire de mots de passe disponible sur un autre appareil de confiance.
</Tip>

## Ajouter un passkey

1. Ouvre **Paramètres > Compte**, repère **Passkeys** et choisis **Ajouter un passkey**.
2. Si ta connexion remonte à plus d’un jour, Tale te demande d’abord ton mot de passe. Saisis-le dans **Mot de passe** et choisis **Confirmer**. Un mot de passe erroné compte pour le verrouillage temporaire, comme un échec de connexion.
3. Dans **Nom du passkey**, indique un nom reconnaissable, par exemple `Portable professionnel`.
4. Garde **Type d'authentificateur** sur **Indifférent (recommandé)** pour voir les possibilités du navigateur, ou choisis l’authentificateur intégré à l’appareil ou une clé de sécurité/un téléphone.
5. Choisis **Ajouter un passkey** et termine la procédure du navigateur.

Le passkey apparaît dans la liste de ton compte. Sur la page de connexion, choisis **Se connecter avec un passkey**. Après une connexion par mot de passe, tu peux aussi choisir **Utiliser un passkey à la place** sur l’écran de vérification.

Pour ne plus utiliser un passkey, choisis son bouton **Supprimer** et confirme. S’il s’agissait de ton seul second facteur et que ton organisation en exige un, tu dois en configurer un autre.

## Récupérer ton accès et remplacer les codes

Sur l’écran de vérification, choisis **Utiliser un code de secours à la place** et saisis un code conservé. Chaque code fonctionne une fois. Après la connexion, ouvre **Paramètres > Compte** et choisis **Régénérer les codes de secours** si tu as besoin d’un nouveau lot. Confirme ton mot de passe et conserve les nouveaux codes. Cette opération invalide tous les anciens codes, même ceux que tu n’as pas utilisés.

Si un code est refusé, vérifie que tu utilises l’entrée de ce compte Tale, saisis le code actuel et contrôle l’horloge de ton appareil. Des échecs répétés peuvent bloquer temporairement la vérification. Suis alors le message affiché au lieu de multiplier les tentatives.

Si tu n’as plus d’application, de passkey ni de code de secours utilisable, contacte un admin de ton organisation. Ne lui envoie ni ton mot de passe, ni ton secret de configuration, ni tes codes restants.

## Exiger un second facteur pour l’organisation

Les admins configurent la règle dans **Paramètres > Gouvernance > Sécurité**. Prévois un contact en cas de perte d’accès et laisse aux membres le temps de configurer une méthode avant de l’activer.

<Frame caption="Les paramètres de sécurité regroupent les règles de mot de passe, de connexion et de double facteur. Descends jusqu'à Authentification à double facteur pour régler l'obligation de configuration.">

![Paramètres de sécurité présentant les limites de connexion et les exigences de mot de passe au-dessus de la règle de double facteur.](https://docs.tale.dev/images/platform/governance-security-monitoring.webp)

</Frame>

| Réglage | Effet |
| --- | --- |
| **Exiger l'authentification à double facteur** | Active l’obligation après confirmation. Un passkey ou une application d’authentification enregistrés y répondent. |
| **Période de grâce (jours)** | Délai de configuration à partir de la première connexion du membre sous cette règle. Zéro impose une configuration immédiate. |
| **Exempter les utilisateurs SSO uniquement** | Les membres sans mot de passe Tale s’appuient sur l’authentification de leur fournisseur d’identité. |

Pendant ce délai, les membres voient un rappel. Une fois le délai écoulé, Tale bloque l’accès à l’organisation jusqu’à la configuration : la page de configuration demande leur mot de passe pour configurer une application d’authentification, ou propose **Enregistrer un passkey à la place**. Un membre connecté depuis plus d’un jour confirme son mot de passe avant la demande du navigateur ; un membre qui se connecte uniquement par SSO choisit d’abord **Se reconnecter**. Désactiver ton application d’authentification personnelle ne te dispense pas de cette règle.

## Aider un membre qui a perdu son accès

Vérifie d’abord l’identité de la personne selon la procédure de récupération de ton organisation. Ouvre ensuite **Paramètres > Membres**, modifie le membre et choisis **Réinitialiser le double facteur**. La confirmation efface la configuration de son application et met fin à toutes ses sessions actives. La personne peut se reconnecter et configurer une nouvelle application. Si le double facteur est obligatoire, elle doit terminer cette configuration avant de continuer.

Pour un passkey perdu, supprime plutôt cet identifiant dans la section **Passkeys** de la fenêtre du membre. Cette suppression par un admin ferme aussi toutes les sessions du membre. Consulte les actions de récupération dans les [journaux d’audit](https://docs.tale.dev/fr/platform/admin/governance/audit-logs).

# Comprendre les agents de projet
Source: https://docs.tale.dev/fr/platform/agents/concepts

Un agent de projet travaille sur les tâches d’un projet précis. Tu définis son mode d’exécution et ses accès, puis tu lui confies une tâche dont le résultat peut être vérifié. Il peut modifier des fichiers et lancer des commandes dans une sandbox. Le [relecteur configuré](https://docs.tale.dev/fr/platform/projects/tasks#review-default), une personne ou un agent de projet indépendant, examine le résultat avant de terminer la tâche. Les nouvelles relectures qui exigent une indépendance humaine ou des justificatifs de compétences suivent la chaîne humaine ; une relecture déjà attribuée à un agent doit être explicitement transférée à une personne autorisée.

## Choisir la forme de travail

| Forme | Travail adapté | Ce que tu définis |
| --- | --- | --- |
| Chat | Poser une question, rechercher des connaissances ou rédiger un texte. | Le message, le modèle et, si nécessaire, le contexte du projet. |
| Agent de projet | Examiner un dépôt, préparer des fichiers ou poursuivre une tâche sur plusieurs échanges. | Un agent réutilisable dans le projet. |
| Automatisation | Exécuter des étapes définies, réagir à un événement ou demander une approbation entre deux actions. | Un workflow versionné et ses données d’entrée. |

Un chat de projet utilise toujours l’assistant de chat intégré. Choisir un projet dans Chat ne sélectionne pas un agent du projet. Le nœud agent d’une automatisation possède sa propre configuration.

## Définir une responsabilité précise

Commence par une responsabilité dont tu peux évaluer le résultat, par exemple : « Examine les modifications, recherche les régressions et appuie tes constats sur des preuves. » Place-la dans les instructions permanentes. Le dépôt concerné, les fichiers, les critères d’acceptation et l’échéance appartiennent à chaque tâche.

Un agent appartient à un seul projet. Les personnes qui peuvent lire le projet voient ses agents ; celles qui peuvent le modifier les gèrent tant qu’il est actif. Les noms doivent être uniques dans le projet, qui peut contenir jusqu’à 50 agents. Un autre projet demande une configuration distincte, même si le nom et les instructions sont identiques. Un projet sans agents propres n’en est pas pour autant dépourvu : sauf si un admin l’a désactivé, l’[agent standard](https://docs.tale.dev/fr/platform/projects/project-agents#standard-agent) de l’organisation prend en charge ses tâches, avec des réglages qu’un admin choisit pour toute l’organisation.

## Comprendre la configuration

| Élément | Ce qu’il détermine | Exemple de décision |
| --- | --- | --- |
| Harness | Le programme de code qui exécute la session dans une sandbox. | Choisir un environnement compatible avec les identifiants disponibles. |
| Modèle et fournisseur | Le modèle appelé et le fournisseur qui le sert. | Choisir une combinaison autorisée pour ce travail. |
| Instructions | La responsabilité et les règles réutilisables, jusqu’à 20 000 caractères. | Exiger des preuves et un compte rendu des vérifications. |
| Skills | Des instructions regroupées avec leurs fichiers complémentaires. | Ajouter la liste de vérification de l’équipe. |
| Connectors et outils | Les services connectés et les opérations autorisées dans Tale. | Accorder l’accès au dépôt et les seuls outils de tâches nécessaires. |
| Secrets | Des identifiants de l’organisation, référencés par nom et fournis à la session. | Utiliser un jeton limité pour un service sans connector. |

Les listes de skills, connectors, outils et noms de secrets acceptent chacune jusqu’à 25 entrées. Accorder un outil d’écriture autorise ses opérations dans les limites de ses règles d’accès. Une instruction demandant de la prudence ne retire pas cette permission. Seuls un Propriétaire ou un Admin peuvent modifier les secrets accordés.

```mermaid
flowchart LR
    P[Tâche et critères d’acceptation] --> A[Agent configuré]
    H[Harness et modèle] --> A
    I[Instructions permanentes] --> A
    E[Skills, connectors, outils et secrets] --> A
    A --> R[Compte rendu et fichiers à examiner]
```

## Vérifier les prérequis avant l’affectation

Les identifiants du fournisseur doivent être compatibles avec le harness et le modèle choisis. Une sandbox doit aussi être disponible. Une réponse réussie dans Chat ne prouve aucune de ces conditions. La tâche doit préciser le résultat attendu et fournir les éléments à examiner.

Une fois ces choix établis, [crée un agent de projet](https://docs.tale.dev/fr/platform/projects/project-agents). Le guide d’[automatisation des tâches](https://docs.tale.dev/fr/platform/projects/task-automation) explique comment démarrer, guider et examiner son travail.

# Choisir un environnement d’agent
Source: https://docs.tale.dev/fr/platform/agents/harnesses

Un harness est le programme de code qui exécute la session d’un agent dans une sandbox. Il interroge le modèle, lit et écrit des fichiers, lance des commandes et rend compte du travail. Tu le choisis pour un agent de projet ou un nœud `agent` d’automatisation. Le sélecteur de modèle du chat ordinaire ne choisit pas de harness.

## Choisir l’environnement et vérifier l’accès

Dans l’onglet **Agents** d’un projet, ouvre un agent et choisis son **Harness**. Le nœud agent d’une automatisation utilise le même nom de champ. Choisis ensuite le modèle et le fournisseur. Sous **Paramètres > Fournisseurs IA**, la section **Harnesses** montre les voies d’exécution actuellement disponibles pour l’organisation.

Il faut des identifiants compatibles et de la [capacité de sandbox](https://docs.tale.dev/fr/platform/admin/sandboxes). Un modèle qui fonctionne dans Chat ne suffit pas. Si un environnement manque ou ne propose aucun modèle, examine son état et les identifiants du fournisseur avant de modifier la demande de travail. Un modèle qui n’appelle des tools que via l’API Responses d’OpenAI, comme GPT-6 Astra ou GPT-6.1 Sol, ne fonctionne que sur Codex : le sélecteur de modèle ne le propose donc pour aucun autre environnement.

## Comparer les environnements pris en charge

« Géré » signifie que le programme appelle le modèle via la passerelle de Tale. « Direct » signifie que la session reçoit les identifiants destinés aux outils du fournisseur. Les définitions livrées prennent en charge les combinaisons suivantes ; leur disponibilité dépend du déploiement et des identifiants.

| Harness | Voie d’accès | Nouvelles instructions dans le processus actif | Canal MCP de Tale |
| --- | --- | --- | --- |
| Claude Code | Gérée ou directe | Oui | Oui |
| Codex | Gérée ou directe | Non | Oui |
| Cursor | Directe uniquement | Non | Non |
| Gemini CLI | Gérée ou directe | Non | Oui |
| Hermes | Gérée ou directe | Non | Non |
| OpenClaw | Gérée ou directe | Non | Oui |
| OpenCode | Gérée uniquement | Non | Oui |
| Pi | Gérée ou directe | Non | Non |
| Qwen Code | Gérée ou directe | Non | Oui |

**Claude Code (compact prompt)** est une option pour les workflows ciblés qui fournissent déjà des consignes complètes. Elle raccourcit les instructions intégrées et certaines descriptions d’outils, tout en conservant les outils, les hooks, MCP et les consignes ajoutées par Tale. Vérifie les résultats et la durée avec ton modèle avant de l’adopter : un prompt plus court ne garantit pas une exécution plus rapide. Choisis **Claude Code** pour retrouver le prompt complet à la prochaine nouvelle exécution. Un abonnement fournisseur réservé à Claude Code ne prend pas automatiquement en charge cette variante.

Pour guider le travail, commente la tâche et mentionne son agent. Claude Code reçoit le message entre deux appels d’outils. Pour les autres environnements, Tale arrête le processus et poursuit la même conversation dans un nouveau processus avec ton commentaire. Cela explique un redémarrage du processus après une nouvelle consigne.

Gemini CLI fait exception : Tale ne poursuit jamais une de ses conversations. Un commentaire ultérieur, une nouvelle tentative automatique ou la réponse à une question posée par l’agent démarre une nouvelle conversation dans le même espace de travail, en rappelant la consigne de la tâche et les échanges précédents, parce que l’environnement ne peut pas reprendre une conversation dans laquelle il a appelé un outil. Les fichiers et les résultats sont conservés ; seule la conversation repart de zéro.

## Comprendre les identifiants et les coûts

Avec une clé API stockée ou fournie par l’environnement du déploiement, Tale remet une clé de passerelle limitée à la session. La clé d’origine du fournisseur de modèle reste dans la plateforme. Les appels de passerelle sont mesurés et soumis aux règles de dépense applicables, en tenant compte des montants déjà attribués aux autres échanges en cours.

Les abonnements fournisseurs utilisent leur harness compatible et reçoivent les identifiants d’abonnement dans l’environnement de la session. Ils ne servent pas d’identifiants de chat ordinaire et ne fonctionnent pas avec un harness incompatible, car les fournisseurs n’autorisent les jetons d’abonnement que dans leur propre environnement ; la page [Fournisseurs IA](https://docs.tale.dev/fr/platform/admin/providers#utiliser-les-abonnements-dans-les-taches-pas-dans-le-chat) l’explique. Leurs appels directs échappent à la mesure et aux plafonds de la passerelle Tale. Examine la consommation auprès du fournisseur d’abonnement.

Ces règles sur les identifiants de modèle ne signifient pas que la sandbox ne contient aucun secret. Les **Secrets** explicitement accordés et le jeton d’un accès GitHub équipé peuvent y être disponibles. Limite ces accès aux besoins de la tâche.

## Comprendre les fichiers et les outils connectés

Un agent de projet réutilise son espace de travail persistant entre ses tâches. Les pièces jointes sont accessibles en lecture seule sous `/agent/inputs/<task>/attachments/`. Les fichiers écrits dans `/agent/output/<task>/` sont collectés comme **Fichiers produits** à la fin de l’échange. Un nœud agent collecte sa sortie sous `/agent/output/`.

Les bundles de skills sont préparés sous forme de fichiers et cités dans les instructions de l’exécution. Examine leurs consignes et scripts avant de les accorder. [Skills des agents](https://docs.tale.dev/fr/platform/agents/skills) explique cette préparation et la visibilité.

Chaque programme trouve aussi le skill intégré `visual-aspect-analyzer` parmi ses propres skills, sans que tu aies à l’équiper. Il pilote un vrai navigateur sur une modification d’interface terminée et signale les décalages de mise en page, le scintillement et les autres régressions visuelles. Un skill du même nom dans les dossiers `.claude/skills` et `.agents/skills` du dépôt de l’espace de travail le remplace dans chaque programme qui lit les skills d’un dépôt.

Le broker de connectors garde les identifiants ordinaires dans Tale et renvoie les résultats des actions. Il propose les lectures aux agents et refuse les écritures par cette voie. Utilise un nœud connector d’automatisation pour une écriture soumise aux règles de Tale. Les outils GitHub et les secrets explicitement accordés suivent d’autres voies : la restriction du broker n’interdit donc pas toutes les écritures depuis le shell.

Les agents qui disposent du canal MCP de Tale peuvent aussi consulter la release de Tale que signale la plateforme. En plus des outils de la plateforme accordés à l’agent, `workspace_status` renvoie `platform.version`, le numéro de release que porte le build du backend qui répond : par exemple `0.5.64` pour la release dont le tag est `v0.5.64`. Pour cette valeur, le backend ne lit rien dans la requête. Un build sans numéro de release, comme un build de développement, renvoie à la place `null` avec une courte note. Considère cette valeur comme une indication et non comme une preuve, car n’importe quel build peut porter un numéro de release. Elle ne décrit en outre que ce backend et n’indique pas si le reste du déploiement fonctionne ; la [page de statut](https://docs.tale.dev/fr/develop/status-page) du déploiement rend compte de ses services.

L’accès sortant autorise normalement l’installation de paquets et le clonage de dépôts, tout en bloquant les adresses privées et les services de métadonnées cloud. Les opérateurs peuvent restreindre davantage les hôtes permis. Lorsqu’un service est inaccessible, examine les règles réseau avant de conclure que les identifiants sont incorrects.

Les skills de documents intégrés `docx`, `pptx`, `xlsx` et `pdf` trouvent déjà installées dans la sandbox les bibliothèques qu’ils appellent. Un agent équipé de ces skills crée et lit donc des fichiers Word, PowerPoint, Excel et PDF même là où l’installation de paquets est bloquée. Leurs consignes contiennent toujours des commandes d’installation comme `npm install -g docx` ; si le registre est bloqué, cette étape échoue, mais la bibliothèque préinstallée reste disponible. La reconnaissance de texte (OCR) des PDF numérisés n’est pas incluse.

## Examiner le résultat

Le programme décide quand son échange est terminé ; Tale collecte le compte rendu et la sortie. Lis les deux avant de terminer la tâche. Vérifie quels contrôles ont réellement été exécutés et quels services manquaient dans la sandbox. L’[automatisation des tâches](https://docs.tale.dev/fr/platform/projects/task-automation) explique la revue du travail de projet ; les [journaux d’exécution](https://docs.tale.dev/fr/platform/automations/execution-logs) expliquent le résultat d’un nœud agent.

Si le programme ne peut pas démarrer du tout — une configuration qu’il refuse, un répertoire d’état qu’il ne trouve pas —, l’exécution échoue aussitôt et sa cause cite les dernières lignes écrites par le programme : la cause est nommée, pas seulement un code de sortie. Une telle exécution n’est pas relancée automatiquement ; corrige la cause, puis relance-la.

# Équiper les agents avec des skills
Source: https://docs.tale.dev/fr/platform/agents/skills

Équipe un agent avec un skill lorsqu’il a besoin d’une procédure réutilisable ou de références provenant de la [bibliothèque de skills](https://docs.tale.dev/fr/platform/workspace/skills) de l’organisation. La bibliothèque conserve le bundle ; l’équipement de l’agent détermine les bundles disponibles pendant ses exécutions.

## Choisir un skill adapté à la tâche

Un skill utile explique quand l’utiliser, comment procéder et à quoi ressemble un bon résultat. Par exemple, équipe l’agent chargé des notes de version avec le skill correspondant. Fournis-lui quelques changements, puis vérifie que sa réponse respecte le format attendu.

Le bundle contient `SKILL.md` et peut inclure des références, des ressources ou des scripts. L’import ne lance pas ces fichiers. Une fois le skill équipé, ses instructions peuvent toutefois guider un agent de programmation disposant d’un shell ou d’autres outils, y compris pour exécuter un script du bundle. Vérifie tout le contenu avant utilisation : un skill ne constitue pas une limite de permission supplémentaire.

## Équiper un agent de projet

Ouvre l’[agent de projet](https://docs.tale.dev/fr/platform/projects/project-agents) et sélectionne les skills nécessaires dans son équipement. La liste dépend de l’accès du projet, même si tu peux personnellement lire davantage de skills :

| Accès du projet | Skills disponibles |
| --- | --- |
| Projet ouvert à toute l’organisation | Skills de l’organisation |
| Projet partagé avec des équipes | Skills de l’organisation et skills d’équipe partagés avec au moins une équipe du projet |

Les anciens skills privés ne peuvent pas équiper un agent de projet. La même règle d’accès est vérifiée au démarrage d’une tâche : sélectionner un skill ne donne pas au projet un accès permanent à celui-ci.

Pour un nouvel agent de projet, les skills de documents `docx`, `pptx`, `xlsx` et `pdf` sont cochés s’ils sont accessibles au projet. Décoche ceux dont la tâche n’a pas besoin.

Chaque skill de la liste indique son créateur : un membre, **Fourni avec Tale** pour les skills fournis à la création de ton organisation, ou **Release de configuration** suivi du membre dont le téléversement l’a installé. Vérifie l’origine d’un skill inconnu avant d’en équiper un agent.

## Utiliser des skills dans une automatisation

Les nœuds agent d’une automatisation déclarent les skills dont ils ont besoin. Une exécution liée à un projet utilise l’accès de ce projet. Une exécution au niveau de l’organisation peut seulement utiliser les skills de l’organisation. Ton appartenance personnelle à d’autres équipes n’élargit pas ces accès.

Lors de la préparation de la sandbox, Tale met les bundles équipés à disposition sous forme de fichiers. Pour chaque skill, l’agent reçoit un extrait de la description, limité à 300 caractères, et le chemin de ses instructions `SKILL.md`. Cet extrait l’aide à choisir un skill pour une tâche formulée librement ; c’est une aide au choix, pas une consigne à exécuter. Les fichiers complémentaires se trouvent à côté des instructions.

Pour un skill marqué `disable-model-invocation`, la liste demande à l’agent d’attendre que la tâche le nomme explicitement. Cette consigne ne constitue pas un contrôle d’accès. Limite l’équipement aux besoins de la tâche et précise la procédure quand elle compte. La disponibilité d’un skill ne prouve pas à elle seule que le résultat suit ses instructions.

## Vérifier les skills manquants ou modifiés

Supprimer un skill le déséquipe de chaque agent qui le portait, et le journal d’audit indique lesquels. Si un skill requis n’est plus partagé avec le périmètre de l’exécution, sa mise à disposition échoue en indiquant son nom ; l’exécution n’est pas relancée automatiquement, car une relance n’y change rien. Dans le dialogue de l’agent, le skill apparaît comme indisponible pour que tu puisses le décocher — tous les autres réglages de l’agent s’enregistrent toujours. Rétablis l’accès prévu ou retire l’équipement obsolète avant de réessayer.

Les modifications d’un bundle partagé s’appliquent à ses prochaines mises à disposition. Vérifie les remplacements et teste l’agent avec une entrée connue après un changement important. Ne suppose pas qu’un skill de même nom dans le dépôt remplace le bundle équipé.

## Choisir entre skills et instructions de l’agent

| Utilise un skill lorsque… | Utilise les instructions de l’agent lorsque… |
| --- | --- |
| plusieurs agents partagent la même procédure. | elles définissent le rôle ou le ton de cet agent. |
| la procédure nécessite des fichiers de référence ou des scripts. | il s’agit d’une règle courte et stable pour cet agent. |
| la procédure doit être maintenue à un seul endroit. | elles expliquent comment cet agent doit utiliser ses skills. |

Le [guide de la bibliothèque de skills](https://docs.tale.dev/fr/platform/workspace/skills) explique comment créer, importer, modifier et partager un bundle.

# Comprendre les approbations d’actions
Source: https://docs.tale.dev/fr/platform/approvals/concepts

Une approbation te permet de vérifier une écriture prévue via un Connector avant son exécution. Une automatisation peut, par exemple, préparer un e-mail puis attendre que tu vérifies le destinataire et le contenu avant l’envoi.

## Quand une écriture attend

Une exécution réelle se met en pause lorsqu’elle atteint une écriture via un Connector que la politique de l’organisation soumet à approbation. Par défaut, les écritures vers des systèmes externes demandent une approbation ; celles qui passent par des Connectors internes authentifiés par la plateforme n’en demandent pas. L’organisation peut modifier cette règle pour un Connector ou une action précise. Consulte [Configurer les approbations](https://docs.tale.dev/fr/platform/approvals/configure).

Les lectures ne demandent pas d’approbation. **Essai** utilise des Connectors simulés : il n’effectue pas l’écriture externe et n’affiche pas sa carte d’approbation réelle. Un test réussi ne prouve pas que l’action prévue convient à la situation.

## Vérifier l’action prévue

Ouvre la [liste des exécutions](https://docs.tale.dev/fr/platform/automations/execution-logs) de l’automatisation, puis celle au statut **En attente**. La carte d’approbation nomme l’action, par exemple `imap-smtp.send`, et le nœud qui la demande. **L'étape appellerait avec** montre les entrées exactes.

Compare la destination, les destinataires, le contenu et les identifiants à la tâche prévue. Vérifie aussi les informations sensibles dans les entrées avant de choisir :

- **Approuver** autorise cette action lorsque l’exécution reprend.
- **Rejeter** empêche l’action et fait échouer l’étape ainsi que l’exécution.

La carte ne permet pas de modifier l’action. Si une entrée est incorrecte, rejette la demande, corrige le workflow ou ses entrées, puis lance une nouvelle exécution.

<Note>

Les membres de l’organisation peuvent décider des approbations d’actions de Connector. Ces cartes ne sont pas attribuées à une personne ou à un groupe de validation précis : la décision se prend dans le détail de l’exécution, que seuls les propriétaires, les admins et les développeurs ouvrent. Quand l’exécution traite une tâche, sa carte apparaît aussi dans la tâche, où toute personne qui peut ouvrir la tâche décide. D’autres types de validation peuvent exiger des droits plus stricts.

</Note>

## Vérifier le résultat

L’approbation autorise l’exécution ; elle ne garantit pas que le Connector réussira. Vérifie ensuite le statut, le résultat du nœud et les effets produits. Une exécution rejetée indique le refus comme cause de l’échec. Le [journal d’audit](https://docs.tale.dev/fr/platform/admin/governance/audit-logs) conserve la décision et son auteur.

Une approbation en attente reste ouverte si la politique est assouplie. La même action dans la même exécution conserve sa décision ; une nouvelle exécution est évaluée à nouveau. Une exécution terminée ou annulée ne peut plus utiliser une approbation encore ouverte pour effectuer son écriture.

## Distinguer une approbation d’une question

Un nœud agent peut aussi se mettre en pause parce qu’il lui manque une information. Ta réponse fournit une entrée ; elle n’approuve pas une écriture via un Connector. [Approbations dans les workflows](https://docs.tale.dev/fr/platform/automations/approvals-in-workflows) explique les deux interactions. Les validations de tâches, de documents contrôlés et de demandes d’effacement ont leurs propres [règles de validation](https://docs.tale.dev/fr/platform/approvals/configure).

# Décider quelles actions demandent une approbation
Source: https://docs.tale.dev/fr/platform/approvals/configure

La politique d’approbation détermine quelles écritures de connectors doivent attendre une personne pendant une exécution réelle. Examine les actions externes avant le déploiement, surtout lorsqu’un workflow envoie des messages ou modifie un autre système. [Comprendre les approbations](https://docs.tale.dev/fr/platform/approvals/concepts) explique la carte de décision.

## Comprendre le comportement par défaut

Les lectures ne demandent pas d’approbation d’opération. Par défaut, une écriture vers un système externe attend une décision : envoi d’e-mail, message Slack, création d’issue GitHub ou écriture WebDAV, par exemple. Les opérations internes, comme modifier une tâche ou enregistrer un document dans Tale, ne demandent pas cette approbation par défaut.

Une opération autorisée reste soumise aux droits d’accès applicables. L’absence de carte ne prouve donc pas qu’elle est en lecture seule. Il peut s’agir d’une écriture interne ou explicitement approuvée automatiquement par l’organisation.

## Demander une modification de politique

La page des connectors n’a pas d’interrupteur d’approbation pour chaque action. La politique de l’organisation peut exiger ou supprimer l’approbation pour un connector ou une action précise. La règle d’une action a priorité sur celle de son connector.

Demande au responsable du déploiement d’appliquer la [configuration des approbations](https://docs.tale.dev/fr/self-hosted/configuration/approvals). Précise l’opération, le motif du contrôle ou de l’exécution automatique, et le workflow concerné. Les admins Cloud coordonnent également cette modification avec le responsable de leur déploiement.

Une opération qui attend déjà une approbation conserve sa demande après la modification. Approuve ou refuse explicitement cette carte ; assouplir la politique ne la libère pas.

## Vérifier un workflow avant le déploiement

1. Examine chaque nœud de connector et identifie s’il lit ou écrit.
2. Confirme les écritures que la politique effective approuve automatiquement.
3. Lance un test pour contrôler les entrées et sorties avec des mocks.
4. Pendant une exécution réelle maîtrisée, examine l’opération et ses entrées exactes sur chaque carte en attente avant de décider.

Un test simulé ne prouve pas qu’une approbation apparaîtra en conditions réelles. Les mocks ne modifient pas les systèmes externes et ne demandent pas d’approbation.

## Distinguer les autres décisions humaines

| Décision | Règles correspondantes |
| --- | --- |
| Accepter le résultat d’une tâche d’agent | [Automatiser les tâches](https://docs.tale.dev/fr/platform/projects/task-automation). Une personne passe le résultat de En revue à Terminé. |
| Approuver une version de document maîtrisé | [Documents](https://docs.tale.dev/fr/platform/knowledge/documents). Le relecteur désigné décide sur la version figée. |
| Autoriser une demande d’effacement | [Demandes des personnes concernées](https://docs.tale.dev/fr/platform/admin/governance/data-subject-requests). Un second Admin donne l’approbation requise. |
| Répondre à la question d’un nœud agent | [Approbations dans les workflows](https://docs.tale.dev/fr/platform/automations/approvals-in-workflows). L’exécution a besoin d’une information pour continuer. |

Ces décisions suivent leurs propres règles. La politique d’approbation des connectors ne les désactive pas. Le chat utilise des outils de consultation en lecture seule et ne crée pas de carte d’approbation d’opération.

# Répondre à un workflow en attente
Source: https://docs.tale.dev/fr/platform/automations/approvals-in-workflows

Une exécution peut attendre une décision avant une écriture via un Connector, ou une information dont l’agent a besoin pour continuer. Ouvre son détail pour savoir quelle réponse fournir. Une exécution en attente n’est pas terminée, même si les nœuds précédents ont réussi.

## Retrouver l’exécution en attente

Ouvre l’automatisation et ses [journaux d’exécution](https://docs.tale.dev/fr/platform/automations/execution-logs), puis sélectionne celle au statut **En attente**. Vérifie la version et les entrées pour savoir quelle exécution tu examines.

Une carte d’approbation nomme une action de Connector et montre ses entrées prévues. Une question de l’agent demande plutôt une réponse, sous forme de choix ou de texte. Ce sont deux interactions distinctes : répondre à une question n’approuve pas une écriture ultérieure.

## Approuver ou rejeter une écriture

Lis attentivement l’action et les données sous **L'étape appellerait avec**. Vérifie le destinataire ou la destination, le contenu et les identifiants qui déterminent ce qui sera modifié.

Choisis **Approuver** pour autoriser l’action. L’exécution reprend et tente l’écriture ; vérifie ensuite le résultat du nœud et les effets produits. Choisis **Rejeter** si la demande est incorrecte ou ne doit pas être exécutée. Le refus empêche cette action et fait échouer l’exécution.

Même en cas de problème, la carte t’indique où en est l’exécution. Si l’approbation ne peut pas être chargée, la carte le signale et propose **Réessayer** ; l’exécution reste en attente jusqu’à ce que quelqu’un décide. Si ta décision n’a pas été enregistrée, la carte le signale et garde **Approuver** et **Rejeter** disponibles pour que tu puisses choisir à nouveau. Si quelqu’un d’autre a décidé avant toi, la carte affiche la décision enregistrée.

Une exécution en direct vérifie que le connecteur dispose d’un identifiant utilisable avant de demander une approbation : s’il n’en existe aucun, le nœud échoue avec cette raison au lieu d’attendre une décision.

Tu ne peux pas modifier les paramètres sur la carte. Rejette une demande incorrecte, corrige le workflow ou ses entrées, puis teste la correction avant une nouvelle exécution réelle. Modifier la politique d’approbation ne libère pas une carte déjà en attente. Consulte les [concepts d’approbation](https://docs.tale.dev/fr/platform/approvals/concepts) pour le cycle de décision et la [configuration de la politique](https://docs.tale.dev/fr/self-hosted/configuration/approvals) pour les règles d’exploitation.

## Répondre à une question de l’agent

Quand un nœud agent utilise `ask_human`, le détail affiche **L'agent a besoin de ta réponse pour continuer**. S’il propose des choix, réponds aux questions sur la carte. Pour une réponse libre, saisis du texte sous **Ta réponse**, puis choisis **Envoyer la réponse & reprendre**.

Fournis directement l’information manquante. Si l’agent demande quel document utiliser, donne son nom ou son identifiant plutôt qu’une simple instruction de continuer. Le nœud en attente reprend avec ta réponse. L’exécution peut ensuite demander une autre réponse ou une approbation d’action. Les propriétaires, les admins et les développeurs répondent dans le détail de l’exécution. Quand l’exécution traite une tâche, la question apparaît aussi dans la tâche, où toute personne qui peut ouvrir la tâche y répond.

## Corriger et tester le workflow

Modifier la définition du workflow est une opération distincte de la réponse à son exécution en cours. Enregistre une version corrigée dans l’[éditeur de workflow](https://docs.tale.dev/fr/platform/automations/editor), teste-la avec des Connectors simulés, puis mets-la en service lorsqu’elle est prête. Enregistrer une version ne modifie pas un appel qui attend déjà une approbation.

<Frame caption="Modifie le workflow sur le canevas ; examine une exécution en attente dans son détail.">

![L’éditeur de workflow montre le graphe de l’automatisation et un panneau de configuration du nœud sélectionné.](https://docs.tale.dev/images/platform/automation-editor-canvas.webp)

</Frame>

Un test avec des Connectors simulés n’effectue pas d’écritures externes et ne demande pas leurs approbations réelles. Pour un exemple complet, suis [Créer un workflow avec approbations](https://docs.tale.dev/fr/tutorials/editor/workflow-with-approvals). Après une décision réelle, vérifie le résultat de l’exécution et le [journal d’audit](https://docs.tale.dev/fr/platform/admin/governance/audit-logs) : l’autorisation d’agir et la réussite de l’action sont deux résultats différents.

# Choisir comment créer une automatisation
Source: https://docs.tale.dev/fr/platform/automations/assistant

Modifie une automatisation sur son canevas ou connecte un assistant externe avec MCP pour utiliser les outils de Tale. Les deux chemins enregistrent des versions du même workflow et suivent les mêmes règles de validation et de déploiement. Il te faut les droits Développeur pour créer et déployer des automatisations.

## Modifier le workflow dans l’éditeur visuel

Ouvre **Automatisations** et sélectionne le workflow. Choisis un nœud pour examiner ses entrées, son modèle, son code ou ses autres réglages. Enregistre la modification avec un message de version, lance un test, puis déploie la version souhaitée lorsque ses vérifications passent.

<Frame caption="Le nœud sélectionné affiche sa configuration à côté du graphe.">

![L’éditeur d’automatisation montre le graphe du workflow et les champs d’entrée du nœud sélectionné dans un panneau latéral.](https://docs.tale.dev/images/platform/automation-editor-canvas.webp)

</Frame>

[L’éditeur de workflow](https://docs.tale.dev/fr/platform/automations/editor) détaille ces étapes, l’examen d’une exécution et le retour à une version antérieure. Le canevas n’inclut pas de panneau d’assistant conversationnel.

## Utiliser un assistant externe avec MCP

Configure ton client avec le point d’accès indiqué sous **Paramètres > API > MCP** et une clé API adaptée. Décris les entrées, la sortie attendue et les systèmes que le workflow peut modifier. Demande au client d’examiner les automatisations et capacités existantes avant d’en créer une autre.

Le [point d’accès MCP](https://docs.tale.dev/fr/develop/mcp-endpoint) propose des outils de documentation, validation, enregistrement, test et déploiement. Examine le workflow obtenu et ses résultats de test avant de le déployer. L’enregistrement crée une version, sans la rendre active.

## Distinguer les décisions pendant l’exécution

Un nœud agent accomplit du travail pendant une exécution. Il est distinct du client qui t’aide à écrire le workflow. De même, une [approbation](https://docs.tale.dev/fr/platform/approvals/concepts) autorise une opération en attente pendant l’exécution ; elle ne valide pas une modification proposée de la définition.

Choisis [l’éditeur](https://docs.tale.dev/fr/platform/automations/editor) pour une modification directe ou [MCP](https://docs.tale.dev/fr/develop/mcp-endpoint) pour travailler depuis ton client. Pars d’[une automatisation existante](https://docs.tale.dev/fr/platform/automations/catalog) lorsqu’une solution adaptée est déjà disponible.

# Automatisations livrées
Source: https://docs.tale.dev/fr/platform/automations/builtin

Tale fournit dix paquets d’automatisation : trois synchronisations de courrier, trois résumés de boîte de réception, deux workflows de revue GitHub et des imports d’issues GitHub et GlitchTip. Chacun commence en version 1 avec le statut **Pas en service**. Les imports d’issues s’exécutent manuellement ; les autres paquets incluent une planification. Examine les données attendues, le modèle, les connexions et les écritures avant qu’un Propriétaire, Admin ou Développeur mette une version en service.

<Frame caption="Le catalogue affiche les noms des paquets, le nombre de versions et leur état de mise en service.">

![Le catalogue liste des paquets GitHub et de courrier, chacun avec une version et le statut Pas en service.](https://docs.tale.dev/images/platform/automations-catalog.webp)

</Frame>

## Commencer avec un paquet

Ouvre **Automatisations**, choisis un paquet et examine ses nœuds dans l’[éditeur de workflow](https://docs.tale.dev/fr/platform/automations/editor). Le connector requis doit être connecté, et le modèle de chaque nœud `llm` doit être un modèle que ton organisation sert — les paquets nomment un modèle que tes fournisseurs ne proposent peut-être pas ; la validation t’en avertit à l’enregistrement. Choisis un modèle servi dans le champ **Modèle** du nœud avant une exécution en direct. Un essai utilise des réponses simulées : il vérifie le déroulement sans prouver l’accès à ta boîte de réception ou à ton dépôt réel.

Les paquets sont ajoutés à la création de l’organisation. Lorsque le paquet fourni évolue, tes versions existantes sont conservées ; seuls son nom et sa description fournis sont actualisés. Un paquet supprimé reste supprimé. Tes modifications créent de nouvelles versions, que tu mets en service séparément.

## Synchroniser le courrier dans la Boîte de réception

Ces workflows importent les nouveaux messages dans des conversations toutes les cinq minutes. Chacun fournit la vue **Réception** : sa mise en service ajoute cette vue à [Accueil](https://docs.tale.dev/fr/platform#home) et propose la boîte connectée dans le formulaire de rédaction. Avant cela, **Accueil** n’a pas de vue **Réception**. Un lien vers la boîte de réception affiche alors une invite de configuration : pour les rôles Propriétaire, Admin et Développeur, elle renvoie vers **Automatisations** ; les autres apprennent qu’une personne ayant l’un de ces rôles doit mettre en service une automatisation e-mail.

| Automatisation | Connector requis | Planification |
| --- | --- | --- |
| Synchroniser les e-mails Gmail | Gmail | Toutes les 5 minutes |
| Synchroniser les e-mails Outlook | Outlook | Toutes les 5 minutes |
| Synchroniser les e-mails via SMTP/IMAP | IMAP/SMTP | Toutes les 5 minutes |

Une passe ne lit que le dossier Boîte de réception de la boîte. Elle distingue les réponses de la boîte elle-même de celles du client grâce à l’adresse de la boîte, que la première passe apprend du compte connecté et conserve sur la connexion comme adresse d’expéditeur ; pour IMAP, elle vient de l’identifiant de connexion.

Connecte d’abord la boîte correspondante. Après la première exécution réelle, examine son [journal](https://docs.tale.dev/fr/platform/automations/execution-logs) et vérifie que les messages attendus apparaissent dans la vue **Réception** d’**Accueil**.

Les pièces jointes sont enregistrées avec leur message : tu les ouvres et les télécharges depuis la conversation. Depuis Gmail, Tale ne récupère chaque pièce jointe que jusqu’à 3,5 Mo : une pièce plus lourde reste listée avec son nom et sa taille, mais tu l’ouvres dans Gmail.

## Trier la Boîte de réception

Ces workflows travaillent toutes les six heures sur la **Boîte de réception** que les automatisations de synchronisation alimentent. Chacun lit les conversations ouvertes de son connector de messagerie dont le dernier message vient du client et qu’aucune exécution précédente n’a jugées depuis l’arrivée de ce message – au plus 25 par exécution si tu ne relèves pas `limit`, et jamais plus de 100. Le modèle décide pour chaque fil si une personne doit répondre, et avec quelle urgence.

Ce qu’une exécution change :

- Le verdict est noté sur chaque fil, avec sa raison, de sorte que l’exécution suivante ne réexamine le fil que lorsque le client écrit de nouveau.
- La **priorité** du fil prend la valeur du verdict du modèle – mais seulement si personne n’en a fixé une. Une priorité choisie par une personne reste telle quelle.
- Là où une réponse est due, un second appel au modèle en rédige une et la dépose sur le fil comme **Réponse suggérée** : une carte au-dessus de l’éditeur, à l’écart de ce qu’une personne a tapé. **Mettre dans l’éditeur** confie le texte à l’éditeur pour le retoucher et l’envoyer ; **Ignorer** l’abandonne, et le fil ne reçoit plus de suggestion tant que le client n’écrit pas de nouveau. L’automatisation n’envoie rien. Un fil qui porte déjà une suggestion la conserve.

La sortie de l’exécution liste ce qui a été lu, le résumé du modèle, les fils qui demandent une réponse avec leurs liens vers la Boîte de réception, et les brouillons déposés. Une exécution sans rien en attente n’appelle pas le modèle. Déploie d’abord l’automatisation de synchronisation correspondante ; sans conversations synchronisées, il n’y a rien à trier.

| Automatisation | Connector requis | Planification |
| --- | --- | --- |
| Trier la boîte de réception Gmail | Gmail | Toutes les 6 heures |
| Trier la boîte de réception Outlook | Outlook | Toutes les 6 heures |
| Trier la boîte de réception IMAP | IMAP/SMTP | Toutes les 6 heures |

## Importer et synchroniser des issues

**Importer les issues GitHub** et **Importer les issues GlitchTip** utilisent le même formulaire pour créer des tâches à partir des issues. Ces imports commencent sans planification. Ils lisent la source et écrivent des tâches Tale, sans commenter, fermer ni modifier les issues externes et sans démarrer d’agent.

1. Connecte la source dans **Paramètres > Connectors** et choisis ses identifiants par défaut. GitHub nécessite un accès au dépôt avec le droit de lire les issues. GlitchTip nécessite l’URL de l’instance et un token disposant de `project:read` et `event:read`. Un token réservé à la configuration des projets ne peut pas lire les issues. Une instance auto-hébergée doit être autorisée par la politique des hôtes du connecteur.
2. Ouvre l’import et choisis **Essai**. Sélectionne le **Projet Tale**, puis saisis le propriétaire et le dépôt GitHub ou les identifiants de l’organisation et du projet GlitchTip. Des labels facultatifs ou une recherche GlitchTip permettent de filtrer les nouvelles issues. **Nombre maximal d'issues** accepte 1–500, avec 100 par défaut.
3. Vérifie le résultat du test, mets la version en service, puis choisis **Exécuter en réel** avec la même destination et les mêmes filtres. Un test utilise des données d’exemple et ne crée aucune tâche. Seule une exécution réelle vérifie la connexion.
4. Ouvre **Exécutions** et sélectionne l’exécution. **Tâches importées** contient les liens vers les tâches Tale correspondantes. S’il reste un lot, **Poursuivre l'import** reprend la source, la destination et la position de continuation pour l’exécution suivante. Pour importer plutôt chaque issue selon une planification, une automatisation conserve cette position entre ses occurrences : voir [Importer chaque issue selon une planification](https://docs.tale.dev/fr/platform/automations/triggers#importer-chaque-issue-selon-une-planification).

Chaque synchronisation recherche de nouvelles issues et actualise jusqu’à 500 issues déjà liées, en commençant par celles dont la vérification est la plus ancienne, même lorsqu’elles ne correspondent plus au filtre. Relance la synchronisation pour maintenir les grandes collections à jour. Les pull requests GitHub sont exclues. Un nouvel import réutilise la même identité source dans un projet Tale. Renommer un dépôt ou un projet actualise le lien vers la source sans créer une deuxième tâche. Une issue déplacée vers un autre dépôt ou projet source reste liée et continue d’être actualisée par les imports précédents, si la connexion peut accéder à son nouvel emplacement.

La fiche source d’une tâche affiche séparément le titre, la description et le statut actuels de l’issue. À l’import, Tale coupe sur la tâche les titres de plus de 200 unités de code UTF-16 et les descriptions de plus de 20 000 (la plupart des emojis en comptent 2) à cette longueur et les termine par « … » ; la fiche source et l’issue liée conservent le texte complet. Fermer ou résoudre une issue conserve le statut, le titre, la description, l’attribution et la priorité de la tâche Tale. Si une issue devient inaccessible, ses dernières informations connues restent visibles. Les erreurs d’authentification et les limites de requêtes font échouer l’exécution, sans déclarer l’issue supprimée. Vérifie et termine le travail dans Tale comme d’habitude.

## Examiner le travail sur GitHub

**Trier les issues GitHub** lit les issues ouvertes, évalue leur caractère exploitable et leur priorité, puis renvoie une sélection classée avec les raisons. Le workflow n’écrit rien sur GitHub et ne crée pas de tâche de projet. Sa limite par défaut est de 50 issues par exécution.

**Examiner les pull requests GitHub** lit les diffs des pull requests ouvertes et publie ses conclusions sous forme de commentaires de revue. Sa limite par défaut est de 10 pull requests par exécution. Il n’approuve ni ne fusionne de pull request. Vérifie le dépôt cible avant une exécution réelle : une nouvelle exécution peut ajouter d’autres commentaires.

| Automatisation | Connector requis | Planification fournie | Écritures |
| --- | --- | --- | --- |
| Trier les issues GitHub | GitHub | Chaque jour à 07:00 UTC | Aucune ; lis la sortie de l’exécution |
| Examiner les pull requests GitHub | GitHub | Toutes les 30 minutes | Un commentaire de revue par pull request traitée |

Les deux workflows exigent `owner` et `repo`. Dans **Essai**, renseigne **Données de l’exécution (JSON)** avec les valeurs de ton dépôt :

```json
{
  "owner": "ton-organisation",
  "repo": "ton-depot",
  "limit": 5
}
```

<Note>

Les planifications GitHub fournies ne transmettent ni `owner` ni `repo` : la mise en service seule ne suffit donc pas à rendre ces exécutions planifiées valides. Une planification n’envoie que `trigger` et `firedAt` : l’entrée de dépôt requise est donc absente et le démarrage est refusé. Lance le workflow manuellement avec les données requises, ou adapte le schéma et la configuration du dépôt avant d’activer les exécutions planifiées. Un démarrage planifié refusé apparaît comme `start_refused` sur le [déclencheur](https://docs.tale.dev/fr/platform/automations/triggers).

</Note>

Avant la mise en service, lis les données résolues et la sortie de l’essai. Pour une exécution réelle, vérifie aussi les permissions du connector et les approbations nécessaires. Les [journaux d’exécution](https://docs.tale.dev/fr/platform/automations/execution-logs) expliquent les attentes, les échecs et les écritures enregistrées.

# Créer ou importer une automatisation
Source: https://docs.tale.dev/fr/platform/automations/catalog

Ouvre **Automatisations** pour retrouver les workflows de ton organisation. Seuls les rôles Propriétaire, Admin et Développeur voient cette section et en gèrent les automatisations. Commence par vérifier si une [automatisation fournie](https://docs.tale.dev/fr/platform/automations/builtin) répond au besoin. Sinon, crée un brouillon que tu pourras tester avant sa mise en service.

La recherche porte sur le nom et le slug. Saisis par exemple `Triage` pour comparer les workflows de triage fournis.

<Frame caption="La liste filtrée avec Triage présente quatre exemples fournis, leur nombre de versions et leur état de déploiement.">

![Quatre automatisations de triage filtrées pour GitHub, Gmail, IMAP et Outlook, avec leurs versions, leur état de déploiement et le bouton de création d’une automatisation.](https://docs.tale.dev/images/platform/automations-catalog.webp)

</Frame>

## Choisir un point de départ

Chaque ligne indique le nom, les projets associés, le nombre de versions et la version en service, ou **Pas en service**. Ouvre-la dans l’onglet **Éditeur** pour examiner le workflow. **Général** regroupe son déclencheur et ses projets : **Projets** détermine les boards qui peuvent l’utiliser ; sans association à un projet, elle sert l’organisation. **Projets** ne propose que les projets que tu peux ouvrir, et l’enregistrement conserve les associations aux projets que tu ne vois pas. Une automatisation associée uniquement à de tels projets n’apparaît pas dans ta liste. Le sélecteur **Version**, à droite des onglets, présente les versions enregistrées, et **Exécutions**, les derniers lancements.

Le menu **Créer une automatisation** propose deux parcours :

| Choix | À utiliser si… | Suite du parcours |
| --- | --- | --- |
| **Vierge (trigger + agent)** | tu souhaites configurer le workflow toi-même. | Définis le nom, le modèle, les instructions et les équipements, puis choisis quand l’agent s’exécute. La création ouvre l’éditeur pour la suite des modifications. |
| **Téléverser un paquet** | tu disposes d’un fichier de workflow ou d’un pack réutilisable. | Tale valide les fichiers et enregistre une version brouillon. |

Les automatisations fournies sont installées à la création de l’organisation. Elles demandent encore leur configuration et une version en service avant un usage automatique. [L’éditeur de workflows](https://docs.tale.dev/fr/platform/automations/editor) explique comment tester les données, examiner les résultats et mettre la version choisie en service.

## Importer un paquet

Un pack contient le fichier obligatoire `workflow.yml`, un manifeste `automation.yml` facultatif et, si nécessaire, des bundles de skills :

```text
review-invoices/
├── workflow.yml
├── automation.yml
└── skills/
    └── invoice-rules/
        ├── SKILL.md
        └── references/
            └── checklist-rules.md
```

<Steps>

<Step title="Sélectionner les fichiers">

Choisis **Créer une automatisation > Téléverser un paquet**. Ajoute le workflow et son manifeste éventuel comme fichiers séparés, ou sélectionne une seule archive `.zip` du pack. Les skills exigent l’archive ; téléverse-la seule. Les notes Markdown hors de `skills/`, les fichiers cachés et les résidus de compilation comme `node_modules/` ou `__pycache__/` sont ignorés.

</Step>

<Step title="Choisir la destination">

Sous **Installer dans**, sélectionne **Organisation** ou un projet existant. Un manifeste déclarant `scope: project` exige un projet. Importer une automatisation existante dans un autre projet ajoute cette association sans retirer les précédentes. La section **Projets** de l’onglet **Général** de l’automatisation permet ensuite de modifier l’ensemble des associations.

<Frame caption="Téléverser un paquet — les fichiers ou un zip, et où l’automatisation s’installe.">

![Le dialogue de téléversement de paquet avec sa zone de dépôt et le sélecteur Installer dans réglé sur Organisation.](https://docs.tale.dev/images/platform/automations-upload-dialog.webp)

</Frame>

</Step>

<Step title="Valider et enregistrer">

Choisis **Téléverser le paquet** et corrige les problèmes signalés dans le workflow, le manifeste ou les skills. La validation précède l’écriture de l’automatisation et des skills fournis. Un nouvel import de la même automatisation ajoute une version brouillon et conserve l’historique.

</Step>

<Step title="Examiner avant la mise en service">

Choisis **Plus tard** pour ouvrir et tester le brouillon dans l’éditeur. Le dialogue de réussite permet aussi de mettre directement la version numérotée en service. Le téléversement seul ne change pas la version active. Configure les identifiants nécessaires et examine les skills avant le déploiement.

</Step>

</Steps>

L’archive ne doit dépasser 20 MiB ni compressée ni décompressée, avec au plus 500 fichiers, 2 MiB par fichier et 20 bundles de skills. Si elle est trop volumineuse, retire les artefacts générés et sépare les contenus indépendants en plusieurs skills. Une compression plus forte ne réduit pas la taille décompressée.

## Résoudre les conflits de skills

La liste `skills` du manifeste doit correspondre aux dossiers fournis sous `skills/`. Un dossier non déclaré ou un bundle déclaré mais absent fait refuser l’import. Chaque bundle exige des métadonnées valides dans `SKILL.md`, avec un `name` identique au nom du dossier. Les skills fournis suivent les règles de la bibliothèque de skills : un nouveau skill appartient à la personne qui téléverse le paquet. Un skill remplacé garde son propriétaire ou appartient à cette personne s’il n’en avait pas. Une liste d’équipes nouvelle ou modifiée ne peut contenir que des équipes avec lesquelles cette personne peut partager. Une liste existante peut rester inchangée. Tale vérifie le public de tous les skills fournis avant d’en installer un seul.

```yaml
# automation.yml
name: Review invoices
skills:
  - invoice-rules
```

Les nouveaux bundles rejoignent la [bibliothèque de skills](https://docs.tale.dev/fr/platform/workspace/skills) de l’organisation ; les bundles identiques restent inchangés. Un contenu différent suspend l’import et affiche les slugs concernés. Examine-les avant de confirmer : le paquet remplace ces bundles partagés, tandis que l’ancien `SKILL.md` reste dans leur historique. Aucune automatisation ni aucun skill n’est écrit avant cette confirmation.

Le workflow peut aussi appeler des skills de la bibliothèque qu’il ne fournit pas. Si l’un manque, l’import affiche un avertissement. Installe un bundle accessible avant de lancer l’agent qui en dépend. L’enregistrement d’un brouillon ne prouve pas que toutes ses dépendances sont prêtes.

## Configurer un projet avec les formulaires du paquet

Le manifeste peut définir des formulaires qui apparaissent à la sélection du modèle de tâche. Les valeurs appartiennent au projet : deux projets peuvent donc employer la même automatisation avec des règles différentes.

```yaml
# automation.yml
settings:
  folder: Setup
  forms:
    - file: validation-policy.yaml
      title: Validation policy
      required: true
      fields:
        - key: method
          label: Validation profile
          type: select
          default: strict_rules
          options:
            - value: strict_rules
              label: Strict checklist
```

Si le projet n’est pas encore configuré, les formulaires obligatoires précèdent les champs de la tâche. **Enregistrer et continuer** les écrit puis reprend la création. **Paramètres** les rouvre ensuite sous forme d’onglets. Un point signale les modifications non enregistrées ; **Enregistrer** écrit tous les formulaires modifiés. Fermer avec des changements en attente demande confirmation.

L’enregistrement remplace le fichier YAML plat du formulaire, par exemple `Setup/validation-policy.yaml`. Les valeurs existantes préremplissent le formulaire, y compris celles d’un fichier téléversé manuellement. Les types admis sont `text`, `number`, `boolean` et `select` ; les valeurs sont stockées comme chaînes. Un champ texte peut imposer un `pattern`. Des blocs `i18n` par entrée traduisent titres, libellés, aide et options. Place les listes et structures imbriquées dans des fichiers séparés que le workflow lira en complément.

## Fournir des références dans un formulaire de fichiers

Un formulaire de fichiers gère directement un dossier au lieu de produire du YAML :

```yaml
settings:
  folder: Setup
  forms:
    - kind: uploads
      title: Reference documents
      subdir: reference
      accept: ['.pdf', '.json']
      match: '\.(pdf|json)$'
      requireFolder: true
```

`subdir` désigne un sous-dossier des paramètres. `accept` limite les extensions proposées par le sélecteur ; `match` filtre les noms sans distinguer la casse et refuse les fichiers qui ne figureraient pas dans la liste. Avec `requireFolder: true`, choisis ou crée d’abord un sous-dossier, par exemple pour chaque période de rapport.

Les téléversements s’appliquent immédiatement, sans bouton **Enregistrer**, et ne bloquent jamais la création d’une tâche. Les exécutions lisent le contenu actuel du dossier. Termine donc la préparation des références avant de lancer le travail qui en dépend.

## Définir les livrables attendus

Le manifeste peut nommer les fichiers de la zone **Résultat** de la tâche. Ils restent dans l’ordre déclaré ; les autres pièces jointes et fichiers de travail sont regroupés sous **Fichiers**.

```yaml
subjects:
  task:
    outcome:
      files:
        - return.xml
        - report.md
        - name: audit-summary.md
          optional: true
```

Un fichier obligatoire apparaît comme **Pas encore prêt** tant qu’une exécution ne l’a pas déposé. Un fichier facultatif n’apparaît qu’une fois présent. Les motifs acceptent `*` et `?`, par exemple `return-*.xml`. Sans déclaration, le résultat regroupe tous les fichiers déposés par les exécutions, du plus récent au plus ancien. Une liste explicite aide à distinguer le rapport final des documents de travail.

## Demander avant une approbation qui engage davantage

**Approuver** clôt la tâche en un clic. Quand l’approbation signifie davantage que clore la tâche, déclare cette conséquence, par exemple quand une intégration transmet l’approbation à un client comme un dépôt. **Approuver** demande alors confirmation et affiche ta phrase :

```yaml
subjects:
  task:
    review:
      requestChanges: true
      approve:
        confirm: Approving tells the client this return has been filed with the tax authority. Approve only after you have filed it.
        i18n:
          fr:
            confirm: L’approbation indique au client que cette déclaration a été déposée auprès de l’administration fiscale. N’approuve qu’après l’avoir déposée.
```

Sans `approve`, **Approuver** reste une clôture en un clic. Traduis la phrase sous `i18n` ; une langue sans phrase propre utilise sa langue de base, puis la phrase anglaise.

# Concepts d’automatisation
Source: https://docs.tale.dev/fr/platform/automations/concepts

Utilise une automatisation pour un travail qui suit un processus répétable. Le workflow décrit les étapes ; les versions enregistrées conservent les révisions, le déploiement choisit la version exécutée en réel et un déclencheur peut la lancer selon un horaire ou un événement. Chaque exécution permet d’examiner les données, les résultats et les opérations.

Tu préfères regarder d’abord ? L’épisode 5 ouvre l’automatisation de triage de bout en bout et décide une carte de validation à l’écran, sous-titres compris — enregistré sur l’ancienne version, où la carte se trouvait dans le chat ; dans cette version, elle se trouve sur la page de détail de l’exécution.

<Video src="https://docs.tale.dev/videos/fr/tutorials/ep5-automations/ep5-automations.fr.mp4" poster="https://docs.tale.dev/videos/fr/tutorials/ep5-automations/ep5-automations.fr.webp" captions="https://docs.tale.dev/videos/fr/tutorials/ep5-automations/ep5-automations.fr.vtt" lang="fr" title="Épisode 5 — Automatisations & validations" caption="Épisode 5 — Automatisations & validations (2:34)">

</Video>

## Le document de workflow

Le `name` identifie l’automatisation. Utilise des segments en minuscules séparés par des tirets ; `/` regroupe les automatisations liées dans des dossiers, comme `billing/dunning-reminder`. Le premier segment ne doit pas être un nom de page réservé : `asks`, `builder`, `catalog`, `listing`, `metrics`, `runs`, `serving-preview` ou `upload`.

Le document contient aussi une `description`, un schéma JSON `inputs` pour les données reçues, les `nodes` qui exécutent les étapes et une expression `output` pour le résultat. Ses `tests` décrivent des exemples et les résultats attendus, vérifiés avant la mise en service.

```yaml
name: billing/dunning-reminder
description: Relancer un client sur une facture en retard.
inputs:
  type: object
  properties:
    invoiceId: { type: string }
  required: [invoiceId]
nodes:
  - id: invoice
    type: transform
    input:
      id: '{{ input.invoiceId }}'
    code: 'return { id: input.id, daysLate: 14 };'
  - id: message
    type: llm
    model: openai/gpt-4o-mini
    prompt: 'Rédige une relance polie pour la facture {{ nodes.invoice.output.id }}.'
output:
  text: '{{ nodes.message.output.text }}'
tests:
  - name: rédige une relance
    input: { invoiceId: 'inv-1' }
```

Le bloc `ui` conserve la disposition du canvas. Déplacer un nœud modifie sa position, sans changer son exécution.

### Les liaisons se déduisent, elles ne se déclarent pas

Il n’y a pas de liste de liaisons. Un nœud en lit un autre en le référençant — `{{ nodes.invoice.output.id }}` — et cette référence _est_ la liaison que trace le canvas. L’ordre d’exécution est un tri topologique sur ces liaisons déduites : supprimer une référence retire donc aussi une flèche, et deux nœuds qui se lisent l’un l’autre sont refusés comme une boucle.

Les templates utilisent une seule grammaire `{{ }}` d’expressions JavaScript sur `input`, `nodes.<id>.output` et, à l’intérieur d’un nœud qui itère, `item` et `index`.

### Le contrôle du flux vit sur le nœud

Brancher et répéter sont des champs du nœud plutôt que des types d’étape à part. Le canvas les montre donc comme des badges sur la boîte qu’ils concernent.

| Champ                        | Ce qu’il fait                                                                                 |
| ---------------------------- | --------------------------------------------------------------------------------------------- |
| `when`                       | N’exécute le nœud que si l’expression est vraie ; ses dépendants sont ignorés avec lui        |
| `elseOf`                     | S’exécute exactement quand le nœud nommé a été ignoré par son propre `when`                   |
| `forEach`                    | S’exécute une fois par élément d’une collection, avec `item` et `index` disponibles           |
| `repeatUntil` / `maxRepeats` | Relance jusqu’à ce que l’expression soit vraie, avec un plafond (5 par défaut, 20 au maximum) |
| `onError`                    | `fail` arrête l’exécution ; `continue` note l’erreur et ignore les dépendants                 |

### Les types de nœud

Quatre types sont intégrés, et chaque action de connector comme chaque capacité native de la plateforme — recherche dans les connaissances, opérations sur documents — rejoint la même table à côté d’eux.

**`transform`** exécute du JavaScript pur pour remettre des données en forme. Sans réseau ni imports : le corps lit l’`input` résolue du nœud et doit retourner une valeur.

**`llm`** appelle un modèle de langage avec un prompt en template. `model` est obligatoire et toujours explicite — une automatisation n’en choisit jamais un à ta place (l’Auto du composer est une affaire de chat, et de chat seulement). La sortie est `{text}`, ou l’objet à la forme du schéma quand le nœud déclare un `outputSchema`.

**`agent`** exécute un tour d’un agent de code (Claude Code, Codex et les autres harnesses) dans la sandbox. Il lit les `files` mis en place, utilise des `skills`, des `connectors` relayés, des `tools` de plateforme accordés et des `secrets` injectés, et renvoie `{text, files, status}` ; `model` est obligatoire. Si un admin a activé la [génération d’images](https://docs.tale.dev/fr/platform/admin/governance/content-models#let-agents-generate-images), il peut aussi créer des images, qui reviennent parmi ses `files`. Prends `llm` quand une complétion unique suffit, et `agent` seulement quand l’étape a besoin d’outils, de fichiers ou de plusieurs tours — un nœud agent en service s’exécute comme un tour asynchrone, il siège donc au niveau supérieur plutôt que dans une `subautomation` et n’itère pas avec `forEach`.

**`subautomation`** exécute une autre automatisation enregistrée comme un seul nœud ; son champ `automation` nomme `"name"` ou `"name@version"`. Sans version, c’est celle en service, et l’imbrication s’arrête à trois niveaux.

### Sortie structurée et non structurée

Une sortie **structurée** possède des champs nommés, accessibles avec `nodes.<id>.output.<field>`. Une sortie **non structurée** contient du texte libre. Référence-la avec `nodes.<id>.output.text` dans une expression textuelle ; ne la traite pas comme un objet possédant d’autres champs.

Un outil sans schéma de sortie produit une sortie non structurée. Pour transformer son texte en données structurées utilisables par les étapes suivantes, ajoute un nœud `llm` avec un `outputSchema`. En cas d’erreur, la validation indique la référence incorrecte et les champs ou contextes autorisés. Corrige-la avant d’enregistrer à nouveau.

## Les versions ne changent jamais

Enregistrer crée une version au lieu d’écraser la précédente. Chaque automatisation possède une numérotation commençant à 1 ; chaque version conserve la note de modification de son auteur. Le workflow d’une version existante reste inchangé.

Une exécution conserve la version avec laquelle elle a démarré. Les modifications suivantes ne changent donc pas ses étapes. Pour examiner une ancienne exécution, ouvre sa version enregistrée et compare les données avec le workflow. Cette immutabilité ne garantit pas une conservation illimitée : supprimer une automatisation ou son historique peut retirer ces enregistrements.

## La mise en service est un geste distinct

Une seule version par automatisation est en service, et c’est celle que lancent les déclencheurs. Mettre une version en service, ou revenir à une plus ancienne, est un geste unique qui ne réécrit aucun historique : la liste des versions reste exactement telle quelle, seul le pointeur bouge. Une automatisation peut aussi n’avoir aucune version en service et vivre uniquement à l’état de brouillon.

Une version dont un test échoue ne peut pas être mise en service ; une version dont les tests réussissent, ou qui n’en a aucun, le peut. Les tests sont rangés dans le document : chacun porte un nom, une entrée, et des attentes sur la sortie comme sur les effets que l’exécution doit produire. Le résultat des tests d’une version est consigné au moment de l’enregistrement, si bien que la mise en service lit ce fait consigné au lieu de rejouer la suite.

<Note>

Une exécution réelle nécessite une version en service. Tu peux tester un brouillon enregistré avec **Essai** avant son déploiement.

</Note>

## Ce qui lance une exécution

Tu peux tester manuellement une version enregistrée ou exécuter en réel la version en service. Pour un démarrage automatique, configure l’un des trois déclencheurs : une planification avec expression cron et fuseau IANA, une URL de webhook protégée par un jeton, ou un événement nommé de la plateforme.

Le déclencheur appartient au nom de l’automatisation. Mettre une autre version en service conserve sa configuration et l’URL du webhook, mais les démarrages suivants utilisent la nouvelle version. Désactive le déclencheur pour suspendre les démarrages automatiques. [Déclencheurs de workflow](https://docs.tale.dev/fr/platform/automations/triggers) explique les horaires, l’authentification et les données fournies par chaque type.

## Ce qu’une exécution enregistre

Une exécution conserve son statut (`queued`, `running`, `waiting`, `success`, `failed` ou `cancelled`), son mode, son origine, ses données d’entrée et de sortie, ainsi qu’un point de reprise par nœud terminé. Sa trace explique les étapes tentées par le moteur.

Si le traitement doit rendre la main avant la fin, la même exécution reprend depuis ses points de reprise sans répéter les nœuds terminés. La liste des effets recense les écritures des connectors. Elle ne constitue pas un inventaire complet des changements effectués depuis une sandbox ou par des outils directs. L’historique reste soumis aux règles de conservation et de suppression.

Le mode **Essai** simule les opérations externes pendant la préparation. Le mode **Réel** peut les effectuer et exige des droits de développeur au démarrage. [Journaux d’exécution](https://docs.tale.dev/fr/platform/automations/execution-logs) explique comment vérifier la version enregistrée, les données résolues, les erreurs et les effets consignés.

## Là où un humain décide

Une approbation suspend l’exécution au statut `waiting` avant une écriture protégée. Approuver autorise le moteur à tenter l’opération, sans garantir sa réussite. Rejeter empêche l’opération et fait échouer l’exécution. Une question suspend aussi le traitement, mais demande une information plutôt qu’une permission.

Le statut `waiting` peut également indiquer qu’un agent travaille encore, qu’une étape d’agent attend une place de sandbox pour démarrer, ou qu’un nœud vérifie périodiquement une condition. Consulte `waitingFor` : `approval` et `ask` nécessitent une personne ; `agent`, `room` et `repeat` reprennent normalement seuls. [Approbations dans les workflows](https://docs.tale.dev/fr/platform/automations/approvals-in-workflows) explique comment examiner et traiter les demandes humaines.

## Choisir un chat, une tâche ou une automatisation

| Besoin | Utilise |
| --- | --- |
| Poser une question et discuter de la réponse | Chat |
| Produire un résultat relu avec un responsable | Une tâche de projet, éventuellement assignée à un agent |
| Enchaîner des étapes ou réagir à un horaire, webhook ou événement | Une automatisation |

Consulte les [automatisations fournies](https://docs.tale.dev/fr/platform/automations/builtin) avant de créer la tienne. Un webhook démarre une automatisation ; ce n’est pas un type distinct d’agent de projet.

## Mettre le modèle en pratique

Workflow, versions, déploiement et déclencheur sont des éléments distincts d’une même automatisation. Suis [L’éditeur de workflow](https://docs.tale.dev/fr/platform/automations/editor) pour tester et mettre un changement en service, puis les [Journaux d’exécution](https://docs.tale.dev/fr/platform/automations/execution-logs) pour examiner son résultat.

# L’éditeur de workflow
Source: https://docs.tale.dev/fr/platform/automations/editor

L’éditeur de workflow permet de modifier le comportement d’une automatisation et de choisir sa version active. Il faut les droits Développeur, Admin ou Propriétaire pour apporter des changements. Enregistrer, tester et mettre en service sont des étapes distinctes : modifier un brouillon laisse la version déployée en place.

Ouvre **Automatisations**, puis sélectionne une automatisation. Elle s’ouvre dans l’onglet **Éditeur**. Pour en créer une, consulte [Créer ou importer une automatisation](https://docs.tale.dev/fr/platform/automations/catalog).

| Onglet | Utilisation |
| --- | --- |
| **Éditeur** | Modifier le workflow, tester une version enregistrée et choisir celle à mettre en service. |
| **Général** | Choisir ce qui démarre l’automatisation et les projets qui peuvent l’utiliser. |
| **Exécutions** | Examiner les derniers lancements et ouvrir le détail d’une exécution. |

Le sélecteur **Version** reste à droite des onglets Éditeur, Général et Exécutions, sur ordinateur comme sur téléphone. Il affiche les messages de version, les dates, les résultats des tests et la version en service. Sélectionne une ligne pour ouvrir cette version. Sur ordinateur, les commandes d’exécution se trouvent à côté des onglets, avec **Enregistrer** et **Abandonner** ; dans **Général**, seuls **Enregistrer** et **Abandonner** y figurent. Un point sur un onglet signale ses modifications non enregistrées. Avant de quitter cet onglet ou de changer de version, Tale te demande quoi en faire.

Sur téléphone, la navigation est compacte à l’ouverture d’une automatisation. Le canevas de l’éditeur occupe la hauteur disponible. Les commandes d’exécution et de mise en service se trouvent dans le canevas, à côté du zoom. Sélectionne un nœud pour ouvrir ses champs — avec Enregistrer et Abandonner — dans un panneau au bas de l’écran.

<Frame caption="Sur un écran large, sélectionne un nœud pour examiner ses champs à côté du canvas.">

![L’éditeur montre les nœuds connectés et les champs du nœud sélectionné à côté du canvas.](https://docs.tale.dev/images/platform/automation-editor-canvas.webp)

</Frame>

Pour passer à une autre automatisation sans revenir à la liste, clique sur le nom de celle qui est ouverte dans le fil d’Ariane. Le menu garde toutes les automatisations de l’organisation, même après un changement de projet, sauf celles associées uniquement à des projets que tu ne peux pas ouvrir. Celles qui ne sont rattachées à aucun projet apparaissent en premier, puis viennent celles liées à des projets. Une ligne horizontale sépare les deux groupes. Cherche par nom ou par slug, puis sélectionne une entrée. Tu conserves l’onglet ouvert. Depuis le détail d’une exécution, tu arrives sur la liste **Exécutions** de l’autre automatisation. Le numéro de version sélectionné n’est pas repris : **Éditeur** affiche la dernière version enregistrée de cette autre automatisation.

## Lire le canvas

Chaque bloc est un nœud. Son libellé indique l’étape et le type ; **Lit** désigne les nœuds dont il utilise la sortie. Les flèches viennent des références, comme `{{ nodes.draft.output.text }}`. Modifie la référence pour changer la dépendance ; dessiner une flèche ne crée pas de dépendance.

Les badges indiquent les conditions et boucles : `when`, `else of`, `for each`, `repeat until` et `continue on error`. Un avertissement de cycle signifie que plusieurs nœuds dépendent les uns des autres. Supprime la référence circulaire avant d’enregistrer une version exécutable.

## Modifier un nœud

Sélectionne un bloc pour ouvrir ses champs. Sur un écran large, le panneau apparaît à côté du canvas ; sans nœud sélectionné, le canvas occupe toute la largeur. Sur un écran plus étroit, les champs s’ouvrent dans un dialogue au-dessus du canvas. Un `transform` possède du **Code** ; un `llm`, des champs de prompt, modèle et schéma de sortie ; un `agent` ajoute le harness et l’équipement. Le sélecteur **Modèle** d’un nœud `llm` ou `agent` liste les modèles servis par les fournisseurs connectés de ton organisation ; un modèle absent de la liste peut être saisi, mais la validation avertit qu’une exécution en direct échouerait à ce nœud tant que son fournisseur n’est pas connecté. **Entrée** contient les valeurs JSON et références transmises au nœud. Un JSON incomplet est signalé et ne met pas le nœud à jour.

Ouvre **Contrôle du flux** pour les conditions et répétitions. Si le nœud en a, la section est déjà ouverte. Utilise **Fermer** pour revenir au canvas. Sur un écran large, tu peux aussi fermer le panneau en cliquant sur le fond du canvas ou en appuyant sur Échap hors d’un champ de texte. Les réglages du déclencheur et des projets se trouvent dans l’onglet **Général**. [Concepts d’automatisation](https://docs.tale.dev/fr/platform/automations/concepts) explique les types de nœuds et les expressions.

## Enregistrer et tester une version

1. Modifie les champs nécessaires et clique sur **Enregistrer**.
2. Explique le changement dans le **Message de version**, puis choisis **Enregistrer la version**. Cela ajoute une version et conserve les précédentes. Si quelqu’un a enregistré une autre version pendant ta modification, Tale refuse l’enregistrement et te demande : **Abandonner mes modifications et recharger** affiche la version plus récente, **Enregistrer quand même** ajoute ta version par-dessus — la plus récente reste dans l’historique des versions, mais la dernière version est alors la tienne.
3. Clique sur **Essai**. Si le workflow déclare un schéma d’entrée, remplis **Données de l’exécution (JSON)** dans le dialogue. Déplie **Schéma des données** pour vérifier les champs obligatoires et leurs types. Un JSON invalide ou non conforme au schéma empêche le démarrage.
4. Lance le test, passe à l’onglet **Exécutions** et ouvre sa ligne. Compare les données résolues, la sortie et les opérations prévues au résultat attendu.

Pour un workflow qui exige `owner` et `repo`, les données pourraient être :

```json
{
  "owner": "your-organization",
  "repo": "your-repository"
}
```

Utilise le schéma réel du workflow. Un champ numérique attend un nombre JSON, pas une chaîne entre guillemets. Vérifie aussi le périmètre lorsqu’un sélecteur de projet est proposé.

**Essai** utilise la version enregistrée sélectionnée et des simulations déterministes. Aucun e-mail n’est envoyé et aucune fiche externe n’est modifiée. Un brouillon peut être testé avant sa mise en service. Une simulation réussie ne vérifie pas les identifiants réels ni les services externes.

<Frame caption="Pour un workflow avec des données d’entrée, saisis le JSON et vérifie le schéma avant le test.">

![Le dialogue de test montre les valeurs JSON owner et repo et le schéma des données déplié.](https://docs.tale.dev/images/platform/automation-run-input.webp)

</Frame>

## Mettre en service et exécuter en réel

Choisis la version testée sous **Version** et clique sur le bouton voisin, qui nomme cette version, par exemple **Mettre v3 en service**. Le badge **En service** indique la version déployée. Une version dont les tests enregistrés ont échoué ne peut pas être déployée ; corrige la cause et enregistre une nouvelle version.

**Exécuter en réel** lance la version déployée, même si tu en consultes une autre. La confirmation montre le périmètre et, si nécessaire, les **Données de l’exécution (JSON)** pour cette version déployée. Vérifie les deux avant de confirmer. Les exécutions réelles peuvent agir sur les systèmes connectés et attendre une [approbation](https://docs.tale.dev/fr/platform/approvals/concepts).

Un déclencheur utilise aussi la version déployée. Configure-le lorsque tu es prêt pour des exécutions répétées ou démarrées par un système externe ; consulte [Déclencheurs d’automatisation](https://docs.tale.dev/fr/platform/automations/triggers).

## Examiner un résultat

**Afficher la dernière exécution** superpose les états au canvas. Sélectionne un nœud pour consulter les données de cette exécution : entrée résolue, sortie et effets. Cela suffit souvent à trouver une référence incorrecte. Compare l’entrée du nœud échoué à la sortie de sa source.

Passe à **Exécutions** et ouvre une ligne pour le détail complet. Les onglets restent visibles, avec **Exécutions** actif. **Éditeur** te ramène au workflow. Vérifie s’il s’agissait d’un test ou d’une exécution réelle et examine les opérations déjà réalisées avant de relancer. [Journaux d’exécution](https://docs.tale.dev/fr/platform/automations/execution-logs) explique les attentes, échecs, relances automatiques et arrêts.

## Revenir à une version ou supprimer

Pour revenir à une ancienne version, ouvre **Version** à droite des onglets, lis les messages et sélectionne la version souhaitée. Sa ligne ouvre **Éditeur** sur cette version ; clique ensuite sur le bouton qui la met en service, par exemple **Mettre v2 en service**. Les prochains démarrages l’utiliseront ; l’historique reste intact. Un message comme « Rétablir l’association précédente des destinataires » rend le choix plus facile à relire.

Pour supprimer l’automatisation, retourne à la liste, ouvre le menu de sa ligne et choisis **Supprimer**. Lis la confirmation qui la nomme. Les versions, le déploiement, le déclencheur et les liens aux projets sont retirés. Une exécution inachevée bloque la suppression : arrête-la ou attends sa fin. Les anciennes exécutions restent soumises à la conservation. Supprimer l’automatisation n’annule pas les actions déjà réalisées.

# Examiner les exécutions et corriger les échecs
Source: https://docs.tale.dev/fr/platform/automations/execution-logs

Ouvre une automatisation, passe à son onglet **Exécutions** et choisis une ligne pour comprendre ce qui s’est passé. Commence par le statut, la version et le mode, puis examine le nœud concerné. Un essai réussi prouve le déroulement simulé, pas l’acceptation de la même action par un compte externe réel.

<Frame caption="Une exécution de test terminée : son statut, son mode, sa version, son initiateur et ses horaires au-dessus du workflow, avec le résultat de chaque nœud.">

![La page d’une exécution de test de Triage GitHub issues, marquée Succeeded, Test et v1 et lancée par toi, avec ses heures de début et de fin au-dessus du graphe du workflow, où les nœuds issues, open issues, score et report affichent chacun Ran ; la liste des effets de l’exécution commence sous le graphe.](https://docs.tale.dev/images/platform/automation-run-detail.webp)

</Frame>

## Lire l’état de l’exécution

L’onglet **Exécutions** présente les 50 dernières exécutions que tu peux voir, de la plus récente à la plus ancienne. Les propriétaires, les admins et les développeurs voient les exécutions de l’organisation elle-même ; une exécution dans un projet, et la question qu’elle attend, n’apparaissent qu’à ceux d’entre eux qui peuvent ouvrir ce projet. Chaque ligne précise version, date, mode et déclencheur, ou donne la cause d’un échec ou d’une attente. Le détail affiche le workflow, les résultats des nœuds et les horaires. Une exécution inachevée n’a pas de date de fin. Les onglets restent visibles pendant la consultation. Choisis **Exécutions** pour revenir à la liste, ou **Éditeur** pour modifier le workflow.

| Statut | Signification | Suite à donner |
| --- | --- | --- |
| **En file d’attente** | Acceptée, en attente d’exécution. | Attendre, puis examiner la capacité si rien ne progresse. |
| **En cours** | Le moteur traite le workflow. | Suivre les nœuds. |
| **En attente** | Une décision, une réponse, un agent ou une condition reste attendu. | Lire ce qui manque. |
| **Réussie** | Les nœuds atteints ont terminé et la sortie est produite. | Examiner sortie et effets. |
| **En échec** | L’exécution s’est terminée sur un échec non traité. | Ouvrir le nœud concerné et lire l’erreur. |
| **Arrêtée** | L’exécution a été annulée. | Vérifier le travail déjà fait avant de relancer. |

Une approbation ou une question attend une personne ; un agent au travail ou une interrogation répétée peut poursuivre seul. Une décision ou une réponse peut aussi être refusée ou expirer. Utilise la cause affichée, pas le seul statut **En attente**, pour décider d’intervenir. [Approbations dans les workflows](https://docs.tale.dev/fr/platform/automations/approvals-in-workflows) explique les commandes de décision.

## Examiner le nœud concerné

Sélectionne un nœud sur le canvas de l’exécution. **Entrée résolue** montre les valeurs après évaluation des expressions, et **Sortie** le résultat de l’étape. Ces champs distinguent une mauvaise référence d’une défaillance du service.

Les états comprennent **Exécuté**, **Ignoré**, **En échec**, **Jamais atteint**, **Pas encore atteint** et, pour une exécution arrêtée, **Arrêté ici** pour le nœud sur lequel elle se trouvait au moment de l’arrêt. Une condition fausse, une dépendance, une branche alternative ou une règle de poursuite après erreur peut expliquer un nœud ignoré. Ce n’est pas toujours un problème.

Par exemple, un rappel peut recevoir le nom du client mais un identifiant de facture vide. Examine la sortie précédente. Si le champ a été renommé, corrige la référence plutôt que les identifiants de messagerie. Vérifie ensuite l’entrée résolue dans un nouvel essai.

Une application qui lit l’[API des exécutions](https://docs.tale.dev/fr/develop/api-reference) reçoit aussi `failureCode` lorsqu’une cause a été attribuée à l’échec. Par exemple, `approval_rejected` indique qu’une personne a refusé l’opération, tandis que `llm_output_invalid` signale une réponse du modèle qui ne respecte pas la structure attendue. Les anciens échecs peuvent ne pas avoir de code. Celui-ci aide à orienter le diagnostic ; il ne garantit ni qu’une relance est sans risque, ni qu’elle réussira.

## Vérifier les changements déjà effectués

La liste des effets enregistre les écritures des connectors avec leur nœud, leur connector et leurs données. Les essais utilisent des réponses simulées ; les actions réelles peuvent modifier des systèmes externes. L’exécution indique explicitement l’absence d’effets enregistrés.

Lis cette liste avant de recommencer. Un échec ultérieur n’annule ni un message déjà envoyé ni une mise à jour déjà effectuée. Si la livraison compte, vérifie aussi le service destinataire. Les effets restent liés à l’exécution jusqu’à son retrait par suppression ou conservation ; ils ne constituent pas une archive permanente distincte. Supprimer l’automatisation conserve ses exécutions : la page d’une exécution s’ouvre toujours, marquée de la date de suppression et dessinée à partir de sa propre trace, jusqu’à ce que la conservation la retire.

## Comprendre les reprises et nouvelles tentatives

Le moteur enregistre les nœuds terminés comme points de reprise et continue après eux. Une exécution inachevée dont la continuation a été perdue peut être reprise après un délai. Une nouvelle exécution distincte possède ses propres points de reprise et peut répéter des écritures. Relancer n’est donc pas reprendre l’exécution existante.

Un échec d’agent admissible permet jusqu’à trois nouvelles tentatives automatiques après la première. Les points de reprise précédents restent acquis et l’en-tête affiche le compteur. Une tentative qui travaille au moins quinze minutes renouvelle ce budget de tentatives. Un pool d’abonnements peut choisir un autre compte pour la suivante. Si un courtier d’abonnement a actualisé le compte pendant que l’étape travaillait et que le fournisseur refuse l’ancien jeton, la nouvelle tentative reprend avec un nouveau jeton sans consommer l’une des trois tentatives ; une troisième interruption de ce type d’affilée compte comme n’importe quel autre échec. Si l’étape n’a pas pu démarrer parce que tous les comptes du pool étaient en pause après avoir atteint une limite de requêtes, la nouvelle tentative démarre dès que le premier compte redevient disponible, au plus tard une minute après, et poursuit la conversation que la tentative refusée devait reprendre. Cette attente consomme l’une des trois tentatives, sauf si la tentative refusée relançait elle-même un échec dû à une limite de requêtes. Si la tentative échouée avait annoncé sa conversation, la nouvelle tentative reprend cette conversation sur l’espace de travail conservé : l’agent continue là où la coupure l’a surpris au lieu de raisonner depuis le début ; une tentative morte avant de l’annoncer, ou dont la session sandbox a disparu, repart de zéro. Une étape Gemini CLI repart toujours de zéro, parce que cet environnement ne peut pas reprendre une conversation dans laquelle il a appelé un outil ; [Choisir un environnement d’agent](https://docs.tale.dev/fr/platform/agents/harnesses) explique cette exception.

Une étape d’agent échoue aussi quand son modèle ne renvoie rien du tout : ni texte, ni appel d’outil, ni token généré. Un serveur de modèle peut répondre ainsi s’il tombe en panne en pleine réponse. L’exécution indique alors, en anglais, « The model returned an empty answer, so the agent did nothing this turn. » Cet échec bénéficie lui aussi de ces nouvelles tentatives. Si le modèle a seulement utilisé des outils, ou signalé des tokens générés sans texte visible, par exemple pour son raisonnement, il a bien répondu et l’étape n’échoue pas pour cette raison.

L’épuisement de la fenêtre totale d’exécution, l’expiration d’une question ou un refus lié au budget ne bénéficie pas de ces reprises. Chaque tentative consomme ses propres ressources ; les coûts antérieurs ne disparaissent pas. Si recommencer ne peut pas résoudre la cause, arrête l’exécution et corrige la dépendance avant de relancer.

## Arrêter ou corriger le workflow

Choisis **Arrêter l’exécution** pour annuler une exécution inachevée, puis confirme. Le moteur empêche la poursuite aux limites de ses étapes ; il n’annule pas les effets déjà produits. Si l’exécution se termine avant de recevoir l’annulation, elle conserve son résultat final.

Pour corriger le document, reviens à l’éditeur, modifie l’entrée ou le nœud concerné et enregistre une version avec un message utile. Fais un essai avec des données représentatives et lis les valeurs et la sortie, au-delà du statut de réussite. Mets la version vérifiée en service. Les prochains démarrages planifiés ou par webhook l’utiliseront ; l’ancien échec reste le journal de l’ancienne version.

Si aucune exécution n’a démarré, examine le [déclencheur](https://docs.tale.dev/fr/platform/automations/triggers). Sa désactivation, une mise en service manquante ou des données refusées peuvent expliquer l’absence totale d’exécution.

# Démarrer les automatisations automatiquement
Source: https://docs.tale.dev/fr/platform/automations/triggers

La section **Déclencheur** de l’onglet **Général** d’une automatisation définit quand elle démarre seule. Chaque déclencheur utilise la version en service en mode réel. Avant de l’activer, teste le workflow avec les données qu’il recevra et vérifie que ses actions externes sont prêtes.

<Frame caption="L’onglet Général d’un paquet fourni : son déclencheur de planification est activé, mais il ne lance rien tant qu’aucune version n’est en service.">

![L’onglet Général de Triage the Gmail inbox avec un déclencheur Schedule activé, l’expression cron 0 */6 * * * décrite comme toutes les six heures et sans démarrage tant qu’aucune version n’est déployée, le fuseau horaire UTC et, en dessous, un sélecteur de projets vide.](https://docs.tale.dev/images/platform/automation-general-trigger.webp)

</Frame>

## Choisir le mode de démarrage

| Type de déclencheur | Usage | Données transmises à l’exécution |
| --- | --- | --- |
| **Planification** | Travail périodique à une heure locale ou à intervalles réguliers. | `{ trigger: "schedule", firedAt: <epoch ms> }` |
| **Webhook** | Réception d’une livraison d’un autre système. | `{ trigger: "webhook", payload: … }` |
| **Événement de la plateforme** | Un événement nommé dans l’organisation. | `{ trigger: "event", event: "…", payload: … }` |

Une automatisation possède un seul déclencheur configuré à la fois. Changer son type remplace la liaison précédente. Remplacer un webhook révoque immédiatement son URL ; en recréer un plus tard ne restitue pas ces identifiants.

Un client API ou MCP peut aussi démarrer sans déclencheur configuré. Sa clé API et ses droits sur le projet autorisent l’appel, et il fournit directement les données du workflow. Consulte la [référence API](https://docs.tale.dev/fr/develop/api-reference).

## Définir un horaire

<Steps>

<Step title="Ouvrir les paramètres du déclencheur">

Ouvre l’automatisation, puis son onglet **Général**. Sans liaison, la section **Déclencheur** indique que l’automatisation ne s’exécute que lancée à la main ou via l’API ; choisis **Ajouter un déclencheur**, puis **Planification** sous **Type de déclencheur**. Un nouveau déclencheur n’est pas **Actif** au départ — laisse-le désactivé tant que le workflow ne doit pas démarrer seul.

</Step>

<Step title="Saisir l’horaire">

Renseigne **Cron** et le **Fuseau horaire**. Les cinq champs représentent minute, heure, jour du mois, mois et jour de la semaine. Choisis un fuseau IANA comme `Europe/Zurich` pour suivre les heures locales. Sans indication, UTC s’applique.

</Step>

<Step title="Vérifier et enregistrer">

Examine la prochaine occurrence affichée pour l’expression valide : c’est la minute à laquelle la planification démarrera vraiment, changement d’heure compris. Clique ensuite sur **Enregistrer** à côté des onglets. Vérifie que la version en service accepte les données de planification du tableau. Active le déclencheur prêt à fonctionner avec **Actif** et enregistre à nouveau. Retrouve le prochain démarrage sous **Exécutions**.

</Step>

</Steps>

```text
*/15 * * * *     toutes les quinze minutes
0 9 * * 1-5      à 09:00 du lundi au vendredi
0 6 1 * *        à 06:00 le premier du mois
30 8 1 * 1       à 08:30 le premier du mois et chaque lundi
```

Les champs acceptent `*`, nombres, plages, pas et listes séparées par des virgules. 0 et 7 désignent le dimanche. Si le jour du mois et celui de la semaine sont tous deux limités, l’un ou l’autre suffit. Le dernier exemple tourne donc chaque lundi ainsi que le premier de chaque mois.

L’heure locale suit les changements saisonniers du fuseau. Un horaire zurichois à 09:00 reste à 09:00 sur place. La résolution est d’une minute. Les occurrences manquées pendant une panne ne sont pas rejouées ; le travail reprend à la suivante. Une date de calendrier impossible est refusée à l’enregistrement.

## Recevoir un webhook

Choisis **Webhook**, puis enregistre pour générer les identifiants. Copie l’URL complète dès son apparition : le jeton n’est montré qu’une fois et seul son hash est conservé. La section fournit une URL d’organisation et un modèle d’URL de projet. Utilise cette dernière pour un projet actif auquel l’automatisation est liée. Une automatisation liée à des projets ne peut pas utiliser l’URL réservée aux exécutions sans projet.

Envoie une petite charge utile à l’URL. Le JSON devient `payload` à l’intérieur de l’entrée, et non directement ses champs de premier niveau. Les autres contenus passent comme texte. La limite est de 256 KiB ; téléverse les grands documents séparément. Une requête acceptée renvoie l’identifiant de l’exécution sans attendre sa fin.

Ainsi, le corps `{ "invoiceId": "inv-1" }` parvient au workflow sous cette forme :

```json
{
  "trigger": "webhook",
  "payload": { "invoiceId": "inv-1" }
}
```

Fournis un identifiant de livraison, par exemple `Idempotency-Key` ou un en-tête pris en charge de l’expéditeur. Le même identifiant renvoie l’exécution initiale pendant 24 heures. Sans identifiant, un corps identique envoyé à la même URL dans les deux minutes est considéré comme un doublon. Utilise des identifiants distincts si des contenus identiques correspondent à des travaux séparés. [Webhooks](https://docs.tale.dev/fr/develop/webhooks) détaille en-têtes, chemins de projet, erreurs et réponses.

<Warning>

L’URL autorise le démarrage. Protège-la comme un identifiant et ne la transmets qu’au système expéditeur. **Renouveler le token** produit un remplacement et invalide l’ancienne URL. Retirer ou remplacer le déclencheur la révoque également. Mets l’expéditeur à jour après un renouvellement.

</Warning>

## Réagir à un événement de la plateforme

Choisis **Événement de la plateforme**, puis le **Nom de l’événement**. Enregistre et active le déclencheur quand il est prêt. Le schéma du workflow doit accepter l’enveloppe `trigger`, `event` et `payload` du tableau. Les événements produits par une exécution d’automatisation ne déclenchent pas d’autres départs : le workflow ne peut ainsi se relancer sans fin par ses propres changements.

Un workflow qui exige des champs de premier niveau comme `owner` et `repo` n’accepte pas automatiquement les métadonnées d’un horaire ou le corps enveloppé d’un webhook. Adapte son schéma et ses références, ou utilise un démarrage API qui fournit ces champs. Les réglages du déclencheur ne permettent pas de définir des données d’entrée arbitraires enregistrées.

## Démarrer un agent de projet selon une planification

Une planification peut mettre au travail l’un des agents existants d’un projet : pour une tâche permanente dont l’agent rend compte à chaque occurrence, ou pour un travail récurrent que tu lancerais sinon à la main. Installe l’automatisation dans le projet de la tâche, ajoute une étape `task.start_agent` qui désigne la tâche, puis donne une planification à l’automatisation. Chaque occurrence démarre l’agent assigné à la tâche, ou assigne d’abord la tâche à l’agent que désigne `agentId`, qui doit appartenir au même projet. `feedback` est le message que l’exécution traite en premier, par exemple une mention de l’occurrence pour laquelle elle s’exécute :

```yaml
nodes:
  - id: start
    type: task.start_agent
    input:
      taskId: <ID de la tâche>
      moveToInProgress: false
      feedback: 'Scheduled occurrence {{ input.firedAt }}.'
```

L’étape renvoie l’exécution qu’elle a démarrée, et la chronologie de la tâche affiche cette exécution comme **automatisation**, avec un lien vers l’exécution de l’automatisation. Quand elle ne démarre rien, l’étape réussit tout de même et en donne la raison, si bien que l’occurrence est consignée au lieu d’être mise en file d’attente :

| Réponse | Signification |
| --- | --- |
| `started: true` | L’exécution de l’agent a démarré ; `runId` l’identifie. |
| `already_running` | L’exécution précédente de la tâche travaille encore et prend le travail en charge. Rien de nouveau ne démarre, et l’occurrence n’attend pas derrière elle. |
| `in_review` | Avec `moveToInProgress: false`, la carte attend son relecteur enregistré, une personne ou un agent. Rien n’est assigné ni démarré, et la revue conserve ce destinataire. |
| `closed` | Avec `moveToInProgress: false`, la carte est **Terminé** ou **Annulé** (`taskStatus`). Rien n’est assigné ni démarré. |
| `agent_busy` | L’agent travaille sur une autre tâche (`busyTaskId`). Un agent ne traite qu’une tâche à la fois dans son espace de travail. |
| `blocked` | Une tâche dont celle-ci dépend est encore ouverte (`blockedBy`). |
| `paused` | La tâche a déjà reçu trois démarrages par des automatisations et des agents au cours de la dernière heure, les relances automatiques ordinaires comprises. Une attente du courtier immédiatement après un échec HTTP 429 du même agent n’ajoute aucun démarrage ; les attentes consécutives restent comptées. `retryAfter` indique quand le compteur horaire autorise un autre démarrage ; les autres vérifications restent applicables. |

Une exécution lancée par une planification n’agit pour le compte de personne. Elle travaille avec les instructions, les secrets et les outils configurés de l’agent, et ses dépenses comptent comme des dépenses d’automatisation dans les limites de l’organisation. Les actions de connecteur qu’elle demande à la plateforme d’exécuter ne se font au nom de personne et sont donc refusées. Elle ne garde cette autorité que tant que la planification peut agir dans le projet : désactiver la planification, la retirer ou désinstaller l’automatisation du projet empêche le démarrage suivant, fait échouer une exécution qui n’a pas encore commencé et retire à une exécution en cours les outils de son espace de travail. Si une personne lance elle-même l’automatisation, l’exécution agit plutôt pour le compte de cette personne, tant qu’elle peut modifier le projet. Une exécution lancée par un webhook ou un événement de la plateforme ne peut pas démarrer d’agents, et une automatisation qui n’est pas installée dans le projet de la tâche n’a pas accès à ses agents.

`moveToInProgress` décide de ce qui arrive à la carte. Par défaut, la carte passe à **En cours** et le résultat attend à **En revue** son [relecteur configuré](https://docs.tale.dev/fr/platform/projects/tasks#review-default), comme après **Démarrer l'agent** ; une revue encore en attente sur le travail précédent est retirée, jamais validée. Avec `false`, la carte reste où elle est et l’exécution ne demande aucune revue, ce qui convient à une tâche permanente dans **À faire**. L’exécution garde ce choix jusqu’au bout : quand elle se termine, son rapport et ses fichiers arrivent comme d’habitude, et la carte n’est ni déplacée ni envoyée en revue, même si quelqu’un l’a entre-temps passée à **En cours**. Ce démarrage ne s’exécute que sous un travail ouvert (**Backlog**, **À faire** ou **En cours**) : une carte qui attend à **En revue** répond `in_review`, une carte close `closed`, si bien que la carte ne présente jamais un travail antérieur au jugement, ou comme terminé, pendant qu’un nouveau travail s’exécute dessous.

Une nouvelle tentative automatique est possible si le type d’échec le permet, tant que la tâche garde son statut et son responsable d’origine et qu’aucune nouvelle décision de statut, d’affectation, d’archivage ou de revue n’est intervenue. Modifier une valeur puis la rétablir met aussi fin à cette tentative ; les commentaires ne l’arrêtent pas. Les limites de tentatives, les autorisations de la planification et les vérifications de l’espace de travail restent applicables. Une occurrence ultérieure peut lancer un nouveau travail lorsque les conditions sont réunies.

### Importer chaque issue selon une planification

Un import d’issues lit au plus un lot par exécution, jusqu’à 500 issues, et indique où commence le lot suivant. Une personne le poursuit avec **Poursuivre l'import** ; une planification conserve plutôt la position entre ses occurrences, si bien que chaque occurrence importe un lot à partir de l’endroit où la précédente s’est arrêtée, jusqu’à ce que toutes les issues ouvertes aient été lues, et l’occurrence suivante commence la passe d’après. Lis la position avec `task.get_import_cursor`, transmets-la à l’import et enregistre son `nextCursor` avec `task.save_import_cursor` :

```yaml
nodes:
  - id: position
    type: task.get_import_cursor
    onError: continue
    input: { projectId: <the project's ID>, externalSystem: github, source: owner/repo }
  - id: issues
    type: subautomation
    automation: github-import-issues
    onError: continue
    input:
      projectId: <the project's ID>
      owner: owner
      repo: repo
      limit: 500
      cursor: '{{ nodes.position.output.cursor }}'
  - id: progress
    type: task.save_import_cursor
    onError: continue
    input:
      projectId: <the project's ID>
      externalSystem: github
      source: owner/repo
      revision: '{{ nodes.position.output.revision }}'
      next: '{{ nodes.issues.output.nextCursor ?? "" }}'
```

`source` est le nom que tu donnes à la liste ; les automatisations qui nomment la même source partagent une même passe. La lecture indique aussi `revision`, le jeton de comparaison de la position, et l’enregistrement le renvoie : la position n’avance que tant qu’elle en est encore à cette révision. Chaque lot enregistré, chaque fin de passe et chaque redémarrage fait passer à une nouvelle révision, et aucune révision ne se répète, même quand le texte du curseur se répète. Un import qui échoue n’enregistre rien, si bien que l’occurrence suivante reprend le même lot. Un enregistrement fait avec une révision antérieure est refusé (`conflict`) et n’écrit rien, qu’il vienne d’une exécution qui se chevauche, d’une exécution retardée au-delà de la fin de sa passe ou d’une exécution qui détient encore une position antérieure à un redémarrage. Après trois lectures d’une même position sans enregistrement, la lecture suivante recommence la passe (`restarted`) au lieu de réessayer une position que la source refuse sans cesse, par exemple après le renommage du dépôt. L’enregistrement indique `batch` et `drained`, qu’un reçu peut rapporter. Chaque exécution rafraîchit aussi jusqu’à 500 issues importées auparavant, en commençant par celles vérifiées le moins récemment, si bien qu’une grande collection est rafraîchie sur plusieurs occurrences.

## Comprendre l’absence de démarrage

Vérifie d’abord **Actif**, la version en service et le dernier déclenchement. Lis ensuite le motif éventuellement enregistré :

| Motif ou symptôme | Vérification |
| --- | --- |
| `not_deployed` | Mets une version testée en service. Un brouillon enregistré ne suffit pas. |
| `start_refused` | Compare le schéma de la version active à l’enveloppe du déclencheur et corrige l’erreur de validation ou de démarrage indiquée. |
| `unusable_cron` | Corrige l’expression ou le fuseau, puis enregistre. Les autres horaires continuent pendant que celui-ci est ignoré. |
| `paused_after_failures` | La planification s’est désactivée d’elle-même après des échecs répétés. Voir [Quand une planification se met en pause](https://docs.tale.dev/fr/platform/automations/triggers#quand-une-planification-se-met-en-pause). |
| Identifiant du webhook refusé | Vérifie l’URL actuelle et l’activation. Les jetons inconnus et désactivés reçoivent volontairement le même refus. |
| Exécution présente, mais inachevée | Ouvre les [journaux d’exécution](https://docs.tale.dev/fr/platform/automations/execution-logs). Le démarrage a réussi ; le problème se trouve dans le workflow. |

La date du dernier déclenchement avance lorsqu’une exécution démarre réellement. Un déclencheur arrivé à échéance mais incapable de démarrer enregistre plutôt un départ ignoré. Tu peux ainsi le distinguer d’un workflow démarré puis tombé en échec.

## Quand une planification se met en pause

Une planification dont les exécutions échouent de la même façon à chaque occurrence continuerait sinon d’échouer indéfiniment. Tale compte donc les exécutions lancées par un déclencheur qui échouent sur une erreur qu’une nouvelle tentative ne corrigera pas : le code de l’automatisation elle-même (`node_error`), un connecteur (`connector_error`), une réponse du modèle qui ne respecte pas son schéma (`llm_output_invalid`) ou le fournisseur de modèles de l’organisation (`auth_error`, `missing_api_key`, `credit_exhausted`, `model_not_found`). Une exécution réussie remet le compteur à zéro. Les autres échecs, comme une limite de débit ou un fournisseur injoignable, ne comptent pas et ne remettent pas non plus le compteur à zéro. Une planification qui s’est déjà mise en pause d’elle-même fait exception : elle garde le compteur qui a provoqué la pause, même si une exécution encore en cours à ce moment-là réussit ensuite, et seul l’enregistrement du déclencheur le remet à zéro.

Après cinq échecs de ce type d’affilée, la planification désactive **Actif** et enregistre `paused_after_failures`. La section **Déclencheur** affiche alors la pause, le code et l’heure du dernier échec, ainsi que **Voir l’exécution**, qui ouvre cette exécution. Tant que des exécutions échouent alors que la planification est encore active, la section indique combien ont échoué d’affilée. Les Propriétaires et Admins reçoivent une notification par la cloche, et aussi par e-mail si l’organisation dispose d’une boîte mail connectée ; le journal d’audit enregistre la pause. Ils peuvent désactiver ces avis avec **Alertes d'automatisation** dans **Paramètres > Notifications**.

Ouvre l’exécution en échec pour lire l’erreur, puis corrige l’automatisation ou sa connexion. Active ensuite **Actif** et enregistre. Chaque enregistrement du déclencheur repart d’un compteur à zéro, qu’il réactive la planification ou la laisse désactivée, et marque les avis comme lus.

Les déclencheurs webhook et événement de la plateforme comptent les échecs de la même façon, mais ne sont jamais mis en pause. Leurs exécutions portent une livraison ou un événement, qu’un déclencheur en pause perdrait.

## Suspendre ou remplacer le déclencheur

Désactive **Actif** et enregistre pour suspendre les départs en conservant configuration et historique. Réactive-le pour reprendre. **Retirer le déclencheur** supprime la liaison et rend l’URL d’un webhook inutilisable.

Le déclencheur appartient au nom de l’automatisation, pas à une version. Un déploiement ou un retour à une version précédente conserve l’horaire ou l’URL et change la version utilisée par les prochains départs. Modifier le déclencheur ne crée pas de version du workflow. Vérifie donc aussi ses paramètres lorsqu’un déploiement change les données attendues.

# Comparer les modèles dans l’Arène
Source: https://docs.tale.dev/fr/platform/chat/arena-mode

Le **Mode Arène** compare deux modèles à partir du même message. Les deux côtés utilisent l’assistant de chat et le même contexte de départ. Choisis une question dont tu peux vérifier la réponse : une préférence ne suffit pas à établir l’exactitude.

## Lancer une comparaison

Ouvre un chat privé, puis le menu **+** de la zone de saisie et choisis **Mode Arène**. Un chat partagé ne peut pas entrer dans ce mode. Choisis les modèles sous **Modèle A** et **Modèle B**, puis envoie ton message. Tu peux sélectionner deux fois le même modèle pour observer les variations, ou deux modèles différents pour comparer leur comportement.

Pour commencer, fournis une source courte et une demande précise, par exemple : « Liste les trois décisions de ces notes de réunion et cite la phrase qui justifie chacune. » Conserve la même source, les mêmes instructions et le même format demandé des deux côtés.

<Frame caption="Le même prompt traité par deux modèles, avec la rangée de verdict en dessous.">

![Le Mode Arène avec un prompt de checklist de lancement traité dans deux colonnes — à gauche, Claude Haiku 4.5 rend une liste numérotée de cinq étapes, à droite, Claude Sonnet 4.6 regroupe le même travail sous des titres et ajoute les risques à signaler — au-dessus des boutons de verdict A est meilleur, B est meilleur, Égalité et Les deux sont mauvais.](https://docs.tale.dev/images/platform/chat-arena-split.webp)

</Frame>

Chaque réponse apparaît dans sa colonne. Le message est admis pour les deux colonnes ensemble : une limite d’utilisation qui l’arrête l’arrête pour les deux côtés, jamais pour une seule colonne. Attends qu’elles soient toutes deux terminées avant de choisir un verdict ; les boutons restent indisponibles tant qu’un côté répond. Le délai fait aussi partie du résultat. Si un côté échoue, sa colonne affiche l’erreur et le tour ne peut pas être jugé : les quatre boutons de verdict restent indisponibles tant que les deux colonnes ne contiennent pas une réponse terminée, tandis que **Quitter sans verdict** reste disponible. Examine l’erreur avant d’en tirer un jugement sur la qualité.

## Évaluer les réponses

Vérifie les faits dans la source, le respect des instructions, les informations essentielles manquantes et les corrections nécessaires avant utilisation. Une réponse plus longue ou plus assurée n’est pas forcément meilleure.

| Verdict | Quand le choisir | Le chat continue avec |
| --- | --- | --- |
| **A est meilleur** | A est plus utile ou plus exact. | La colonne A. |
| **B est meilleur** | B est plus utile ou plus exact. | La colonne B, et la zone de saisie passe au modèle B. |
| **Égalité** | Les deux répondent aussi bien à la demande. | La colonne A. |
| **Les deux sont mauvais** | Aucune réponse n’est acceptable. | La colonne A. |
| **Quitter sans verdict** | Tu ne souhaites pas noter ce résultat. | La colonne A, sans verdict. |

Chaque choix termine la comparaison à deux colonnes. Le message suivant est envoyé dans le chat conservé. Réactive l’Arène pour comparer à nouveau : une égalité ne maintient pas les deux colonnes actives.

La réponse de l’autre colonne est écartée et rejoint la [corbeille](https://docs.tale.dev/fr/platform/admin/governance/trash) de l’organisation, où un administrateur peut la restaurer comme chat à part entière jusqu’à la fin du délai de grâce de rétention. Elle n’apparaît plus dans ta liste de chats ni dans la recherche, et un lien vers elle indique que le chat n’est pas disponible.

## Retrouver le feedback enregistré

Lorsque les deux modèles ont répondu, le verdict alimente l’[analyse des retours](https://docs.tale.dev/fr/platform/admin/governance/feedback-analytics) de l’organisation. Les administrateurs peuvent y examiner les verdicts de l’Arène et les comparaisons entre modèles. Un tour où une seule colonne a répondu n’est jamais enregistré : le verdict est refusé, si bien que l’analyse ne contient que des comparaisons de deux réponses terminées. Quitter sans verdict n’ajoute aucune note.

Essaie plusieurs questions représentatives avant de conclure sur un modèle. Un bon résumé court ne prédit pas forcément ses résultats sur du code ou de longs documents. Les préférences de l’organisation incluent aussi les tâches des autres personnes.

## Débloquer une comparaison

Si un modèle manque, consulte le [catalogue des modèles](https://docs.tale.dev/fr/platform/models) pour vérifier son fournisseur et les règles d’accès. Si les boutons de verdict restent indisponibles, les deux générations doivent d’abord se terminer, ou vérifie que les deux colonnes affichent une réponse terminée : un côté qui a échoué ou n’a jamais répondu ne laisse rien à comparer. Quitte alors sans verdict, corrige la cause et renvoie le message. Un échec peut venir des identifiants, de la disponibilité ou d’une règle : utilise la cause affichée pour décider quoi corriger avant de réessayer.

# Poser des questions sur des fichiers et des images
Source: https://docs.tale.dev/fr/platform/chat/attachments

Joins un fichier lorsqu’il sert à la conversation en cours. L’assistant reçoit les images, consulte le texte des documents compatibles et lit les transcriptions des enregistrements. Pour réutiliser des fichiers dans plusieurs chats, place-les dans un [projet](https://docs.tale.dev/fr/platform/projects/manage-files) ou dans la [bibliothèque de connaissances](https://docs.tale.dev/fr/platform/knowledge/documents).

## Ajouter une pièce jointe

Ouvre le menu `+` près du champ de message et choisis **Ajouter photos et fichiers**. Tu peux aussi déposer des fichiers sur le champ ou y coller une capture d’écran. Un message peut contenir jusqu’à dix fichiers.

Les images apparaissent en miniature. Les autres fichiers apparaissent sous forme de pastilles avec leur nom et l’état du traitement. Vérifie les noms avant l’envoi. Retire une pièce jointe préparée avec sa commande de suppression si elle ne doit pas accompagner le message.

Après l’envoi, **Modifier le message** change le texte dans une nouvelle version de la conversation et conserve les pièces jointes d’origine. Tu n’as pas besoin de les téléverser à nouveau.

<Frame caption="Un document préparé affiche son nom, puis sa taille une fois traité et prêt à partir avec ta question.">

![Le champ de saisie affiche un document joint au-dessus du message, avec sa taille et une commande pour le retirer.](https://docs.tale.dev/images/platform/chat-document-attachment.webp)

</Frame>

Précise ce que l’assistant doit chercher, par exemple : « Lis le compte rendu et liste les décisions, leurs responsables et les échéances manquantes. » Joindre un fichier seul ne suffit pas à expliquer le résultat attendu.

Quand tu essaies de joindre de l’audio ou de la vidéo, Tale vérifie si l’organisation dispose d’un modèle de transcription disponible. Si cette vérification empêche l’import, une boîte de dialogue explique le problème et propose les actions auxquelles tu as accès. Ces fichiers sont refusés avant leur transfert ; les autres fichiers compatibles de la même sélection peuvent toujours être importés. Ferme la boîte de dialogue pour continuer à écrire, ouvre le réglage proposé si tu y as accès, ou demande à un admin de vérifier les [Modèles](https://docs.tale.dev/fr/platform/admin/governance/content-models).

## Comprendre ce que reçoit le modèle

| Pièce jointe | Contenu utilisé | Vérification |
| --- | --- | --- |
| Image ou capture collée | L’image elle-même, si le modèle sait lire les images. | Choisis un modèle compatible et vérifie que le texte est lisible. |
| PDF, document Office récent ou fichier texte compatible | Texte accessible par les outils de consultation de l’assistant. | Attends le traitement et vérifie qu’une étape de lecture apparaît dans la réponse. |
| Fichier audio ou vidéo | Une transcription en texte. | Un admin doit configurer la transcription. Compare les noms, nombres et termes spécialisés avec l’enregistrement. |
| Ancien fichier Office sans extracteur de texte | Le nom du fichier, sans texte consultable. | Enregistre-le en `.docx`, `.xlsx` ou `.pptx` et joins cette copie. |

Accepter un fichier à l’import et en extraire le texte sont deux opérations distinctes. La présence d’un fichier dans le chat ne signifie pas nécessairement que l’assistant peut en lire le contenu.

## Envoyer pendant le traitement

Si des documents ou enregistrements sont encore en traitement au moment de l’envoi, Tale met le message en attente, puis l’envoie lorsqu’ils sont prêts. Le message en attente apparaît au-dessus du champ. Annule-le à cet endroit pour modifier la question ; son texte revient dans le champ.

Colle un lien vidéo compatible dans le champ du message pour lancer la création d’une pièce jointe. Une URL saisie au clavier reste du texte ordinaire. Tale récupère d’abord les sous-titres et transcrit l’audio si aucun n’est disponible, puis fournit le texte à l’assistant. Si les sous-titres montrent deux personnes qui parlent au même moment, la transcription conserve les paroles de chacune. Tu peux toujours coller un lien sans modèle de transcription, car les sous-titres utilisables n’en ont pas besoin. Si tu colles de nouveau un lien dans un chat existant avant l’envoi, ce chat réutilise la pièce jointe qu’il a déjà pour ce lien, même si tu l’as collé entre-temps dans un autre chat ; chaque chat garde la sienne. Une pièce jointe en échec, retirée ou ajoutée il y a plus d’un jour n’est pas réutilisée. Si ce lien échoue, réessaie ou retire-le avant d’envoyer. Si Tale ne parvient pas à retirer un lien, sa pastille réapparaît et un message en donne la raison ; le lien reste joint tant que le retrait n’a pas abouti.

Un changement de modèle s’applique aux nouvelles transcriptions ; les pièces jointes déjà traitées conservent leur texte. Importer à nouveau les mêmes octets réutilise le travail terminé pour la même cible de transcription, mais relance la transcription si le fournisseur ou le modèle cible diffère.

## Choisir le bon emplacement

Les pièces jointes appartiennent à cette conversation. Elles ne rejoignent pas automatiquement la bibliothèque de l’organisation et ne deviennent pas accessibles dans un autre chat. Changer de conversation retire les pièces jointes préparées : vérifie les pastilles après un changement de chat.

Une réponse régénérée utilise les pièces jointes enregistrées avec le message d’origine. Pour poser une question sur une autre version, envoie le nouveau fichier et indique laquelle l’assistant doit utiliser.

<Tip>

Pour des questions récurrentes sur un brief ou une politique, ajoute le fichier une fois dans le projet approprié. Démarre les chats suivants dans ce projet au lieu d’importer une copie à chaque fois.

</Tip>

## Résoudre un problème de pièce jointe

| Symptôme | Action |
| --- | --- |
| Le modèle choisi ne peut pas lire l’image | Choisis un modèle compatible. Auto tient compte des modèles capables de lire les images ; s’il n’y en a aucun, demande à un admin d’en configurer un. |
| Le traitement échoue | Réessaie. Si un petit fichier compatible échoue aussi, demande à un admin de vérifier le stockage, l’indexation ou la transcription selon l’erreur. |
| L’assistant connaît le nom, mais pas le contenu | Vérifie le format et l’état du traitement. Convertis les anciens fichiers dans un format récent compatible. |
| La réponse invente des détails d’un enregistrement | Compare la transcription à l’enregistrement et fournis le passage corrigé avant de continuer. |
| Un message reste en attente | Vérifie chaque pièce jointe, y compris les liens vidéo. Retire les éléments en échec ou relance leur traitement. |
| Un lien vidéo retiré réapparaît | Tale n’a pas pu le retirer, et le message affiché en donne la raison. Le lien reste joint. Retire-le de nouveau une fois la cause réglée, par exemple quand ta connexion est rétablie ou après t’être reconnecté. |

Reviens à [Poser des questions dans le chat](https://docs.tale.dev/fr/platform/chat/basics) pour vérifier les sources et poursuivre l’échange.

# Poser des questions dans le chat
Source: https://docs.tale.dev/fr/platform/chat/basics

Utilise le chat pour poser une question, comprendre un document ou rechercher une information dans Tale. L’assistant peut parcourir les connaissances accessibles et lire des pages publiques. Commence par une question précise, puis affine la réponse avec des messages de suivi.

<Frame caption="Le chat conserve ta question, les étapes de l’assistant et sa réponse dans le même échange.">

![Un chat sur les retours d’onboarding affiche la question et une réponse qui présente trois thèmes dans un tableau.](https://docs.tale.dev/images/platform/chat-thread-reply.webp)

</Frame>

## Envoyer un premier message

Ouvre **Accueil**. Sur ordinateur, le chat que tu as lu en dernier se rouvre, s’il y en a un. Pour aborder un nouveau sujet, choisis **Nouveau chat** en haut de la liste d’**Accueil** ou, sur ordinateur, sélectionne à nouveau **Accueil** alors que cette section est active. Écris dans le champ de message. Appuie sur **Entrée** pour envoyer ou sur **Maj+Entrée** pour aller à la ligne. Une suggestion de départ joue le même rôle que ta propre question : précise la source, le sujet et le type de réponse attendu.

Par exemple : « Retrouve les retours d’onboarding et résume les trois problèmes les plus fréquents. Cite les documents et sépare les problèmes signalés de tes suggestions. »

Si ton organisation a activé un avis de confidentialité, il s’affiche sous le champ de message pour te rappeler ce qu’il ne faut pas partager dans le chat.

Pendant la génération, la commande d’envoi devient une commande d’arrêt. L’arrêter conserve le texte déjà reçu, même s’il se termine au milieu d’une phrase. Pose une question de suivi pour clarifier la demande ou obtenir un détail manquant.

## Choisir un modèle lorsque c’est utile

Le sélecteur démarre sur **Auto** lorsque plusieurs modèles utilisables sont disponibles. Auto choisit un modèle pour chaque message parmi ceux de ton organisation. Les règles de l’organisation peuvent définir un choix par défaut ou restreindre les modèles autorisés. Les détails sous la réponse indiquent celui qui a effectivement répondu.

Choisis un modèle précis pour comparer des réponses dans les mêmes conditions ou lorsque tu sais lequel convient au travail. Il reste sélectionné jusqu’à ce que tu changes ce choix, y compris le fournisseur qui sert le modèle lorsque deux fournisseurs proposent le même. S’il permet de régler l’effort de raisonnement, le sélecteur propose aussi ce réglage. Un effort plus élevé peut prendre plus de temps ; il ne remplace pas la vérification du résultat.

<Frame caption="Le sélecteur de modèle se trouve à côté du menu des pièces jointes et des commandes vocales.">

![Le champ de message affiche le menu plus, le modèle Auto, un microphone et le bouton d’envoi.](https://docs.tale.dev/images/platform/chat-composer.webp)

</Frame>

Si aucun modèle n’est disponible, demande à un admin de vérifier les identifiants actifs des fournisseurs et les règles d’accès. Le chat ne propose que les modèles servis par des identifiants par clé API ou variable d’environnement : un abonnement ne fonctionne que dans les tâches et les automatisations, et la liste des modèles nomme les abonnements qu’elle laisse de côté. La page [Modèles](https://docs.tale.dev/fr/platform/models) explique la composition du catalogue.

## Fournir les bonnes sources

Choisis l’emplacement du chat avant de poser des questions sur des fichiers :

| Emplacement | Fichiers consultables par l’assistant |
| --- | --- |
| Chat général de l’organisation | Documents accessibles de la bibliothèque et pièces jointes propres au chat. |
| Chat dans un projet | Fichiers de ce projet, documents accessibles de la bibliothèque et pièces jointes du chat. |
| Lien vers un chat partagé | Instantané en lecture seule, sans possibilité d’y poser une autre question. |

Le chat du projet reçoit aussi ses instructions permanentes. Tale applique les droits sur les fichiers : demander de lire un autre projet n’accorde pas cet accès. Les fichiers dans la corbeille ou dont la conservation a expiré ne sont pas consultables.

Utilise les [pièces jointes](https://docs.tale.dev/fr/platform/chat/attachments) pour cette conversation, les [fichiers du projet](https://docs.tale.dev/fr/platform/projects/manage-files) pour un travail récurrent et les [connaissances](https://docs.tale.dev/fr/platform/knowledge/overview) pour les références partagées. L’assistant récupère les contenus selon le besoin ; importer un document ne signifie pas que chaque réponse l’a utilisé.

Les questions sur Tale lui-même ne demandent aucun envoi : l’assistant consulte la documentation publique sur docs.tale.dev avant d’expliquer un écran ou un réglage. Si le serveur ne peut pas joindre docs.tale.dev, par exemple sur une installation auto-hébergée sans accès à Internet, le déroulé affiche une lecture en échec et la réponse ne s’appuie pas sur la documentation. La documentation décrit la dernière version ; l’assistant signale quand ton espace de travail peut en différer.

## Vérifier ce que l’assistant a consulté

Au-dessus de la réponse, le déroulé montre les recherches et les lectures. Une étape en échec indique ce qui n’a pas pu être lu et aide à expliquer une réponse incomplète. Déplie la partie consacrée au raisonnement lorsqu’elle existe, mais vérifie les faits dans les sources plutôt que de te fier à la qualité de cette explication.

La zone **Sources** sous la réponse liste les documents et pages chargés. Ouvre une source et vérifie qu’elle appuie l’affirmation concernée. Une citation indique le contenu utilisé, sans garantir toutes les conclusions. Une réponse sans étape de consultation peut reposer sur les connaissances préalables du modèle.

L’assistant peut rechercher des documents, entrées de connaissances, sites, contacts, produits, tâches accessibles et conversations de la boîte de réception que tu peux voir, y compris le texte des e-mails qu’elles ont reçus et de leurs pièces jointes. Une tâche peut être désignée par sa clé, par exemple `DOCS-12`, telle que le tableau l’affiche. Il peut lire le détail d’un résultat et une page web publique. Le chat n’exécute pas de code, ne modifie pas de systèmes connectés, ne crée pas d’images, ne produit pas de fichiers livrables et n’utilise pas de [skills](https://docs.tale.dev/fr/platform/workspace/skills). Confie ce travail à une [tâche de projet](https://docs.tale.dev/fr/platform/projects/tasks). Toute personne qui peut ouvrir le projet peut en créer une et la confier à l’un des agents du projet ; [Transformer un chat en tâche](https://docs.tale.dev/fr/platform/chat/basics#create-task-from-chat) montre comment la créer depuis la conversation. Un agent de projet qui traite la tâche peut créer des images si un admin a activé la [génération d’images](https://docs.tale.dev/fr/platform/admin/governance/content-models#let-agents-generate-images).

## Transformer un chat en tâche {#create-task-from-chat}

Quand une conversation aboutit à un travail qui demande un fichier, par exemple une présentation, un rapport ou un tableur, confie-le à un agent de projet. Sélectionne **Créer une tâche** dans l’en-tête de la conversation ; sur un écran étroit, choisis **Créer une tâche depuis le chat** dans le menu **⋯**. Si le chat est classé dans un projet, la tâche y est créée. Sinon, choisis d’abord le projet : **Avec un agent** liste les projets que tu peux ouvrir qui ont des agents, avec leur nombre. Un projet sans agents propres y figure avec **Agent standard** : sa tâche va à l’[agent standard](https://docs.tale.dev/fr/platform/projects/project-agents#standard-agent) de l’organisation. Quand l’agent standard ne peut pas fonctionner pour toi, par exemple parce qu’un Admin l’a désactivé, ces projets figurent plutôt sous **Sans agent pour l’instant**, chacun indiquant qui peut en ajouter un.

La boîte de dialogue de la tâche s’ouvre avec ta dernière demande comme description, un lien vers le chat et les fichiers que tu as joints dans la conversation. Si le projet a un seul agent, ou s’il utilise l’agent standard, celui-ci figure déjà sous **Assigné à** ; sinon, choisis-en un. Modifie ce que tu veux, puis sélectionne **Créer et démarrer l'agent** : la tâche est créée et l’agent s’y met aussitôt. **Créer seulement** la crée sans démarrer l’agent ; **Démarrer l'agent**, dans la tâche, le lance plus tard.

<Frame caption="Créer une tâche ouvre la boîte de dialogue de la tâche avec la demande, un lien vers le chat et l’agent à démarrer.">

![La boîte de dialogue de création de tâche contient comme titre et description « Plan the quarterly business review agenda for Friday », sous la demande un lien intitulé From the chat, Content editor comme agent assigné et les boutons Create only et Create and start agent.](https://docs.tale.dev/images/platform/chat-create-task.webp)

</Frame>

La tâche apparaît ensuite au-dessus du champ de message du chat, avec ce qu’elle fait en ce moment : **L’agent travaille**, **En attente d’une place de sandbox**, **Nouvelle tentative…**, **Prête pour la revue** avec le nombre de fichiers livrés, ou **L’agent n’a pas pu la terminer**. **Ouvrir** te mène à la tâche. Tu reçois aussi une notification quand elle est prête pour la revue et quand l’agent ne peut pas terminer ; [Quand l’agent ne peut pas terminer](https://docs.tale.dev/fr/platform/projects/task-automation#quand-lagent-ne-peut-pas-terminer) explique la suite.

<Frame caption="La tâche qu’un chat a confiée affiche sa progression au-dessus du champ de message.">

![Au-dessus du champ de message, une ligne nomme la tâche « Plan the quarterly business review agenda for Friday » avec Ready for review · Website relaunch et un lien Open.](https://docs.tale.dev/images/platform/chat-task-tray.webp)

</Frame>

Demande un tel fichier à l’assistant : il répond ce qui tient dans une réponse, puis te guide dans ces étapes pour tes propres projets, en nommant les boutons tels que tu les vois.

Aucun projet que tu peux ouvrir ne propose d’agent ? Alors l’agent standard ne peut pas fonctionner pour toi : un Admin l’a peut-être désactivé dans [Gouvernance > Modèles](https://docs.tale.dev/fr/platform/admin/governance/content-models#standard-agent), ou aucun modèle que tu peux utiliser ne peut le faire fonctionner. Demande à un Admin ce qu’il en est, ou demande à un Éditeur ou à un Admin d’ajouter un agent dans l’onglet **Agents** du projet. En tant qu’Éditeur, tu peux aussi en ajouter un depuis la tâche : sous **Assigné à**, choisis **Créer un agent…**.

Seuls les fichiers de ta propre conversation suivent. Une tâche n’accepte que les fichiers téléversés par la personne qui la crée ; une tâche créée depuis un chat qu’une autre personne a partagé dans un projet commence donc sans eux.

## Continuer ou conserver la conversation

La barre sous la réponse permet de copier le texte, donner un avis, consulter les détails ou créer une branche à cet endroit. Une branche permet d’explorer une autre direction tout en conservant l’échange précédent.

Retrouve les anciens chats dans [Accueil](https://docs.tale.dev/fr/platform#home) ; la vue **Chats**, au-dessus de la liste, n’affiche que les chats. Épingle ceux qui servent souvent, donne-leur un titre reconnaissable ou déplace-les dans un projet lorsque le sujet devient récurrent : fais-les glisser sur le projet ou choisis **Déplacer vers un projet…** dans leur menu. [Chats partagés](https://docs.tale.dev/fr/platform/chat/shared-threads) explique comment publier un instantané en lecture seule pour des collègues.

Une conversation très longue peut dépasser la fenêtre de contexte du modèle. Tale affiche un avis lorsque des messages anciens sont omis. Répète une contrainte importante ou démarre un nouveau chat avec les sources utiles, plutôt que de supposer que l’assistant voit encore tout l’historique.

## Améliorer une réponse incomplète

| Problème | Action |
| --- | --- |
| La réponse est trop générale | Pose une question, précise le public et indique la longueur ou le format souhaité. |
| Un fichier n’a pas été utilisé | Vérifie le projet du chat, l’indexation du fichier et les étapes de consultation. Nomme le fichier. |
| La recherche signale une source indisponible | Demande à un admin de vérifier le service indiqué ou la configuration d’embedding. Un résultat vide ne prouve pas que l’information n’existe pas. |
| Une réponse s’arrête sur une erreur | Lis l’erreur, vérifie le modèle choisi et réessaie après correction. Tale ne change pas de fournisseur en silence. |
| Une réponse reste vide | La mention affichée à sa place en donne la raison : le modèle n’a rien renvoyé, il a épuisé sa limite de tokens en sortie avant d’écrire, ou le filtre de contenu du fournisseur a retenu la réponse. Choisis **Réessayer**, ou réduis d’abord l’effort de raisonnement, raccourcis la demande ou choisis un autre modèle. |

Pour un exemple guidé avec vérification des sources, suis [Mieux dialoguer avec le chat](https://docs.tale.dev/fr/tutorials/member/chat-effectively).

# Chat
Source: https://docs.tale.dev/fr/platform/chat/overview

Chat permet de poser rapidement une question sur un document, de comprendre un sujet ou de préciser une réponse par des questions complémentaires. L’assistant peut rechercher dans les connaissances accessibles et consulter des pages publiques si la question le nécessite. Vérifie les sources avant de t’appuyer sur une réponse factuelle, surtout lorsque l’information peut avoir changé.

<Frame caption="La question reste à côté de sa réponse pour préciser la demande sans recommencer.">

![Un chat présente une question sur les retours d’onboarding et une réponse organisée en tableau de thèmes.](https://docs.tale.dev/images/platform/chat-thread-reply.webp)

</Frame>

## Commencer par une question utile

Ouvre **Accueil**, choisis **Nouveau chat**, écris dans le champ de message et envoie. Une suggestion peut t’aider à démarrer. Indique le résultat attendu et la source pertinente : « À partir du guide d’onboarding, liste les étapes qu’un nouveau client doit terminer. Cite le guide. »

Lorsque plusieurs modèles utilisables sont disponibles, le sélecteur peut démarrer sur **Auto**. Choisis un modèle nommé pour décider quel modèle disponible répondra, et ajuste l’effort de raisonnement lorsqu’il est pris en charge. Tu peux joindre un fichier pour poser une question sur son contenu, ou ouvrir un chat de projet pour des références récurrentes.

<Frame caption="Les suggestions proposent une première question ; le champ de message accepte aussi la tienne.">

![Un nouveau chat affiche le message d’accueil, quatre suggestions de conversation et le champ de saisie.](https://docs.tale.dev/images/platform/chat-starters-empty.webp)

</Frame>

## Choisir l’espace adapté au travail

| Tu souhaites | Commence dans |
| --- | --- |
| Poser une question, comparer des informations ou clarifier une réponse | Un **chat** |
| Réutiliser les mêmes fichiers et instructions dans plusieurs conversations | Un **chat de projet** |
| Produire un livrable avec un responsable et une relecture | Une **tâche** de projet |
| Exécuter un processus répétable selon un horaire ou un événement | Une **automatisation** |

Chat se concentre sur la conversation et la recherche d’informations. Pour un livrable conséquent, l’assistant peut t’orienter vers une tâche : un agent travaille alors dans une sandbox et une personne relit le résultat. Consulte [Tâches](https://docs.tale.dev/fr/platform/projects/tasks) et [Automatisations](https://docs.tale.dev/fr/platform/automations/concepts).

## Bien utiliser la conversation

<CardGroup cols="2">

<Card title="Premiers pas dans Chat" icon="message-circle" href="https://docs.tale.dev/fr/platform/chat/basics">
Envoie un message, choisis un modèle, lis les sources et reprends une conversation.
</Card>

<Card title="Joindre des fichiers" icon="paperclip" href="https://docs.tale.dev/fr/platform/chat/attachments">
Ajoute un document ou une image et comprends les états d’import et d’indexation.
</Card>

<Card title="Comparer les modèles dans Arena" icon="swords" href="https://docs.tale.dev/fr/platform/chat/arena-mode">
Compare deux réponses à la même question et conserve celle qui convient le mieux.
</Card>

<Card title="Utiliser ta voix" icon="mic" href="https://docs.tale.dev/fr/platform/chat/voice-mode">
Dicte un message ou écoute une réponse, avec la configuration de fournisseur nécessaire.
</Card>

<Card title="Partager un chat" icon="share-2" href="https://docs.tale.dev/fr/platform/chat/shared-threads">
Publie un instantané en lecture seule pour l’organisation et arrête le partage plus tard.
</Card>

<Card title="T’exercer sur une vraie source" icon="book-open" href="https://docs.tale.dev/fr/tutorials/member/chat-effectively">
Pose une question précise, vérifie sa source et formule une relance utile.
</Card>

</CardGroup>

# Partager un chat avec ton organisation
Source: https://docs.tale.dev/fr/platform/chat/shared-threads

Partage un chat lorsqu’un collègue doit lire la question et la réponse sans poursuivre ta conversation. Le lien publie un instantané pour les membres connectés de ton organisation. Il n’est pas public et ne se met pas à jour automatiquement lorsque tu continues à discuter.

## Créer l’instantané

1. Ouvre le menu dans l’en-tête du chat et choisis **Partager**.
2. Dans **Partager le chat**, sélectionne **Partager avec l'organisation**.
3. Clique sur **Créer le lien de partage**.
4. Vérifie le contenu avec **Aperçu**, puis utilise **Copier le lien** lorsqu’il est prêt.

L’instantané correspond à la branche que tu consultes. Si tu as utilisé **Modifier le message** ou **Réessayer**, le lien publie, pour chaque tour modifié ou régénéré, la version affichée à l’écran. Avant de créer le lien, passe à la version que tes collègues doivent lire avec **Branche précédente** et **Branche suivante**.

Relis la conversation avant de diffuser le lien. Une réponse peut reprendre ou résumer des informations provenant d’une source à accès restreint. Partager cette réponse rend son texte lisible par les membres de l’organisation qui possèdent le lien.

<Frame caption="Les destinataires lisent l’instantané avec le nom de la personne qui l’a partagé, sans champ de saisie.">

![Un chat partagé en lecture seule affiche la conversation et une mention indiquant qui l’a partagé et à quelle date.](https://docs.tale.dev/images/platform/chat-shared-view.webp)

</Frame>

## Inclure une réponse ultérieure

Les nouveaux messages restent hors de l’instantané publié. Rouvre **Partager** et choisis **Inclure les messages plus récents** pour que le même lien affiche la suite de l’échange. L’instantané est repris depuis la branche que tu consultes. Passe donc d’abord à la version que tu veux publier. Vérifie à nouveau cette version dans l’aperçu.

Un destinataire qui souhaite poursuivre le sujet démarre son propre chat. L’instantané ne crée pas de conversation collaborative et n’accorde pas l’accès à toutes les sources qui y sont mentionnées.

## Arrêter le partage

Choisis **Garder privé** dans le dialogue ou **Arrêter le partage** dans le menu du chat, dans la liste d’**Accueil**. Le lien devient indisponible. Supprimer le chat d’origine met également fin à l’accès partagé.

Si le dialogue ne parvient pas à charger l’état du partage, aucune des deux options n’est sélectionnée et un message indique que le chat est peut-être encore partagé. Choisis **Réessayer**. Une fois l’état affiché, tu peux choisir **Garder privé**. D’ici là, un lien existant reste valable.

L’arrêt empêche les nouvelles consultations par ce lien. Il ne retire pas le texte déjà copié par quelqu’un : relire avant de partager reste donc nécessaire.

## Partager avec un projet

Pour une collaboration suivie, utilise **Partager avec le projet** sur un chat dans un [projet](https://docs.tale.dev/fr/platform/projects/concepts). L’onglet **Chats** distingue les conversations personnelles de celles partagées avec le projet. L’accès au projet ne partage pas automatiquement tes chats personnels.

Un chat Arena ne peut pas être partagé tant que la comparaison est en cours. Termine d’abord le choix, puis partage la conversation conservée ; consulte [Mode Arena](https://docs.tale.dev/fr/platform/chat/arena-mode).

# Mode vocal
Source: https://docs.tale.dev/fr/platform/chat/voice-mode

La dictée permet de parler au lieu de taper un message. La sortie vocale lit une réponse de l’assistant à voix haute. Tu peux utiliser chacune séparément : dicter n’impose pas une réponse parlée et écouter ne nécessite pas l’accès au microphone.

## Dicter et vérifier un message

1. Clique sur **Démarrer la dictée** sur le microphone du champ de message.
2. Autorise le microphone dans le navigateur si nécessaire, puis parle clairement.
3. Clique sur **Arrêter la dictée**. Si la transcription passe par le serveur, attends qu’elle se termine.
4. Relis et corrige le texte, surtout les noms, nombres et dates. Envoie-le lorsqu’il est prêt.

La dictée ajoute du texte au champ de saisie ; elle n’envoie pas automatiquement le message. L’envoi arrête une dictée en cours. Le modèle de chat reçoit le texte que tu soumets.

Tale utilise d’abord la reconnaissance vocale du navigateur lorsqu’elle est disponible. Sinon, il peut enregistrer et transcrire via le modèle configuré par l’organisation. La reconnaissance du navigateur peut utiliser un service de son fournisseur : ne suppose pas qu’elle fonctionne hors ligne.

Le parcours serveur exige la prise en charge de l’enregistrement par MediaRecorder dans le navigateur, l’autorisation du microphone et un modèle de transcription disponible dans l’organisation. Un admin choisit le **Modèle de transcription audio** sous [Paramètres > Gouvernance > Modèles](https://docs.tale.dev/fr/platform/admin/governance/content-models). Ce réglage sert aussi aux pièces jointes audio et vidéo. Il ne modifie pas le service de reconnaissance du navigateur : la dictée du navigateur reste utilisable lorsqu’elle est prise en charge, même si le modèle serveur de l’organisation est indisponible.

Si tu essaies de démarrer la dictée serveur alors que son modèle de transcription est indisponible, une boîte de dialogue explique le problème. Ouvre le réglage proposé si tu y as accès, relance une vérification de disponibilité ayant échoué temporairement, ou demande de l’aide à un admin. Tu peux fermer la boîte de dialogue et continuer à écrire.

## Écouter une réponse

Active **Mode vocal** dans le champ de message pour écouter les réponses du chat courant. Un modèle de synthèse vocale prépare l’audio à partir de la réponse. Utilise la commande de lecture de la réponse pour arrêter ou réécouter. Le texte reste disponible pour vérifier les détails.

Une politique de l’organisation peut masquer la sortie vocale. Une commande désactivée peut aussi signaler l’absence de modèle vocal utilisable. Un administrateur vérifie les [fournisseurs d’IA](https://docs.tale.dev/fr/platform/admin/providers). Changer seulement le modèle de chat ne configure pas un fournisseur vocal.

Le réglage dans un chat existant s’applique à ce chat. Sur un nouveau chat, il définit aussi la valeur par défaut des conversations suivantes. Il n’y a pas de voix distincte à configurer pour chaque agent de projet.

## Résoudre un problème vocal

| Symptôme | Points à vérifier |
| --- | --- |
| Le microphone ne démarre pas | Permission du navigateur, périphérique d’entrée sélectionné et éventuelle utilisation par une autre app. |
| Un message indique que la dictée est indisponible | Le navigateur ne joint pas son service vocal : vérifier la connexion, un proxy ou un bloqueur de contenu, puis réessayer. |
| Des mots manquent ou sont incorrects | Réduire le bruit ambiant et corriger le texte avant l’envoi. |
| La transcription serveur échoue | Réessayer tant que l’enregistrement reste disponible, ou le supprimer et taper le message. |
| La réponse est prête mais silencieuse | Vérifier le volume et l’autorisation de lecture du navigateur, puis lancer la lecture de la réponse. |
| Une erreur de configuration apparaît | Demander à un administrateur de vérifier le modèle vocal et ses identifiants. |

Après un échec de transcription serveur, l’enregistrement reste dans la mémoire de la page pour une relance. Quitter ou recharger la page peut le perdre. Ce n’est pas une pièce jointe audio enregistrée. Utilise les [pièces jointes](https://docs.tale.dev/fr/platform/chat/attachments) pour importer un enregistrement existant.

## Comprendre le parcours de l’audio

La dictée du navigateur suit son propre service de reconnaissance. Le parcours serveur transmet l’enregistrement à Tale pour une transcription avec le fournisseur de l’organisation. Ce parcours de dictée ne le stocke pas comme document. Une fois envoyé, le texte transcrit rejoint l’historique du chat.

La sortie vocale transmet le texte de la réponse au fournisseur configuré et diffuse l’audio pour la lecture. Si la réponse contient des informations issues d’une source restreinte, elles font aussi partie de cette demande vocale. Les administrateurs doivent choisir des services compatibles avec les [exigences de résidence des données](https://docs.tale.dev/fr/cloud/data-residency) de l’organisation.

# Connecter un client externe avec MCP
Source: https://docs.tale.dev/fr/platform/connectors/mcp-servers

Le point d’accès MCP permet à un assistant de programmation externe ou à un autre client MCP de travailler avec ton organisation dans Tale. Il peut découvrir des capacités, créer des automatisations et examiner leurs exécutions. L’accès suit la clé API de l’organisation et les droits de son titulaire.

## Trouver le point d’accès

Ouvre **Paramètres > API > MCP**. La page indique l’URL du déploiement, le slug de l’organisation, les groupes d’outils et une requête à copier pour vérifier la connexion. Si tu n’as pas encore de clé adaptée, crée-la sous **Paramètres > API**.

<Frame caption="Les paramètres MCP fournissent le point d’accès, le contexte de l’organisation et les outils disponibles.">

![La page MCP affiche une URL se terminant par /api/v1/mcp, un slug d’organisation, des groupes d’outils et une requête de test.](https://docs.tale.dev/images/platform/settings-mcp-endpoint.webp)

</Frame>

Suis [Point d’accès MCP](https://docs.tale.dev/fr/develop/mcp-endpoint) pour configurer le client, l’authentification et les droits. Conserve la clé dans les réglages d’identifiants du client, pas dans un prompt ou un document partagé.

## Choisir le sens de la connexion

Le point d’accès de Tale accepte les connexions de clients externes. Tale ne propose pas de formulaire pour ajouter un serveur MCP externe à l’équipement de ses propres agents de projet.

Pour un agent dans Tale qui doit utiliser un autre service, consulte le [catalogue de connectors](https://docs.tale.dev/fr/platform/connectors/overview). Sans connector adapté, un [agent de projet](https://docs.tale.dev/fr/platform/projects/project-agents) peut appeler le service depuis sa sandbox avec un secret aux droits limités. L’agent en cours d’exécution peut lire ce secret : limite donc ses droits au travail demandé.

## Vérifier l’accès avant de créer

Commence par la requête de test de la page MCP et confirme que le client liste les outils. Vérifie ensuite les droits exigés par l’outil avant une écriture. Enregistrer une automatisation et la déployer sont deux opérations distinctes. Connecter un client ne contourne ni les tests de déploiement ni les règles d’approbation.

[Clés API](https://docs.tale.dev/fr/platform/admin/api-keys) explique le renouvellement et la révocation. [Comprendre les automatisations](https://docs.tale.dev/fr/platform/automations/concepts) présente leur cycle d’enregistrement, de test et de déploiement.

# Connecter Tale à des services externes
Source: https://docs.tale.dev/fr/platform/connectors/overview

Utilise un connector lorsque Tale doit lire ou modifier les données d’un service externe. Le connector définit les actions prises en charge. Les identifiants permettent à Tale d’accéder au compte choisi. Les Développeurs, Admins et Propriétaires les gèrent dans **Paramètres > Connectors**.

<Video src="https://docs.tale.dev/videos/fr/tutorials/ep7-connectors/ep7-connectors.fr.mp4" poster="https://docs.tale.dev/videos/fr/tutorials/ep7-connectors/ep7-connectors.fr.webp" captions="https://docs.tale.dev/videos/fr/tutorials/ep7-connectors/ep7-connectors.fr.vtt" lang="fr" title="Épisode 7 — Connectors & le monde extérieur" caption="Épisode 7 — Connectors & le monde extérieur (2:18)">

</Video>

## Choisir la connexion selon la tâche

| Connector | Usage courant | Authentification |
| --- | --- | --- |
| Confluence | Importer des pages Confluence Cloud dans les connaissances. | Nom d’utilisateur avec mot de passe ou jeton. |
| Discord | Travailler avec les messages et canaux. | Jeton. |
| GitHub | Lire ou gérer dépôts, issues et pull requests. | Jeton. |
| GlitchTip | Lire les issues d’un projet pour que l’import GlitchTip en fasse des tâches. | Jeton et URL de l’instance. |
| Gmail | Lire, envoyer et organiser le courrier. | OAuth. |
| Google Drive | Importer des fichiers dans les connaissances. | OAuth. |
| IMAP / SMTP Mailbox | Lire ou envoyer du courrier via un service privé. | Nom d’utilisateur et mot de passe. |
| Jev decisions | Répondre à des questions typées sur les données d’un workflow avec des probabilités calibrées, pour décider s’il faut agir. | Clé API (une clé OpenRouter). |
| Microsoft Outlook | Travailler avec courrier, calendriers et contacts. | OAuth. |
| Shopify | Travailler avec produits, clients et commandes. | Clé API. |
| Slack | Travailler avec les messages et canaux. | OAuth. |
| Tavily | Rechercher sur le web et extraire des pages. | Clé API. |
| Microsoft Teams | Travailler avec les messages et canaux. | OAuth. |
| Twilio | Envoyer des SMS et passer des appels vocaux. | Nom d’utilisateur avec mot de passe ou jeton. |
| WebDAV Files | Lire, écrire et lister les fichiers WebDAV de l’organisation. | Nom d’utilisateur et mot de passe. |

Les cartes du catalogue déployé affichent les actions et méthodes d’authentification actuelles. Ces définitions sont fournies avec la plateforme. Ajouter un compte n’installe pas de code de connector arbitraire.

Les imports de connaissances utilisent l’[indexation des documents](https://docs.tale.dev/fr/platform/knowledge/documents). OneDrive et SharePoint passent par l’import dans **Connaissances > Documents**, avec un consentement individuel, plutôt que par un connector d’organisation distinct. Monter les documents Tale sur ton appareil correspond au sens inverse : utilise [WebDAV](https://docs.tale.dev/fr/platform/connectors/webdav).

## Ajouter le compte voulu

Choisis **Ajouter des identifiants**, recherche le service et ouvre sa carte. Les connectors déjà configurés apparaissent en premier, mais tu peux ajouter un autre compte pour le même service. Le formulaire demande l’authentification prise en charge.

<Frame caption="Ajouter des identifiants s’ouvre sur le catalogue — les connecteurs livrés, ceux qui ont déjà un identifiant en premier.">

![La boîte de dialogue Ajouter des identifiants par-dessus la table de Paramètres > Connectors, qui liste les connecteurs livrés sous forme de cartes avec leurs catégories et leur nombre d’actions, un champ de recherche en haut et le connecteur Tavily déjà configuré en tête de liste.](https://docs.tale.dev/images/platform/connectors-add-credential.webp)

</Frame>

Le champ **Nom** est prérempli avec le nom du connecteur. Si tu ajoutes plusieurs comptes pour le même service, remplace-le par un nom qui indique l’usage, par exemple `Boîte support` ou `Bot de publication`. Utilise ceux du service externe, pas une clé API Tale. Pour OAuth, connecte-toi chez le fournisseur avec le compte à ajouter et termine le consentement. Chaque connexion ajoute de nouveaux identifiants, nommés d’après le connecteur puis numérotés (`Gmail`, puis `Gmail 2`) ; Slack en garde un seul jeu par espace. Renomme les nouveaux identifiants pour distinguer les comptes. Si le parcours ne démarre pas, un administrateur doit peut-être configurer l’app OAuth d’abord.

Confluence, GlitchTip et Shopify demandent une **URL de l'instance** pour chaque compte. Utilise l’origine du site Atlassian, l’origine de l’instance GlitchTip comme `https://app.glitchtip.com` ou l’adresse `myshopify.com` de la boutique, pas une page quelconque ni le domaine destiné aux clients. Une instance GlitchTip auto-hébergée doit aussi être autorisée par la politique des hôtes du connecteur. [Identifiants des connectors](https://docs.tale.dev/fr/platform/admin/connectors) explique les champs, la reconnexion et le renouvellement des secrets.

## Déterminer le compte utilisé

Une action utilise les identifiants explicitement nommés, ou ceux par défaut du connector en l’absence de nom. Un seul compte par connector peut être défini comme compte par défaut. Sans compte par défaut, un appel sans nom échoue même si d’autres identifiants existent. Si tu supprimes le compte par défaut, les plus anciens identifiants actifs restants de ce connector deviennent le compte par défaut ; la confirmation de suppression les nomme d’abord.

Deux boîtes support correspondent par exemple à deux lignes. Donne-leur des noms distincts et examine les données résolues du workflow avant une exécution réelle. Le compte par défaut est utilisé lorsque l’action ne nomme pas un autre compte. Les opérations de courrier conçues pour parcourir tous les comptes actifs constituent un cas séparé.

Désactiver des identifiants conserve leur configuration mais empêche leur usage. Remplacer leur secret renouvelle la connexion derrière les références existantes. Vérifie les workflows concernés avant une désactivation, une suppression ou un changement de compte par défaut.

## Distinguer lectures et écritures

Les automatisations utilisent les actions comme nœuds de workflow. Chaque action définit son schéma d’entrée, sa sortie et son effet de lecture ou d’écriture. GlitchTip et Jev decisions ne font que lire : l’import GlitchTip crée des tâches Tale sans jamais modifier l’issue d’origine, et une décision Jev répond à chaque question avec ses probabilités sans rien écrire. Chaque décision est facturée au compte OpenRouter dont la clé figure dans les identifiants. Les essais simulent les réponses. Lors d’une exécution réelle, une écriture peut envoyer un message ou modifier des données externes et suit la politique d’approbation de l’organisation.

Les agents de projet dont les connectors sont configurés reçoivent les actions de lecture prises en charge via le broker de Tale. Il conserve ces identifiants hors de la sandbox et renvoie les résultats. Il refuse les écritures des connectors. Les outils GitHub directs et les secrets explicitement accordés suivent d’autres voies et demandent une vérification distincte.

Ajouter des identifiants n’ajoute pas librement des outils à l’assistant de chat ordinaire. Utilise les [automatisations](https://docs.tale.dev/fr/platform/automations/editor) pour un déroulement défini et les [agents de projet](https://docs.tale.dev/fr/platform/projects/project-agents) pour le travail en sandbox.

## Si le service manque

Un agent de projet peut appeler un service depuis sa sandbox si son harness dispose des outils adaptés et d’un secret explicitement accordé. Un nœud `transform` transforme uniquement des données et ne peut pas appeler une API externe. Vérifie les permissions et les effets attendus avant de choisir une intégration directe.

Si l’application externe doit appeler Tale, utilise l’[API REST](https://docs.tale.dev/fr/develop/api-reference) ou le [point d’accès MCP](https://docs.tale.dev/fr/develop/mcp-endpoint). [MCP et intégrations personnalisées](https://docs.tale.dev/fr/platform/connectors/mcp-servers) explique la distinction.

# Ouvrir les documents Tale avec WebDAV
Source: https://docs.tale.dev/fr/platform/connectors/webdav

WebDAV permet à un client de fichiers compatible de lire et modifier les documents de l’organisation comme un dossier distant. Les changements concernent le même stockage que **Connaissances > Documents**. Les fichiers de connaissances propres à un projet ne figurent pas dans ce montage.

## Obtenir les données de connexion

Ouvre **Paramètres > API > WebDAV**. Les Propriétaires, Admins et Développeurs peuvent générer leurs propres identifiants d’appareil. Copie l’URL affichée avec le slug de l’organisation et le chemin `/documents/`. Ne la reconstruis pas avec un identifiant d’organisation et n’utilise pas l’adresse d’une autre organisation.

<Frame caption="Paramètres > API > WebDAV — les détails de connexion préremplis en haut, le générateur de mots de passe applicatifs en dessous.">

![Les paramètres WebDAV affichent l’URL de connexion et le nom d’utilisateur au-dessus de trois mots de passe applicatifs. Retired design workstation est révoqué ; Design workstation et MacBook Pro restent actifs avec une action de révocation.](https://docs.tale.dev/images/platform/settings-webdav.webp)

</Frame>

Utilise l’adresse e-mail de ton compte Tale comme nom d’utilisateur et un mot de passe applicatif comme mot de passe. Le mot de passe habituel du compte ne fonctionne pas pour WebDAV. Sur un service déployé, utilise HTTPS. Ne place pas les identifiants dans une URL ni dans l’historique de commandes.

## Générer un mot de passe par appareil

1. Choisis **Générer** et saisis un **Libellé**, par exemple `Portable design`.
2. Génère le mot de passe et copie-le avant de fermer le résultat. Sa valeur complète n’apparaît qu’une fois.
3. Enregistre-le dans le gestionnaire d’identifiants du client, puis choisis **Je l'ai sauvegardé**.

La liste conserve le libellé, le préfixe et les dates d’utilisation, pas un mot de passe récupérable. En cas de perte, génère un remplacement et révoque l’ancien après avoir mis le client à jour. Des mots de passe distincts permettent de retirer l’accès d’un seul appareil.

## Configurer le client

<Tabs>

<Tab title="Finder sur macOS">

Dans Finder, utilise **⌘K** pour ouvrir la connexion à un serveur. Colle l’URL WebDAV et connecte-toi avec ton e-mail et le mot de passe applicatif. Ouvre le dossier monté et vérifie un document connu avant d’y copier des fichiers. N’enregistre les identifiants que sur un appareil de confiance.

</Tab>

<Tab title="Windows">

Connecte un lecteur réseau dans l’Explorateur avec l’adresse WebDAV HTTPS et les identifiants générés. Le service Windows WebClient doit être disponible. En cas d’échec ou de transfert volumineux bloqué, examine les [prérequis et limites Microsoft](https://learn.microsoft.com/en-us/iis/publish/using-webdav/using-the-webdav-redirector) avec l’équipe informatique, ou utilise un client WebDAV dédié. Conserve HTTPS.

</Tab>

<Tab title="Linux">

Un gestionnaire de fichiers compatible utilise l’hôte et le chemin affichés. GNOME Files emploie `davs://` pour WebDAV sécurisé, et KDE Dolphin `webdavs://`. Si le dialogue sépare serveur et dossier, saisis l’hôte comme serveur et `/dav/<orgSlug>/documents/` comme dossier, avec HTTPS et le port approprié.

</Tab>

<Tab title="iPhone et iPad">

Choisis un client qui prend explicitement en charge WebDAV et un mot de passe propre à l’appareil. La page Documents de Tale dans le navigateur convient aussi aux accès occasionnels. Le dialogue serveur générique de Fichiers ne garantit pas WebDAV. L’envoi direct depuis Pages, Numbers et Keynote [n’est plus pris en charge](https://support.apple.com/en-us/101948).

</Tab>

<Tab title="rclone">

Lance `rclone config` et crée une connexion WebDAV avec l’URL Tale, ton e-mail et le mot de passe applicatif. Choisis le fournisseur `other` et saisis le mot de passe à l’invite. Le [guide WebDAV de rclone](https://rclone.org/webdav/) explique la liste et la copie ; commence par un petit dossier de test.

</Tab>

</Tabs>

## Vérifier un petit transfert

Ouvre ou télécharge un document que tu peux déjà lire dans Tale. Si ton rôle permet l’écriture, téléverse un petit fichier texte au nom unique dans un dossier de test. Vérifie son nom et son contenu sous **Connaissances > Documents**, puis son état d’indexation avant de l’attendre dans la recherche.

L’envoi WebDAV suit les permissions et l’indexation des documents ; sa source est enregistrée comme `webdav`. Un transfert terminé ne signifie pas que l’indexation est achevée. Si un fichier de projet manque, ouvre plutôt les connaissances de ce projet.

## Gérer les verrous et les fichiers supprimés

Un éditeur compatible peut verrouiller un fichier pendant sa modification. Une écriture concurrente reçoit **423 Locked**. Termine ou ferme l’autre session plutôt que de répéter l’écrasement. Révoquer un mot de passe applicatif libère aussi ses verrous.

La zone `.trash/` liste en lecture seule les documents supprimés provisoirement. Télécharge un fichier encore conservé pour l’examiner et utilise Tale pour le restaurer. Cette zone ne récupère pas un fichier déjà supprimé définitivement. Un fichier que tu charges, écrases, copies ou supprimes via WebDAV laisse une entrée à ton nom dans le journal d’audit, sous **Paramètres > Gouvernance > Journaux** ; une suppression y figure comme un document mis à la corbeille.

## Révoquer ou réparer une connexion

Choisis **Révoquer** sur la ligne du mot de passe et confirme. Les requêtes suivantes avec ce mot de passe sont refusées ; les autres mots de passe restent utilisables. La révocation est irréversible. Configure un nouveau mot de passe dans le client si nécessaire. La génération et la révocation d’un mot de passe d’application laissent chacune une entrée dans le journal d’audit, sous **Paramètres > Gouvernance > Journaux**.

En cas de demandes de connexion répétées, vérifie l’URL exacte, ton appartenance à l’organisation et une éventuelle révocation. Un refus de permission après authentification diffère d’un mot de passe incorrect. La [référence API WebDAV](https://docs.tale.dev/fr/develop/webdav-api) explique les codes et le diagnostic du protocole. Les logiciels qui utilisent REST emploient plutôt des [clés API](https://docs.tale.dev/fr/platform/admin/api-keys).

# Développeur
Source: https://docs.tale.dev/fr/platform/developer/overview

En tant que Développeur, tu configures les connexions techniques et automatisations qui soutiennent le travail de l’équipe. Tu peux modifier les contenus et accéder aux réglages techniques : fournisseurs, connecteurs et identifiants API. La gestion des membres reste réservée aux Propriétaires et Admins.

## Choisir une connexion ou un processus

<CardGroup cols="2">

<Card title="Créer une clé API" icon="key" href="https://docs.tale.dev/fr/platform/admin/api-keys">

Autorise un script ou service à appeler Tale et prévois la rotation et la révocation.

</Card>

<Card title="Connecter un client MCP" icon="network" href="https://docs.tale.dev/fr/develop/mcp-endpoint">

Permets à un client externe de découvrir et d’utiliser les outils exposés par Tale.

</Card>

<Card title="Connecter un service externe" icon="plug" href="https://docs.tale.dev/fr/platform/admin/connectors">

Ajoute des identifiants, choisis ceux par défaut et renouvelle une autorisation expirée.

</Card>

<Card title="Créer une automatisation" icon="workflow" href="https://docs.tale.dev/fr/platform/automations/catalog">

Pars d’un workflow vide ou importe un paquet, puis teste et déploie une version.

</Card>

</CardGroup>

## Partir d’une connexion concrète

Pour les requêtes entrantes, commence par la [référence API](https://docs.tale.dev/fr/develop/api-reference) ou les [webhooks](https://docs.tale.dev/fr/develop/webhooks). Pour un agent qui appelle un autre système, privilégie un connecteur pris en charge. Des identifiants directs dans une sandbox demandent un périmètre soigneusement limité. [Agents de projet](https://docs.tale.dev/fr/platform/projects/project-agents) explique l’équipement. Les fichiers de déploiement et variables d’environnement figurent dans la [configuration auto-hébergée](https://docs.tale.dev/fr/self-hosted/configuration/environment-reference).

# Éditeur
Source: https://docs.tale.dev/fr/platform/editor/overview

En tant qu’Éditeur, tu maintiens les informations communes : importer des documents, corriger des entrées de connaissances et actualiser des fiches. Tu peux travailler dans les projets pour lesquels tu as un accès en édition. Commence par une source et une question à laquelle elle doit répondre, puis élargis la collection selon les besoins de l’équipe.

## Choisir une tâche de contenu

<CardGroup cols="2">

<Card title="Entretenir les connaissances" icon="library" href="https://docs.tale.dev/fr/platform/knowledge/overview">

Choisis fichiers, informations courtes, sites web ou fiches structurées.

</Card>

<Card title="Mettre en place un projet" icon="folder-open" href="https://docs.tale.dev/fr/tutorials/member/use-projects">

Réunis fichiers et instructions, puis pose une question dans le chat du projet.

</Card>

<Card title="Suivre le travail avec des tâches" icon="list-checks" href="https://docs.tale.dev/fr/platform/projects/tasks">

Précise les critères d’acceptation, les responsables, l’avancement et la relecture.

</Card>

<Card title="Entretenir les instructions réutilisables" icon="list-plus" href="https://docs.tale.dev/fr/platform/workspace/skills">

Crée et partage des skills pour les agents qui ont besoin d’une méthode répétable.

</Card>

</CardGroup>

## Quand faire intervenir un Développeur

Le rôle Éditeur ne permet pas de créer des workflows ni d’administrer les connecteurs ; ces ressources sont en lecture seule. Un Développeur, Admin ou Propriétaire gère les modifications d’automatisations et les identifiants techniques. Les agents de projet nécessitent aussi un accès en édition au projet, des fournisseurs et des sandboxes fonctionnels. Consulte [Membres et rôles](https://docs.tale.dev/fr/platform/admin/members-and-roles) avant de suivre un guide qui demande des permissions supplémentaires.

# Plateforme
Source: https://docs.tale.dev/fr/platform

Ces guides expliquent comment travailler dans Tale, dans le Cloud ou sur ton propre déploiement. Commence par une question dans un chat, regroupe le travail suivi dans un projet ou consulte une fonction précise pour modifier un réglage.

## Passer d’une section à l’autre {#navigation}

Sur ordinateur, la barre de navigation à gauche présente les sections sous forme d’icônes : **Accueil**, **Connaissances** et **Automatisations**. En bas de cette barre se trouvent **Paramètres**, tes notifications et ton menu de profil. Survole une icône pour lire son nom. Sur téléphone, la barre d’onglets en bas de l’écran propose **Accueil**, **Connaissances**, **Automatisations** et **Paramètres**. Seuls les rôles Propriétaire, Admin et Développeur, qui construisent les automatisations, voient **Automatisations** ; les Membres et les Éditeurs ne la voient pas.

Sur téléphone, la navigation flotte au-dessus de la page dans une barre arrondie. Le contenu défile derrière elle, tandis que les champs de message et les actions de la page restent accessibles au-dessus. La barre disparaît quand le clavier à l’écran s’ouvre et réapparaît quand tu le fermes.

Quand tu fais défiler la page vers le bas, la barre devient plus petite, descend légèrement et n’affiche plus que les icônes. Remonte dans la page pour retrouver la barre complète et ses libellés. Toutes les destinations restent accessibles dans les deux formats.

Une section s’ouvre toujours sur sa première page, quoi que tu y aies fait auparavant : le même choix te mène donc chaque fois au même endroit. Par exemple, ouvre l’onglet **Exécutions** d’une automatisation, passe dans **Accueil**, puis choisis **Automatisations** : la liste des automatisations s’ouvre, et non l’onglet que tu as quitté. Sur ordinateur, seul **Accueil** reprend où tu en étais : il rouvre le chat que tu as lu en dernier, ou un nouveau chat si tu n’en as aucun. Choisir **Accueil** alors que tu y es déjà démarre un nouveau chat, tout comme le raccourci **⌥⌘N** sur Mac ou **Alt+Ctrl+N** sous Windows et Linux.

**Paramètres** liste ses pages dans un panneau latéral, à côté de la page, et l’en-tête indique la page ouverte ; sur téléphone, Paramètres commence par la liste de ses pages. **Connaissances** présente ses pages sous forme d’onglets sous son en-tête.

| Tu souhaites… | Marche à suivre |
| --- | --- |
| Ouvrir une autre section | Choisis cette section dans la barre de navigation ou, sur téléphone, dans la barre d’onglets. |
| Démarrer un nouveau chat | Sur ordinateur, choisis **Nouveau chat** dans **Accueil**, ou choisis **Accueil** alors que tu y es déjà. Sur téléphone, ouvre **Accueil**, choisis **Chats**, puis **Nouveau chat**. |
| Ouvrir un projet | Sur ordinateur, choisis le projet sous **Projets** dans **Accueil**. Sur téléphone, choisis le projet, puis **Ouvrir le projet**. |
| Revenir à la liste des projets | Choisis **Tous les projets** dans **Accueil**, ou clique sur **Projets** dans le fil d’Ariane au-dessus du projet. |
| Revenir à la liste des documents | Choisis **Connaissances**. |

Les favoris et les liens partagés vers un projet, une tâche ou un document précis ouvrent toujours cette destination.

### Retrouver ton travail dans Accueil {#home}

**Accueil** réunit tes chats, tes tâches, tes projets et les conversations clients. Sur ordinateur, le panneau latéral d’**Accueil** reste affiché à côté de chaque chat, tâche, projet et page de la boîte de réception. Sur téléphone, **Accueil** ouvre la même liste en plein écran. Un chat, une tâche ou une conversation que tu ouvres depuis cette liste n’a qu’un seul en-tête : une flèche de retour qui t’y ramène, son titre et ses actions. Ton menu de profil reste accessible en haut de l’écran **Accueil** et dans **Paramètres**.

Sur ordinateur, fais glisser le bord droit du panneau d’**Accueil** pour ajuster sa largeur. Tu peux aussi atteindre la séparation avec Tab, puis appuyer sur la flèche gauche ou droite. Ton navigateur conserve cette largeur pour cette organisation.

En haut du panneau, **Tout**, **Chats**, **Tâches** et **Réception** déterminent ce que la liste affiche. Juste à côté, **Nouveau chat**, le crayon, démarre un chat ; son infobulle indique le raccourci clavier. **Réception** n’apparaît que si ton organisation dispose d’une boîte de réception : une automatisation de synchronisation du courrier mise en service, ou une app API qui a déjà synchronisé une conversation.

**Projets** liste tous les projets que tu peux ouvrir. Choisis un projet pour ouvrir sa page avec le tableau des tâches, **Général**, **Chats**, **Connaissances** et **Agents**. Les deux icônes à côté du titre **Projets** sont **Tous les projets**, qui ouvre la liste complète, et **Nouveau projet**. Fais glisser un chat sur un projet pour l’y ranger. Le menu d’un projet propose **Nouveau chat** et **Épingler le projet**.

Sous les projets, une seule liste regroupe ton travail sous **Épinglés**, **Aujourd’hui**, **Hier**, **7 derniers jours** et **Plus ancien** :

- Tes chats.
- Les tâches ouvertes qui te sont attribuées ou qui attendent ta relecture, dans tous les projets que tu peux consulter.
- Dans **Tout**, les conversations ouvertes de la boîte de réception que tu peux voir.

Une vue **Tâches** vide propose **Tous les projets**, qui ouvre la liste des projets. Sur ordinateur, une vue **Tout** ou **Chats** vide propose aussi **Nouveau chat**. Si tes chats, tes tâches ou tes conversations ne peuvent pas être chargés, la liste garde ce qui a été chargé et indique ce qui manque, au lieu d’afficher une vue vide. **Réessayer** relance le chargement.

Sur téléphone, la liste diffère sur trois points :

- **Nouveau chat** se trouve en haut de la vue **Chats**, et non dans l’en-tête. **Nouveau projet** n’existe pas sur cet écran, et le menu d’un projet propose **Ouvrir le projet** et **Épingler le projet**.
- Quand tu choisis un projet sous **Projets**, **Tout**, **Chats** et **Tâches** n’affichent que les chats de ce projet et tes tâches ouvertes qui s’y trouvent. La ligne du projet sélectionné est mise en évidence. Le filtre reste actif quand tu passes d’une de ces vues à une autre. Choisis à nouveau la ligne du projet pour retirer le filtre. **Réception** n’est jamais filtrée par projet.
- **Tous les projets** est un lien avec libellé à côté du titre **Projets**, et non une icône.

Chaque ligne commence par une bulle de chat, un cercle coloré selon le statut de la tâche ou les initiales du contact. Viennent ensuite le titre, le temps écoulé depuis la dernière modification et, en dessous, une ligne de contexte : pour un chat, son projet ; pour une tâche, son identifiant et son statut, par exemple `WEB-2` **En revue** ou **En attente de ta relecture** ; pour une conversation, le contact et son dernier message. Un point dans la couleur d’accentuation signale les chats et conversations non lus, ainsi que les tâches qui attendent ta relecture. Un crayon suivi de **Brouillon**, au début de la ligne de contexte, signale un chat, une tâche ou une conversation où tu as saisi un texte sans l’envoyer, sauf pour l’élément ouvert. Les brouillons restent dans le navigateur où tu les as saisis. Le menu d’un chat propose **Épingler le chat**, **Marquer comme lu** ou **Marquer comme non lu**, **Renommer**, **Déplacer vers un projet…**, **Partager**, **Arrêter le partage** pour un chat partagé, **Archiver** et **Supprimer**. Les chats archivés rejoignent **Archivés**, en bas de la liste.

La vue **Réception** affiche les conversations d’un seul statut : choisis **Ouvert**, **Fermé**, **Spam** ou **Archivé** dans son menu de statut. Elle propose aussi **Nouvel e-mail**, un champ de recherche et un bouton **Filtre** pour **Responsable**, **Statut de lecture** et **Canal**. Pour traiter plusieurs conversations à la fois, survole les initiales d’une conversation et coche la case qui apparaît. La barre au-dessus de la liste propose alors **Envoyer les messages**, **Fermer** et **Marquer comme spam** pour les conversations ouvertes, ou **Rouvrir** pour les conversations fermées ou marquées comme spam, ainsi que **Archiver** ou **Désarchiver** et **Effacer la sélection**.

La case au début de la barre sélectionne toute la liste. Tant que seules certaines conversations sont cochées, elle affiche un tiret ; coche-la alors pour sélectionner toutes les conversations que la liste affiche, sauf celles qu’une recherche ou un filtre masque. Une sélection de plus de 200 conversations est traitée en plusieurs fois, et la boîte de réception en affiche l’avancement. Le message qui suit indique combien de conversations ont été modifiées et combien ont échoué, avec la raison du premier échec lorsqu’elle est connue. Celles qui ont échoué restent cochées pour que tu puisses réessayer. Si la liste ne peut pas être chargée, elle affiche **Échec du chargement des conversations** avec **Réessayer**, au lieu d’une liste vide.

<Frame caption="La vue Réception à côté d’une conversation ouverte : menu de statut, Nouvel e-mail, recherche et filtre au-dessus des conversations, chacune avec des initiales et son dernier message.">

![L’accueil en vue Réception, avec trois conversations ouvertes — Copy of the August invoice de Léa Martin, Annual discount on the team plan de Hannah Weber et Seat pricing for read-only members de Daniel Okafor — à côté de la conversation ouverte avec Hannah Weber, qui montre ses deux messages, la réponse de l’équipe entre les deux et le champ de message.](https://docs.tale.dev/images/platform/home-inbox.webp)

</Frame>

Un chat, une tâche ou une conversation s’ouvre sous un en-tête qui affiche son icône, son titre, une ligne de contexte et ses actions. **Masquer le panneau latéral**, au début de cet en-tête, replie le panneau d’**Accueil** pour laisser plus de place ; **Afficher le panneau latéral** le fait revenir. L’infobulle du bouton indique le raccourci clavier. La page d’un projet propose le même bouton au début de son en-tête. Dans une conversation, la première action, **Copier le lien**, copie un lien qui ouvre la même conversation pour un collègue. Les Propriétaires et Admins attribuent la conversation depuis son en-tête, à une personne, à une équipe ou aux deux. Choisir à nouveau la personne ou l’équipe déjà attribuée retire cette attribution, tout comme **Retirer l'attribution** et **Retirer l'équipe** en bas de la liste ; l’autre attribution reste inchangée.

Les images d’un e-mail s’affichent dans le message. Tale récupère pour toi les images hébergées sur les serveurs de l’expéditeur : celui-ci ne voit ni ton adresse IP, ni le moment où tu lis le message. Une image de plus de 10 Mo ou au format SVG ne s’affiche pas.

### Raccourcis clavier {#shortcuts}

Sur ordinateur, tu peux aussi parcourir **Accueil** et ouvrir la recherche au clavier :

| Mac | Windows ou Linux | Effet |
| --- | --- | --- |
| **⌥⌘N** | **Alt+Ctrl+N** | Démarre un nouveau chat depuis n’importe quelle page. |
| **⌘K** | **Ctrl+K** | Ouvre la recherche depuis n’importe quelle page, comme la loupe de la barre de navigation. |
| **⌘\\** | **Ctrl+\\** | Masque ou affiche le panneau d’**Accueil** sur un chat, une tâche ou une conversation ouverte. |
| **⌥↑** ou **⌥↓** | **Alt+↑** ou **Alt+↓** | Ouvre l’élément précédent ou suivant de la vue en cours, même quand le panneau est masqué. |
| **↑** ou **↓** | **↑** ou **↓** | Passe à la ligne précédente ou suivante dès qu’une ligne du panneau a le focus clavier. |

Si aucun élément de la liste n’est ouvert, **⌥↓** (**Alt+↓**) ouvre le premier et **⌥↑** (**Alt+↑**) le dernier. Dans un champ de texte, ces touches gardent leur rôle habituel. Quand une ligne a le focus clavier, les touches **Début** et **Fin** mènent à la première et à la dernière ligne de sa liste, et **Entrée** ouvre cette ligne.

## Choisir une fonction

<CardGroup cols="2">

<Card title="Chat" icon="message-circle" href="https://docs.tale.dev/fr/platform/chat/overview">

Pose des questions, joins des fichiers, vérifie les sources, compare les modèles et partage une conversation.

</Card>

<Card title="Projets" icon="folder-open" href="https://docs.tale.dev/fr/platform/projects/overview">

Réunis fichiers, instructions, chats personnels ou partagés et tâches.

</Card>

<Card title="Agents" icon="bot" href="https://docs.tale.dev/fr/platform/agents/concepts">

Configure des agents pour les tâches de projet avec un harness, un modèle et un équipement adaptés.

</Card>

<Card title="Automatisations" icon="workflow" href="https://docs.tale.dev/fr/platform/automations/concepts">

Crée un processus répétable, teste-le, déploie une version et consulte ses exécutions.

</Card>

<Card title="Connaissances" icon="library" href="https://docs.tale.dev/fr/platform/knowledge/overview">

Entretiens documents, informations courtes, sites publics, contacts et produits.

</Card>

<Card title="Approbations" icon="check-check" href="https://docs.tale.dev/fr/platform/approvals/concepts">

Examine l’opération proposée par une automatisation avant de l’autoriser.

</Card>

<Card title="Bibliothèque de skills" icon="list-plus" href="https://docs.tale.dev/fr/platform/workspace/skills">

Crée des instructions réutilisables et partage-les avec des équipes ou l’organisation.

</Card>

<Card title="Modèles" icon="cpu" href="https://docs.tale.dev/fr/platform/models">

Comprends les capacités, la disponibilité et le choix des modèles.

</Card>

<Card title="Connecteurs" icon="plug" href="https://docs.tale.dev/fr/platform/connectors/overview">

Connecte des services externes et vérifie les actions accessibles aux agents et automatisations.

</Card>

</CardGroup>

## Trouver ton point de départ

Ton rôle détermine les actions disponibles. Les équipes et l’accès aux projets déterminent les ressources accessibles. Choisis le parcours le plus proche de ton travail ; un administrateur peut expliquer une action absente.

<CardGroup cols="2">

<Card title="Membre" icon="user" href="https://docs.tale.dev/fr/platform/member/overview">

Pose des questions, consulte les connaissances et règle tes préférences personnelles.

</Card>

<Card title="Éditeur" icon="pencil-ruler" href="https://docs.tale.dev/fr/platform/editor/overview">

Entretiens les contenus partagés et travaille dans les projets que tu peux modifier.

</Card>

<Card title="Développeur" icon="terminal" href="https://docs.tale.dev/fr/platform/developer/overview">

Crée des automatisations et connecte du code, des clients et des services externes.

</Card>

<Card title="Admin" icon="shield" href="https://docs.tale.dev/fr/platform/admin/overview">

Configure les personnes, les fournisseurs, l’infrastructure et les politiques de l’organisation.

</Card>

</CardGroup>

# Ajouter des sites aux connaissances
Source: https://docs.tale.dev/fr/platform/knowledge/crawling

Ajoute un site lorsque ton équipe doit interroger un contenu public qui évolue. Tale récupère les pages sélectionnées et indexe leur texte lisible pour la recherche dans les connaissances. La gestion des sources nécessite le rôle Éditeur ou supérieur. Les pages protégées par une connexion demandent un autre parcours d’import, comme [Documents](https://docs.tale.dev/fr/platform/knowledge/documents).

## Ajouter un site ou des pages précises

Ouvre **Connaissances > Sites web** et clique sur **Ajouter un site web**. Choisis le type de source avant de saisir l’adresse :

| Type de source | Quand l’utiliser | Valeur à saisir |
| --- | --- | --- |
| **Site web entier** | Tu veux découvrir le contenu d’un domaine | Un **Domaine**, par exemple `example.com` |
| **Liste d'URL** | Tu veux un ensemble précis de pages ou documents publics | Une adresse par ligne sous **URL** |

Le mode site entier accepte une URL mais utilise son nom d’hôte. Coller un chemin ne limite pas le scan à ce chemin ; utilise une liste d’URL pour cela. Une adresse en `http://` est refusée, parce que le crawler ne récupère qu’en HTTPS, et un point final est retiré. Les formes avec et sans `www` désignent le même site : les ajouter toutes deux déclenche un avertissement de doublon.

Choisis l’**Intervalle d'analyse**, puis **Enregistrer**. La valeur par défaut est de six heures ; les choix vont d’une heure à trente jours. Le planificateur prend en charge la nouvelle source. L’enregistrement ne signifie pas que toutes les pages ont déjà été récupérées et indexées.

<Frame caption="Le mode site entier demande un domaine et un intervalle. Choisis une liste d’URL lorsque la sélection des pages compte.">

![Le dialogue d’ajout d’un site présente Domaine et Intervalle de scan, réglé sur six heures par défaut.](https://docs.tale.dev/images/platform/websites-add-dialog.webp)

</Frame>

## Permettre au chat de chercher dans les pages

Le crawl enregistre le texte d’une page. Le chat et la recherche dans les connaissances n’y accèdent que lorsque ton organisation dispose d’un modèle d’embedding qui fonctionne, car chaque recherche transforme d’abord la question en vecteur. Sans modèle, une source peut afficher **Actif** avec toutes ses pages indexées pendant que l’assistant répond que la recherche dans les pages web n’est pas configurée.

**Connaissances > Sites web** affiche alors l’avis **Le chat ne peut pas encore chercher dans ces sites web** ; un administrateur peut voir à sa place la bannière **La recherche de connaissances est coupée**, au-dessus de chaque page. Un administrateur définit le modèle dans **Paramètres > Résidence des données** ; les détails destinés aux exploitants figurent dans [Résidence des données](https://docs.tale.dev/fr/self-hosted/configuration/data-residency). Dès qu’un modèle est enregistré, Tale relance un scan de chaque source explorée sans modèle et de chaque source dont le dernier scan a échoué. Tu n’as pas à les ajouter de nouveau.

## Garder une liste d’URL ciblée

Une liste récupère uniquement les adresses fournies et ne suit aucun autre lien. Elle peut couvrir plusieurs sites ; Tale les regroupe en une source par site. Une adresse listée en `http://` est acceptée et récupérée en `https://`, contrairement à un domaine `http://` en mode site entier, qui est refusé ; une page qui ne répond qu’en clair reste inaccessible dans les deux cas. Ajouter une liste à une source de type liste d’URL existante complète les adresses sans retirer les précédentes et actualise son intervalle de scan.

Utilise des URL publiques complètes. Les PDF et documents Office modernes liés peuvent être indexés s’ils contiennent du texte lisible. Un téléchargement servi sous un type générique ou ancien (`application/octet-stream`, `application/vnd.ms-excel` pour un export `.xlsx`) est reconnu à son nom de fichier et à son contenu. Les images et scans sans texte extractible ne deviennent pas des contenus recherchables.

## Comprendre la découverte et l’actualisation

Pour un site entier, le crawler utilise l’accueil et les sitemaps publiés, y compris les index de sitemaps et ceux déclarés dans `robots.txt`. Sans sitemap exploitable, il suit les liens du domaine depuis l’accueil. Une page absente des sitemaps et inaccessible par ces liens peut manquer. Utilise une liste d’URL si des pages précises sont indispensables.

Les scans sont incrémentaux : les contenus inchangés sont ignorés, les contenus modifiés réindexés, les nouvelles pages ajoutées et les pages retirées supprimées de l’index — comme les pages que le `robots.txt` en est venu à interdire. Une page qui redirige vers une autre adresse du même site n’est indexée qu’une fois, sous l’adresse où elle aboutit. Les compteurs de pages de la ligne suivent le scan à mesure que les pages arrivent, après la découverte et après chaque lot stocké, la table bouge donc pendant qu’un scan tourne. Une liste d’URL actualise sa sélection fixe au même rythme. Aucune publication séparée n’est nécessaire après l’indexation.

Le crawler visite en lecteur anonyme. Ajouter une URL ne rend pas accessible un contenu privé. À chaque requête il se présente comme `TaleBot/<version> (+https://docs.tale.dev/platform/knowledge/crawling)`, si bien qu’un groupe de `robots.txt` peut le désigner par son nom — `User-agent: TaleBot` — pour l’autoriser, le ralentir ou le refuser seul.

Le crawler applique les règles `Disallow` de `robots.txt` destinées à l’agent `*` sur chaque chemin par lequel une URL peut entrer — les sitemaps, le parcours de liens et les liens qu’une page JavaScript révèle après rendu — et de nouveau avant chaque récupération : une page qu’une règle couvre n’est jamais récupérée, et une page qu’une règle ajoutée plus tard couvre quitte l’index au scan suivant. Les règles ne filtrent pas une liste d’URL explicite : une adresse listée est ta consigne. À chaque récupération, un en-tête HTTP `X-Robots-Tag: noindex` ou `none`, ou une balise HTML `<meta name="robots" content="noindex">`, empêche l’indexation, y compris pour une URL de liste, et retire ce qu’un scan antérieur avait stocké de la page. Ces règles sont une courtoisie, pas un contrôle d’accès : si tu administres le site source, ne compte pas sur le crawler comme mécanisme de contrôle d’accès.

Utilise HTTPS sur le port standard et enregistre un nom d’hôte : une adresse qui indique un autre port, comme `:8001`, ou une adresse IP nue est refusée — le robot se connecte par le nom d’hôte et vérifie le certificat avec lui. Les adresses privées et les redirections vers un réseau privé sont bloquées, sauf si l’exploitant a autorisé ces sources internes pour son installation.

## Tenir compte des limites du crawler

| Limite | Conséquence sur la couverture |
| --- | --- |
| 10 000 URL suivies par site | Certaines pages d’un grand site peuvent rester inconnues. Fournis une liste ciblée pour le contenu nécessaire. |
| Trois minutes de découverte, au plus 50 récupérations de sitemaps | Les ensembles de sitemaps volumineux ou lents peuvent rester incomplets. |
| 100 Mio (`KNOWLEDGE_CRAWL_DOCUMENT_MAX_BYTES`) et 30 secondes par récupération de contenu | Les téléchargements trop volumineux et les réponses lentes échouent (`timeout` pour le budget de téléchargement et celui de 20 secondes du rendu) ; une page derrière plus de cinq redirections aussi (`redirect_limit_exceeded`). |
| Cinq minutes de traitement par lot, jusqu’à 200 reprises | Un long scan se poursuit par lots. Une récupération ou un rendu déjà engagé peut dépasser le budget du lot ; il ne s’agit pas d’une durée totale garantie. |
| Cinq échecs consécutifs pour une URL découverte automatiquement | Le crawler cesse de programmer cette URL pendant sept jours, puis la sonde une fois de plus. Un échec de la sandbox qui effectue le rendu ne compte pas : si son proxy de sortie refuse la connexion ou si son navigateur ne répond plus, le scan se termine avec cette cause sur la source, et le scan suivant réessaie chaque page. Les URL fournies explicitement restent candidates à chaque scan, et une page listée que le site répond en 404 reste dans la liste avec cette réponse. |

Tu ne peux pas fixer ton propre plafond de pages, filtrer les chemins à inclure ou exclure, ni arrêter un scan avec un bouton. Une liste d’URL réduit la sélection demandée ; ces limites continuent de s’appliquer.

## Vérifier le contenu indexé

Le tableau affiche **Statut**, **Indexé**, **Analysé** et **Intervalle**. La colonne **Indexé** indique un nombre de pages. Ouvre la ligne du site pour examiner la liste des pages, le nombre de mots et de fragments et la date du dernier passage. Déplie une page pour lire ses fragments de texte enregistrés. Un échec de récupération affiche sa cause et le nombre d’échecs consécutifs. Une page que le crawler laisse volontairement de côté — la source refuse l’indexation, le type de contenu ne fournit aucun texte lisible, ou une redirection quitte le site — apparaît comme **Ignorée** avec sa cause et ne compte pas comme un échec.

| Statut | Signification |
| --- | --- |
| **En cours d'analyse** | Un scan est en cours ; une source que tu viens d’ajouter commence ici. |
| **Actif** | Un scan s’est terminé avec succès. Vérifie les résultats page par page pour connaître la couverture. |
| **Erreur** | Le scan a échoué ou les tentatives de récupération n’ont laissé aucun contenu stocké. Ouvre la source pour connaître la cause. |
| **Suppression en cours** | La source est en cours de retrait. |

Un scan en cours au moment où Tale a été redémarré, mis à jour ou arrêté brutalement reprend de lui-même en quelques minutes, avec les pages qu’il n’avait pas encore atteintes. Les pages qui ont besoin du navigateur peuvent suivre jusqu’à un quart d’heure plus tard. La source affiche **En cours d'analyse** pendant tout ce temps.

Pour lancer un scan en dehors de l’intervalle, ouvre le menu de la ligne ou les détails de la source et choisis **Analyser maintenant**. C’est utile quand le site a changé ou après un scan en échec, qui sinon est relancé automatiquement dans les deux heures. L’action est proposée tant que la source n’est ni en cours d’analyse ni en cours de suppression.

La vue des pages permet aussi de rechercher dans le contenu indexé. Essaie une expression distinctive de la page avant de t’appuyer dessus dans Chat, puis pose une question précise et vérifie la citation.

## Examiner une page absente

Vérifie d’abord l’adresse, le type de source et la date du dernier scan. Ouvre ensuite le site, limite la liste des pages à **En échec** ou **Ignorées**, puis lis l’erreur de la page concernée.

| Problème signalé | Vérification ou correction |
| --- | --- |
| Certificat non approuvé | L’administrateur du site doit corriger un certificat TLS expiré, autosigné, associé au mauvais hôte ou non approuvé pour une autre raison. Répéter les scans ne le répare pas. |
| Adresse privée, redirection refusée ou URL invalide | Utilise l’adresse HTTPS publique prévue. Demande à ton exploitant quelles sources internes sont autorisées si nécessaire. |
| Erreur HTTP, échec réseau ou délai dépassé | Ouvre la page d’origine et vérifie sa disponibilité. Un scan ultérieur peut réussir après réparation du service source. |
| Réponse trop volumineuse | Publie un document plus petit ou divise la source. La limite de récupération est de 100 Mio, sauf si ton opérateur a défini `KNOWLEDGE_CRAWL_DOCUMENT_MAX_BYTES`. |
| La source refuse l’indexation | La réponse contient `X-Robots-Tag: noindex` ou `none`, ou la page porte `<meta name="robots" content="noindex">`. Le responsable du site doit modifier cette consigne pour que Tale puisse indexer le contenu. |
| Contenu non pris en charge ou sans texte lisible | Les points d’accès JSON/XML, téléchargements binaires, images ou scans peuvent ne fournir aucun texte exploitable. Fournis une page HTML ou un document pris en charge dont le texte peut être extrait. |
| Échec du rendu ou de l’extraction | Vérifie que la page publique se charge et que le document d’origine s’ouvre. Répare ou exporte à nouveau une source endommagée. |
| L’assistant répond que la recherche dans les pages web n’est pas configurée | L’organisation n’a pas de modèle d’embedding qui fonctionne. Un administrateur le définit dans **Paramètres > Résidence des données** ; Tale relance ensuite un scan des sources concernées. |
| **Erreur** avec « Le modèle d'embedding n'a pas pu traiter les pages. » | Le fournisseur d’embedding a refusé la requête ou n’a pas pu y répondre : identifiants rejetés, solde épuisé, limite de débit maintenue malgré toutes les tentatives, ou panne. Les détails de la source précisent lequel, avec la réponse du fournisseur en dessous. Un administrateur corrige le modèle dans **Paramètres > Résidence des données** ou ses identifiants dans **Paramètres > Fournisseurs IA** ; l’enregistrement relance le scan des sources concernées. Après une panne chez le fournisseur, choisis **Analyser maintenant** dès qu’il est de nouveau disponible. |
| **Erreur** avec « L'analyse n'a pas eu lieu. » | Le navigateur du crawler n’a pas pu démarrer, aucune page n’a donc été rendue ; son rapport se trouve sous **Détails techniques** dans les détails de la source. L’adresse n’est pas en cause : demande à ton exploitant de vérifier le service de sandbox, puis choisis **Analyser maintenant**. |

Une récupération réussie efface l’erreur précédente. Si une actualisation échoue, la copie déjà indexée peut rester disponible : **Actif** et le nombre de pages indexées ne prouvent pas que chaque page est à jour. Compare les fragments enregistrés et la date du passage avec l’original avant de t’appuyer sur une modification récente.

Si la source affiche **Suspendu**, des échecs répétés d’accès à la base de connaissances ont arrêté les analyses. Demande à un administrateur de réparer la connexion dans **Paramètres > Résidence des données**, puis utilise **Reprendre l'analyse**.

# Documents
Source: https://docs.tale.dev/fr/platform/knowledge/documents

Utilise **Connaissances > Documents** pour les fichiers de la bibliothèque commune : politiques, guides, rapports et justificatifs. Les membres lisent les documents auxquels ils ont accès. Les rôles Éditeur et supérieurs peuvent les importer et les gérer. Les contenus propres à un seul projet appartiennent à son [onglet Connaissances](https://docs.tale.dev/fr/platform/projects/manage-files).

<Frame caption="La liste réunit le fichier original, sa provenance, son indexation et l’accès par équipe. Le filtre ne conserve que les fichiers chargés et indexés.">

![L’onglet Documents présente les fichiers partagés avec leur taille, source, statut RAG et équipes.](https://docs.tale.dev/images/get-started/documents-list.webp)

</Frame>

## Importer depuis ton appareil

1. Ouvre **Connaissances > Documents** et le dossier de destination. Crée-le avec **Nouveau dossier** si nécessaire.
2. Choisis **Téléverser des documents > Depuis ton appareil**, puis les fichiers.
3. Attends la fin de l’import et retrouve les lignes dans le tableau.
4. Ouvre un document pour vérifier son aperçu et ses détails. Consulte le **Statut RAG** avant de poser une question sur son contenu.

Choisis un nom de fichier explicite, avec une date ou une révision si cela aide à distinguer les sources. Importer un autre fichier du même nom crée un document séparé ; cela ne remplace pas l’existant.

## Distinguer stockage et recherche

Un fichier enregistré n’est pas forcément interrogeable. Tale doit pouvoir en extraire le texte avant de l’indexer pour la recherche dans les connaissances.

| Format | Résultat attendu |
| --- | --- |
| PDF avec texte intégré, `.docx`, `.xlsx`, `.pptx`, `.odt`, CSV, texte brut | Extraction et indexation prises en charge. Vérifie le résultat pour le fichier concerné. |
| Anciens formats Office `.doc`, `.xls`, `.ppt` | Stockage et téléchargement possibles. Convertis-les dans un format moderne pour l’indexation. |
| Images comme JPG, PNG, GIF, WEBP | Stockage et téléchargement possibles. L’index de connaissances n’en extrait pas le texte. |
| Fichiers Microsoft Loop (`.loop`) importés depuis Microsoft 365 | Import et téléchargement possibles. Tale ne peut pas en extraire le texte : leur statut est **Non pris en charge**. |
| PDF scanné sans texte lisible | Fournis une version traitée par OCR ou contenant du texte pour rendre le contenu recherchable. |

Réindexer plusieurs fois un format non pris en charge ne le rend pas interrogeable. Pour une question sur une image, consulte [Pièces jointes du chat](https://docs.tale.dev/fr/platform/chat/attachments) : un modèle de vision disponible peut y lire l’image directement.

## Lire le statut d’indexation

| Statut | Signification et action |
| --- | --- |
| **En file d'attente** | Attend une place d’indexation. Une bibliothèque chargée traite les fichiers progressivement. |
| **Indexation** | Le texte est préparé pour la recherche. Attends avant de tester la source. |
| **Indexé** | L’indexation est terminée. Pose une question précise et ouvre sa citation. |
| **Réindexation nécessaire** | L’index est périmé. Utilise **Relancer l'indexation** à côté du statut. |
| **Échoué** | Lis l’erreur, résous sa cause, puis réessaie. |
| **Non pris en charge** | Ce contenu ne peut pas être indexé : format incompatible, texte vide ou illisible, ou PDF endommagé, par exemple. Ouvre le badge pour connaître la cause. |
| **Non indexé** | Aucun index terminé n’est disponible. Vérifie le fichier et lance l’indexation lorsque l’action est proposée. |

Les traitements interrompus reprennent en arrière-plan ou signalent un échec avec une option de relance. Si le statut n’avance pas, transmets le nom du document et l’erreur à un administrateur. Il peut vérifier les services d’indexation et la configuration des embeddings. Les fichiers échoués ou non pris en charge occupent toujours du stockage jusqu’à leur suppression.

## Résoudre un problème d’indexation

Clique sur **Échoué** ou **Non pris en charge** pour lire l’explication. La correction dépend de la cause, pas seulement de l’extension du fichier.

| Cause | Action à entreprendre |
| --- | --- |
| Format non pris en charge ou image | Convertis la source en document pris en charge contenant du texte lisible. Importer une image seule ne lance pas d’OCR pour la recherche dans les connaissances. |
| Texte vide ou PDF scanné sans couche de texte | Ajoute le contenu manquant ou fournis une version traitée par OCR. Un fichier composé uniquement d’espaces et de sauts de ligne est également vide. |
| Données binaires sous une extension de texte | Exporte du texte lisible, de préférence en UTF-8. Renommer un fichier binaire en `.txt` ne le convertit pas. |
| PDF impossible à lire | Vérifie que l’original s’ouvre, retire sa protection par mot de passe si tu y es autorisé, ou exporte un nouveau PDF. Un fichier Office endommagé peut afficher une erreur d’indexation générale ; vérifie l’original avant de multiplier les essais. |
| Secret détecté ou règle sur les données personnelles | Retire les identifiants de la source ou demande à un administrateur de vérifier la règle signalée. Importe ensuite le contenu corrigé, ou relance après correction de la configuration. |
| Modèle d’embedding absent ou compte refusé par le fournisseur | Un administrateur doit configurer le modèle dans **Paramètres > Résidence des données**, ou corriger la clé, l’accès au modèle, l’offre ou le solde du compte. Relance ensuite. |
| Identifiants d’embedding manquants ou inutilisables | Les identifiants qu’utilise le modèle d’embedding ont été supprimés ou désactivés, le fournisseur n’a plus d’identifiants par défaut (**Paramètres > Résidence des données** affiche **Identifiants manquants**), ou leur secret est illisible : il a été enregistré avec une ancienne clé de chiffrement, ou les identifiants renvoient à une variable d’environnement que le serveur ne définit pas. Un administrateur ajoute ou répare les identifiants sous **Paramètres > Fournisseurs IA**, ou en choisit d’autres pour le modèle d’embedding. Chacun de ces enregistrements remet les documents concernés en file d’attente. Si la correction a eu lieu sur le serveur lui-même, par exemple en définissant la variable d’environnement, utilise **Relancer l'indexation**. |
| Panne temporaire du fournisseur ou du service d’indexation | Les traitements en arrière-plan retentent les échecs temporaires. Si l’erreur persiste, transmets le nom du document et le message à un administrateur. Après réparation, utilise **Relancer l'indexation**. |
| Reconstruction ou réparation du moteur de recherche | La reconstruction peut se terminer automatiquement. Si la réparation échoue, l’exploitant doit réparer ou restaurer la base de connaissances avant une nouvelle tentative. |

**Non pris en charge** ne propose pas de relance : traiter les mêmes octets ne corrigerait pas la cause. Un statut **Échoué** peut lui aussi nécessiter une modification de la source ou de la configuration. Une application distingue ces cas avec `indexing.errorCode` ; la [référence API](https://docs.tale.dev/fr/develop/api-reference) donne les codes stables.

<Frame caption="Le dialogue explique que ce document ne contient aucun texte à indexer. Ajoute du contenu lisible avant de l’importer à nouveau.">

![Le dialogue en anglais signale un document vide ou un scan sans couche de texte et recommande une version texte lisible.](https://docs.tale.dev/images/platform/document-indexing-unsupported.webp)

</Frame>

## Si les documents ne se chargent pas

**Documents** liste les dossiers et les documents à partir de deux chargements distincts. Quand les documents ne peuvent pas être chargés, Tale ne fait pas passer les dossiers pour l’ensemble du contenu :

- Les dossiers restent listés et tu peux toujours les ouvrir. Un avis au-dessus du tableau indique que les documents n’ont pas pu être chargés et propose **Réessayer**, qui relance le chargement sans que tu aies à recharger la page.
- Le décompte sous le tableau précise que seuls les premiers éléments sont affichés et que la suite n’a pas pu être chargée. Une recherche ne porte que sur ce qui est listé.
- Si des documents étaient déjà affichés quand une actualisation a échoué, ils restent en place, et l’avis indique que la liste est peut-être incomplète ou obsolète.
- Pendant la nouvelle tentative, les lignes restent affichées, et ta recherche, tes filtres et une boîte de dialogue ouverte sont conservés.
- Si rien ne peut être chargé, le tableau affiche l’erreur et **Réessayer** au lieu de l’état vide.

Un dossier qui ne contient vraiment aucun document affiche ses sous-dossiers sans avis. Si **Réessayer** échoue à chaque fois, demande à un administrateur de vérifier que les services de Tale fonctionnent.

## Choisir qui peut lire le document

Les documents de la bibliothèque sont accessibles à **Toute l'organisation** par défaut. Utilise **Assigner une équipe** dans le menu de la ligne pour restreindre l’accès aux équipes choisies : les membres de l’une d’elles peuvent lire le document, et les propriétaires et admins le peuvent toujours. Sauf si tu es propriétaire ou admin, tu ne peux choisir que des équipes dont tu fais partie. Un document rangé dans un dossier d’équipe reprend les équipes du dossier et ne peut pas en nommer une autre ; déplacer un document dans un tel dossier lui applique les équipes du dossier. Ces restrictions s’appliquent aussi à la recherche : un agent ne peut pas y rendre visible un document inaccessible.

La racine de la bibliothèque affiche les dossiers et les documents qui ne sont rangés dans aucun dossier. Ouvre un dossier pour consulter son contenu : les documents qu’il contient n’apparaissent pas aussi comme lignes de fichiers à la racine.

Les dossiers organisent la bibliothèque ; pour en renommer un, utilise **Renommer** dans son menu de ligne. Un dossier synchronisé, les dossiers qu’il contient et ceux qui le contiennent gardent leur nom, car chaque synchronisation reconstruit ce chemin. Vérifie l’accès dans **Équipes** et la provenance dans **Source**. Le filtre **Équipes** restreint la liste aux éléments accessibles à **Toute l'organisation**, à **Mes équipes** (tout ce qu’une de tes équipes peut voir) ou à une équipe par son nom ; la sélection fait partie de l’adresse de la page, ce qui permet de mettre une liste filtrée en favori. Les fichiers de projet ont leur propre périmètre et n’apparaissent pas dans cette bibliothèque. Consulte [Connaissances](https://docs.tale.dev/fr/platform/knowledge/overview) pour choisir où conserver une source.

## Importer depuis Microsoft 365 ou Google Drive

Choisis **Depuis Microsoft 365** ou **Depuis Google Drive** sous **Téléverser des documents**. À la première utilisation, connecte ton compte et autorise l’import. Si Tale indique qu’il n’est pas configuré, un administrateur doit préparer le service dans [Connecteurs](https://docs.tale.dev/fr/platform/admin/connectors).

Sélectionne les fichiers ou dossiers, puis le mode d’import :

| Mode | Résultat |
| --- | --- |
| **Importation unique** | Copie une fois la sélection en conservant les dossiers. Les changements ultérieurs de la source ne modifient pas cette copie. |
| **Importation synchronisée** | Maintient la sélection prise en charge à jour. Les nouveaux fichiers arrivent lors d’un prochain passage ; les fichiers modifiés sont réindexés ; ceux supprimés à la source disparaissent de la copie. |

Dans la bibliothèque, la colonne **Source** indique la provenance de chaque fichier. Un fichier importé porte le logo de OneDrive, SharePoint ou Google Drive. Des flèches circulaires à côté du logo signifient qu’une importation synchronisée tient le fichier à jour ; elles figurent aussi sur le dossier synchronisé lui-même. Les mêmes flèches barrées signalent une importation unique. Les fichiers téléversés, ceux qu’un agent ou une automatisation a créés, les entrées de connaissances et les imports par API ont chacun leur propre icône. Survole une icône pour lire la source en toutes lettres.

Démarrer la synchronisation d’un dossier peut aussi réorganiser un import antérieur. Si le même fichier source existe déjà dans Tale, la synchronisation reprend ce document et le déplace dans le dossier synchronisé correspondant, même si son contenu n’a pas changé. La correspondance repose sur l’identité du fichier source, pas uniquement sur son nom. Une synchronisation sans dossier de destination conserve l’emplacement existant.

Pour Microsoft 365, choisis **Mon OneDrive** ou **Sites SharePoint**. La synchronisation concerne les dossiers OneDrive personnels ; SharePoint s’importe une seule fois. Pour Google Drive, sélectionne dans Mon Drive. Les Docs, Sheets et Slides natifs sont ignorés : exporte-les d’abord en PDF ou au format Office.

Si un dossier est trop grand pour être listé entièrement, Tale refuse l’import. Sélectionne des sous-dossiers plus petits ou utilise la synchronisation lorsqu’elle est disponible. Si le dossier ou le fichier source sélectionné est supprimé, sa copie est retirée et la synchronisation prend fin.

À la fin d’un import, un avis indique le résultat. **Importation terminée** compte les fichiers que cet import a apportés, ainsi que ceux qu’un import précédent avait déjà apportés sans changement. Si certains fichiers n’ont pas pu être importés, un avertissement comme **3 sur 4 fichiers importés** s’affiche à la place. Quand le premier fichier en échec a une raison à montrer, par exemple un fichier qui dépasse la limite de téléversement, l’avertissement nomme ce fichier et cette raison. Si aucun fichier n’a pu être importé, l’avis indique **Échec de l'importation**. Si le sélecteur est encore ouvert, relance l’import pour réessayer les fichiers en échec. Les fichiers déjà importés sont ignorés.

Si l’accès à ton compte Microsoft 365 ou Google Drive prend fin pendant un import, par exemple parce que la connexion a été retirée ou a expiré, Tale ouvre **Reconnecter Microsoft 365** ou **Reconnecter Google Drive** au lieu d’un avis tant que le sélecteur d’import est encore ouvert. Le dialogue indique combien de fichiers ont été importés avant la fin de l’accès ; ces fichiers restent en place. Reconnecte ton compte, puis importe à nouveau les mêmes fichiers ou dossiers pour récupérer le reste. Les fichiers déjà importés ne sont pas importés une seconde fois.

Fermer le sélecteur n’annule pas un import déjà lancé. Son résultat apparaît dans un avis. Un sélecteur ouvert entre-temps reste ouvert et ta nouvelle sélection est conservée. Si l’accès a pris fin, ouvre à nouveau l’import pour reconnecter ton compte.

Une synchronisation s’exécute environ toutes les 15 minutes, avec le compte du membre qui l’a configurée. Un fichier ajouté à la source apparaît dans son dossier dans ce délai, puis est indexé comme un fichier déposé. Quand un passage n’atteint pas la source, la cellule **Source** de la ligne du dossier remplace les flèches circulaires par un panneau d’avertissement rouge dont l’infobulle indique **Sync en échec**, ou par une prise débranchée rouge indiquant **À reconnecter** si la connexion Microsoft 365 ou Google Drive de ce membre a expiré. L’icône ouvre la cause, le début des échecs et le compte utilisé par la synchronisation ; les fichiers déjà synchronisés restent en place. Ce membre est aussi prévenu par la cloche et par e-mail : immédiatement pour une connexion expirée, sinon dès que la synchronisation échoue depuis une heure. Reconnecter le compte, ce que le dialogue propose à ce membre, relance la synchronisation au passage suivant. Tout membre autorisé à importer des documents peut plutôt lancer une nouvelle importation synchronisée du même élément pour l’exécuter avec son propre compte. L’avis disparaît au passage réussi suivant.

Pour conserver les fichiers sans nouvelles mises à jour, choisis **Arrêter la synchronisation** sur la ligne du fichier ou du dossier. Supprimer l’élément importé arrête aussi sa synchronisation. Ces actions ne touchent pas les originaux dans OneDrive ou Google Drive. **Déconnecter Google Drive** dans le dialogue d’import révoque la connexion ; reconnecte-toi pour importer à nouveau.

## Réviser un document maîtrisé

Utilise un document maîtrisé quand l’approbation doit rester liée au fichier exact que le relecteur a vu. Remplacer le fichier de son brouillon met à jour l’enregistrement existant ; téléverser un autre fichier du même nom crée toujours un document distinct.

<Steps>

<Step title="Choisir le document maîtrisé">

Pour un téléversement ordinaire, ouvre le menu de la ligne et clique sur **Marquer comme document maîtrisé**. L’enregistrement passe à `v1 · Brouillon`. Un document approuvé propose **Remplacer le fichier** et **Nouvelle révision**. Utilise **Nouvelle révision** seulement si tu veux ouvrir le brouillon suivant sans remplacer son fichier.

</Step>

<Step title="Remplacer le fichier actuel">

Ouvre le menu de la ligne d’un brouillon ou d’un document approuvé et clique sur **Remplacer le fichier**, puis choisis un fichier au même format. Un brouillon garde sa révision actuelle. Pour un document approuvé, Tale conserve la vN approuvée et n’ouvre le brouillon vN+1 qu’une fois le remplacement terminé ; si tu annules ou si le téléversement échoue, la vN reste approuvée. Une conservation légale bloque les deux parcours.

<Frame caption="La boîte de dialogue accepte un seul fichier au format actuel du document.">

![La boîte de dialogue « Remplacer le fichier » d’un document texte maîtrisé, avec un sélecteur de fichier au même format et un rappel que les versions approuvées restent dans l’historique.](https://docs.tale.dev/images/platform/controlled-document-replace-file.webp)

</Frame>

</Step>

<Step title="Vérifier et soumettre la révision">

Ouvre l’aperçu du document et vérifie qu’il affiche le fichier de remplacement. Ouvre ensuite le menu de la ligne et clique sur **Soumettre à la relecture**. Le sélecteur ne propose que les membres qui peuvent réellement ouvrir le document — un fichier de projet exige l’accès en édition au projet — et jamais toi. Seul le relecteur que tu désignes peut approuver ou demander des modifications, chaque relecture est donc un second regard.

Tale fige le brouillon pendant que le relecteur statue sur ce fichier exact ; le relecteur est prévenu par la cloche et par e-mail, et la décision te revient par le même chemin — une demande de modifications porte le retour du relecteur, que la boîte de dialogue de soumission affiche aussi avant ta prochaine tentative.

Si le relecteur ne peut plus statuer — il a quitté l’organisation, a été désactivé ou a perdu l’accès au document —, ouvre le menu de la ligne et clique sur **Changer de relecteur** : la demande en attente passe au membre que tu désignes, et l’enregistrement reste figé sur le même fichier.

</Step>

</Steps>

## Examiner le contenu avant de supprimer

**Supprimer** retire le document et son contenu indexé. La confirmation explique les conséquences ; garde une copie si tu auras besoin du fichier plus tard. Un nouvel import crée un nouveau document.

<Warning>

Supprimer un dossier retire définitivement ses fichiers et sous-dossiers. Pour un dossier synchronisé, cela retire aussi la configuration et l’historique de synchronisation. Les originaux dans Microsoft 365 ou Google Drive restent intacts.

</Warning>

Un document maîtrisé avec une version approuvée est protégé contre la suppression, y compris pendant la préparation d’un nouveau brouillon. Son menu affiche **Document maîtrisé protégé**. Un dossier qui en contient un ne peut pas non plus être supprimé. Une conservation légale peut également bloquer les modifications ou la suppression. Demande à un administrateur de vérifier la restriction au lieu de la contourner par des imports en double.

# Entrées de connaissances
Source: https://docs.tale.dev/fr/platform/knowledge/knowledge-entries

Une entrée de connaissances convient à une information courte que tes collègues doivent pouvoir retrouver : horaires du support, délai de retour ou responsable d’un processus. Elle comporte un sujet et un contenu. Pour une politique complète ou un rapport, choisis un [document](https://docs.tale.dev/fr/platform/knowledge/documents). Pour des champs nommés et des valeurs exactes, utilise les [données structurées](https://docs.tale.dev/fr/platform/knowledge/structured-data).

Les membres peuvent lire les entrées. Le rôle Éditeur ou supérieur est nécessaire pour les créer, les modifier et les supprimer. Elles font partie des connaissances partagées de l’organisation : réserve tes notes personnelles et les informations destinées à un seul projet à un autre espace.

## Ajouter une information

<Steps>

<Step title="Ouvrir le formulaire">

Va dans **Connaissances > Entrées de connaissances**, puis clique sur **Ajouter une entrée**. Si l’action n’apparaît pas, demande à un administrateur de vérifier ton rôle.

</Step>

<Step title="Choisir un sujet durable">

Dans **Sujet**, saisis par exemple `Délai de réponse du support`. Choisis un nom qui restera pertinent si la réponse change. Le sujet est limité à 120 caractères et doit être unique. Si Tale signale un doublon, modifie l’entrée existante.

</Step>

<Step title="Donner le contexte nécessaire">

Dans **Contenu**, indique l’information, son périmètre et ses conditions. Le Markdown est accepté, jusqu’à 8 000 caractères. Par exemple :

```markdown
Le support vise une première réponse sous 45 minutes pendant les heures
ouvrées : du lundi au vendredi, de 09:00 à 17:00 CET. Il s’agit d’un objectif
de réponse, pas d’un délai de résolution. Responsable : Support Operations.
```

Évite les dates relatives comme « vendredi prochain » et les renvois comme « la politique ci-dessus ». L’entrée doit rester compréhensible lorsqu’elle est consultée seule.

</Step>

<Step title="Enregistrer et vérifier l’indexation">

Clique sur **Enregistrer**. La ligne affiche le sujet, le contenu, la source (**Manuel** pour le formulaire, **Chat** pour une information captée par l’assistant, **API** pour une information écrite par une intégration via REST), le statut d’indexation et la date de mise à jour. Ouvre-la pour lire le texte intégral. L’indexation s’effectue en arrière-plan : une entrée enregistrée n’est pas immédiatement disponible dans la recherche.

</Step>

</Steps>

<Frame caption="Le tableau permet de vérifier l’information et son indexation avant de s’appuyer dessus dans une réponse.">

![Le tableau des entrées de connaissances présente des informations manuelles avec sujet, contenu, source, statut d’indexation et date de mise à jour.](https://docs.tale.dev/images/platform/knowledge-entries-list.webp)

</Frame>

## Corriger une information existante

Dans le menu de la ligne, choisis **Modifier**, corrige le contenu et clique sur **Enregistrer**. Cela crée une nouvelle version courante et programme l’indexation de son texte. Chaque sujet possède une seule entrée courante ; corriger l’entrée existante évite les réponses contradictoires.

Après une correction, ouvre les détails pour consulter l’**Historique des versions**. Les anciennes versions permettent de retrouver ce qui a changé et leur date de remplacement. Elles ne constituent pas des informations courantes supplémentaires. Pour une entrée jamais modifiée, l’historique indique qu’il n’existe encore aucune version précédente. L’**ID de version** affiché dans les détails appartient à la version courante et change à chaque modification ; c’est le sujet qui identifie l’entrée d’une version à l’autre. Une application peut également créer et modifier des entrées via l’[API REST](https://docs.tale.dev/fr/develop/api-reference).

<Tip>

Lorsqu’un chat fait ressortir une information utile, vérifie-la à la source, puis ajoute ou modifie l’entrée toi-même. Chat n’enregistre pas automatiquement les faits dans les connaissances de l’organisation.

</Tip>

## Retirer une entrée obsolète

Choisis **Supprimer** dans le menu de la ligne et lis la confirmation. L’entrée et ses versions disparaissent de cette vue ; le document associé n’est plus disponible pour la recherche dans les connaissances. Garde une copie du texte avant la suppression si tu en as encore besoin. Pour une correction, utilise **Modifier**.

## Si l’information manque dans une réponse

Vérifie d’abord l’entrée courante : est-elle enregistrée et indexée ? La question désigne-t-elle clairement son sujet ? Si l’indexation a échoué, résous la cause indiquée avant de la relancer. En cas d’échecs répétés, un administrateur doit vérifier la configuration des embeddings et les services d’indexation.

Demande une citation à l’assistant, ouvre la source et compare-la à l’entrée. Une réponse plausible ne prouve pas qu’elle utilise la dernière information. La page [Documents](https://docs.tale.dev/fr/platform/knowledge/documents) détaille les états d’indexation communs.

## Si la liste ou l’historique ne se charge pas

Quand un chargement échoue, Tale le signale à l’endroit où le contenu devrait apparaître. L’échec n’apparaît jamais comme une bibliothèque vide ni comme une entrée sans historique. **Réessayer** relance le chargement sans que tu aies à recharger la page :

- Si aucune entrée ne peut être chargée, le tableau affiche l’erreur et **Réessayer** au lieu de l’état vide.
- Si des entrées sont déjà affichées, elles restent en place, et un avis au-dessus du tableau indique que la liste est peut-être incomplète ou obsolète. Ta recherche et les lignes sélectionnées sont conservées pendant la nouvelle tentative. Si d’autres entrées n’ont pas pu être chargées, le décompte sous le tableau le précise, et une recherche ne porte que sur les entrées chargées.
- Dans les détails d’une entrée, si l’**Historique des versions** ne peut pas être chargé, la section le signale et propose **Réessayer**. Le contenu actuel reste lisible.

Si **Réessayer** échoue à chaque fois, demande à un administrateur de vérifier que les services de Tale fonctionnent.

# Connaissances
Source: https://docs.tale.dev/fr/platform/knowledge/overview

Connaissances est la bibliothèque partagée de ton organisation. Documents, informations courtes, sites publics, contacts et produits donnent aux personnes et aux agents des sources communes. Commence par les informations nécessaires pour répondre à une vraie question. Une petite collection tenue à jour est plus facile à vérifier qu’une archive non relue.

<Video src="https://docs.tale.dev/videos/fr/tutorials/ep3-knowledge/ep3-knowledge.fr.mp4" poster="https://docs.tale.dev/videos/fr/tutorials/ep3-knowledge/ep3-knowledge.fr.webp" captions="https://docs.tale.dev/videos/fr/tutorials/ep3-knowledge/ep3-knowledge.fr.vtt" lang="fr" title="Épisode 3 — Connaissances" caption="Épisode 3 — Connaissances (2:45)">

</Video>

<Frame caption="Commence par Documents pour les fichiers, ou ouvre la page adaptée à ta source. Le filtre ne conserve que les fichiers chargés et indexés.">

![L’espace Connaissances présente les onglets Documents, Entrées de connaissances, Sites web, Produits et Contacts au-dessus du tableau des fichiers partagés.](https://docs.tale.dev/images/get-started/documents-list.webp)

</Frame>

## Choisir le bon emplacement

| Tu disposes de | Utilise | Pourquoi |
| --- | --- | --- |
| Une politique, un guide, un tableur ou un rapport | **Documents** | Conserve le fichier d’origine et retrouve les passages des formats pris en charge. |
| Une information courte, comme les horaires du support | **Entrées de connaissances** | Un sujet durable permet de maintenir une seule réponse courante. |
| Des pages publiques qui évoluent | **Sites web** | Explore un site entier ou une liste d’URL à intervalle régulier. |
| Des personnes, des organisations et leurs coordonnées | **Contacts** | Conserve les noms et les autres champs dans des fiches structurées. |
| Des articles avec leurs caractéristiques | **Produits** | Consulte les champs de la fiche au lieu de rechercher un paragraphe. |
| Des fichiers de référence pour un travail précis | L’onglet **Connaissances** du projet | Garde les fichiers dans le périmètre d’accès et le contexte de ce projet. |

Les membres peuvent lire les contenus auxquels ils ont accès. Les rôles Éditeur et supérieurs entretiennent la bibliothèque commune. Ouvre une ligne ou choisis **Voir** dans son menu pour afficher ses détails. Si tu peux modifier une source, ce même menu propose les actions correspondantes, comme **Supprimer** ; les contacts, produits, sites web et entrées de connaissances y proposent aussi **Modifier**, que tu retrouves dans leurs détails. Le guide des [données structurées](https://docs.tale.dev/fr/platform/knowledge/structured-data) aide à choisir lorsqu’un tableur peut servir de document source ou de collection de fiches.

## Préparer une source pour les réponses

Importer ou enregistrer n’est que la première étape. Les documents, les entrées et les pages web doivent aussi être **indexés** : Tale en extrait le texte et le prépare pour la recherche. Vérifie le statut avant de poser une question sur un nouveau contenu. Un fichier peut rester téléchargeable même si son format ne permet pas l’indexation.

Choisis un titre clair et indique les dates et le périmètre dans le contenu. Corrige ou retire les consignes dépassées. Si deux sources se contredisent, précise laquelle fait référence et vérifie la citation. Ajouter des fichiers ne résout pas cette contradiction.

<Tip>

Teste une nouvelle source avec une question dont tu connais la réponse : « Quels sont les horaires de notre support ? Cite la source. » Ouvre la source citée et compare la réponse. Ce contrôle est plus précis qu’une demande de résumé général de toute la bibliothèque.

</Tip>

## Comprendre l’accès et la recherche

Le chat de l’organisation peut rechercher dans la bibliothèque commune selon tes droits. Le chat d’un projet peut aussi consulter les fichiers de ce projet et utilise ses instructions enregistrées. Il ne recherche pas dans les fichiers d’un autre projet. Les agents de projet doivent être équipés des outils de plateforme correspondants.

Les restrictions par équipe s’appliquent aussi à la recherche. Un fichier visible dans un espace peut donc manquer dans le contexte d’un autre projet. Utilise les [fichiers de projet](https://docs.tale.dev/fr/platform/projects/manage-files) pour les contenus propres à un projet et l’affectation aux équipes pour les documents de la bibliothèque commune.

Si toutes les recherches échouent, demande à un administrateur de vérifier le modèle d’embeddings et la connexion aux connaissances dans **Paramètres > Résidence des données**. Les détails destinés aux exploitants figurent dans [Résidence des données](https://docs.tale.dev/fr/self-hosted/configuration/data-residency).

## Entretenir chaque source

<CardGroup cols="2">

<Card title="Documents" icon="file-text" href="https://docs.tale.dev/fr/platform/knowledge/documents">
Importe des fichiers, vérifie leur indexation et gère les révisions approuvées.
</Card>

<Card title="Entrées de connaissances" icon="book-open" href="https://docs.tale.dev/fr/platform/knowledge/knowledge-entries">
Ajoute une information courte, corrige-la et consulte son historique.
</Card>

<Card title="Sites web" icon="globe" href="https://docs.tale.dev/fr/platform/knowledge/crawling">
Choisis les pages à explorer, règle l’intervalle et examine les pages manquantes.
</Card>

<Card title="Données structurées" icon="table" href="https://docs.tale.dev/fr/platform/knowledge/structured-data">
Choisis des fiches pour les champs exacts et des documents pour les explications.
</Card>

</CardGroup>

# Choisir entre documents et fiches structurées
Source: https://docs.tale.dev/fr/platform/knowledge/structured-data

Utilise des documents quand l’information demande une explication en plusieurs paragraphes, comme un contrat ou un compte rendu. Choisis une fiche structurée quand elle tient dans des champs nommés, comme l’adresse e-mail d’un contact ou la référence d’un produit. Les deux se complètent : la fiche identifie le sujet, les documents apportent son contexte.

## Choisir où ranger l’information

| Information | Emplacement | Intérêt |
| --- | --- | --- |
| Politique, contrat, manuel ou compte rendu | **Documents** | Tale recherche dans le texte et en extrait les passages pertinents. |
| Information courte avec son propre historique | **Entrées de connaissances** | Un sujet possède une version courante, et les versions précédentes sont conservées. |
| Personne ou organisation avec laquelle tu travailles | **Contacts** | Les champs regroupent les coordonnées dans une fiche modifiable. |
| Produit et ses caractéristiques | **Produits** | Les données restent dans des champs au lieu d’être enfouies dans un fichier. |
| Pages d’un site public | **Sites web** | Tale les explore et actualise leur contenu consultable à intervalle régulier. |
| Fichiers de référence pour un projet | Onglet **Connaissances** du projet | L’accès dépend du projet, et ses chats peuvent retrouver les fichiers. |

Le mode de stockage détermine la façon dont Tale retrouve l’information. Trouver un passage ne signifie pas que tout le document a été examiné. Lire les champs d’une fiche fournit leurs valeurs à Tale, sans garantir qu’elles sont à jour ni que la réponse qui en découle est correcte.

## Associer les fiches aux documents utiles

Pour préparer un appel avec Acme, conserve ses coordonnées dans **Contacts** et son contrat ainsi que les comptes rendus dans **Documents**, ou dans l’onglet **Connaissances** du projet concerné.

Demande à l’assistant de retrouver la fiche d’Acme et de résumer les questions ouvertes dans les dernières notes. Vérifie l’adresse e-mail dans la fiche et les décisions dans les notes citées. Si les fichiers appartiennent à un projet, démarre le chat dans ce projet.

<Tip>

Garde le même nom de société ou de produit dans les fiches et les fichiers associés. Ajoute une date aux comptes rendus et un numéro de révision aux politiques pour distinguer les sources actuelles des anciennes.

</Tip>

## Créer une fiche contact

Le rôle Rédacteur ou un rôle supérieur est nécessaire pour modifier les fiches de l’organisation. Ouvre **Connaissances > Contacts**, choisis **Ajouter un contact**, puis **Saisie manuelle**.

1. Renseigne le **Courriel** du contact. Ajoute un **Nom** et un **Téléphone** si nécessaire.
2. Vérifie **Langue**, dont la valeur initiale est `en`, et adapte-la à la langue du contact.
3. Choisis **Enregistrer**. La fiche apparaît dans Contacts avec ses coordonnées et sa date d’ajout.

Avant d’enregistrer, le formulaire vérifie chaque champ selon ce que Tale conserve : un **Nom** de 300 caractères au plus, un **Téléphone** de 50 au plus, une **Langue** de 20 au plus et un **Courriel** d’au plus 64 caractères avant le `@`. Une valeur qui dépasse une limite est signalée sous son champ, et rien n’est enregistré tant que tu ne l’as pas corrigée.

Pour n’afficher que les contacts d’une langue, choisis **Filtre** au-dessus de la liste des contacts, puis la langue sous **Langue**. Une langue inclut ses variantes régionales : **FR** affiche les contacts dont la langue est `fr`, `fr-CH` ou `fr_CA`. Un contact sans langue n’apparaît que tant qu’aucune langue n’est choisie.

Tu peux aussi créer une fiche au moment d’écrire. Dans la vue **Réception** d’**Accueil**, choisis **Nouvel e-mail** et saisis une adresse dans **À** : si aucun contact ne la porte, la liste propose **Ajouter « … » comme contact**, ce qui ouvre ce même formulaire avec le **Courriel** déjà renseigné. Une fois la fiche enregistrée, ce contact devient le destinataire : tu ne quittes jamais le message en cours.

Si cette adresse existe déjà, retrouve la fiche et modifie-la depuis le menu de sa ligne ; depuis **Nouvel e-mail**, Tale sélectionne pour toi le contact existant. Enregistrer un contact crée uniquement une fiche ; cette opération ne lui envoie aucun e-mail.

Tu peux modifier ou supprimer les contacts que ton équipe a saisis ou importés ici, un par un depuis le menu de la ligne. Pour en supprimer plusieurs à la fois, coche leurs lignes, puis choisis **Supprimer la sélection**. Les contacts issus d’une intégration, de l’API ou d’une conversation appartiennent à leur source, qui écraserait une modification faite ici : le menu de leur ligne ne propose ni **Modifier** ni **Supprimer**, et leurs lignes n’ont pas de case à cocher.

## Créer une fiche produit

<Frame caption="Connaissances > Produits : chaque produit est une fiche aux champs nommés pour le stock, le prix, la catégorie et le statut.">

![L’onglet Produits de Connaissances liste trois produits : Team training workshop, 12 en stock à 950,00 dollars US dans Services, marqué comme brouillon, ainsi qu’Onboarding accelerator à 1 900,00 dollars US dans Services et Analytics Pro — annual license à 1 188,00 dollars US dans Licenses, tous deux actifs.](https://docs.tale.dev/images/platform/knowledge-products-list.webp)

</Frame>

Ouvre **Connaissances > Produits**, choisis **Ajouter un produit**, puis **Saisie manuelle**. Le formulaire comporte trois étapes.

1. Dans **Bases**, saisis le **Nom du produit**. Ajoute une description et une image si elles aident à l’identifier, puis choisis **Suivant**.
2. Dans **Prix et stock**, vérifie ensemble le **Prix** et la **Devise**. Par exemple, saisis `12.50` et sélectionne `CHF`. Changer la devise ne convertit pas le montant. Renseigne le stock et la catégorie si nécessaire, puis vérifie le **Statut**. Un nouveau produit commence comme **Brouillon**.
3. Dans **Vérification**, relis les données et choisis **Créer**. Le tableau affiche le produit avec son prix, son statut et sa date de mise à jour.

Le menu de la ligne permet de modifier un produit enregistré. Choisis des noms faciles à distinguer et vérifie le prix ainsi que la devise avant de changer le statut.

Choisis **Téléverser une image** ou dépose un fichier PNG, JPEG, WebP, GIF ou SVG dans la zone d’image. La limite est de 5 Mio. Attends l’aperçu avant de poursuivre. Tale vérifie le contenu du fichier ; s’il le refuse, le message sous le champ d’image en donne la raison — un format non pris en charge, un fichier au-delà de la limite ou un SVG contenant des scripts ou des gestionnaires d’événements — pour que tu saches si un autre fichier est nécessaire.

L’image reste disponible après l’enregistrement et le rechargement du produit. Une fois le produit enregistré, les autres membres de l’organisation ayant accès aux produits peuvent la voir. Son adresse exige une session connectée et ne constitue pas un lien de partage public. Pour la retirer, modifie le produit, choisis **Supprimer l'image**, puis enregistre. Retirer ou remplacer l’image, ou supprimer le produit, supprime aussi le fichier téléversé lui-même, sauf si un autre produit l’affiche encore.

Si tu choisis **Ou coller une URL**, saisis une adresse HTTPS publique complète, qui commence par `https://`. Le formulaire signale une adresse incomplète sous le champ avant que tu puisses continuer. Tale refuse les hôtes non sûrs ou non autorisés. Demande à un administrateur si tu as besoin d’une source d’image interne. Les images chargées depuis une adresse externe restent soumises aux règles d’accès de cette source.

## Vérifier l’accès et l’actualité

Une fiche ou un document n’est utile qu’aux personnes qui y ont accès. Vérifie les équipes associées lorsqu’un collègue ne trouve pas une information. Les fichiers d’un projet suivent les droits du projet, et non les équipes de la bibliothèque documentaire ; consulte [Fichiers du projet](https://docs.tale.dev/fr/platform/projects/manage-files).

Mets à jour la fiche de référence lorsqu’une donnée change. Après la révision d’un document, attends la fin de l’indexation avant de tester une question sur le nouveau texte. Le contenu d’un site suit son intervalle d’exploration et peut donc différer de la page en ligne.

## Utiliser les types de fiches disponibles

L’espace de connaissances propose Contacts, Produits et Sites web. **Paramètres > Gouvernance > Modèles** règle l’accès aux modèles d’IA et les choix par défaut. Cette page ne crée ni types de fiches personnalisés ni champs de base de données.

Si les champs disponibles ne conviennent pas, conserve les détails dans un document et rattache ton processus à la fiche appropriée. Pour importer des données par programme et connaître les champs acceptés, consulte la [référence API](https://docs.tale.dev/fr/develop/api-reference).

La page [Documents](https://docs.tale.dev/fr/platform/knowledge/documents) explique comment importer et vérifier un fichier. [Entrées de connaissances](https://docs.tale.dev/fr/platform/knowledge/knowledge-entries) couvre la mise à jour d’une information, et [Exploration de sites](https://docs.tale.dev/fr/platform/knowledge/crawling) le suivi des pages publiques.

# Installer Tale comme application
Source: https://docs.tale.dev/fr/platform/member/install-as-app

Installe Tale pour disposer d’une icône et d’une fenêtre dédiée. Utilise la même adresse Tale et le même compte que dans ton navigateur. L’installation ne crée pas une autre organisation et ne copie pas tes chats dans un nouveau compte.

## Installer sur ordinateur ou Android

Ouvre ton instance Tale dans un navigateur compatible. Depuis ton nom ou ton avatar, ouvre le menu du compte et choisis **Installer l'app**, puis accepte la demande du navigateur. Tale affiche cette action lorsque le navigateur propose l’installation.

Si l’action manque, consulte le menu du navigateur. Sur ordinateur, Chrome propose l’installation d’une page comme application dans **Caster, enregistrer et partager**. Les libellés varient selon le navigateur et l’appareil. Le [guide des applications Chrome](https://support.google.com/chrome/answer/9658361?hl=fr) explique leur installation et leur gestion.

Ouvre la nouvelle icône et vérifie qu’elle mène à la bonne instance Tale. Connecte-toi si nécessaire, puis vérifie l’organisation dans le menu du compte. Un profil de navigateur et une application installée peuvent avoir des sessions différentes.

## Installer sur iPhone ou iPad

Sur iOS, **Installer l'app** ouvre des instructions dans le menu du compte Tale. Le navigateur réalise l’installation.

Dans Safari, ouvre Tale, choisis **Partager > Sur l’écran d’accueil**, puis confirme avec **Ajouter**. Si **Ouvrir comme app web** apparaît, laisse cette option activée pour obtenir une fenêtre autonome. Le [guide iPhone d’Apple](https://support.apple.com/guide/iphone/open-as-web-app-iphea86e5236/ios) présente les commandes actuelles.

D’autres navigateurs iOS peuvent aussi proposer l’ajout à l’écran d’accueil. Si le tien ne le propose pas, ouvre la même adresse dans Safari. Après l’installation, les cookies de l’application peuvent être séparés de ceux du navigateur : une déconnexion dans une fenêtre ne ferme donc pas forcément l’autre session. [WebKit explique cette séparation](https://webkit.org/blog/14787/webkit-features-in-safari-17-2/).

## Comprendre ce qui change

L’organisation, les droits et les contenus enregistrés restent sur l’instance Tale. L’installation change la façon de lancer et d’afficher l’application. Elle n’installe pas de modèle local et ne rend pas les fonctions serveur disponibles sans connexion.

Les notifications dépendent toujours du navigateur, du système, de l’autorisation accordée et de tes préférences Tale. Installer l’application ne donne pas automatiquement cette autorisation. Vérifie-la après un changement d’appareil ou une réinstallation.

## Retirer l’application installée

Utilise **Désinstaller** ou **Supprimer l’app** dans le navigateur ou le système. Retirer une icône du Dock de macOS ne supprime que son raccourci. Dans Chrome, utilise le menu de l’application ou `chrome://apps`. Effacer ses données de navigation peut aussi fermer ta session.

La désinstallation ne supprime ni ton compte Tale, ni l’organisation, ni les documents stockés sur le serveur. Pour modifier ton compte, consulte [Profil et compte](https://docs.tale.dev/fr/platform/member/preferences). Sur un appareil partagé, déconnecte-toi de l’application et des sessions de navigateur utilisées.

## Si l’installation est indisponible

| Observation | Action |
| --- | --- |
| Aucune action **Installer l'app** | Vérifie le menu d’installation du navigateur et si l’application est déjà installée. |
| Aucune option dans un navigateur privé ou administré | Essaie une fenêtre normale ou demande la politique d’installation à l’administrateur de l’appareil. |
| L’icône ouvre la mauvaise instance | Vérifie l’adresse dans le navigateur d’origine, puis installe l’instance voulue. |
| L’application s’ouvre sans charger le contenu | Vérifie l’accès réseau et le fonctionnement de l’instance Tale. |

# Membre
Source: https://docs.tale.dev/fr/platform/member/overview

En tant que Membre, tu poses des questions dans Chat et lis les connaissances et contenus de projet partagés avec toi. La configuration de l’organisation et tes équipes déterminent les ressources visibles. Tu peux aussi créer des tâches de projet et y faire travailler les agents du projet, entretenir tes préférences de compte et créer des skills réutilisables.

## Commencer ta journée

<CardGroup cols="2">

<Card title="Poser une question utile" icon="message-circle" href="https://docs.tale.dev/fr/tutorials/member/chat-effectively">

Exerce-toi avec une source, vérifie les faits et pose une relance.

</Card>

<Card title="Lire les connaissances partagées" icon="library" href="https://docs.tale.dev/fr/platform/knowledge/overview">

Retrouve documents, informations et fiches, et comprends pourquoi une source peut manquer.

</Card>

<Card title="Comprendre les projets" icon="folder-open" href="https://docs.tale.dev/fr/platform/projects/concepts">

Distingue les fichiers et conversations du projet des chats qui restent personnels.

</Card>

<Card title="Gérer ton compte" icon="user" href="https://docs.tale.dev/fr/platform/member/preferences">

Modifie ton profil, consulte tes limites d’utilisation et comprends les préférences enregistrées et la gestion des chats.

</Card>

</CardGroup>

Passe d’une activité à l’autre avec la [navigation principale](https://docs.tale.dev/fr/platform#navigation). Chaque section s’ouvre sur sa première page ; sur ordinateur, **Accueil** rouvre plutôt le chat que tu as lu en dernier, et le choisir à nouveau démarre un nouveau chat. [Accueil](https://docs.tale.dev/fr/platform#home) liste aussi tes projets, les tâches ouvertes qui te sont attribuées ou qui attendent ta relecture, et la boîte de réception si ton organisation en a une.

## Confier du travail à un agent de projet

Quand tu as besoin d’un livrable, par exemple la synthèse de plusieurs contrats ou un document traduit, ouvre un projet auquel tu as accès et crée une tâche dans son onglet **Tâches**. Décris le résultat attendu et la façon dont tu le vérifieras, joins les fichiers nécessaires et attribue la tâche à l’un des agents du projet. **Démarrer l'agent** le met au travail : l’agent rend compte dans les commentaires de la tâche et la passe à **En revue**. Lis son compte rendu, ouvre les livrables, puis passe la tâche à **Terminé** lorsque tu acceptes le résultat.

Tu peux modifier les tâches que tu as créées et celles qui te sont attribuées. Sur les tâches des autres, tu lis et tu commentes. La configuration des agents eux-mêmes, comme les paramètres et les fichiers du projet, reste réservée aux Éditeurs. [Gérer les tâches d’un projet](https://docs.tale.dev/fr/platform/projects/tasks#qui-peut-creer-et-modifier-les-taches) et [Déléguer une tâche à un agent](https://docs.tale.dev/fr/platform/projects/task-automation) entrent dans le détail.

## Ouvrir une notification

Un lien de notification ouvre la tâche, le document ou la conversation concernée. Si tu dois d’abord te connecter, Tale conserve la destination et l’ouvre après la connexion. Ton compte doit toujours avoir accès à l’organisation et au contenu. Pour un déploiement privé, connecte-toi au réseau requis avant d’ouvrir le lien.

## Si une action manque

Les Membres lisent la bibliothèque commune ; les Éditeurs et rôles supérieurs en entretiennent le contenu. Dans un projet, tu modifies les tâches que tu as créées ou qui te sont attribuées ; ses paramètres, ses agents et ses fichiers restent réservés aux Éditeurs. Les automatisations et les réglages techniques nécessitent des droits de Développeur ou d’administrateur : les Membres et les Éditeurs ne voient donc pas du tout **Automatisations**. Demande l’accès adapté à ta tâche : une ressource visible n’est pas forcément modifiable. [Membres et rôles](https://docs.tale.dev/fr/platform/admin/members-and-roles) explique les différences.

# Gérer ton compte et tes préférences
Source: https://docs.tale.dev/fr/platform/member/preferences

Les réglages du compte déterminent le nom visible par tes collègues et ta façon de te connecter. Le menu de profil permet aussi de changer d’organisation et de langue, et affiche les équipes dont tu fais partie. Ces commandes sont accessibles sans rôle d’admin.

## Modifier le nom visible par tes collègues

Ouvre **Paramètres > Compte**. Sous **Profil**, modifie **Nom**, puis clique sur **Enregistrer** en haut de la page. La commande d’abandon restaure la valeur enregistrée. L’adresse e-mail reste en lecture seule, car elle identifie le compte utilisé pour la connexion et les notifications.

Ton nom est visible par les collègues et ne doit pas dépasser 100 caractères. Ce n’est pas une instruction privée destinée à l’assistant.

## Protéger la connexion

La section **Mot de passe** propose **Changer le mot de passe**, ou **Définir le mot de passe** si ton compte n’en possède pas encore. Respecte les exigences affichées dans le dialogue. Elles proviennent de la politique de mot de passe de ton organisation. Si tu appartiens à plusieurs organisations, ton mot de passe doit respecter les exigences de chacune d’elles. Changer le mot de passe ferme tes sessions : garde le nouveau à portée de main avant de confirmer. Un mot de passe actuel erroné compte pour le verrouillage temporaire, comme un échec de connexion.

Configure une application sous **Authentification à deux facteurs** ou ajoute une passkey dans la section correspondante. Conserve les codes de secours dans un endroit accessible sans connexion à Tale. [Authentification à deux facteurs](https://docs.tale.dev/fr/platform/admin/two-factor-authentication) couvre la configuration, la récupération et les exigences de l’organisation.

## Changer de langue ou d’espace de travail

Ouvre le menu de profil depuis ton avatar. **Langue** change la langue de l’interface. Si tu appartiens à plusieurs organisations, **Organisation** change d’espace de travail. La ligne **Équipes** nomme tes équipes et ouvre la page du compte ; elle ne bascule vers rien, car une équipe n’est pas un espace de travail.

Vérifie le nom de l’organisation avant de modifier des réglages ou d’ajouter du contenu.

## Voir ton rôle {#role}

**Paramètres > Compte > Ton rôle** affiche ton rôle dans cette organisation, par exemple Éditeur ou Membre. Ton rôle détermine ce que tu peux faire ; tes équipes déterminent quels contenus d’équipe tu vois. Les admins attribuent les rôles dans [Membres et rôles](https://docs.tale.dev/fr/platform/admin/members-and-roles). Avec l’authentification unique, ton fournisseur d’identité peut aussi définir ton rôle à chaque connexion. Les propriétaires et les admins voient le bouton **Gérer les membres** à côté du titre de la section.

## Voir tes équipes {#teams}

**Paramètres > Compte > Tes équipes** liste les équipes dont tu fais partie. Les équipes déterminent quels documents d’équipe, projets et files de la boîte de réception tu vois ; ce qui est partagé avec toute l’organisation te reste visible dans tous les cas. Si tu n’es dans aucune équipe, la section le dit. Si tes équipes ne peuvent pas être chargées, la section l’indique au lieu d’affirmer que tu n’es dans aucune équipe. Choisis **Réessayer** pour les charger. Quand une actualisation échoue, les équipes déjà affichées restent visibles, avec un message indiquant qu’elles ne sont peut-être plus à jour.

Pour restreindre une liste à certains travaux, utilise son filtre **Équipes** : **Toute l'organisation** n’affiche que les éléments sans équipe, **Mes équipes** affiche ceux qu’une de tes équipes peut voir, et chaque équipe figure par son nom. La boîte de réception propose un filtre **Responsable** derrière son champ de recherche, qui réunit personnes et équipes. Un filtre change la vue, sans accorder l’accès aux données d’une autre équipe.

Les propriétaires et les admins gèrent les membres dans [Équipes](https://docs.tale.dev/fr/platform/admin/teams) ; le bouton **Gérer les équipes** de la section les y mène.

## Définir des instructions personnalisées pour l’assistant de chat

Ouvre **Paramètres > Personnalisation**. Les **Instructions personnalisées** sont des instructions permanentes que l’assistant de chat suit dans chacune de ses réponses, par exemple un ton préféré, un langage de programmation par défaut ou le niveau de détail souhaité. L’interrupteur peut suivre la valeur par défaut de l’organisation ou enregistrer ton propre choix ; l’indication située en dessous précise ce qui s’applique. Le champ de texte apparaît tant que la fonction est activée. Saisis tes instructions, puis clique sur **Enregistrer** dans l’en-tête de la page.

<Frame caption="La page Personnalisation contient tes instructions personnalisées et l’interrupteur qui les active.">

![La page Personnalisation affiche l’interrupteur des instructions personnalisées et son champ de texte.](https://docs.tale.dev/images/platform/settings-preferences.webp)

</Frame>

<Note>

Tes instructions ne remplacent jamais les instructions obligatoires de l’organisation ni **Général > Instructions** d’un projet ; en cas de conflit, celles-ci prévalent. Désactiver l’interrupteur conserve le texte pour plus tard sans l’appliquer.

</Note>

## Consulter tes limites d’utilisation {#usage-limits}

Ouvre **Paramètres > Utilisation** pour voir ce que tu as déjà utilisé des limites que ton organisation t’applique. Si aucune limite ne te concerne, la page l’indique.

<Frame caption="Paramètres > Utilisation affiche chaque limite qui te concerne, avec son utilisation et sa prochaine réinitialisation.">

![La page Utilisation affiche les limites mensuelles personnelles de tokens, de coût et de requêtes, puis les limites mensuelles partagées de l’organisation, chacune avec une barre d’utilisation et sa date de réinitialisation. En dessous figure le stockage utilisé par rapport à la limite par personne. Un admin voit aussi le bouton Gérer les limites.](https://docs.tale.dev/images/platform/settings-usage.webp)

</Frame>

- **Tes limites** comptent tes propres chats, sorties vocales et exécutions d’agents, quelle que soit la façon de les lancer ; [Comment l’usage est compté](https://docs.tale.dev/fr/platform/admin/governance/usage-attribution) explique à qui une exécution est imputée. Quand l’une d’elles est atteinte, tu ne peux plus lancer ce type d’activité avant sa réinitialisation : un message envoyé à ce moment-là est refusé avec un avis qui nomme la limite, et il reste dans la zone de saisie.
- **Limites partagées** comptent l’utilisation de toutes les personnes qu’elles couvrent, par exemple une équipe dont tu fais partie ou l’organisation entière. Elles peuvent donc être atteintes avant tes propres limites.
- **Stockage** compare les fichiers que tu as téléversés avec ta limite de stockage. Une fois celle-ci atteinte, les nouveaux téléversements de documents sont refusés.

Chaque limite d’utilisation indique la quantité utilisée, la limite et le moment de sa réinitialisation, dans ton fuseau horaire. Les périodes suivent l’heure UTC : les limites quotidiennes repartent à minuit, les limites hebdomadaires le lundi et les limites mensuelles le premier du mois. Si un admin a défini un seuil d’alerte, la barre passe à l’orange dès que ton utilisation l’atteint. Quand un bandeau au-dessus de la zone de saisie signale une limite, **Voir l'utilisation** ouvre cette page. Les admins voient aussi **Gérer les limites**, qui ouvre **Gouvernance > Politiques et limites**.

## Archiver des chats ou se déconnecter

Sous **Paramètres > Compte > Tes chats**, les actions **Archiver tous les chats** et **Supprimer tous les chats** portent sur tes propres chats dans l’organisation actuelle, y compris les chats de projet. L’archivage concerne les chats non archivés. La suppression inclut aussi les chats archivés et les déplace dans la corbeille, où tu peux les restaurer pendant le délai de conservation. Les chats sous conservation légale restent inchangés, et ceux avec une réponse en cours ne peuvent pas être supprimés.

Lis la confirmation avant de continuer. Le résultat indique combien de chats ont été modifiés et combien n’ont pas pu l’être. Utilise le menu d’un chat dans **Accueil** si tu souhaites seulement ranger celui-ci. Les chats archivés restent sous **Archivés**, en bas de la liste d’**Accueil**, où **Désarchiver** dans le menu d’un chat le fait revenir.

**Se déconnecter** dans le menu de profil ferme la session actuelle et ramène à la connexion. Déconnecte-toi après usage sur un appareil partagé. Pour un espace dédié sur ton propre appareil, consulte [Installer l’application](https://docs.tale.dev/fr/platform/member/install-as-app).

Si ta session prend fin pendant que Tale est ouvert, par exemple après une déconnexion dans un autre onglet, une requête refusée affiche **Ta session a pris fin. Reconnecte-toi.**, et un téléversement de document échoue avec la même phrase, sans proposer de nouvel essai. Si tu ouvres ensuite l’onglet **Environnement** d’un projet, il affiche plutôt **Accès administrateur requis**. S’il était déjà ouvert, ou si tu le rouvres moins de cinq minutes après son dernier chargement, il affiche encore ses variables, et un enregistrement y affiche la même phrase. **Paramètres > Résidence des données** indique **Tu n'es pas autorisé à gérer la résidence des données de cette organisation.** Dans les pages de ton organisation, dont l’adresse commence par `/dashboard`, Tale vérifie la session et demande confirmation avant d’ouvrir la page de connexion. Cette étape te fait quitter la page actuelle. Les modifications non enregistrées risquent d’être perdues. Choisis **Rester ici** pour garder la page ouverte et copier le travail que tu souhaites conserver. Les refus suivants ne rouvrent pas la confirmation. Sur les autres pages, Tale ne demande rien : recharge la page pour te reconnecter.

Quand tu es prêt, ferme les boîtes de dialogue ouvertes et choisis **Se reconnecter** dans l’avis qui reste affiché en haut de la page, au-dessus de son en-tête, puis confirme. Tale vérifie à nouveau la session avant de quitter la page. Si tu t’es déjà reconnecté dans un autre onglet, ta page reste ouverte. Sinon, la page de connexion affiche le même avis de fin de session. Une fois connecté, tu reviens sur la page où tu étais. Tu peux y remettre le travail copié, mais les brouillons non enregistrés ne sont pas restaurés automatiquement.

# Choisir un modèle disponible
Source: https://docs.tale.dev/fr/platform/models

Le sélecteur affiche les modèles que ton organisation peut utiliser actuellement, pas toute l’offre d’un fournisseur. Des identifiants utilisables, leur liste de modèles autorisés et les règles d’accès déterminent le résultat. Un administrateur les gère dans **Paramètres > Fournisseurs IA** et [Contenu et modèles](https://docs.tale.dev/fr/platform/admin/governance/content-models).

## Choisir une sélection automatique ou explicite

Dans Chat, **Auto** choisit un modèle pour chaque message selon ses caractéristiques, comme la longueur, le code et les documents joints. Il utilise une heuristique légère, sans second appel à une IA. Consulte les détails d’une réponse pour voir quel modèle a répondu.

Choisis un modèle précis dans la zone de saisie pour comparer les résultats, maîtriser le choix ou traiter une tâche connue. Cette sélection reste en place jusqu’à ce que tu la changes ou reviennes à Auto. L’[Arène](https://docs.tale.dev/fr/platform/chat/arena-mode) compare deux modèles disponibles sur le même message.

Les agents de projet et les étapes de workflow qui appellent un modèle utilisent leur configuration. Le sélecteur d’un agent distingue les fournisseurs, même lorsqu’ils servent le même identifiant de modèle. Choisir une entrée fixe cette combinaison fournisseur/modèle. Un échec est signalé ; la réponse ne provient pas discrètement d’un autre modèle.

## Comprendre l’origine de la liste

Ouvre **Paramètres > Fournisseurs IA** pour examiner le fournisseur et ses modèles proposés. Le nombre affiché indique les définitions disponibles chez le fournisseur. Il ne prouve ni que ton organisation dispose d’identifiants, ni qu’elle est autorisée à appeler tous ces modèles.

| Source | Origine des modèles | Actualisation |
| --- | --- | --- |
| Catalogue intégré | Les définitions sont fournies avec Tale. | Lors d’une mise à jour de la plateforme ou du catalogue. |
| Catalogue OpenRouter | Tale récupère la liste d’OpenRouter. | Après une récupération ou une actualisation forcée. |
| Endpoint de modèles du fournisseur | Tale récupère la liste propre au fournisseur. | Après une récupération ou une actualisation forcée. |
| Pas de catalogue | Les identifiants de modèles viennent de la liste autorisée de l’identifiant de connexion. | Lorsqu’un administrateur modifie cette liste. |

Azure OpenAI et Nous Portal utilisent des identifiants de modèles définis dans les identifiants de connexion. Pour Azure, saisis les noms de déploiement de ta ressource, qui peuvent différer des noms publics. Sans catalogue, une liste autorisée vide ne rend aucun modèle disponible.

## Actualiser un catalogue distant

Les Propriétaires, Admins et Développeurs peuvent choisir **Actualiser les catalogues** dans l’en-tête des paramètres. Lis le résultat de chaque fournisseur : le nombre de modèles ou l’erreur qui a empêché l’actualisation. Un échec de récupération ne signifie pas que le fournisseur ne propose aucun modèle.

Les catalogues distants sont mis en cache pendant 24 heures, puis actualisés à la demande lorsque le cache est périmé. Le bouton force une nouvelle tentative. Si une récupération automatique échoue, Tale peut conserver le catalogue précédent ou les modèles fournis ; une actualisation forcée signale l’échec. Un nouveau modèle doit aussi respecter les règles d’accès et les identifiants disponibles. Une installation qui ne possède que des catalogues intégrés n’a aucune liste distante à récupérer.

## Retrouver un modèle absent

Vérifie ces limites dans l’ordre, ou transmets les détails à un administrateur si tu ne peux pas modifier les réglages :

1. Vérifie que le fournisseur possède des identifiants activés et utilisables. Une entrée de catalogue ne connecte pas un compte.
2. Examine leur **Modèles autorisés**. Avec un catalogue, elle restreint la sélection ; sans catalogue, elle la définit.
3. Vérifie les règles d’accès aux modèles pour l’organisation, l’équipe ou la personne dans [Contenu et modèles](https://docs.tale.dev/fr/platform/admin/governance/content-models).
4. Pour un agent de projet, vérifie la compatibilité des identifiants avec le [harness](https://docs.tale.dev/fr/platform/agents/harnesses) choisi. Un abonnement peut imposer un environnement précis, et un modèle qui n’appelle des tools que via l’API Responses d’OpenAI, comme GPT-6.1 Sol, n’est proposé que pour Codex.
5. Dans Chat, un modèle que seuls des identifiants d’abonnement servent n’apparaît pas : un abonnement ne fonctionne que dans les tâches et les automatisations, et la liste des modèles du chat nomme les abonnements qu’elle laisse de côté. Ajoute des identifiants par clé API ou variable d’environnement pour discuter avec ce modèle ; la page [Fournisseurs IA](https://docs.tale.dev/fr/platform/admin/providers#utiliser-les-abonnements-dans-les-taches-pas-dans-le-chat) explique pourquoi.

Si le modèle apparaît mais que l’appel échoue, lis la cause affichée. Des identifiants expirés, un fournisseur indisponible, une limite de dépense et un manque de sandbox sont des problèmes distincts. Actualiser le catalogue ne les résout pas tous. [Fournisseurs IA](https://docs.tale.dev/fr/platform/admin/providers) explique les identifiants ; [Politiques et limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits) couvre les refus liés aux dépenses.

# Trier le backlog du projet
Source: https://docs.tale.dev/fr/platform/projects/backlog

Utilise **Backlog** pour les propositions sur lesquelles l’équipe ne s’est pas encore engagée. Ce statut ordinaire apparaît en premier dans le tableau et la liste. Une proposition peut déjà être affectée à quelqu’un ; cette affectation ne signifie pas que le travail a commencé. Une proposition qui t’est attribuée apparaît tout de même parmi tes tâches dans [Accueil](https://docs.tale.dev/fr/platform#home), avec le statut **Backlog**.

## Enregistrer une proposition

Ouvre les **Tâches** du projet et crée une tâche. Choisis **Backlog** dans le sélecteur de statut ; sinon, une nouvelle tâche commence avec **À faire**. Donne-lui un titre qui décrit le résultat recherché et assez de contexte pour décider si la proposition mérite d’être suivie.

Par exemple, « Examiner l’erreur du paiement mobile » se juge mieux avec la page concernée, un symptôme reproductible et une capture d’écran qu’avec un titre seul. Attends de comprendre le problème avant de préciser la solution technique.

Un agent de projet équipé de l’outil de création de tâches peut aussi déposer une proposition. Cet outil autorise **Backlog** ou **À faire** comme statut initial, pas un statut de travail en cours ou terminé. La même limite s’applique aux automatisations qui utilisent les outils de tâches du projet.

## Décider de la suite

| Décision | Action |
| --- | --- |
| Il manque des informations | Garde **Backlog** et précise ce qui manque dans la description ou un commentaire. |
| L’équipe accepte le travail | Choisis **À faire** et affecte la tâche. |
| Le travail a commencé | Passe à **En cours**. |
| La proposition ne sera pas suivie | Choisis **Annulé** pour conserver la discussion. |

Change le statut dans le détail de la tâche ou déplace la carte entre les colonnes. Ce sont les commandes habituelles des tâches : le backlog n’a pas de procédure distincte d’acceptation ou de rejet.

## Confier la tâche à un agent

Choisis un agent du même projet et précise le résultat attendu avant de sélectionner **Démarrer l'agent**. L’affectation ne remplace pas cette action de démarrage. L’[automatisation des tâches](https://docs.tale.dev/fr/platform/projects/task-automation) explique les prérequis, le suivi et la vérification du résultat.

## Comprendre l’origine des propositions

L’automatisation fournie **Trier les issues GitHub** renvoie un rapport classé par priorité. Elle ne crée pas de tâches et ne remplit pas automatiquement le backlog. Une personne ou un agent correctement équipé doit transformer une issue retenue en tâche. Le rapport recommande ainsi du travail ; son acceptation reste une décision distincte.

Le guide [Gérer les tâches du projet](https://docs.tale.dev/fr/platform/projects/tasks) couvre les détails, les commentaires, les dépendances et les autres fonctions du tableau.

# Comprendre les projets
Source: https://docs.tale.dev/fr/platform/projects/concepts

Utilise un projet lorsque plusieurs questions ou tâches reposent sur les mêmes documents. Il réunit fichiers, instructions, chats, tableau des tâches et agents. Une question ponctuelle peut rester dans un chat ordinaire. Un lancement, une passation client ou une investigation suivie gagne généralement à être organisé dans un projet.

## Ce que le projet regroupe

| Espace | Ce qui y appartient |
| --- | --- |
| **Général** | Nom, description, instructions permanentes, partage et relecteur par défaut des tâches. |
| **Chats** | Tes conversations de projet et celles explicitement partagées avec lui. |
| **Connaissances** | Les fichiers de référence, classés en dossiers et limités à ce projet. |
| **Tâches** | Le travail avec un responsable, un statut, des commentaires et un résultat à relire. |
| **Agents** | Les agents nommés et configurés pour travailler sur les tâches. |

Un chat de projet démarre avec les instructions enregistrées du projet. Il peut rechercher dans les fichiers de ce projet et les connaissances accessibles de l’organisation. Les conversations suivantes disposent ainsi d’un contexte commun sans recopier le brief dans chaque message. Les fichiers d’autres projets restent hors de ce périmètre de recherche.

<Frame caption="Général réunit les instructions et le partage du projet. Enregistre les champs après modification.">

![La page Général du projet Website relaunch présente le nom, la description, les instructions, le partage et les commandes Enregistrer et Abandonner.](https://docs.tale.dev/images/platform/project-general-tab.webp)

</Frame>

## Choisir une identité reconnaissable

**Créer un projet** demande un nom et une **Clé du projet**, avec une description, une icône et une couleur facultatives. La clé devient le préfixe des identifiants de tâches, comme `WR-1`, et ne peut plus changer après la création. Choisis une abréviation courte et durable.

Tu peux ensuite modifier le nom, la description, l’icône, la couleur et les instructions dans **Général**. Utilise **Enregistrer** pour appliquer les modifications ou **Abandonner** pour les annuler. Pour suivre toutes les étapes, consulte [Utiliser les projets](https://docs.tale.dev/fr/tutorials/member/use-projects).

Consacre les instructions au contexte récurrent : le périmètre du travail, les sources qui font référence et la façon de traiter les informations manquantes. Une demande ponctuelle appartient au chat ou à la description d’une tâche. Les instructions du projet ne doivent pas devenir le journal de toutes les décisions passées.

## Vérifier qui peut l’ouvrir

Les nouveaux projets sont accessibles à **Toute l'organisation** par défaut. Choisis des équipes sous **Qui peut le voir** à la création du projet, ou plus tard sous **Audience** dans **Général**. Une audience vide signifie toute l’organisation ; sinon, les membres de l’une des équipes listées peuvent ouvrir le projet, et les administrateurs de l’organisation le peuvent toujours. Sauf si tu es propriétaire ou admin, tu ne peux choisir que des équipes dont tu fais partie. Retirer une équipe plus tard masque le projet aux membres extérieurs aux équipes restantes, et la page te demande de le confirmer. Le partage repose sur les équipes plutôt que sur des invitations individuelles ; la liste des projets affiche les équipes de chaque projet dans la colonne **Partage** et propose un filtre **Équipes**.

Les fichiers suivent l’accès au projet. Ils n’apparaissent pas comme des documents ordinaires de la bibliothèque ; affecter un document de la bibliothèque à une équipe n’en fait pas non plus une pièce jointe de projet. [Gérer les fichiers](https://docs.tale.dev/fr/platform/projects/manage-files) explique les déplacements et pourquoi retirer un fichier d’un projet peut élargir son public.

## Distinguer les chats personnels et partagés

Un chat dans un projet commence comme ta propre conversation. Les autres membres ne le voient pas simplement parce qu’ils peuvent ouvrir le projet. **Chats** sépare **Tes chats** de **Partagés avec le projet**. Utilise **Partager avec le projet** lorsque l’échange est prêt à être lu par tes collègues.

Tes collègues ouvrent un chat partagé en lecture seule : ils ne peuvent ni répondre, ni modifier un message, ni évaluer une réponse. Là où tu as modifié un message ou relancé une réponse, ils lisent la version que tu as sélectionnée, pas celle qu’elle a remplacée.

Relis les messages avant de partager, y compris les informations sensibles citées par une réponse. Déplacer un chat partagé vers un autre projet, ou hors du projet, met fin à son partage avec le projet. Partage-le à nouveau volontairement si le nouveau public doit le lire.

Utilise **Déplacer vers un projet…** dans les actions du chat, ou fais glisser le chat sur le projet dans **Accueil**, pour y rattacher une conversation existante. Les liens d’instantané pour l’organisation constituent une fonction distincte ; consulte [Partager un chat](https://docs.tale.dev/fr/platform/chat/shared-threads).

## Passer de la discussion au travail

Crée une [tâche](https://docs.tale.dev/fr/platform/projects/tasks) lorsqu’une décision a besoin d’un responsable ou d’un résultat. Un collègue peut la réaliser, ou un [agent de projet](https://docs.tale.dev/fr/platform/projects/project-agents) configuré peut y travailler. Indique les critères d’acceptation dans la description pour permettre la relecture.

Archive un projet terminé pour le retirer de la liste active. Un projet archivé est en lecture seule pour tout le monde : ses réglages, ses tâches, ses fichiers et ses agents restent consultables mais ne peuvent plus être modifiés, jusqu’à ce qu’un administrateur du projet le restaure depuis **Général**. Avant de supprimer, lis le choix proposé pour ses contenus : les détacher conserve les fichiers dans la bibliothèque et les chats comme conversations personnelles ; les supprimer retire aussi ces contenus. Les fichiers détachés peuvent devenir accessibles à un public plus large. Choisis selon ce qui doit rester disponible.

# Gérer les fichiers d’un projet
Source: https://docs.tale.dev/fr/platform/projects/manage-files

L’onglet **Connaissances** du projet contient les fichiers consultables par ses chats. Ajoute une référence une fois pour la réutiliser dans plusieurs conversations du projet. Tu dois pouvoir modifier le projet pour ajouter, organiser ou retirer ses fichiers.

<Frame caption="Les fichiers appartiennent au projet. Leur statut indique si le chat peut rechercher dans leur texte.">

![L’onglet Connaissances du projet Website relaunch contient deux fichiers indexés et des commandes pour créer des dossiers et importer des fichiers ou dossiers.](https://docs.tale.dev/images/platform/project-knowledge-files.webp)

</Frame>

## Importer au bon endroit

1. Ouvre le projet, puis **Connaissances**.
2. Sélectionne un dossier ou reste à la racine.
3. Clique sur **Ajouter un fichier** ou dépose des fichiers dans la zone d’import.
4. Vérifie que chacun apparaît au bon endroit et termine son indexation.

**Nouveau dossier** crée un dossier à la racine. **Nouveau sous-dossier** crée un dossier à l’intérieur d’un autre. **Importer un dossier** reprend un dossier de ton appareil et reproduit sa structure à l’emplacement sélectionné. Un import de dossier est limité à 200 fichiers et 200 Mo. Divise les dossiers plus volumineux et vérifie les fichiers ignorés dans le compte rendu.

## Vérifier si le chat peut lire le fichier

| Statut | Signification et action |
| --- | --- |
| **En file d'attente** | Le fichier attend son traitement. |
| **Indexation…** | Tale prépare le texte pour la recherche. |
| **Indexé** | Le texte est consultable. Vérifie une réponse contre le fichier d’origine. |
| **Échec** | Consulte les détails disponibles et utilise **Réessayer l'indexation**. Si l’échec revient, demande l’aide d’un admin. |
| **Non pris en charge** | Ce contenu ne peut pas être indexé. Fournis du texte lisible ou un format pris en charge ; relancer le même fichier ne résout pas la cause. |
| **Non indexé** | Le fichier est stocké, mais pas consultable par recherche. Utilise **Indexer maintenant** si proposé, ou convertis un format sans extracteur de texte. |

Une intégration peut importer un fichier sans l’indexer. Il reste visible dans l’arborescence. Un fichier texte compatible peut être lu directement lorsqu’il est nommé, mais il n’apparaît pas dans la recherche textuelle avant indexation.

Si tous les fichiers n’arrivent pas, le compte rendu de l’import liste les autres avec leur motif : les fichiers **Ignorés** n’ont pas passé le contrôle de type ou de taille avant l’envoi, et les fichiers **Non ajoutés** ont été refusés par Tale, qui en donne la raison. Les règles de l’organisation peuvent imposer des limites supplémentaires de taille ou de stockage. Si l’import échoue, commence par un petit fichier compatible. Un admin peut vérifier [Politiques et limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits), le stockage et le modèle d’embedding.

## Si les fichiers ou les dossiers ne se chargent pas

Quand l’onglet ne parvient pas à charger les fichiers ou les dossiers du projet, un avis au-dessus de l’arborescence indique ce qui a échoué et propose **Réessayer**. Tale ne présente jamais le projet comme vide à cause d’un échec de chargement :

- Si seuls les dossiers échouent, tous les fichiers chargés restent listés. Les fichiers à la racine restent à leur place, et les fichiers placés dans des dossiers apparaissent sous **Fichiers dans des dossiers** jusqu’au chargement des dossiers.
- Si seuls les fichiers échouent, les dossiers restent visibles et l’avis indique que les fichiers manquent.
- Si une actualisation échoue alors que l’arborescence était chargée, celle-ci garde son contenu, et l’avis indique qu’il n’est peut-être plus à jour.

**Réessayer** ne relance que le chargement qui a échoué, et l’arborescence garde ses dossiers dépliés et sélectionnés. Si l’échec se répète, demande à un administrateur de vérifier que les services de Tale fonctionnent.

## Poser la question dans un chat du projet

Ouvre **Chats** dans ce projet, démarre une conversation et pose une question en nommant le fichier ou son sujet. L’assistant peut consulter les fichiers de ce projet et les documents de la bibliothèque auxquels tu as accès. Il ne peut pas lire les fichiers d’un autre projet depuis ce chat.

Le chat général de l’organisation ne recherche pas dans les fichiers des projets. Tant qu’ils appartiennent au projet, ces fichiers n’apparaissent ni dans la liste documentaire de l’organisation ni dans sa bibliothèque WebDAV. L’accès au projet détermine qui peut les lire ; ils n’ont pas d’équipes associées séparément.

## Remplacer un document maîtrisé en conservant la revue

Importer un autre fichier sous le même nom crée un document distinct. Un nom identique ne relie pas deux révisions. Pour qu’une approbation reste liée au fichier exact qui a été examiné, utilise **Marquer comme document maîtrisé** dans le menu de la ligne.

Le document maîtrisé commence en brouillon. **Remplacer le fichier** met à jour un brouillon ou ouvre le brouillon suivant à partir d’une version approuvée, tout en conservant cette dernière. **Soumettre à la relecture** fige le brouillon pour le relecteur désigné. [Documents maîtrisés](https://docs.tale.dev/fr/platform/knowledge/documents) décrit le cycle complet et les règles de revue.

## Déplacer vers les connaissances ou supprimer

**Retirer du projet** déplace le fichier vers la bibliothèque de connaissances de l’organisation. Cette action ne le supprime pas.

<Warning>

Retirer le fichier du projet le rend visible par toute l’organisation. N’utilise cette action que si tu souhaites réellement élargir son audience. Lis la confirmation avant de continuer.

</Warning>

Pour retirer le fichier entièrement, choisis **Supprimer** dans son menu et lis la confirmation. Supprimer un dossier retire aussi les fichiers, sous-dossiers et entrées de recherche qu’il contient. Ces actions ne peuvent pas être annulées depuis l’arborescence. Une conservation légale ou un document maîtrisé protégé peut empêcher la suppression.

**Supprimer** est proposé pour les fichiers téléversés ici et pour ceux qu’un agent a écrits dans le projet, comme des lectures ou des rapports générés. Un fichier synchronisé depuis un connecteur ne propose pas de suppression dans le projet, car la prochaine synchronisation le restaurerait ; retire-le plutôt à sa source.

Si un fichier sert à plusieurs projets indépendants, envisage une copie partagée avec les équipes appropriées dans la [bibliothèque de connaissances](https://docs.tale.dev/fr/platform/knowledge/documents). Évite de conserver plusieurs versions contradictoires de la même politique.

# Projets
Source: https://docs.tale.dev/fr/platform/projects/overview

Un projet regroupe les fichiers, instructions, conversations et tâches d’un même travail. Utilise-le lorsque le contexte doit durer au-delà d’un chat ou qu’un résultat a besoin d’un responsable et d’une relecture. Commence par [Utiliser les projets](https://docs.tale.dev/fr/tutorials/member/use-projects) pour créer un projet et poser une question sur son fichier de référence.

<Video src="https://docs.tale.dev/videos/fr/tutorials/ep6-projects/ep6-projects.fr.mp4" poster="https://docs.tale.dev/videos/fr/tutorials/ep6-projects/ep6-projects.fr.webp" captions="https://docs.tale.dev/videos/fr/tutorials/ep6-projects/ep6-projects.fr.vtt" lang="fr" title="Épisode 6 — Les projets avec l'IA" caption="Épisode 6 — Les projets avec l'IA (2:21)">

</Video>

<Frame caption="Le tableau réunit les propositions, le travail en cours et les résultats à relire.">

![Website relaunch présente des tâches dans les colonnes Backlog, À faire, En cours, En revue, Terminé et Annulé.](https://docs.tale.dev/images/platform/projects-task-board.webp)

</Frame>

## Trouver la prochaine étape

<CardGroup cols="2">

<Card title="Comprendre l’accès au projet" icon="compass" href="https://docs.tale.dev/fr/platform/projects/concepts">
Distingue ce qui est partagé, les chats personnels et les accès accordés par les équipes.
</Card>

<Card title="Gérer les fichiers de référence" icon="folder-open" href="https://docs.tale.dev/fr/platform/projects/manage-files">
Importe et classe les fichiers, vérifie l’indexation et gère les révisions maîtrisées.
</Card>

<Card title="Créer et suivre les tâches" icon="list-checks" href="https://docs.tale.dev/fr/platform/projects/tasks">
Définis le responsable, le relecteur, les dates et les critères d’acceptation, puis suis l’avancement.
</Card>

<Card title="Configurer un agent de projet" icon="bot" href="https://docs.tale.dev/fr/platform/projects/project-agents">
Choisis le harness, le modèle, les outils et les instructions d’un agent capable de prendre des tâches.
</Card>

<Card title="Lancer et relire le travail d’un agent" icon="workflow" href="https://docs.tale.dev/fr/platform/projects/task-automation">
Démarre une tâche, relis le résultat, demande une reprise et traite les échecs d’exécution.
</Card>

<Card title="Examiner les propositions" icon="gauge" href="https://docs.tale.dev/fr/platform/projects/backlog">
Utilise le Backlog pour étudier les idées avant de les intégrer au travail prévu de l’équipe.
</Card>

</CardGroup>

Tous les projets que tu peux ouvrir figurent sous **Projets** dans [Accueil](https://docs.tale.dev/fr/platform#home), où **Tous les projets** ouvre la liste complète. Un projet s’ouvre sur son tableau des tâches ; **Général**, **Chats**, **Connaissances** et **Agents** complètent les vues des tâches. Pour les propriétaires, les admins et les développeurs, une automatisation liée au projet ajoute l’espace **Automatisations** ; les administrateurs du projet peuvent configurer l’**Environnement**. Les applications installées peuvent ajouter d’autres onglets. Elles ne sont pas nécessaires pour commencer avec les fichiers, les chats et les tâches.

# Créer et gérer des agents de projet
Source: https://docs.tale.dev/fr/platform/projects/project-agents

Crée un agent de projet pour disposer d’un agent réutilisable sur les tâches du projet. Il associe un environnement de code, un modèle, des instructions et un équipement autorisé. Tu dois pouvoir modifier le projet actif. Les Membres voient les agents du projet dans son onglet **Agents**, qui leur indique de demander un nouvel agent à un Éditeur ou à un Admin. Tant qu’un projet n’a pas d’agents propres, ses tâches peuvent aller à l’[agent standard](https://docs.tale.dev/fr/platform/projects/project-agents#standard-agent) de l’organisation. Seuls un Propriétaire ou un Admin peuvent changer les secrets accordés.

## Préparer la première tâche

Choisis un résultat limité, comme vérifier les approbations manquantes dans un brief de lancement. L’agent nécessite des [identifiants de fournisseur](https://docs.tale.dev/fr/platform/admin/providers) compatibles et une [sandbox](https://docs.tale.dev/fr/platform/admin/sandboxes) disponible. Enregistrer sa configuration ne prouve pas encore qu’une exécution réussira.

Sépare les instructions réutilisables de la tâche. « Repère les preuves manquantes et indique les contrôles effectués » appartient à l’agent. Le document, la date de revue et les critères d’acceptation appartiennent à la tâche.

<Frame caption="L'onglet Agents — les agents du projet ; chaque ligne nomme le harness, le fournisseur et le modèle.">

![L’onglet Agents du projet Website relaunch listant deux agents nommés — Content editor sur Claude Code et Redirect auditor sur Codex — chaque ligne nommant le fournisseur et l’identifiant du modèle, à côté du bouton Nouvel agent.](https://docs.tale.dev/images/platform/project-agents-models.webp)

</Frame>

## Configurer l’agent

<Steps>

<Step title="Choisir un nom et un environnement">

Ouvre l’onglet **Agents** du projet et choisis **Nouvel agent**. Donne-lui un **Nom** reconnaissable, puis choisis le **Harness**, son [environnement de code](https://docs.tale.dev/fr/platform/agents/harnesses). Les noms sont uniques dans le projet, qui accepte jusqu’à 50 agents.

Tu peux aussi partir d’une tâche : tant que le projet n’a pas d’agent, **Créer un agent…** sous **Assigné à** ouvre **Nouvel agent** par-dessus la tâche et lui assigne l’agent que tu crées.

</Step>

<Step title="Choisir le modèle et le fournisseur">

Recherche un **Modèle** par nom ou identifiant API. Le même modèle peut apparaître une fois par fournisseur : lis le fournisseur de l’entrée avant de la choisir. Cela fixe la combinaison pour les prochaines exécutions. Les offres par abonnement n’apparaissent qu’avec un environnement compatible, et un modèle qui n’appelle des tools que via l’API Responses d’OpenAI, comme GPT-6.1 Sol, n’apparaît qu’avec Codex.

Une ancienne configuration peut nommer un modèle sans fournisseur fixé. Le dialogue indique alors quel fournisseur le servirait actuellement ou pourquoi aucun ne peut le faire. Choisis une entrée pour fixer ce choix.

</Step>

<Step title="Accorder l’équipement et écrire les instructions">

Sous **Skills, connectors & outils**, ajoute les bundles, services et opérations nécessaires. Pour un nouvel agent, les skills de documents `docx`, `pptx`, `xlsx` et `pdf` sont cochés s’ils sont accessibles au projet. Ils contiennent des consignes pour travailler avec des fichiers Word, PowerPoint, Excel et PDF. Décoche ceux dont l’agent n’a pas besoin. La modification d’un agent existant conserve son équipement enregistré. La liste de skills suit les accès des équipes du projet, pas seulement ta visibilité personnelle. Un skill absent peut donc demander une modification de son partage.

<Frame caption="Le menu Skills d’un nouvel agent, avec les skills de documents déjà activés ; chaque skill indique qui l’a créé.">

![La boîte Nouvel agent avec le menu Skills ouvert : docx, pdf, pptx et xlsx sont activés et marqués Fourni avec Tale, tandis que brief-summary et release-notes par Alex Rivera ainsi que visual-aspect-analyzer restent désactivés.](https://docs.tale.dev/images/platform/project-agent-document-skills.webp)

</Frame>

Lis **Écrit des données** avant d’accorder un outil d’écriture : il autorise des opérations réelles selon ses règles d’accès. Le broker de connectors ne propose que des lectures aux agents. Les outils GitHub directs et les secrets explicitement accordés suivent d’autres voies.

**Modifier la priorité et l'agent assigné aux tâches** permet à un agent de projet de prioriser les tâches existantes, de les assigner à un agent du même projet ou de retirer leur assignation, sans démarrer de travail. Cette autorisation reste désactivée tant que tu ne l’accordes pas et n’est pas proposée aux nœuds agent des automatisations. L’agent doit d’abord lire la tâche et joindre les valeurs lues à sa demande de modification. Si ces valeurs ont changé entre-temps, toute la demande est refusée et il doit relire la tâche. Un changement d’assignation exige une tâche ouverte, sans exécution active, revue en attente ou question ouverte. Modifier uniquement la priorité conserve ces passages de relais. Le Tool ne change ni le statut ni le réviseur, ne répond à aucune question destinée à une personne et ne lance aucune exécution. Seule une exécution active disposant de droits sur tout le projet peut l’utiliser, pas une exécution démarrée par un Membre.

**Revoir les résultats des tâches d’autres agents** autorise un relecteur désigné à décider d’un résultat terminé produit par un autre agent de projet. Cette permission est désactivée au départ et n’est pas proposée aux nœuds agent des automatisations. Choisir un agent comme relecteur ne lui accorde pas cet outil et ne démarre aucune exécution. Il relit depuis sa propre tâche, avec des droits actuels sur tout le projet et la permission de relecture toujours accordée. Sa décision enregistre un retour et des éléments de vérification : une approbation termine la tâche examinée, tandis qu’une demande de modifications la remet à **À faire** sans démarrer de travail. Les compétences humaines requises et les approbations de workflows restent protégées. [Configurer un relecteur indépendant](https://docs.tale.dev/fr/platform/projects/task-automation#agent-review) décrit le parcours complet.

**Lancer d'autres agents sur des tâches** permet à l’agent de mettre au travail un autre agent de ce projet, par exemple un agent coordinateur qui distribue le travail prêt et relance un agent après avoir répondu à sa question. Il désigne une tâche, éventuellement l’agent à qui l’assigner, et un message que l’exécution lancée traite en premier. L’exécution lancée agit pour le compte de la même personne que l’exécution du coordinateur, et elle désigne le coordinateur comme l’agent qui l’a lancée. Un agent lancé de cette façon ne peut pas lancer d’autres agents, une exécution démarrée par un Membre ne peut en lancer aucun, et ni un agent qui travaille déjà sur une autre tâche ni une tâche bloquée par une tâche ouverte ne sont lancés. N’accorde cet outil qu’à un agent dont les instructions précisent quel travail il peut distribuer ; l’[automatisation des tâches](https://docs.tale.dev/fr/platform/projects/task-automation#travail-lance-par-une-automatisation-ou-un-autre-agent) décrit ce qu’une telle exécution peut faire.

Les appels de connecteurs d’une exécution se font au nom du membre qui l’a démarrée, que ce soit avec **Démarrer l'agent**, **Relancer**, un passage à **En cours** ou une mention de l’agent avec @. Ils utilisent les [identifiants des connecteurs](https://docs.tale.dev/fr/platform/admin/connectors) de l’organisation et sont enregistrés au nom de ce membre. Si ce membre quitte l’organisation ou est désactivé, les appels sont refusés : utilise **Annuler l'exécution** (ou laisse l’exécution se terminer), puis redémarre-la pour qu’elle se fasse en ton nom. Quand un commentaire relance l’exécution pour la guider, comme le font tous les environnements sauf Claude Code, les appels se font ensuite au nom de l’auteur du commentaire.

Rédige des **Instructions** qui définissent responsabilité, preuves et limites. Pour la revue du lancement : « Lis le brief fourni. Signale les approbations manquantes et les dates contradictoires avec le passage correspondant. Ne termine pas la tâche. »

</Step>

<Step title="Vérifier et enregistrer">

Si le travail demande des **Secrets**, un Propriétaire ou Admin accorde des identifiants nommés de l’organisation. L’agent en cours peut lire leurs valeurs : utilise des jetons limités et remplaçables. Modifier une valeur partagée affecte aussi les autres agents et nœuds de workflow qui utilisent ce nom. Une exécution qu’un Membre démarre ne reçoit aucun de ces secrets, ni le jeton d’une connexion GitHub équipée : un Éditeur ou un rôle supérieur doit démarrer le travail qui en a besoin.

Choisis **Créer l'agent**. Vérifie l’environnement, le fournisseur et le modèle de la nouvelle ligne. Rouvre l’agent pour examiner l’équipement et les instructions enregistrés.

</Step>

</Steps>

## Affecter et démarrer le travail

Ouvre une tâche du même projet, affecte-la à l’agent et choisis **Démarrer l'agent**. L’affectation et l’exécution sont deux actions distinctes. Fournis les fichiers et les critères d’acceptation avant le démarrage. Il n’est pas nécessaire de pouvoir modifier le projet : un Membre fait travailler un agent sur les tâches qu’il a créées ou qui lui sont attribuées, un Éditeur ou un rôle supérieur sur n’importe quelle tâche du projet. Une exécution qu’un Membre démarre s’en tient à cette tâche, sans les secrets de l’agent et dans un espace de travail à part ; [Exécutions démarrées par un Membre](https://docs.tale.dev/fr/platform/projects/tasks#executions-demarrees-par-un-membre) détaille ce qui change.

Le compte rendu apparaît dans les commentaires et les fichiers collectés sont joints comme résultats. Si un admin a activé la [génération d’images](https://docs.tale.dev/fr/platform/admin/governance/content-models#let-agents-generate-images), l’agent peut aussi créer des images pour la tâche ; elles apparaissent parmi les fichiers produits et comptent pour le membre qui a lancé l’exécution. Après un travail réussi, la tâche passe **En revue** pour que le relecteur humain ou l’agent relecteur indépendant désigné l’évalue. Mentionne l’agent dans un commentaire pour guider ou poursuivre le travail. Le harness détermine si le message rejoint le processus actif ou lance une continuation.

L’[automatisation des tâches](https://docs.tale.dev/fr/platform/projects/task-automation) explique le suivi, l’arrêt et la revue. L’assistant de chat ordinaire reste distinct, même avec un contexte de projet.

## L’agent standard {#standard-agent}

Un projet sans agents propres peut quand même confier du travail à un agent. Sauf si un Admin l’a désactivé dans [Gouvernance > Modèles](https://docs.tale.dev/fr/platform/admin/governance/content-models#standard-agent), **Assigné à** y propose l’option **Agent standard**, à toutes les personnes qui peuvent assigner la tâche, Membres compris. La première fois que quelqu’un la choisit, Tale met l’agent en place dans le projet et lui assigne la tâche. Tu le démarres ensuite comme n’importe quel autre agent, ou tu le mentionnes dans un commentaire. S’il ne peut pas démarrer pour toi, le champ de commentaire te le signale, et ton commentaire est enregistré comme une simple mention.

<Frame caption="L’onglet Agents d’un projet dont les tâches vont à l’agent standard.">

![L’onglet Agents du projet Customer onboarding portal avec une seule ligne : l’agent standard avec le badge Standard, Claude Code, OpenRouter, le modèle anthropic/claude-haiku-4.5 et quatre équipements. Une note indique que Tale l’a mis en place pour ce projet et que son harness, son modèle et ses instructions suivent les réglages de l’organisation. La ligne a un bouton de suppression, mais aucun bouton de modification.](https://docs.tale.dev/images/platform/project-agents-standard.webp)

</Frame>

L’onglet **Agents** l’affiche avec le badge **Standard**. Personne ne le modifie : son harness, son modèle et ses instructions suivent les réglages de l’organisation, relus à chaque démarrage d’une exécution, et son équipement se limite aux skills de documents `docx`, `pptx`, `xlsx` et `pdf` que le projet peut utiliser au démarrage d’une exécution. Si un admin en désactive un, il disparaît de son équipement au lieu de bloquer l’agent. Sur **Automatique**, chaque exécution utilise un modèle que la personne qui la démarre peut utiliser ; il peut donc fonctionner avec des modèles différents selon les personnes.

Pour donner au projet un agent propre, choisis **Nouvel agent**. Dès lors, le projet ne propose plus l’agent standard ; celui déjà mis en place reste assignable jusqu’à ce que tu le supprimes. Sa suppression conserve l’historique de ses tâches, et tant que le projet n’a pas d’agents, la prochaine tâche confiée à l’agent standard le remet en place.

## Modifier ou retirer un agent

Utilise le menu de sa ligne pour le modifier ou le supprimer. L’agent standard n’a que **Supprimer l'agent**. Les changements concernent les prochaines exécutions ; une exécution active conserve sa configuration initiale. La suppression retire les affectations à l’agent mais conserve l’historique des tâches. Elle efface aussi les [espaces de travail de sandbox](https://docs.tale.dev/fr/platform/admin/sandboxes#explain-why-a-workspace-disappeared) de l’agent avec leurs fichiers, y compris ceux des Membres. Examine le travail en cours et conserve les résultats nécessaires avant de retirer l’agent concerné.

Si la création échoue, lis la cause affichée : un nom déjà utilisé, un accès au projet manquant, un modèle indisponible et un skill invisible sont des problèmes distincts. Une exécution qui échoue définitivement indique en haut de sa tâche ce qui s’est passé et qui peut y remédier ; [Quand l’agent ne peut pas terminer](https://docs.tale.dev/fr/platform/projects/task-automation#quand-lagent-ne-peut-pas-terminer) détaille les cas. Modifier les instructions ne résout pas ces prérequis.

# Déléguer une tâche à un agent
Source: https://docs.tale.dev/fr/platform/projects/task-automation

Un agent de projet travaille sur une tâche et remet son résultat pour relecture. Assigne le travail, démarre l’exécution et garde les retours sur la tâche pour que l’agent et le relecteur partagent le même contexte. Il te faut le droit de modifier la tâche : un Éditeur ou un rôle supérieur l’a sur toutes les tâches du projet, un Membre sur celles qu’il a créées ou qui lui sont attribuées. Il faut aussi un fournisseur fonctionnel, un harness compatible et de la capacité de sandbox.

<Frame caption="Le travail des agents utilise le même tableau que le travail humain : il démarre à En cours et attend sa validation à En revue.">

![Le tableau du projet répartit les tâches entre Backlog, À faire, En cours, En revue, Terminé et Annulé.](https://docs.tale.dev/images/platform/projects-task-board.webp)

</Frame>

## Préparer et démarrer la tâche

1. Crée une [tâche](https://docs.tale.dev/fr/platform/projects/tasks) avec le résultat attendu, les critères de fin et les fichiers d’entrée.
2. Choisis un [agent de projet](https://docs.tale.dev/fr/platform/projects/project-agents) sous **Assigné à**.
3. Si tu peux modifier le projet, choisis une personne ou un agent indépendant sous **Relecteur**, ou conserve le **Choix par défaut du projet**. Initialement, le projet attribue les relectures à la personne autorisée qui a créé la tâche ou le projet. [Désigner un responsable et un relecteur](https://docs.tale.dev/fr/platform/projects/tasks#designer-un-responsable-et-un-relecteur) explique ce choix, les permissions et les transferts en attente.
4. Clique sur **Démarrer l'agent** ou passe la tâche à **En cours**. Si tu assignes l’agent dès la création de la tâche, **Créer et démarrer l'agent** dans **Créer une tâche** le fait dans la même étape.

L’assignation seule ne démarre pas l’exécution. Une tâche déjà assignée peut rester dans **Backlog** tant que l’équipe n’a pas décidé de la lancer. Tant que personne n’a démarré l’agent, la tâche affiche à toute personne qui peut le démarrer **Démarrer l'agent** et la mention **L’agent attend que tu le démarres.** Une fois démarré, l’agent utilise la description, les commentaires et les fichiers d’entrée dans sa sandbox. La fiche d’exécution indique s’il attend ou travaille. Une exécution qu’un Membre démarre s’en tient à sa tâche et se passe des secrets de l’agent ; [Exécutions démarrées par un Membre](https://docs.tale.dev/fr/platform/projects/tasks#executions-demarrees-par-un-membre) détaille ce qui change.

Les agents reçoivent la consigne de rédiger les mises à jour, les comptes rendus, les tâches associées et les questions dans la langue du titre et de la description de la tâche. Si ces éléments ne permettent pas de déterminer une langue, ils utilisent la langue par défaut de l’organisation pour les agents. Un identifiant, un trimestre ou un titre issu d’un modèle ne détermine pas cette langue. Changer la langue de ton interface ne change pas celle de la tâche ; tu peux demander explicitement à l’agent d’en changer.

Les commentaires de progression d’un workflow peuvent contenir des traductions pour chaque langue d’interface prise en charge. Le même commentaire enregistré s’affiche alors dans la langue choisie par chaque lecteur. Les commentaires sans traduction conservent leur texte d’origine.

## Lire et accepter le résultat

L’agent publie son compte rendu dans un commentaire et joint les fichiers produits comme livrables. Il passe ensuite la tâche à **En revue**. Un relecteur humain reçoit une notification et, si l’envoi d’e-mails est configuré, un e-mail. Un agent relecteur lit la relecture en attente depuis sa propre tâche ; lui attribuer une relecture ne le démarre pas automatiquement.

Tale liste les fichiers livrés ou ignorés dans un commentaire système distinct, affiché dans la langue de ton interface. Ce commentaire signale aussi un compte rendu absent ou raccourci. Le compte rendu conserve ainsi la langue de la tâche.

Pour une relecture humaine, lis le compte rendu, ouvre les livrables et compare-les aux critères de fin. Passe la tâche à **Terminé** seulement lorsque tu acceptes le travail. Tale enregistre la décision ; l’agent qui a produit le résultat ne peut pas l’approuver lui-même.

Pour une relecture attribuée à une personne, **Relecteur** détermine la notification et la file de revue sans réserver la décision à cette personne. Les autres personnes qui peuvent modifier la tâche peuvent aussi accepter le résultat, sous réserve des règles de relecture indépendante et de compétences de l’organisation. Une relecture en attente attribuée à un agent doit être explicitement transférée à une personne autorisée avant une approbation humaine. Changer de relecteur ne réassigne pas le travail de réalisation ; [Désigner un responsable et un relecteur](https://docs.tale.dev/fr/platform/projects/tasks#designer-un-responsable-et-un-relecteur) donne les détails.

Modifier **Relecteur** pendant que la tâche attend **En revue** transfère la demande enregistrée. La notification de l’ancien relecteur humain disparaît des demandes non lues ; une nouvelle personne reçoit la demande, tandis qu’une relecture attribuée à un agent attend cet agent. Le **Choix par défaut du projet** utilise la sélection actuelle du projet. Une modification simultanée de la relecture ou du résultat fait refuser le transfert : relis l’état actualisé avant de réessayer.

## Configurer un relecteur indépendant {#agent-review}

1. Crée un [agent de projet](https://docs.tale.dev/fr/platform/projects/project-agents) distinct pour les relectures. Sous **Skills, connectors & outils**, accorde-lui **Trouver des tâches**, **Lire une tâche** et **Revoir les résultats des tâches d’autres agents**. Cette dernière permission est désactivée au départ et n’est pas proposée aux nœuds agent des automatisations.
2. Choisis cet agent comme [relecteur par défaut](https://docs.tale.dev/fr/platform/projects/tasks#review-default) du projet, ou explicitement sous **Relecteur** sur une tâche. Pour une relecture déjà en attente, utilise le champ de la tâche pour la transférer ; changer le choix du projet ne suffit pas.
3. Donne au relecteur sa propre tâche et la consigne d’examiner uniquement les relectures qui lui sont attribuées. Démarre cette tâche directement ou par une [planification](https://docs.tale.dev/fr/platform/automations/triggers#demarrer-un-agent-de-projet-selon-une-planification) existante. Ne démarre pas une nouvelle exécution de réalisation sur la tâche dont le résultat est examiné.
4. Demande au relecteur de lire la relecture actuelle, d’examiner le compte rendu et les livrables réels, puis d’enregistrer des résultats de vérification concrets et un retour. Sa décision doit porter sur la même exécution terminée et les mêmes éléments que ceux qu’il a lus ; un résultat modifié exige une nouvelle lecture et un nouvel examen.

Pour une relecture attribuée à un agent, `task_get.reviewFiles` liste les pièces jointes et les livrables par pages de 50. Pour continuer, passe `reviewFiles.page.continueCursor` comme `reviewFileCursor`. Avec `task_review`, `operation: "stage_file"`, la valeur actuelle de `expected: {approvalId, runId, evidenceRevision}` et une `fileId` de cette liste, le relecteur peut copier un fichier disponible de 20 Mio au plus dans son espace de travail. Il doit ensuite ouvrir le chemin renvoyé et examiner le contenu : la copie seule ne prouve pas que le fichier a été relu.

Un `unavailableReason` explique pourquoi un fichier ne peut pas être copié : stockage non pris en charge, métadonnées absentes ou ambiguës, taille trop élevée ou lien avec un document protégé. Les règles d’accès aux documents continuent de s’appliquer. Si la source ou le relecteur change, il faut relire l’état actuel. Si les droits changent pendant le transfert, l’opération refuse de confirmer le succès. Des octets déjà transférés avec autorisation peuvent rester dans l’espace de travail, sans permettre une décision devenue obsolète.

L’approbation passe la tâche examinée à **Terminé**. Une demande de modifications enregistre le retour et passe la tâche à **À faire**, en conservant son assignation. Aucune décision ne démarre une autre exécution. Même une mention d’agent dans ce retour ne déclenche pas de travail : une personne autorisée, un coordinateur ou une planification doit démarrer la tentative suivante séparément. L’activité indique l’agent relecteur et sa décision.

Pour une demande de modifications enregistrée, le coordinateur appelle `task_start_agent` avec `taskId` et `resumeFrom: {kind: "review_repair", approvalId, runId}`. Ces identifiants désignent la revue refusée et l’exécution de réalisation qu’elle a examinée. Le serveur choisit l’agent de cette réalisation et inclut les commentaires enregistrés du relecteur ainsi que `feedbackCommentId` dans les consignes de correction. Un complément dans `feedback` doit tenir avec ce texte et son préfixe d’identification dans la limite existante de 10 000 unités de code UTF-16.

La correction ne démarre que si la tâche est encore **À faire**, confiée au même agent, avec la même réalisation terminée comme dernière exécution. Une revue plus récente ou une modification intermédiaire du statut, de l’assignation ou de l’archivage empêche le démarrage, même si la valeur précédente a ensuite été rétablie. La réponse `stale_repair` ne change rien : le coordinateur relit la tâche et abandonne l’intention dépassée. Il ne réessaie jamais sans cette vérification explicite. La correction suit le cycle normal et soumet une nouvelle revue à la fin ; `moveToInProgress: false` est refusé.

Si la réponse se perd, le même agent coordinateur peut répéter l’appel protégé depuis une exécution active et actuellement autorisée, y compris une occurrence ultérieure. `replayed: true` renvoie le `runId` et le `repairReceipt` d’origine, conserve la première exécution à l’origine de la demande et ne lance aucun nouveau travail. Le reçu confirme un démarrage passé, pas que l’exécution est toujours active. Le droit de déléguer et l’accès au projet sont revérifiés à chaque appel. Les limites de simultanéité, d’occupation de l’agent et de trois démarrages automatisés par tâche sur une heure restent applicables aux nouveaux démarrages. Des échecs répétés sans changement doivent mener à une tâche d’investigation distincte plutôt qu’à des réessais sans limite.

Pour retrouver une décision après une réponse perdue lors d’une occurrence précédente du relecteur, lis `task_get.reviewDecision`. Ce champ contient le dernier reçu natif validé, ou `null` si une revue en attente, humaine ou liée à un workflow plus récente existe, ou si le reçu est indisponible. Compare les identifiants de revue et d’exécution à l’intention enregistrée, puis lis séparément l’état actuel de la tâche. Un reçu historique ne décrit pas sa colonne actuelle et `null` ne prouve pas qu’aucune décision n’a été enregistrée. La répétition immédiate et identique de `task_review` exige toujours la même exécution émettrice active.

Pour les deux décisions, le relecteur doit être différent de l’agent qui a effectivement produit le résultat. Il lui faut une exécution active avec des droits sur tout le projet et la permission de relecture toujours accordée ; une exécution démarrée par un Membre ne peut pas décider d’une relecture. Une politique d’indépendance humaine ou des justificatifs de compétences requis orientent les nouvelles relectures vers la chaîne humaine ; une relecture déjà attribuée à un agent exige un transfert explicite à une personne autorisée. Les approbations de workflows et les questions adressées à une personne conservent leurs décisions humaines. Avant une décision, lis `pendingReview.agentReviewBlockedReason` pour connaître un problème actuel de source, de permission, d’identité ou de politique. Si le travail concerne GitHub, le relecteur doit vérifier lui-même le commit cité et ses contrôles : Tale enregistre ses éléments, mais ne vérifie pas indépendamment l’état actuel de GitHub et ne fusionne pas de Pull Request avec cette décision.

## Demander des modifications

Explique les changements attendus dans un commentaire et **mentionne l’agent assigné avec @**. Cette mention est une instruction : un agent actif peut la recevoir pendant son exécution, tandis qu’un agent inactif démarre une reprise de la conversation précédente. Le résultat revient à **En revue**.

Si tu as démarré une exécution, tes mentions continuent de la guider même après que la tâche est passée à l’agent, par exemple parce que ta mention lui a confié une tâche qui t’était attribuée. Quand l’environnement de l’agent redémarre pour prendre en compte un commentaire, comme le font tous les environnements sauf Claude Code, la suite de l’exécution revient à l’auteur du commentaire : elle compte dans ses limites, et ses appels de connecteurs se font en son nom.

Un commentaire sans mention conserve une note sans déclencher cette action. Le sélecteur de mentions indique si l’agent ne peut pas répondre, par exemple lorsque l’automatisation des tâches est désactivée ou suspendue, ou lorsque tu peux commenter la tâche sans pouvoir la modifier.

Pour une tâche pilotée par une automatisation, mentionne celle qui en est responsable pour demander une nouvelle exécution. Mentionner une autre automatisation ne lui transfère pas la tâche et ne la démarre pas. [Automatisations](https://docs.tale.dev/fr/platform/automations/concepts) présente les workflows qui coordonnent plusieurs étapes.

Une tâche ne peut avoir qu’une seule exécution en file d’attente, en cours ou en attente à la fois, quelle que soit l’automatisation qui l’a démarrée. Répéter une demande de démarrage tant qu’elle est active renvoie à l’exécution existante, même si elle nomme une autre automatisation. Une fois celle-ci terminée, un nouveau démarrage peut créer une autre exécution et répéter le travail. Vérifie donc l’exécution actuelle et ses effets avant une nouvelle tentative.

## Confier la file de travail à un agent coordinateur

Un agent coordinateur est un agent de projet dont les instructions consistent à lire tout le tableau, à distribuer le travail prêt et à répondre aux questions de routine que laissent les autres agents, pour que les personnes ne voient que ce qui demande leur intervention. Il lit avec **Trouver des tâches** et **Lire une tâche** ; aucun de ces deux outils ne modifie quoi que ce soit.

### Lire toute la file de travail par passages

**Trouver des tâches** renvoie au plus 50 tâches à la fois. Tant qu’une page indique `isDone: false`, son `continueCursor`, renvoyé comme `cursor` avec les mêmes arguments, donne la page suivante ; la dernière page indique `isDone: true`. Un curseur qui revient avec d’autres filtres, un autre ordre ou depuis l’exécution d’un autre projet est refusé, tout comme un curseur abîmé : il n’est jamais lu comme la première page. Un total n’apparaît que lorsqu’une seule page contient toutes les tâches correspondantes.

Pour parcourir toute une file de travail, utilise `order: "created"`. Les tâches arrivent alors dans l’ordre de leur création, de la plus ancienne à la plus récente, et gardent leur place : un passage cite donc chaque tâche au plus une fois, dans l’état où elle se trouve quand sa page est lue. L’ordre par défaut regroupe les tâches par statut et garde, pour chacun, l’ordre de sa colonne : une tâche qui bouge pendant que le coordinateur tourne les pages peut alors manquer ou apparaître deux fois.

Chaque tâche listée contient `pendingReview: null` ou les valeurs enregistrées `approvalId`, `runId` de réalisation et `reviewer` typé. Un relecteur trouve sa file avec `status: "in_review"` et son identifiant d’agent dans `reviewerAgentId`. Ce filtre porte sur le destinataire enregistré de la relecture, pas sur l’agent chargé de la réalisation ni sur le choix actuel du projet. Conserve ce filtre à chaque requête avec curseur. Le coordinateur parcourt aussi toutes les tâches `in_review` pour repérer les relectures d’agents supprimés, puis lit `task_get.pendingReview.agentReviewBlockedReason` pour déterminer la correction nécessaire. Les relectures d’agents restent dans cette file de tâches ; la file personnelle de l’accueil concerne les demandes humaines.

Un passage peut durer plus longtemps qu’une exécution. Avant la fin de son exécution, le coordinateur note un point de reprise dans un commentaire sur sa propre tâche : le passage, son ordre et ses filtres, le `continueCursor` suivant et la dernière tâche examinée. Son exécution suivante retrouve ce commentaire avec **Lire une tâche** et reprend à partir de là. Quand un passage se termine, ou que son curseur est refusé, le passage suivant commence à la première page. Une lecture qui échoue n’est pas une file vide : le coordinateur la signale et s’arrête.

### Distinguer le travail en cours, terminé ou en attente

**Lire une tâche** désigne les sous-tâches, les tâches bloquantes et les commentaires par leurs identifiants, et remonte vers les commentaires plus anciens avec `commentCursor`. Il liste aussi les exécutions des agents de projet sur la tâche, de la plus récente à la plus ancienne, chacune avec les 500 premiers caractères du message transmis à son démarrage, ainsi que l’exécution d’automatisation de la tâche et une éventuelle demande de revue en cours :

- Une exécution avec `live: true` est en file d’attente ou en cours, et rien d’autre ne démarre sur la tâche avant qu’elle se termine.
- Une exécution achevée, en échec ou annulée est terminée ; `settledAt` en indique le moment.
- `retryPending: true` signifie qu’une nouvelle tentative automatique reste prévue pour la dernière exécution en échec et que son quota de tentatives le permet. Laisse Tale s’en charger. `false` signifie qu’aucune tentative n’est en attente pour cette exécution ; si le champ manque sur une ancienne plateforme, cet état est inconnu. Il ne donne ni l’heure de réinitialisation du fournisseur ni l’autorisation de relancer : relis d’abord la tâche, son responsable, ses exécutions et sa revue, puis respecte l’attente du fournisseur et tout `retryAfter` renvoyé lors d’un refus de démarrage.
- Un `workflowRun` qui attend une question (`ask`) ou une approbation (`approval`) attend une personne. Une `pendingReview` désigne son relecteur humain ou agent ; le coordinateur lui laisse la décision, sauf s’il est lui-même le relecteur indépendant désigné et dispose de la permission requise.

La réponse ne contient ni transcriptions, ni textes d’erreur, ni résultats, et rien qui vienne d’un autre projet.

### Répondre à une question de routine

Une question de routine est une question à laquelle le coordinateur peut répondre à partir de ce que le projet consigne déjà. Écris le même protocole dans les instructions des agents qui travaillent et dans celles du coordinateur :

1. L’agent qui travaille pose la question dans un commentaire de la tâche, avec une clé de question stable, ses éléments de preuve et la question. Il indique dans son résultat l’identifiant du commentaire et celui de son exécution (**Lire une tâche** montre cette exécution comme l’exécution active de sa tâche), puis termine son exécution au lieu d’attendre à l’intérieur. Mentionner le coordinateur dans ce commentaire ne démarre rien : le commentaire d’un agent ne démarre jamais un agent.
2. Lors de son passage suivant, le coordinateur ne répond que tant que la tâche attend encore cette question : l’exécution qui l’a posée est la plus récente de la tâche et elle est terminée, aucune exécution n’est active sur la tâche, et la tâche attend la revue de cette exécution-là (`pendingReview.runId`). De cette lecture, il retient l’identifiant de l’exécution et `pendingReview.approvalId`. Si quelqu’un a entre-temps fait avancer la tâche, en acceptant le résultat, en annulant la tâche ou en demandant des modifications, la question n’est plus au coordinateur : il la signale au lieu d’y répondre.
3. Il publie sa réponse dans un commentaire qui cite l’identifiant du commentaire de la question ; la réponse reste sur la tâche quoi qu’il arrive ensuite. Il relance ensuite l’agent avec **Lancer d'autres agents sur des tâches**, en passant `resumeFrom: {runId, approvalId}` avec les deux identifiants qu’il a retenus, et un message qui commence par la clé de la question, l’identifiant de l’exécution et l’identifiant du commentaire de réponse : une lecture ultérieure avec **Lire une tâche** ne montre que les 500 premiers caractères du message d’un démarrage. Au moment où il a lieu, le démarrage vérifie que c’est encore la question ouverte de la tâche. Ce n’est qu’alors qu’il retire la demande de revue en cours, sans valider le résultat, et relance l’agent.
4. Si le démarrage répond `stale_question`, la question a été dépassée entre la lecture du coordinateur et le démarrage : une décision a été prise, il existe une exécution ou une revue plus récente, ou l’assignation a changé. Rien n’a été modifié. Le coordinateur relit la tâche et abandonne la question devenue caduque. Il ne relance pas, et jamais sans `resumeFrom`.
5. Si la réponse au démarrage se perd, le coordinateur relit la tâche avant de tenter quoi que ce soit d’autre : une exécution plus récente dont le message commence par cette clé de question, cet identifiant d’exécution et cet identifiant de commentaire de réponse signifie que le démarrage a abouti. Si le même démarrage est renvoyé, il répond `stale_question` et ne change rien.

Une question venant d’une tâche permanente, qu’une planification démarre avec `moveToInProgress: false`, n’attend aucune revue. Le coordinateur y publie seulement sa réponse, et l’exécution de l’occurrence suivante de la planification la lit. Ni le coordinateur ni personne d’autre ne démarre la tâche plus tôt pour transmettre la réponse.

Les questions d’une automatisation et les approbations de workflows restent l’affaire des personnes. Un coordinateur peut décider d’une relecture de travail d’agent uniquement par le parcours indépendant décrit plus haut, quand elle lui est attribuée. Lire ou reprendre une tâche n’approuve pas son résultat.

## Traiter une attente ou un échec

| État ou symptôme | Action |
| --- | --- |
| Attente d’une place de sandbox | La capacité de l’organisation ou de l’infrastructure partagée peut être épuisée. Attends une place ou demande à un admin d’examiner [Sandboxes](https://docs.tale.dev/fr/platform/admin/sandboxes). |
| Nouvelle tentative automatique affichée | Tale reprend après un échec récupérable. Surveille le compteur sans lancer une autre exécution. |
| **L’agent n’a pas pu terminer cette tâche** | Aucune nouvelle tentative automatique ne suit. L’avis indique ce qui s’est passé et qui peut y remédier, et **Détails**, à côté de l’exécution, montre ce que l’exécution elle-même a signalé ; [Quand l’agent ne peut pas terminer](https://docs.tale.dev/fr/platform/projects/task-automation#quand-lagent-ne-peut-pas-terminer) détaille les cas. Corrige la cause, puis utilise **Relancer** pour continuer la conversation. |
| Réassignation refusée | Annule l’exécution active avant de choisir un autre responsable. |
| Des agents ou des automatisations relancent sans cesse une même tâche | Une tâche accepte au plus trois démarrages de son agent par des automatisations et d’autres agents en une heure, les relances automatiques ordinaires comprises ; l’exception pour l’attente du courtier décrite ci-dessous s’applique aussi. Le démarrage suivant est refusé, une relance au-delà de la limite ne démarre pas, et la chronologie indique **Exécution refusée: les exécutions d'agents sont en pause sur cette tâche**. Les démarrages par des personnes, et leurs relances, ne sont jamais comptés. Les exécutions d’automatisations n’ont pas ce plafond : entre deux automatisations qui se mentionnent sans fin, c’est la règle d’un seul moteur qui arrête la boucle. Annule l’exécution active, puis lis la chronologie avant de laisser l’une ou l’autre redémarrer. |
| **Exécution refusée: l'agent travaille sur une autre tâche** | Une nouvelle tentative automatique a attendu son agent pendant deux heures, et il travaille encore sur une autre tâche. Rien n’attend derrière ce refus : relance la tâche dès que l’agent est libre, ou laisse faire l’agent coordinateur ou l’automatisation qui distribue le travail. |
| Clôture impossible | Termine d’abord les sous-tâches ouvertes. |

Un échec récupérable donne lieu à jusqu’à trois nouvelles tentatives après la tentative initiale, qui démarrent aussitôt sauf dans les cas décrits plus bas. Une exécution qui progresse pendant au moins quinze minutes reçoit une nouvelle réserve de tentatives. Cela aide le travail long à reprendre après une interruption, sans prouver que le résultat est correct.

Une nouvelle tentative automatique poursuit le travail de la personne qui a démarré l’exécution : elle ne démarre donc que là où cette personne pourrait la lancer maintenant. Le projet doit encore être actif, et cette personne doit toujours avoir le droit de modifier la tâche. Si un administrateur archive le projet, ou si cette personne quitte l’organisation ou perd le droit de modifier la tâche, aucune nouvelle tentative ne démarre et l’exécution reste en échec. Il en va de même pour une mention qui n’atteint l’agent qu’après la fin de son exécution. Une fois le projet restauré, toute personne qui peut modifier la tâche peut utiliser **Relancer**.

Un agent servi par un courtier d’abonnement peut perdre son jeton en cours de travail, lorsque le courtier actualise le compte. La nouvelle tentative poursuit alors la conversation avec un nouveau jeton, sans faire avancer le compteur de tentatives : elle affiche le même compteur que l’exécution qu’elle remplace, ou **Reprise après l'actualisation du jeton** si celle-ci n’en affichait aucun ou avait travaillé au moins quinze minutes, ce qui lui a valu une nouvelle réserve de tentatives. Après deux interruptions de ce type d’affilée, une nouvelle interruption compte comme n’importe quel autre échec.

Une exécution peut aussi ne pas démarrer du tout, parce que tous les comptes de son courtier d’abonnement sont en pause après avoir atteint une limite de requêtes. Sa nouvelle tentative est alors mise en file d’attente aussitôt, mais ne démarre que lorsque le premier compte redevient disponible, au plus tard une minute après. Cette attente ne consomme aucune tentative si l’exécution refusée suit immédiatement un échec HTTP 429 du même agent. Cette seule attente n’ajoute pas non plus de démarrage au compteur horaire des démarrages automatisés de la tâche : l’échec dû à la limite de requêtes a déjà été compté. Un refus consécutif pour la même attente, ou un refus après un autre échec, compte pour les deux limites.

### Quand l’agent ne peut pas terminer

Quand une exécution échoue et que plus rien ne la relance, parce que ses nouvelles tentatives automatiques sont épuisées ou qu’une nouvelle tentative ne changerait rien à la cause, la tâche l’indique tout en haut : **L’agent n’a pas pu terminer cette tâche**, avec ce qui s’est passé et qui peut y remédier. **Relancer**, à cet endroit, redémarre l’agent pour toute personne qui peut modifier la tâche.

| L’avis indique | Qui agit |
| --- | --- |
| Une limite d’utilisation a arrêté l’exécution | Un Admin relève la limite ; relance ensuite l’agent. |
| Il manque quelque chose à l’agent : son modèle, l’un de ses skills ou l’agent lui-même | Un Éditeur ou un Admin corrige l’agent dans l’onglet **Agents** du projet. |
| Une pièce jointe de cette tâche n’est plus dans le stockage | Toute personne qui peut modifier la tâche retire la pièce jointe ou la téléverse à nouveau ; **Détails**, à côté de l’exécution, nomme le fichier. Relance ensuite l’agent. |
| L’exécution a atteint sa limite de temps | Relance l’agent, ou découpe la tâche en tâches plus petites. |
| L’exécution a attendu trop longtemps une sandbox libre | Relance l’agent quand moins d’agents sont occupés. |
| Le modèle d’IA a échoué, ou l’exécution n’a pas pu démarrer ou a été interrompue | Relance l’agent. S’il échoue encore, montre à un Admin ce que l’exécution a signalé dans **Détails**. |

Tale prévient aussi la personne qui a démarré l’exécution et toutes celles qui suivent la tâche : par la notification **Échec de l’exécution de l’agent** et, si l’organisation dispose d’une boîte mail connectée, par e-mail. Seules les personnes qui peuvent encore ouvrir le projet sont prévenues. Une nouvelle exécution démarrée sur la tâche marque la notification non lue comme lue. Tu peux désactiver ces avis avec **Escalades d'agent** dans **Paramètres > Notifications**.

## Travail lancé par une automatisation ou un autre agent

Un agent de projet peut aussi être mis au travail sans que personne ait à cliquer sur **Démarrer l'agent** : par une [automatisation planifiée](https://docs.tale.dev/fr/platform/automations/triggers#demarrer-un-agent-de-projet-selon-une-planification), ou par un autre agent du projet qui dispose de l’outil **Lancer d'autres agents sur des tâches**, comme un agent coordinateur qui distribue le travail prêt et répond aux questions. La chronologie affiche une telle exécution comme **automatisation**, avec, pour les propriétaires, les admins et les développeurs, un lien vers l’exécution de l’automatisation, ou comme **délégué**, lancée par l’agent qui l’a demandée. L’agent apprend qui l’a démarré, et il lit un message transmis par cette automatisation ou cet agent comme venant d’eux, jamais comme la revue d’une personne : là où ce message contredit la description ou le commentaire d’une personne, ce sont ces derniers qui l’emportent.

L’exécution agit pour le compte de la même personne que l’exécution qui l’a demandée : la personne qui a démarré cette exécution, ou personne si la chaîne a commencé par une planification, auquel cas ses dépenses comptent comme des dépenses d’automatisation. Cette personne, ou la planification, doit pouvoir agir dans le projet au moment où l’exécution démarre : si la personne perd le rôle Éditeur, si la planification est suspendue ou si l’automatisation est retirée du projet, le démarrage suivant n’a pas lieu. Un agent lancé par un autre agent ne peut pas lancer d’autres agents, et une exécution démarrée par un Membre ne peut en lancer aucun. Un tel démarrage vérifie aussi ce qu’une personne pourrait oublier : une tâche bloquée par une tâche ouverte ne démarre pas, et un agent qui travaille déjà sur une autre tâche n’est pas lancé une seconde fois. Une nouvelle tentative automatique d’une telle exécution suit la même règle : tant que son agent travaille sur une autre tâche dans le même espace de travail, elle attend, vérifie à nouveau toutes les cinq minutes et démarre dès que l’agent est libre, sans consommer de tentative. Chaque vérification relit la tâche : si elle quitte **En cours** ou change de responsable, si elle ou son projet est archivé, ou si la personne perd son rôle, l’attente prend fin. Si l’agent est encore occupé deux heures après l’échec, la nouvelle tentative ne démarre pas et la chronologie indique **Exécution refusée: l'agent travaille sur une autre tâche**.

Une exécution déléguée dépose son résultat à **En revue** pour le relecteur enregistré. Reprendre une tâche qui y attend retire sa demande de revue en cours, sans valider le résultat. Un démarrage qui laisse la carte en place (`moveToInProgress: false`) est refusé sous une carte en attente de revue, ou sous une carte **Terminé** ou **Annulé**, afin qu’un travail antérieur ne soit jamais présenté au jugement pendant qu’un nouveau travail s’exécute dessous. Un coordinateur qui répond à la question d’un agent le relance en nommant l’exécution qui a posé la question et la revue qu’elle attend. La reprise n’a lieu que tant que c’est encore la question ouverte de la tâche. Si une décision a été prise entre-temps (**Terminé**, **Annulé** ou un autre déplacement), s’il existe une exécution ou une revue plus récente, ou si l’assignation a changé, l’agent répond `stale_question` et rien n’est assigné, retiré, déplacé ni démarré. Si ton organisation exige une relecture humaine indépendante, la personne pour le compte de laquelle l’exécution agit ne peut pas en accepter le résultat.

## Annuler ou suspendre le travail

Utilise **Annuler l'exécution** pour arrêter l’agent actif. Toute personne qui peut modifier la tâche peut annuler son exécution, tout comme la personne qui a démarré celle-ci, même si la tâche est passée depuis à l’agent. Déplacer une tâche d’agent hors de **En cours** peut aussi annuler son exécution : lis la confirmation avant de continuer. Une tâche ne peut pas avoir deux exécutions d’agent actives en même temps.

Pour une tâche pilotée par une automatisation, le déplacement arrête l’exécution et place la tâche là où tu l’as déplacée, en une seule étape. Si ce déplacement est refusé, par exemple parce que tu passes à **Terminé** une tâche parente dont des sous-tâches restent ouvertes, l’exécution continue et la tâche reste dans **En cours**. **Annuler l'exécution**, dans le panneau de l’automatisation sur la tâche, passe la tâche à **Annulé** : les mêmes sous-tâches ouvertes l’en empêchent donc. Pour arrêter l’exécution tout en gardant la tâche ouverte, déplace-la plutôt vers **À faire**.

Un admin peut désactiver l’automatisation des tâches pour l’organisation. Cela bloque les nouveaux démarrages pendant que le travail déjà lancé se termine. Les limites et budgets de l’organisation s’appliquent toujours ; consulte [Politiques et limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits).

## Choisir le bon responsable

Assigne une personne lorsque le travail demande un jugement humain ou un accès hors des droits de l’agent. Choisis un agent de projet pour une tâche délimitée utilisant ses fichiers et outils configurés. Une automatisation convient à un processus défini avec des étapes, des déclencheurs ou des approbations pour les opérations des connecteurs. Un Membre ne peut choisir qu’une automatisation conçue pour les tâches, c’est-à-dire l’une de celles listées sous **Automatisations** dans **Assigné à**.

Pour commencer, suis [Créer ton premier agent](https://docs.tale.dev/fr/tutorials/editor/first-agent-end-to-end). Choisis une tâche assez petite pour en vérifier toi-même le résultat.

# Gérer les tâches d’un projet
Source: https://docs.tale.dev/fr/platform/projects/tasks

Une tâche regroupe le but d’un travail, son responsable, son statut, ses fichiers et les échanges autour du résultat. Utilise le tableau du projet pour le travail confié à une personne comme pour celui délégué à un agent. Toute personne qui peut ouvrir le projet peut y créer des tâches ; [qui peut modifier une tâche](https://docs.tale.dev/fr/platform/projects/tasks#qui-peut-creer-et-modifier-les-taches) dépend de ton rôle et du fait que la tâche soit la tienne ou non. Le projet doit être actif : un projet archivé reste en lecture seule jusqu’à ce qu’un administrateur le restaure.

<Frame caption="Le tableau classe les tâches par statut. Passe à Liste pour retrouver les mêmes tâches sous forme de lignes.">

![Le tableau du projet Website relaunch affiche des cartes dans Backlog, À faire, En cours, En revue, Terminé et Annulé.](https://docs.tale.dev/images/platform/projects-task-board.webp)

</Frame>

## Créer une tâche avec un résultat précis

1. Ouvre **Tâches** dans le projet, puis clique sur **Créer une tâche**.
2. Donne au **Titre** le nom du résultat attendu, par exemple « Vérifier le brief de lancement ».
3. Explique dans **Description** ce qui est demandé et comment le résultat sera vérifié. Ajoute les fichiers nécessaires en pièces jointes.
4. Choisis au besoin **Statut**, **Priorité** et **Assigné à**. Une nouvelle tâche commence à **À faire**. Utilise **Backlog** pour une proposition qui n’a pas encore été retenue.
5. Clique sur **Créer une tâche**, puis ouvre la carte pour compléter ses détails. Si un agent figure sous **Assigné à**, **Créer et démarrer l'agent** crée la tâche et démarre l’agent en une seule étape.

Un titre compte jusqu’à 200 caractères et une description jusqu’à 20 000 ; la plupart des emojis comptent double. Une description plus longue, collée ou laissée sur une tâche par un import antérieur, n’est pas coupée : le champ indique la limite et compte la longueur, et **Créer une tâche** ou **Enregistrer** reste indisponible tant que tu ne l’as pas raccourcie.

Tale attribue un identifiant à partir de la clé du projet, par exemple `WEB-1`. Utilise-le pour désigner le travail sans confondre des tâches aux titres proches.

Une conversation peut aussi lancer une tâche : **Créer une tâche** dans l’en-tête du chat ouvre la même boîte de dialogue avec ta demande, les fichiers du chat et un lien vers celui-ci, puis le chat suit la tâche au-dessus de son champ de message. Voir [Transformer un chat en tâche](https://docs.tale.dev/fr/platform/chat/basics#create-task-from-chat).

Une automatisation conçue pour les tâches peut aussi proposer un modèle dans **Créer une tâche** : son nom apparaît alors à côté de **Tâche vierge**, au-dessus du formulaire. Choisis-la, saisis le nom qu’elle demande, par exemple un trimestre, puis clique sur **Créer une tâche** ; l’automatisation devient responsable de la tâche. Si une tâche existe déjà pour ce nom, Tale l’ouvre au lieu d’en créer une deuxième et indique **Une tâche existe déjà pour ce sujet.** Un Membre peut alors la lire et la commenter, mais ne la modifie que si elle est la sienne. Les modèles qui créent des dossiers ou des fichiers de paramètres dans le projet ne sont proposés qu’aux Éditeurs et aux rôles supérieurs.

<Tip>

Une description utile précise les éléments de départ, le résultat attendu et un critère de fin. Par exemple : « Compare la date de revue du brief joint avec les notes de réunion. Signale toute différence dans un commentaire en citant les deux fichiers. »

</Tip>

<Frame caption="Les détails réunissent description, pièces jointes, sous-tâches et commentaires à côté du responsable et du statut.">

![La tâche Sign off the launch checklist affiche sa description, ses pièces jointes, sous-tâches, commentaires, statut, responsable, relecteur, dates, répétition, étiquettes et dépendances.](https://docs.tale.dev/images/platform/project-task-detail.webp)

</Frame>

## Qui peut créer et modifier les tâches

Toute personne qui peut ouvrir un projet peut y créer des tâches. Les Éditeurs et les rôles supérieurs peuvent modifier toutes les tâches du projet. Sur les tâches qu’il a créées ou qui lui sont attribuées, un Membre peut :

- Modifier le titre, la description, les pièces jointes, les sous-tâches, les dates, la priorité, les étiquettes et la répétition.
- Attribuer la tâche à lui-même, à un autre membre du projet, à l’un de ses agents ou à une automatisation conçue pour les tâches.
- Démarrer, guider ou arrêter l’agent, y compris en le mentionnant avec @ dans un commentaire.
- Changer le statut, et accepter un résultat en passant la tâche à **Terminé**.
- Archiver la tâche ou la restaurer.

Il en va de même pour les sous-tâches placées sous une telle tâche, quelle que soit la personne qui les a ajoutées, par exemple un agent qui a découpé le travail : elles n’empêchent donc jamais le Membre de clôturer sa tâche. Modifier **Relecteur** exige le droit de modifier le projet, même sur une tâche que tu as créée ou qui t’est attribuée.

Sur les tâches des autres, un Membre lit et commente ; s’il y mentionne un agent, la mention reste ordinaire et ne lance rien. Chacun peut modifier et supprimer ses propres commentaires sur toute tâche qu’il peut lire, et les propriétaires et les admins peuvent aussi supprimer ceux des autres.

Une tâche archivée se lit mais ne se modifie pas. Tant que personne ne la restaure, personne ne peut la commenter, modifier ou supprimer ses commentaires, ni changer ses dépendances ; une tâche qu’elle bloque peut toutefois la retirer sous **Bloqué par**. Une exécution d’agent qui travaillait déjà sur la tâche y dépose quand même son résultat.

Si tu confies à quelqu’un d’autre, une personne ou un agent, une tâche qui t’était attribuée, tu lui cèdes aussi le droit de la modifier, sauf si tu l’as créée. Une exécution que tu as démarrée reste toutefois entre tes mains : si ta mention avec @ confie la tâche à un agent, tu peux guider cette exécution par d’autres mentions et l’arrêter avec **Annuler l'exécution** jusqu’à ce qu’elle se termine.

Une dépendance appartient à la tâche qu’elle bloque : un Membre n’enregistre donc de dépendances que pour ses propres tâches, sous **Bloqué par** sur l’une de ses tâches, ou sous **Bloque** sur toute tâche qu’il peut ouvrir, en choisissant l’une de ses tâches comme tâche bloquée. Les paramètres, les agents, les fichiers et le catalogue d’étiquettes du projet restent réservés aux Éditeurs et aux rôles supérieurs ; un Membre choisit parmi les étiquettes que le projet possède déjà. Seuls les propriétaires et les admins peuvent supprimer une tâche ; les autres personnes qui peuvent la modifier l’archivent à la place.

Les automatisations suivent une règle plus stricte, car une automatisation agit en son propre nom, avec les identifiants de connecteurs de l’organisation, et non au nom de la personne qui la démarre. Un Membre ne peut confier une tâche qu’à une automatisation conçue pour les tâches, c’est-à-dire l’une de celles listées sous **Automatisations** dans **Assigné à**, ou à l’automatisation à laquelle la tâche appartient déjà. Ce sont aussi les seules qu’il peut démarrer ou auxquelles il peut demander des modifications. Toutes les autres restent réservées aux Éditeurs et aux rôles supérieurs.

### Exécutions démarrées par un Membre

Une exécution démarrée par une personne qui ne peut pas modifier le projet, par exemple un Membre, s’en tient à sa tâche :

- Ses outils de plateforme ne modifient que cette tâche et ses sous-tâches : l’agent ne crée de nouvelles tâches que comme sous-tâches de celle-ci, n’utilise que des étiquettes que le projet possède déjà et ne peut pas synchroniser dans le projet des éléments venant d’autres systèmes.
- Elle ne peut pas enregistrer de documents dans le projet. Les fichiers produits arrivent quand même sur la tâche, sous **Fichiers produits**.
- L’exécution ne reçoit ni les **Secrets** de l’agent ni le jeton d’un accès GitHub équipé. L’agent apprend quels identifiants ont été retenus et doit le signaler dans son compte rendu si le travail en a besoin ; un Éditeur ou un rôle supérieur doit alors le démarrer. Les connecteurs équipés sur l’agent continuent de fonctionner, au nom de la personne qui a démarré l’exécution.
- Elle travaille dans son propre espace de travail, conservé pour les exécutions de cette personne avec cet agent : les fichiers des exécutions que des Éditeurs ont démarrées n’y sont pas, et ce que cette exécution laisse ne parvient jamais à celles-ci. Les exécutions suivantes de la même personne avec cet agent le retrouvent, jusqu’à ce que Tale le supprime : quand la personne quitte l’organisation ou que l’agent est supprimé, ou dès qu’aucune exécution ne l’a utilisé pendant le nombre de jours fixé par l’organisation sous [**Jours sans utilisation**](https://docs.tale.dev/fr/platform/admin/sandboxes#delete-unused-workspaces-automatically).

L’exécution peut toujours lire les tâches et les connaissances du projet, et elle garde ces limites même si un Éditeur la guide ensuite. Une exécution qu’un Éditeur ou un rôle supérieur démarre dispose, sur toute tâche, de l’équipement complet de l’agent. Le commentaire d’un Membre peut changer cela : si l’environnement de l’agent redémarre pour prendre en compte le commentaire, comme le font [tous les environnements sauf Claude Code](https://docs.tale.dev/fr/platform/agents/harnesses), la suite de l’exécution compte comme celle du Membre, avec les mêmes limites pour ses outils et ses identifiants.

## Désigner un responsable et un relecteur

**Assigné à** désigne qui réalise le travail : une personne, un agent de projet ou une automatisation disponible dans le projet. **Relecteur** permet de choisir une personne, un agent de projet ou le **Choix par défaut du projet** pour examiner le résultat. Modifier ce choix exige le droit de modifier le projet. Un relecteur humain doit aussi avoir ce droit ; un agent relecteur doit appartenir au même projet et être différent de celui qui a produit le résultat.

Assigner un agent et lancer son exécution sont deux choix distincts. Après l’assignation, clique sur **Démarrer l'agent** ou passe la tâche à **En cours**. Lis [Automatiser les tâches](https://docs.tale.dev/fr/platform/projects/task-automation) avant de lancer un travail qui utilise des services connectés ou produit des fichiers.

Si le projet n’a pas d’agent propre, **Assigné à** propose l’option **Agent standard**, l’agent de l’organisation pour ces projets. La choisir met l’agent en place dans le projet et lui assigne la tâche ; [L’agent standard](https://docs.tale.dev/fr/platform/projects/project-agents#standard-agent) explique son fonctionnement. Les Éditeurs et les rôles supérieurs peuvent plutôt choisir **Créer un agent…** : **Nouvel agent** s’ouvre par-dessus la tâche, et l’agent que tu crées lui est assigné. Quand l’agent standard ne peut pas fonctionner pour eux, par exemple parce qu’un Admin l’a désactivé, les Membres sont invités à demander à un Éditeur ou à un Admin d’ajouter un agent dans l’onglet **Agents** du projet.

<Frame caption="Dans un projet sans agents propres, Assigné à propose l’agent standard de l’organisation.">

![La liste Assigné à, défilée jusqu’à sa section Agents : l’agent standard, décrit comme l’agent de l’organisation pour les projets sans agent propre, puis l’entrée pour créer un agent, au-dessus du pied de liste qui indique que l’agent standard prend en charge les tâches tant que le projet n’a pas d’agents propres.](https://docs.tale.dev/images/platform/project-task-standard-agent.webp)

</Frame>

Quand la relecture est attribuée à une personne, celle-ci reçoit la demande sans être la seule autorisée à accepter le résultat. Toute autre personne qui peut modifier la tâche peut aussi l’accepter : un Éditeur ou un rôle supérieur, ou le Membre à qui la tâche appartient. Si l’organisation exige une relecture indépendante, la personne qui a démarré l’exécution examinée ne peut pas en accepter le résultat ; si le résultat ne vient pas d’une exécution d’agent, cette restriction s’applique à la personne qui a créé la tâche. Les compétences humaines requises restent exigées. Une relecture attribuée à un agent attend sa décision, ou un transfert explicite à une personne autorisée avant toute approbation humaine.

Si la politique de relecture de l’organisation est illisible ou invalide, l’approbation humaine est refusée, y compris après un transfert d’un agent à une personne. Un administrateur de l’organisation doit rétablir une configuration valide avant que l’approbation puisse réussir. Les demandes de modifications et le retrait d’une relecture gardent leur fonctionnement actuel.

### Définir le relecteur par défaut du projet {#review-default}

Dans l’onglet **Général** du projet, ouvre **Relecture des tâches**, choisis le **Relecteur par défaut**, puis enregistre les modifications du projet. Le choix initial, **Personne**, retient d’abord la personne qui a créé la tâche, puis celle qui a créé le projet, si elle peut le modifier. Choisis un agent de projet indépendant pour lui attribuer les nouvelles relectures. Ce réglage ne démarre pas l’agent et ne lui accorde pas la permission de relire ; [Configurer un relecteur indépendant](https://docs.tale.dev/fr/platform/projects/task-automation#agent-review) décrit ces étapes.

Les tâches qui suivent le **Choix par défaut du projet** reprennent ce choix au début d’une nouvelle relecture. Une personne ou un agent explicitement choisi pour une tâche reste sélectionné. Les relectures déjà en attente conservent leur relecteur enregistré, même si le choix du projet change. Si quelqu’un modifie ce choix pendant ta modification, abandonne ton brouillon périmé et choisis à nouveau.

Le choix d’un agent par défaut s’applique uniquement aux résultats d’une exécution native d’agent de projet, si l’organisation n’exige ni indépendance humaine ni justificatifs de compétences. Un travail soumis par une personne ou une automation sans cette exécution suit la chaîne de relecture humaine. Pour enregistrer le choix d’un agent, sa permission de relire doit être active ; une tâche ne peut pas choisir l’agent qui l’a réalisée comme relecteur. Une relecture déjà en attente ne change jamais de responsable automatiquement après une modification des permissions, de l’affectation ou de la politique.

### Transférer une relecture en attente {#transfer-review}

Ouvre la tâche et lis **Relecture en cours** sous **Relecteur**. Cette indication désigne qui doit examiner le résultat en attente ; elle peut différer du choix actuel du projet. Choisir un autre relecteur lui transfère aussi cette relecture, sans changer l’assignation du travail ni démarrer d’exécution. Le **Choix par défaut du projet** utilise la sélection actuelle du projet. Si le relecteur ou le résultat a changé depuis le chargement de la tâche, le transfert est refusé ; vérifie l’état actualisé avant de choisir à nouveau.

Un agent peut uniquement relire un résultat terminé produit par un autre agent de projet. Si tu réassignes la tâche, l’agent à l’origine du résultat reste le même, mais la décision de relecture en attente est bloquée pour l’agent relecteur. Pour conserver la nouvelle assignation et faire examiner ce résultat, transfère explicitement la relecture à une personne autorisée. La politique de relecture de l’organisation continue de s’appliquer.

Une exécution active ou une question ouverte peut empêcher le transfert à un agent. En l’absence d’une exécution d’agent terminée compatible, ou si la politique exige une indépendance humaine ou des justificatifs de compétences, choisis une personne autorisée. Si l’agent est indisponible ou n’a pas la permission de relire, la tâche en indique la raison ; elle ne te réattribue pas silencieusement la relecture.

La relecture en cours explique aussi les blocages liés à l’auto-relecture, à une nouvelle affectation du travail ou à une politique illisible. Rétablis la condition indiquée ou transfère explicitement la relecture ; le résultat de l’exécution reste enregistré. Une tâche répétée conserve un agent explicitement choisi même s’il a été supprimé ou a perdu sa permission. Corrige ce choix plutôt que d’hériter silencieusement d’un autre relecteur.

## Montrer la progression avec les statuts

Modifie **Statut** dans les détails de la tâche ou déplace sa carte vers une autre colonne du tableau. Le sélecteur de statut offre une alternative au glisser-déposer utilisable au clavier.

| Statut | Signification |
| --- | --- |
| **Backlog** | Travail proposé, mais pas encore retenu. |
| **À faire** | Travail prêt à démarrer. |
| **En cours** | Travail commencé. Pour une tâche assignée à un agent, passer à ce statut lance son exécution. |
| **En revue** | Résultat en attente de son relecteur humain ou de son agent relecteur. |
| **Terminé** | Le travail accompli a été accepté. |
| **Annulé** | Travail abandonné. |

Pour une tâche d’agent, changer de statut peut démarrer ou annuler une exécution. Lis l’indication de l’action avant de déplacer la carte. Un agent remet son résultat à **En revue** ; il ne peut pas le marquer lui-même **Terminé**.

## Garder les décisions avec le travail

Ouvre la tâche pour ajouter une description, des pièces jointes, des dates, des étiquettes, des sous-tâches ou des commentaires. Consigne dans les commentaires les questions, décisions et retours qu’un futur relecteur devra comprendre.

Saisis `@` dans un commentaire pour ouvrir le sélecteur de mentions. Mentionner l’agent assigné constitue une instruction : cela peut guider une exécution en cours ou en démarrer une autre si l’agent est inactif. Un commentaire sans mention conserve l’échange sans demander cette action à l’agent.

Les mentions dans la description de la tâche agissent de la même façon quand tu enregistres la tâche : les personnes citées sont notifiées, et un agent cité est guidé ou démarre une exécution comme décrit ci-dessus. S’il démarre une exécution, la tâche passe à **En cours**, quelle que soit la colonne où tu l’as créée. Quand tu modifies la description plus tard, seules les mentions que tu ajoutes comptent. Reformuler le texte autour d’une mention existante ne notifie personne à nouveau. L’agent lit la description telle qu’elle est au démarrage de son exécution : si tu la modifies pendant que l’exécution attend encore, c’est ta nouvelle version qu’il suit.

Utilise **Sous-tâches** pour séparer des résultats vérifiables indépendamment. Une sous-tâche nomme sa tâche parente en haut de ses détails (**Partie de …**) ; clique dessus pour y remonter. Tant qu’une de ses sous-tâches reste ouverte, une tâche parente ne peut passer ni à **Terminé** ni à **Annulé** ; les autres statuts restent disponibles, **À faire** compris. **Dépendances** indique ce qui bloque la tâche et ce qu’elle bloque. Les dépendances circulaires sont refusées.

Quand tu modifies un champ, l’**Activité** de la tâche affiche sa valeur d’avant et celle d’après. Un champ que tu vides indique ce qui reste, par exemple **Aucune échéance** ou **Non assigné**, au lieu de répéter seulement l’ancienne valeur. Les titres, descriptions, étiquettes et noms de fichiers apparaissent exactement tels qu’ils ont été saisis, même quand le texte correspond à un nom de statut comme `done`. Les statuts, les priorités, les dates et les mentions d’un champ vide s’affichent dans ta langue.

## Rendre une tâche récurrente

Si le même travail revient régulièrement, comme un point d’avancement hebdomadaire, rends la tâche récurrente. Chaque fois que tu la clôtures, la tâche suivante apparaît dans **À faire**, avec pour échéance le prochain jour prévu par la répétition.

Clique sur **Répéter**, sous **Échéance**, dans les détails de la tâche ou dans **Créer une tâche**, puis choisis comment la tâche se répète. Ton choix est enregistré dès que tu cliques dessus :

- **Jamais**
- **Tous les jours**
- **Tous les jours ouvrés**, du lundi au vendredi
- **Chaque semaine le …**, **Chaque mois le …** ou **Chaque année le …**, qui reprennent le jour de l’échéance ; sans échéance, celui de la date de début si elle est encore à venir, sinon celui d’aujourd’hui

<Frame caption="Choisis la répétition dans les détails de la tâche ; l’aperçu indique les prochaines échéances.">

![Le menu Repeat de la tâche Sign off the launch checklist propose Never, Daily, Every weekday, des options hebdomadaire, mensuelle et annuelle nommées d’après l’échéance, dont l’hebdomadaire est sélectionnée, et Custom, au-dessus des prochaines échéances et de l’option de créer la tâche suivante à l’échéance.](https://docs.tale.dev/images/platform/project-task-repeat.webp)

</Frame>

**Prochaines échéances** indique quand les trois prochaines tâches arriveront à échéance. Une tâche sans échéance en reçoit une dès que tu choisis une répétition : le premier jour prévu à partir d’aujourd’hui, ou à partir de sa date de début si celle-ci est plus tardive. Une répétition mensuelle le 31 tombe le dernier jour des mois plus courts. Si tu retires l’échéance d’une tâche déjà récurrente, la répétition reste : la tâche suivante arrive alors quand tu clôtures celle-ci, avec pour échéance le premier jour prévu après la clôture, et **Répéter** le signale à l’ouverture. Toute modification de la répétition redonne une échéance à la tâche.

Si les dates dépassent la plage de dates prise en charge, l’aperçu le signale. Choisis une date de début ou une échéance antérieure avant de définir la répétition.

### Définir une répétition personnalisée

Pour tout autre rythme, choisis **Personnalisé** dans la même liste. Choisis **Jour**, **Semaine**, **Mois** ou **Année**, indique à quelle fréquence la tâche revient, puis sélectionne les jours de la semaine, le jour du mois ou la date, par exemple toutes les 2 semaines le mardi et le jeudi. **Prochaines échéances** suit chaque modification. Clique sur **Enregistrer** pour garder la répétition. **Annuler**, **Échap** ou un clic en dehors de la liste abandonnent tes modifications ; la flèche de retour ramène à la liste en les conservant.

### Créer la tâche suivante à l’échéance

Par défaut, la tâche suivante apparaît quand tu passes celle-ci à **Terminé** ou **Annulé**. Si le travail doit revenir à temps même quand la tâche précédente n’est pas terminée, ouvre **Répéter** sur une tâche récurrente, coche **Créer la tâche suivante à l'échéance** sous les dates et clique sur **Enregistrer**. La tâche suivante apparaît alors au début du jour d’échéance, à minuit dans le fuseau horaire de la personne qui a réglé la répétition, même si cette tâche est encore ouverte. Si la tâche est déjà à échéance, la suivante apparaît en quelques minutes, et si tu clôtures la tâche avant son jour d’échéance, la suivante est créée tout de suite. L’activité attribue cette création à **Système**. **Répéter** affiche alors une icône de calendrier, et l’infobulle de l’icône de répétition dans **Tableau** et **Liste** se termine par **tâche suivante à l'échéance**.

Les tâches ouvertes ne retiennent plus une telle série : elles peuvent donc s’accumuler si personne ne les clôture. Une série ne compte jamais plus de 10 tâches ouvertes : la suivante attend que quelqu’un en clôture une. Si tu modifies la répétition, ou choisis **Jamais** puis à nouveau une répétition, les tâches encore ouvertes dans la série restent comptées.

### Ce que reprend la tâche suivante

La tâche suivante a son propre identifiant et commence dans **À faire**. Elle reprend le titre, la description, la priorité, les étiquettes, les pièces jointes, le responsable, le relecteur, les personnes qui suivent la tâche et la répétition. Ses sous-tâches reviennent avec elle, chacune dans **À faire** avec des dates décalées du même intervalle, ainsi que les dépendances qui les relient. Les commentaires, les dépendances vers d’autres tâches, les sous-tâches archivées et les fichiers produits par un agent restent sur la tâche précédente. Les personnes ne sont reprises que si elles ont encore accès au projet : le responsable s’il peut encore être assigné, le relecteur s’il peut encore modifier le projet, et les personnes qui suivent la tâche si elles voient encore le projet. Qui a cessé de suivre la tâche ne suit pas non plus la suivante, même s’il l’a créée.

L’échéance de la tâche suivante est le premier jour prévu par la répétition après l’échéance de la tâche précédente, et une date de début garde le même nombre de jours d’avance. Cette échéance n’est jamais dans le passé : si tu clôtures une tâche en retard, la suivante est due aujourd’hui ou au prochain jour prévu. Les dates manquées ne s’accumulent donc pas en tâches en retard.

Sous **Répéter**, la tâche précédente renvoie à la suivante, par exemple **Tâche suivante : WEB-13**. Si tu rouvres la tâche précédente puis la clôtures à nouveau, aucune deuxième tâche n’est créée. Dans **Tableau** et **Liste**, une icône de répétition signale la tâche qui porte la série à ce moment-là ; son infobulle indique la répétition.

### Arrêter une série

Quand tu clôtures une tâche récurrente, le message **Tâche suivante créée** indique l’échéance de la suivante et propose **Arrêter la répétition**. Le même bouton reste sous **Répéter** sur la tâche qui a créé la suivante, à côté de **Tâche suivante**, tant que la tâche suivante se répète. Si personne n’a encore touché à la tâche suivante (elle est toujours dans **À faire**, inchangée, sans commentaire ni exécution d’agent), elle est supprimée avec ses sous-tâches. Sinon, elle reste en place mais ne se répète plus. Dans les deux cas, la série s’arrête : sur la tâche depuis laquelle tu l’as arrêtée, **Répéter** affiche **Jamais**, et son infobulle indique **La série a été arrêtée.** Si tu as utilisé le bouton sous **Répéter**, le focus passe ensuite sur **Répéter**. Tu peux aussi ouvrir la tâche la plus récente de la série et régler son champ **Répéter** sur **Jamais**.

**Arrêter la répétition** n’agit que sur les tâches que tu peux modifier : celle sur laquelle tu l’utilises et les tâches ultérieures de la série que tu peux modifier aussi. Les tâches antérieures continuent d’afficher leur répétition. Si une tâche ultérieure appartient désormais à quelqu’un d’autre, par exemple après une réattribution, elle garde sa répétition et la série continue à partir d’elle ; aucune tâche suivante n’est alors supprimée.

Si tu supprimes la tâche la plus récente d’une série, la série s’arrête. La tâche précédente n’en crée pas d’autre, même si tu la rouvres puis la clôtures à nouveau : elle n’affiche pas d’icône de répétition, et son champ **Répéter** reste verrouillé, avec l’infobulle **La tâche suivante a été supprimée. Cette tâche ne peut plus se répéter.** Si tu supprimes une tâche plus ancienne, la série continue à partir de la plus récente.

### Quand la répétition ne peut pas être modifiée

Survole **Répéter** ou place le focus clavier dessus pour lire pourquoi le champ est verrouillé :

- Une tâche qui a déjà créé sa tâche suivante lui a transmis la série et ne se répète plus, même si tu la rouvres. Tant que la série continue, modifie la répétition sur la tâche suivante, que le lien **Tâche suivante** ouvre. Si la série a été arrêtée ou si la tâche suivante a été supprimée, **Répéter** l’indique.
- Toute autre tâche passée à **Terminé** ou **Annulé** garde la répétition avec laquelle elle a été clôturée. Rouvre-la pour modifier sa répétition.
- Une sous-tâche n’a pas de répétition propre. Tant que sa tâche parente se répète, **Répéter** affiche par exemple **Avec WEB-3**, et chaque tâche suivante de la parente apporte une nouvelle copie de la sous-tâche. Une sous-tâche archivée n’a pas de champ **Répéter** : elle ne revient pas. Un travail qui suit son propre rythme a besoin d’une tâche à part entière.
- Une tâche qu’une automatisation prend en charge ne se répète pas, et assigner une tâche récurrente à une automatisation arrête sa série.
- Dans **Créer une tâche**, **Répéter** affiche **Jamais** tant que **Statut** est sur **Terminé** ou **Annulé**, ou qu’une automatisation est assignée.

## Vérifier le résultat avant de clôturer

Pour une tâche humaine, compare le travail au critère de fin décrit dans la tâche. Pour un agent, lis son compte rendu dans les commentaires et examine les fichiers produits. Une exécution terminée indique que l’agent a cessé de travailler. Consulte la décision de relecture enregistrée pour savoir si le résultat a été accepté.

Passe la tâche à **Terminé** lorsqu’elle répond au besoin. Si l’agent doit reprendre son travail, explique précisément la modification attendue dans un commentaire et mentionne-le. [Automatiser les tâches](https://docs.tale.dev/fr/platform/projects/task-automation) détaille les reprises, nouvelles tentatives et annulations.

## Ouvrir tes tâches depuis Accueil

[Accueil](https://docs.tale.dev/fr/platform#home) liste les tâches ouvertes qui te sont attribuées ou qui attendent ta relecture, dans tous les projets que tu peux consulter ; **Tâches**, au-dessus de la liste, n’affiche qu’elles. Une tâche ouverte depuis **Accueil** s’affiche sur une page à part, à côté du panneau latéral, et non dans la boîte de dialogue du tableau :

- La demande vient en premier, sous forme de carte : la description, les pièces jointes et les sous-tâches.
- La discussion suit comme une conversation, des éléments les plus anciens aux plus récents, regroupés par jour. Elle réunit les commentaires et l’historique de la tâche, par exemple les changements de statut, les attributions et les exécutions d’agents.
- Le champ de commentaire se trouve en bas. Envoie avec **⌘+Entrée** ou **Ctrl+Entrée**, ou avec le bouton d’envoi rond ; **Entrée** seule passe à la ligne. Saisis `@` pour mentionner un agent ou une personne, avec le même effet que dans la boîte de dialogue du tableau. Le texte que tu n’as pas encore envoyé reste dans le champ pour cette tâche, ici comme dans la boîte de dialogue du tableau, et la ligne de la tâche dans **Accueil** affiche **Brouillon** tant que tu travailles ailleurs.
- **Détails**, à côté de la discussion, regroupe le statut, la priorité, la personne assignée, le relecteur, les dates, la répétition, les étiquettes et les dépendances, ainsi que **Suivre** et **Archiver**. Les propriétaires et administrateurs de l’organisation y trouvent aussi **Supprimer** : la tâche disparaît définitivement avec ses sous-tâches, leurs commentaires et leurs fichiers, et leurs exécutions d’agent en cours s’arrêtent. **Masquer les détails**, au bout de l’en-tête, replie ce panneau et **Afficher les détails** le rouvre. Dans une fenêtre trop étroite pour afficher les deux côte à côte, **Afficher les détails** ouvre plutôt les détails dans un volet au-dessus de la discussion — sur le côté, ou en bas de l’écran sur téléphone.

**Tableau**, dans l’en-tête, ouvre le tableau des tâches du projet. Une tâche ouverte depuis le tableau s’affiche toujours dans sa boîte de dialogue ; les deux vues modifient la même tâche. **Copier le lien**, l’icône de lien à côté de **Tableau**, copie le lien de cette page de tâche. Pour copier l’identifiant de la tâche, par exemple `WEB-2`, clique dessus dans la ligne sous le titre ; un message confirme chaque copie.

## Retrouver le travail à suivre

Réduis le tableau avec les filtres ou passe à la liste pour parcourir les tâches ligne par ligne. Garde les propositions dans le [Backlog](https://docs.tale.dev/fr/platform/projects/backlog) jusqu’à leur démarrage. Utilise des étiquettes pour les distinctions qui ne demandent pas un nouveau statut.

Le champ **Rechercher des tâches** et les filtres restreignent le tableau ensemble : chaque tâche qui correspond aux deux apparaît, quel que soit leur nombre. La recherche trouve les tâches dont le titre, la description ou l’identifiant, par exemple `WEB-12`, contient chacun des mots saisis, ainsi que celles dont un commentaire les contient tous. Le tableau affiche jusqu’à 2 000 tâches. Dans un projet plus grand, un message indique que seules les 2 000 premières sont affichées ; utilise la recherche pour atteindre les autres.

Si les tâches ne peuvent pas être chargées, le tableau l’indique au lieu d’afficher des colonnes vides, et ta recherche et tes filtres restent tels quels. Choisis **Réessayer** pour les charger. Quand une actualisation échoue, les tâches déjà affichées restent visibles, avec un message indiquant qu’elles apparaissent telles qu’au dernier chargement. Un message apparaît aussi quand les dépendances ou l’activité des agents et des relectures ne peuvent pas être chargées, car les tâches bloquées, les agents en cours, les questions ouvertes et les relectures en attente ne sont alors peut-être pas signalés. **Réessayer** dans un message recharge uniquement ce qui a échoué.

Au clavier, appuie sur **Entrée** sur **Filtre** : le panneau s’ouvre sur son premier filtre, **Assigné à**. Appuie sur **Entrée** pour le déplier, puis sur **Tab** pour atteindre ses options. Les touches fléchées en choisissent une, et le tableau suit aussitôt. **Espace** choisit l’option où se trouve le focus, et l’annule quand elle est déjà choisie. **Tab** passe au filtre suivant et **Échap** ferme le panneau.

Dans les vues **Tableau** et **Liste**, appuie sur **Tab** jusqu’à placer le focus sur le titre de la tâche, puis sur **Entrée** pour l’ouvrir.

Si tu peux modifier la tâche, place le focus sur son titre et appuie sur **Espace** pour la saisir. Déplace-la avec les touches fléchées, puis appuie de nouveau sur **Espace** pour la déposer. **Échap** annule le déplacement et laisse la tâche à sa place. Un lecteur d’écran nomme la tâche quand tu la saisis, puis annonce son statut et sa position pendant le déplacement.

Si une modification est refusée, vérifie l’état de la tâche avant de réessayer : une exécution active empêche de réassigner l’agent, des sous-tâches ouvertes empêchent la clôture, et ton rôle, ainsi que le fait que la tâche soit la tienne ou non, déterminent si tu peux la modifier.

# Bibliothèque de skills
Source: https://docs.tale.dev/fr/platform/workspace/skills

Un skill décrit une méthode de travail réutilisable : rédiger des notes de version, vérifier un brief ou préparer un document selon les conventions de ton équipe. Il contient un fichier d’instructions `SKILL.md` et, si nécessaire, des fichiers complémentaires. Entretiens-le dans **Paramètres > Skills**, puis [équipe les agents concernés](https://docs.tale.dev/fr/platform/agents/skills).

Un skill agit là où un agent fait le travail : un [agent de projet](https://docs.tale.dev/fr/platform/projects/project-agents) qui traite une [tâche](https://docs.tale.dev/fr/platform/projects/tasks), ou un nœud agent dans une [automatisation](https://docs.tale.dev/fr/platform/automations/concepts). Le chat répond aux questions et cherche dans les connaissances de ton organisation ; il n’utilise pas de skills, n’exécute pas de code et ne produit pas de fichiers. Pour faire produire un document avec un skill, confie une tâche à un agent qui en est équipé. Toute personne qui peut ouvrir le projet peut créer cette tâche ; équiper un agent du skill demande au moins le rôle Éditeur.

Chaque membre peut créer un skill et modifier les siens. Pour modifier ou supprimer le skill partagé d’une autre personne, il faut être administrateur de l’organisation. Ton organisation peut réserver le partage avec tout le monde à certains rôles ; voir [Qui peut partager avec tout le monde](https://docs.tale.dev/fr/platform/workspace/skills#who-can-share-with-everyone).

## Créer un petit skill

<Steps>

<Step title="Nommer le skill et préciser quand l’utiliser">

Ouvre **Paramètres > Skills**, puis **Ajouter un skill > Skill vierge**. Saisis un **Nom**, par exemple `brief-summary`, et une **Description** :

```text
Résume un brief de projet en indiquant la date de relecture, le responsable
et les questions ouvertes. À utiliser pour une passation ou une vérification rapide.
```

Le nom est un identifiant unique : lettres minuscules, chiffres et tirets simples, jusqu’à 64 caractères. La description indique au modèle dans quels cas lire le skill. Sous **Visibilité**, choisis qui voit le skill : **Organisation**, ou **Équipes** avec au moins une équipe. Clique sur **Créer** pour l’ajouter et ouvrir son éditeur.

</Step>

<Step title="Rédiger les instructions">

Sous **Instructions (corps)**, donne une procédure courte et un résultat vérifiable. Par exemple :

```markdown
Lis le brief fourni. Produis un tableau de trois lignes : date de relecture,
responsable et questions ouvertes. Cite la phrase qui justifie chaque réponse.
Écris « Non précisé » si l’information manque. Ne déduis pas une date de
lancement d’une date de relecture.
```

Ajoute des fichiers de référence lorsqu’ils aident à suivre la procédure. Place les exemples détaillés dans ces fichiers et précise quand l’agent doit les ouvrir.

</Step>

<Step title="Choisir le public et enregistrer">

À la création, **Organisation** est présélectionnée, sauf si ton organisation la réserve. Si le contenu s’adresse à un autre public, change-le sous **Visibilité** : **Équipes** demande au moins une équipe. Ajoute une icône ou des libellés si cela facilite la recherche, puis clique sur **Enregistrer**.

Créer un skill ne l’ajoute pas automatiquement à un agent. Ouvre l’agent du projet concerné et sélectionne le skill dans son équipement. Lance une petite tâche avec des données connues, puis compare le résultat aux instructions.

</Step>

</Steps>

<Frame caption="L’éditeur indique qui a créé le skill et réunit les fichiers du bundle, la description, les libellés et la visibilité, puis la section Instructions.">

![L’éditeur du skill docx affiche l’arborescence à côté de Créé par Fourni avec Tale, la description, l’icône, les libellés, la visibilité Organisation et le titre Instructions.](https://docs.tale.dev/images/platform/skill-library-detail.webp)

</Frame>

## Importer un bundle existant

Utilise **Ajouter un skill > Téléverser un zip** ou **Téléverser un dossier**. Le bundle doit contenir `SKILL.md` à sa racine. Des références, ressources et scripts peuvent l’accompagner :

```text
brief-summary/
├── SKILL.md
└── references/
    └── example-brief.md
```

L’aperçu présente les métadonnées, le partage, la licence et la liste des fichiers avant que **Téléverser le bundle** n’enregistre quoi que ce soit. Vérifie le contenu et le public. Sans `visibility`, le partage est ouvert à l’organisation. Si ton organisation le réserve et que tu ne peux pas publier, l’aperçu le signale et **Téléverser le bundle** reste indisponible ; ajoute `visibility: team` et les identifiants de tes équipes dans `SKILL.md`. Quand tu crées un skill d’équipe ou modifies ses équipes, tu ne peux indiquer que des équipes de ton organisation, et seulement les tiennes si tu n’es pas administrateur. Tu peux conserver la liste existante même si une équipe a été supprimée depuis. Un `owner` indiqué dans le fichier est ignoré : un nouveau skill t’appartient. Un skill remplacé garde son propriétaire actuel ou t’appartient s’il n’en avait pas. Si le nom existe déjà, Tale demande s’il faut remplacer le skill ; ce remplacement concerne aussi les agents qui l’utilisent.

<Warning>

L’import ne lance aucune tâche et n’exécute aucun fichier. Une fois le skill ajouté à un agent, ses instructions guident toutefois un agent de code qui peut disposer d’outils, d’identifiants et d’un shell. Examine les instructions et scripts inconnus avant de l’équiper. Un skill n’ajoute pas de barrière de permissions.

</Warning>

## Comprendre le partage

| Visibilité | Qui peut le lire | Quels agents de projet peuvent l’utiliser |
| --- | --- | --- |
| **Organisation** | Tous les membres de l’organisation | Les agents de tous les projets |
| **Équipes** | Les membres des équipes sélectionnées | Les agents des projets associés à une équipe correspondante |

L’accès du projet détermine son équipement, même si tu peux personnellement lire davantage de skills. Un projet ouvert à l’organisation peut utiliser les skills de l’organisation. Les anciens skills privés restent visibles par leur propriétaire, mais aucun agent ne peut les équiper. Les nouveaux skills privés ne sont pas acceptés.

Restreindre la visibilité demande une confirmation, car certains agents peuvent perdre l’accès. La suppression a la même conséquence pratique : une exécution qui dépend du bundle manquant ne peut plus le préparer. Vérifie les usages d’un skill partagé avant de le restreindre ou de le retirer.

### Qui peut partager avec tout le monde {#who-can-share-with-everyone}

Par défaut, chaque membre peut partager un skill avec toute l’organisation. Un admin peut réserver ce droit aux éditeurs et au-delà, ou aux propriétaires et aux admins, dans [Partage des skills](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits#skill-sharing), et autoriser certains membres à publier avec la compétence **Publier des skills pour l'organisation**. Quand ton organisation le réserve et que tu ne peux pas publier :

- **Organisation** n’est pas disponible sous **Visibilité**, et un nouveau skill commence avec **Équipes**. Tu peux partager avec tes propres équipes.
- Un skill partagé avec l’organisation que tu as créé ne peut pas être modifié sur place. Restreins-le à tes équipes, avec d’autres modifications dans le même enregistrement si besoin, ou supprime-le.
- L’aperçu du téléversement signale un bundle qui serait partagé avec toute l’organisation, y compris un bundle sans `visibility`, et **Téléverser le bundle** reste indisponible.

Les skills déjà partagés avec l’organisation le restent.

## Voir qui a créé et modifié un skill

La colonne **Créé par** indique le membre qui a créé chaque skill. Recherche un nom dans la bibliothèque pour retrouver tout ce que cette personne a partagé. Pour un skill sans créateur enregistré, comme les skills de documents fournis à la création de ton organisation, elle affiche **Fourni avec Tale** ; pour un skill installé par une release de configuration gérée, **Release de configuration** suivi du membre dont le téléversement l’a installé. Quand le créateur a quitté l’organisation, elle affiche **Ancien membre**.

<Frame caption="Paramètres > Skills — la colonne Créé par nomme le membre qui a écrit chaque skill et marque les skills de documents comme Fourni avec Tale.">

![La bibliothèque liste sept skills : brief-summary et release-notes créés par Alex Rivera, puis docx, pdf, pptx, visual-aspect-analyzer et xlsx marqués Fourni avec Tale, tous partagés avec l’Organisation.](https://docs.tale.dev/images/platform/skill-library-list.webp)

</Frame>

Ouvre un skill pour voir **Créé par** et **Dernière modification par** : le membre dont l’enregistrement ou le téléversement dans Tale a produit la version actuelle. **Dernière modification par** n’apparaît pas si personne n’a modifié le skill depuis sa création, ou si son fichier a changé en dehors de Tale depuis la dernière modification. La liste des skills dans l’[équipement d’un agent](https://docs.tale.dev/fr/platform/agents/skills) indique elle aussi le créateur sous chaque skill.

Tale consigne dans le journal d’audit la création, la modification, le téléversement et la suppression d’un skill, ainsi que chaque changement de sa visibilité ou de ses équipes. Les administrateurs et propriétaires trouvent ces entrées dans **Paramètres > Gouvernance > Journaux**, catégorie **Skill**.

## Référence du fichier

Voici un `SKILL.md` minimal :

```markdown
---
name: brief-summary
description: Résume un brief de projet. À utiliser pour les passations et vérifications.
visibility: org
---

Lis le brief. Indique la date de relecture, le responsable et les questions
ouvertes. Cite les preuves et marque les informations absentes « Non précisé ».
```

| Champ | Signification |
| --- | --- |
| `name` | Correspond au nom du dossier. `anthropic` et `claude` sont réservés. |
| `description` | Quand et pourquoi lire le skill ; 1 024 caractères maximum. |
| `visibility` / `teams` | `org`, ou `team` accompagné des identifiants d’équipes. L’interface remplit ces valeurs. |
| `owner` | L’identifiant utilisateur du membre qui a créé le skill. Tale le renseigne ; une valeur présente dans un fichier téléversé est ignorée. |
| `license` | Les conditions d’utilisation fournies par l’auteur. |
| `recommended-packages` | Les dépendances conseillées ; l’import ne les installe pas. |
| `disable-model-invocation` | Demande un usage explicite du skill. Cette métadonnée est une instruction, pas une restriction d’accès. |
| `icon` / `labels` | La présentation dans la bibliothèque ; jusqu’à huit libellés de 40 caractères au plus. |

Tale conserve les clés de frontmatter inconnues. Le frontmatter est limité à 16 KB et le fichier `SKILL.md` complet à 512 KB. Les instructions lues souvent doivent rester bien plus courtes.

## Actualiser et résoudre les problèmes

Ouvre une ligne pour modifier la description, les instructions, les libellés et la visibilité. L’arborescence **Bundle** permet d’examiner les fichiers complémentaires. Les agents ne sont pas liés à une version précise : la prochaine préparation utilise le bundle courant. Teste donc les changements partagés sur une tâche représentative.

Le champ **Libellés** accepte jusqu’à huit libellés séparés par des virgules, de 40 caractères au plus chacun. Si la liste est plus longue ou qu’un libellé est trop long, le champ indique ce qu’il faut retirer ou raccourcir, et **Enregistrer** reste indisponible. Rien de ce que tu as saisi n’est perdu. L’arborescence **Bundle** retient, pour chaque skill et dans ton navigateur, les dossiers que tu as repliés.

Si Tale ne parvient pas à charger un skill ou l’un de ses fichiers, la boîte de dialogue l’indique et propose **Réessayer**. Si une actualisation échoue, la version déjà affichée reste en place, modifications non enregistrées comprises. Un fichier retiré est signalé comme absent du bundle, et un fichier vide comme vide.

Si un agent ne trouve pas le skill, vérifie son équipement et la visibilité pour le projet. Tale lui montre un extrait de la description, limité à 300 caractères, pour l’aider à choisir un skill pertinent. Indique donc d’abord quand le skill s’applique. S’il ignore un skill équipé, nomme-le dans la tâche et compare le résultat avec ses instructions. [Skills des agents](https://docs.tale.dev/fr/platform/agents/skills) explique comment le bundle équipé est préparé et présenté à l’agent.

En cas d’erreur d’import, vérifie que `SKILL.md` est à la racine, que son frontmatter est valide et que son nom est accepté. L’erreur précise les chemins ou limites de taille en cause. Pour retirer un bundle, ouvre-le et choisis **Supprimer le skill** après avoir vérifié les agents concernés.

# Définir les règles d’approbation des automations
Source: https://docs.tale.dev/fr/self-hosted/configuration/approvals

Les règles d’approbation déterminent si une écriture de connector s’exécute immédiatement ou attend une personne. Par défaut, une écriture vers un système externe exige une approbation ; les connectors internes authentifiés par la plateforme peuvent écrire. Adapte cette limite par organisation lorsque son processus de revue l’exige.

## Définir la politique de l’organisation

Enregistre les règles dans `TALE_CONFIG_DIR/<orgSlug>/governance/approval-policy.yml`. Chaque règle désigne exactement un `connector` ou une `action` complète, puis une `decision`.

Cet exemple exige une revue pour les écritures du connector interne `task` et autorise `imap-smtp.send` sans approbation distincte :

```yaml
rules:
  - connector: task
    decision: require_approval
  - action: imap-smtp.send
    decision: auto_approve
```

<Warning>

`auto_approve` autorise l’écriture correspondante sans revue humaine à ce point de contrôle. Vérifie l’action exacte, les identifiants et les destinataires prévus avant d’autoriser une action externe comme l’envoi d’un e-mail.

</Warning>

Utilise les identifiants du catalogue livré, pas les noms traduits affichés. Une action s’écrit `<connector>.<action>` ; les décisions autorisées sont `auto_approve` et `require_approval`.

## Comprendre les priorités

Une règle d’action prime sur une règle de connector, quel que soit leur ordre. Parmi les règles de même précision, la dernière correspondance gagne. Sans correspondance, Tale applique le comportement interne ou externe décrit plus haut. Évite de répéter une cible pour que la politique reste lisible.

La politique s’applique aux nouvelles évaluations. Une approbation en attente reste en attente si tu assouplis la règle ; elle n’est pas accordée silencieusement. Ce fichier ne supprime pas les autres contrôles, comme la publication d’une automation ou la clôture d’une tâche qui nécessite une revue.

## Vérifier l’effet

Teste avec une automation isolée et des données sans conséquence avant d’activer la règle en production. Vérifie une opération correspondante et une opération qui doit garder son comportement par défaut. Consulte l’approbation en attente et la trace d’exécution dans le [parcours des approbations](https://docs.tale.dev/fr/platform/approvals/configure).

Chaque nouvelle décision d’écriture lit la politique et le slug actuels de l’organisation, sans utiliser le bref cache d’affichage. Si la politique est invalide ou si son répertoire de configuration est indisponible, l’opération s’arrête avant l’écriture. Répare la configuration avant de réessayer. Seule l’absence du fichier dans une arborescence accessible permet d’utiliser les règles par défaut. Un fichier `.yml` invalide ne laisse jamais la place à un fichier `.json` voisin. Les approbations déjà enregistrées conservent leur décision, y compris celles en attente et les opérations déjà autorisées.

# Choisir l’authentification
Source: https://docs.tale.dev/fr/self-hosted/configuration/authentication

Tale prend en charge les comptes locaux par e-mail et mot de passe, le SSO propre à chaque organisation et les identités transmises par un reverse proxy de confiance. Choisis selon l’endroit où ton équipe gère ses identités et la personne responsable des comptes. L’authentification et le provisionnement sont distincts : le SSO authentifie, tandis que les invitations, le provisionnement à la connexion ou SCIM gèrent l’appartenance.

## Choisir l’intégration adaptée

| Environnement | Configuration | Prérequis principal |
| --- | --- | --- |
| Comptes locaux gérés dans Tale | Connexion locale et invitations | Secrets stables et URL de l’instance accessible. |
| Fournisseur d’identité d’entreprise existant | SSO : Microsoft Entra ID, OIDC générique, OAuth2 ou SAML 2.0 | Une application IdP avec les URL exactes de callback ou de métadonnées. |
| Une application ou un proxy authentifie déjà ses utilisateurs | En-têtes de confiance, par organisation | Une clé créée dans **Paramètres > SSO d’entreprise** et un proxy qui l’envoie avec les en-têtes d’identité. |

Le SSO d’entreprise et les en-têtes de confiance se configurent tous deux par organisation. Prépare et teste la correspondance des identités avant de changer le mécanisme de comptes existants.

## Fixer d’abord l’URL publique

Définis `SITE_URL` et l’éventuel chemin de base pris en charge avec l’adresse réellement utilisée. Termine la [configuration TLS et des domaines](https://docs.tale.dev/fr/self-hosted/configuration/tls-and-domains) avant d’enregistrer les redirections chez le fournisseur d’identité.

Garde `BETTER_AUTH_SECRET` identique entre les processus backend de l’instance. Utilise le secret généré par le déploiement ou injecte-le depuis ton gestionnaire. Des valeurs différentes peuvent interrompre la connexion même si le fournisseur d’identité accepte la personne.

## Utiliser des comptes locaux

La connexion locale conserve des empreintes de mots de passe dans la base applicative. La [première configuration](https://docs.tale.dev/fr/self-hosted/install/first-admin) crée le Propriétaire initial ; les membres suivants rejoignent l’organisation sur invitation. Configure l’envoi d’e-mails si ton parcours d’invitation ou de récupération en dépend.

Vérifie avec un compte de test l’invitation, la connexion, la déconnexion et la récupération. Une session Propriétaire qui fonctionne ne prouve pas qu’un nouveau membre peut rejoindre l’organisation.

Tale n’envoie aucun courriel de vérification : une adresse est donc confirmée par qui crée le compte. Le premier Propriétaire issu de la configuration initiale, une personne ajoutée par un administrateur dans **Paramètres > Membres** et le compte créé par le déploiement valent tous comme confirmation, et le compte est utilisable immédiatement. Les applications connectées lisent cela dans l’attribut `email_verified` de l’identité délivrée par Tale : un collègue qui vient d’être ajouté peut donc s’y connecter tout de suite. Un compte issu du SSO d’entreprise, de SCIM ou d’en-têtes de confiance conserve en revanche ce qu’indique son annuaire.

## Connecter le SSO d’entreprise

Configure l’organisation sous **Paramètres > SSO d’entreprise**. Microsoft Entra ID et OIDC générique découvrent les endpoints depuis l’émetteur ; OAuth2 utilise des URL explicites d’autorisation, de token et de userinfo. SAML utilise des métadonnées, une URL de réception des assertions et des certificats de signature.

<Frame caption="Copie les URL de l’instance en cours pour inclure son domaine et son chemin de déploiement.">

![La page du SSO d’entreprise affiche le choix du protocole et les champs de connexion Microsoft Entra ID.](https://docs.tale.dev/images/platform/settings-enterprise-sso.webp)

</Frame>

Utilise les URL de callback et de métadonnées affichées. Les callbacks OIDC natifs utilisent `/api/sso/callback` ; la route de compatibilité `/http_api/api/sso/callback` reste prise en charge pour les anciennes inscriptions. L’URL enregistrée chez l’IdP doit correspondre à celle utilisée dans le parcours.

Suis [SSO d’entreprise et provisionnement](https://docs.tale.dev/fr/platform/admin/enterprise-sso) pour les protocoles, les claims, les rôles par défaut, les équipes et SCIM. Teste la connexion dans une session distincte avant de fermer ta session d’administration. Une découverte validée ne prouve ni les claims, ni les droits sur les groupes, ni une connexion complète.

## Faire confiance à un proxy d’authentification

Une application qui connecte déjà ses utilisateurs peut les faire entrer dans une organisation via son reverse proxy. Un administrateur active la fonction dans **Paramètres > SSO d’entreprise**, carte **En-têtes de confiance** : choisis le rôle le plus élevé que le proxy peut attribuer, puis crée une clé et copie-la, car elle ne s’affiche qu’une fois. Fais pointer la connexion du proxy vers `/api/trusted-headers/authenticate`, avec cette clé dans l’en-tête `Remote-Internal-Secret` et les en-têtes d’identité `Remote-Email`, `Remote-Name`, `Remote-Role` et `Remote-Teams`. La [référence d’environnement](https://docs.tale.dev/fr/self-hosted/configuration/environment-reference) indique les variables `TRUSTED_*_HEADER` qui permettent de renommer ces en-têtes.

La clé détermine l’organisation. Un membre de cette organisation est connecté ; une adresse que l’instance n’a jamais vue devient un nouveau membre avec le rôle attribué ; un compte existant d’une autre organisation est refusé. Le rôle Propriétaire ne peut jamais être attribué, et un rôle au-dessus du plafond de l’organisation est ramené à ce plafond. À chaque connexion, le siège du membre suit le rôle attribué, si bien que **Paramètres > Membres** montre ce que le proxy a attribué ; un siège Propriétaire ne change jamais. Désactiver la carte refuse toutes les clés sans en révoquer aucune ; révoquer une clé ne met pas fin aux sessions qu’elle a ouvertes.

<Warning>

Le proxy doit supprimer les en-têtes d’identité fournis par le client, définir ses propres valeurs authentifiées et n’ajouter la clé qu’à la requête de passage. Quiconque détient la clé peut se connecter comme n’importe quel membre que le proxy désigne dans cette organisation : traite-la comme un mot de passe et fais-la tourner depuis la carte.

</Warning>

`Remote-Teams` contient des noms d’équipe séparés par des virgules, par exemple `Finance,Operations` ; une entrée `id:name` comme `t-fin:Finance` est aussi acceptée. Les équipes sont rapprochées et créées par nom. Un en-tête absent laisse les équipes inchangées ; un en-tête présent mais vide retire les appartenances accordées par cette synchronisation. Des entrées invalides peuvent donc supprimer ces appartenances. Celles accordées manuellement restent intactes.

Un visiteur qui arrive par le proxy est connecté dès la première requête que l’application fait pour elle-même : si cette requête porte la clé et l’en-tête d’identité mais aucun cookie de session, le backend crée la session sur place et l’application s’ouvre connectée — sans page de connexion, sans redirection. Si l’application atterrit malgré tout sur sa page de connexion (un cookie périmé, par exemple), la page envoie elle-même le navigateur vers l’adresse de passage, et un refus revient sur cette page avec sa raison. Rediriger `/log-in` du proxy directement vers l’adresse de passage reste possible ; l’adresse répond à un succès par une redirection vers l’application et à un refus par une page avec son code d’état. Le proxy possédant la session, l’application ne propose pas de déconnexion à un membre connecté ainsi ; après une déconnexion pour inactivité, la connexion automatique marque une pause jusqu’à ce que le membre continue depuis l’avis.

Pour afficher Tale dans la page de l’application elle-même plutôt que dans un onglet, un administrateur ajoute l’origine de cette page sous **Intégration dans un cadre**, sur la même page de paramètres. Les pages de Tale répondent alors avec une règle `frame-ancestors` qui nomme `'self'` et les origines listées au lieu de refuser tout cadre, et l’en-tête `X-Frame-Options` disparaît. La liste appartient à une organisation, mais l’enveloppe de connexion est un seul document pour toute l’instance : une origine admise par n’importe quelle organisation peut donc la charger. Le navigateur n’envoie le cookie de session dans un cadre que si la page englobante est sur le même site que Tale, par exemple un sous-domaine de l’hôte ou Tale servi sous le domaine de l’hôte ; un cadre d’un autre site affiche la page de connexion.

## Diagnostiquer les échecs de connexion

| Symptôme | Première vérification |
| --- | --- |
| L’IdP refuse une redirection | Compare l’URL enregistrée à celle de Tale, protocole, hôte et chemin compris. |
| La redirection revient sans connecter | Vérifie l’accès au callback, les cookies et les noms de claims. |
| Un membre reçoit le mauvais rôle | Vérifie le rôle par défaut et les règles avec ses claims réels. |
| Les équipes synchronisées disparaissent | Inspecte le claim de groupes ou `Remote-Teams` ; distingue absence et valeur vide. |
| La connexion par en-têtes est refusée | Vérifie que la carte est activée pour cette organisation, que la clé n’est pas révoquée, et les noms d’en-têtes configurés dans le proxy. |

Teste les changements de correspondance dans une organisation de staging et garde un accès administratif de secours déjà vérifié. Ces changements peuvent affecter tous les membres dont l’identité dépend de la connexion.

# Publier les configurations d’un client
Source: https://docs.tale.dev/fr/self-hosted/configuration/config-releases

Une release de configuration installe un workflow vérifié et ses propres skills dans une organisation et un projet existants. Son identité est le commit source complet. Suis ce parcours si l’application reste en place ; utilise les [déploiements gérés](https://docs.tale.dev/fr/self-hosted/install/cli-install) pour une nouvelle instance ou un changement d’environnement d’exécution.

## Comprendre le résultat de chaque commande

| Commande | Résultat à vérifier avant de continuer |
| --- | --- |
| `config build` | Manifeste et archives compilées depuis une révision source committée. |
| `config verify --rebuild` | Une reconstruction indépendante correspond aux artefacts examinés. |
| `config stage` | Dossier transférable contenant uniquement les fichiers de déploiement et leur inventaire de hashes. |
| `config deploy` | Workflow et skills propres installés, relus et enregistrés dans un reçu persistant. |
| `config verify-native` | Comparaison en lecture seule avec le contenu actuellement installé. |

Un ID ou une session **native** appartient ici à l’instance Tale cible. Un **reçu** décrit le résultat d’un déploiement ; il ne remplace pas la vérification du serveur actuel. Valider le format et les octets ne prouve pas le résultat métier de l’automatisation : conserve les tests métier dans le dépôt client.

## Avant de commencer

Installe la [CLI Tale](https://docs.tale.dev/fr/self-hosted/install/cli-install) et fixe une révision qui prend en charge le format des paquets et les API du serveur cible. Les commandes de configuration désignent explicitement la source et la destination. Elles ne nécessitent ni `tale.json` local, ni contexte Docker, ni dossier source Tale voisin. Le parseur et le validateur intégrés vérifient les champs pris en charge, sans ajouter les fonctions d’un serveur plus récent à une ancienne instance.

Il te faut un descripteur et un paquet committés, une organisation et un projet existants, ainsi qu’une session native autorisée. Si le paquet possède ses propres skills, utilise l’ID natif de cet opérateur comme propriétaire du build. Cet ID est distinct de ceux du projet, de l’organisation et d’une identité externe.

Pour une instance neuve sans ID natifs, utilise un déploiement géré avec une nouvelle identité explicite, un projet symbolique et `skillOwner: "operator"`. Il transfère des sources vérifiées et compile après avoir prouvé l’opérateur natif ; les commandes de version autonomes exigent toujours des ID résolus. Garde la configuration métier dans l’arbre source du client. Les paramètres de modèles externes appartiennent à la déclaration de déploiement.

Les exemples utilisent le client synthétique `example-team` et l’automatisation `document-review`. Injecte le cookie complet de session dans `TALE_CONFIG_COOKIE` depuis ton gestionnaire de secrets. Garde-le hors des arguments, sources, archives, reçus et logs.

## Committer le descripteur et le paquet

Place le descripteur dans `tale/client.json`, les paquets sous `tale/packs/` et les tests métier à côté. Conserve aussi les éventuels catalogues de releases historiques à cet endroit. Les chemins du descripteur sont relatifs à son propre répertoire.

Ajoute `.tale/` au `.gitignore` du client si cette entrée manque. Les builds par défaut y conservent l’état des verrous locaux ; les commandes avec une sortie explicite se coordonnent à côté de cette sortie. La configuration maintenue utilise `tale/` sans point.

```json
{
  "schemaVersion": 1,
  "clientId": "example-team",
  "sourceRepository": "https://github.com/example-team/client-app",
  "automations": [
    {
      "name": "document-review",
      "displayName": "Document review",
      "packPath": "packs/document-review",
      "releasesPath": "releases/document-review",
      "logicalSkillSlugs": ["record-check"],
      "requiredExternalSkills": []
    }
  ]
}
```

`logicalSkillSlugs` nomme les répertoires de skills fournis par ce paquet. `requiredExternalSkills` nomme les dépendances déjà installées dans Tale : la CLI vérifie leur présence, mais cette release ne fixe pas leurs octets. Garde les identifiants, hôtes cibles et ID de projets dans la déclaration de déploiement. Committe le descripteur et le paquet ; le compilateur lit les objets Git, pas les modifications non committées.

## Construire et vérifier le commit source

Définis `CONFIG_REPO` avec le dossier source, `CONFIG_SOURCE_COMMIT` avec le commit source complet de 40 caractères et `TALE_NATIVE_USER_ID` avec l’ID natif de l’opérateur. Choisis un nouveau répertoire absolu `CONFIG_BUILD` hors du dossier source. Ces commandes construisent la release et reconstruisent ses octets indépendamment.

```bash
tale --json config build \
  --repo "$CONFIG_REPO" \
  --descriptor tale/client.json \
  --automation document-review \
  --source-commit "$CONFIG_SOURCE_COMMIT" \
  --skill-owner "$TALE_NATIVE_USER_ID" \
  --output "$CONFIG_BUILD"

tale --json config verify \
  --repo "$CONFIG_REPO" \
  --descriptor tale/client.json \
  --automation document-review \
  --manifest "$CONFIG_BUILD/$CONFIG_SOURCE_COMMIT.json" \
  --rebuild
```

Le manifeste par défaut utilise le schéma 4/compilateur 3. Il enregistre `releaseRef` égal à `sourceCommit`, l’arbre du paquet, le hash du descripteur et l’inventaire compilé complet. La sortie contient le ZIP canonique, un ZIP par skill propre au paquet et un ZIP d’installation du workflow seul. Les slugs des skills portent le SHA source complet ; les métadonnées du compilateur préservent leur identité logique. Les octets complets incluent le propriétaire déclaré. Changer ce propriétaire exige un nouveau commit source et une nouvelle release.

Exige des octets identiques lors de la reconstruction et lance les tests métier du client sur le ZIP canonique extrait. Conserve les artefacts vérifiés et relève `artifactSha256` dans `CONFIG_ARTIFACT_SHA256`. La validation du format natif prouve que le paquet peut être interprété ; elle ne valide pas ses résultats métier. Un nouveau déploiement fondé sur les sources ne nécessite aucun commit supplémentaire des fichiers générés.

## Préparer le dossier de transfert

Utilise un dossier source dont `HEAD` correspond à `CONFIG_SOURCE_COMMIT`. Définis `CONFIG_STAGE` avec un nouveau répertoire absolu hors de ce dossier source. L’option `DEPLOYMENT_COMMIT` enregistre le commit complet de ta déclaration de déploiement ; omets `--deployment-ref` si tu n’en suis pas.

```bash
tale --json config stage \
  --repo "$CONFIG_REPO" \
  --descriptor tale/client.json \
  --automation document-review \
  --config-ref "$CONFIG_SOURCE_COMMIT" \
  --skill-owner "$TALE_NATIVE_USER_ID" \
  --client example-team \
  --deployment-ref "$DEPLOYMENT_COMMIT" \
  --output "$CONFIG_STAGE"
```

La préparation construit le descripteur et le paquet committés, vérifie les archives indépendamment et rassemble uniquement les fichiers autorisés avec un inventaire de leurs hashes. Les modifications non committées n’y entrent pas. Compare le hash de l’artefact au build vérifié. Transfère le répertoire comme une unité complète ; la destination native n’a besoin ni du dossier source client ni de son identifiant Git.

Fixe l’URL du dépôt client, le SHA source complet, la révision de CLI et, si nécessaire, celle du déploiement. La provenance dépend aussi de ton dossier source de confiance : une URL dans le descripteur ne prouve pas quel remote a fourni un objet Git local.

## Déployer et relire le résultat

Définis `TALE_CONFIG_URL`, `TALE_CONFIG_ORIGIN`, `TALE_ORG_ID` et `TALE_PROJECT_ID` avec la destination native approuvée. Conserve `CONFIG_RECEIPT` sur un stockage persistant. Après examen des fichiers préparés, fournis `--yes` pour un déploiement sans interaction déjà autorisé, puis lance une vérification séparée en lecture seule. Utilise la même référence de déploiement optionnelle que pour la préparation.

```bash
tale --json --yes config deploy \
  --stage "$CONFIG_STAGE" \
  --url "$TALE_CONFIG_URL" \
  --origin "$TALE_CONFIG_ORIGIN" \
  --org "$TALE_ORG_ID" \
  --project "$TALE_PROJECT_ID" \
  --receipt "$CONFIG_RECEIPT" \
  --config-ref "$CONFIG_SOURCE_COMMIT" \
  --source-repository https://github.com/example-team/client-app \
  --artifact-sha256 "$CONFIG_ARTIFACT_SHA256" \
  --deployment-ref "$DEPLOYMENT_COMMIT"

tale --json config verify-native \
  --stage "$CONFIG_STAGE" \
  --url "$TALE_CONFIG_URL" \
  --origin "$TALE_CONFIG_ORIGIN" \
  --org "$TALE_ORG_ID" \
  --project "$TALE_PROJECT_ID" \
  --config-ref "$CONFIG_SOURCE_COMMIT" \
  --source-repository https://github.com/example-team/client-app \
  --artifact-sha256 "$CONFIG_ARTIFACT_SHA256" \
  --deployment-ref "$DEPLOYMENT_COMMIT"
```

L’URL cible désigne l’API accessible ; l’origine est celle du navigateur, y compris quand l’API utilise une adresse locale derrière un proxy. L’ID natif connecté doit correspondre au propriétaire des skills déclaré.

Le déploiement crée les skills manquants par le téléversement natif réservé à la création et vérifie chaque octet installé. Il réutilise des octets existants identiques et refuse tout contenu différent sous le même slug de release. L’import du workflow seul ne peut écrire aucun skill. Avant d’annoncer le succès, la CLI vérifie le workflow déployé, les paramètres, la présentation, le contrat de tâche et le lien au projet.

Lance `verify-native` après le déploiement et les tests d’exploitation. Cette commande n’importe rien et ne crée ni version ni reçu. Un déploiement répété relit aussi le contenu natif avant de signaler une release inchangée. Un reçu conservé ne prouve pas, à lui seul, les octets actuels.

## Reprendre un déploiement interrompu

Conserve le dossier exact de transfert et le reçu pendant l’enquête. Choisis la suite selon l’état indiqué par la CLI :

| État | Prochaine étape sûre |
| --- | --- |
| Un reçu fiable enregistre une progression partielle | Relance avec le même dossier, la même cible et le même reçu. Les skills identiques peuvent être réutilisés. |
| Une version correspondante est déjà déployée | Relis-la avec `verify-native`. Un nouveau déploiement vérifie aussi avant d’annoncer l’absence de changement. |
| Réponse d’import perdue, seule une version non publiée est visible | Arrête et examine. L’API native ne peut pas lire son contrat de tâche complet avant déploiement ; la CLI ne peut donc pas prouver qu’elle peut la réutiliser. |
| Un slug de skill de release contient d’autres octets | Préserve les indices et identifie la release ou la modification en conflit. N’écrase pas le contenu pour faire réussir la vérification. |
| Le reçu est illisible ou désigne une autre cible | Récupère le bon reçu ou résous l’écart avant de relancer. N’invente jamais un reçu de réussite. |

Coordonne les déploiements vers la même cible. Le verrou local n’empêche ni un autre hôte ni un administrateur de modifier le contenu natif. Après reprise, relance les vérifications métier du client et la comparaison native indépendante.

## Reconstruire une release historique

Les releases sémantiques existantes restent compatibles : `build --config-version` choisit le schéma 3/compilateur 2 ; `stage --config-version` utilise le catalogue committé et ses références explicites de catalogue et d’ops. Garde les manifestes et archives d’origine intacts. Un descripteur peut enregistrer des snapshots source historiques avec leurs sommes de contrôle pour une reconstruction hors ligne ; seuls les champs pris en charge par ce format sont vérifiables. Les anciens skills partagés ne sont réutilisables que si cela est explicitement autorisé et que leurs octets sont déjà identiques. Restaure un contenu historique différent par une nouvelle release.

La reconstruction historique demande des outils supplémentaires. Le schéma 1 utilise Git `archive --mtime` ; vérifie que ton Git prend cette option en charge. Le schéma 2/compilateur 1 utilise la bibliothèque standard de Python 3. Le schéma 3/compilateur 2, le schéma 4/compilateur 3 et le déploiement natif n’ont pas besoin de Python.

Conserve ensemble sources, tests métier, archives vérifiées, révision de CLI, références de déploiement et reçu. Les cookies de session et identifiants restent dans ton gestionnaire de secrets, hors de ces artefacts. [Mises à niveau](https://docs.tale.dev/fr/self-hosted/operate/upgrades) et [Sauvegardes et restauration](https://docs.tale.dev/fr/self-hosted/operate/backups-and-restore) couvrent la reprise de l’application et de ses données.

# Choisir et déplacer les stockages
Source: https://docs.tale.dev/fr/self-hosted/configuration/data-residency

Choisis le stockage de trois catégories : enregistrements applicatifs, connaissances recherchables et fichiers d’origine. Déplacer l’une ne déplace pas les autres. Le stockage ne détermine pas non plus où un fournisseur de modèles ou un connecteur traite une requête ; inclus ces destinations dans ton évaluation de résidence.

## Choisir la portée du changement

| Stockage | Paramètre du déploiement | Paramètre propre à une organisation |
| --- | --- | --- |
| Base applicative : utilisateurs, chats, exécutions et audit | `DATABASE_URL` | Aucun réglage de base applicative distincte sur cette page. |
| Base de connaissances : texte extrait, embeddings, index et contenu web | `KNOWLEDGE_DATABASE_URL` | **Paramètres > Résidence des données > Base de connaissances** |
| Fichiers d’origine : documents, pièces jointes, audio et médias générés | `OBJECT_STORE_*` | **Paramètres > Résidence des données > Stockage objet** |

Le stack fourni place `tale_app` et `tale_knowledge` dans un service Postgres tout en gardant deux bases distinctes. D’autres installations utilisent des services séparés. Les valeurs d’environnement générées choisissent les connexions par défaut ; un processus applicatif démarré seul ne crée pas des identifiants de stockage objet valides.

Les modifications d’organisation demandent les droits Admin ou Propriétaire. Sans connexion propre, Tale utilise le stockage par défaut et conserve l’isolation par organisation. Une connexion de connaissances configurée mais invalide échoue au lieu de basculer silencieusement vers une autre base.

## Préparer une base externe

Prépare base et identifiants avant de modifier Tale. La base applicative exige un rôle autorisé à appliquer ses migrations de schéma. La base de connaissances demande `vector` ; `pg_search` active la partie BM25 de la recherche hybride. Avec pgvector seul, la recherche vectorielle fonctionne sans cette composante par mots-clés. Tale crée schémas et tables de connaissances, mais n’installe pas d’extensions sur ta base.

Utilise une connexion Postgres directe ou compatible avec les sessions. Le pooling par transaction ne convient pas aux verrous de session, à `LISTEN` et aux requêtes préparées du stack. Pour `sslmode=verify-ca` ou `verify-full`, fournis les racines PEM requises via `POSTGRES_CA_FILE` et monte le fichier dans les rôles backend. Vérifie réseau et permissions depuis l’environnement de déploiement.

Avant la bascule, décide comment transférer les données applicatives ou connaissances existantes et prends des sauvegardes coordonnées. Enregistrer une connexion change seulement la destination des opérations suivantes ; cela ne copie pas les anciennes lignes et ne réindexe pas automatiquement les documents.

## Modifier les valeurs par défaut

Modifie `.env`, puis déploie ou recrée les services backend concernés. `docker compose restart` garde l’ancien environnement. Si tu déplaces les deux bases hors du service fourni, conserve son ancien volume jusqu’à l’acceptation des nouveaux stockages et du plan de reprise.

Pour le stockage objet par défaut, le backend synchronise `default/object-storage/connection.json` et son fichier de secrets depuis l’environnement au démarrage. Le résultat distingue `seeded`, `reconciled`, `skipped` si les identifiants manquent et `ignored` pour un fichier géré par l’opérateur. Avec `"managedBy": "operator"`, tu prends la responsabilité du fichier à la place de cette synchronisation.

Changer le bucket ou le point d’accès par défaut ne copie pas les objets existants. Transfère-les avec les outils du stockage en conservant clés et métadonnées nécessaires, puis coordonne la bascule avant de retirer l’ancien stockage. Bases et buckets externes ne sont pas couverts par les snapshots de volumes CLI. Mets à jour les procédures de [Sauvegardes et restauration](https://docs.tale.dev/fr/self-hosted/operate/backups-and-restore) lors du changement.

## Connecter la base de connaissances d’une organisation

1. Ouvre **Paramètres > Résidence des données** dans l’organisation cible et renseigne **Base de connaissances** : hôte, port, base, utilisateur, mode SSL et mot de passe.
2. Choisis **Tester la connexion**. Le test vérifie d’abord les champs comme **Enregistrer** et signale un hôte, une base de données ou un utilisateur manquant sous son champ au lieu de s’exécuter. Vérifie accès et extensions ; une connexion réussie ne prouve pas que l’ancien corpus a migré.
3. Enregistre lorsque la destination et le plan de transfert sont prêts. Les requêtes suivantes utilisent la connexion choisie sans redémarrage de conteneur.
4. Indexe un document contrôlé, cherche une expression connue et vérifie que les contenus antérieurs nécessaires restent disponibles.

Les fichiers se trouvent sous `$TALE_CONFIG_DIR/<orgSlug>/knowledge/` : `connection.json`, `connection.secrets.json` et `embedding.json`. Les secrets utilisent SOPS lorsqu’une clé age est configurée. Supprimer la connexion rétablit le routage par défaut ; les données externes restent en place, mais ne sont plus accessibles par la connexion retirée.

### Adapter le modèle d’embedding au corpus {#le-modele-dembedding-de-lorganisation}

Dans **Modèle d’embedding**, choisis fournisseur et identifiants enregistrés, puis le modèle. **Modèle** liste les modèles d’embedding que porte le catalogue du fournisseur et remplit la largeur des vecteurs indiquée par le catalogue. Un fournisseur qui ne propose aucun modèle d’embedding, comme Anthropic, ne peut pas être retenu : la ligne affiche **Ne propose pas d’embeddings**, et tu choisis un autre fournisseur. Lorsque Tale ne connaît aucune largeur de vecteurs pour le fournisseur, saisis le tag du modèle (pour Azure OpenAI, le nom de ton déploiement) et la largeur des vecteurs que ce modèle produit. C’est le cas d’un fournisseur livré dont le catalogue ne liste aucun modèle d’embedding, d’un fournisseur défini par ton organisation dont la liste de modèles n’en contient aucun, et d’Azure OpenAI, dont les déploiements portent tes propres noms. La [déclaration `embedding`](https://docs.tale.dev/fr/self-hosted/configuration/providers#ce-quun-connecteur-declare) du fournisseur départage les deux cas, et l’enregistrement refuse un fournisseur déclaré sans embeddings, quelle que soit la voie de la requête. Si Tale ne peut pas vérifier les déclarations, la section le signale et propose **Réessayer** ; tant que la vérification n’a pas répondu, aucun modèle ne peut être choisi. Une URL de base facultative sélectionne un point d’accès compatible OpenAI. Sans modèle configuré, l’indexation et la recherche de connaissances ne peuvent pas fonctionner normalement.

La largeur est fixée par base à la première utilisation. Les organisations qui partagent cette base doivent utiliser la même largeur ; une autre largeur demande une base compatible séparée. Changer de modèle peut aussi rendre les anciens vecteurs incompatibles à largeur identique. Prévois une réindexation avec le modèle choisi au lieu de mélanger des embeddings sans vérification.

`embedding.json` accepte `minSimilarity`, le seuil du volet vectoriel de la recherche de l’assistant ; sa valeur par défaut est `0.45`. Le formulaire conserve ce réglage du fichier sans proposer de champ. Ajuste-le avec des requêtes représentatives. La recherche REST n’applique un seuil que si la requête en fournit un ; ce n’est pas une limite universelle pour toutes les recherches.

### Doser les requêtes vers un serveur d’embedding auto-hébergé {#capacite-du-serveur-dembedding}

Deux autres réglages facultatifs de `embedding.json` décrivent la charge que le serveur d’embedding peut absorber. Définis-les lorsque tu exploites ce serveur toi-même, par exemple un serveur de modèles sur ton propre matériel qui calcule une requête à la fois et met les autres en file d’attente. Comme `minSimilarity`, ils n’existent que dans le fichier : le formulaire des paramètres les conserve à l’enregistrement, et la CLI les déclare dans la ressource `knowledge-embedding`.

- `maxConcurrentRequests` (de 1 à 64, 3 par défaut) fixe le nombre de requêtes d’embedding que Tale garde en cours en même temps vers ce modèle pour l’organisation. L’indexation des documents, celle des e-mails reçus, les explorations de sites web et les recherches partagent cette limite. Les requêtes suivantes attendent dans leur ordre d’arrivée, mais une recherche passe devant les lots d’indexation en attente. Chaque processus Tale compte séparément : l’API et chaque réplique de worker peuvent donc chacune atteindre la limite. Une valeur plus basse s’applique aussitôt, une valeur plus haute une fois terminées les requêtes lancées sous l’ancienne. Sur un serveur qui calcule une requête à la fois, une valeur plus élevée n’ajoute aucune charge ; elle allonge seulement l’attente de chaque requête.
- `minTokensPerSecond` (tout nombre positif) est le débit le plus bas auquel le serveur calcule les embeddings de ce modèle sous sa charge habituelle. Mesure-le pendant que d’autres traitements tournent sur le même matériel, comme un modèle de chat, mais sans compter le temps qu’une requête passe à attendre derrière d’autres requêtes. Tale ajoute lui-même ce temps d’attente.
- `maxTokensPerMinute` et `maxRequestsPerMinute` (nombres entiers) dosent ce que Tale envoie à ce modèle en une minute, pour l’organisation dans chaque processus Tale. Règle-les sur les limites par minute d’un fournisseur hébergé, comptées par compte fournisseur sur tous les déploiements qui partagent la clé : un lot d’indexation qui dépasserait une limite attend qu’une part suffisante de la dernière minute soit écoulée, si bien qu’une exploration de centaines de pages est dosée au lieu d’être refusée par des `429`. Tale estime les tokens d’après les caractères, en comptant large, respecte aussi un soixantième de chaque limite à l’intérieur de chaque seconde – un fournisseur applique sa valeur par minute à la seconde également – et dimensionne chaque requête pour tenir dans cette seconde. Un `429` que le fournisseur renvoie malgré tout suspend toutes les requêtes de l’organisation vers ce modèle et est réessayé à l’échelle de la minute ; une recherche n’est freinée par aucun des deux. Alibaba Cloud Model Studio autorise par exemple 1 800 requêtes et 1 000 000 de tokens par minute pour text-embedding-v4.

```json
{
  "providerSlug": "local-embedding",
  "model": "example-embedding",
  "dimensions": 1024,
  "baseUrl": "https://embeddings.example.internal/v1",
  "maxConcurrentRequests": 2,
  "minTokensPerSecond": 800,
  "maxTokensPerMinute": 1000000,
  "maxRequestsPerMinute": 1800
}
```

Chaque requête d’embedding a un plafond : 15 minutes pour l’indexation et 5 minutes pour une recherche, qu’une réponse du chat attend. Sans `minTokensPerSecond`, Tale ne peut pas savoir combien de temps la file d’attente du serveur peut durer ; une requête peut donc utiliser tout son plafond. Avec ce réglage, Tale accorde à chaque requête le temps nécessaire au travail qui peut la précéder ou l’accompagner sur le serveur, en plus du sien. Ce travail comprend les tokens de la requête elle-même, estimés largement à partir de ses caractères, les autres requêtes que ce processus Tale peut avoir en cours, et `maxConcurrentRequests` autres venant d’autres clients. Tale compte chacune de ces requêtes comme au moins un lot complet de 64 textes de 1 024 tokens chacun, divise le total par `minTokensPerSecond` et ajoute 50 %, sans jamais accorder moins de 60 secondes ni plus que le plafond. Avec l’exemple ci-dessus, un lot complet de texte ordinaire dispose d’environ huit minutes et une recherche de son plafond de cinq minutes. Une recherche s’arrête aussi au bout de cinq minutes au total, attente d’une place libre comprise. Si le serveur est partagé par plus de clients qu’un seul autre processus Tale avec la même limite, indique un débit plus bas.

Une requête dont le délai a expiré n’est pas renvoyée aussitôt : le serveur l’avait depuis le début, et la répéter ne ferait qu’allonger sa file d’attente. Une connexion refusée, une limite de débit ou une erreur du serveur est relancée après une pause qui s’allonge à chaque tentative, ou après la pause qu’un serveur chargé demande avec `Retry-After`, d’au plus une minute. Si un serveur demande une pause plus longue, Tale le laisse tranquille. Si l’un des lots d’une requête en plusieurs lots échoue, par exemple pour une longue page web, Tale annule les autres lots, en cours ou en attente, pour que le serveur cesse de les calculer.

L’indexation d’un document dispose d’au plus 15 minutes par tentative. Quand un gros document ou une longue file d’attente demande davantage, la tentative s’arrête à cette limite et annule sa requête en cours ; une requête dont le délai expire met aussi fin à la tentative. La tentative suivante commence après une pause qui s’allonge à chaque fois et reprend après les fragments déjà enregistrés. Si un document n’est toujours pas terminé après six tentatives, il apparaît en échec ; **Relancer l'indexation** reprend alors à partir des fragments enregistrés.

## Connecter le bucket d’une organisation

1. Prépare un bucket compatible S3 et les permissions objet nécessaires. Configure CORS pour les véritables origines du navigateur et les méthodes requises `GET`, `PUT` et `HEAD`.
2. Dans **Stockage objet**, saisis région, point d’accès si nécessaire, bucket, préfixe de clé facultatif et identifiants. Utilise l’adressage path-style si ton stockage le demande.
3. Lance **Tester la connexion**, puis enregistre. Une région ou un bucket manquant, ou une valeur qui dépasse la longueur maximale d’un champ, est signalé sous son champ avant tout envoi. Le test serveur écrit, lit et supprime un objet de test ; il ne teste pas CORS dans le navigateur.
4. Envoie et télécharge un fichier contrôlé dans le navigateur avant de compter sur la nouvelle connexion.

Les nouveaux imports utilisent le bucket de l’organisation. Les anciens fichiers du stockage par défaut peuvent rester accessibles grâce aux références mixtes ; connecter le bucket ne suffit donc pas à relocaliser l’historique. La configuration réside dans `$TALE_CONFIG_DIR/<orgSlug>/object-storage/connection.json` et `connection.secrets.json`.

Supprimer la connexion envoie les nouveaux imports vers le stockage par défaut. Les objets existants restent dans le bucket de l’organisation ; Tale ne pourra les relire qu’après rétablissement de la connexion.

### Déplacer les fichiers existants

Après avoir enregistré le bucket, utilise **Déplacer les fichiers existants** dans la même section. Examine l’aperçu proposé, confirme le déplacement et suis sa progression. Garde la connexion stable jusqu’à la fin.

Le rattrapage parcourt les documents référencés et leur historique, fichiers importés, audio synthétisé et transcriptions vidéo de cette organisation. Il copie chaque objet avec son type de contenu, vérifie sa taille à destination, puis supprime la source. Les clés restent identiques et une copie déjà vérifiée peut être terminée après interruption. Il s’agit d’un déplacement, pas d’une sauvegarde supplémentaire ni d’un contrôle cryptographique du contenu.

La destination doit différer du stockage par défaut. En cas d’échec, examine dernière erreur et progression avant de lancer un autre passage. Conserve les deux stockages jusqu’à vérification du résultat et du téléchargement d’anciens fichiers représentatifs. [Secrets avec SOPS](https://docs.tale.dev/fr/self-hosted/configuration/secrets-with-sops) explique la protection des fichiers de connexion.

# Référence des variables d'environnement
Source: https://docs.tale.dev/fr/self-hosted/configuration/environment-reference

Cette référence indique les variables de déploiement, leurs valeurs par défaut et les processus concernés. Le fichier `.env` du projet est une source possible ; l’environnement des conteneurs et un gestionnaire de secrets peuvent aussi fournir les valeurs. Le [fichier d’exemple](https://github.com/tale-project/tale/blob/main/.env.example) contient la configuration correspondante.

Après une modification, recrée les services concernés avec ta procédure de déploiement. `docker compose restart` conserve l’environnement existant. Les fichiers de configuration d’organisation ont un cycle distinct.

## Comment lire cette page

Les tableaux indiquent le nom, la valeur par défaut et le rôle de chaque variable. Les valeurs requises doivent atteindre le service concerné ; certaines sont générées par le déploiement. Les variables facultatives peuvent rester absentes. Une valeur par défaut peut venir de Compose plutôt que du processus lui-même.

Consulte aussi les commentaires du fichier d’exemple et vérifie l’environnement effectif du service lorsqu’une valeur manque.

## Identité de domaine (obligatoire au premier boot)

| Nom         | Défaut              | Description                                                                                                                               |
| ----------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `HOST`      | `localhost`         | **Obligatoire.** Nom d'hôte sans protocole. Utilisé pour le réseau Docker et le mail sortant.                                             |
| `SITE_URL`  | `https://localhost` | **Obligatoire.** URL canonique complète incluant le schéma et tout port non standard. Les callbacks d'auth l'utilisent.                   |
| `ADDITIONAL_SITE_URLS` | non défini | **Optionnel.** Autres origines sur lesquelles le même déploiement répond, séparées par des virgules ou des espaces (ex. `https://a.example,https://b.example`). Chacune est une entrée complète. Voir [TLS et domaines](https://docs.tale.dev/fr/self-hosted/configuration/tls-and-domains#plusieurs-domaines-a-la-fois). |
| `TOTP_ENVIRONMENT` | non défini | Nom d’environnement des entrées de l’application d’authentification, lu par `backend-api` et le rôle `all` : 1–32 lettres, chiffres, tirets bas ou traits d’union. Les espaces aux extrémités sont supprimés et les lettres passent en majuscules. `pr` ou une valeur absente conserve `Tale` ; avec `te`, les nouvelles entrées portent le nom `Tale <TE>`. Une valeur invalide empêche le backend de démarrer. |
| `BASE_PATH` | non défini          | **Optionnel.** Préfixe de chemin pour les déploiements en sous-chemin derrière un reverse proxy (ex. `/app`). Laisse vide pour la racine. |
| `DOCS_URL` | `https://docs.<HOST>` | Origine publique de l’hôte de documentation distinct dans le proxy. Le service docs doit aussi faire partie du déploiement. |

`SITE_URL` désigne l’origine publique canonique. Protocole, hôte et port doivent correspondre à l’adresse du navigateur et aux callbacks enregistrés. `BASE_PATH` ajoute le préfixe de chemin ; le proxy normalise une barre oblique finale. Les adresses supplémentaires sont des origines sans chemin dans `ADDITIONAL_SITE_URLS`. Une origine supplémentaire invalide empêche le backend de démarrer.

La documentation utilise sa propre origine. Sur l’origine de la plateforme, `/docs` ouvre la référence API interactive et `/openapi.json` fournit son schéma. `DOCS_URL` change l’hôte de documentation du proxy ; cette variable n’installe pas le service docs et ne réécrit pas les liens des clients déjà compilés. `TALE_DOCS_URL` dans les outils de compilation SEO et le préfixe `DOCS_BASE_URL` du service docs, utilisé à la compilation comme à l’exécution, sont des réglages distincts.

Une modification de `TOTP_ENVIRONMENT` s’applique aux nouveaux codes QR et URI de configuration, y compris lorsqu’un secret existant est affiché à nouveau. Elle ne change ni les secrets ni les noms des entrées déjà enregistrées sur ton appareil ; tu peux renommer ces entrées dans ton application d’authentification.

## TLS

| Nom         | Défaut       | Description                                                                                                           |
| ----------- | ------------ | --------------------------------------------------------------------------------------------------------------------- |
| `TLS_MODE`  | `selfsigned` | Un de `selfsigned`, `letsencrypt`, `external`. Voir [TLS et domaines](https://docs.tale.dev/fr/self-hosted/configuration/tls-and-domains). |
| `TLS_EMAIL` | non défini   | E-mail de contact pour les notifications Let's Encrypt. Optionnel mais recommandé en production.                      |
| `TRUSTED_PROXIES` | `private_ranges` | Avec `TLS_MODE=external`, les adresses dont le proxy accepte les en-têtes transférés : plages CIDR séparées par des espaces, ou `private_ranges`. Les autres modes l’ignorent. Voir [TLS et domaines](https://docs.tale.dev/fr/self-hosted/configuration/tls-and-domains). |

`selfsigned` crée un certificat Caddy local. Fais confiance à sa CA uniquement pour ta propre installation contrôlée. `letsencrypt` exige un domaine public et les ports 80/443 accessibles. Avec `external`, Caddy sert HTTP derrière un proxy TLS.

## Secrets de sécurité (obligatoire)

| Nom                     | Défaut                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `BETTER_AUTH_SECRET` | valeur d'exemple dans le fichier | Secret d’authentification commun aux réplicas backend. Génère une valeur aléatoire robuste, par exemple avec `openssl rand -base64 32`, et garde-la stable. Un changement peut invalider les sessions et les connexions en cours. |
| `ENCRYPTION_SECRET_HEX` | valeur d'exemple dans le fichier | Racine de chiffrement de 32 octets en hexadécimal ; génère-la avec `openssl rand -hex 32`. Conserve la valeur correspondant aux secrets existants. La remplacer ne migre pas les données chiffrées : rétablis la bonne clé ou saisis les secrets concernés par leur parcours prévu. |
| `INSTANCE_SECRET`       | valeur d'exemple dans le fichier | **Obligatoire.** Le secret racine de l’instance : 64 caractères hex, généré par `tale init` (à la main : `openssl rand -hex 32`). Au démarrage, Tale en dérive la clé HMAC des mots de passe d’app WebDAV (`WEBDAV_APP_PASSWORD_HMAC_KEY`) sauf si tu définis cette clé toi-même, et les jetons éphémères avec lesquels les sessions sandbox récupèrent des blobs sont signés par une sous-clé de la même dérivation. Garde-le stable entre les déploiements : une rotation re-dérive la clé et invalide chaque mot de passe d’app WebDAV. |
| `SANDBOX_TOKEN`         | valeur d'exemple dans le fichier | **Obligatoire.** Secret HMAC partagé entre le backend et le spawner sandbox : le backend signe chaque appel au spawner avec, et le spawner rejette les appels non signés. Sans lui, le spawner refuse de démarrer — il tient le socket docker de l’hôte, il n’a donc pas de mode non signé. `tale init` et `bun run dev` le génèrent ; une stack que tu composes toi-même le pose avant le premier boot (`openssl rand -hex 32`). Une rotation veut dire redémarrer le backend et le spawner ensemble — ils doivent s’accorder. |
| `SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD` | non défini | **Requis pour les appels de harness sandbox.** Le backend utilise cet identifiant d’administration pour créer les clés de session. Donne la même valeur au gateway : tant qu’il n’a pas de compte d’administration, il n’en crée un que pour un appelant qui présente ce secret, et c’est ainsi que le backend prend la main sur le gateway à la première utilisation. L’image du gateway prend toujours cette valeur comme jeton de configuration (`BIFROST_SETUP_TOKEN`), à la place de celui qu’on aurait donné au conteneur. Le gateway conserve ensuite une empreinte du mot de passe dans `llm-gateway-data`. Garde le secret correspondant ou utilise la procédure de récupération/rotation prise en charge par le gateway. Ne supprime pas son état comme réparation habituelle. Le nom par défaut est `admin` (`SANDBOX_LLM_GATEWAY_ADMIN_USERNAME`). |

Remplace les valeurs livrées dans `.env.example` avant d'exposer l'instance — ce sont des espaces réservés volontairement non sûrs.

## Base de données

Tale utilise `tale_app` pour les données applicatives et `tale_knowledge` pour les fragments, embeddings et pages web. Le déploiement standard conserve les deux dans le service Postgres `db`, avec l’alias `knowledge-db`. Tu peux configurer des connexions externes séparément.

| Nom                                       | Défaut                                                              | Description                                                                                                                                                                                                                                                                                                                                                |
| ----------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DB_PASSWORD` | `tale_password_change_me` | **Requis pour Postgres fourni.** Mot de passe commun aux bases applicative et documentaire dans le déploiement standard. Remplace l’exemple avant la production. |
| `DATABASE_URL`                            | construit depuis `DB_PASSWORD`                                      | **Optionnel.** URL de connexion de la base opérationnelle. Pose-la pour diriger le backend vers un Postgres que tu exploites toi-même : il n’a besoin d’aucune extension ni d’un superutilisateur, seulement d’une base et d’un rôle qui peut créer des schémas. Relue à chaque démarrage. |
| `DATABASE_POOL_MAX` | `10` | **Optionnel.** Nombre maximal de connexions par pool de la base opérationnelle. Chaque réplique de `backend-api` ou `backend-worker` utilise normalement jusqu’au double de cette valeur (pool applicatif et file de jobs). Les opérations sur les sandboxes peuvent temporairement ouvrir une connexion supplémentaire par place occupée du pool applicatif, soit un pic égal au triple de cette valeur par réplique. Compare ce pic au `max_connections` de la base. |
| `POSTGRES_CA_FILE`                        | non défini                                                          | **Optionnel.** Chemin d’un bundle PEM auquel **toutes** les connexions Postgres font confiance : la base opérationnelle, le corpus de connaissances et les bases que les organisations apportent elles-mêmes. Nécessaire dès qu’une URL demande `sslmode=verify-ca` ou `verify-full` face à un fournisseur dont la racine n’est pas livrée avec Node — Amazon RDS est le cas courant. Si tes bases utilisent des fournisseurs différents, concatène leurs racines dans un seul fichier. |
| `KNOWLEDGE_DATABASE_URL` | `postgresql://tale:${DB_PASSWORD}@knowledge-db:5432/tale_knowledge` | URL de connexion du corpus documentaire par défaut. La modifier sélectionne une autre base, sans migrer les fragments ni les vecteurs existants. |
| `KNOWLEDGE_DB_POOL_MAX` | `10` | **Optionnel.** Connexions qu’un processus backend ouvre vers le corpus documentaire. Chaque job d’indexation en occupe une pendant qu’il écrit une tranche de fragments ; si `WORKER_CONCURRENCY` autorise plus de jobs simultanés que cela, ils attendent le pool : augmente les deux ensemble. Comme `DATABASE_POOL_MAX`, cette valeur compte par réplique dans le `max_connections` de la base du corpus. |
| `KNOWLEDGE_DB_NAME` | `tale_knowledge` | Nom de la base documentaire créée par l’initialisation du service de base fourni. |
| `KNOWLEDGE_INDEX_REPAIR_INLINE_MAX_BYTES` | `1073741824`                                                        | **Optionnel.** Taille maximale (en octets) d'un index de recherche BM25 que le backend reconstruit de façon synchrone au démarrage quand il le trouve corrompu ; au-delà, un job d'arrière-plan le reconstruit pendant que les écritures vers ce corpus sont refusées. Voir [Architecture des conteneurs](https://docs.tale.dev/fr/self-hosted/operate/container-architecture). |
| `KNOWLEDGE_INDEX_REPAIR_DISABLED` | non défini | `1` ou `true` désactive la vérification et la réparation BM25 au démarrage. Cela ne corrige aucune corruption ; les échecs de lecture ou d’écriture nécessitent une enquête et une réparation contrôlée. |
| `KNOWLEDGE_CRAWL_DOCUMENT_MAX_BYTES` | `104857600` | **Optionnel.** Taille maximale (en octets) d’un document (PDF, DOCX, XLSX, PPTX, ODT) que le crawler de sites télécharge et lit ; au-delà, la page est notée comme trop volumineuse. Les pages HTML ont leur propre budget de 2 Mio. Chaque récupération reste en mémoire pendant l’extraction du texte, et jusqu’à cinq sites sont analysés en même temps : dimensionne la mémoire du backend en conséquence. Une valeur inférieure à 1 Mio, ou qui n’est pas un entier, retombe sur la valeur par défaut. |

L’URL générée est `postgresql://tale:${DB_PASSWORD}@db:5432/tale_app` ; `APP_DB_NAME` change le nom de base. Le corpus utilise les schémas `private_knowledge` et `public_web`. Une organisation peut choisir ses propres connexions sous **Paramètres > Résidence des données**. Enregistrer une autre URL ne migre aucune donnée. Consulte [Résidence des données](https://docs.tale.dev/fr/self-hosted/configuration/data-residency).

Deux points à connaître avant de diriger l’une des deux bases vers ta propre infrastructure :

- **Le corpus de connaissances exige `pgvector` déjà installé.** Tale crée lui-même ses schémas et ses tables sur une base vide, mais n’installe jamais d’extension — la table des chunks porte une colonne `vector`, donc `CREATE EXTENSION vector;` doit avoir été lancé sur la base cible. Le `pg_search` de ParadeDB reste optionnel : sans lui la recherche retombe sur le vectoriel seul au lieu d’échouer. La base opérationnelle, elle, n’a besoin d’aucune extension.
- **Utilise une connexion Postgres directe ou compatible avec les sessions.** Notifications de tâches, verrous de migration et requêtes préparées dépendent de ces propriétés. Vérifie tout proxy de connexion géré selon ces exigences.

## Store d'objets

Les fichiers et médias utilisent un stockage compatible S3. Ces variables règlent la connexion par défaut. Une connexion propre à l’organisation est prioritaire ; une panne du stockage par défaut ne signifie pas que les buckets de toutes les organisations sont inaccessibles.

| Nom                              | Défaut                       | Description                                                                                                                                                                           |
| -------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OBJECT_STORE_ACCESS_KEY` | non défini | Clé d’accès de la connexion S3 par défaut. Pour MinIO fourni, configure la même valeur dans `MINIO_ROOT_USER`. Sans identifiants, aucune connexion par défaut n’est créée ; une organisation peut néanmoins avoir sa propre connexion valide. |
| `OBJECT_STORE_SECRET_KEY` | auto-généré par `tale init` | Clé secrète du stockage par défaut. Pour MinIO fourni, elle doit correspondre à `MINIO_ROOT_PASSWORD`. Coordonne la rotation du stockage et du backend, puis teste lecture et écriture. Changer le mot de passe ne déplace pas les fichiers et ne les rend pas intrinsèquement orphelins. |
| `OBJECT_STORE_BUCKET`            | `tale-blobs`                 | Bucket où vivent les blobs. Le backend le crée s’il est absent et que la clé y est autorisée ; s’il existe déjà, il l’utilise tel quel. |
| `OBJECT_STORE_ENDPOINT` | `http://object-store:9000` dans le compose livré | Endpoint du stockage vu par le backend. AWS S3 n’utilise pas d’endpoint personnalisé ; retire ou vide explicitement celui du stockage fourni dans l’environnement Compose effectif. MinIO, R2 ou un autre service compatible utilisent une URL dédiée. |
| `OBJECT_STORE_REGION`            | `us-east-1`                  | Région de signature. Signifiante sur AWS ; arbitraire mais exigée par le signataire pour un store auto-hébergé. |
| `OBJECT_STORE_FORCE_PATH_STYLE`  | `true` avec endpoint, `false` sans | Adresse le bucket en `endpoint/bucket/key` plutôt qu’en `bucket.endpoint/key`. Le défaut suit l’endpoint et convient donc aux deux cas ; ne le pose que pour un store qui déroge à sa propre forme. |
| `OBJECT_STORE_PREFIX`            | non défini                   | Préfixe de clés dans le bucket, pour que les blobs de Tale partagent un bucket avec d’autres données. Vide signifie la racine du bucket. |
| `OBJECT_STORE_PUBLIC_ENDPOINT`   | `${SITE_URL}` (posé par la CLI) | Où le **navigateur** atteint le store. Le proxy publie le store embarqué sous `/<bucket>/*` et transfère les URLs présignées telles quelles, donc téléversements et téléchargements se font directement navigateur↔store. Si ce point d’accès est l’une des origines du déploiement, un lien destiné à un navigateur sur une autre origine configurée est signé pour cette origine. Laisse-le vide pour un bucket que le navigateur atteint déjà. |

Le proxy fourni expose la route des objets au navigateur sans publier le port d’administration du stockage. Un stockage externe peut utiliser son propre endpoint public.

### Comment ces variables arrivent dans le déploiement en cours

Au démarrage, le backend rapproche `default/object-storage/connection.json` de son environnement. Recrée `backend-api` et `backend-worker` avec les nouvelles valeurs. Les messages de démarrage distinguent les résultats suivants :

| Ligne | Signification |
| --- | --- |
| `object store (seeded)` | il n’y avait aucune connexion ; une a été écrite depuis l’environnement |
| `object store (reconciled)` | l’environnement a changé ; la connexion a été mise à jour |
| `object store (adopted)` | une connexion écrite par une version antérieure a été reconnue et est désormais suivie |
| `object store (ignored)` | la connexion porte `"managedBy": "operator"`, ces variables ne font donc rien |
| `object store (skipped)` | Aucune paire d’identifiants fournie pour créer la connexion par défaut. Vérifie si une connexion existante ou propre à l’organisation reste utilisable. |
| *(rien)* | déjà aligné — l’état normal |

Si tu préfères gérer le store à la main, mets `"managedBy": "operator"` dans `connection.json` : le backend ne touchera plus jamais ce fichier. Un fichier sans `managedBy` du tout — écrit avant ce comportement — n’est repris que s’il nomme encore le même bucket sur le même endpoint que l’environnement ; si tu l’avais repointé à la main, ta modification reste.

Droits sur le bucket : le backend vérifie l’existence du bucket avec `HeadBucket` et ne le crée que s’il est absent. Une clé qui peut lire, écrire et supprimer des objets sans pouvoir créer de bucket suffit donc, à condition que tu crées le bucket toi-même. Les téléversements et téléchargements présignés passent par le navigateur : un bucket externe a donc aussi besoin d’une politique CORS autorisant l’origine de ton déploiement en `GET`, `PUT` et `HEAD` — voir [Résidence des données](https://docs.tale.dev/fr/self-hosted/configuration/data-residency).

## Confidentialité du journal d'audit

Un pepper pseudonymise les données personnelles enregistrées lors des connexions échouées. Les versions précédentes généraient aussi `TALE_AUDIT_SIGNING_KEY` et `TALE_AUDIT_SIGNING_KEY_PREVIOUS`. Plus rien ne les lit : tu peux conserver ou supprimer une valeur existante.

| Nom                               | Défaut                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TALE_AUDIT_PEPPER` | auto-généré par `tale init` | Au moins 16 caractères pour pseudonymiser les échecs de connexion : HMAC-SHA256 de l’e-mail et de l’adresse IP tronquée. Sans valeur, ces champs d’audit restent en clair et le backend avertit. La rotation empêche de corréler les nouveaux identifiants avec les anciens ; la conservation suit la politique appliquée de l’organisation. |

Voir [Intégrité du journal d'audit](https://docs.tale.dev/fr/self-hosted/operate/security/audit-log-integrity) pour le modèle de vérification.

## Observabilité

| Nom                         | Défaut     | Description                                                                                                                                                            |
| --------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SENTRY_DSN`                | non défini | DSN Sentry pour le suivi d'erreurs. Laisse vide pour désactiver. Compatible avec GlitchTip et Bugsink auto-hébergés.                                                   |
| `SENTRY_ENVIRONMENT` | non défini | Libellé commun aux erreurs du navigateur, du backend et de la sandbox. Les déploiements gérés utilisent leur `name` existant par défaut ; une référence d’environnement explicite peut définir un libellé canonique sans renommer le déploiement. |
| `SENTRY_TRACES_SAMPLE_RATE` | non défini | Taux d’échantillonnage facultatif des traces du navigateur (`0.0`–`1.0`), indépendant de celui du backend. |
| `BACKEND_SENTRY_TRACES_SAMPLE_RATE` | `0` | Taux d’échantillonnage des spans HTTP et des tâches du backend (`0.0`–`1.0`). Nécessite `SENTRY_DSN` et une destination acceptant les transactions Sentry ; `0` désactive les spans. |
| `METRICS_BEARER_TOKEN` | non défini | Jeton Bearer pour les routes `/metrics/*` du proxy. Sans jeton configuré, elles répondent 401. Restreins séparément l’accès réseau aux endpoints internes des processus. |
| `UMAMI_URL` | non défini | Origine HTTPS de la passerelle de collecte authentifiée. HTTP est accepté uniquement pour les tests locaux sur `localhost`, `127.0.0.1` ou `[::1]`. Exige un identifiant de site et un jeton valides ; aucun chemin, paramètre de recherche ni identifiant de connexion dans l’URL. |
| `UMAMI_WEBSITE_ID` | non défini | UUID du site Umami. Une valeur absente ou invalide désactive la collecte. Utilise un identifiant distinct par déploiement. |
| `UMAMI_PROXY_TOKEN` | non défini | Jeton Bearer de la passerelle, réservé au serveur : 16 à 256 lettres ASCII, chiffres ou caractères de `._~-`. Ne l’injecte jamais dans la configuration du navigateur. |

Définir `METRICS_BEARER_TOKEN` expose les endpoints de métriques derrière le token : `/metrics/platform`, `/metrics/backend` (les métriques du backend applicatif) et `/metrics/sla-rules`. Voir [Configuration d'observabilité](https://docs.tale.dev/fr/self-hosted/configuration/observability-config) pour la configuration de scrape.

## Chiffrement des secrets de fournisseur

SOPS protège les fichiers de secrets de configuration compatibles. Les identifiants actuels des fournisseurs en base utilisent `ENCRYPTION_SECRET_HEX`, décrit avec les secrets de sécurité plus haut.

| Nom | Défaut | Description |
| --- | --- | --- |
| `SOPS_AGE_KEY` | non défini | Une clé privée age directe. Prime sur le fichier de clés. |
| `SOPS_AGE_KEY_FILE` | non défini | Chemin accessible au processus, avec une ou plusieurs clés privées age, une par ligne. Monte le fichier dans chaque conteneur concerné. |

Sans clé age, le module SOPS écrit les fichiers compatibles en clair avec les permissions `0600`. Les fichiers déjà chiffrés exigent toujours leur clé. Lis [Secrets avec SOPS](https://docs.tale.dev/fr/self-hosted/configuration/secrets-with-sops) avant de modifier ces variables.

Les identifiants de fournisseurs peuvent référencer une variable préfixée par `TALE_PROVIDER_KEY_` (40 caractères maximum). Les courtiers d’abonnement utilisent le préfixe distinct `TALE_TOKEN_SOURCE_` (60 maximum). Ces champs contiennent des noms de variables, pas les secrets. Injecte les valeurs dans les processus backend et recrée les conteneurs concernés après modification. [Fournisseurs](https://docs.tale.dev/fr/self-hosted/configuration/providers) décrit ce fonctionnement.

## Applications OAuth des connecteurs

Les connecteurs OAuth (Gmail, Google Drive, Outlook, Teams, Slack, …) résolvent leur application fournisseur d’abord par organisation : une app configurée sous **Paramètres > Connectors > Apps OAuth** gagne pour cette organisation. L’environnement fournit la valeur par défaut du déploiement en dessous (et reste la seule source pour Slack, dont la vérification de signature des événements s’exécute avant qu’aucune organisation ne soit connue). Pour chaque slug de connecteur :

| Nom                                    | Défaut | Description                                                                                                               |
| -------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| `CONNECTOR_OAUTH_<SLUG>_CLIENT_ID`     | unset  | Identifiant client OAuth pour ce connecteur. Slug en majuscules, tirets remplacés par des tirets bas (`gmail` → `GMAIL`). |
| `CONNECTOR_OAUTH_<SLUG>_CLIENT_SECRET` | unset  | Secret client correspondant.                                                                                              |
| `CONNECTOR_SLACK_SIGNING_SECRET`       | unset  | Le secret de signature de l’app Slack. L’endpoint d’événements entrants vérifie chaque livraison avec lui et renvoie 503 tant qu’il manque. |

Enregistre `${SITE_URL}${BASE_PATH}/api/connectors/oauth2/callback` sur l’application fournisseur, et pour Slack aussi `${SITE_URL}${BASE_PATH}/api/connectors/slack/events` comme Events Request URL. Détails : [Connectors (développement)](https://docs.tale.dev/fr/develop/connectors).

## Import cloud Knowledge (Documents)

Les autorisations OneDrive / Google Drive par utilisateur pour **Connaissances → Documents** sont distinctes des connectors d’organisation et de la connexion. Ici aussi, une app d’organisation configurée sous **Paramètres > Connectors > Apps OAuth** prime — l’entrée **google-drive** est partagée avec la voie connector, et **OneDrive / SharePoint (import de connaissances)** a sa propre entrée ; les chaînes ci-dessous s’appliquent partout où l’organisation n’en a pas configuré. Enregistre cette URI de redirection sur l’app Microsoft (ou Google) :

`${SITE_URL}${BASE_PATH}/api/cloud-import/oauth2/callback`

Résolution des identifiants pour OneDrive (premier match gagne) :

| Nom                                            | Description                                   |
| ---------------------------------------------- | --------------------------------------------- |
| `CLOUD_IMPORT_MICROSOFT_CLIENT_ID` / `_SECRET` | App dédiée à l’import Knowledge (préférée).   |
| `CLOUD_IMPORT_MICROSOFT_TENANT_ID`             | ID d’annuaire (tenant) de cette app.          |
| `AUTH_MICROSOFT_ENTRA_ID_ID` / `_SECRET`       | App de connexion Microsoft.                   |
| `AUTH_MICROSOFT_ENTRA_ID_TENANT_ID`            | ID d’annuaire (tenant) de l’app de connexion. |

Les inscriptions d’app Entra mono-tenant exigent une URL d’autorisation propre au tenant — `/common` échoue avec AADSTS50194. Définis l’ID de tenant (ou `organizations` / `common` pour une app multi-tenant). S’il est absent, Tale reprend le tenant de l’issuer SSO Entra de l’organisation s’il est configuré.

L’écran de consentement Microsoft demande Graph **Files.Read** et **Sites.Read.All** (liste/téléchargement OneDrive et SharePoint), **User.Read** (libellé du compte) et **offline_access** (jeton de rafraîchissement pour la sync). Cette autorisation est intentionnelle et par utilisateur — elle n’est pas attachée à la connexion à Tale.

Google Drive utilise uniquement une app dédiée (pas de repli sur l’app de connexion) :

| Nom                                               | Description                          |
| ------------------------------------------------- | ------------------------------------ |
| `CLOUD_IMPORT_GOOGLE_DRIVE_CLIENT_ID` / `_SECRET` | App d’import Google Drive Knowledge. |

Enregistre la même URI de callback cloud-import sur le client OAuth Google. Le consentement demande **drive.readonly** et **userinfo.email**.

## Drapeaux de fonctionnalité

Ces variables règlent l’authentification backend, les événements de fichiers et les droits opérateur. Recrée les rôles backend concernés après un changement d’environnement. Modifier seulement le conteneur web ne suffit pas.

| Nom                               | Défaut                   | Description                                                                                                                                                                                                                                                |
| --------------------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TRUSTED_SECRET_HEADER` | `Remote-Internal-Secret` | Nom de l'en-tête de requête qui porte la clé trusted headers de l'organisation sur la requête de passage. |
| `TRUSTED_EMAIL_HEADER`            | `Remote-Email`           | Nom de l'en-tête de requête qui porte l'e-mail de l'utilisateur — l'identité pour laquelle la session est émise.                                                                                                                                           |
| `TRUSTED_NAME_HEADER`             | `Remote-Name`            | Nom de l'en-tête de requête qui porte le nom affiché. S'il manque, Tale prend la partie locale de l'e-mail.                                                                                                                                                |
| `TRUSTED_ROLE_HEADER` | `Remote-Role` | Nom de l'en-tête de requête qui porte le rôle d'organisation avec lequel la session agit, plafonné au plafond de l'organisation (`member` si l'en-tête manque). |
| `TRUSTED_TEAMS_HEADER`            | `Remote-Teams`           | Nom de l'en-tête de requête qui porte les appartenances aux équipes, en noms d'équipe séparés par des virgules (les entrées `id:name` sont aussi acceptées). Absent, les équipes ne bougent pas ; présent, la liste du proxy fait foi pour les appartenances qu'il a accordées (vide les révoque). |
| `TALE_FILE_EVENTS`                | `false`                  | Diffuse les changements des fichiers de config sous `TALE_CONFIG_DIR` aux onglets ouverts (`/events/file`) : un fichier d’agent, de skill ou de branding modifié sur disque apparaît sans recharger. Actif dans le compose de dev, inactif en production.  |
| `TALE_DEPLOYMENT_CONFIG_ADMINS`   | non défini               | Allowlist de courriels (séparés par des virgules) des opérateurs autorisés à écrire le fichier de configuration du déploiement (`deployment.yml`, aujourd’hui la section du runtime de la sandbox) via l’API. Vide/non défini = lecture seule pour tous les admins. La résidence des données se configure par organisation et ne dépend pas de cette liste. |
| `TALE_ALLOW_PRIVATE_PROVIDER_HOSTS` | non défini | Avec `1` dans l’environnement du backend, autorise les destinations privées des fournisseurs de modèles, y compris leur configuration dans la passerelle sandbox. Les métadonnées cloud restent bloquées. Voir [Fournisseurs](https://docs.tale.dev/fr/self-hosted/configuration/providers). |
| `TALE_ALLOW_PRIVATE_CRAWL_HOSTS` | non défini | Avec `1`, autorise les cibles intranet et les hôtes privés dans l’`imageUrl` d’un produit. Les métadonnées cloud restent bloquées. |
| `TALE_ALLOW_OPEN_SIGN_UP` | non défini | La valeur exacte `true` laisse `POST /api/auth/sign-up/email` ouvert après le premier compte du déploiement. Réservé aux piles de test jetables — l’orchestrateur de développement local et la surcouche compose de développement le définissent eux-mêmes. Un déploiement réel le laisse non défini : chaque compte suivant est créé par une administratrice ou un administrateur. |
| `TALE_ORGANIZATION_CREATORS` | non défini | Liste d’adresses e-mail, séparées par des virgules, des comptes autorisés à créer une organisation, comparées sans tenir compte de la casse. Non définie, toute personne connectée peut en créer une. Définie, toute autre personne est refusée avec `403 ORGANIZATION_CREATION_FORBIDDEN` dès que le déploiement compte une organisation — la première est toujours autorisée — et l’application lui masque **Créer une organisation**. Une valeur définie mais vide ferme la création à tout le monde. Un déploiement géré l’écrit à partir de `organizations.creators` de sa spécification ; voir [Installer la CLI tale](https://docs.tale.dev/fr/self-hosted/install/cli-install#managed-organization-creators). |

L’autorisation des cibles privées concerne deux contrôles : l’enregistrement des sites et les requêtes du crawler, ainsi que la validation de l’`imageUrl` d’un produit. Sans elle, une cible de site privée renvoie `400 WEBSITE_DOMAIN_NOT_CRAWLABLE` ; une URL d’image privée renvoie `400 INVALID_BODY`. Pour un produit, seule la chaîne du nom d’hôte est contrôlée, sans télécharger l’image ni résoudre le DNS. L’enregistrement d’un site et le crawler vérifient aussi les adresses résolues. Active cette variable uniquement si le déploiement a besoin de ces destinations privées. Elle est distincte de l’autorisation des fournisseurs privés.

## Topologie du déploiement

Ces valeurs façonnent les rôles applicatifs d’un déploiement de workspace : le nombre de réplicas, que `tale deploy` lit dans l’environnement du projet et ramène dans la plage autorisée avec un avertissement, et la quantité de travail qu’un réplica de worker prend en charge à la fois.

| Nom                            | Défaut  | Description                                                                                              |
| ------------------------------ | ------- | ---------------------------------------------------------------------------------------------------------- |
| `TALE_PLATFORM_REPLICAS`       | `1`     | Replicas de l'étage web qui sert la coquille de l'app. Plage `1`–`16`.                                     |
| `TALE_BACKEND_API_REPLICAS`    | `1`     | Replicas de l'API — chaque porte applicative, l'auth et le flux de hints. Plage `1`–`16`.                  |
| `TALE_BACKEND_WORKER_REPLICAS` | `1`     | Replicas du runner de jobs : ingestion, crawls, automations, tours d'agent. Plage `1`–`16`.                |
| `WORKER_CONCURRENCY`           | `5`     | Jobs qu’un réplica `backend-worker` exécute en même temps dans chaque file de jobs — ingestion, crawls, automations et tours d’agent en reçoivent chacun autant. Les démarrages de tours d’agent en reçoivent au moins 8 et les fenêtres de traitement des tours d’agent en cours au moins 16 par file, car chacun attend surtout sa sandbox (`AGENT_START_SLOTS`, `AGENT_DRIVE_SLOTS`). Le processus worker le lit lui-même ; plage `1`–`64`. C’est le levier à actionner avant d’ajouter des réplicas de worker quand un retard s’accumule. Chaque job d’indexation en cours écrit via le pool du corpus, donc augmente `KNOWLEDGE_DB_POOL_MAX` en même temps. |
| `AGENT_START_SLOTS` | `WORKER_CONCURRENCY`, au moins `8` | Démarrages de tours d’agent qu’un réplica `backend-worker` exécute en même temps, pour les exécutions de tâches et pour les étapes d’automatisation chacun. Un démarrage occupe sa place pendant la création de la sandbox et la première fenêtre de 90 secondes du tour. Plage `1`–`256`. |
| `AGENT_DRIVE_SLOTS` | `WORKER_CONCURRENCY`, au moins `16` | Fenêtres de traitement des tours d’agent en cours qu’un réplica `backend-worker` exécute en même temps, par voie. Un réplica garde environ 2,5 fois ce nombre de tours en cours traités par voie ; au-delà, les fenêtres attendent assez longtemps pour que la reprise intervienne. Augmente-le (ou ajoute des réplicas) pour plus de tours à la fois. Plage `1`–`256`. |
| `TALE_BACKEND_URL` | `http://backend-api:3005` | Où l'étage web atteint le backend applicatif : la page publique `/status` le sonde et le serveur web lui demande les réponses que seule une base de données peut donner. Le Compose livré et l'entrypoint du conteneur prennent l'alias in-compose par défaut ; définis la variable seulement si ton service backend porte un autre nom. Lue uniquement par le service `platform`. |

Un déploiement de workspace fait temporairement tourner les deux couleurs. Prévois cette capacité supplémentaire. Augmente le rôle qui limite le débit selon tes mesures ; davantage de réplicas consomment aussi plus de connexions et de mémoire. Consulte [Mises à jour](https://docs.tale.dev/fr/self-hosted/operate/upgrades).

## Sessions

| Nom                            | Défaut     | Description                                                                                                                                                                                                           |
| ------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SESSION_IDLE_TIMEOUT_MINUTES` | non défini | **Optionnel.** Déconnecte une session après ce nombre de minutes d'inactivité (`1`–`1440`). La fenêtre glisse à chaque activité et est appliquée côté serveur — sessions e-mail/mot de passe, SSO et trusted headers. |

Laisse-le non défini pour conserver la durée de session par défaut. Si défini, une session inactive expire côté serveur une fois la fenêtre écoulée, tandis qu'une session active continue de glisser à chaque requête. Les Administrateurs d'organisation peuvent raccourcir la fenêtre effective par organisation — jamais l'allonger au-delà de ce plafond — via la [politique de gouvernance du délai d'inactivité de session](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits) ; les sessions inactives sous cette politique sont révoquées par une passe qui tourne environ toutes les cinq minutes.

## Lien vers le support

| Nom                        | Défaut                     | Description |
| -------------------------- | -------------------------- | ----------- |
| `TALE_CONTACT_SUPPORT_URL` | `https://tale.dev/contact` | **Optionnel, lu par le service `platform`.** Cible du lien **contacter le support** sur les écrans d’erreur de l’application. Une URL absolue `http://` ou `https://`. |

Indique ici ton propre service d’assistance pour que les personnes confrontées à une erreur joignent l’équipe qui exploite ton déploiement. Quand l’écran d’erreur connaît l’organisation, le lien ajoute `organizationId=<id>` à la chaîne de requête, après les paramètres que l’URL contient déjà, et remplace un paramètre `organizationId` qu’elle porte déjà. Toute autre valeur, par exemple `mailto:` ou une URL sans schéma, est ignorée avec un avertissement dans le journal du service `platform`, et le lien garde sa valeur par défaut.

## Infrastructure sandbox {#sandbox-infrastructure}

Le spawner sandbox lit les paramètres ci-dessous. Transmets-les dans son environnement et recrée ce service après une modification. `SANDBOX_MAX_SESSIONS` fixe la capacité partagée par toutes les organisations. Le total des trois limites de travail d’une organisation se recalcule automatiquement ; tu ne peux pas enregistrer ces limites s’il dépasse cette capacité. Gère les limites dans [Sandboxes](https://docs.tale.dev/fr/platform/admin/sandboxes), où les environnements réellement actifs et les mesures de l’hôte apparaissent séparément des allocations.

| Nom | Défaut | Description |
| --- | --- | --- |
| `SANDBOX_MAX_SESSIONS` | dimensionnée selon la mémoire de l’hôte sur un hôte Docker local (au moins `8`, au plus `256`) ; `8` ailleurs | Nombre maximal de sessions actives ou au démarrage de toutes les organisations sur l’hôte Docker ou dans le namespace Kubernetes, y compris les conteneurs inactifs conservés pour être réutilisés. Cette capacité ne réserve ni CPU ni mémoire. Sans valeur, sur un hôte Docker dont le spawner peut lire la mémoire, elle est dimensionnée selon cette mémoire : une session par tranche de 768 MiB restant après `SANDBOX_MIN_FREE_MEMORY`, ou de 1,5 GiB quand les sessions d’agent font tourner Docker dans la sandbox. Si la mémoire ne peut pas être lue au démarrage, la capacité reste à `8` jusqu’à ce qu’elle le soit. Une valeur explicite la fixe. Des réplicas Kubernetes concurrents l’appliquent au mieux ; utilise ResourceQuota pour imposer des limites strictes aux ressources du namespace. |
| `SANDBOX_MIN_FREE_MEMORY` | un dixième de la mémoire de l’hôte, au moins `1g` | Mémoire qu’une nouvelle session ou une session libérée qui reprend du travail doit laisser libre sur un hôte Docker local, en plus de ce que les sessions encore au démarrage ou tout juste démarrées vont bientôt occuper. Si un démarrage en laissait moins, le spawner arrête d’abord une session libérée inactive ; si la mémoire manque encore, il répond « occupé » et le travail attend que des sessions en cours en libèrent. Accepte des tailles comme `2g` ou `1536m`. Sans effet sous Kubernetes ou avec un daemon Docker distant. |
| `SANDBOX_MIN_FREE_DISK` | un vingtième de chaque disque, au moins `2g`, au plus `20g` | Espace libre requis pour les sessions nouvelles et réactivées sur le système de fichiers des espaces de travail et celui, vérifié, des données Docker. Sous ce seuil, le travail attend ; les caches de build arrêtés et inutilisés sont supprimés en premier. Accepte `10g` ou `4096m` ; `0` désactive le contrôle. Kubernetes dépend de sa classe de stockage et du provisionnement des volumes. |
| `SANDBOX_DOCKER_WORKLOADS` | `project,workflow` | Types de travail autorisés à utiliser Docker dans leur sandbox, lorsque le déploiement le permet. Avec `project`, les agents de workflow démarrent sans Docker ; avec `workflow`, ce sont les agents de projet ; avec `none`, les deux. Le réglage s’applique aux nouvelles sessions ; les sessions existantes conservent leurs capacités. Une demande de session peut renoncer à Docker avec `docker: false`, mais ne peut pas dépasser cette liste ni le réglage du déploiement. |
| `SANDBOX_AGENT_CPUS` | `2` | Limite de CPU par session d’agent. Tiens compte des builds simultanés et des autres tâches de l’hôte pour choisir le nombre de sessions. |
| `SANDBOX_AGENT_MEMORY` | `4g` ; `8g` avec Docker dans la sandbox | Limite de mémoire par session d’agent, partagée avec son daemon Docker interne et les conteneurs qu’il lance. Une valeur explicite remplace ces deux valeurs par défaut et s’applique aux nouvelles sessions. |
| `SANDBOX_AGENT_PROFILE` | `agent` | Lu par l’API backend et le worker. Profil des nouveaux espaces d’agents et de workflows : `agent` prend en charge Docker interne ; `agent-light` conserve les outils de développement et l’espace persistant sans démarrer Docker ni les services de cache de build. Les espaces existants conservent leur profil enregistré. |
| `TALE_SANDBOX_CLAUDE_EFFORT` | non défini (hérite de la valeur du harness) | Lu par l’API backend et le worker. Effort de raisonnement de Claude Code : `low`, `medium`, `high` ou `max`. Les valeurs inférieures retirent l’instruction Ultrathink automatique et définissent l’effort par exécution, tout en gardant la réflexion adaptative. Les autres harnesses et les modèles tiers restent inchangés. Compare des tâches représentatives avant de réduire l’effort ; des exécutions plus courtes ne sont pas garanties. |
| `SANDBOX_SESSION_CREATE_TIMEOUT_MS` | `180000` | Budget total de démarrage, dont le cache de build facultatif, le conteneur ou Pod, la disponibilité du daemon et l’envoi de l’environnement. L’annulation d’une requête interrompt le démarrage de sa session ; le nettoyage arrête le calcul en conservant l’espace de travail. La préparation du cache partagé a sa propre durée maximale. |
| `SANDBOX_DOCKER_DATA_ROOT` | non défini | Chemin hôte facultatif correspondant au `DockerRootDir` de Docker. La CLI ajoute un montage en lecture seule au service sandbox. Avec Compose directement, ajoute le montage ci-dessous. |
| `SANDBOX_DOCKER_DATA_PATH` | `/var/lib/tale-sandbox/docker-data` si la racine est définie | Emplacement de ce montage en lecture seule dans le spawner. L’admission vérifie ce système de fichiers ainsi que celui des espaces de travail. Un montage configuré impossible à vérifier ou à lire bloque l’admission. |
| `SANDBOX_BUILDKITD_CPUS` | `SANDBOX_AGENT_CPUS` | Limite de CPU du conteneur auxiliaire du cache de build d’une organisation, qui exécute les builds d’images de toutes ses sessions d’agent quand Docker tourne dans la sandbox. Les conteneurs auxiliaires en cours prennent une nouvelle valeur aussitôt. Le nombre d’étapes parallèles du solveur BuildKit correspond à cette limite CPU arrondie à l’entier inférieur, avec un minimum de un ; cette limite s’applique à la recréation d’un conteneur auxiliaire inactif. |
| `SANDBOX_BUILDKITD_MEMORY` | le double de `SANDBOX_AGENT_MEMORY` | Limite de mémoire du conteneur auxiliaire du cache de build d’une organisation, partagée par les builds que ses sessions d’agent lancent en même temps. Accepte des tailles comme `16g` ou `12288m`. Un conteneur auxiliaire en cours prend une nouvelle valeur quand il est recréé, dès qu’aucun build ne tourne. |
| `SANDBOX_BUILDKITD_IDLE_CACHE` | `5g` | Cache de build que garde le conteneur auxiliaire du cache de build d’une organisation quand il s’arrête faute de sessions d’agent. Juste avant cet arrêt, le spawner réduit le cache à cette taille, en commençant par les entrées inutilisées depuis le plus longtemps : le nettoyage propre au cache ne tourne que tant que le conteneur auxiliaire tourne. Accepte des tailles comme `5g` ou `2048m` ; `0` ne garde rien. |
| `SANDBOX_BUILDKITD_PROVISION_TIMEOUT_MS` | `5000` | Budget total en millisecondes pour préparer le cache de build partagé facultatif lors de la création d’une session, y compris les appels Docker en attente et les miroirs de registres. Plage `100`–`60000`. À expiration du budget de préparation partagé, les appels en attente sont annulés et ne peuvent plus lancer de conteneurs auxiliaires ; la session utilise son builder local. |
| `SANDBOX_BUILDKITD_CACHE_RETENTION` | `14d` | Durée pendant laquelle les conteneurs auxiliaires arrêtés du cache de build d’une organisation gardent leurs caches. Une fois le builder arrêté depuis plus longtemps, et si aucune session de l’organisation ne peut l’utiliser, le spawner supprime ses conteneurs auxiliaires, son réseau et ses volumes de cache, comme le fait la suppression d’une organisation ; son prochain build repart sans cache. Accepte des jours ou des heures entiers comme `14d` ou `336h` ; `off` (ou `0`) garde les caches jusqu’à la suppression de l’organisation. |
| `SANDBOX_SESSION_MAX_IDLE_MS` | `1800000` (30 min) | Délai d’inactivité avant l’arrêt des sessions non épinglées. Les conteneurs auxiliaires du cache de build d’une organisation s’arrêtent aussi après ce délai sans session potentiellement active ; leurs réseaux et volumes de cache sont conservés. |
| `SANDBOX_SESSION_RELEASED_IDLE_MS` | `300000` (5 min) | Délai d’inactivité d’une session libérée, c’est-à-dire dont la tâche ou l’exécution est terminée et qu’aucun autre travail n’occupe plus. Une session libérée et non épinglée, inactive pendant ce délai, est arrêtée sans attendre `SANDBOX_SESSION_MAX_IDLE_MS` ; le tour suivant la reprend sur son espace de travail conservé. Les sessions d’agent avec Docker dans la sandbox gardent le délai complet, car à chaque reprise leur daemon Docker interne repart d’un stockage d’images vide. |
| `SANDBOX_RUNTIME_IMAGE`          | `tale-sandbox-runtime:latest` | **Optionnel, lu par le spawner.** L'image dont sort chaque conteneur de session. Le défaut est le tag que la stack de développement construit localement ; un hôte qui tire ses images pose donc le nom de la registry : `ghcr.io/tale-project/tale/tale-sandbox-runtime:<version>`, aligné sur le reste de la stack. `tale deploy` le pose pour toi. |
| `SANDBOX_DIND_INNER_POOL` | non défini (automatique) | Pool d’adresses optionnel du daemon Docker interne des sessions d’agent, sur Docker ou Kubernetes. Choisis un `/16` IPv4 privé RFC1918 sous forme canonique, hors de tes réseaux de Pods, de Services et de VPC. Le runtime refuse tout chevauchement avec les réseaux et adresses qu’elle détecte. |
| `SANDBOX_EGRESS_MAX_CLIENTS` | `2000` | **Lu par le service `sandbox-egress`**, pas par le spawner : recrée ce service après un changement. Connexions que le proxy egress sert en même temps pour toutes les sessions réunies ; avec la sortie transparente, chaque connexion sortante d’une session, de ses builds et de ses installations de paquets passe par lui. Au-delà de la limite, le proxy refuse les nouvelles connexions, et les installations et chargements de pages échouent sur des connexions réinitialisées. Chaque connexion occupe un thread et deux fichiers ouverts, donc les fichiers Compose fournis dimensionnent les limites de processus et de fichiers ouverts du proxy pour la valeur par défaut ; une valeur plus haute demande aussi des limites plus hautes, et le proxy avertit au démarrage quand sa limite de fichiers ouverts est trop basse. Au démarrage, le proxy relève sa limite de fichiers ouverts à ce dont les connexions ont besoin, dans la mesure où la limite stricte du conteneur le permet. Sous Kubernetes, pose-la sur le Deployment egress ; une spécification de Pod ne fixe aucune limite de processus, donc le `podPidsLimit` du nœud doit laisser la place d’un thread par connexion. |

Les réglages backend ci-dessus doivent parvenir à l’API et au worker. Recrée ces services après une modification. Le spawner vérifie aussi la mémoire et le disque lors de la reprise d’une session libérée : un espace déjà démarré peut donc attendre de la capacité.

Les appareils connectés appliquent les mêmes contrôles de mémoire et d’espace disque qu’un hôte Docker local, tout en conservant leur plafond de sessions configuré.

Un daemon Docker arrêté volontairement reste prêt pour la prochaine commande ; les contrôles de santé ne le démarrent pas. Un contrôle qui échoue bloque immédiatement le nouveau travail, mais ne suffit pas à arrêter la session. La reprise après des contrôles défaillants exige au moins trois contrôles terminés en échec sur une période d’au moins cinq secondes. Un contrôle réussi ou un nouveau moteur efface cet historique. Un échec de démarrage confirmé ou un arrêt inattendu du moteur peut déclencher la reprise immédiatement. Après une vérification atomique de l’activité, le spawner peut alors arrêter une session inactive et non épinglée, en gardant son espace de travail pour le prochain démarrage. Sur Docker, l’arrêt de toute la session supprime son stockage Docker interne ; l’arrêt automatique du seul moteur interne inactif le conserve. Les sessions occupées ou épinglées restent en place et refusent de nouveaux démarrages jusqu’à ce que Docker réponde de nouveau ou qu’un opérateur résolve le problème.

Lors d’une mise à niveau progressive, garde chaque ancien spawner sur la référence fixe de son image runtime actuelle jusqu’à son remplacement. Ne déplace pas un tag runtime encore utilisé par un ancien spawner : il ne distingue pas les erreurs de contrôle passagères des pannes confirmées. Un nouveau spawner avec un ancien runtime refuse le nouveau travail quand Docker est indisponible et conserve les limites habituelles d’inactivité et de durée de vie.

Un spawner en conteneur contrôle automatiquement le système de fichiers des données Docker lorsqu’il peut vérifier son montage `/etc/hostname` existant auprès du daemon. Si cette détection est indisponible, le contrôle des espaces de travail reste actif et `/health` indique `unavailable` pour la surveillance du disque Docker. Un montage explicite en lecture seule du répertoire de données est prioritaire ; s’il ne peut être vérifié ou lu, l’admission attend qu’il soit disponible. Pour le configurer, consulte `docker info --format '{{.DockerRootDir}}'` et utilise ce chemin réel sur l’hôte. Docker Desktop et les daemons distants peuvent nécessiter une autre configuration. Avec Compose directement, ajoute la surcharge suivante et transmets les deux variables au service sandbox :

```yaml
services:
  sandbox:
    environment:
      SANDBOX_DOCKER_DATA_ROOT: ${SANDBOX_DOCKER_DATA_ROOT}
      SANDBOX_DOCKER_DATA_PATH: /var/lib/tale-sandbox/docker-data
    volumes:
      - ${SANDBOX_DOCKER_DATA_ROOT}:/var/lib/tale-sandbox/docker-data:ro
```

Un seuil d’admission n’est pas un quota de stockage par session. Les volumes nommés Docker n’ont pas de limite de taille portable, et le respect de la taille demandée par un PVC Kubernetes dépend du stockage utilisé. Pour des quotas stricts, choisis un système de fichiers ou une classe de stockage qui les applique. Surveille séparément les espaces de stockage de containerd et les répertoires de volumes montés à part, ainsi que les volumes gérés par un pilote externe, en plus des espaces de travail, des couches d’images et des caches de build.

Les sessions Kubernetes utilisent `/readyz` pour le démarrage et `/livez` pour la vivacité du daemon. Un daemon Docker interne arrêté volontairement est considéré comme prêt au démarrage ; un daemon Docker en cours d’exécution doit répondre à sa sonde de santé. La sonde de vivacité ne vérifie que le daemon de la sandbox, afin qu’une dépendance défaillante ne fasse pas redémarrer une session occupée. Un daemon bloqué peut redémarrer même si sa session est épinglée. Les diagnostics Docker et egress apparaissent dans `/healthz`.

Une génération déjà active n’est pas comptée une seconde fois. Un workflow sans Docker interne garde l’identité et les outils de son agent, mais ne démarre aucun daemon Docker et ne maintient pas les conteneurs auxiliaires du cache de build en activité. Sans valeur explicite pour `SANDBOX_AGENT_MEMORY`, chaque session a une limite par défaut de `4g` sans Docker interne ou de `8g` avec Docker, même si d’autres sessions du déploiement utilisent Docker. Une valeur explicite s’applique aux deux modes. Ces limites sont des plafonds, pas de la mémoire réservée.

À pleine capacité, le spawner peut arrêter une session inactive, libérée et non épinglée avant le délai d’inactivité pour accepter un nouveau travail, en commençant par celle qui est inactive depuis le plus longtemps. Le daemon doit confirmer qu’aucun travail n’est en cours ; les sessions occupées ou dont l’état est inconnu restent protégées. L’arrêt conserve le répertoire ou le volume persistant de l’espace de travail. Sans session à récupérer en toute sécurité, la capacité du déploiement continue de bloquer les nouveaux démarrages. Il en va de même lorsque la mémoire libre de l’hôte passerait sous `SANDBOX_MIN_FREE_MEMORY`. Tant que le disque qui contient les espaces de travail des sessions reste sous `SANDBOX_MIN_FREE_DISK`, le nouveau travail attend sans que des sessions inactives soient arrêtées : une session arrêtée garde son espace de travail.

Les enregistrements du protocole des harnesses, y compris les lignes inachevées, sont limités à 8 Mio. Une sortie trop volumineuse ou incomplète provoque un échec explicite ; l’aperçu de progression borné n’est jamais considéré comme un résultat structuré complet. Les réponses finales complètes sont conservées séparément de cet aperçu.

La reprise d’une session libérée encore en mémoire vérifie la même réserve et comptabilise son besoin mémoire prévu avant de reprendre le travail. Les reprises simultanées partagent ce calcul. Une réponse « occupé » permet une nouvelle tentative : elle ne supprime pas l’espace de travail et n’interrompt pas une session déjà occupée. Ces réservations ne limitent pas la croissance ultérieure des outils actifs ou des builders de l’organisation.

Lorsque Docker est activé dans les sandboxes d’agent, le daemon démarre automatiquement à la première commande Docker. Les agents n’ont aucun mode à choisir. Après cinq minutes sans client connecté, il s’arrête uniquement si aucun conteneur n’est en cours d’exécution, de redémarrage ou en pause et si toutes les règles de redémarrage automatique sont désactivées ; un état inconnu le maintient actif. La commande suivante le relance avec les mêmes images, volumes et espace de travail. Si des métadonnées de conteneurs existent déjà au démarrage du conteneur de session, le daemon démarre immédiatement pour respecter leurs règles de redémarrage. L’isolation, les privilèges et les limites mémoire du déploiement restent inchangés.

### Dimensionner la capacité des sessions

Sans `SANDBOX_MAX_SESSIONS` sur un hôte Docker, le spawner dimensionne la capacité selon la mémoire de l’hôte (un hôte de 16 GiB obtient 19 sessions, un hôte de 64 GiB en obtient 76 ; 9 et 38 quand les sessions d’agent font tourner leur propre daemon Docker) et n’admet une nouvelle session que si l’hôte garde `SANDBOX_MIN_FREE_MEMORY` de libre, en comptant ce que les sessions encore au démarrage ou tout juste démarrées vont bientôt occuper. Un pic de nouvelles sessions qui surchargerait l’hôte attend donc au lieu de démarrer ; ce contrôle n’empêche pas les sessions déjà lancées de continuer à grandir. Fixe toi-même la capacité sous Kubernetes, avec un daemon Docker distant ou si l’hôte fait aussi tourner d’autres charges gourmandes : teste alors les tâches que ton déploiement exécutera en même temps. Le rendu dans le navigateur et les builds Docker n’ont pas les mêmes pics de charge ; inclus les agents, les workflows et l’exploration de toutes les organisations. Une place libre ne garantit pas des ressources suffisantes.

Sous Docker, relève la consommation pendant que des tâches représentatives s’exécutent en parallèle. Répète cette commande pendant l’exécution ; une mesure au repos ne montre pas les pics des tâches :

```bash
docker stats --no-stream --format 'table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}'
```

Retire de la mémoire de l’hôte la part nécessaire au système, aux services de la plateforme, aux bases de données, aux conteneurs auxiliaires de build et à une marge de sécurité. Divise le reste par le pic mesuré par session active, puis arrondis à l’entier inférieur. Par exemple, un hôte de 32 GiB avec 8 GiB mis de côté et un pic mesuré de 3 GiB par session donne `(32 - 8) / 3 = 8` sessions. C’est un exemple de calcul, pas un benchmark. Pour des tâches différentes, additionne leurs pics simultanés et vérifie la saturation du CPU ainsi que la durée des tâches avant d’augmenter la limite.

Les 4 GiB ou 8 GiB d’un agent sont un plafond de mémoire ; cette mémoire n’est pas réservée au démarrage. Huit agents qui exécutent des builds Docker peuvent donc consommer bien plus que huit sessions surtout inactives. Mesure avec une charge représentative et garde une marge. Passe à 16 ou plus seulement si l’hôte tient cette charge dans la durée. Avant de réduire la capacité, abaisse les totaux d’organisation qui dépassent la nouvelle valeur. Les limites par défaut d’une organisation totalisent 6 ; une capacité inférieure demande aussi des limites d’organisation plus basses.

### Appliquer un changement de capacité

Ajoute ou modifie cette ligne dans le `.env` du déploiement, en conservant les autres entrées. Les valeurs explicites restent en vigueur après une mise à niveau ; sans valeur, un hôte Docker dimensionne la capacité selon sa mémoire comme décrit plus haut, et Kubernetes utilise 8.

```dotenv .env
SANDBOX_MAX_SESSIONS=8
```

Pour une stack Compose que tu gères toi-même, recrée uniquement le service sandbox avec son image locale existante :

```bash
docker compose up -d --no-deps --no-build --pull never sandbox
```

Utilise le même projet, les mêmes fichiers `-f` et les mêmes options de fichiers d’environnement que la stack active. Un redémarrage seul ne charge pas un `.env` modifié. Pour une installation gérée par la CLI, suis la procédure de déploiement dans [Mises à niveau](https://docs.tale.dev/fr/self-hosted/operate/upgrades). Sous Kubernetes, définis la variable dans le Deployment du spawner sandbox, puis déploie cette nouvelle configuration.

Vérifie la nouvelle capacité du déploiement dans [Sandboxes](https://docs.tale.dev/fr/platform/admin/sandboxes). Avec des limites d’organisation de 2/2/2 et une capacité de 8, le total affiche **6 / 8**. Les réglages existants des organisations sont conservés ; leur total doit toujours respecter la capacité actuelle pour être enregistré. Ce changement n’augmente pas les limites de CPU ou de mémoire des conteneurs.

### Après une mise à niveau

La capacité par défaut était de 16, et les organisations créées avant cette version ont reçu les limites 2/4/4, soit un total de 10. Un déploiement qui n’a jamais défini `SANDBOX_MAX_SESSIONS` démarre donc la nouvelle version avec une capacité de 8 et des organisations dont le total enregistré la dépasse. Le travail en cours n’est pas touché, et chaque organisation continue d’admettre du travail selon ses limites enregistrées ; seul l’enregistrement de la page Sandboxes reste bloqué tant que le total ne rentre pas, et abaisser une limite s’enregistre toujours. Définis `SANDBOX_MAX_SESSIONS=16` explicitement pour conserver la capacité précédente, ou demande à chaque organisation concernée d’abaisser une limite.

À partir de cette version, un déploiement Docker qui n’a jamais défini `SANDBOX_MAX_SESSIONS` obtient une capacité dimensionnée selon la mémoire de son hôte au lieu de 8, jamais moins de 8. Il peut admettre plus de sessions à la fois qu’avant, et seulement tant que l’hôte a de la mémoire disponible. Définis une valeur explicite pour garder une capacité fixe.

### Caches de build Docker

La préparation du cache de build partagé utilise `SANDBOX_BUILDKITD_PROVISION_TIMEOUT_MS` (5 secondes par défaut). Chaque session attend au plus cette durée ou un quart de son budget total de démarrage si ce délai est plus court, puis utilise son builder local. La préparation partagée a son propre budget borné : annuler l’attente d’une session n’annule pas la préparation destinée aux autres sessions, et un résultat tardif ne se rattache pas à une session déjà passée au builder local. Les miroirs de registry sont préparés en parallèle. Le nombre d’étapes simultanées du builder partagé correspond à sa limite CPU arrondie à l’entier inférieur, avec un minimum de un ; sa limite de mémoire reste applicable. Le temps de préparation est déduit du budget de démarrage restant de la session.

Les caches de build Docker sont isolés par organisation. Chaque organisation utilise un builder privilégié et trois miroirs de registre sans privilèges élevés. Dès qu’aucune session ne peut encore les utiliser, le délai d’inactivité commence ; les conteneurs auxiliaires s’arrêtent ensuite. Le prochain build les redémarre avec leurs volumes de cache conservés. Juste avant l’arrêt du builder, le spawner réduit son cache à `SANDBOX_BUILDKITD_IDLE_CACHE`, car son nettoyage ne tourne que tant qu’il tourne. Le cache d’une organisation arrêtée n’est plus réduit ensuite ; après `SANDBOX_BUILDKITD_CACHE_RETENTION` (14 jours) sans build, ses conteneurs auxiliaires et ses caches sont supprimés, et sinon ils partent avec l’organisation. Tant que le disque des sessions reste sous `SANDBOX_MIN_FREE_DISK`, les caches des organisations arrêtées partent plus tôt, en commençant par celles arrêtées depuis le plus longtemps. Les réseaux et les volumes restent disponibles pour être réutilisés. Les sessions Kubernetes utilisent leur propre builder Docker interne ; la réconciliation Kubernetes n’appelle pas la CLI Docker pour ces conteneurs auxiliaires.

Le spawner remplit le premier pool d’adresses Docker disponible avec les réseaux d’organisation avant de passer au suivant. Par défaut, chaque réseau reçoit un `/23` de 512 adresses ; un `/16` entièrement libre peut donc accueillir 128 réseaux d’organisation. Les sous-réseaux plus petits configurés dans Docker gardent leur taille. Le spawner exclut les réseaux Docker existants, les routes et les adresses des serveurs DNS de l’hôte du daemon Docker, ainsi que `172.31.0.0/16` pour les anciennes images de runtime, puis vérifie le réseau créé.

Pour observer l’hôte du daemon même avec Docker à distance, le spawner lance brièvement l’image BuildKit configurée dans le namespace réseau de l’hôte. Ce conteneur utilise un système de fichiers en lecture seule, sans capacités Linux ni montages. Si cette observation échoue ou qu’aucun sous-réseau sûr ne reste disponible, les sessions construisent localement sans cache partagé. Le spawner recrée un réseau inutilisé qui lui appartient si son sous-réseau est invalide ; il conserve les réseaux utilisés ou appartenant à un autre propriétaire.

Une mise à niveau crée des caches d’organisation vides et conserve les anciennes données globales. Les anciens conteneurs auxiliaires s’arrêtent automatiquement dès qu’aucune session active n’en dépend. Laisse se terminer les anciennes sessions épinglées ou arrête-les pour achever la transition ; jusque-là, l’ancien service de cache partagé reste accessible. L’automatisation du navigateur utilise Chromium sans interface graphique. La vue en direct et la prise de contrôle manuelle ont été retirées.

### Réseaux Docker internes

Sur Docker et Kubernetes, le choix automatique vérifie les routes IPv4 et leurs passerelles dans toutes les tables de routage, les adresses et préfixes des interfaces, les serveurs DNS et les adresses résolues des hôtes de proxy et de passerelle configurés dans l’environnement au démarrage du conteneur. Les hôtes transmis plus tard pendant un tour d’agent échappent à cette observation initiale. Il tient aussi compte du réseau d’organisation Docker raccordé ensuite. Le runtime privilégie `172.31.0.0/16` s’il est libre, puis essaie d’autres plages privées `/16`. Le premier `/24` sert à `docker0` ; les réseaux Compose internes utilisent des blocs `/24` du même pool. En mode automatique, une observation indisponible ou l’absence de plage libre empêche le démarrage de la session.

Un Pod ne peut pas déduire tous les CIDR des Pods, des Services et du VPC du cluster depuis son propre namespace réseau. Pour DinD sur Kubernetes, définis `SANDBOX_DIND_INNER_POOL` avec un `/16` privé que tu as vérifié contre l’ensemble de ces réseaux. Un pool explicite reste refusé si le runtime détecte un chevauchement ou une valeur invalide. Si certaines observations manquent, il les indique dans un avertissement et peut continuer avec ce pool ; c’est à toi de tenir compte des plages invisibles depuis le Pod.

Après avoir modifié ce pool, redémarre le spawner et recrée les sessions existantes pour leur appliquer la valeur. Redémarrer le conteneur runner dans le même Pod Kubernetes conserve l’environnement du Pod et le stockage Docker interne.

Le proxy egress autorise les requêtes DNS vers les adresses IP de serveurs de noms validées dans son `/etc/resolv.conf`, y compris le DNS privé du cluster. Chaque exception se limite à cette IP exacte et au port de destination 53 en UDP/TCP. Les autres destinations privées et le transfert entre réseaux raccordés restent bloqués.

### Protection du transfert IPv6

Garde `sandbox`, `sandbox-egress` et `SANDBOX_RUNTIME_IMAGE` sur la même version lors d’une mise à niveau. Avant de raccorder le réseau de build Docker d’une organisation, le spawner vérifie la protection de la session contre le transfert de paquets. Compose et les conteneurs de session Docker générés désactivent IPv6 avec `net.ipv6.conf.all.disable_ipv6=1` et `net.ipv6.conf.default.disable_ipv6=1`. Conserve les deux valeurs dans tes propres définitions Docker.

Les Pods Kubernetes ne reçoivent pas automatiquement de sysctls non sûrs. Le proxy egress a besoin d’un pare-feu IPv6 fonctionnel ou d’IPv6 désactivé dans son namespace réseau. Si le pare-feu IPv6 est indisponible, l’entrypoint tente cette désactivation locale, puis vérifie la valeur par défaut et chaque interface. Un `/proc/sys` en lecture seule ou des droits insuffisants peuvent l’en empêcher ; IPv6 encore actif sans protection bloque le démarrage. Configure le Pod egress avant le déploiement avec les paramètres réseau autorisés par ton cluster.

## Appareils de sandbox {#sandbox-devices}

Les organisations peuvent exécuter leurs sandboxes sur leurs propres machines, qu’elles connectent dans [Paramètres > Sandboxes](https://docs.tale.dev/fr/platform/admin/sandbox-devices). Un appareil se connecte en HTTPS à `<SITE_URL><BASE_PATH>/sandbox/tunnel` et garde un WebSocket ouvert. Le proxy fourni transmet ce chemin, et uniquement celui-ci, au hub d’appareils du spawner ; l’API signée du spawner reste sur le réseau interne. Les appareils ont besoin du backend Docker : avec Kubernetes, le hub reste désactivé.

| Nom | Défaut | Description |
| --- | --- | --- |
| `SANDBOX_HUB_PORT` | `8004` | **Lu par le spawner.** Port du hub d’appareils, qui ne répond qu’à une mise à niveau WebSocket authentifiée par ticket et à une vérification d’état. `0` désactive les appareils : **Ajouter un appareil** est alors indisponible. Si tu changes le port, fais aussi pointer `SANDBOX_HUB_UPSTREAM` dessus. |
| `SANDBOX_DEVICE_TUNNEL_URL` | `<SITE_URL><BASE_PATH>/sandbox/tunnel` en `wss://` | **Facultatif, lu par le backend.** Où les appareils se connectent, lorsqu’un proxy placé devant Tale publie le hub sous un autre hôte ou chemin. Une adresse `https://` est utilisée comme `wss://`. |
| `SANDBOX_DEVICE_IMAGE_REGISTRY` | `GHCR_REGISTRY`, sinon `ghcr.io/tale-project/tale` | **Facultatif, lu par le backend.** D’où les appareils téléchargent les images de sandbox de la version du serveur. |
| `SANDBOX_HUB_UPSTREAM` | `sandbox:8004` | **Facultatif, lu par le proxy.** Où le proxy transmet `/sandbox/tunnel`, lorsque le spawner n’est pas le service `sandbox`. |

Un appareil exécute toujours la version du serveur. Il apprend la version à chaque renouvellement de sa connexion et remplace ses propres conteneurs dès que le serveur change de version, sauf s’il a été connecté avec `--no-auto-update`. Il ne conserve aucune donnée sur le serveur : ses espaces de travail restent sur la machine. Les sandboxes d’un appareil joignent les points d’accès sandbox du backend et la passerelle de modèles par la connexion de l’appareil, sur les mêmes chemins que les sessions sur le serveur ; l’API d’administration de la passerelle n’est jamais accessible par cette voie. Un appareil conserve les adresses du backend et de la passerelle reçues lors de sa connexion : après avoir modifié `SANDBOX_HTTP_API_BASE_URL` ou `EXTERNAL_AGENT_GATEWAY_URL`, lance `tale sandbox update` sur chaque appareil.

Un appareil doit faire confiance au certificat TLS du site. Un déploiement avec `TLS_MODE=selfsigned` ne peut pas accueillir d’appareils.

Si tu utilises ton propre proxy au lieu du proxy fourni, transmets `/sandbox/tunnel` au port `SANDBOX_HUB_PORT` du spawner, conserve les mises à niveau WebSocket et l’en-tête `Authorization`, et autorise des connexions qui restent ouvertes pendant des heures.

## Tours d'agent en sandbox

| Nom                              | Défaut               | Description                                                                                                                                                                                                                                                                                                                              |
| -------------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `TALE_EXTERNAL_TURN_DEADLINE_MS` | `1800000` (30 min)   | **Optionnel.** Combien de temps un tour d’agent de code en sandbox (Claude Code, OpenCode, Codex) peut rester sans que personne ne lise sa sortie avant que le daemon de la sandbox ne le récupère. Une fenêtre glissante, relancée chaque fois que la plateforme se rattache à la sortie — pas un plafond absolu sur le tour. En millisecondes. |
| `SANDBOX_LLM_GATEWAY_STREAM_IDLE_TIMEOUT_SECONDS` | `600` (10 min) | **Optionnel.** Combien de temps la passerelle de modèles de la sandbox attend l’octet suivant d’un modèle en amont resté silencieux avant d’interrompre le flux, y compris pendant qu’un modèle local lent traite encore un long prompt. Le backend lit cette valeur et s’en sert pour configurer la passerelle. Les tours Claude Code et Codex attendent au moins aussi longtemps avant d’abandonner un flux silencieux et de renvoyer la requête. Tu peux donc l’augmenter pour un modèle local lent sans que l’un d’eux envoie un tour en double. En contrepartie, un modèle en amont bloqué retient aussi un tour plus longtemps avant que la passerelle n’interrompe le flux. Une valeur supérieure à 600 relève aussi d’autant le délai de requête de la passerelle : il borne une réponse entière non diffusée en flux, sur laquelle un agent se replie quand un flux s’interrompt, ainsi que le temps qu’un modèle en amont peut mettre à commencer une réponse en flux. En secondes. |

Cherche pourquoi la sortie n’est plus lue avant d’augmenter ce délai. Il limite les flux de sortie abandonnés, pas la durée totale d’une tâche. Recrée les rôles backend concernés après avoir changé l’environnement.

## Ingestion de liens vidéo (yt-dlp)

Le worker utilise ces valeurs pour récupérer les transcriptions vidéo. Son image comprend yt-dlp et un plugin de jetons PO. [Importation vidéo](https://docs.tale.dev/fr/self-hosted/configuration/video-ingestion) distingue les restrictions de source, les problèmes de sortie réseau et les sessions autorisées. Recrée le worker après une modification de son environnement ; relire une variable dans un processus ne recharge pas `.env`.

| Nom                              | Défaut                                     | Description                                                                                                                                                                                                                                                                                                                                                  |
| -------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `VIDEO_INGEST_PROXY_URL` | non défini | Proxy des requêtes yt-dlp. Protocoles admis : `http`, `https`, `socks4`, `socks4a`, `socks5`, `socks5h` ; le dernier résout le DNS de destination au proxy. Utilise un service de sortie approuvé. |
| `VIDEO_INGEST_POT_PROVIDER_URL` | `http://bgutil-provider:4416` (intégré) | URL du fournisseur de jetons PO. Le sidecar fourni est utilisé par défaut lorsque le plugin est présent dans l’image. Les jetons peuvent aider la récupération, sans autoriser du contenu privé ni garantir le succès. |
| `VIDEO_INGEST_FETCH_POT` | `always` dès qu'un fournisseur est branché | Quand demander des jetons : `never`, `auto` ou `always`. Le parcours fourni utilise `always`. Choisis `never` pour désactiver délibérément cette source de jetons. |
| `VIDEO_INGEST_YTDLP_PLUGIN_DIRS` | `/opt/yt-dlp/plugins` (intégré)            | Répertoire depuis lequel yt-dlp charge les plugins — chaque plugin imbriqué un niveau plus bas (`<dir>/<nom>/yt_dlp_plugins/…`). Par défaut, le répertoire de plugins bgutil intégré quand il est présent ; ne le remplace que pour ajouter tes propres plugins.                                                                                             |
| `VIDEO_INGEST_COOKIES_FILE` | non défini | Chemin dans le worker vers un fichier de cookies Netscape. Protège-le comme des identifiants de compte et utilise une session autorisée. Le pool de sessions par organisation décrit dans le guide vidéo permet un import et une révocation gérés. |
| `VIDEO_INGEST_PLAYER_CLIENT`     | `default,tv_simply`                        | Liste de repli des clients de lecture YouTube, séparés par des virgules. Quand un fournisseur de PO tokens est branché, la valeur par défaut s'élargit à `default,mweb,tv_simply` (mweb exige un token GVS) ; définis-la explicitement pour forcer une liste.                                                                                                |
| `VIDEO_INGEST_PO_TOKEN`          | non défini                                 | PO token défini manuellement (`CLIENT.CONTEXT+TOKEN`). Surtout pour les tests — les tokens sont liés à l'ID de la vidéo et éphémères ; privilégie le fournisseur.                                                                                                                                                                                            |
| `VIDEO_INGEST_IMPERSONATE`       | non défini                                 | Cible d'imitation TLS/JA3 du navigateur (p. ex. `safari`). Nécessite `curl_cffi` dans l'image ; à laisser non défini sauf disponibilité connue.                                                                                                                                                                                                              |
| `VIDEO_INGEST_BIN_DIR`           | non défini                                 | Répertoire ajouté en tête du `PATH` du processus enfant yt-dlp/ffmpeg, pour qu'un `yt-dlp` auto-provisionné (et son runtime Deno) installé hors des répertoires bin intégrés soit trouvé en premier. L'image du backend intègre yt-dlp dans le `PATH`, donc laisse-le non défini là ; définis-le sur un hôte ou une machine de dev avec sa propre toolchain. |
| `VIDEO_INGEST_FFMPEG_LOCATION`   | `/usr/bin/ffmpeg`                          | Chemin absolu vers le ffmpeg que yt-dlp utilise pour la post-production (conversion des sous-titres, extraction audio). À surcharger quand ffmpeg vit ailleurs — p. ex. le `/opt/homebrew/bin/ffmpeg` de Homebrew sur une machine de dev macOS.                                                                                                              |

# Configurer la supervision
Source: https://docs.tale.dev/fr/self-hosted/configuration/observability-config

Commence par les journaux des conteneurs et l’état des services. Ajoute les métriques Prometheus pour suivre les tendances et déclencher des alertes, puis un service de suivi des erreurs si tu veux consulter leur historique. Tale n’envoie ces données à un service de supervision externe que si tu en configures un.

## Consulter les journaux de l’application

Les conteneurs écrivent sur stdout et stderr. La configuration Compose fournie utilise le pilote Docker `json-file`, avec une rotation à 10 Mo par fichier et trois fichiers par conteneur. Utilise les noms de services de ton fichier Compose :

```bash
docker compose logs --tail=100 backend-api backend-worker
docker compose logs -f backend-api
```

Appuie sur `Ctrl-C` pour arrêter le suivi ; les conteneurs continuent de fonctionner. Consulte `backend-api` pour les requêtes, la connexion et les réponses du chat interactif ; utilise `backend-worker` pour les tâches de fond, les appels d’agent mis en file et l’importation des documents. `docker compose ps` permet de repérer un conteneur qui redémarre en boucle.

`journalctl -u docker` affiche le journal du démon Docker. Avec le pilote par défaut `json-file`, il ne remplace pas les journaux des conteneurs. Pour utiliser journald ou centraliser les journaux, configure séparément le pilote Docker et leur collecte. Tale ne fournit pas d’agent de collecte. Un changement de pilote exige de recréer les conteneurs concernés.

## Activer les métriques protégées {#metriques}

Définis un `METRICS_BEARER_TOKEN` robuste dans l’environnement du déploiement. Applique la modification avec ta procédure habituelle afin de recréer les services concernés. Un simple redémarrage de conteneur ne recharge pas les variables d’environnement de Compose. Enregistre le même jeton dans le gestionnaire de secrets de ton système de supervision.

Le proxy exige `Authorization: Bearer <token>` pour ces routes. Sans jeton configuré, elles renvoient **401**.

| Route | Contenu | Utilisation |
| --- | --- | --- |
| `/metrics/platform` | Métriques du processus web et objectifs de temps de réponse | Cible de collecte Prometheus |
| `/metrics/backend` | Métriques HTTP et système du backend, files d’attente, générations actives et état d’arrêt progressif | Cible de collecte Prometheus |
| `/metrics/sla-rules` | Règles d’enregistrement et d’alerte générées en YAML | Fichier de règles Prometheus |

Le backend traite les recherches de connaissances et les tâches d’importation. Ses métriques HTTP et de file d’attente aident à repérer les erreurs et les retards ; elles ne mesurent pas séparément la durée de la recherche ou de la génération. `BACKEND_UPSTREAM` désigne la cible backend d’un déploiement séparé. Cette variable ne crée pas de service de métriques propre aux connaissances.

Crée une tâche de collecte par route. Dans cet exemple, `/run/secrets/tale_metrics_token` est un fichier du conteneur Prometheus qui contient uniquement le jeton. Crée-le avec ton gestionnaire de secrets et autorise Prometheus à le lire.

```yaml
scrape_configs:
  - job_name: tale-platform
    scheme: https
    metrics_path: /metrics/platform
    authorization:
      credentials_file: /run/secrets/tale_metrics_token
    static_configs:
      - targets: ['tale.example.com']
  - job_name: tale-backend
    scheme: https
    metrics_path: /metrics/backend
    authorization:
      credentials_file: /run/secrets/tale_metrics_token
    static_configs:
      - targets: ['tale.example.com']
```

Ne collecte pas `/metrics/sla-rules` comme des métriques. Les règles générées utilisent des séries de latence qui nécessitent une instrumentation supplémentaire. Charger le fichier ne suffit pas à mesurer le respect des objectifs de réponse. Examine les règles avant de les charger dans Prometheus. La page [Prometheus et Grafana](https://docs.tale.dev/fr/self-hosted/operate/observability/prometheus-grafana) détaille l’installation complète.

## Choisir la destination des erreurs

`SENTRY_DSN` active le suivi facultatif des erreurs. Il peut désigner Sentry ou un service compatible comme GlitchTip ou Bugsink. Le navigateur, le backend et la sandbox utilisent ce DSN et le libellé `SENTRY_ENVIRONMENT` ; les événements serveur indiquent le rôle du processus et la version déployée.

```bash
SENTRY_DSN=https://your-key@your-sentry-host/project-id
SENTRY_ENVIRONMENT=example-pr
SENTRY_TRACES_SAMPLE_RATE=0.1
```

Les déploiements gérés utilisent leur `name` existant comme libellé par défaut. Pour choisir un autre libellé, déclare `"environment": { "SENTRY_ENVIRONMENT": { "env": "TALE_REPORTING_ENVIRONMENT" } }` dans la spécification du déploiement et définis cette variable à destination. La valeur commence par une lettre minuscule ou un chiffre et contient de 1 à 64 lettres minuscules, chiffres ou traits d’union. L’identité du déploiement, son état et ses identifiants enregistrés conservent leurs chemins existants.

Les erreurs de sandbox comprennent les échecs HTTP et des tâches de fond. Les annulations attendues du client et les flux SSE fermés après annulation sont exclus. La sandbox envoie uniquement des erreurs ; les paramètres de traces du navigateur et du backend n’activent pas de traces dans la sandbox. Elle utilise le filtre de confidentialité du backend décrit ci-dessous.

`SENTRY_TRACES_SAMPLE_RATE` concerne les traces de performance du navigateur ; leur taux par défaut est de 1.0 en développement. Les traces du backend sont désactivées par défaut. Pour les activer, règle `BACKEND_SENTRY_TRACES_SAMPLE_RATE` entre `0` et `1` (par exemple, `0.05` échantillonne 5 % des opérations) et utilise une destination qui accepte les transactions Sentry. Recrée les services API et worker du backend après la modification. Choisis des taux adaptés à ton budget de supervision ; le taux backend `0` désactive les spans tout en conservant le suivi des erreurs.

Les spans du backend mesurent le traitement des requêtes HTTP et l’exécution des tâches d’arrière-plan. Une tâche comprend des spans enfants pour le contrôle du drainage, son traitement ou son transfert. Les contrôles d’état et les collectes de métriques sont exclus ; les spans HTTP ne mesurent pas la durée de transmission du corps d’une réponse en continu. Leurs noms utilisent des classes de routes et les noms de files enregistrées. Les spans excluent le contenu des requêtes et des tâches, le texte SQL, les identifiants, les URL, le contexte utilisateur et les fils d’activité. Les requêtes sortantes ne portent aucun en-tête de trace. Le travail des agents ajoute des spans enfants pour l’acquisition, la préparation du gateway, le staging, l’exécution, la persistance et la récupération des fichiers. Leurs noms sont fixes et ils ne contiennent ni prompts, ni chemins de fichiers, ni identifiants secrets.

Les événements du backend n’incluent jamais les cookies ni le corps des requêtes. Les en-têtes d’autorisation, de cookie, de clé d’API, de jeton, de secret et de session, les jetons de webhook et de partage dans les URL ainsi que les valeurs d’identification des paramètres de requête, comme les codes OAuth, sont remplacés par `[Filtered]` avant l’envoi. Les cadres de pile et les messages d’erreur sont envoyés tels quels ; choisis la destination selon tes exigences de traitement des données.

Un redémarrage de la base de données n’est pas signalé comme une erreur : une mise à niveau gérée recrée la base à chaque version. Tant qu’elle est injoignable, les requêtes répondent `503 DATABASE_UNAVAILABLE` avec `Retry-After`, les tâches d’arrière-plan échouent puis sont relancées selon la politique de leur file, et les flux de mise à jour en direct ouverts patientent puis reprennent. Chacun écrit un avertissement dans le journal à la place. La file des tâches n’en écrit qu’un pour toute la panne, et non un à chaque interrogation échouée. Si la base reste injoignable plus d’une minute environ, un processus API ayant des flux ouverts envoie un seul événement de niveau « warning » pour cette panne. Un processus backend qui démarre pendant que la base est injoignable l’attend jusqu’à une minute environ au lieu de s’arrêter, et écrit un avertissement dans le journal à chaque nouvelle tentative. Si la base reste injoignable au-delà, le démarrage échoue et est signalé comme une erreur. Un hôte ou un port erroné dans `DATABASE_URL` ne fait donc échouer le démarrage qu’au bout d’une minute environ.

Le backend ne signale pas non plus une requête abandonnée par son client, par exemple quand tu fermes un onglet ou annules un téléversement pendant que son corps arrive encore. La requête reçoit le statut `499`, compte parmi les erreurs client dans les métriques de requêtes et laisse une seule ligne de débogage dans le journal. Toute autre erreur survenue dans une requête dont le client s’est déconnecté reste signalée. Une requête de l’application dont le corps JSON est vide ou tronqué reçoit `400 INVALID_JSON` et n’est pas signalée.

Le navigateur ne signale pas les erreurs qui ne révèlent aucun défaut de Tale :

- les erreurs provenant d’une extension du navigateur
- les requêtes que la page annule elle-même, par exemple quand tu la quittes avant la fin de son chargement
- les requêtes que le backend refuse avec un statut inférieur à 500, par exemple faute d’autorisation ou parce qu’un nom est déjà pris
- les requêtes restées sans aucune réponse, par exemple quand l’appareil est hors ligne
- les requêtes qui échouent pendant que la plateforme ou sa base de données redémarre : `UPSTREAM_UNAVAILABLE` du proxy pendant un déploiement ou un redémarrage, et `503 DATABASE_UNAVAILABLE` de la plateforme

Les autres erreurs serveur, de statut 500 ou plus, restent signalées.

## Statistiques agrégées avec Umami

La collecte est désactivée par défaut. Tu l’actives séparément pour chaque déploiement avec `UMAMI_URL`, `UMAMI_WEBSITE_ID` et `UMAMI_PROXY_TOKEN`, décrits dans la [référence des variables d’environnement](https://docs.tale.dev/fr/self-hosted/configuration/environment-reference). Utilise un identifiant de site distinct par déploiement. Recrée le service de production concerné avec les nouvelles variables ; il n’est pas nécessaire de reconstruire l’image. Pour arrêter la collecte, vide l’identifiant de site et applique la modification de la même façon. Le serveur de développement Vite n’injecte pas cette configuration.

Le navigateur charge le script Umami depuis sa propre origine, sous `/_a/script.js`, et envoie les événements sélectionnés à `/_a/api/send`. Si un chemin de base est configuré, il précède ces URL. Seuls l’identifiant de site et le chemin du proxy figurent dans la configuration du navigateur ; l’origine de collecte et le jeton Bearer restent sur le serveur.

`UMAMI_URL` doit désigner une passerelle qui authentifie `GET /_collect/script.js` et `POST /_collect/api/send` avec ce jeton Bearer. L’URL d’un tableau de bord Umami standard ne suffit pas à fournir cette interface. Caddy doit remplacer `X-Analytics-Client-IP` par une adresse client issue d’une source de confiance. Garde les ports applicatifs privés et configure les plages d’adresses des proxys de confiance si un autre proxy se trouve en amont. Le serveur transmet l’IP validée, le User-Agent du navigateur et les en-têtes Umami nécessaires ; il retire les cookies, les identifiants de connexion et les en-têtes de provenance du navigateur.

Les rapports contiennent les chemins publics connus ou les modèles de routes privées de la plateforme, les origines de provenance, la langue du navigateur, la taille de l’écran, le navigateur, le système, l’appareil et la localisation approximative. La collecte déduit les visites et la localisation de l’IP sans conserver l’adresse brute. Des paramètres génériques remplacent les identifiants privés d’organisation et de ressource. Les titres de page, paramètres de recherche, fragments, champs de formulaire et contenus produit sont exclus. Le site marketing compte aussi les demandes de contact et de démo abouties, sans leur contenu. Il n’y a ni identité entre sites, ni capture automatique des clics, ni enregistrement des sessions. Do Not Track et Global Privacy Control désactivent la collecte.

Après le déploiement, vérifie le comportement avec un navigateur qui autorise la collecte :

1. Ouvre une page connue, passe à une autre et vérifie les deux pages vues dans le site Umami du déploiement.
2. Inspecte le corps de la requête. Les routes privées contiennent des paramètres génériques, sans paramètres de recherche, titres ni données de formulaire.
3. Active Do Not Track ou Global Privacy Control et vérifie que la collecte s’arrête.
4. Bloque la collecte ou teste son indisponibilité. La navigation normale doit continuer à fonctionner.

## Connaître les limites

Tale n’exporte actuellement pas de traces OpenTelemetry par OTLP. Un OpenTelemetry Collector peut collecter les métriques Prometheus, mais cette collecte ne produit pas de traces distribuées. L’export de traces de bout en bout exige aussi une instrumentation de l’application.

Pour les seuils d’alerte et les procédures d’intervention, consulte [Exploitation](https://docs.tale.dev/fr/self-hosted/operate/observability/operations). Si un service échoue, utilise les tableaux de symptômes du [Dépannage](https://docs.tale.dev/fr/self-hosted/operate/observability/troubleshooting).

# Fournisseurs
Source: https://docs.tale.dev/fr/self-hosted/configuration/providers

Pour configurer un fournisseur IA, distingue sa définition de fournisseur, les identifiants de l’organisation et le serveur de modèles. La définition décrit l’endpoint et le protocole ; les identifiants contrôlent l’accès ; l’opérateur de l’endpoint exploite le service.

Cette page couvre les définitions personnalisées et les secrets issus de l’environnement. Pour créer des identifiants et choisir les valeurs par défaut dans l’application, suis [Fournisseurs IA](https://docs.tale.dev/fr/platform/admin/providers).

## Endpoints de fournisseurs locaux

Un serveur d’inférence local exige une définition de fournisseur et l’autorisation pour le backend d’atteindre son hôte. La définition n’installe pas le serveur et ne charge aucun modèle.

1. Rends le serveur joignable depuis chaque rôle backend qui l’appelle. Dans un conteneur, `localhost` désigne ce conteneur, pas la machine hôte. Vérifie la résolution du nom, l’accès réseau et, si nécessaire, le certificat TLS depuis le réseau d’exécution réel.
2. Pour un endpoint privé ou de boucle locale, définis `TALE_ALLOW_PRIVATE_PROVIDER_HOSTS=1` dans l’environnement du backend. Cette option autorise les hôtes de fournisseurs privés pour tout le déploiement ; ce n’est pas une liste d’autorisation par fournisseur. Les endpoints de métadonnées cloud restent bloqués. Recrée les conteneurs concernés pour appliquer le changement : un redémarrage conserve leur environnement Compose actuel.
3. Déclare le fournisseur dans `TALE_CONFIG_DIR/<orgSlug>/providers/local-models.yml` ou avec la [procédure de configuration gérée](https://docs.tale.dev/fr/self-hosted/configuration/config-releases). Respecte le schéma natif et choisis un nom distinct des définitions fournies. Un admin de l’organisation peut aussi créer le même fichier depuis l’app : **Ajouter des identifiants** > **Fournisseur personnalisé** sous **Paramètres > Fournisseurs IA** ; voir [Définir un fournisseur personnalisé](https://docs.tale.dev/fr/platform/admin/providers#definir-un-fournisseur-personnalise).

Dans cet exemple, remplace l’IP privée et le port par ceux de ton serveur. HTTP est accepté uniquement pour les hôtes reconnus comme privés ou de boucle locale ; les endpoints publics exigent HTTPS. Un nom DNS interne ne contourne pas le contrôle des hôtes privés effectué à chaque requête.

```yaml
name: local-models
displayName: Local models
apiFormat: openai
baseUrl: http://192.168.1.20:8000/v1
catalog:
  source: models-endpoint
auth:
  - method: api-key
  - method: env
```

Cette définition utilise une API de chat compatible OpenAI et découvre les modèles à partir de `/v1/models`. Vérifie la compatibilité réelle du serveur : une liste de modèles ne prouve pas que la génération, les appels d’outils ou le streaming fonctionnent. Si le serveur ne peut pas lister ses modèles, utilise `catalog.source: none` et saisis leurs identifiants exacts dans la liste autorisée de l’accès. Un fournisseur personnalisé ne charge pas de fichier de modèles statique propre à l’organisation.

Un administrateur ajoute ensuite un accès dans [Fournisseurs IA](https://docs.tale.dev/fr/platform/admin/providers), actualise le catalogue et sélectionne un modèle précis pour un court chat. Vérifie la requête terminée dans les journaux du serveur prévu. Les embeddings, la parole et les outils nécessitent leur propre contrôle des destinations ; un endpoint de chat local ne les rend pas locaux.

## Configurer la transcription audio

La politique de l’organisation se trouve dans `TALE_CONFIG_DIR/<org>/governance/transcription-model.yml`, sous le type `transcription_model`. La page [Modèles](https://docs.tale.dev/fr/platform/admin/governance/content-models) modifie la même sélection. Un fichier absent ou un objet vide signifie une sélection automatique :

```yaml
{}
```

Pour fixer un modèle, fournis les deux champs. Cet exemple utilise le modèle OpenAI Whisper fourni et exige toujours un accès actif et utilisable dans l’organisation :

```yaml
providerSlug: openai
modelId: whisper-1
```

Une sélection partielle est invalide. Un modèle fixé mais indisponible n’est jamais remplacé automatiquement : rétablis son accès fournisseur ou les modèles autorisés pour cet accès, ou reviens explicitement à la sélection automatique. Un échec de lecture ou de validation de la configuration refuse aussi la transcription serveur. La politique couvre les fichiers audio et vidéo, le recours à l’audio pour les liens vidéo et la dictée serveur. La reconnaissance vocale du navigateur reste indépendante.

Avec un accès OpenRouter actif défini par défaut, Tale découvre aussi les modèles de reconnaissance vocale via `/models?output_modalities=transcription`. Le même accès et ses modèles autorisés s’appliquent. Pour fixer un modèle, reprends son identifiant exact dans ce catalogue, ou conserve la sélection automatique. Le [guide de reconnaissance vocale d’OpenRouter](https://openrouter.ai/docs/guides/overview/multimodal/stt) décrit l’API du fournisseur.

Pour un endpoint personnalisé compatible OpenAI, utilise `catalog.source: models-endpoint`. Sa réponse à `/models` doit déclarer le modèle audio avec un identifiant `id` exact et soit `type: transcription`, soit `architecture.output_modalities: [transcription]`. Un modèle dédié uniquement à la transcription peut omettre `context_window` ou indiquer `0` ; les autres modèles exigent toujours une valeur positive. Un modèle de chat avec entrée audio ou un modèle de synthèse vocale ne devient pas automatiquement un candidat à la transcription.

Tale envoie les champs multipart `file` et `model` à `POST <baseUrl>/audio/transcriptions`, avec une authentification Bearer. Pour OpenRouter, Tale demande `response_format: json`, car certains de ses modèles refusent `verbose_json`. Les autres endpoints compatibles doivent accepter `response_format: verbose_json`. La réponse JSON fournit la transcription dans `text`. Pour la durée, Tale privilégie une valeur `duration` valide, sinon une valeur `usage.seconds` valide. Si aucune ne convient, Tale utilise la durée mesurée localement lorsqu’elle est disponible. Des `segments` horodatés peuvent fournir les horodatages vidéo ; sans eux, la transcription reste du texte brut. La présence au catalogue ne prouve pas que cette API fonctionne. Actualise le catalogue, sélectionne le modèle, puis teste un court enregistrement et vérifie la requête dans les journaux de cet endpoint.

## Configurer la génération d’images {#configure-image-generation}

La politique de l’organisation se trouve dans `TALE_CONFIG_DIR/<org>/governance/image-generation.yml`, sous le type `image_generation`. La page [Modèles](https://docs.tale.dev/fr/platform/admin/governance/content-models#let-agents-generate-images) modifie les mêmes réglages. Une nouvelle organisation démarre avec la génération d’images désactivée, et un fichier absent signifie aussi désactivée :

```yaml
enabled: false
```

Indique `enabled: true` pour la sélection automatique, ou fixe un modèle en renseignant les deux champs :

```yaml
enabled: true
providerSlug: openai
modelId: gpt-image-1
```

Un modèle fixé à moitié ou un champ inconnu est invalide. Un fichier invalide ou illisible laisse la génération d’images désactivée, et la page Modèles nomme le problème. La sélection automatique essaie `google/gemini-2.5-flash-image`, `gpt-image-1-mini`, `gpt-image-1` et `black-forest-labs/flux.2-pro`, dans cet ordre, via un identifiant par défaut OpenRouter ou OpenAI. Si le modèle fixé est indisponible, Tale ne passe jamais à un autre modèle. Un modèle fixé peut rester dans le fichier tant que `enabled` vaut `false`.

Le backend appelle le modèle d’images avec l’identifiant de l’organisation ; aucune clé n’entre dans la sandbox. Pour OpenRouter, il envoie `POST <baseUrl>/images`, l’API d’images d’OpenRouter, avec un format `1:1`, `3:2` ou `2:3`, et enregistre le coût que la réponse indique. Pour tout autre fournisseur, il utilise l’API d’images d’OpenAI : `POST <baseUrl>/images/generations`, ou `POST <baseUrl>/images/edits` en formulaire multipart quand l’agent transmet des images de référence ; il demande alors à un modèle d’images GPT la qualité `medium`. Tale évalue ensuite les tokens indiqués par la réponse avec les tarifs de l’entrée du modèle dans le catalogue. Tale découvre les modèles d’images d’OpenRouter via `/models?output_modalities=image`, et le catalogue OpenAI fourni contient `gpt-image-1` et `gpt-image-1-mini`.

La réponse `/models` d’un endpoint personnalisé compatible OpenAI doit déclarer un modèle d’images avec `image` parmi `architecture.output_modalities` ou `modalities.output`, et un `context_length` ou `context_window` positif. Tale n’enregistre que des images matricielles (PNG, JPEG, WebP, GIF) et refuse le SVG d’un modèle ; une image de référence transmise par un agent doit être un fichier PNG, JPEG ou WebP de 4 Mo au plus. Une entrée de catalogue ne prouve pas que l’endpoint fonctionne : active la génération d’images, fixe le modèle, fais créer une image de test par un agent, puis vérifie la requête dans les journaux de l’endpoint.

Un tour d’agent crée au plus 16 images et n’exécute qu’une génération à la fois. Avant chaque appel, Tale réserve 0,25 USD par image sur l’enveloppe du tour et les plafonds de budget, puis enregistre le coût indiqué à la place de cette réserve à la fin de l’appel. La clé de passerelle du tour cède le même montant sur son plafond, de sorte que le modèle et les images restent ensemble dans une seule enveloppe ; si la passerelle ne peut pas abaisser ce plafond, l’image est refusée. Un tour qui passe par un abonnement fournisseur n’a pas d’enveloppe de passerelle : ses images sont mesurées par rapport à l’enveloppe que l’installation accorde par défaut à un tour.

## Configurer l’agent standard {#configure-the-standard-agent}

La politique de l’organisation se trouve dans `TALE_CONFIG_DIR/<org>/governance/standard-agent.yml`, avec le type de politique `standard_agent`. La [page Modèles](https://docs.tale.dev/fr/platform/admin/governance/content-models#standard-agent) modifie les mêmes réglages. Une nouvelle organisation reçoit l’agent standard activé, et un fichier absent signifie aussi qu’il est activé :

```yaml
enabled: true
```

Fixe le harness, le modèle ou les deux, et remplace les instructions intégrées :

```yaml
enabled: true
harness: claude-code
providerSlug: anthropic
modelId: claude-sonnet-5
instructions: |
  Écris dans le style de la maison. Livre chaque document au format Word.
```

`harness` prend le slug d’un environnement qu’un agent de projet peut utiliser, par exemple `claude-code` ou `codex` ; la page Modèles refuse les autres. Un modèle fixé demande à la fois `providerSlug` et `modelId`. Une fixation partielle, un champ inconnu ou des instructions de plus de 20 000 caractères sont invalides. Un fichier invalide ou illisible empêche tout agent standard de démarrer, et la page Modèles nomme le problème ; il n’est jamais lu comme activé. Un modèle fixé indisponible ne bascule jamais vers un autre modèle, pas plus qu’un modèle que l’accès aux modèles d’une personne lui refuse. La politique est lue à chaque démarrage d’une exécution : une modification s’applique donc à l’exécution suivante. Avec `enabled: false`, les agents standard déjà mis en place restent dans leurs projets, mais aucun ne démarre.

## Vérifier l’accès aux modèles depuis la sandbox

Le chat appelle un fournisseur depuis le backend. Les agents de programmation passent par `sandbox-llm-gateway` : un chat réussi ne valide donc pas leur connexion. L’endpoint doit être résolvable et joignable depuis le backend et la passerelle. Chaque client HTTPS doit faire confiance à son certificat. Un nom comme `https://models.internal/v1` exige lui aussi l’autorisation des fournisseurs privés lorsque le DNS renvoie une adresse privée. HTTP reste limité aux formes d’hôtes acceptées par le schéma, comme une IP privée, `localhost` ou `.local`.

Au démarrage d’une nouvelle session sandbox, le backend contrôle le nom du fournisseur personnalisé et ses réponses DNS avant de le configurer dans la passerelle. Les destinations privées exigent `TALE_ALLOW_PRIVATE_PROVIDER_HOSTS=1` ; les métadonnées restent bloquées même avec cette option. Ce contrôle préalable ne fixe pas les réponses DNS des requêtes ultérieures de la passerelle. Garde la définition du fournisseur et le DNS sous le contrôle d’opérateurs de confiance.

Recrée les processus backend concernés avec le nouvel environnement, puis démarre une nouvelle session sandbox avec le fournisseur, le modèle et un environnement d’exécution compatible. Envoie une demande sans contenu sensible et vérifie la réponse complète ainsi que l’entrée correspondante dans les journaux du serveur d’inférence. Si le chat fonctionne mais que l’agent n’atteint pas son modèle, examine les journaux de `sandbox-llm-gateway`. `SANDBOX_EGRESS_ALLOWLIST` contrôle l’accès web général de la sandbox, pas cette connexion distincte au modèle.

Les agents de programmation s’appuient aussi sur la fenêtre de contexte que le catalogue indique pour le modèle : la valeur `context_length` ou `context_window` que ton serveur publie sur `/v1/models`, ou 128 000 tokens lorsque la liste n’indique ni l’une ni l’autre, comme pour un fournisseur configuré avec `catalog.source: none`. Fais en sorte que cette liste indique le contexte que ton serveur sert réellement. Lorsque cette fenêtre, ou une [limite de contexte](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits) plus basse pour la personne qui a lancé l’exécution, reste sous 200 000 tokens, une session Claude Code gérée condense sa conversation en un résumé avant que le prompt ne la dépasse. Claude Code traite toute valeur inférieure à 100 000 tokens comme 100 000 : un modèle qui offre moins de contexte peut donc recevoir des prompts plus longs qu’il ne peut en contenir. Réserve Claude Code aux modèles qui offrent au moins ce contexte.

Sur un modèle autre que Claude, une session Claude Code gérée omet aussi la ligne d’attribution que Claude Code place sinon au début de chaque prompt système. Cette ligne change à chaque requête : un serveur qui met en cache le début des prompts devrait sinon recalculer toute la conversation à chaque tour.

## Où vivent les connecteurs

Les définitions fournies se trouvent dans `configs/platform/system/providers/<slug>/provider.yml` et leurs catalogues statiques dans `configs/platform/system/models/<slug>/models.yml`. Anthropic utilise par exemple `providers/anthropic/provider.yml` et `models/anthropic/models.yml`. Ces fichiers appartiennent à l’image et évoluent avec sa version.

<Warning>

Les fichiers fournis sont des entrées d’image en lecture seule, remplacées lors des mises à niveau. Pour un fournisseur externe, utilise la déclaration vérifiée `configuration` décrite dans [Installation CLI](https://docs.tale.dev/fr/self-hosted/install/cli-install#configurer-la-plateforme). Elle crée un connecteur propre à l’organisation sous `TALE_CONFIG_DIR/<org>/providers/` avec le schéma natif ; les modifications d’identifiants et de politiques passent par les API natives. L’entrée **Fournisseur personnalisé** d’**Ajouter des identifiants** dans l’app écrit le même fichier propre à l’organisation et conserve chaque version enregistrée sous `.history/`.

</Warning>

## Ce qu’un connecteur déclare

Une définition décrit le protocole, l’endpoint, le catalogue et les méthodes d’authentification admises. Elle ne contient aucun identifiant d’organisation. Ces deux extraits en montrent le format :

<CodeGroup>

```yaml anthropic.yml
name: anthropic
displayName: Anthropic
apiFormat: anthropic
baseUrl: https://api.anthropic.com
catalog:
  source: static
auth:
  - method: api-key
  - method: env
  - method: subscription-broker
    constraints:
      execution: sandbox
      harness: claude-code
```

```yaml openrouter.yml
name: openrouter
displayName: OpenRouter
apiFormat: openai
baseUrl: https://openrouter.ai/api/v1
catalog:
  source: openrouter-api
auth:
  - method: api-key
  - method: env
```

</CodeGroup>

| Champ | Rôle |
| --- | --- |
| `apiFormat` | Format de requête : `openai` ou `anthropic`. |
| `wireDialect: openai-modern` | Pour le format OpenAI : utilise `max_completion_tokens` et omet la température personnalisée pour les modèles de raisonnement. Laisse-le absent pour les endpoints qui exigent les champs classiques. |
| `baseUrl` | Endpoint fixe partagé par les accès correspondants. |
| `endpointMode: per-credential` | Utilise un endpoint propre à chaque accès à la place de `baseUrl`, comme Azure OpenAI. |
| `catalog.source` | `static`, `openrouter-api`, `models-endpoint` ou `none`. Les entrées statiques viennent du catalogue de modèles décrit plus haut. |
| `embedding` | Indique si le fournisseur sert des embeddings : `supported` quand son catalogue fournit une largeur de vecteurs vérifiée, `unsupported` quand il ne propose aucun modèle d’embedding, si bien que **Paramètres > Résidence des données > Modèle d’embedding** le refuse, ou `unknown`, la valeur par défaut, quand un admin saisit le modèle et sa largeur de vecteurs. Ne déclare `unsupported` que si la documentation du fournisseur lui-même l’indique. |
| `auth` et `constraints` | Méthodes d’accès admises et conditions d’exécution, par exemple un harness sandbox précis. |

## Source de clé par variable d’environnement

Avec la méthode **Variable d’environnement**, l’accès enregistre un nom de variable ; le backend en lit la valeur dans son environnement au moment de la requête. Fournis cette valeur avec le gestionnaire de secrets du déploiement. Cette méthode ne stocke pas la clé API dans la base applicative.

Seuls les noms commençant par `TALE_PROVIDER_KEY_` sont acceptés. Le nom complet est limité à 40 caractères ; le suffixe accepte lettres, chiffres et traits de soulignement. Le formulaire ajoute le préfixe automatiquement.

```bash
TALE_PROVIDER_KEY_OPENROUTER=sk-or-...
TALE_PROVIDER_KEY_OPENAI_PROD=sk-...
```

<Note>

Le préfixe réservé empêche un accès de désigner un autre secret tel que `SOPS_AGE_KEY` ou `BETTER_AUTH_SECRET`. La validation refuse les noms invalides avant l’enregistrement.

</Note>

Après avoir ajouté ou renouvelé la valeur, recrée `backend-api` et `backend-worker` avec le nouvel environnement. Un redémarrage Compose conserve les anciennes valeurs. Les espaces au début et à la fin sont supprimés avant utilisation. Vérifie une vraie requête après le déploiement.

## Connecter un courtier d’abonnement

Un courtier d’abonnement fournit un pool de jetons d’accès OAuth ; Tale choisit un compte utilisable pour chaque tour d’agent. Les intégrations livrées sont Anthropic avec Claude Code et OpenAI ChatGPT avec Codex, pour les agents de tâche et d’automatisation. Conserve des identifiants API directs pour les chats et les autres appels directs aux modèles. Un jeton OAuth n’est pas une clé API de fournisseur.

Utilise une adresse distincte pour chaque fournisseur. Tale AI Gateway expose `/api/tokens/anthropic` et `/api/tokens/openai`, avec sa clé API comme jeton Bearer pour l’authentification. L’adresse combinée `/api/tokens` ne convient pas à des identifiants associés à un seul fournisseur. Le backend doit pouvoir joindre le courtier selon la politique d’accès aux hôtes décrite plus haut pour les fournisseurs.

L’exemple ci-dessous est le document d’identifiants du courtier construit par le [formulaire des fournisseurs IA](https://docs.tale.dev/fr/platform/admin/providers#connecter-un-courtier-dabonnement), pas un fichier de définition de fournisseur. Remplace le nom d’hôte par celui de ton courtier et fournis sa clé API dans `TALE_TOKEN_SOURCE_AI_GATEWAY` aux deux processus backend. Les noms de propriétés correspondent à Tale AI Gateway ; adapte-les à la réponse si tu utilises un autre courtier.

```json
{
  "endpoint": "https://broker.example.com/api/tokens/anthropic",
  "httpMethod": "GET",
  "auth": {
    "method": "bearer",
    "secretEnv": "TALE_TOKEN_SOURCE_AI_GATEWAY"
  },
  "responseMapping": {
    "tokensPath": "$.tokens",
    "tokenField": "access_token",
    "statusField": "status",
    "activeValue": "active",
    "expiresField": "expires_at"
  },
  "targetEnvVar": "CLAUDE_CODE_OAUTH_TOKEN",
  "selection": "round-robin"
}
```

Pour OpenAI, remplace la fin de l’adresse par `/api/tokens/openai` et `targetEnvVar` par `TALE_SUBSCRIPTION_TOKEN`. Chaque entrée OpenAI utilisable doit aussi contenir l’`account_id` du fournisseur. Tale transmet cette valeur dans `TALE_SUBSCRIPTION_ACCOUNT_ID`, avec le jeton, à la connexion ChatGPT de Codex. N’utilise ni l’`id` de la passerelle ni `CODEX_ACCESS_TOKEN` à la place de ces valeurs. Limite les modèles autorisés de ces identifiants aux modèles pris en charge par l’abonnement ChatGPT ; le catalogue de l’API OpenAI peut contenir des modèles indisponibles avec les abonnements.

Pour Anthropic OAuth, utilise `CLAUDE_CODE_OAUTH_TOKEN`. La cible historique `ANTHROPIC_AUTH_TOKEN` reste prise en charge lorsqu’elle est configurée explicitement ; elle utilise l’authentification Bearer générique de Claude Code. Tale retire les autres variables d’identifiants du fournisseur avant de transmettre le jeton choisi. Une variable cible non prise en charge par l’environnement d’agent sélectionné est refusée.

### Identité des comptes et quotas

En plus des champs de jeton, de statut et d’expiration configurés, chaque entrée peut fournir les champs standard suivants. Leurs noms sont fixes et ne demandent aucune configuration supplémentaire de la réponse.

| Champ | Rôle |
| --- | --- |
| `id` | Identifiant du courtier |
| `provider` | Fournisseur |
| `account_id` | Compte du fournisseur |
| `available` | Disponibilité pour un nouveau travail |
| `available_at` | Moment où le compte redevient disponible |
| `hold` | Raison pour laquelle un compte indisponible est retenu |
| `usage` | Relevé d’usage |

L’`id` doit rester stable lorsque le jeton d’accès change, afin de reconnaître le compte lors des nouvelles tentatives. Il est distinct de l’`account_id` du fournisseur requis par OpenAI. Si `provider` désigne un autre fournisseur que celui des identifiants, l’entrée est exclue.

`available: false` exclut le compte jusqu’à l’horodatage ISO dans `available_at`. Si le renouvellement est inconnu, omets cet horodatage ou utilise `null` ; le compte reste alors exclu jusqu’à ce que le courtier le déclare disponible. Le statut et l’expiration du jeton sont vérifiés séparément. Tale AI Gateway calcule la disponibilité à partir d’un relevé `usage` contenant `checked_at` et `windows`, chaque fenêtre indiquant son type, son utilisation et son horodatage de renouvellement.

Les anciens courtiers peuvent omettre ces métadonnées facultatives. Sans `id`, Tale utilise une empreinte du jeton pour identifier le compte lors des nouvelles tentatives ; il ne peut donc pas le reconnaître après un changement de jeton. L’absence de données de quota laisse le compte sélectionnable, sans prouver qu’il reste du quota.

Tale AI Gateway exclut un compte lorsqu’un relevé récent indique qu’une fenêtre globale de session ou hebdomadaire est utilisée à 100 % et que son renouvellement n’a pas encore eu lieu. Un signal explicite de limite du fournisseur (`usage.limited: true`) rend aussi le compte indisponible, même si le taux d’utilisation affiché est inférieur ou absent. Les limites propres à un modèle n’excluent pas le compte entier. Un relevé devient périmé après 15 minutes : des données inconnues ou périmées laissent donc le compte sélectionnable. Une fenêtre épuisée sans horodatage de renouvellement bloque le compte uniquement tant que le relevé est récent. La demande de jetons suivante actualise les données périmées lorsque le fournisseur le permet. Après le renouvellement du quota concerné, le compte peut rejoindre le pool. Le fournisseur peut encore refuser une requête entre deux actualisations. Tale AI Gateway signale aussi un compte comme indisponible jusqu’à l’actualisation prévue de son jeton (`refresh_at`) dès qu’elle est à moins d’une heure, soit la durée de validité qu’il garantit par défaut à un jeton distribué, et qu’un autre compte peut prendre le travail. Un tel compte porte `hold: "refresh"`, tandis qu’un quota épuisé porte `hold: "quota"`. La passerelle juge qu’un autre compte peut prendre le travail sans connaître les règles propres à Tale : le délai d’attente après un HTTP 429 décrit plus bas et l’`account_id` exigé par OpenAI. Si ces règles ne laissent aucun compte disponible, Tale utilise, parmi les comptes retenus pour leur actualisation, celui dont l’actualisation est la plus lointaine, au lieu de refuser le travail. Une exécution ne démarre donc avec un jeton sur le point d’être révoqué que si le pool n’a rien de mieux, et un pool d’un seul compte n’est jamais retenu de cette façon. Un courtier qui n’envoie pas de champ `hold` laisse exclus tous les comptes indisponibles.

### Sélection et résolution des erreurs

`random` est le choix initial du formulaire ; `first` suit l’ordre du courtier. `round-robin` choisit le compte utilisable dont la dernière sélection est la plus ancienne, avec un historique conservé par organisation et par identifiants. Les requêtes simultanées de plusieurs processus backend mettent cet historique à jour de façon atomique ; l’ordre des réponses et les redémarrages ne le réinitialisent pas. Conserver l’historique d’un compte après un changement de jeton exige un `id` stable. Ces stratégies répartissent les sélections de comptes, pas la consommation de jetons ni la capacité des agents en cours. Les identifiants existants conservent leur stratégie enregistrée.

Lorsqu’un compte répond HTTP 429, Tale l’exclut des nouvelles sélections pendant 60 secondes pour cette organisation et ces identifiants. Les nouvelles tentatives privilégient les comptes encore inutilisés pendant la série d’échecs de l’exécution. Si tous les comptes autrement utilisables ont été essayés, une tentative peut en réutiliser un ; les exclusions liées au quota et au délai d’attente restent applicables. Lorsque tous les comptes sont dans ce délai d’attente, une nouvelle tentative automatique d’une tâche ou d’une automatisation est mise en file d’attente aussitôt, mais ne démarre que lorsque le premier compte redevient disponible. Cette attente ne consomme aucune tentative automatique si l’exécution refusée relançait elle-même un échec en HTTP 429.

Un HTTP 401 pendant une exécution utilisant un jeton du courtier peut indiquer que ce jeton a changé pendant le travail. Tale redemande des identifiants au courtier et reprend la conversation si sa référence et sa session sandbox sont encore disponibles ; sinon, un nouveau tour commence. Les deux premières interruptions de ce type d’affilée ne consomment pas de tentative automatique et n’excluent pas le compte, pour permettre l’utilisation d’un jeton de remplacement du même compte. La troisième compte comme n’importe quel autre échec. Cette limite couvre aussi un 401 dû à une autorisation invalide plutôt qu’à un changement de jeton. Après au moins quinze minutes de travail, le décompte repart de zéro.

Sans valeur personnalisée, une demande de pool expire après 10 secondes et accepte au plus 262 144 octets. L’expiration d’un jeton, lorsqu’un champ est configuré pour la lire, doit se situer au-delà de la marge de sécurité `expirySkewMs`, de cinq minutes par défaut. Avec Tale AI Gateway, conserve les champs de statut et d’expiration pour écarter les jetons inactifs ou proches de leur expiration ; la passerelle retient déjà elle-même les comptes dont le jeton va bientôt être actualisé. Son champ `refresh_at` indique le moment où son actualisation met fin à un jeton, avant l’`expires_at` du fournisseur. Configurer `refresh_at` comme champ d’expiration et relever `expirySkewMs` (3 600 000 ms au plus) rend cette règle stricte : aucune exécution ne démarre alors avec un jeton valable moins longtemps que la marge, mais tant que tous les comptes sont aussi proches de leur actualisation, le pool refuse tout nouveau travail, et un pool d’un seul compte le fait avant chaque actualisation. Les dates d’expiration peuvent être des horodatages ISO ou Unix, en secondes ou en millisecondes.

La durée minimale restante protège le démarrage d’une exécution, pas toute sa durée. Une longue tâche ou automatisation peut dépasser la durée d’un jeton et nécessiter la reprise limitée décrite ci-dessus. Une nouvelle demande au courtier ne garantit pas que le compte fournira des identifiants valides.

Si aucun compte n’est utilisable, vérifie l’authentification auprès du courtier, le statut des comptes, les expirations et les actualisations prévues des jetons, les renouvellements de quota et les champs de réponse configurés. Renouvelle l’autorisation du compte, ou attends le renouvellement du quota ou l’actualisation du jeton selon le cas, puis vérifie qu’une tâche ou automatisation termine sa réponse avec le fournisseur et l’environnement prévus. Une requête réussie auprès du courtier ne teste pas à elle seule la connexion au fournisseur.

## Secrets de courtier depuis l’environnement

Des identifiants de type **Courtier d'abonnement** peuvent lire le secret du courtier dans l’environnement du déploiement. Utilise le préfixe distinct `TALE_TOKEN_SOURCE_` dans **Secret depuis une variable d'environnement** et laisse **Secret du courtier** vide. Les autres noms sont refusés. Si tu fournis les deux valeurs, le secret stocké du courtier est prioritaire. Recrée les processus concernés lorsque tu changes une valeur issue de l’environnement.

Si la nouvelle configuration du courtier utilise encore une authentification, laisser les deux champs de secret vides conserve le secret déjà stocké. Saisir une référence d’environnement sans nouveau secret du courtier active la source d’environnement. Choisir **Aucune** pour l’authentification du courtier retire le secret stocké de la configuration de remplacement.

## Gérer les réglages propres à l’organisation

Les noms des accès, modèles autorisés, valeurs par défaut et états actifs restent des données d’organisation, généralement gérées sous [Fournisseurs IA](https://docs.tale.dev/fr/platform/admin/providers). Une version de configuration gérée peut créer des accès précis liés à l’environnement via les API natives après vérification de l’organisation et de l’opérateur. Elle n’installe aucun serveur d’inférence et ne prouve pas le comportement du modèle. Effectue les contrôles de l’endpoint local décrits plus haut après le déploiement.

# Définir les limites de conservation
Source: https://docs.tale.dev/fr/self-hosted/configuration/retention

La conservation détermine combien de temps Tale garde chaque catégorie de données. L’opérateur fixe les limites autorisées ; l’admin de l’organisation active les catégories et choisit une durée dans ces limites. Une durée plus courte peut supprimer un historique existant : examine son effet avant de l’appliquer.

## Distinguer limites et politique

Deux fichiers sous `TALE_CONFIG_DIR/<orgSlug>/governance/` ont des fonctions différentes :

| Fichier | Fonction |
| --- | --- |
| `retention.yml` | Limites et valeurs par défaut définies par l’opérateur pour chaque catégorie. JSON est aussi accepté. |
| `retention-policy.yml` | Catégories actives et durées choisies par l’organisation. Les paramètres de gouvernance gèrent ce fichier. |

Chaque organisation reçoit ses propres fichiers à sa création. Modifier ceux d’une organisation ne change pas la politique d’une autre. Si son fichier de limites manque, Tale ne reprend pas celui d’une organisation `default`.

Chaque catégorie contient `min`, `max`, `default` et `unit`. Augmenter `min` impose de garder les données plus longtemps ; diminuer `max` réduit la durée autorisée. Aucune de ces valeurs n’active seule le nettoyage. La politique appliquée détermine si la catégorie est active.

## Modifier les limites d’une organisation

Pars de son fichier complet existant et conserve les catégories que tu ne modifies pas. Cet extrait montre une seule catégorie ; il ne remplace pas le fichier entier :

```yaml
chatHistory:
  min: 30
  max: 730
  default: 90
  unit: days
```

La plupart des catégories utilisent les jours ; `userTempHours` et `agentTempHours` utilisent les heures. La catégorie de consommation de tokens s’appelle `usageLedger`. Reprends les identifiants du fichier existant pour que la validation puisse détecter les erreurs.

Les variables d’environnement sont associées explicitement dans `_metadata.envNames`, à la racine du fichier, avec un préfixe facultatif `_metadata.envPrefix`. Le fichier livré associe par exemple `TALE_RETENTION_AUDIT_MIN` à `auditLog.min`. Une variable ne peut qu’augmenter le minimum ou diminuer le maximum. Redémarre les processus backend après avoir modifié leur environnement.

Deux minimums sont imposés : `auditLog.min` ne peut pas descendre sous 180 jours, ni `loginAttempt.min` sous 90 jours. Tale ne charge pas un fichier qui passe sous l’un d’eux. Tant que tu ne l’as pas corrigé, la **Politique de rétention** de l’organisation n’affiche aucune plage autorisée et ne peut pas être enregistrée ; les journaux du backend indiquent les deux minimums. Le nettoyage planifié continue d’utiliser les dernières limites appliquées.

Avec le fichier livré, une organisation peut conserver les journaux d’audit de 180 à 3650 jours. Une mise à niveau de Tale ne réécrit pas le fichier d’une organisation : une organisation créée par une version antérieure peut donc encore contenir `auditLog.min: 365`. Abaisse cette valeur pour autoriser une conservation plus courte des journaux d’audit, ou augmente-la si une réglementation ou un contrat exige un historique d’audit plus long.

## Examiner et appliquer un changement

Après avoir modifié les limites, demande à l’admin de l’organisation d’examiner la proposition dans [Politiques et limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits). Le nettoyage utilise les limites déjà appliquées ; une modification du fichier par l’opérateur ne les active pas silencieusement.

Vérifie les catégories actives, les anciennes et nouvelles durées et les éventuels délais de grâce. `auditLogRetentionDays: 730` est une durée choisie, tandis que `auditLog.min: 180` est une limite minimale. Distingue ces deux sens pendant la revue du diff.

<Tip>

Teste d’abord une durée réduite sur des données synthétiques. Vérifie qu’une donnée encore dans la période reste présente, qu’une donnée expirée suit le comportement de sa catégorie et qu’une donnée sous gel reste protégée.

</Tip>

## Comprendre le nettoyage

Le worker backend effectue le nettoyage planifié par organisation. Les threads, documents, contacts et conversations externes ont un cycle de vie ; les catégories de lignes individuelles peuvent être supprimées directement après leur durée de conservation et leur délai de grâce. Ne suppose pas que chaque élément supprimé passe par la Corbeille.

Chaque cycle supprime un nombre limité d’éléments par catégorie et par organisation : jusqu’à 50 000 événements chat-filter, et des lots de 1 000 éléments au plus pour toutes les autres catégories. Un arriéré plus important, comme un long historique lors de la première activation d’une catégorie, se résorbe sur plusieurs cycles quotidiens.

La conservation des journaux d’audit est aussi propre à chaque organisation. Elle supprime le début éligible de sa chaîne d’audit, du plus ancien au plus récent, et s’arrête lorsqu’une ligne sous gel doit rester. La durée plus courte d’un tenant ne réduit pas l’historique d’un autre.

Chaque nettoyage est consigné dans le [journal d’audit](https://docs.tale.dev/fr/platform/admin/governance/audit-logs) de l’organisation sous forme d’événements système de la catégorie Données. Il commence par **Cycle de rétention démarré**, ajoute un seul événement par catégorie où il a supprimé des éléments, avec leur nombre plutôt qu’un événement par élément, et se termine par **Cycle de rétention terminé**. Un cycle qui s’arrête sur une erreur, ou qui conserve des éléments arrivés à échéance parce que leur suppression a échoué, se termine plutôt par **Cycle de rétention en échec** ; le prochain nettoyage planifié tente à nouveau de les supprimer. Tous les événements d’un même cycle désignent le même cycle de rétention comme cible, et un cycle qui ne trouve rien à supprimer consigne tout de même son début et sa fin.

`TALE_RETENTION_DISABLED=true` suspend le nettoyage planifié pendant une maintenance contrôlée par l’opérateur. Cette variable ne restaure pas les données et ne désactive pas les autres voies de suppression. Consigne son activation et retire-la à la fin de la maintenance.

## Préserver les données sous gel

Les gels juridiques priment sur la conservation dans leur périmètre. Un gel de l’organisation la protège dans son ensemble ; un gel plus ciblé protège les entités ou personnes concernées. Consulte le [parcours du gel juridique](https://docs.tale.dev/fr/platform/admin/governance/legal-hold) avant de modifier une politique qui les touche.

Un gel ne remplace pas une sauvegarde. Une fois la suppression achevée hors gel, augmenter la durée ne récupère pas les données. La restauration dépend d’une sauvegarde conservée et de l’état de déploiement correspondant.

# Protéger les secrets de configuration avec SOPS
Source: https://docs.tale.dev/fr/self-hosted/configuration/secrets-with-sops

Tale utilise SOPS et age pour les fichiers de secrets de configuration compatibles, notamment les connexions à la base documentaire et au stockage objet. Les identifiants actuels des fournisseurs AI sont stockés séparément dans la base applicative et utilisent `ENCRYPTION_SECRET_HEX`. Changer une clé age ne modifie pas ces identifiants.

## Identifier le secret concerné

Le mode de stockage détermine la clé à utiliser :

| Stockage du secret | Clé de chiffrement | Conséquence opérationnelle |
| --- | --- | --- |
| Fichier de configuration `*.secrets.json` compatible SOPS | `SOPS_AGE_KEY` ou `SOPS_AGE_KEY_FILE` | Conserve une clé capable de déchiffrer chaque fichier et sauvegarde retenus. |
| Identifiants de fournisseurs et autres valeurs Secret Box en base | `ENCRYPTION_SECRET_HEX` | Remplacer la clé rend les données chiffrées illisibles ; une rotation age ne les migre pas. |
| Identifiant de fournisseur issu d’une variable d’environnement | `TALE_PROVIDER_KEY_*` | Change le secret dans le gestionnaire du déploiement et redémarre ses consommateurs. |

Un ancien fichier `providers/<name>.secrets.json` peut subsister dans une configuration historique. Sa présence ne signifie pas que les identifiants actuels l’utilisent. Consulte [Fournisseurs](https://docs.tale.dev/fr/self-hosted/configuration/providers) pour le modèle actuel.

## Choisir une source de clé age

Une valeur directe `SOPS_AGE_KEY` prime sur `SOPS_AGE_KEY_FILE`. Choisis explicitement une source. Le fichier accepte une clé privée age par ligne et ignore les lignes vides et les commentaires `#`. Tale inclut tous les destinataires configurés lorsqu’il chiffre un nouveau fichier SOPS.

Le chemin est résolu depuis le processus qui lit le fichier. Un chemin hôte dans `.env` ne suffit pas : monte le fichier dans chaque conteneur concerné, indique son chemin interne et restreins l’accès. Recrée les conteneurs après une modification de leur environnement ; `docker compose restart` ne recharge pas les définitions modifiées.

Si les deux variables sont absentes, le module SOPS écrit les fichiers compatibles en JSON non chiffré avec les permissions `0600`. Il reconnaît toujours les fichiers déjà chiffrés et refuse de les lire sans clé. Retirer les variables ne déchiffre aucun fichier existant.

## Préparer une rotation

Inventorie les fichiers SOPS et leurs sauvegardes avant de remplacer une clé. Garde une copie protégée de l’ancienne clé et vérifie le déchiffrement d’un fichier représentatif sans afficher son contenu ni l’envoyer dans les logs.

Crée une nouvelle clé age avec tes outils habituels de gestion des secrets. Prépare un fichier protégé contenant **l’ancienne clé privée et la nouvelle**. N’écrase pas l’ancien fichier avec une commande qui ne génère que la nouvelle clé.

Monte ce fichier dans le déploiement et utilise `SOPS_AGE_KEY_FILE`. Retire la valeur directe de l’environnement des processus concernés, sinon elle reste prioritaire. Déploie le changement et vérifie que les connexions existantes fonctionnent.

## Rechiffrer et vérifier

Réécris chaque fichier concerné par son mécanisme de sauvegarde pris en charge ou par une procédure SOPS contrôlée. Tale chiffre les nouveaux fichiers pour tous les destinataires configurés. Ajouter une clé ne modifie pas les fichiers existants.

<Warning>

Ne retire pas l’ancienne clé avant d’avoir vérifié chaque fichier actif avec la nouvelle clé seule. Conserve l’ancienne clé sous protection pour les sauvegardes historiques qui en ont encore besoin.

</Warning>

Déploie ensuite un fichier qui ne contient que la nouvelle clé. Redémarre les processus concernés pour vider les caches déchiffrés, puis teste chaque connexion. Le démarrage d’un processus ne prouve pas à lui seul que tous les fichiers sont lisibles.

## Résoudre un échec de déchiffrement

| Symptôme | Vérification |
| --- | --- |
| Un fichier chiffré est trouvé sans clé | Rétablis la clé correspondante ; désactiver le chiffrement ne convertit pas le fichier. |
| La lecture du fichier de clés échoue | Vérifie le montage, le chemin interne, le propriétaire et les permissions. |
| L’ancienne clé reste sélectionnée | Retire la valeur non vide de `SOPS_AGE_KEY` avant d’utiliser le fichier. |
| La nouvelle clé ne lit pas un fichier | Conserve l’ancienne clé et rechiffre ce fichier avant de terminer la rotation. |
| Un fournisseur échoue après modification de `ENCRYPTION_SECRET_HEX` | Rétablis l’accès aux secrets en base ; changer les clés age ne les répare pas. |

Pour les secrets gérés par Vault, Kubernetes ou un autre service externe, privilégie la [source par variable d’environnement](https://docs.tale.dev/fr/self-hosted/configuration/providers) lorsqu’elle est disponible. Conserve les clés avec ton plan de reprise, sous une protection distincte des sauvegardes qu’elles déchiffrent.

# TLS et domaines
Source: https://docs.tale.dev/fr/self-hosted/configuration/tls-and-domains

Choisis l’URL que les utilisateurs ouvriront et le service qui terminera TLS avant de configurer la connexion ou d’envoyer des invitations. Le proxy Caddy de Tale peut utiliser son autorité de certification interne, obtenir des certificats publics ou servir HTTP derrière ton propre proxy TLS.

## Choisir un mode TLS

| `TLS_MODE` | Cas d’usage | Ce que tu exploites |
| --- | --- | --- |
| `selfsigned` | Développement local ou environnement privé dont les clients font confiance à ta CA. | Installer le certificat racine Caddy dans le magasin de confiance de chaque client. |
| `letsencrypt` | Nom d’hôte public servi par le proxy Tale. | DNS public, ports 80/443 accessibles et stockage persistant des certificats Caddy. |
| `external` | Load balancer ou reverse proxy qui termine déjà TLS. | Certificat amont, transfert de confiance et liaison HTTP privée vers Tale. |

Garde `SITE_URL` comme URL publique et `HOST` comme nom d’hôte. Pour appliquer de nouvelles valeurs d’environnement, recrée les services concernés. Avec la CLI du workspace, utilise le déploiement et ajoute `--stop` si le proxy doit être recréé ; examine l’aperçu et prévois une interruption. Dans ton propre Compose, le service s’appelle `proxy`, pas comme le conteneur généré.

## Faire confiance à un certificat de développement privé

`TLS_MODE=selfsigned` fait émettre les certificats par la CA interne de Caddy. Un avertissement du navigateur peut indiquer que le client ne fait pas confiance à cette CA ou que le nom d’hôte ne correspond pas. Vérifie les deux.

Copie le **certificat racine public** depuis le conteneur proxy actif. Affecte à `TALE_PROXY_CONTAINER` le véritable nom de ce conteneur :

```bash
docker cp "$TALE_PROXY_CONTAINER:/data/caddy/pki/authorities/local/root.crt" ./tale-local-root.crt
```

Vérifie qu’il provient de ton instance, puis installe-le dans les paramètres de certificats de confiance du système ou du navigateur de chaque client concerné. Ne distribue pas la clé privée de la CA. Exécuter `caddy trust` avec `docker exec` modifie le magasin du conteneur, pas celui de ton poste. Le [guide HTTPS local de Caddy](https://caddyserver.com/docs/automatic-https#local-https) précise cette limite.

## Obtenir un certificat public

1. Fais pointer les enregistrements DNS publics du nom d’hôte vers le serveur prévu. Vérifie A et AAAA si IPv6 est configuré.
2. Rends les ports 80 et 443 accessibles sur ce proxy et conserve son volume `caddy-data` lors des remplacements.
3. Configure l’URL publique et le mode de certificat :

```bash
HOST=tale.example.com
SITE_URL=https://tale.example.com
TLS_MODE=letsencrypt
TLS_EMAIL=ops@example.com
```

4. Applique la configuration, consulte `tale logs proxy`, puis ouvre l’URL publique depuis une autre machine. Vérifie le nom d’hôte et la chaîne du certificat dans le navigateur.

Caddy gère émission et renouvellement. Des problèmes DNS, réseau, ACME ou de stockage peuvent les retarder ou les empêcher. Surveille donc l’expiration et les erreurs du proxy sans supposer un délai fixe. `TLS_EMAIL` est l’adresse de contact ACME ; elle ne remplace pas la surveillance des échéances. Les [prérequis HTTPS de Caddy](https://caddyserver.com/docs/automatic-https) décrivent les conditions réseau publiques.

## Utiliser un proxy TLS amont ou ton certificat

Définis `TLS_MODE=external` lorsqu’un autre proxy termine TLS, tout en gardant l’URL HTTPS publique :

```bash
HOST=tale.example.com
SITE_URL=https://tale.example.com
TLS_MODE=external
TRUSTED_PROXIES=10.20.0.0/16
```

Dans ce montage, Caddy sert HTTP en interne ; ton proxy doit donc lui indiquer comment le navigateur s’est connecté. Transmets l’en-tête `Host` d’origine et envoie `X-Forwarded-Proto: https` : Tale s’appuie sur les deux pour garder chaque navigateur sur l’origine qu’il a ouverte. Caddy n’accepte les en-têtes transférés que depuis les adresses listées dans `TRUSTED_PROXIES` : des plages CIDR séparées par des espaces, ou `private_ranges` pour toutes les adresses privées et de bouclage, valeur par défaut si la variable n’est pas définie. Indique la plage depuis laquelle ton proxy se connecte. Toute autre valeur empêche le proxy de démarrer ; les autres modes TLS ignorent cette variable.

Garde cette liaison HTTP privée. Le conteneur proxy publie le port 80 : n’en autorise l’accès qu’à ton proxy TLS, sinon un client situé dans une plage de confiance pourrait se prévaloir d’une connexion HTTPS qu’il n’a jamais établie. Vérifie les retours de connexion, cookies sécurisés, imports et flux sur le chemin complet. Un certificat installé sur le proxy amont est indépendant du mode TLS de Tale.

Si tu maintiens plutôt une image de proxy Tale et un Caddyfile personnalisés, monte certificat et clé privée en lecture seule, puis configure la directive Caddy `tls <cert-file> <key-file>`. Monter les fichiers ou définir `TLS_MODE=external` ne les charge pas automatiquement. Ta configuration doit conserver les routes Tale, les sondes et la protection des métriques.

## Changer le domaine public ou le chemin de base

Modifie `HOST` et `SITE_URL` ensemble, ainsi que les points d’accès de stockage publics et les callbacks du fournisseur d’identité qui utilisent l’ancienne origine. Recrée les services applicatifs et proxy concernés. Teste ensuite la connexion, le téléchargement d’un fichier existant, un import et une page actualisée en direct sur la nouvelle URL.

Pour un déploiement géré créé avec `identity.bootstrap: "fresh"`, suis aussi la [procédure de migration du nom d’hôte](https://docs.tale.dev/fr/self-hosted/install/cli-install#managed-origin-migration). Elle exige l’état conservé du déploiement et un `identity.migrateOriginFrom` explicite. Modifier uniquement `HOST` et `SITE_URL` ne met pas à jour les journaux de l’identité et des clients gérés. Conserve le compte, l’organisation et les identifiants client, puis exporte la configuration des applications clientes pour le nouvel émetteur une fois le déploiement prêt.

Pour un sous-chemin comme `https://example.com/app`, définis aussi `BASE_PATH=/app`. Garde ce préfixe dans les requêtes envoyées au proxy Tale : ses routes générées le retirent en interne. Vérifie les liens absolus et callbacks, pas seulement l’accueil. Lors d’une transition planifiée, conserve l’ancien domaine tant que les utilisateurs ont besoin de ses liens ou sessions.

## Servir plusieurs domaines {#plusieurs-domaines-a-la-fois}

Liste les origines supplémentaires dans `ADDITIONAL_SITE_URLS`, séparées par des virgules ou des espaces :

```bash
HOST=tale.example.com
SITE_URL=https://tale.example.com
ADDITIONAL_SITE_URLS=https://tale.partner.example,https://app.example.org
```

Une origine comprend un schéma, un hôte et éventuellement un port, sans chemin. Caddy sert les origines listées et demande leurs certificats publics en mode `letsencrypt`. Configure le DNS et l’accès pour chacune. Ce sont des points d’entrée distincts ; les cookies restent liés au domaine sur lequel l’utilisateur se connecte.

Tale n’accepte que les origines configurées pour construire les URL publiques. Un hôte inconnu retombe sur `SITE_URL`. N’utilise pas ce repli à la place d’une configuration de domaine.

Pour un déploiement géré, déclare ces origines dans `additionalOrigins` de la spécification de déploiement plutôt que de modifier l’environnement du runtime ; voir [Servir des origines supplémentaires](https://docs.tale.dev/fr/self-hosted/install/cli-install#managed-additional-origins). La CLI y gère `ADDITIONAL_SITE_URLS` et conserve l’identité native sur l’origine principale.

### Garder les paramètres canoniques stables

| Paramètre | Pourquoi le domaine principal compte |
| --- | --- |
| Liens par e-mail et notifications | Le travail en arrière-plan n’a pas d’origine de navigateur. |
| Entity ID du SP SAML | Le fournisseur d’identité connaît un identifiant stable du service. |
| Adresses des ressources SCIM | La synchronisation d’annuaire a besoin d’URL stables. |
| Passkeys | Les identifiants sont liés au domaine de la partie de confiance et ne passent pas automatiquement d’un domaine à l’autre. |
| Point d’accès public du stockage objet | Les tâches en arrière-plan signent les liens de fichiers pour ce point d’accès. Un lien remis au navigateur utilise le domaine sur lequel il se trouve lorsque ce point d’accès est l’une des origines du déploiement ; revois un hôte de fichiers distinct lors d’un changement de domaine. |

### Enregistrer chaque callback fournisseur

Ouvre **Paramètres > SSO d'entreprise** pour copier l’URL de redirection OIDC ou ACS SAML de chaque domaine. Les métadonnées SAML contiennent les entrées ACS configurées. Pour le consentement des connecteurs, utilise les URL par domaine sous **Paramètres > Connectors > Apps OAuth**. Enregistre les URL nécessaires chez chaque fournisseur et teste une nouvelle connexion depuis chaque origine prise en charge.

# Configurer l’import de transcriptions vidéo
Source: https://docs.tale.dev/fr/self-hosted/configuration/video-ingestion

Tale utilise `yt-dlp` pour récupérer le contenu associé aux liens vidéo. La disponibilité dépend de la vidéo, des sous-titres ou de la voie d’extraction prise en charge, ainsi que des contrôles d’accès de la plateforme source. Une vidéo lisible sur ton portable peut refuser le réseau ou la session du serveur.

Ce guide d’exploitation concerne la récupération des transcriptions. Commence par une vidéo publique accessible et examine l’erreur avant d’ajouter des identifiants ou de changer la sortie réseau.

## Identifier l’étape en échec

| Observation | Première vérification |
| --- | --- |
| Une seule vidéo échoue | URL prise en charge, contenu toujours disponible et transcription ou source audio utilisable. |
| Beaucoup de vidéos échouent depuis un hôte | Erreurs de l’extracteur dans le worker, réponses de la plateforme source et chemin réseau de l’hôte. |
| Récupération réussie, recherche de connaissances en échec | Configuration d’embedding de l’organisation et statut d’indexation. |
| Échecs après une session fonctionnelle | Expiration, état du compte source et refroidissement ou retrait de la session. |

Consulte `tale logs backend-worker --tail 200` et le motif d’échec de l’élément. Conserve URL et catégorie d’erreur, mais retire cookies, URL signées et identifiants avant de partager le diagnostic. Une relance peut résoudre un échec temporaire ; des refus identiques répétés demandent une investigation.

## Vérifier le fournisseur de jetons intégré

L’image Platform inclut le plugin de jetons et le déploiement fourni démarre `bgutil-provider` sur le réseau interne. Son adresse par défaut est `http://bgutil-provider:4416`. Il fournit les jetons de preuve d’origine utilisés par certaines requêtes d’extraction ; il ne donne pas accès aux contenus privés et ne garantit pas l’acceptation de la requête.

Vérifie `tale logs bgutil-provider` et son accessibilité depuis le worker. Le service est démarré au mieux : son échec ne bloque pas le déploiement principal, mais peut dégrader la récupération des transcriptions.

`VIDEO_INGEST_POT_PROVIDER_URL` choisit un autre fournisseur. `VIDEO_INGEST_PO_TOKEN` fournit un jeton obtenu manuellement. Garde ces valeurs dans ta configuration de secrets. La [référence d’environnement](https://docs.tale.dev/fr/self-hosted/configuration/environment-reference) décrit aussi les options de client d’extraction et de plugin ; modifie-les selon l’erreur observée.

## Configurer un proxy de sortie

Utilise `VIDEO_INGEST_PROXY_URL` lorsque tes récupérations vidéo doivent passer par un proxy approuvé. Métadonnées, sous-titres et audio utilisent ce chemin. Les schémas acceptés sont `http`, `https`, `socks4`, `socks4a`, `socks5` et `socks5h` ; ce dernier résout le DNS côté proxy.

```bash
VIDEO_INGEST_PROXY_URL=socks5h://proxy.example.com:1080
```

Ajoute les identifiants requis via ton gestionnaire de secrets. Une URL invalide ou un schéma non pris en charge est ignoré avec un avertissement : confirme donc la configuration appliquée et une véritable récupération. Recrée le worker après avoir modifié son environnement. Redémarrer le conteneur existant ne recharge pas un `.env` modifié.

Changer de route ne garantit pas l’accès. Vérifie que l’usage du proxy et du compte source est autorisé pour le contenu nécessaire. Si la source reste indisponible, importe une transcription que tu possèdes déjà comme [document de connaissances](https://docs.tale.dev/fr/platform/knowledge/documents).

## Importer une session de navigateur autorisée

Le serveur peut utiliser les cookies d’un pool séparé par **organisation et domaine**. Il chiffre les fichiers de cookies avec `ENCRYPTION_SECRET_HEX` et ne les renvoie pas dans les listes. Ce pool appartient à l’ingestion vidéo côté serveur ; il n’exporte pas les cookies vers les scripts des agents.

Il n’existe pas de formulaire d’import dans l’application. L’écriture REST exige une clé dont l’utilisateur administre une organisation et figure dans `TALE_DEPLOYMENT_CONFIG_ADMINS`. La clé doit aussi résoudre l’organisation cible. `GET /api/v1/me` indique `capabilities.deploymentEditor` pour cette clé. Nomme explicitement l’organisation avec `X-Organization-Slug`, surtout si le compte en rejoint plusieurs.

1. Exporte un fichier de cookies au format Netscape depuis une session autorisée pour le domaine source. Traite-le comme des identifiants de compte et exclus-le du dépôt.
2. Définis `TALE_URL`, `TALE_API_KEY` et `TALE_ORG_SLUG` pour la bonne instance et organisation. Limite la lecture de `cookies.txt` au compte de l’opérateur.
3. Importe le fichier sans placer son contenu dans les arguments de commande :

```bash
jq -n --arg domain youtube.com --rawfile cookiesJar cookies.txt \
  '{domain: $domain, cookiesJar: $cookiesJar, label: "operator-managed session"}' |
  curl --fail-with-body -sS -X POST "$TALE_URL/api/v1/browser-sessions/import" \
    -H "Authorization: Bearer $TALE_API_KEY" \
    -H "X-Organization-Slug: $TALE_ORG_SLUG" \
    -H 'Content-Type: application/json' \
    --data-binary @-
```

Un import réussi renvoie HTTP 201 avec `sessionId`. Des données invalides provoquent un refus de validation ; un manque de permissions renvoie 403. Résous le contrôle indiqué plutôt que d’accorder un rôle plus large uniquement pour faire passer la requête.

## Vérifier et révoquer les sessions

```bash
curl --fail-with-body -sS "$TALE_URL/api/v1/browser-sessions" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG"
```

La liste présente les métadonnées : statut, expiration et nombre d’échecs. La durée par défaut est 14 jours ; l’import accepte un `ttlMs` positif jusqu’à 180 jours. Les cookies sources peuvent expirer avant : un enregistrement encore valide ne prouve pas que la session du compte fonctionne.

Une récupération bloquée met la session au repos ; des blocages répétés peuvent la retirer. Une tâche planifiée traite les sessions refroidies ou expirées. Une nouvelle tentative peut utiliser une autre session saine de la même organisation et du même domaine. Sans session disponible, la récupération peut continuer avec les autres options configurées.

Pour révoquer une session importée, utilise `DELETE /api/v1/browser-sessions/<sessionId>` avec le même périmètre d’organisation et les permissions d’écriture nécessaires. Confirme l’ID dans la liste auparavant. Renouvelle ou révoque aussi la session du compte source si ses cookies ont été exposés. Relance enfin une vidéo contrôlée et vérifie transcription puis indexation : importer les cookies ne prouve pas que l’ingestion a réussi.

# Héberger Tale sur ton infrastructure
Source: https://docs.tale.dev/fr/self-hosted

En hébergeant Tale, ton organisation choisit où l’application s’exécute, où les données sont stockées et quels modèles elle utilise. La plateforme open source offre les mêmes fonctionnalités que la version Enterprise. Ton équipe exploite l’infrastructure et décide quels services externes elle peut contacter.

Pour une première installation, suis le [démarrage local](https://docs.tale.dev/fr/self-hosted/install/quickstart) : installe la CLI publiée, lance `tale init`, puis `tale dev`. Le guide t’accompagne de la création du compte propriétaire à la première réponse dans le chat, en passant par la connexion du fournisseur. Docker exécute les services fournis ; aucun dépôt source ni outil de compilation n’est nécessaire. Si `doctor` figure dans `tale --help`, tu peux utiliser `tale doctor` pour vérifier ta machine avant de créer le projet.

## Choisir ton point de départ

| Ton objectif | Guide |
| --- | --- |
| Essayer une instance locale ou installer un nouvel environnement | [Démarrage de l’installation](https://docs.tale.dev/fr/self-hosted/install/quickstart) |
| Comprendre les services, les données et les connexions réseau | [Vue d’ensemble de l’architecture](https://docs.tale.dev/fr/self-hosted/overview) |
| Déployer avec tes propres définitions Compose ou Kubernetes | [Exploiter ton propre déploiement](https://docs.tale.dev/fr/self-hosted/install/own-compose) |
| Modifier le code de l’application | [Configurer l’environnement de développement](https://docs.tale.dev/fr/develop/contributor-setup) |
| Utiliser une instance déjà exploitée par une autre équipe | [Envoyer ton premier message](https://docs.tale.dev/fr/get-started/quickstart) |

## Répartir les responsabilités d’exploitation

Désigne les responsables des accès, de TLS, des mises à jour, des sauvegardes, de la surveillance et des incidents avant d’ajouter des utilisateurs. Configure un fournisseur d’IA. Pour rendre les documents interrogeables, prévois aussi un modèle d’embeddings et le stockage des connaissances. Teste un téléversement et une conversation complète avant de considérer l’instance comme prête.

L’auto-hébergement ne garantit pas que toutes les requêtes restent sur ton réseau. Un fournisseur de modèles, un Connector, un robot d’exploration ou un service de surveillance externe peut recevoir des données. Vérifie les destinations réelles à l’aide du guide de [renforcement de la sécurité](https://docs.tale.dev/fr/self-hosted/operate/security/hardening) et de la configuration des fournisseurs. Une installation isolée nécessite des images, modèles, identifiants et dépendances disponibles localement.

## Configurer et maintenir l’instance

La [référence des variables d’environnement](https://docs.tale.dev/fr/self-hosted/configuration/environment-reference) décrit les paramètres du déploiement. Les guides de configuration couvrent ceux de l’organisation. Consulte l’[architecture des conteneurs](https://docs.tale.dev/fr/self-hosted/operate/container-architecture) pour les dépendances d’exploitation et [Sauvegardes et restauration](https://docs.tale.dev/fr/self-hosted/operate/backups-and-restore) pour préparer une reprise.

Si ton équipe préfère confier l’exploitation à Tale, consulte [Tale Cloud](https://docs.tale.dev/fr/cloud). Les guides de la plateforme s’appliquent aux deux modes d’hébergement.

# Installer la CLI tale
Source: https://docs.tale.dev/fr/self-hosted/install/cli-install

La CLI `tale` permet d’installer Tale, de le déployer et d’en assurer l’exploitation. Installe-la sur la machine où tu exécuteras tes commandes, puis suis le [démarrage rapide en local](https://docs.tale.dev/fr/self-hosted/install/quickstart) ou la procédure de déploiement ci-dessous.

La même CLI gère les opérations du workspace sur les conteneurs, les déploiements depuis des commits source exacts et les releases de configuration client. Ton automatisation choisit la destination, les références et les références d’identifiants, puis appelle la CLI. [Publier les configurations d’un client](https://docs.tale.dev/fr/self-hosted/configuration/config-releases) traite les contenus conservés dans son propre repository.

Pour ta première instance, suis le [démarrage rapide](https://docs.tale.dev/fr/self-hosted/install/quickstart). Le parcours habituel est `tale init`, puis `tale dev`. Une spécification de déploiement géré n’est nécessaire que si ton automatisation doit fixer les commits source exacts du runtime et du client.

## Avant de commencer

Il te faut :

- Un ordinateur sous macOS, Linux ou Windows avec PowerShell.
- Pour les conteneurs en local : Docker avec Compose et un daemon Docker en cours d’exécution.
- Pour un workspace distant : l’accès à son daemon Docker, généralement par un contexte Docker SSH. Le compte utilisé sur l’hôte distant doit pouvoir exécuter Docker.

Le stockage objet fourni n’existe actuellement qu’en image `linux/amd64`. Sur un hôte ARM64, le développement local et les déploiements de workspace nécessitent donc une émulation amd64 fonctionnelle : Docker Desktop l’inclut ; sur un hôte Linux avec Docker autonome, [QEMU doit être enregistré sur l’hôte](https://docs.docker.com/build/building/multi-platform/#install-qemu-manually). Tale sélectionne l’image amd64, mais n’installe pas l’émulation. Les bundles de déploiement géré exigent toujours des images natives pour l’architecture déclarée. Un déploiement géré ARM64 doit donc attendre une image native du stockage objet.

L’installeur télécharge l’exécutable depuis GitHub. Il doit pouvoir joindre `raw.githubusercontent.com`, `api.github.com`, `github.com` et les destinations de téléchargement vers lesquelles GitHub le redirige.

## Lancer install-cli.sh ou install-cli.ps1

Sur macOS ou Linux :

```bash
curl -fsSL https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.sh | bash
```

Sur Windows PowerShell :

```powershell
irm https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.ps1 | iex
```

L’installeur Unix choisit l’exécutable adapté au système et au processeur. Par défaut, il remplace un exécutable `tale` déjà présent dans le `PATH`, ou l’installe dans `/usr/local/bin`. Il demande `sudo` seulement si l’écriture dans ce répertoire le nécessite. Sous Windows, il utilise `%LOCALAPPDATA%\Programs\tale` par défaut et ajoute ce répertoire au `PATH` de ton compte.

Des exécutables sont disponibles pour macOS avec Apple Silicon ou Intel, Linux x86_64 ou arm64, et Windows x64. Windows ARM nécessite l’émulation x64. Si une architecture Unix n’est pas prise en charge, l’installeur indique comment compiler depuis les sources.

Définis `VERSION` pour choisir une version précise et `INSTALL_DIR` pour changer le répertoire de destination. Dans un shell Unix, **exporte** ces variables avant de lancer le pipeline pour que le processus `bash` les reçoive. Une affectation placée uniquement avant `curl` ne les transmet pas à l’installeur. Dans PowerShell, utilise `$env:VERSION` et `$env:INSTALL_DIR`.

| OS      | Script d'installeur       |
| ------- | ------------------------- |
| macOS   | `scripts/install-cli.sh`  |
| Linux   | `scripts/install-cli.sh`  |
| Windows | `scripts/install-cli.ps1` |

## Vérifier

```bash
tale --version
```

La CLI affiche la version installée. Si la commande est introuvable, vérifie le répertoire indiqué par l’installeur et ajoute-le au `PATH`. Si un terminal Windows déjà ouvert ne trouve toujours pas `tale`, rouvre-le. Si le téléchargement échoue, vérifie l’accès aux destinations réseau ci-dessus. La variable d’environnement facultative `GITHUB_TOKEN` authentifie la recherche de version lorsque GitHub limite les appels anonymes à son API.

## Vérifier la configuration

Pour les commandes qui gèrent les conteneurs, utilise le workspace créé avec `tale init` dans le [démarrage rapide](https://docs.tale.dev/fr/self-hosted/install/quickstart). La CLI recherche `tale.json` dans le répertoire courant puis dans ses parents. Vérifie le projet sélectionné avant de le modifier :

```bash
tale config show
```

Les releases de configuration et les [déploiements gérés](https://docs.tale.dev/fr/self-hosted/install/cli-install#managed-deployments) désignent explicitement sources et destinations, sans s’aligner sur un workspace voisin. `config show` garde son comportement existant pour les projets locaux.

Pour un déploiement de workspace, l’hôte du proxy, les réglages TLS et les secrets vivent dans son `.env`. Pour la production, modifie `HOST` ou passe `--host` à `tale deploy`. En local, `tale dev` utilise `localhost` par défaut ; ses options `--host` et `--port` ne valent que pour cette exécution. Pour un workspace distant, utilise le contexte Docker de ton shell ou `DOCKER_HOST`. Un bundle géré s’applique sur la destination déclarée avec son daemon Docker local.

## Lancer tale deploy

```bash
tale deploy
```

Sans `--bundle`, `tale deploy` déploie la version de la CLI : il récupère ses images, redémarre les conteneurs concernés dans l’ordre prévu et exécute les migrations. Choisis auparavant une autre version de workspace avec `tale update`. Pour des commits source distincts du runtime et du client, suis [Déploiements gérés](https://docs.tale.dev/fr/self-hosted/install/cli-install#managed-deployments).

## Référence des commandes

La CLI regroupe ses commandes selon ce que tu fais, comme le fait `tale --help`. Chaque commande et ses arguments sont listés ci-dessous. Comment lire la notation :

- Un argument positionnel entre `[crochets]` est **optionnel** ; entre `<chevrons>`, il est **requis**.
- Les options obligatoires des releases de configuration sont indiquées explicitement ; les autres options sont facultatives, sauf indication contraire dans l’aide de la commande.
- Une option de la forme `--option <valeur>` **exige une valeur** quand tu l'utilises (p. ex. `--port 8443`) ; une option seule comme `--detach` est un commutateur booléen.
- Les **valeurs par défaut** figurent entre parenthèses après la description. Aucune valeur par défaut signifie que l'option est désactivée, ou que la valeur est résolue depuis `.env` / le contexte.

Cette référence décrit aussi les commandes du code source actuel. La CLI publiée en version v0.5.70 ne contient ni `tale doctor` ni `tale dev --stop`. Consulte `tale --help` et `tale <commande> --help` pour connaître les commandes et options disponibles dans ta version installée.

**Les options globales** fonctionnent sur chaque commande :

- `--verbose` — sortie détaillée : logs de débogage et flux brut du sous-processus (forme longue uniquement ; il n'y a pas de `-v`).
- `-q, --quiet` — uniquement les avertissements et les erreurs.
- `-y, --yes` — répondre « oui » à toutes les questions (non interactif).
- `--no-color` — désactiver les couleurs ANSI (respecte aussi `NO_COLOR` / `FORCE_COLOR`).
- `--json` — JSON lisible par machine sur stdout ; pris en charge par `doctor`, `status`, `sandbox status`, toutes les sous-commandes `config` et les commandes de déploiement géré.
- `--ci` — forcer une sortie non interactive en mode ajout seul (sans contrôle du curseur).

Les commandes se terminent avec `0` en cas de succès, `2` pour une erreur d'utilisation, `3` pour une condition préalable non remplie (pas de projet, Docker arrêté, port occupé), `4` pour une interruption par l'utilisateur (Ctrl-C, ou une question requise sans terminal) et `5` pour l'échec d'une dépendance externe — ainsi les scripts peuvent se ramifier selon la cause.

### Installation

`tale doctor` — examine les prérequis d’un démarrage local sans créer de projet, installer de logiciel ni modifier la configuration. La commande vérifie le daemon Docker, la prise en charge de Compose et le mode de conteneurs Linux, indique l’architecture du daemon et examine les ports locaux. Avec un contexte Docker distant, elle ignore les ports locaux. Examine les avertissements sur ARM64 et les ports occupés ; une instance existante peut déjà utiliser le port.

- `-p, --port <port>` — port HTTPS à vérifier (par défaut `443`) ; le port sandbox `8003` est aussi vérifié.
- `--json` — produit les résultats en JSON lisible par machine.

Un échec lié à Docker, Compose, à un mode de conteneurs non pris en charge ou au choix du port HTTPS `8003` renvoie le code `3`. Les avertissements seuls renvoient `0` ; cela ne vérifie ni les téléchargements d’images, ni la capacité de stockage, ni le fournisseur de modèles. Vérifie un autre port avec `tale doctor --port 8443`, puis utilise le même port avec `tale dev`.

`tale init [directory]` — créer un projet : crée les configs d'exemple, `AGENTS.md` + un pointeur `CLAUDE.md` et un `.env` local par défaut (localhost, certificat auto-signé, secrets générés). Aucun Docker requis ; le domaine de production et le TLS sont choisis plus tard, lors de `tale deploy`. Dans un terminal, il demande un nom de projet quand `directory` est omis, confirme avant d'écraser un projet existant, et demande une fois si les agents peuvent lancer `docker` dans les sandboxes (par défaut : non — l'activer fait tourner un Docker interne privilégié) ; les exécutions non interactives sautent toutes les questions. `directory` est optionnel (par défaut : le répertoire courant).

- `-f, --force` — écraser un `tale.json` existant au lieu d'abandonner.
- `--no-env` — créer le projet mais ignorer la génération du `.env`.

`tale dev` — démarrer tous les services localement avec un certificat auto-signé. L’hôte et le port choisis définissent l’adresse locale de l’application pour cette exécution, sans réécrire les réglages de production dans `.env`. La vérification attend que les services dotés de sondes de santé soient sains et que les autres soient en cours d’exécution. Si le délai est dépassé, consulte les logs des services signalés avant de réessayer.

- `-d, --detach` — s'exécuter en arrière-plan au lieu de diffuser les logs.
- `--stop` — arrête les conteneurs locaux de développement de ce projet et conserve leurs données. Relance `tale dev` pour reprendre.
- `-p, --port <port>` — port HTTPS à exposer (par défaut `443`).
- `--host <hostname>` — alias d'hôte pour le proxy (par défaut `localhost`).
- `-y, --yes` — non-interactif : accepter automatiquement les invites (p. ex. installer ou démarrer Docker).

`tale deploy` — déployer la version de la CLI avec remplacement blue-green des rôles applicatifs. Les services d’exécution partagés sont remplacés sur place ; la base et le proxy nécessitent `--stop`. Au premier déploiement, la CLI demande domaine public et e-mail TLS s’ils ne sont pas fournis. Consulte [Mises à jour](https://docs.tale.dev/fr/self-hosted/operate/upgrades) avant de modifier une installation existante.

- `--stop` — mettre aussi à jour le palier arrêté-puis-recréé (`db`, `proxy`) — ces conteneurs sont recréés, donc accepte une brève interruption ; sans l'option, les `db`/`proxy` en marche restent intouchés.
- `-s, --services <list>` — ne mettre à jour que ces services séparés par des virgules (par défaut : tous les services rotatifs).
- `--host <hostname>` — alias d'hôte pour le proxy (par défaut : la valeur `HOST` de `.env`).
- `--override` — écraser la config du conteneur depuis le workspace local (les `*.secrets.json` chiffrés et `.history/` sont toujours préservés).
- `--override-all` — réinitialiser le catalogue intégré dans chaque organisation côté serveur ; implique `--stop`.
- `-q, --quiet` — masquer les logs des conteneurs pendant le déploiement.
- `-y, --yes` — accepter automatiquement les confirmations destructives (p. ex. `--override-all`).
- `--skip-backup` — ignorer le snapshot de volume automatique d'avant déploiement.
- `--dry-run` — prévisualiser sans rien modifier.

### Déploiements gérés {#managed-deployments}

Utilise une déclaration de déploiement vérifiée quand le runtime et les configurations client doivent suivre des commits source exacts. Ton automatisation choisit la destination, les identifiants et les références, puis appelle la CLI Tale. Celle-ci acquiert les sources, résout et vérifie les digests des images, prépare le transfert, préserve l’état existant pris en charge, crée les snapshots de récupération nécessaires, déploie la stack, provisionne l’instance native et vérifie la configuration. Cette logique de déploiement reste dans Tale.

#### Préparer le runtime et les références source

Lance la préparation sous Linux avec une CLI compilée depuis un checkout Tale propre et committé, pour l’architecture cible `linux/amd64` ou `linux/arm64`. Le même exécutable accompagne le paquet pour le provisionnement local au backend. La préparation demande Git et Docker pour vérifier sources et images. L’application s’exécute sur la destination avec son daemon Docker local, son répertoire d’état conservé et son environnement. Le commit complet de CLI, le commit source du runtime et celui de la configuration client sont trois références distinctes. Sur la destination, le runtime préparé ne publie que les ports 80 et 443 du proxy et les deux bases de données sur `127.0.0.1:5432` et `127.0.0.1:5433` ; le spawner sandbox (8003) et son hub d’appareils (8004) restent sur le réseau interne, où le backend et le proxy les joignent.

Un déploiement géré consigne son point de récupération avant de modifier quoi que ce soit : le snapshot pris avant le déploiement et le bundle en cours d’application, conservés dans le répertoire d’état jusqu’à l’écriture du reçu ready. Un déploiement interrompu attend donc le même bundle à la reprise et en refuse un autre, en nommant le sha256 du bundle en attente. Quand ce bundle ne peut plus aboutir — parce qu’une CLI corrigée est désormais épinglée, par exemple —, déclare le sha256 nommé comme `supersedesPendingBundle` dans la déclaration de déploiement et relance la préparation : le bundle vérifié reprend le même snapshot, le reçu ready le liste sous `supersededBundles`, et tu retires ensuite la déclaration. Cette reprise couvre le point de récupération du déploiement, pas le déploiement du runtime lui-même. Un déploiement du runtime arrêté après la vérification de ses images — au démarrage de Compose ou pendant l’attente des contrôles de santé — ne reprend qu’avec le même runtime préparé (`runtime/runtime.json`), la même origine, les mêmes réglages TLS et le même environnement ; il refuse un bundle dont le runtime ou les réglages diffèrent, avec ou sans `supersedesPendingBundle`, par `A different runtime operation is pending; recover that exact operation first.` Termine-le avec le bundle qui l’a lancé avant de changer la CLI épinglée, dans un sens comme dans l’autre : une autre CLI peut préparer un runtime différent à partir du même commit de runtime. Les phases locales au backend (`deploy provision`, `deploy export-client-native`) s’exécutent dans le backend sous son propre utilisateur, propriétaire de son répertoire de données ; quand l’une échoue, le résultat du déploiement reprend le résumé de la CLI interne.

Le snapshot pris avant le déploiement contient aussi le stockage de la passerelle de modèles, `llm-gateway-data`, qu’une passerelle plus récente migre sans retour possible dès son premier démarrage sur ce stockage. Un déploiement en attente qui n’a rien modifié ne consigne aucun snapshot ; une reprise par `supersedesPendingBundle`, ou une nouvelle tentative qui modifie le runtime, prend d’abord le snapshot et le consigne avec le déploiement en attente. Un point de récupération sans le stockage de la passerelle (un snapshot pris avant que la CLI capture ce stockage, ou aucun après une reprise par une CLI plus ancienne) bloque tout déploiement qui démarrerait une image de passerelle que ce stockage n’a jamais fait tourner d’après le reçu du runtime et le conteneur de la passerelle : l’application du bundle est refusée avant toute modification et le reçu en attente reste tel quel, car un snapshot pris maintenant pourrait déjà contenir un stockage migré. Ne supprime pas le reçu. Tant qu’aucun déploiement du runtime n’est en attente, un bundle vérifié qui résout encore l’image de passerelle exécutée en dernier par le déploiement peut le reprendre avec `supersedesPendingBundle` ; le déploiement suivant prend un snapshot qui contient le stockage de la passerelle. Dès qu’un déploiement du runtime est en attente, la CLI n’offre aucune issue pour cet état. Un déploiement sur une image de passerelle déjà exécutée sur ce stockage aboutit, et signale quand son snapshot ne contient pas le stockage ou qu’il n’a aucun point de récupération. Un déploiement géré ne revient jamais en arrière de lui-même et ne restaure aucun volume ; il conserve son état en attente pour la récupération.

Les commandes de bundle géré ne sont pas disponibles sous Windows, y compris `deploy verify-bundle` et le `deploy provision` local au backend : leurs contrôles d’intégrité exigent les droits d’exécution POSIX. Exécute le déploiement géré complet sur un hôte Linux. Les commandes ordinaires du workspace et les commandes autonomes `config build`, `verify`, `stage`, `deploy` et `verify-native` restent disponibles sous Windows.

Cet exemple synthétique cible une organisation et un projet existants. Remplace les ID publics et définis les variables nommées. `revision` accepte un SHA de commit complet ou une référence d’environnement. Les identifiants restent des références, résolues en privé sur la destination. `tlsMode: "external"` suppose qu’un point d’entrée existant gère le TLS public ; `letsencrypt` demande aussi `tlsEmail`.

Pour les jobs Linux ou macOS ARM64 de GitHub Actions, utilise l’action composite Tale `.github/actions/setup-cli`. Fixe l’action et `revision` au même commit Tale complet. Elle compile avec Bun 1.4.2, vérifie le binaire final, fournit `executable` et complète le `PATH`. Les builds macOS prennent en charge la préparation générale de configuration ; la pile Linux gérée exige toujours un binaire Linux correspondant. Sur un runner Linux x64, passe `linux-baseline: 'true'` quand le processeur cible n’a pas AVX2 (Intel avant Haswell, par exemple). Le binaire standard s’y arrête sur `Illegal instruction`, le binaire baseline fonctionne. Les autres runners refusent cette option.

`origin` et chaque entrée native `redirectUris` acceptent aussi des références d’environnement. Un registre de déploiement peut ainsi posséder les adresses publiques. La préparation les résout en URL HTTPS littérales validées dans le bundle.

L’exemple définit `runtime.containerPrefix` pour rendre l’environnement reconnaissable dans la liste des conteneurs. Cette option est expliquée ci-dessous.

```json
{
  "schemaVersion": 1,
  "name": "example-native",
  "stateDirectory": "/opt/tale-example",
  "composeProject": "tale-example",
  "runtime": {
    "revision": { "env": "TALE_RUNTIME_REF" },
    "platform": "linux/amd64",
    "containerPrefix": "north-desk-prod"
  },
  "origin": { "env": "TALE_PUBLIC_ORIGIN" },
  "tlsMode": "external",
  "identity": {
    "email": { "env": "EXAMPLE_OPERATOR_EMAIL" },
    "password": { "env": "EXAMPLE_OPERATOR_PASSWORD" },
    "slug": "example-team",
    "name": "Example team",
    "ssoEnabled": false,
    "nativeClients": [
      {
        "key": "example-portal",
        "name": "Example portal",
        "clientId": { "env": "EXAMPLE_NATIVE_CLIENT_ID" },
        "redirectUris": [{ "env": "EXAMPLE_PORTAL_CALLBACK" }]
      }
    ]
  },
  "configs": [
    {
      "repository": "https://github.com/example-team/client-app",
      "revision": { "env": "EXAMPLE_CONFIG_REF" },
      "client": "example-team",
      "descriptor": "tale/client.json",
      "automation": "document-review",
      "projectId": "existing-project-id",
      "skillOwner": "native-operator-id"
    }
  ]
}
```

#### Choisir l’environnement des rapports d’erreurs

Les instances gérées définissent `SENTRY_ENVIRONMENT` sur le `name` existant du déploiement par défaut. Pour utiliser un libellé canonique comme `example-pr`, déclare `"environment": { "SENTRY_ENVIRONMENT": { "env": "TALE_REPORTING_ENVIRONMENT" } }` et définis cette variable à destination. Le libellé commence par une lettre minuscule ou un chiffre et contient de 1 à 64 lettres minuscules, chiffres ou traits d’union. Le navigateur, le backend et la sandbox l’utilisent sans modifier `name`, `composeProject`, `stateDirectory` ni les identifiants enregistrés.

#### Choisir les noms des conteneurs

Définis `runtime.containerPrefix` pour obtenir des noms comme `north-desk-prod-db` et `north-desk-prod-backend-api` dans la liste des conteneurs. Le préfixe commence par une lettre minuscule et contient des lettres minuscules, des chiffres et des traits d’union simples, sur 40 caractères au maximum. Les espaces, les traits de soulignement, les traits d’union répétés et un trait d’union final sont refusés.

| Paramètre | Ce qu’il identifie |
| --- | --- |
| `runtime.containerPrefix` | Le nom visible de chaque conteneur géré : `<prefix>-<service>`. |
| `name` et `composeProject` | Le déploiement existant et son projet Compose, y compris l’appartenance des volumes. |
| `stateDirectory` | L’état du déploiement, les identifiants et les traces nécessaires à la reprise. |

Garde les valeurs des deux dernières lignes lorsque tu renommes les conteneurs d’une installation existante. Le préfixe ne modifie pas les noms DNS des services : leurs adresses internes conservent donc les mêmes noms. Sans préfixe, la convention de nommage du code source s’applique.

Ajouter, modifier ou retirer un préfixe recrée les conteneurs et peut interrompre brièvement le service. Prépare un nouveau bundle, examine sa simulation, puis applique-le en suivant la procédure habituelle de snapshot et de reprise. Si l’application est interrompue, relance exactement ce bundle ; un déploiement en attente refuse un autre bundle. Une fois le déploiement terminé, tu peux retirer le préfixe avec un autre bundle préparé pour rétablir la convention du code source.

Exécute une seule instance gérée complète par démon Docker. Un préfixe de nom n’attribue pas de ports, de réseaux sandbox ou de répertoires de travail distincts sur l’hôte.

#### Servir des origines supplémentaires {#managed-additional-origins}

Déclare `additionalOrigins` lorsque la même instance doit aussi répondre sur d’autres origines HTTPS, par exemple un domaine partenaire ou l’ancien nom d’hôte pendant un déménagement. Chaque entrée est une origine HTTPS nue sur le port par défaut, ou une référence d’environnement que la préparation résout en une telle origine. La liste compte de 1 à 16 origines distinctes ; aucune ne peut reprendre `origin`.

```json
{
  "origin": "https://desk.example.org",
  "additionalOrigins": [
    "https://desk.partner.example",
    { "env": "TALE_EXTRA_ORIGIN" }
  ]
}
```

La CLI écrit la liste dans la variable `ADDITIONAL_SITE_URLS` du runtime et la gère elle-même : une entrée de `environment` ne peut donc pas la définir. Chaque origine est un point d’entrée complet, avec ses propres sessions, liens de fichiers, accès de connexion et callbacks de connecteurs. Avec `tlsMode: "letsencrypt"`, le proxy obtient un certificat pour chaque origine, et les noms d’hôte locaux ou les adresses IP sont refusés. Avec `tlsMode: "external"`, ton proxy TLS doit transmettre l’en-tête `Host` d’origine de chaque origine et envoyer `X-Forwarded-Proto: https` depuis une adresse à laquelle le proxy de Tale fait confiance. Si cette plage est plus étroite que les plages d’adresses privées, définis `TRUSTED_PROXIES` par une référence dans `environment`.

L’identité native reste sur `origin` : les liaisons du compte et de l’organisation, les journaux des clients, l’émetteur OIDC, les passkeys et les liens envoyés par e-mail n’utilisent que celle-ci. Une entrée peut être égale à `identity.migrateOriginFrom` pour que l’ancien nom d’hôte continue de répondre pendant une migration.

La préparation refuse une révision du runtime dont le proxy ne peut pas faire confiance à un terminateur TLS externe, avec le message `Runtime does not serve additional origins`. Ajouter, modifier ou retirer la liste recrée les services qui la lisent. Une fois la déclaration retirée, le bundle appliqué suivant supprime aussi la variable. Enregistre les URL de callback de chaque origine auprès de tes fournisseurs d’identité et de connecteurs, et prépare le DNS et les certificats avec [TLS et domaines](https://docs.tale.dev/fr/self-hosted/configuration/tls-and-domains#plusieurs-domaines-a-la-fois).

#### Désigner qui peut créer des organisations {#managed-organization-creators}

Un déploiement géré refuse la création d’organisations à son proxy pour tout le monde : le choix d’organisation n’affiche pas d’entrée **Créer une organisation**, et `POST /api/auth/organization/create` répond 403. Pour que des personnes désignées puissent ouvrir d’autres espaces de travail, déclare `organizations.creators` — de 1 à 64 adresses de connexion distinctes, littérales ou sous forme de références d’environnement que la préparation résout.

```json
{
  "organizations": {
    "creators": ["ops@example.org", { "env": "TALE_WORKSPACE_LEAD" }]
  }
}
```

La CLI écrit la liste dans la variable `TALE_ORGANIZATION_CREATORS` du runtime et la gère elle-même : une entrée de `environment` ne peut donc pas la définir. Une fois la déclaration en place, le proxy ne refuse plus la création d’organisations ; c’est le backend qui compare chaque personne à la liste, répond `403 ORGANIZATION_CREATION_FORBIDDEN` à toutes les autres, et l’application n’affiche **Créer une organisation** qu’aux personnes désignées. Les adresses sont comparées sans tenir compte de la casse ; deux graphies d’une même adresse sont refusées comme doublon.

L’organisation gérée elle-même n’est pas concernée : le déploiement la crée pendant le bootstrap, et la première organisation d’un déploiement est toujours autorisée. Retire la déclaration et applique le bundle suivant pour rétablir le refus au proxy et supprimer la variable. La même variable fonctionne sur un déploiement que tu exploites toi-même ; voir la [référence des variables d’environnement](https://docs.tale.dev/fr/self-hosted/configuration/environment-reference).

#### Préparer, vérifier et appliquer le bundle

Définis `TALE_DEPLOY_SPEC` avec ce fichier JSON, `TALE_DEPLOY_BUNDLE` avec un nouveau répertoire absolu et `TALE_CLI_COMMIT` avec le commit complet du binaire. `DEPLOYMENT_COMMIT` est une provenance d’orchestration optionnelle ; omets ses arguments si tu ne l’utilises pas. Prépare et vérifie, transfère le répertoire entier, puis lance l’aperçu et le déploiement sur la destination avec la même CLI fixée.

```bash
tale --json deploy prepare \
  --spec "$TALE_DEPLOY_SPEC" \
  --deployment-ref "$DEPLOYMENT_COMMIT" \
  --output "$TALE_DEPLOY_BUNDLE"

tale --json deploy verify-bundle \
  --bundle "$TALE_DEPLOY_BUNDLE" \
  --cli-ref "$TALE_CLI_COMMIT" \
  --deployment-ref "$DEPLOYMENT_COMMIT"

tale --json deploy --bundle "$TALE_DEPLOY_BUNDLE" \
  --cli-ref "$TALE_CLI_COMMIT" \
  --deployment-ref "$DEPLOYMENT_COMMIT" --dry-run

tale --json --yes deploy --bundle "$TALE_DEPLOY_BUNDLE" \
  --cli-ref "$TALE_CLI_COMMIT" \
  --deployment-ref "$DEPLOYMENT_COMMIT"
```

`deploy prepare` accepte `--sources-file <file>` pour associer `repository@fullSHA` à des checkouts exacts existants. Sinon, la CLI récupère des repositories GitHub canoniques. Injecte le contenu d’une clé SSH en lecture seule pour les repositories client privés dans `TALE_SOURCE_SSH_KEY`, uniquement pendant la préparation. La CLI vérifie les clés d’hôte SSH de GitHub par HTTPS et garde la clé hors du paquet et du runtime. Docker doit déjà avoir accès au registre.

La préparation vérifie d’abord chaque configuration avec les schémas propres à la CLI, et seulement ensuite télécharge et vérifie les images du runtime. Elle nomme chaque phase et chaque image au fur et à mesure. Un paquet qui déclare des champs inconnus de cette CLI est refusé en quelques secondes avec `native manifest normalization changes release semantics at <fields>` ; prépare-le alors avec une CLI au moins aussi récente que le Tale visé par le paquet. Une erreur que la CLI lève délibérément affiche sa propre cause. Toute autre erreur garde un résumé fixe, afin qu’aucun identifiant ni aucune sortie du registre n’atteigne le journal.

`deploy verify-bundle` vérifie l’inventaire complet et les hashes sans contacter la destination. `deploy --bundle --dry-run` vérifie les artefacts de configuration et les préconditions de la destination sans appliquer de changement. Les déploiements gérés refusent les options réservées au workspace comme `--services`, `--host` ou `--override-all`. Ils déploient la stack en préservant son état, avec des contrôles de santé et de provenance. Le comportement blue-green du workspace décrit plus haut est un autre parcours.

#### Configurer l’identité native

`deploy provision [--bundle <directory>]` est la phase locale au backend du déploiement du bundle. Elle lit au maximum 64 KiB de JSON privé sur stdin, vérifie le compte local et l’organisation sélectionnée, puis ferme la session avant d’annoncer le succès. Ses champs comprennent `origin`, `email`, `password`, `slug`, `name`, `ssoEnabled`, les identifiants Entra optionnels et `nativeClients`. Par défaut, le compte existant reste requis. Un `identity.bootstrap: "fresh"` explicite autorise la création du premier compte local et de l’organisation. Un bundle lie ce choix et les configurations préparées avant toute modification native. `deploy provision` refuse les options de workspace et `--dry-run` ; utilise les vérifications en lecture seule. Les attentes optionnelles `--cli-ref` et `--deployment-ref` exigent `--bundle` et sont contrôlées avant connexion.

Pour un nouvel opérateur vérifié administrativement, déclare explicitement `identity.emailVerification: "operator-attested"`. Tu attestes ainsi la possession de l’adresse du compte authentifié ; ce n’est pas une preuve de livraison dans la boîte mail. Le backend utilise un jeton natif bref lié à ce compte et à cette adresse exacte, en conservant les hooks natifs. Il n’envoie aucun email, ne change pas l’adresse et ne crée pas d’autre session. Cette option exige `bootstrap: "fresh"`. Sans elle, la vérification native habituelle reste inchangée. Une dérive du statut vérifié d’un compte précédemment prêt bloque pour examen.

Pour une nouvelle cible, remplace le `projectId` d’une configuration par `project: { "key": "NORTH", "name": "Configuration" }`. Une clé de projet natif compte 2–6 lettres majuscules, son nom au plus 80 caractères. `skillOwner: "operator"` transfère une capsule source vérifiée et la compile dans le backend pour l’utilisateur natif authentifié ; l’hôte vérifie indépendamment l’artefact obtenu. Les ID explicites existants et les versions déjà liées à leur propriétaire conservent leur comportement.

Chaque client natif choisit un `clientId` existant ou `managed: true` explicite. Avant la création native, la CLI conserve une intention privée, puis renvoie seulement un chemin privé de transmission et le SHA des identifiants. Les répétitions gardent ID, politique de sécurité et secrets. Une acceptation incertaine sans objet natif correspondant bloque. Pour les clients existants, seuls le nom affiché et les URL de callback HTTPS peuvent converger. Sur les backends 0.5 pris en charge, les créations ou modifications nécessaires utilisent des adaptateurs d’authentification locaux fixes, dont les connexions sont ensuite fermées. Cela n’ouvre aucune route publique d’inscription ou de modification, aucun chemin de module arbitraire et aucune rotation de secret.

#### Changer le nom d’hôte d’un déploiement géré {#managed-origin-migration}

Utilise le déploiement géré existant et son répertoire d’état privé. Ce parcours modifie l’origine associée au compte, à l’organisation et aux clients existants ; il ne déplace pas la base de données et ne crée pas de nouvelles identités.

1. Définis la nouvelle origine HTTPS dans `origin` de la spécification et l’origine HTTPS précédente exacte dans `identity.migrateOriginFrom`, par exemple `https://old.example.org`. Elles doivent être différentes. Conserve `identity.bootstrap: "fresh"`, le compte, l’organisation et les clés des clients gérés.
2. Vérifie l’état conservé avant de préparer le bundle. L’initialisation doit être terminée. Chaque attestation d’e-mail déclarée et chaque client géré nécessitent leur journal correspondant terminé. Un journal d’identité ou de client absent, en attente ou sans rapport avec la cible bloque la migration.
3. Prépare et vérifie le bundle, examine l’aperçu, puis applique-le avec le parcours décrit plus haut. La CLI authentifie le compte existant et vérifie les identifiants client avant de modifier les origines associées. Une nouvelle tentative accepte les journaux terminés sur l’une ou l’autre origine déclarée, en conservant les IDs et les secrets.
4. Une fois le reçu de déploiement prêt, exporte la configuration des applications clientes pour le nouvel émetteur. Retire `migrateOriginFrom` des prochaines spécifications de déploiement.

Si une configuration native est déclarée, son reçu conservé est également nécessaire. La migration garde l’ID et le slug de l’organisation et vérifie chaque ressource avec le parcours habituel de planification et de relecture. Une écriture de configuration interrompue sur la nouvelle origine reprend uniquement son plan exact en attente. Un reçu de configuration en attente sur l’ancienne origine bloque la migration.

Pour revenir en arrière après une migration terminée, inverse explicitement les deux origines et reprends le même parcours vérifié. Prépare le DNS, les certificats, les URL de rappel et les tests d’accès avec [TLS et domaines](https://docs.tale.dev/fr/self-hosted/configuration/tls-and-domains). Changer l’origine dans le bundle n’effectue pas ces opérations externes.

#### Renommer l’adresse de l’opérateur de déploiement {#managed-operator-address-migration}

Un déploiement géré se connecte à chaque exécution en tant qu’opérateur `identity`. Pour donner à ce compte une adresse machine, afin que les personnes se connectent avec leurs propres comptes, conserve le compte et ne change que son adresse de connexion. Son identifiant utilisateur, et tout ce qui en dépend — clients gérés, skills appartenant à l’opérateur, clés d’API et journaux conservés —, reste inchangé.

1. Définis `identity.email` sur la nouvelle adresse et `identity.migrateEmailFrom` sur l’adresse précédente exacte. Les deux doivent être différentes. Conserve `identity.bootstrap: "fresh"` et le mot de passe du compte. Le bootstrap doit être terminé, et une attestation d’e-mail déclarée a besoin de son journal terminé.
2. Prépare, vérifie, prévisualise et applique le bundle. La CLI lit l’adresse actuelle du compte conservé dans le backend, se connecte avec elle et prouve l’identifiant utilisateur conservé. Elle consigne le changement dans le journal, renomme le compte via l’adaptateur natif, met fin à toutes les sessions du compte et se reconnecte avec la nouvelle adresse. Le renommage est conditionné à l’adresse précédente : un changement concurrent est refusé au lieu d’être écrasé. Une attestation d’e-mail déclarée vérifie ensuite la nouvelle adresse.
3. Une nouvelle tentative après une interruption trouve l’adresse déjà changée et termine les journaux sans second renommage. Laisser `migrateEmailFrom` déclaré ensuite est sans effet ; retire-le une fois le reçu de déploiement prêt.

Si un autre compte détient la nouvelle adresse, si le compte conservé ne détient aucune des deux adresses, ou si le compte de l’opérateur porte un lien d’authentification unique (SSO), le déploiement s’arrête avant toute modification. Retire d’abord un tel lien : il appartient à la personne qui s’est connectée avec, pas à un compte machine.

#### Déclarer un administrateur de secours {#managed-break-glass}

`identity.breakGlass` conserve un administrateur pour le cas où l’opérateur de déploiement est indisponible, par exemple `{ "email": "break-glass@example.org", "passwordHash": { "env": "TALE_BREAK_GLASS_PASSWORD_HASH" } }`. L’adresse est une valeur littérale ou une référence d’environnement obligatoire, et doit différer de l’adresse actuelle et de l’adresse précédente de l’opérateur. Le mot de passe n’atteint jamais le déploiement : crée son hachage avec `tale auth hash-password` là où le mot de passe est conservé, et ne fournis que le hachage.

Chaque déploiement aligne le backend sur la déclaration. Un compte absent est créé avec une adresse vérifiée et exactement les identifiants déclarés, et un journal conservé lie l’adresse à son identifiant de compte dès que le compte existe. Les déploiements suivants rétablissent les identifiants déclarés sur le compte lié et mettent fin à toutes ses sessions dès que ces identifiants changent, y compris lorsqu’ils terminent une exécution interrompue. Un compte à cette adresse que ce déploiement n’a pas créé, ou plus tard un autre compte qui la détient, arrête le déploiement. Le compte devient `admin` de l’organisation gérée via les points d’accès natifs des membres ; un `owner` n’est jamais modifié. Le déploiement ne se connecte jamais avec ce compte. Change son mot de passe en modifiant le hachage déclaré, pas dans l’application. Le déploiement n’enregistre aucune date de changement de mot de passe : une politique de rotation des mots de passe de l’organisation peut donc demander un nouveau mot de passe à ce compte, que le déploiement suivant rétablit.

#### Connexion à deux facteurs imposée

Un déploiement géré se connecte en tant qu’opérateur avec le seul mot de passe. Si l’organisation impose `two_factor_policy`, donne à l’opérateur un passkey et jamais d’application d’authentification : la connexion par mot de passe d’un compte doté d’une application d’authentification reçoit une demande de code, et un compte sans aucun des deux facteurs est renvoyé vers la configuration à la fin de sa période de grâce. La CLI s’arrête à l’une ou l’autre réponse et nomme celle qu’elle a reçue. Les personnes se connectent avec leurs propres comptes et peuvent utiliser l’un ou l’autre facteur.

#### Exporter les identifiants des clients natifs

Pour transmettre les identifiants d’un client géré à une application distincte, définis `NATIVE_CLIENT_KEY` avec sa clé déclarée et `PRIVATE_EXPORT_DIRECTORY` avec un nouveau répertoire privé. Son répertoire parent doit déjà appartenir à ton compte, avoir le mode `0700` et se trouver sous des répertoires de confiance. Exporte depuis le même déploiement prêt, sans interpréter les chemins du backend ni les noms de conteneurs :

```bash
tale --json deploy export-client --bundle "$TALE_DEPLOY_BUNDLE" \
  --client "$NATIVE_CLIENT_KEY" --output "$PRIVATE_EXPORT_DIRECTORY" \
  --env-prefix TALE_OIDC --cli-ref "$TALE_CLI_COMMIT" \
  --deployment-ref "$DEPLOYMENT_COMMIT"
```

Le répertoire de sortie a le mode `0700`. Ses fichiers réguliers `client.json`, `receipt.json` et, avec `--env-prefix`, `consumer-env.json` ont le mode `0600`. Le dernier contient quatre chaînes littérales : `TALE_OIDC_ISSUER`, `TALE_OIDC_CLIENT_ID`, `TALE_OIDC_CLIENT_SECRET` et `TALE_OIDC_ORG_SLUG`. L’issuer correspond à l’origine Tale suivie de `/api/auth`. Transfère ces octets par ton canal privé d’identifiants et fais lire le JSON par l’application ; ne charge pas le fichier comme script shell et ne le publie pas comme artefact CI. Stdout contient uniquement des métadonnées non sensibles, chemins, tailles et hashes. Une sortie identique n’est réutilisée qu’après vérification de l’état prêt actuel et de tous les artefacts. Une sortie partielle, périmée ou étrangère bloque sans écrasement.

### Configurer la plateforme

Utilise `tale config` pour gérer les paramètres existants de la plateforme via les API natives. Enregistre cette déclaration dans `configuration.json` pour définir la couleur d’accent et un délai d’inactivité de 45 minutes :

```json
{
  "schemaVersion": 1,
  "resources": [
    {
      "kind": "branding",
      "config": {
        "accentColor": "#336699"
      }
    },
    {
      "kind": "governance",
      "key": "session_idle_timeout",
      "config": {
        "enabled": true,
        "idleTimeoutMinutes": 45
      }
    }
  ]
}
```

Définis `TALE_URL` avec l’origine HTTPS de l’instance et `TALE_ORG_ID` avec l’ID natif de l’organisation. Fournis un cookie de session autorisé via `TALE_CONFIG_COOKIE` ; garde-le hors des arguments et des fichiers versionnés. Valide localement, enregistre et examine le plan, puis applique-le et compare l’état natif :

```bash
tale --json config validate --file configuration.json
tale --json config plan --file configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID" --output configuration-plan.json
tale --json --yes config apply --file configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID" \
  --plan configuration-plan.json --receipt configuration-receipt.json
tale --json config read --file configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID"
```

Les répertoires de sortie et de reçus doivent déjà exister. Une connexion HTTP sur loopback exige aussi `--origin` avec l’origine HTTPS publique. `read` indique `matches` pour chaque ressource déclarée. Le plan précise la portée, les hashes actuels et souhaités, ainsi que les effets natifs. L’application exige la déclaration et la cible exactes. Une modification native concurrente bloque l’écriture. Les ressources non déclarées restent en place. La CLI ne propose ni suppression ni écriture de fichier arbitraire.

Ces types de ressources utilisent les schémas partagés et les permissions natives de la plateforme :

| Type                  | Configuration                                                   | Portée       |
| --------------------- | --------------------------------------------------------------- | ------------ |
| `branding`            | Champs natifs de personnalisation                               | Organisation |
| `governance`          | Politique stockée dans un fichier, avec `key` et `config` natif | Organisation |
| `provider`            | Définition d’un fournisseur et `expectedModels` facultatif      | Organisation |
| `provider-credential` | Métadonnées d’identifiants nommés issus de l’environnement      | Organisation |
| `knowledge-embedding` | Fournisseur, modèle, dimensions, endpoint et limites du serveur | Organisation |
| `deployment`          | Paramètres de l’instance, dont le runtime du sandbox            | Instance     |

Les politiques de conservation et DSAR exigent leurs workflows natifs dédiés. Interromps les envois, la synchronisation et les crawls avant de changer de modèle d’embedding. La CLI vérifie le nombre de documents et de sites web dans toute l’organisation ; elle ne verrouille pas l’import et ne migre pas les vecteurs existants. Pour une organisation avec des documents ou des sites web enregistrés, un changement de modèle exige une migration native distincte de l’index. Une modification limitée à `minSimilarity`, `maxConcurrentRequests`, `minTokensPerSecond`, `maxTokensPerMinute` ou `maxRequestsPerMinute` laisse les vecteurs existants valables et échappe donc à cette vérification. Les paramètres d’instance exigent aussi la liste native des éditeurs autorisés. L’application autonome signale `restartRequired` pour les paramètres de démarrage ; les enregistrer ne les active pas encore. Examine les effets du plan avant de l’appliquer.

Les déploiements gérés utilisent le même moteur via `configuration`. Ajoute cet exemple à la déclaration de déploiement quand un opérateur externe sert déjà le fournisseur. Remplace l’endpoint et le catalogue synthétiques par des valeurs vérifiées, puis injecte `EXTERNAL_PROVIDER_SECRET` depuis ton gestionnaire de secrets :

```json
{
  "environment": {
    "TALE_PROVIDER_KEY_EXTERNAL": {
      "env": "EXTERNAL_PROVIDER_SECRET"
    }
  },
  "configuration": {
    "schemaVersion": 1,
    "resources": [
      {
        "kind": "provider",
        "config": {
          "name": "external-chat",
          "displayName": "External chat",
          "apiFormat": "openai",
          "baseUrl": "https://models.example.invalid/v1",
          "catalog": {
            "source": "models-endpoint"
          },
          "embedding": "unknown",
          "auth": [
            {
              "method": "env"
            }
          ]
        },
        "expectedModels": [
          {
            "id": "Example-chat",
            "provider": "external-chat",
            "tags": ["chat"],
            "supportsTools": true,
            "supportsVision": false,
            "contextWindow": 131072
          }
        ]
      },
      {
        "kind": "provider-credential",
        "config": {
          "providerSlug": "external-chat",
          "authMethod": "env",
          "name": "Managed external provider",
          "envName": "TALE_PROVIDER_KEY_EXTERNAL",
          "modelAllowlist": ["Example-chat"]
        }
      }
    ]
  }
}
```

`envName` suit le préfixe natif `TALE_PROVIDER_KEY_` et la limite de 40 caractères. Chaque alias exige une référence `environment` obligatoire. Les endpoints privés exigent aussi une référence explicite `TALE_ALLOW_PRIVATE_PROVIDER_HOSTS` dont la valeur est `1` ; les restrictions natives d’hôtes restent actives. `expectedModels` vérifie le catalogue fraîchement résolu par Tale lors de la relecture. Ce contrôle ne prouve ni la capacité d’inférence, ni la latence, ni les résultats métier.

Pour la sélection du modèle de vision, utilise `governance` avec `key: "vision_model"` et les champs natifs `providerSlug`/`modelId`. L’embedding utilise `knowledge-embedding` avec `providerSlug`, `model`, `dimensions` et `baseUrl`, plus les réglages facultatifs que la plateforme garde à côté du modèle dans [`embedding.json`](https://docs.tale.dev/fr/self-hosted/configuration/data-residency#le-modele-dembedding-de-lorganisation) : `minSimilarity`, le plancher de cosinus de l’assistant pour ce modèle, et les limites du serveur `maxConcurrentRequests`, `minTokensPerSecond`, `maxTokensPerMinute` et `maxRequestsPerMinute` ([Doser les requêtes vers un serveur d’embedding auto-hébergé](https://docs.tale.dev/fr/self-hosted/configuration/data-residency#capacite-du-serveur-dembedding)). Chacun suit la règle de la plateforme elle-même : une valeur le fixe, une clé omise laisse ce que le fichier contient (une valeur posée à la main survit à une release qui ne la mentionne pas), et `null` l’efface — `"minSimilarity": null`, par exemple, est la seule façon de retirer un plancher par la CLI. Pour remplacer les identifiants par défaut, déclare aussi les anciens identifiants d’environnement avec `isDefault: false` ; la CLI applique ce changement explicite en premier. Les secrets ne figurent ni dans la déclaration ni dans le reçu.

La configuration native suit la vérification d’identité et précède les versions de configuration. Le reçu `native.configuration` lie les hashes de déclaration et de bundle, l’organisation, les hashes des ressources et les révisions natives. Un reçu en attente précède la première écriture. Si une ressource échoue ensuite, les changements précédents peuvent rester en place. Relis l’état natif et le reçu avant de reprendre le même plan vérifié. Le compare-and-set natif protège chaque ressource des modifications concurrentes d’un admin ; aucune transaction ne couvre l’ensemble. Conserve l’état du déploiement, les snapshots et les reçus pour la restauration.

Les déploiements gérés activent aussi une ressource `deployment` déclarée avant de signaler qu’ils sont prêts. La CLI conserve l’activation en attente, attend jusqu’à cinq minutes la fin des sessions du spawner sandbox vérifié, puis redémarre ce conteneur. Si des sessions restent actives, l’opération reste en attente. Le reçu `configurationActivation` enregistre la configuration montée et le démarrage observé du conteneur ; de nouveaux contrôles de santé doivent réussir. Une nouvelle tentative vérifie un redémarrage déjà accepté. Après une activation réussie, une nouvelle exécution sans changement ne redémarre pas le service.

#### Remplacer un plan de configuration en attente

Si un plan interrompu peut encore aboutir, relance ce même plan. Le remplacement explicite sert lorsque les réglages déclarés ne peuvent plus fonctionner, par exemple si le point de terminaison d’embedding n’est plus disponible. Conserve le reçu existant : il garde la trace des modifications qui ont pu atteindre la plateforme.

1. Lis le reçu en attente et compare les ressources déclarées à leur état actuel sur la plateforme. Enregistre les réglages corrigés dans `replacement-configuration.json`, avec la même cible et exactement les mêmes identifiants de ressources. Le remplacement ne permet ni d’ajouter ni de retirer des ressources.
2. Calcule le hash du champ `plan` du reçu conservé, pas celui du reçu entier ni du plan de remplacement. La commande suivante nécessite Bun et utilise du JSON canonique : clés d’objets triées récursivement, ordre des tableaux conservé et aucun espace.

```bash
PENDING_PLAN_SHA=$(bun -e '
  const receipt = await Bun.file(process.argv[1]).json();
  if (receipt.phase !== "pending") throw new Error("Receipt is not pending");
  function canonical(value) {
    if (Array.isArray(value)) return "[" + value.map(canonical).join(",") + "]";
    if (value !== null && typeof value === "object") {
      return "{" + Object.keys(value).sort().map(key =>
        JSON.stringify(key) + ":" + canonical(value[key])
      ).join(",") + "}";
    }
    return JSON.stringify(value);
  }
  console.log(new Bun.CryptoHasher("sha256")
    .update(canonical(receipt.plan)).digest("hex"));
' configuration-receipt.json)
```

3. Crée un nouveau plan à partir de la déclaration corrigée et examine-le avant de l’appliquer :

```bash
tale --json config plan --file replacement-configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID" --output replacement-plan.json
```

Une fois le plan vérifié, applique-le avec le chemin du reçu d’origine et le hash du plan conservé :

```bash
tale --json --yes config apply --file replacement-configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID" \
  --plan replacement-plan.json --receipt configuration-receipt.json \
  --supersedes-pending-plan "$PENDING_PLAN_SHA"
tale --json config read --file replacement-configuration.json \
  --url "$TALE_URL" --org "$TALE_ORG_ID"
```

Chaque ressource doit encore correspondre à l’état initial, à la modification prévue ou au résultat vérifié du plan en attente. Toute modification indépendante sur la plateforme bloque le remplacement avant la première écriture. Clarifie cet écart avec l’administrateur concerné ; ne supprime pas le reçu pour contourner la vérification.

Le reçu conserve le plan précédent et ses ressources vérifiées sous `superseded`, y compris après une interruption ou une nouvelle tentative. Vérifie qu’il atteint `phase: "ready"` et que `config read` indique des ressources conformes. Omet ce paramètre de sélection ponctuel lors des opérations suivantes.

Pour un déploiement géré, définis `supersedesPendingConfigurationPlan` dans la spécification de déploiement avec ce même hash du plan conservé, puis corrige `configuration`. Prépare et examine ensuite un nouveau bundle. Si celui-ci remplace aussi un déploiement en attente, sélectionne séparément le hash de ce dernier avec `supersedesPendingBundle`. Ce paramètre de bundle ne suffit pas à autoriser le remplacement du plan de configuration natif. Retire les deux paramètres de reprise des spécifications suivantes une fois l’opération prête.

Pour chaque ressource, la preuve publique `native.configuration` donne le hash prévu dans `configurationSha256` et celui de l’état relu sur la plateforme dans `observedConfigurationSha256`. Ils peuvent différer lorsqu’un réglage conserve une valeur existante, par exemple lorsqu’un seuil de similarité ou une limite du serveur d’embedding est omis. Le reçu privé conserve l’état exact observé pour permettre la reprise.

### Exploitation

`tale status` — afficher l'état actuel du déploiement. Aucun argument.

`tale logs <service>` — diffuser les logs d'un service (`service` est l'un des services en cours d'exécution ; sur une stack de dev sans déploiement, la commande retombe sur le conteneur de dev).

- `-f, --follow` — suivre la sortie des logs au fil de l'écriture.
- `-n, --tail <lines>` — n'afficher que les N dernières lignes.
- `--since <duration>` — afficher les logs depuis une durée relative (p. ex. `1h`, `30m`).
- `-c, --color <color>` — cibler une couleur de déploiement précise (`blue` ou `green`).
- `--raw` — diffuser la sortie brute, non filtrée (aucune classification).

`tale backup` — sauvegarder les volumes de projet existants pris en charge. Aucun argument. Les bases et buckets externes exigent leurs propres sauvegardes ; consulte [Portée des sauvegardes](https://docs.tale.dev/fr/self-hosted/operate/backups-and-restore).

`tale restore [snapshot-id]` — restaurer un snapshot ; sans id, la liste des snapshots disponibles s'affiche.

- `--stop` — arrêter les conteneurs du projet avant la restauration.
- `-y, --yes` — ignorer l'invite de confirmation.

`tale rollback` — revenir à la version patch précédente (niveau patch uniquement). Demande confirmation au préalable.

- `-y, --yes` — ignorer l'invite de confirmation (requis en mode non-interactif).

### Maintenance

`tale update` — changer la version d’une instance de workspace : mettre à jour la CLI et synchroniser les fichiers projet, puis lancer `tale deploy`. Les commandes du workspace s’alignent sur cette version. Les bundles gérés et releases de configuration gardent leur révision de CLI fixée séparément.

- `-v, --version <version>` — mettre à jour vers exactement cette version (p. ex. `0.9.0`) au lieu de la dernière ; autorise les rétrogradations.
- `-f, --force` — forcer la re-synchronisation et écraser les fichiers projet modifiés localement.
- `--dry-run` — montrer ce qui changerait sans rien modifier.

`tale migrate` — reprovisionner les valeurs par défaut intégrées pour chaque organisation sur le déploiement en cours — la même étape idempotente que chaque déploiement exécute, à la demande. Les migrations de schéma ne sont pas une commande : le backend les applique au démarrage, donc un conteneur déployé est toujours sur son propre schéma.

- `--dry-run` — montrer ce qui serait exécuté sans l'exécuter.

`tale cleanup` — supprimer les conteneurs inactifs (couleur non courante). Aucun argument.

`tale reset` — supprimer tous les conteneurs blue-green.

- `-f, --force` — ignorer l'invite de confirmation.
- `-a, --all` — supprimer aussi les conteneurs d'infrastructure avec état.
- `--dry-run` — prévisualiser la réinitialisation sans rien modifier.

`tale uninstall` — supprimer le binaire CLI `tale` de ce système. Il demande confirmation avant de supprimer quoi que ce soit et _propose_ aussi de déconnecter l’[appareil de sandbox](https://docs.tale.dev/fr/self-hosted/install/cli-install#sandbox-device) de cette machine, de retirer `~/.tale-daemon` laissé par l’ancien `tale daemon` et de démanteler les ressources Docker et les fichiers d'un projet. Sans `--purge`, un projet et ses conteneurs restent intacts — lance `tale reset --all` à l'intérieur pour les supprimer. Si l’appareil de sandbox ne peut pas être arrêté, rien n’est désinstallé.

- `-f, --force` — ignorer l'invite de confirmation (supprime uniquement le binaire ; les nettoyages optionnels nécessitent toujours `--purge`).
- `--purge` — déconnecter aussi l’appareil de sandbox et supprimer ses espaces de travail, retirer `~/.tale-daemon` et, pour un projet trouvé depuis le répertoire courant, démanteler ses ressources Docker et supprimer ses fichiers. Irréversible.
- `--dry-run` — montrer ce qui serait supprimé sans rien supprimer.

`tale config show` — afficher le répertoire du projet local résolu et la version de CLI. Hors d’un projet, la commande signale qu’aucun projet n’a été trouvé et se termine sans erreur.

### Releases de configuration

Ces commandes utilisent la révision de CLI choisie sans alignement sur une instance ni opération Docker. [Publier les configurations d’un client](https://docs.tale.dev/fr/self-hosted/configuration/config-releases) couvre les descripteurs, commits source, identifiants et reprises. L’identité par défaut est le SHA source complet : manifeste schéma 4/compilateur 3 avec `releaseRef === sourceCommit`. Les numéros entiers de version native restent distincts.

`build`, `verify` et `stage` exigent `--repo <directory>`, `--descriptor <path>` et `--automation <name>`. Le chemin du descripteur est relatif au dépôt. Celui du manifeste à vérifier peut être absolu ou relatif au dépôt.

| Commande             | Options obligatoires                         | Options facultatives                                                                                                                     |
| -------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `tale config build`  | `--source-commit <sha>`                      | `--skill-owner <user-id>` (requis pour les skills propres au paquet), `--output <directory>`, compatibilité `--config-version <version>` |
| `tale config verify` | `--manifest <path>`                          | `--rebuild` pour la reconstruction exacte hors ligne                                                                                     |
| `tale config stage`  | `--config-ref <sha>`, `--output <directory>` | `--skill-owner <user-id>`, `--client <name>`, `--deployment-ref <sha>`                                                                   |

La préparation source exige un checkout dont `HEAD` est ce commit complet et une sortie hors du checkout. Elle reconstruit les contenus committés sans commit de catalogue généré. `stage --config-version` choisit explicitement l’ancien parcours compatible et exige `--catalogue-commit`, `--catalogue-repository`, `--client` et `--ops-commit`. Ne combine pas `--config-ref` et `--config-version`.

Les commandes natives exigent `--stage <directory>`, `--url <origin>`, `--org <id>` et `--project <id>`. HTTPS est obligatoire sauf pour HTTP local ; utilise `--origin <origin>` pour l’origine canonique du navigateur derrière un proxy. Les deux lisent `TALE_CONFIG_COOKIE` uniquement dans l’environnement.

| Commande                    | Options obligatoires            | Options facultatives                                              |
| --------------------------- | ------------------------------- | ----------------------------------------------------------------- |
| `tale config deploy`        | `--receipt <path>`              | `--yes` global pour un déploiement sans interaction déjà autorisé |
| `tale config verify-native` | Aucune autre option obligatoire | `--native-version <number>`, `--allow-retained`                   |

Les deux commandes natives acceptent les attentes exactes `--config-ref`, `--source-repository`, `--artifact-sha256`, `--deployment-ref`, `--client` et `--automation`. Les anciens arguments de catalogue restent compatibles. `verify-native` est en lecture seule ; `--allow-retained` vérifie une version conservée choisie explicitement sans la présenter comme déployée. Sans `--native-version`, la vérification choisit la dernière version enregistrée. L’API native expose le contrat de tâche uniquement pour la version déployée ; une vérification conservée ne peut donc pas attester ce champ.

Les commandes de configuration n’ont pas de `--dry-run` : utilise `stage`, `verify --rebuild` et `verify-native`. Le JSON de succès est `{ok:true,command:"config <verb>",data}`. Les données de build et de vérification incluent `automationName`, `releaseRef`, `sourceCommit`, `artifactSha256`, `artifactPath` et `verified` ; la sortie compatible emploie `configVersion` à la place de `releaseRef`. Les reçus de transfert SHA et les reçus natifs utilisent le schéma 2. Un résultat de déploiement contient `automationVersion` et `unchanged` ; le champ explicite `verified` appartient aux sorties de vérification.

### Appareil de sandbox {#sandbox-device}

Ces commandes exécutent les sandboxes de ton organisation Tale sur la machine où tu les lances. [Exécuter les sandboxes sur tes propres appareils](https://docs.tale.dev/fr/platform/admin/sandbox-devices) explique comment ajouter un appareil dans **Paramètres > Sandboxes**, qui fournit la commande `connect`. L’appareil conserve sa configuration et ses espaces de travail dans `~/.tale/sandbox` ; `TALE_SANDBOX_HOME` les déplace.

`tale sandbox connect <site> --token <token>` — connecter cette machine à l’organisation qui a émis le jeton : la commande vérifie Docker (et propose de l’installer), enregistre la machine et démarre les conteneurs de l’appareil dans la version du serveur. `site` est ton site Tale, par exemple `https://your-org.tale.dev`. Le jeton (`tsdj_…`) ne fonctionne qu’une fois, dans l’heure. Linux et macOS uniquement.

- `--name <name>` — le nom que Tale affiche pour l’appareil (par défaut : le nom d’hôte de la machine). Les caractères autres que `A`–`Z`, `a`–`z`, les chiffres, `.`, `-` et `_` deviennent des tirets.
- `--max-sessions <n>` — combien de sandboxes tournent ici en même temps, de 1 à 256 (par défaut : une pour deux CPU et pour 4 Gio de mémoire utilisables par Docker, 16 au plus).
- `--no-auto-update` — ne pas suivre automatiquement la version du serveur ; lance plutôt `tale sandbox update` après chaque mise à jour de Tale.
- `--docker-socket <path>` — le socket Docker qu’utilisent les conteneurs de l’appareil, pour Docker rootless (par défaut : `/var/run/docker.sock`).

`tale sandbox status` — afficher la connexion, l’organisation, la version et les conteneurs de l’appareil, ainsi que les sandboxes en cours d’exécution. Aucun argument.

`tale sandbox update` — passer immédiatement l’appareil à la version du serveur et reprendre les adresses actuelles du serveur pour ses sandboxes (nécessaire après un changement d’adresse du backend ou de la passerelle de modèles). Aucun argument.

`tale sandbox logs` — afficher le journal de l’appareil.

- `-f, --follow` — continuer à afficher les nouvelles lignes.
- `--tail <lines>` — combien de lignes afficher d’abord (par défaut : `200`).

`tale sandbox disconnect` — retirer l’appareil de son organisation, arrêter ses sandboxes et supprimer leurs espaces de travail de cette machine. La commande demande d’abord confirmation et ne change rien tant que Docker ne tourne pas. Si le serveur est injoignable, la machine est tout de même nettoyée, et un administrateur retire l’appareil dans **Paramètres > Sandboxes**.

- `--keep-data` — conserver les espaces de travail sur cette machine.
- `-f, --force` — ignorer l’invite de confirmation.

### Avancé

`tale auth hash-password` — afficher le hachage Better Auth d’un mot de passe, pour un [administrateur de secours](https://docs.tale.dev/fr/self-hosted/install/cli-install#managed-break-glass).

La commande lit le mot de passe sur stdin, ou dans une invite masquée avec confirmation dans un terminal interactif. Elle refuse un mot de passe qui ne respecte pas la politique de mot de passe par défaut de la plateforme et n’affiche que le hachage.

`tale auth reset-owner` — réinitialiser les identifiants du compte propriétaire.

Pour une récupération manuelle, lance la commande sans options dans un terminal interactif. Le mot de passe se saisit dans une invite masquée, sans figurer dans l’historique du shell ni les arguments. La réinitialisation invalide les sessions existantes.

- `-e, --email <email>` — définir une nouvelle adresse e-mail du propriétaire.
- `-p, --password <password>` — définir un nouveau mot de passe du propriétaire.

## Dépannage

- **`tale deploy` vise la mauvaise machine.** La CLI utilise le contexte Docker / `DOCKER_HOST` de ton shell. Bascule avec `docker context use …` (ou définis `DOCKER_HOST`) pour qu'il pointe sur l'hôte voulu, puis relance.
- **`tale deploy` utilise le mauvais alias d'hôte.** L'hôte sur lequel le proxy répond vient de `HOST` dans le `.env` du projet, pas d'un stockage CLI séparé. Modifie `.env` ou passe `--host` pour le remplacer le temps d'un lancement.
- **L'installeur échoue sur macOS parce que le binaire ne peut pas s'exécuter.** Quand le binaire fraîchement installé refuse de démarrer (p. ex. Gatekeeper le tue), l'installeur échoue avec des pistes de récupération au lieu d'annoncer un succès — suis-les, puis relance l'installeur.
- **`tale` introuvable après installation sous Linux.** L'installeur dépose le binaire dans `/usr/local/bin` ; vérifie que le répertoire est dans le `PATH` de l'utilisateur (`echo $PATH`).

Pour l’exploitation courante, consulte [Mises à jour](https://docs.tale.dev/fr/self-hosted/operate/upgrades), [Sauvegardes et restauration](https://docs.tale.dev/fr/self-hosted/operate/backups-and-restore) ou [Architecture des conteneurs](https://docs.tale.dev/fr/self-hosted/operate/container-architecture).

# Créer le premier compte propriétaire
Source: https://docs.tale.dev/fr/self-hosted/install/first-admin

Sur une instance vide, la configuration Tale crée le premier compte et la première organisation. Ce compte devient Propriétaire. Termine cette étape pendant que tu contrôles encore l’accès à l’instance, avant de partager son adresse.

## Vérifier que l’instance est prête

Ouvre l’adresse affichée par `tale dev`, ou la `SITE_URL` configurée pour un déploiement, et vérifie le certificat et l’hôte. Pour un déploiement CLI, lance `tale status` ; pour une installation que tu maintiens, inspecte ses services et sondes. Un backend en échec nécessite un [dépannage](https://docs.tale.dev/fr/self-hosted/operate/observability/troubleshooting) avant la création du compte.

Une page de connexion au lieu de la configuration indique généralement qu’un compte existe déjà. C’est normal dans un environnement de développement prérempli. Ne supprime pas la base pour récupérer l’accès : connecte-toi au compte existant ou demande à un admin d’ajouter ton compte.

## Terminer la configuration

Ouvre l’URL de l’instance. Suis les étapes pour créer ton compte et nommer l’organisation. Conserve tes identifiants dans un gestionnaire de mots de passe.

Après avoir créé le compte et l’organisation, utilise le lien vers les fournisseurs sur la dernière page de l’assistant ou ouvre **Paramètres > Fournisseurs IA**. Sans fournisseur, tu peux explorer l’application ; une vraie réponse exige encore des identifiants valides et un modèle disponible. Suis [Fournisseurs IA](https://docs.tale.dev/fr/platform/admin/providers) pour en connecter un.

## Confirmer le rôle propriétaire

Ouvre **Paramètres > Membres** et vérifie que ton compte porte le rôle **Propriétaire**. Le nom de l’organisation et le compte doivent correspondre à l’instance que tu voulais initialiser.

<Frame caption="Vérifie le propriétaire et les rôles des membres avant d’ouvrir l’accès à l’équipe.">

![La page des membres de l’organisation affiche les personnes et leurs rôles.](https://docs.tale.dev/images/get-started/settings-organization-members.webp)

</Frame>

Déconnecte-toi puis reconnecte-toi pour tester les identifiants indépendamment de la session de configuration. Garde un autre accès administratif de secours déjà vérifié avant de modifier l’authentification.

## Ajouter l’équipe {#inviter-lequipe}

Ajoute les personnes sous **Paramètres > Membres** et choisis leurs rôles délibérément. Pour un nouveau compte, le formulaire définit un mot de passe initial ; un compte existant conserve ses identifiants. Cette procédure n’envoie aucun e-mail d’invitation. Transmets les identifiants initiaux par un canal sécurisé. L’inscription publique se ferme après le premier compte. Le SSO d’entreprise et le provisionnement suivent leurs propres [règles de configuration et d’appartenance](https://docs.tale.dev/fr/platform/admin/enterprise-sso).

C’est le backend lui-même qui l’applique, pas seulement le proxy placé devant : dès qu’un compte existe, `/api/auth/sign-up/email` répond 403. C’est important, car le backend est aussi joignable depuis le réseau bac à sable des agents, que le proxy ne voit jamais : du code exécuté dans une session d’agent ne peut donc pas créer de comptes non plus. **Paramètres > Membres** crée les comptes côté serveur et n’est pas concerné. Un déploiement de test jetable qui a besoin de la route ouverte définit `TALE_ALLOW_OPEN_SIGN_UP=true` ; jamais sur un déploiement réel.

Toute personne connectée peut créer une organisation supplémentaire tant que tu ne désignes pas qui en a le droit : définis `TALE_ORGANIZATION_CREATORS` avec leurs adresses de connexion, et l’entrée **Créer une organisation** disparaît du choix d’organisation pour toutes les autres personnes, que l’API refuse avec `403 ORGANIZATION_CREATION_FORBIDDEN`. La première organisation est toujours autorisée, la configuration initiale n’est donc pas concernée. Un déploiement géré déclare la même liste sous `organizations.creators` dans sa spécification ; voir [Installer la CLI tale](https://docs.tale.dev/fr/self-hosted/install/cli-install#managed-organization-creators) et la [référence des variables d’environnement](https://docs.tale.dev/fr/self-hosted/configuration/environment-reference).

Utilise [Membres et rôles](https://docs.tale.dev/fr/platform/admin/members-and-roles) pour choisir les accès. Puis [envoie ton premier message](https://docs.tale.dev/fr/get-started/quickstart) et vérifie la réponse complète. Crée un [agent de projet](https://docs.tale.dev/fr/tutorials/editor/first-agent-end-to-end) quand tu souhaites déléguer une tâche. Un Dashboard accessible confirme l’accès à l’application, pas le fournisseur ni chaque service en arrière-plan.

# Choisir une méthode d’installation
Source: https://docs.tale.dev/fr/self-hosted/install

Utilise la CLI Tale pour une installation standard. Choisis ton propre déploiement lorsque tes outils d’infrastructure doivent gérer les définitions des services. Les deux méthodes nécessitent les mêmes services applicatifs et une personne responsable de la configuration et de la maintenance.

## Installer avec la CLI

Le [guide de démarrage](https://docs.tale.dev/fr/self-hosted/install/quickstart) couvre les prérequis, la création du projet, le démarrage et la première connexion. `tale init` prépare un répertoire de projet. `tale dev` lance une instance de développement ; `tale deploy` déploie cet environnement.

La CLI gère les opérations sur les conteneurs. Tu restes responsable de la configuration, des identifiants, des volumes et des mises à jour. Conserve le répertoire du projet avec ses paramètres de déploiement. [Installer la CLI](https://docs.tale.dev/fr/self-hosted/install/cli-install) décrit les systèmes pris en charge, l’accès à un hôte Docker distant, les commandes et les déploiements gérés.

## Utiliser tes propres définitions de services

[Exploiter ton propre déploiement](https://docs.tale.dev/fr/self-hosted/install/own-compose) décrit les services, les volumes, le réseau, les contrôles de disponibilité et l’ordre de démarrage à respecter. Suis ce guide si tu maintiens Compose toi-même. [Déployer sur Kubernetes](https://docs.tale.dev/fr/self-hosted/install/kubernetes) transpose ce contrat en Deployments, Services et NetworkPolicies, et liste les vérifications qu’un cluster doit réussir. Tale ne fournit pas de chart Helm officiel.

Pour modifier le code source de Tale, configure plutôt un [environnement de développement](https://docs.tale.dev/fr/develop/contributor-setup).

## Terminer la configuration initiale

Une fois l’instance prête, [crée le premier compte administrateur](https://docs.tale.dev/fr/self-hosted/install/first-admin), connecte un fournisseur et teste une conversation. Ajoute ensuite les utilisateurs dans [Membres et rôles](https://docs.tale.dev/fr/platform/admin/members-and-roles), selon les options de compte et de connexion disponibles dans ton organisation.

Avant d’utiliser des données de production, configure TLS et les sauvegardes. Vérifie les [paramètres d’environnement](https://docs.tale.dev/fr/self-hosted/configuration/environment-reference) et consulte l’[architecture d’exploitation](https://docs.tale.dev/fr/self-hosted/operate/container-architecture).

# Déployer sur Kubernetes
Source: https://docs.tale.dev/fr/self-hosted/install/kubernetes

Tale fonctionne sur Kubernetes lorsque tu transposes le [contrat de services](https://docs.tale.dev/fr/self-hosted/install/own-compose) en Deployments, Services et volumes, et que tu bascules le spawner de sandbox sur `SANDBOX_BACKEND=kubernetes`. Il n’existe pas de chart Helm officiel. Ce guide fournit un jeu complet de manifestes pour un seul namespace, vérifié de bout en bout avec Tale 0.5.31 sur un cluster à un seul nœud, ainsi que les vérifications qui prouvent le résultat. Le cluster, son stockage, son point d’entrée public et la procédure de mise à jour restent sous ta responsabilité.

## Vérifier les prérequis

| Prérequis | Pourquoi il compte |
| --- | --- |
| Un CNI qui applique NetworkPolicy, comme Calico, Cilium ou kube-network-policies | La barrière de sortie des sandboxes et celle du backend sont des objets NetworkPolicy. Tout serveur d’API les accepte ; seul le CNI bloque réellement le trafic. |
| Une StorageClass par défaut dont les volumes `ReadWriteOnce` se rattachent là où un Pod est planifié | La base de données, le stockage d’objets, les certificats du proxy, l’état de la passerelle et chaque workspace de sandbox vivent sur des PersistentVolumeClaims. Le volume d’un workspace de sandbox supprimé suit la `reclaimPolicy` de la StorageClass : avec `Delete`, ses fichiers disparaissent avec lui ; avec `Retain`, ils restent jusqu’à ce que tu supprimes le volume. |
| Un stockage `ReadWriteMany`, ou un seul nœud, pour la configuration des organisations | Les rôles backend écrivent `config-data` ; la couche web et le spawner le lisent. Sur un nœud, `ReadWriteOnce` suffit. Plusieurs nœuds exigent `ReadWriteMany` ou l’épinglage de ces Pods sur un nœud. |
| Des nœuds qui accordent `NET_ADMIN` et fournissent ip6tables, ou autorisent les sysctls IPv6 | Le proxy de sortie installe son pare-feu au démarrage et refuse de démarrer sans lui. |
| Les ports 80 et 443 joignables à l’adresse publique | Caddy obtient lui-même les certificats en mode `selfsigned` et `letsencrypt`. Derrière un Ingress qui termine TLS, définis `TLS_MODE=external`. |
| Un accès en lecture à `ghcr.io/tale-project/tale/*` sur chaque nœud, y compris pour l’image du runtime sandbox | Les Pods de session démarrent depuis `SANDBOX_RUNTIME_IMAGE`. Un nœud qui ne peut pas la récupérer fait échouer la première session qui y est planifiée. |
| Une RuntimeClass sysbox ou kata si les agents ont besoin de Docker dans leur sandbox | Sans elle, garde `SANDBOX_DOCKER_IN_CONTAINER=false`. Le niveau `runc` exigerait des Pods privilégiés. |
| `kubectl` et `envsubst` sur la machine qui applique les manifestes | Les manifestes contiennent une variable `${VERSION}` que kubectl ne développe pas. |

Réserve de la mémoire pour les rôles applicatifs plus une session d’agent par tâche simultanée ; `SANDBOX_AGENT_MEMORY` et les autres limites de session sont décrites dans la [référence d’environnement](https://docs.tale.dev/fr/self-hosted/configuration/environment-reference#sandbox-infrastructure).

## Organiser le namespace

Tous les services s’exécutent dans un seul namespace, `tale`. Les Pods de session doivent joindre directement `backend-api` et `sandbox-llm-gateway`, et la barrière de sortie que le spawner installe n’autorise que le namespace dans lequel il s’exécute : les rôles applicatifs doivent donc s’y trouver aussi. Les noms de Services reprennent les noms de services Compose : les images résolvent `db`, `knowledge-db`, `object-store`, `backend-api`, `platform`, `sandbox`, `sandbox-egress`, `sandbox-llm-gateway` avec son alias `llm-gateway`, et `bgutil-provider` par leur nom.

<Warning>

Chaque Pod ci-dessous définit `enableServiceLinks: false`. Sinon, Kubernetes injecte pour chaque Service du namespace des variables à la manière de Docker, comme `SANDBOX_PORT=tcp://10.96.6.49:8003` et `DB_PORT=tcp://10.96.150.113:5432`. Le spawner lit `SANDBOX_PORT` comme son port d’écoute et s’arrête au démarrage, et l’image de la plateforme dérive son URL de base de données de `DB_PORT`.

</Warning>

| Service Compose | Objets Kubernetes | Remarques |
| --- | --- | --- |
| `db` avec l’alias `knowledge-db` | StatefulSet `db` ; Services `db` et `knowledge-db` sélectionnant le même Pod | `TALE_DB_ROLE` reste vide : l’image crée les deux bases et applique les migrations de connaissances ; le backend migre le schéma applicatif au démarrage. Un `emptyDir` en mémoire de 256 Mio sert de `/dev/shm`. L’image s’arrête sur `SIGINT` dans un délai de 60 secondes. |
| `object-store` | Deployment avec la stratégie `Recreate`, PVC sur `/data`, Service sur 9000 | Le backend crée le bucket au démarrage. |
| `platform` | Deployment ; Service sur 3000 | `config-data` en lecture seule, `TALE_BACKEND_URL=http://backend-api:3005`. |
| `backend-api` | Deployment à deux réplicas ; Service sur 3005 | `config-data` en lecture-écriture. Deux réplicas permettent une mise à jour sans interruption. |
| `backend-worker` | Deployment | Ni Service ni sonde HTTP. |
| `proxy` | Deployment avec la stratégie `Recreate` ; `hostPort` 80 et 443 ; PVC pour `/data` | Le magasin de certificats survit aux redémarrages sur le PVC. |
| `sandbox` | ServiceAccount, Role, RoleBinding, Deployment ; Service sur 8003 | `SANDBOX_BACKEND=kubernetes` ; `config-data` en lecture seule sur `/app/platform-config`. Aucun socket Docker. |
| `sandbox-egress` | Deployment ; Service sur 3128 | Le jeu de capabilities livré, sans sysctls. |
| `sandbox-llm-gateway` | Deployment avec la stratégie `Recreate`, PVC sur `/app/data` ; Services `sandbox-llm-gateway` et `llm-gateway` sur 8080 | L’image s’exécute avec l’uid 1000 ; `fsGroup: 1000` lui permet d’écrire son état. La passerelle lit `SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD` dans `tale-env` : tant qu’elle n’a pas de compte d’administration, elle n’en crée un que pour un appelant qui présente ce secret. |
| `bgutil-provider` | Deployment ; Service sur 4416 | Fournisseur de jetons vidéo, facultatif. |

Les sondes transposent les contrôles de santé Compose :

| Service | Sonde de démarrage | Sonde de disponibilité | Sonde de vivacité |
| --- | --- | --- | --- |
| `backend-api` | `GET /ping` sur 3005, jusqu’à cinq minutes pour les migrations | `GET /ready` sur 3005 | `GET /ping` sur 3005 |
| `platform` | `curl -sf http://localhost:3000/api/health && [ -f /tmp/platform-ready ]`, jusqu’à trois minutes | la même commande | aucune |
| `db` | `pg_isready -U tale -d tale && [ -f /tmp/.db_ready ]`, jusqu’à trois minutes | la même commande | `pg_isready -U tale -d tale` |
| `object-store` | aucune | `mc ready local` | aucune |
| `proxy` | aucune | `GET /health` sur 2020 | aucune |
| `sandbox` | `GET /health` sur 8003 | `GET /health` sur 8003 | aucune |
| `sandbox-egress` | aucune | `curl -sS -o /dev/null --max-time 3 --noproxy '*' http://127.0.0.1:3128/` | aucune |
| `sandbox-llm-gateway` | aucune | `GET /health` sur 8080 | aucune |

Kubernetes n’a pas de `depends_on`. Un rôle backend qui démarre avant que Postgres réponde se termine une fois avec `ECONNREFUSED`, et la politique de redémarrage corrige la situation.

## Préparer les manifestes

Enregistre chaque bloc YAML des sections suivantes sous le nom de fichier indiqué à sa première ligne, dans un même répertoire. Modifie le Secret : remplace chaque espace réservé `<...>` et définis `HOST`, `SITE_URL`, `TLS_MODE` et `OBJECT_STORE_PUBLIC_ENDPOINT` pour ton adresse. Si cette adresse comporte un port non standard, reporte-le aussi dans `containerPort` et `hostPort` du proxy dans `30-proxy.yaml` ; Caddy écoute sur le port indiqué dans `SITE_URL`. Fixe ensuite une seule version pour toutes les images Tale, `0.5.31` au moment de la rédaction, et applique les fichiers dans l’ordre :

```bash
export VERSION=0.5.31
for f in 00-namespace.yaml 10-stores.yaml 20-application.yaml 30-proxy.yaml 40-sandbox.yaml; do
  envsubst '${VERSION}' < "$f" | kubectl apply -f -
done
```

`envsubst` ne remplace que `${VERSION}` ; toute autre valeur des fichiers est littérale. La même boucle réalise une mise à niveau : change `VERSION`, relance-la, et les Deployments basculent sur la nouvelle image.

## Créer l’environnement partagé

Le premier fichier contient le namespace, les valeurs communes au déploiement issues du `.env` de Compose, et le claim de configuration partagé. Génère chaque secret une seule fois et conserve-le ; `ENCRYPTION_SECRET_HEX` en particulier doit rester stable pour les valeurs déjà chiffrées. La [référence d’environnement](https://docs.tale.dev/fr/self-hosted/configuration/environment-reference) explique chaque variable.

```yaml
# 00-namespace.yaml
apiVersion: v1
kind: Namespace
metadata: { name: tale }
---
apiVersion: v1
kind: Secret
metadata: { name: tale-env, namespace: tale }
type: Opaque
stringData:
  HOST: tale.example.com
  SITE_URL: https://tale.example.com
  TLS_MODE: letsencrypt
  POSTGRES_USER: tale
  POSTGRES_DB: tale
  DB_PASSWORD: <generated>
  DATABASE_URL: postgresql://tale:<DB_PASSWORD>@db:5432/tale_app
  KNOWLEDGE_DB_NAME: tale_knowledge
  INSTANCE_SECRET: <openssl rand -hex 32>
  BETTER_AUTH_SECRET: <openssl rand -hex 32>
  ENCRYPTION_SECRET_HEX: <openssl rand -hex 32>
  TALE_AUDIT_PEPPER: <openssl rand -hex 32>
  SANDBOX_TOKEN: <openssl rand -hex 32>
  SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD: <generated>
  OBJECT_STORE_ACCESS_KEY: tale
  OBJECT_STORE_SECRET_KEY: <generated>
  OBJECT_STORE_BUCKET: tale-blobs
  OBJECT_STORE_ENDPOINT: http://object-store:9000
  OBJECT_STORE_REGION: us-east-1
  OBJECT_STORE_PUBLIC_ENDPOINT: https://tale.example.com
---
# Configuration des organisations : les rôles backend écrivent, platform et le spawner lisent.
# ReadWriteOnce suffit sur un nœud ; plusieurs nœuds exigent ReadWriteMany.
apiVersion: v1
kind: PersistentVolumeClaim
metadata: { name: config-data, namespace: tale }
spec:
  accessModes: [ReadWriteOnce]
  resources: { requests: { storage: 2Gi } }
```

`DATABASE_URL` porte le même mot de passe que `DB_PASSWORD` ; la connexion de connaissances utilise par défaut `knowledge-db:5432/tale_knowledge` avec ce mot de passe. `SITE_URL` doit correspondre à l’adresse saisie dans le navigateur, port non standard compris.

## Exécuter les stockages

Le StatefulSet conserve le volume de données à travers les remplacements de Pod et donne à l’image l’arrêt qu’elle attend. MinIO s’exécute comme un Deployment unique sur son propre claim.

```yaml
# 10-stores.yaml
apiVersion: v1
kind: Service
metadata: { name: db, namespace: tale }
spec:
  selector: { app: db }
  ports: [{ name: pg, port: 5432, targetPort: 5432 }]
---
apiVersion: v1
kind: Service
metadata: { name: knowledge-db, namespace: tale }
spec:
  selector: { app: db }
  ports: [{ name: pg, port: 5432, targetPort: 5432 }]
---
apiVersion: apps/v1
kind: StatefulSet
metadata: { name: db, namespace: tale }
spec:
  serviceName: db
  replicas: 1
  selector: { matchLabels: { app: db } }
  template:
    metadata: { labels: { app: db } }
    spec:
      enableServiceLinks: false
      terminationGracePeriodSeconds: 60
      containers:
        - name: postgres
          image: ghcr.io/tale-project/tale/tale-db:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          ports: [{ name: pg, containerPort: 5432 }]
          volumeMounts:
            - { name: data, mountPath: /var/lib/postgresql/data }
            - { name: shm, mountPath: /dev/shm }
          startupProbe:
            exec: { command: [sh, -c, 'pg_isready -U tale -d tale && [ -f /tmp/.db_ready ]'] }
            periodSeconds: 5
            failureThreshold: 36
          readinessProbe:
            exec: { command: [sh, -c, 'pg_isready -U tale -d tale && [ -f /tmp/.db_ready ]'] }
            periodSeconds: 5
          livenessProbe:
            exec: { command: [sh, -c, 'pg_isready -U tale -d tale'] }
            periodSeconds: 15
          resources:
            requests: { cpu: 250m, memory: 512Mi }
      volumes:
        - name: shm
          emptyDir: { medium: Memory, sizeLimit: 256Mi }
  volumeClaimTemplates:
    - metadata: { name: data }
      spec:
        accessModes: [ReadWriteOnce]
        resources: { requests: { storage: 20Gi } }
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata: { name: object-store-data, namespace: tale }
spec:
  accessModes: [ReadWriteOnce]
  resources: { requests: { storage: 20Gi } }
---
apiVersion: v1
kind: Service
metadata: { name: object-store, namespace: tale }
spec:
  selector: { app: object-store }
  ports: [{ name: s3, port: 9000, targetPort: 9000 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: object-store, namespace: tale }
spec:
  replicas: 1
  strategy: { type: Recreate }
  selector: { matchLabels: { app: object-store } }
  template:
    metadata: { labels: { app: object-store } }
    spec:
      enableServiceLinks: false
      terminationGracePeriodSeconds: 30
      containers:
        - name: minio
          image: ghcr.io/tale-project/ops/minio:RELEASE.2025-04-22T22-12-26Z
          args: ['server', '/data', '--address', ':9000', '--console-address', ':9001']
          env:
            - name: MINIO_ROOT_USER
              valueFrom: { secretKeyRef: { name: tale-env, key: OBJECT_STORE_ACCESS_KEY } }
            - name: MINIO_ROOT_PASSWORD
              valueFrom: { secretKeyRef: { name: tale-env, key: OBJECT_STORE_SECRET_KEY } }
            - { name: MINIO_BROWSER, value: 'off' }
          ports: [{ name: s3, containerPort: 9000 }]
          volumeMounts: [{ name: data, mountPath: /data }]
          readinessProbe:
            exec: { command: [sh, -c, 'mc ready local'] }
            periodSeconds: 10
          resources:
            requests: { cpu: 100m, memory: 256Mi }
      volumes:
        - name: data
          persistentVolumeClaim: { claimName: object-store-data }
```

Pour un Postgres externe, définis `DATABASE_URL` et `KNOWLEDGE_DATABASE_URL` comme décrit dans [Connecter des stockages externes](https://docs.tale.dev/fr/self-hosted/install/own-compose#connecter-des-stockages-externes) et omets le StatefulSet et ses Services ; pour un bucket externe, définis les valeurs `OBJECT_STORE_*` et omets les objets MinIO.

## Exécuter les rôles applicatifs

Les trois rôles partagent l’image de la plateforme : l’API et le worker écrivent `config-data`, la couche web le lit. Le fichier contient aussi le fournisseur de jetons vidéo facultatif qu’utilise le worker ; retire ses deux objets si tu n’ingères pas de vidéos.

<Warning>

Les rôles backend s’exécutent sans `NET_ADMIN` et avec `TALE_SKIP_SSRF_FIREWALL=1`. Avec cette capability, l’image installe sa barrière de sortie iptables, qui n’accepte que les sous-réseaux directement connectés au Pod et rejette le reste de l’espace d’adressage privé. Sur un réseau de Pods, cela rejette aussi le DNS du cluster et chaque adresse de Service : le rôle échoue avec `getaddrinfo EAI_AGAIN db` et redémarre jusqu’à ce que tu retires la capability. La NetworkPolicy à la fin du fichier assure la barrière à la place : les rôles joignent chaque voisin du namespace, le DNS du cluster et l’internet public, jamais le service de métadonnées du cloud, les nœuds ni les réseaux privés. Étends sa dernière règle si tes fournisseurs de modèles ou tes connecteurs se trouvent sur une plage privée.

</Warning>

```yaml
# 20-application.yaml
apiVersion: v1
kind: Service
metadata: { name: backend-api, namespace: tale }
spec:
  selector: { app: backend-api }
  ports: [{ name: http, port: 3005, targetPort: 3005 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: backend-api, namespace: tale }
spec:
  replicas: 2
  selector: { matchLabels: { app: backend-api } }
  template:
    metadata: { labels: { app: backend-api, tale.tier: backend } }
    spec:
      enableServiceLinks: false
      terminationGracePeriodSeconds: 45
      containers:
        - name: backend-api
          image: ghcr.io/tale-project/tale/tale-platform:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          env:
            - { name: TALE_ROLE, value: api }
            - { name: PORT, value: '3005' }
            - { name: TALE_CONFIG_DIR, value: /app/data }
            - { name: SANDBOX_URL, value: http://sandbox:8003 }
            - { name: SANDBOX_HTTP_API_BASE_URL, value: http://backend-api:3005 }
            - { name: TALE_SKIP_SSRF_FIREWALL, value: '1' }
          ports: [{ name: http, containerPort: 3005 }]
          volumeMounts: [{ name: config-data, mountPath: /app/data }]
          startupProbe:
            httpGet: { path: /ping, port: 3005 }
            periodSeconds: 5
            failureThreshold: 60
          readinessProbe:
            httpGet: { path: /ready, port: 3005 }
            periodSeconds: 5
          livenessProbe:
            httpGet: { path: /ping, port: 3005 }
            periodSeconds: 10
          resources:
            requests: { cpu: 500m, memory: 1Gi }
      volumes:
        - name: config-data
          persistentVolumeClaim: { claimName: config-data }
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: backend-worker, namespace: tale }
spec:
  replicas: 1
  selector: { matchLabels: { app: backend-worker } }
  template:
    metadata: { labels: { app: backend-worker, tale.tier: backend } }
    spec:
      enableServiceLinks: false
      terminationGracePeriodSeconds: 45
      containers:
        - name: backend-worker
          image: ghcr.io/tale-project/tale/tale-platform:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          env:
            - { name: TALE_ROLE, value: worker }
            - { name: TALE_CONFIG_DIR, value: /app/data }
            - { name: SANDBOX_URL, value: http://sandbox:8003 }
            - { name: SANDBOX_HTTP_API_BASE_URL, value: http://backend-api:3005 }
            - { name: TALE_SKIP_SSRF_FIREWALL, value: '1' }
          volumeMounts: [{ name: config-data, mountPath: /app/data }]
          resources:
            requests: { cpu: 500m, memory: 1Gi }
      volumes:
        - name: config-data
          persistentVolumeClaim: { claimName: config-data }
---
apiVersion: v1
kind: Service
metadata: { name: platform, namespace: tale }
spec:
  selector: { app: platform }
  ports: [{ name: http, port: 3000, targetPort: 3000 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: platform, namespace: tale }
spec:
  replicas: 1
  selector: { matchLabels: { app: platform } }
  template:
    metadata: { labels: { app: platform } }
    spec:
      enableServiceLinks: false
      terminationGracePeriodSeconds: 45
      containers:
        - name: platform
          image: ghcr.io/tale-project/tale/tale-platform:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          env:
            - { name: TALE_BACKEND_URL, value: http://backend-api:3005 }
            - { name: TALE_CONFIG_DIR, value: /app/data }
          ports: [{ name: http, containerPort: 3000 }]
          volumeMounts: [{ name: config-data, mountPath: /app/data, readOnly: true }]
          startupProbe:
            exec: { command: [sh, -c, 'curl -sf http://localhost:3000/api/health && [ -f /tmp/platform-ready ]'] }
            periodSeconds: 5
            failureThreshold: 36
          readinessProbe:
            exec: { command: [sh, -c, 'curl -sf http://localhost:3000/api/health && [ -f /tmp/platform-ready ]'] }
            periodSeconds: 5
          resources:
            requests: { cpu: 250m, memory: 512Mi }
      volumes:
        - name: config-data
          persistentVolumeClaim: { claimName: config-data }
---
apiVersion: v1
kind: Service
metadata: { name: bgutil-provider, namespace: tale }
spec:
  selector: { app: bgutil-provider }
  ports: [{ name: http, port: 4416, targetPort: 4416 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: bgutil-provider, namespace: tale }
spec:
  replicas: 1
  selector: { matchLabels: { app: bgutil-provider } }
  template:
    metadata: { labels: { app: bgutil-provider } }
    spec:
      enableServiceLinks: false
      automountServiceAccountToken: false
      containers:
        - name: provider
          image: brainicism/bgutil-ytdlp-pot-provider:1.3.1
          ports: [{ name: http, containerPort: 4416 }]
          readinessProbe:
            tcpSocket: { port: 4416 }
            periodSeconds: 30
          resources:
            requests: { cpu: 50m, memory: 128Mi }
            limits: { memory: 512Mi }
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata: { name: tale-backend-egress, namespace: tale }
spec:
  podSelector:
    matchLabels: { tale.tier: backend }
  policyTypes: [Egress]
  egress:
    - to:
        - podSelector: {}
    - to:
        - namespaceSelector: {}
      ports:
        - { protocol: UDP, port: 53 }
        - { protocol: TCP, port: 53 }
    - to:
        - ipBlock:
            cidr: 0.0.0.0/0
            except:
              - 169.254.0.0/16
              - 10.0.0.0/8
              - 172.16.0.0/12
              - 192.168.0.0/16
```

Les conteneurs de la plateforme démarrent en root, corrigent la propriété de `/app/data` puis passent à l’utilisateur applicatif ; ne leur impose pas `runAsNonRoot`.

## Exposer le proxy

Le proxy est le seul service public. Il occupe les `hostPort` 80 et 443 du nœud où il s’exécute ; fais pointer le nom public vers l’adresse de ce nœud. Caddy écoute sur le port indiqué dans `SITE_URL` : avec `https://tale.example.com:8443`, le Pod doit exposer 8443 au lieu de 443, tandis que le port 80 continue de servir la redirection vers HTTPS. La stratégie est `Recreate` : deux Pods de proxy ne peuvent partager ni un `hostPort` ni un volume `ReadWriteOnce`.

```yaml
# 30-proxy.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata: { name: caddy-data, namespace: tale }
spec:
  accessModes: [ReadWriteOnce]
  resources: { requests: { storage: 1Gi } }
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: proxy, namespace: tale }
spec:
  replicas: 1
  strategy: { type: Recreate }
  selector: { matchLabels: { app: proxy } }
  template:
    metadata: { labels: { app: proxy } }
    spec:
      enableServiceLinks: false
      containers:
        - name: caddy
          image: ghcr.io/tale-project/tale/tale-proxy:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          env:
            - { name: BACKEND_UPSTREAM, value: 'backend-api:3005' }
            - { name: OBJECT_STORE_UPSTREAM, value: 'object-store:9000' }
          ports:
            - { name: http, containerPort: 80, hostPort: 80 }
            - { name: https, containerPort: 443, hostPort: 443 }
          volumeMounts:
            - { name: caddy-data, mountPath: /data }
            - { name: caddy-config, mountPath: /config }
          readinessProbe:
            httpGet: { path: /health, port: 2020 }
            periodSeconds: 10
          resources:
            requests: { cpu: 50m, memory: 64Mi }
      volumes:
        - name: caddy-data
          persistentVolumeClaim: { claimName: caddy-data }
        - name: caddy-config
          emptyDir: {}
```

Deux alternatives conservent le même Pod :

- Un Service LoadBalancer sur 80 et 443 devant le proxy, à la place des entrées `hostPort`. `TLS_MODE=selfsigned` et `letsencrypt` fonctionnent tels quels ; le proxy sert aussi `docs.<HOST>` et obtient ce certificat.
- Un Ingress qui termine TLS. Définis `TLS_MODE=external` et `TRUSTED_PROXIES` sur la plage d’adresses de l’Ingress pour que les en-têtes transmis soient acceptés, comme décrit dans [TLS et domaines](https://docs.tale.dev/fr/self-hosted/configuration/tls-and-domains).

## Exécuter la couche sandbox

Le proxy de sortie a besoin du jeu de capabilities du contrat Compose et d’aucun sysctl : le script d’entrée installe le pare-feu IPv6 avec ip6tables lorsque le noyau du nœud le fournit, et désactive sinon IPv6 dans son propre espace de noms réseau. Un cluster qui refuse les deux bloque le Pod au démarrage ; autorise dans ce cas les sysctls `net.ipv6.conf.*` sur le kubelet. Le spawner crée les Pods de session, les Secrets et les claims de workspace via l’API Kubernetes ; il s’exécute donc avec une Role limitée au namespace et sans socket Docker.

Le proxy sert `SANDBOX_EGRESS_MAX_CLIENTS` connexions à la fois (2000 par défaut) pour l’ensemble des sessions, chacune avec un thread et deux fichiers ouverts. Une spécification de Pod ne peut fixer ni limite de processus ni limite de fichiers ouverts : au démarrage, le proxy relève sa limite de fichiers ouverts à ce dont ses connexions ont besoin, dans la mesure où la limite stricte du runtime de conteneurs le permet, et avertit dans son journal quand elle est trop basse. Ses threads comptent dans le `podPidsLimit` du kubelet ; si tes nœuds en fixent un, garde-le au-dessus de la limite de connexions, ou abaisse `SANDBOX_EGRESS_MAX_CLIENTS` en conséquence.

```yaml
# 40-sandbox.yaml
apiVersion: v1
kind: Service
metadata: { name: sandbox-egress, namespace: tale }
spec:
  selector: { app: sandbox-egress }
  ports: [{ name: proxy, port: 3128, targetPort: 3128 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: sandbox-egress, namespace: tale }
spec:
  replicas: 1
  selector: { matchLabels: { app: sandbox-egress } }
  template:
    metadata: { labels: { app: sandbox-egress } }
    spec:
      enableServiceLinks: false
      automountServiceAccountToken: false
      containers:
        - name: egress
          image: ghcr.io/tale-project/tale/tale-sandbox-egress:${VERSION}
          env:
            - { name: SANDBOX_EGRESS_MAX_CLIENTS, value: '2000' }
          securityContext:
            runAsUser: 0
            capabilities:
              drop: ['ALL']
              add: ['NET_ADMIN', 'DAC_OVERRIDE', 'CHOWN', 'SETUID', 'SETGID', 'NET_BIND_SERVICE', 'KILL']
          ports: [{ name: proxy, containerPort: 3128 }]
          readinessProbe:
            exec: { command: [sh, -c, "curl -sS -o /dev/null --max-time 3 --noproxy '*' http://127.0.0.1:3128/"] }
            periodSeconds: 10
          resources:
            requests: { cpu: 50m, memory: 64Mi }
            limits: { memory: 512Mi }
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata: { name: llm-gateway-data, namespace: tale }
spec:
  accessModes: [ReadWriteOnce]
  resources: { requests: { storage: 1Gi } }
---
apiVersion: v1
kind: Service
metadata: { name: sandbox-llm-gateway, namespace: tale }
spec:
  selector: { app: sandbox-llm-gateway }
  ports: [{ name: http, port: 8080, targetPort: 8080 }]
---
apiVersion: v1
kind: Service
metadata: { name: llm-gateway, namespace: tale }
spec:
  selector: { app: sandbox-llm-gateway }
  ports: [{ name: http, port: 8080, targetPort: 8080 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: sandbox-llm-gateway, namespace: tale }
spec:
  replicas: 1
  strategy: { type: Recreate }
  selector: { matchLabels: { app: sandbox-llm-gateway } }
  template:
    metadata: { labels: { app: sandbox-llm-gateway } }
    spec:
      enableServiceLinks: false
      automountServiceAccountToken: false
      securityContext: { fsGroup: 1000 }
      containers:
        - name: gateway
          image: ghcr.io/tale-project/tale/tale-sandbox-llm-gateway:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          ports: [{ name: http, containerPort: 8080 }]
          volumeMounts: [{ name: data, mountPath: /app/data }]
          readinessProbe:
            httpGet: { path: /health, port: 8080 }
            periodSeconds: 10
          resources:
            requests: { cpu: 50m, memory: 128Mi }
            limits: { memory: 512Mi }
      volumes:
        - name: data
          persistentVolumeClaim: { claimName: llm-gateway-data }
---
apiVersion: v1
kind: ServiceAccount
metadata: { name: tale-sandbox-spawner, namespace: tale }
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata: { name: tale-sandbox-spawner, namespace: tale }
rules:
  - apiGroups: ['']
    resources: ['pods']
    verbs: ['create', 'get', 'list', 'delete', 'patch']
  - apiGroups: ['']
    resources: ['secrets']
    verbs: ['create', 'delete', 'list']
  - apiGroups: ['']
    resources: ['persistentvolumeclaims']
    verbs: ['get', 'list', 'create', 'delete']
  - apiGroups: ['networking.k8s.io']
    resources: ['networkpolicies']
    verbs: ['create', 'update']
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata: { name: tale-sandbox-spawner, namespace: tale }
roleRef: { apiGroup: rbac.authorization.k8s.io, kind: Role, name: tale-sandbox-spawner }
subjects: [{ kind: ServiceAccount, name: tale-sandbox-spawner, namespace: tale }]
---
apiVersion: v1
kind: Service
metadata: { name: sandbox, namespace: tale }
spec:
  selector: { app: sandbox }
  ports: [{ name: http, port: 8003, targetPort: 8003 }]
---
apiVersion: apps/v1
kind: Deployment
metadata: { name: sandbox, namespace: tale }
spec:
  replicas: 1
  selector: { matchLabels: { app: sandbox } }
  template:
    metadata: { labels: { app: sandbox } }
    spec:
      enableServiceLinks: false
      serviceAccountName: tale-sandbox-spawner
      terminationGracePeriodSeconds: 30
      containers:
        - name: spawner
          image: ghcr.io/tale-project/tale/tale-sandbox:${VERSION}
          envFrom: [{ secretRef: { name: tale-env } }]
          env:
            - { name: SANDBOX_BACKEND, value: kubernetes }
            - { name: SANDBOX_K8S_NAMESPACE, value: tale }
            - { name: SANDBOX_RUNTIME_IMAGE, value: 'ghcr.io/tale-project/tale/tale-sandbox-runtime:${VERSION}' }
            - { name: NODE_EXTRA_CA_CERTS, value: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt }
            - { name: SANDBOX_RUNTIME, value: runc }
            - { name: SANDBOX_DOCKER_IN_CONTAINER, value: 'false' }
            - { name: SANDBOX_EGRESS_PROXY, value: 'http://sandbox-egress:3128' }
          ports: [{ name: http, containerPort: 8003 }]
          volumeMounts: [{ name: config-data, mountPath: /app/platform-config, readOnly: true }]
          startupProbe:
            httpGet: { path: /health, port: 8003 }
            periodSeconds: 5
            failureThreshold: 24
          readinessProbe:
            httpGet: { path: /health, port: 8003 }
            periodSeconds: 10
          resources:
            requests: { cpu: 100m, memory: 256Mi }
            limits: { memory: 512Mi }
      volumes:
        - name: config-data
          persistentVolumeClaim: { claimName: config-data }
```

| Paramètre | Exigence |
| --- | --- |
| `SANDBOX_BACKEND` | `kubernetes`. Les chemins hôte et noms de bridges propres à Docker ne configurent pas ce backend. |
| `SANDBOX_K8S_NAMESPACE` | Le namespace où sont créés les Pods de session, les Secrets et les claims de workspace ; dans cette organisation, celui du spawner lui-même. `tale-sandbox` par défaut. |
| `SANDBOX_RUNTIME_IMAGE` | L’image du runtime sandbox Tale correspondante, accessible à chaque nœud. |
| `NODE_EXTRA_CA_CERTS` | Le fichier CA du cluster, généralement `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt` dans le spawner. C’est le seul mécanisme de confiance CA que le spawner respecte ; garde la vérification TLS active. |
| `SANDBOX_K8S_WORKSPACE_SIZE_LIMIT` | La taille du claim de workspace `/agent` de chaque session d’agent, `4Gi` par défaut ; limite aussi le workspace temporaire d’un rendu du crawler, qui se passe de claim puisqu’il n’est jamais repris, et le stockage temporaire du Docker interne lorsqu’il est activé. |
| `SANDBOX_K8S_CPU_REQUEST` / `SANDBOX_K8S_MEMORY_REQUEST` | Ce que chaque Pod de session demande au planificateur, en quantités Kubernetes. Sans valeur, un Pod d’agent demande `250m` et `512Mi` (`1Gi` avec Docker dans la sandbox) et un rendu du crawler `250m` et `512Mi` ; une demande ne dépasse jamais la limite du Pod. Augmente-les quand les agents de tes nodes lancent des builds plus lourds, pour que le planificateur ne place pas plus de sessions qu’un node ne peut en porter. |
| `SANDBOX_K8S_CACHE_STORAGECLASS` | La StorageClass des claims de workspace ; sans valeur, celle du cluster s’applique. |
| `SANDBOX_RUNTIME` / `SANDBOX_RUNTIME_CLASS` | Un niveau de runtime pris en charge et, si nécessaire, le nom de la RuntimeClass installée. |
| `SANDBOX_EGRESS_PROXY` | Le Service de sortie utilisé par les sessions, `http://sandbox-egress:3128` par défaut. |

Le spawner se met à l’échelle horizontalement. Chaque réplica retrouve une session qu’il n’a pas créée grâce au nom déterministe de son Pod et l’adopte ; exec, arrêt et destruction fonctionnent donc via le réplica que le Service choisit. `SANDBOX_MAX_SESSIONS` compte le namespace, mais des admissions simultanées sur plusieurs réplicas peuvent le dépasser brièvement ; une ResourceQuota fournit la limite stricte. Le [contrat Kubernetes des sandboxes](https://github.com/tale-project/tale/blob/main/services/sandbox/docs/kubernetes.md) documente la forme du Pod et les détails du runtime.

### Ce que le spawner impose

Au démarrage, le spawner applique la NetworkPolicy `tale-sandbox-session-egress` : les Pods de session peuvent joindre le DNS et les Pods de leur propre namespace, rien d’autre. Le service de métadonnées du cloud, les nœuds et les autres namespaces restent ainsi inaccessibles, même pour un processus qui ignore `HTTP_PROXY`. Les destinations publiques passent par `sandbox-egress`. Une permission `networkpolicies` absente est journalisée sans arrêter le spawner ; vérifie que la politique existe avant d’admettre des traitements.

Les Pods de session exécutent le runner avec l’uid 65534, toutes les capabilities retirées, un système de fichiers racine en lecture seule, sans jeton ServiceAccount, et avec le Secret de session monté uniquement comme environnement. Le workspace `/agent` est un claim qui survit à un arrêt sur inactivité. Une destruction explicite le supprime, tout comme le nettoyage des workspaces dès que son propriétaire est retiré ou qu’il reste inutilisé au-delà de la fenêtre de l’organisation ; le nettoyage trouve les claims avec `list`. Les opérations de session utilisent HTTP vers runnerd sur l’IP du Pod, port 8200 ; `pods/exec` n’intervient jamais.

<Note>

L’autorisation à l’échelle du namespace est plus large que le réseau Compose. Depuis un Pod de session, Postgres et le stockage d’objets répondent sur leurs ports de Service, même si la session ne détient aucun identifiant pour eux. Placer ces stockages dans un autre namespace resserrerait cette barrière ; cette organisation n’a pas été vérifiée et nécessite sa propre politique pour les rôles backend.

</Note>

Pour Docker dans les sessions, choisis explicitement un `SANDBOX_DIND_INNER_POOL` hors des plages Pod, Service et VPC et lis les [prérequis réseau du Docker interne](https://docs.tale.dev/fr/self-hosted/configuration/environment-reference#sandbox-infrastructure) ; un Pod ne peut pas découvrir tous les réseaux du cluster.

## Déployer et vérifier

Après la boucle d’application, attends que chaque Pod soit prêt et contrôle les signaux qui comptent :

```bash
kubectl -n tale get pods
kubectl -n tale logs -l 'app in (backend-api,backend-worker)' --tail=-1 | grep -c 'applying app migration'
kubectl -n tale get networkpolicy tale-sandbox-session-egress tale-backend-egress
curl -s https://tale.example.com/api/health
```

Le rôle backend qui démarre en premier applique les migrations sous un verrou consultatif ; le décompte provient donc des deux rôles réunis, et le journal de l’API se termine par `api listening on :3005` ; l’endpoint de santé répond `{"status":"ok","version":"0.5.31"}`. Ouvre ensuite le site, [crée le premier propriétaire](https://docs.tale.dev/fr/self-hosted/install/first-admin) et connecte un fournisseur.

Sous **Paramètres > Sandboxes**, la carte du déploiement porte le namespace comme périmètre dans son titre et n’affiche aucune mesure CPU ou mémoire de l’hôte ; c’est attendu sur ce backend. Assigne une tâche à un agent et attends son livrable : l’exécution crée dans le namespace un Pod de session nommé `tale-sbx-ses-<hash>`, accompagné d’un Secret `-spec` et d’un claim `-ws`.

Prouve la barrière depuis un Pod de session en cours :

```bash
POD=$(kubectl -n tale get pods -l tale.sandbox/role=session -o name | head -1)
kubectl -n tale exec $POD -c runner -- curl -m 5 http://169.254.169.254/
kubectl -n tale exec $POD -c runner -- curl -m 20 -s -o /dev/null -w '%{http_code}\n' https://example.com/
```

La première commande expire ; la seconde affiche `200`, obtenu via le proxy de sortie. Teste ensuite le cycle de vie tel que tu t’y fieras en exploitation : un redémarrage du runner conserve le Pod et le workspace, une session inactive s’arrête après `SANDBOX_SESSION_MAX_IDLE_MS` en laissant son claim, la tâche suivante la reprend avec ses fichiers intacts, et sa destruction supprime le Pod, le Secret et le claim. Avec deux réplicas du spawner, relance une tâche après la mise à l’échelle et confirme que le second réplica la sert.

Mets à jour l’API sans interruption en conservant deux réplicas et en redémarrant le Deployment :

```bash
kubectl -n tale rollout restart deploy/backend-api
kubectl -n tale rollout status deploy/backend-api
```

Les migrations s’exécutent au démarrage sous un verrou consultatif pendant que l’image précédente continue de servir ; l’endpoint de santé reste vert pendant toute la mise à jour. Fixe une seule `VERSION` pour toutes les images Tale et suis [Mettre à niveau et rétablir un déploiement](https://docs.tale.dev/fr/self-hosted/operate/upgrades) avant de la changer ; une version qui modifie l’image du proxy exige aussi de recréer le Pod du proxy.

Les snapshots, bascules bleu-vert et contrôles de rollback de la CLI ne s’exécutent pas sur Kubernetes. Sauvegarde les claims avec les snapshots de ton fournisseur de stockage et conserve avec eux le Secret, la clé de chiffrement et la configuration des organisations ; [Sauvegardes et restauration](https://docs.tale.dev/fr/self-hosted/operate/backups-and-restore) liste ce qu’une restauration exige.

## Périmètre vérifié

Ces cinq fichiers ont été appliqués tels quels, à l’exception des valeurs du Secret, sur un cluster kind neuf à un seul nœud, avec Kubernetes 1.36, kube-network-policies, la StorageClass local-path et Tale 0.5.31 : démarrage et migrations, point d’entrée public, création du premier propriétaire et carte Sandboxes, tâche d’agent avec livrable, cycle de vie des sessions avec arrêt sur inactivité, reprise et accès entre réplicas, les sondes de barrière ci-dessus et un redémarrage progressif de l’API à deux réplicas. La planification sur plusieurs nœuds avec un stockage de configuration `ReadWriteMany`, Docker dans les sessions sur une RuntimeClass sysbox ou kata, un Ingress avec `TLS_MODE=external` et des stockages hautement disponibles ne faisaient pas partie de cet essai.

# Gérer Compose toi-même
Source: https://docs.tale.dev/fr/self-hosted/install/own-compose

Utilise cette référence si ton équipe maintient les fichiers et le processus de déploiement. Le [démarrage rapide CLI](https://docs.tale.dev/fr/self-hosted/install/quickstart) est plus court si tu veux que Tale génère les fichiers et coordonne les mises à niveau. Il n’existe pas de chart Helm officiel. Le spawner sandbox prend en charge Docker et Kubernetes ; choisis la configuration réseau et le runtime adaptés.

Cette page décrit le contrat de déploiement avec un exemple de couche applicative, pas un Compose complet prêt à démarrer. Assemble et valide stockage, proxy et sandbox avant d’utiliser cet exemple.

## Choisir la répartition des services

| Groupe | Services | Cycle de vie |
| --- | --- | --- |
| Application réplicable | `platform`, `backend-api`, `backend-worker` | Même image et release ; conserver des interfaces compatibles pendant le remplacement. |
| Stockages persistants et entrée | `db`, `object-store`, `proxy` | Préserver volumes, identifiants, certificats et noms réseau stables lors du remplacement. |
| Exécution partagée | `sandbox`, `sandbox-egress`, `sandbox-llm-gateway` | Coordonner les sessions actives avant remplacement ; le spawner demande le daemon Docker et des chemins de workspace correspondants. |
| Vidéo facultative | `bgutil-provider` | Fournisseur de jetons démarré au mieux ; sa panne peut affecter les récupérations vidéo. |

Le montage fourni conserve `tale_app` et `tale_knowledge` dans un service Postgres avec l’alias `knowledge-db`. Des bases séparées ou gérées sont aussi possibles ; configure explicitement connexions et sauvegardes. Recréer un conteneur persistant ne détruit pas automatiquement ses données, mais retirer ou remplacer son volume peut le faire.

## Fixer des images compatibles

Définis `VERSION` dans le `.env` de Compose avec la release Tale examinée et testée. Exporte la même valeur dans le shell pour le téléchargement séparé de l’image d’exécution plus bas. Garde les images Tale sur une release commune ; les deux services utilisant des images amont ont leurs propres versions.

| Service | Image |
| --- | --- |
| `platform`, `backend-api`, `backend-worker` | `ghcr.io/tale-project/tale/tale-platform:<version>` |
| `proxy` | `ghcr.io/tale-project/tale/tale-proxy:<version>` |
| `db` | `ghcr.io/tale-project/tale/tale-db:<version>` |
| `sandbox` | `ghcr.io/tale-project/tale/tale-sandbox:<version>` |
| `sandbox-egress` | `ghcr.io/tale-project/tale/tale-sandbox-egress:<version>` |
| `sandbox-llm-gateway` | `ghcr.io/tale-project/tale/tale-sandbox-llm-gateway:<version>` |
| `object-store` | `ghcr.io/tale-project/ops/minio:RELEASE.2025-04-22T22-12-26Z` |
| `bgutil-provider` | `brainicism/bgutil-ytdlp-pot-provider:1.3.1` |

Les sessions utilisent aussi `ghcr.io/tale-project/tale/tale-sandbox-runtime:<version>`. Définis `SANDBOX_RUNTIME_IMAGE` sur le spawner et télécharge-la avant le démarrage. Le tag local de développement par défaut ne suffit pas sur un hôte qui ne l’a jamais construite. Si tu actives Docker dans les conteneurs ou le cache de build partagé, prépare aussi les images compatibles de la [référence d’environnement](https://docs.tale.dev/fr/self-hosted/configuration/environment-reference).

## Préparer secrets et adresses publiques

Génère des valeurs uniques avant le premier démarrage et conserve-les dans ton gestionnaire de secrets. Ne copie pas les identifiants d’exemple d’un environnement de développement en production.

| Valeur | Exigence |
| --- | --- |
| `BETTER_AUTH_SECRET` | Secret d’authentification stable à forte entropie. |
| `ENCRYPTION_SECRET_HEX` | Valeur hexadécimale de 32 octets, par exemple via `openssl rand -hex 32` ; la conserver pour les valeurs déjà chiffrées en base. |
| `DB_PASSWORD` ou identifiants de base externe | Correspondre au rôle réellement utilisé par le backend. |
| `SANDBOX_TOKEN` | Même jeton aléatoire dans le backend et le spawner. |
| `SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD` | Même secret stable dans le backend et la passerelle ; une passerelle sans compte d’administration n’en crée un que pour un appelant qui présente ce secret. Le nom d’utilisateur vaut `admin` par défaut. |
| `OBJECT_STORE_ACCESS_KEY`, `OBJECT_STORE_SECRET_KEY` | Identifiants valides pour le stockage ; les mapper sur `MINIO_ROOT_USER` et `MINIO_ROOT_PASSWORD` pour MinIO. |
| `OBJECT_STORE_PUBLIC_ENDPOINT` | Point d’accès joignable par le navigateur, généralement `SITE_URL` lorsque le proxy relaie le stockage fourni. |
| Identité age SOPS | Nécessaire aux fichiers de configuration chiffrés ; voir [Secrets avec SOPS](https://docs.tale.dev/fr/self-hosted/configuration/secrets-with-sops). |

Le backend synchronise au démarrage la connexion objet par défaut gérée par l’environnement. Il laisse volontairement intact un fichier `managedBy: operator`. Changer les identifiants ne déplace pas les objets et ne les rend pas intrinsèquement orphelins, mais backend et stockage doivent être d’accord. La passerelle conserve son hash de mot de passe établi ; retrouve le secret correspondant ou suis sa procédure de rotation au lieu de supprimer le volume comme dépannage courant.

Définis `HOST`, `SITE_URL` et `TLS_MODE` pour l’accès public. [TLS et domaines](https://docs.tale.dev/fr/self-hosted/configuration/tls-and-domains) traite les certificats, origines supplémentaires et sous-chemins.

## Assembler la couche applicative

Les trois rôles partagent une image. `TALE_ROLE=api` et `TALE_ROLE=worker` choisissent les rôles backend ; laisse cette variable absente du service web. Ne fixe pas de `container_name` sur les rôles à répliquer.

```yaml
# Application-tier fragment; add the stores, proxy, and sandbox services.
# No container_name on replicated services.
services:
  platform:
    image: ghcr.io/tale-project/tale/tale-platform:${VERSION}
    env_file: [.env]
    volumes: ['config-data:/app/data:ro']
    restart: unless-stopped
    stop_grace_period: 45s
    healthcheck:
      test:
        [
          'CMD-SHELL',
          'curl -sf http://localhost:3000/api/health && [ -f /tmp/platform-ready ]',
        ]
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 180s
    networks:
      internal:
        aliases: [platform]
  backend-api:
    image: ghcr.io/tale-project/tale/tale-platform:${VERSION}
    environment:
      TALE_ROLE: api
      PORT: '3005'
      TALE_CONFIG_DIR: /app/data
      DATABASE_URL: ${DATABASE_URL:-postgresql://tale:${DB_PASSWORD:?required}@db:5432/tale_app}
      SANDBOX_URL: http://sandbox:8003
      SANDBOX_HTTP_API_BASE_URL: http://backend-api:3005
      OBJECT_STORE_ENDPOINT: ${OBJECT_STORE_ENDPOINT-http://object-store:9000}
    env_file: [.env]
    volumes: ['config-data:/app/data']
    cap_add: [NET_ADMIN]
    restart: unless-stopped
    healthcheck:
      test: ['CMD-SHELL', 'curl -sf http://localhost:3005/ping']
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 30s
    networks:
      internal:
        aliases: [backend-api]
      sandbox:
        aliases: [backend-api]
  backend-worker:
    image: ghcr.io/tale-project/tale/tale-platform:${VERSION}
    environment:
      TALE_ROLE: worker
      TALE_CONFIG_DIR: /app/data
      DATABASE_URL: ${DATABASE_URL:-postgresql://tale:${DB_PASSWORD:?required}@db:5432/tale_app}
      SANDBOX_URL: http://sandbox:8003
      SANDBOX_HTTP_API_BASE_URL: http://backend-api:3005
      OBJECT_STORE_ENDPOINT: ${OBJECT_STORE_ENDPOINT-http://object-store:9000}
    env_file: [.env]
    volumes: ['config-data:/app/data']
    cap_add: [NET_ADMIN]
    restart: unless-stopped
    healthcheck: { disable: true }
    networks: [internal]
volumes:
  config-data:
networks:
  internal:
  sandbox:
    name: tale-sandbox-net
    internal: true
    enable_ipv6: false
```

Les entrées `environment` remplacent `env_file`. Le fragment conserve donc les valeurs externes de base et de stockage au lieu d’imposer les adresses fournies. Dans un projet Compose unique, ajoute des dépendances de santé ; entre projets, ton orchestrateur doit imposer l’ordre de démarrage.

## Préserver les noms réseau et l’isolation

| Adresse | Destination et exigence réseau |
| --- | --- |
| `platform` | Réplicas web sur le réseau applicatif interne. Ils atteignent le backend via `TALE_BACKEND_URL`, `http://backend-api:3005` si tu ne la définis pas. |
| `backend-api` | Réplicas API sur les réseaux applicatif et sandbox, port 3005. |
| `knowledge-db` | Postgres de connaissances, ou une cible définie par `KNOWLEDGE_DATABASE_URL`. |
| `object-store` | MinIO fourni sur le réseau applicatif. |
| `sandbox` | Spawner accessible au backend sur le port 8003. |
| `sandbox-egress` | Proxy de sortie accessible aux sessions sur le port 3128. |
| `sandbox-llm-gateway` / `llm-gateway` | Passerelle accessible au backend et aux sessions sur le port 8080. |
| `bgutil-provider` | Fournisseur de jetons accessible au worker sur le port 4416. |

Le réseau sandbox doit être isolé des sorties directes. Le stack généré le nomme `tale-sandbox-net` ; si tu choisis un autre nom, garde `SANDBOX_EGRESS_NETWORK` cohérent avec le réseau réel. La sortie doit toujours passer par `sandbox-egress`.

Configure `BACKEND_UPSTREAM=backend-api:3005` sur le proxy. Pour le stockage fourni, définis `OBJECT_STORE_UPSTREAM=object-store:9000` et le même `OBJECT_STORE_BUCKET` dans le proxy et le backend. Publie les ports 80/443 du proxy ; garde bases, administration du stockage, passerelle et API sandbox privées. Préserve un transfert fiable des informations client si un autre proxy se trouve en amont.

## Monter l’état persistant et les capacités requises

| Ressource | Montages ou réglages requis |
| --- | --- |
| Configuration des organisations | `config-data:/app/data` en lecture-écriture dans les rôles backend, en lecture seule dans `platform` ; en lecture seule sous `/app/platform-config` dans le spawner. |
| Données applicatives et connaissances fournies | `db-data:/var/lib/postgresql/data` ; un service de connaissances séparé demande son propre volume persistant. |
| Stockage objet fourni | `object-store-data:/data` et MinIO `command: server /data`. |
| Certificats et état du proxy | `caddy-data:/data`, `caddy-config:/config`. |
| État de passerelle | `llm-gateway-data:/app/data`. |
| Spawner | `/var/run/docker.sock` et `/var/lib/tale-sandbox` montés aux mêmes chemins hôte/conteneur. Le socket Docker donne le contrôle du daemon de l’hôte. |
| Rôles backend | `cap_add: [NET_ADMIN]` pour le filtrage réseau du point d’entrée fourni. |
| Service de sortie | Après retrait de toutes les autres capacités : `NET_ADMIN`, `DAC_OVERRIDE`, `CHOWN`, `SETUID`, `SETGID`, `NET_BIND_SERVICE` et `KILL`. Sans `KILL`, le superviseur root ne peut plus signaler tinyproxy une fois passé à `nobody` : un arrêt attend la fin du délai de grâce et se termine en exit 137 au lieu de se vider proprement. |
| IPv6 de sortie | `sysctls` avec `net.ipv6.conf.all.disable_ipv6: '1'` et `net.ipv6.conf.default.disable_ipv6: '1'`, comme dans le stack fourni. Le pare-feu egress fonctionne en fail-closed : il exige un pare-feu IPv6 fonctionnel ou IPv6 désactivé pour la valeur par défaut et chaque interface, et un conteneur ne peut pas écrire ces sysctls lui-même à travers un `/proc/sys` en lecture seule. Sans elles, le proxy refuse de démarrer sur un noyau sans le module `ip6_tables` ; voir [Infrastructure sandbox](https://docs.tale.dev/fr/self-hosted/configuration/environment-reference#sandbox-infrastructure). |
| Arrêt Postgres | `stop_signal: SIGINT`, `stop_grace_period: 60s`, `shm_size: 256mb` dans la référence. |
| Arrêt web et spawner | Délais de grâce de 45 secondes pour le web, 30 pour le spawner ; coordonner le travail actif avant l’arrêt. |

Conserve `db-backup` si tes outils écrivent dans `/var/lib/postgresql/backup` ; un montage seul ne programme aucune sauvegarde. Les anciens volumes de configuration `convex-data` demandent un transfert délibéré vers `config-data`, pas leur suppression. Garde l’ancienne copie jusqu’à vérification.

## Utiliser les bonnes sondes

| Service | Sonde | Signification |
| --- | --- | --- |
| `backend-api` | `curl -sf http://localhost:3005/ping` | Processus actif ; reste disponible pendant le drainage. |
| `backend-api` | `GET /ready` sur le port 3005 | Acceptation de nouveau travail, distincte de la santé des stockages externes. |
| `platform` | `curl -sf http://localhost:3000/api/health && [ -f /tmp/platform-ready ]` | Démarrage web terminé. |
| `backend-worker` | Désactiver la sonde web de l’image. | Aucun serveur HTTP ; surveiller les jobs et la progression séparément. |
| `proxy` | `curl -sf http://127.0.0.1:2020/health` | Le proxy répond. |
| `db` | `pg_isready -U tale && [ -f /tmp/.db_ready ]` | Postgres et initialisation prêts ; adapter l’utilisateur. |
| `object-store` | `mc ready local` | Disponibilité du MinIO fourni. |
| `sandbox` | `curl -fsS http://127.0.0.1:8003/health` | Spawner prêt après préparation de l’image d’exécution. |
| `sandbox-egress` | `curl -sS -o /dev/null --max-time 3 --noproxy '*' http://127.0.0.1:3128/` | Le proxy répond lui-même à une requête non proxy (page 400) : cela prouve qu’il sert, sans dépendance à un site tiers. Ne sonde pas le port par une simple connexion TCP : tinyproxy journalise chaque connexion-fermeture comme une erreur, une ligne par intervalle. |
| `sandbox-llm-gateway` | `wget -q -O /dev/null http://127.0.0.1:8080/health` | Utiliser le client présent dans l’image ; elle ne contient pas `curl`. |

Prévois assez de temps pour un démarrage à froid : le téléchargement de l’environnement sandbox peut dépasser un délai adapté à un hôte déjà préparé. Une sonde réussie ne prouve ni accès aux fichiers, ni identifiants de modèle, ni parcours utilisateur complet. Vérifie-les séparément.

## Connecter des stockages externes

Une base applicative externe remplace `DATABASE_URL` ; les connaissances utilisent `KNOWLEDGE_DATABASE_URL`. Cette dernière demande pgvector et, pour la recherche hybride complète, pg_search. Fournis une connexion compatible avec les sessions et, si nécessaire, `POSTGRES_CA_FILE`. Ne suppose pas qu’un pooler par transaction conserve le comportement requis.

Pour un stockage compatible S3 externe, définis explicitement `OBJECT_STORE_*` et le point d’accès navigateur. AWS S3 peut utiliser un point d’accès personnalisé vide ; d’autres stockages demandent path-style. Prépare permissions et CORS, puis teste réellement envoi et téléchargement. Retire seulement les services fournis devenus inutiles et leurs références `depends_on`. Garde les anciens volumes jusqu’à validation de la migration.

Changer les URL ne migre pas les lignes ou fichiers existants. [Résidence des données](https://docs.tale.dev/fr/self-hosted/configuration/data-residency) décrit les choix par organisation et déploiement. Les stockages externes exigent des sauvegardes coordonnées hors des archives de volumes de `tale backup`.

## Démarrer et valider l’installation

Démarre les stockages avant leurs dépendants et utilise des règles de redémarrage comme `unless-stopped`. Prépare `VERSION` dans le shell comme indiqué plus haut, puis valide ton Compose complet :

```bash
docker compose config --quiet
docker pull "ghcr.io/tale-project/tale/tale-sandbox-runtime:$VERSION"
docker compose up -d
docker compose ps
docker compose logs --tail=100 backend-api backend-worker
```

Confirme santé des services, migrations backend réussies et progression des workers. Ouvre l’URL publique, suis [Premier administrateur](https://docs.tale.dev/fr/self-hosted/install/first-admin), configure fournisseur et modèle d’embedding, puis teste de façon contrôlée chat, import/téléchargement et recherche. Si tu utilises des harnesses, vérifie aussi une session sandbox.

Les migrations de base s’exécutent au démarrage du backend. Ton processus doit maintenir des versions compatibles pendant cette étape, s’arrêter en cas d’échec, drainer le travail actif avant remplacement et conserver l’état nécessaire à la reprise. Copier la répartition des services n’active pas la coordination bleu-vert, la reprise de bascule, les snapshots automatiques ni les contrôles de rollback de la CLI.

## Transposer le contrat à Kubernetes

[Déployer sur Kubernetes](https://docs.tale.dev/fr/self-hosted/install/kubernetes) transpose ce contrat en Deployments, Services, StatefulSets et NetworkPolicies, bascule le spawner de sandbox sur `SANDBOX_BACKEND=kubernetes` et liste les vérifications qu’un cluster doit réussir avant d’accueillir des utilisateurs. Cette page reste la référence pour les noms de services, les volumes, les sondes et les variables d’environnement que les objets Kubernetes doivent reproduire.

# Démarrer ta première instance auto-hébergée
Source: https://docs.tale.dev/fr/self-hosted/install/quickstart

Démarre Tale localement avec la CLI publiée, puis crée ton espace de travail et envoie un message. Tu n’as pas besoin de cloner le dépôt, d’installer Bun ou de compiler l’application. La CLI télécharge les images des conteneurs et prépare la configuration.

## Préparer la machine locale

Il te faut :

- macOS, Linux ou Windows avec PowerShell, ainsi que Docker exécutant des conteneurs Linux avec Compose. Docker Desktop inclut Compose sur macOS et Windows. Si Docker manque, `tale dev` propose de t’aider à l’installer.
- Un accès réseau à GitHub pour la CLI et aux registres de conteneurs pour les images. Le premier démarrage télécharge plusieurs Go ; prévois de la place pour les images et tes données.
- Les identifiants d’un fournisseur de modèles compatible pour tester la première réponse. Tu peux créer ton compte et explorer l’application avant de connecter un fournisseur.

Sur ARM64, y compris Apple Silicon, le stockage objet fourni nécessite l’émulation amd64. Docker Desktop l’inclut ; sur un hôte Linux avec Docker autonome, tu dois la configurer séparément. Vérifie les [prérequis d’architecture](https://docs.tale.dev/fr/self-hosted/install/cli-install#avant-de-commencer) avant de démarrer sur ARM64 Linux.

Le port HTTPS par défaut est `443` ; le service sandbox utilise aussi `127.0.0.1:8003`. Garde l’instance privée jusqu’à la création de son compte propriétaire.

## Installer la CLI

Choisis l’installateur adapté à ton système :

<Tabs>

<Tab title="macOS / Linux">

```bash
curl -fsSL https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.sh | bash
```

</Tab>

<Tab title="Windows (PowerShell)">

```powershell
irm https://raw.githubusercontent.com/tale-project/tale/main/scripts/install-cli.ps1 | iex
```

</Tab>

</Tabs>

Vérifie l’installation avec `tale --version` dans le même terminal. Si la commande est introuvable, suis les indications de l’installateur pour le `PATH` et rouvre les terminaux déjà ouverts. Le [guide CLI](https://docs.tale.dev/fr/self-hosted/install/cli-install) couvre les versions fixées et le choix du répertoire d’installation.

Consulte `tale --help` avant d’utiliser `tale doctor`. Si `doctor` n’y figure pas, lance `docker info` et `docker compose version` pour vérifier Docker et Compose. Lorsqu’elle est disponible, la commande `tale doctor` examine aussi l’architecture des conteneurs et les ports locaux sans installer de logiciel ni modifier de fichiers. Suis les solutions proposées ; un résultat positif ne vérifie ni les téléchargements d’images ni l’accès aux modèles.

## Initialiser et démarrer

Choisis où conserver ton projet, puis exécute :

```bash
tale init my-project
cd my-project
tale dev
```

`tale init` crée le projet et un fichier `.env` privé contenant les secrets générés. Sauvegarde ce fichier et ses clés de chiffrement en lieu sûr. À la question sur Docker dans les sandboxes, conserve le choix désactivé par défaut tant que tes agents n’ont pas besoin de Docker : son activation autorise Docker imbriqué avec privilèges.

`tale dev` démarre les conteneurs et affiche l’adresse lorsque l’application est prête. Laisse la commande tourner pendant les premiers téléchargements et la préparation de la base de données. Ouvre l’URL affichée, normalement `https://localhost`. Le certificat local est autosigné ; vérifie que l’adresse correspond à ta propre instance avant d’accepter l’avertissement du navigateur.

<Note>

Le répertoire généré `default/` contient des exemples de catalogue et des entrées installées automatiquement. Tu n’as pas besoin de le modifier pour ce premier démarrage. Son `README.md` explique quelles modifications de configuration affectent une organisation.

</Note>

## Créer le propriétaire et tester une réponse

1. Suis l’assistant pour créer ton compte et nommer l’organisation. Ce premier compte devient son **Propriétaire**. [Premier compte propriétaire](https://docs.tale.dev/fr/self-hosted/install/first-admin) explique comment vérifier ce rôle et utiliser un compte existant.
2. Après la configuration, ouvre **Paramètres > Fournisseurs IA** et ajoute des identifiants compatibles. La dernière page de l’assistant mène aussi aux paramètres des fournisseurs. Consulte [Fournisseurs IA](https://docs.tale.dev/fr/platform/admin/providers) pour les champs et les méthodes d’authentification prises en charge.
3. Ouvre **Accueil**, choisis **Nouveau chat**, sélectionne un modèle disponible et envoie une courte demande, par exemple « Écris une liste de trois points pour préparer une réunion. » Attends la fin de la réponse.

Une réponse complète confirme que le compte, le fournisseur et le modèle choisi fonctionnent ensemble. Si la liste des modèles est vide ou que la demande échoue, consulte les solutions du guide des fournisseurs. [Envoyer ton premier message](https://docs.tale.dev/fr/get-started/quickstart) explique comment poursuivre et retrouver la conversation. Quand tu souhaites déléguer du travail dans un projet, [crée ton premier agent](https://docs.tale.dev/fr/tutorials/editor/first-agent-end-to-end).

## Arrêter et reprendre plus tard

Appuie sur `Ctrl-C` dans le terminal qui exécute `tale dev` pour arrêter l’instance au premier plan. Relance `tale dev` depuis le même répertoire de projet pour reprendre avec les données existantes.

Consulte `tale dev --help` avant d’utiliser les commandes ci-dessous pour le fonctionnement en arrière-plan. Si `--stop` n’y figure pas, garde `tale dev` au premier plan et arrête-le avec `Ctrl-C`.

```bash
tale dev --detach
tale dev --stop
```

L’arrêt conserve le projet, les secrets et les données persistantes. Continue à utiliser le même répertoire ; créer un nouveau projet démarre une instance distincte.

## Résoudre les problèmes de démarrage

| Symptôme | Action suivante |
| --- | --- |
| `tale` est introuvable | Vérifie le répertoire d’installation et le `PATH` ; sous Windows, ouvre un nouveau terminal. |
| Docker ne démarre pas | Ouvre Docker Desktop ou démarre le daemon. Vérifie que `docker info` fonctionne dans le même terminal, puis réessaie. |
| Compose manque | Vérifie `docker compose version` ; installe le plugin Compose ou mets Docker Desktop à jour. |
| Une image se télécharge lentement ou échoue | Vérifie l’erreur réseau ou du registre et l’espace disque libre. Après correction, relance `tale dev` dans le même répertoire. |
| Le port HTTPS est occupé | Vérifie quel processus utilise le port `443`. Avec la CLI publiée en version v0.5.70, libère ce port avant de réessayer. |
| Le port `8003` est occupé | Arrête l’autre instance Tale locale ou le service qui utilise ce port. `--port` ne change que HTTPS. |
| Un conteneur redémarre en boucle | Lance `tale status`, puis `tale logs backend-api --tail 100` ou `tale logs platform --tail 100`. Cherche la cause dans les logs du service signalé. |
| La connexion apparaît à la place de la configuration initiale | Un compte existe déjà. Connecte-toi avec ce compte ; ne réinitialise pas les données pour répéter la configuration. |
| L’application s’ouvre sans réponse du modèle | Vérifie les identifiants et le modèle choisi sous **Paramètres > Fournisseurs IA**. |

Réessaie après avoir corrigé la cause signalée ; conserve `.env` et les volumes de données. Si le problème persiste, suis le guide de [dépannage](https://docs.tale.dev/fr/self-hosted/operate/observability/troubleshooting) et indique la version de la CLI ainsi que l’erreur pertinente dans ta demande d’aide. Retire les identifiants des logs avant de les partager.

## Préparer la production

`tale deploy` applique la configuration du projet sur l’hôte Docker choisi. Le développement et le déploiement utilisent des volumes distincts : le compte local, les chats et les fichiers téléversés ne sont pas transférés. Prépare DNS, TLS, sauvegardes et contrôles d’accès avant d’ajouter ton équipe.

Lis [TLS et domaines](https://docs.tale.dev/fr/self-hosted/configuration/tls-and-domains), [Sauvegardes et restauration](https://docs.tale.dev/fr/self-hosted/operate/backups-and-restore) et [Renforcement](https://docs.tale.dev/fr/self-hosted/operate/security/hardening). Si tu dois maintenir toi-même les définitions des services, utilise [Exécuter ton propre Compose](https://docs.tale.dev/fr/self-hosted/install/own-compose).

# Sauvegardes et restauration
Source: https://docs.tale.dev/fr/self-hosted/operate/backups-and-restore

Une instance Tale récupérable demande plus qu’une archive de base de données. Conserve ses fichiers, la configuration des organisations, le dossier de déploiement et les clés de déchiffrement, avec la version qui a écrit les données. Définis d’abord la perte de données et la durée de reprise acceptables, puis vérifie que tes sauvegardes et ta procédure respectent ces objectifs.

Ce guide couvre les snapshots de volumes Docker de la CLI utilisée dans un workspace. Si tu gères Compose toi-même, prévois une sauvegarde des mêmes stockages. Les bases et buckets externes exigent des sauvegardes séparées et coordonnées.

## Préparer un hôte de reprise vide

Récupère le workspace d’origine et vérifie que ta connexion Docker vise l’hôte de reprise. Garde les services arrêtés. Remplace `your-project-id` ci-dessous par l’ID d’origine de `tale.json`. Pour un snapshot de développement, utilise plutôt `TALE_RESTORE_PREFIX="${TALE_RESTORE_PROJECT}-dev_"`. Les noms de production et de développement sont distincts ; si les deux existent, la CLI choisit la production en premier.

```bash
TALE_RESTORE_PROJECT=your-project-id
TALE_RESTORE_PREFIX="${TALE_RESTORE_PROJECT}_"
docker volume create --label "project=$TALE_RESTORE_PROJECT" "${TALE_RESTORE_PREFIX}config-data"
docker volume create --label "project=$TALE_RESTORE_PROJECT" "${TALE_RESTORE_PREFIX}backups"
docker volume inspect "${TALE_RESTORE_PREFIX}backups"
```

Ces commandes préparent les volumes de configuration et de sauvegarde sans démarrer de backend ni appliquer de migration. Avec ton système de sauvegarde, restaure le contenu complet de `backups` dans ce volume. Le point de montage affiché appartient à l’hôte Docker, qui peut être distant. Conserve la structure des répertoires et les manifestes des snapshots. `tale restore` doit ensuite afficher le snapshot attendu. Pendant la restauration effective, la CLI crée les autres volumes cibles manquants après avoir vérifié le snapshot.

## Vérifier la portée du snapshot

`tale backup` capture les volumes du projet présents dans cet inventaire :

| Volume | Données incluses |
| --- | --- |
| `db-data` | Données applicatives et, dans le stack fourni pour un hôte, base de connaissances. |
| `knowledge-db-data` | Base de connaissances séparée lorsque ce volume existe, notamment avec Compose depuis les sources. |
| `config-data` | Configuration des organisations, fichiers de secrets associés pris en charge et identité visuelle. Les identifiants de fournisseurs stockés dans Postgres font partie de la sauvegarde de la base. |
| `object-store-data` | Fichiers importés et médias générés lorsque le stockage par défaut utilise le service fourni. |
| `caddy-data`, `caddy-config` | Certificats et état du proxy. |
| `llm-gateway-data` | Le stockage de la passerelle de modèles : son compte d’administration, les clés des fournisseurs, les clés de session avec leurs budgets et leurs dépenses, et son journal des requêtes. |

Un snapshot contient une archive et son fichier de somme SHA-256 pour chaque volume capturé. `manifest.json`, écrit en dernier, indique la version de la plateforme lorsqu’elle peut être déterminée. Un dossier sans manifeste est incomplet : il ne figure pas dans la liste de restauration et la rotation peut le supprimer après la création d’un snapshot complet plus récent. Les snapshots pris avant que la CLI capture le stockage de la passerelle ne contiennent pas d’archive de `llm-gateway-data`.

Conserve aussi le workspace qui contient `tale.json`, son `.env` et les fichiers de clés montés séparément. Garde notamment `ENCRYPTION_SECRET_HEX` et l’identité age nécessaire aux fichiers SOPS. Les espaces de travail des sandbox ne font pas partie de cet inventaire ; ajoute-les à ton plan si tu dois conserver leur état.

<Warning>

Les données Postgres externes ne sont pas capturées, même si un volume de base locale inutilisé apparaît encore dans le snapshot. La CLI n’avertit pas de cette configuration. Les buckets externes sont également exclus ; la CLI signale un bucket par défaut redirigé ou les buckets propres aux organisations qu’elle détecte. Vérifie les connexions de stockage de chaque organisation avant de considérer la couverture comme complète.

</Warning>

## Créer et vérifier un snapshot

Exécute ces commandes dans le dossier du déploiement concerné :

```bash
tale status
tale backup
tale restore
```

`backup` affiche le résultat. Sans identifiant, `restore` liste seulement les snapshots disponibles, leur version enregistrée et l’éventuelle absence des fichiers ou du stockage de la passerelle. Note l’identifiant du snapshot avec ceux des sauvegardes externes.

Pendant l’archivage d’un volume, le processus suspend les conteneurs qui l’utilisent. Les imports, téléchargements, opérations de base et appels de modèle passant par la passerelle peuvent attendre pendant cette pause, dont la durée dépend de la quantité de données et du débit. Docker signale un conteneur suspendu comme `unhealthy` jusqu’à ce que sa sonde réussisse de nouveau. Après chaque archive, le processus attend donc que chaque conteneur sain avant la pause soit de nouveau signalé comme `healthy`, ce qui prend en général un intervalle de sonde. Si un conteneur ne se rétablit pas dans la limite des tentatives que permet sa sonde, le snapshot échoue. Ces archives correspondent à un état de reprise après arrêt brutal par volume, pas à une transaction atomique entre tous les stockages. Pour obtenir un point de reprise coordonné, arrête les écritures et tâches planifiées ou utilise une fenêtre de maintenance qui couvre aussi les stockages externes.

Un `tale deploy` qui change de version ou remplace la configuration de l’hôte prend un snapshot avant ses modifications. L’échec du snapshot interrompt ce déploiement. `--skip-backup` contourne cette protection ; utilise cette option uniquement si ton plan de reprise fournit déjà la sauvegarde nécessaire.

## Conserver une copie hors de l’hôte

Les snapshots résident dans le volume Docker `backups` du projet. Une panne de l’hôte ou du disque peut détruire les données et les snapshots locaux ensemble. Copie les snapshots complets, la configuration du workspace et les clés dans ton système de sauvegarde externe protégé. Tale ne les transfère pas pour toi.

Utilise l’identifiant de projet de `tale.json` pour trouver le volume :

```bash
docker volume inspect <project-id>_backups
```

Le chemin de montage appartient à l’hôte Docker, qui peut être une VM ou une machine distante. Configure ton agent de sauvegarde à cet endroit sans supposer que le chemin existe sur ton poste. Vérifie que la copie externe contient `manifest.json`, toutes les archives qu’il cite et leurs fichiers de somme de contrôle.

La rotation locale garde les cinq snapshots les plus récents **et** ceux des 14 derniers jours. Un snapshot n’est supprimé que s’il dépasse les deux limites. Modifie `BACKUP_KEEP_COUNT` et `BACKUP_KEEP_DAYS` dans `.env` pour ajuster ces fenêtres ; configure séparément la rétention des copies externes.

## Restaurer les données et leur version

<Warning>

La restauration remplace le contenu des volumes inclus. Préserve l’état actuel si tu peux en avoir besoin et vérifie le workspace cible. Garde utilisateurs et intégrations planifiées à l’écart de l’environnement de reprise jusqu’à sa validation.

</Warning>

1. Récupère le snapshot complet, le dossier de déploiement, les clés correspondantes et les sauvegardes externes. Sur un nouvel hôte, suis d’abord la préparation décrite plus haut.
2. Lance `tale restore` pour choisir un identifiant et lire sa version de plateforme. Si elle est inconnue, retrouve-la dans tes traces de déploiement avant de démarrer l’application.
3. Restaure avec le stack arrêté. `--stop` arrête les conteneurs du projet ; la CLI vérifie ensuite les sommes de contrôle et demande confirmation avant de remplacer les données. Utilise ta CLI actuelle, avant que l’étape 5 la change : une CLI antérieure à la capture du stockage de la passerelle ignore son archive.

```bash
tale restore <snapshot-id> --stop
```

4. Restaure les bases et buckets externes au point de reprise coordonné, sans rouvrir le trafic. Un snapshot marqué `without blobs` laisse le volume local de fichiers existant intact. Un snapshot marqué `without gateway` laisse `llm-gateway-data` intact et ne peut pas ramener la passerelle au stockage qu’elle avait avant sa mise à niveau ; la CLI le signale avant de demander confirmation. Si la passerelle a été mise à niveau après ce snapshot, remets ta propre copie du volume en place avant l’étape suivante, comme l’explique [Mises à niveau](https://docs.tale.dev/fr/self-hosted/operate/upgrades).
5. Sélectionne la version indiquée dans le snapshot et déploie-la, y compris les services persistants :

```bash
tale update --version <snapshot-platform-version>
tale deploy --stop
tale status
```

La version compte : un backend plus récent peut appliquer des migrations dès son démarrage. Restaurer les données puis lancer une image actuelle choisie arbitrairement ne rétablit pas l’état enregistré. La CLI restaure les anciennes archives de configuration `convex-data` dans le volume actuel `config-data`.

## Valider la reprise avant de rouvrir le trafic

Lors d’un exercice isolé, connecte-toi, ouvre une conversation connue, télécharge un ancien fichier, vérifie la configuration d’une organisation et lance une recherche contrôlée dans les connaissances. Vérifie l’accès aux secrets des fournisseurs et aux stockages externes sans déclencher de notifications ou d’automatisations de production. Note la période de données perdue, le temps de reprise et chaque étape manuelle.

Répète l’exercice après une modification importante du stockage, des clés ou du déploiement, et à la fréquence qu’imposent tes objectifs. [Mises à niveau](https://docs.tale.dev/fr/self-hosted/operate/upgrades) explique le choix de version ; [Dépannage](https://docs.tale.dev/fr/self-hosted/operate/observability/troubleshooting) aide lorsqu’un service restauré ne devient pas opérationnel.

# Trouver le service à l’origine d’une panne
Source: https://docs.tale.dev/fr/self-hosted/operate/container-architecture

Commence par la responsabilité de chaque service pour circonscrire une panne avant de modifier des conteneurs. Le stack fourni regroupe bases applicative et de connaissances dans `db` ; Compose depuis les sources peut faire tourner `knowledge-db` séparément. Confirme ton installation avec `tale status` ou l’inventaire de ton orchestrateur.

## Choisir les premiers journaux

| Symptôme | Commencer par | Vérifier ensuite |
| --- | --- | --- |
| URL publique ou TLS en échec | `proxy` | DNS, certificats, ports publics et accès aux services en amont. |
| L’interface ne charge pas | `platform`, puis `proxy` | Santé du service web, fichiers statiques et version déployée. |
| L’interface charge, mais connexion ou requêtes de données échouent | `backend-api` | Santé de l’API, accès à la base, erreurs de requête et routage du proxy. |
| Jobs, automatisations planifiées ou imports bloqués | `backend-worker` | File d’attente, erreurs des jobs, identifiants et stockages nécessaires. |
| Échecs de lecture ou d’écriture dans toute l’application | `db` ou base applicative externe | Connexion, espace disque, verrous et journaux de base. |
| Impossible d’envoyer ou télécharger des fichiers | `backend-api`, puis `object-store` ou bucket externe | Connexion résolue de l’organisation, identifiants, point d’accès public et CORS du navigateur. |
| Un harness ne démarre pas ou n’atteint pas son modèle | `sandbox`, `sandbox-llm-gateway` | Création de session, authentification de la passerelle, disponibilité du modèle et image d’exécution. |
| Accès réseau sandbox ou rendu de page en échec | `sandbox-egress`, `sandbox` | Hôte cible, ports autorisés, règles de sortie et journaux de session. |
| Échec de récupération d’une transcription vidéo | `backend-worker`, `bgutil-provider` | Accès à la vidéo, erreurs de l’extracteur, proxy et état des sessions de navigateur. |

Utilise les noms logiques avec `tale logs <service>`. Pour ton propre Compose, utilise `docker compose logs --tail=200 <service>`. Les noms de conteneurs générés peuvent inclure le projet, la couleur et le numéro de réplica.

## Suivre une requête de chat interactive

1. Le navigateur atteint `proxy`. Les fichiers web vont à `platform` ; les requêtes applicatives et d’authentification vont à `backend-api`.
2. L’API vérifie session et organisation, résout le modèle et les identifiants choisis, puis exécute le tour interactif. Elle stocke sa progression dans la base applicative.
3. Le navigateur lit cette progression via le flux du fil de discussion. `/events` transporte des notifications d’invalidation pour actualiser les données, pas les tokens de la réponse.
4. Les outils de connaissance utilisent la connexion de l’organisation demandeuse. Les fichiers d’origine sont lus selon sa configuration de stockage.
5. Un tour utilisant un harness de codage demande une session sandbox et la passerelle de modèles. Tâches en file, jobs d’agents de workflow et tours de chat REST peuvent aussi dépendre des workers.

Une panne de worker n’a donc pas la même portée qu’une panne d’API, mais elle ne permet pas d’affirmer que tout chat ou travail d’agent reste disponible. Vérifie le point d’entrée et le type d’exécution concernés. Conserve l’erreur initiale avant de relancer un tour qui peut consommer des tokens ou effectuer une action externe.

## Comprendre les dépendances des sandbox

`sandbox` est un spawner qui accède au daemon Docker de l’hôte. Il crée des conteneurs temporaires depuis l’image sandbox-runtime fixée et monte leurs espaces de travail. Les sessions utilisent un réseau isolé : les requêtes web passent par `sandbox-egress`, les appels aux modèles par les accès de session limités de la passerelle.

L’environnement fournit aussi Chromium et Playwright pour le rendu de pages et la génération de documents. Une interface web disponible ne prouve pas que ces exécutions fonctionnent. Vérifie les images, montages de workspace, jeton sandbox partagé et identifiants de passerelle avant d’examiner un script particulier.

Le service de sortie bloque les destinations privées et de métadonnées et peut imposer une liste d’hôtes autorisés. Une sortie indisponible peut provoquer un refus ou une erreur réseau ; le message dépend de l’opération. [Durcissement](https://docs.tale.dev/fr/self-hosted/operate/security/hardening) décrit la politique et [Gérer Compose toi-même](https://docs.tale.dev/fr/self-hosted/install/own-compose) les capacités et montages requis.

## Reconnaître une réparation d’index de connaissances

Un index BM25 endommagé peut faire échouer l’ingestion alors que les tables de documents restent lisibles. Le backend vérifie les index avec `pdb.verify_index` ; un verrou consultatif coordonne les tentatives de réparation par base. Les bases propres aux organisations sont vérifiées à leur première utilisation.

| Résultat | Comportement du backend | Réponse de l’opérateur |
| --- | --- | --- |
| Index sain | Poursuivre le travail normal. | Aucune réparation nécessaire. |
| Index endommagé jusqu’à `KNOWLEDGE_INDEX_REPAIR_INLINE_MAX_BYTES` | Reconstruire immédiatement et vérifier à nouveau ; la limite par défaut est 1 GiB. | Prévoir un démarrage plus long et examiner le résultat final. |
| Index endommagé plus volumineux | Planifier une reconstruction concurrente en arrière-plan ; l’indexation affectée peut attendre avec un motif de reconstruction. | Suivre le worker et la vérification finale. |
| Échec de réparation ou état non établi | Enregistrer l’échec ; les opérations du corpus peuvent rester indisponibles. | Examiner la cause, les permissions de base et le stockage avant une réparation manuelle. |

Une réparation peut produire les actions d’audit `knowledge_index_repaired`, `knowledge_index_rebuild_scheduled` ou `knowledge_index_repair_failed`, ainsi que des notifications aux administrateurs. L’échec d’une reconstruction ne prouve pas que les documents sources sont perdus. Sa réussite ne remplace pas une sauvegarde de la base.

`KNOWLEDGE_INDEX_REPAIR_DISABLED=1` désactive la vérification automatique ; ce n’est pas une réparation. Des dommages répétés après redémarrage demandent d’examiner l’arrêt de Postgres et le stockage. Préfère un arrêt normal avec son délai de grâce aux arrêts forcés. [Dépannage](https://docs.tale.dev/fr/self-hosted/operate/observability/troubleshooting) fournit la vérification d’index en lecture seule et les précautions de reprise.

# Surveiller et traiter les incidents
Source: https://docs.tale.dev/fr/self-hosted/operate/observability/operations

Surveille les actions que les utilisateurs doivent terminer autant que les services qui les portent. Une sonde HTTP réussie ne prouve pas qu’une connexion, un téléchargement, une recherche ou une automatisation aboutit. Définis la gravité des alertes selon leur impact sur ton instance et associe chacune à un responsable et à une procédure de reprise.

[Configurer l’observabilité](https://docs.tale.dev/fr/self-hosted/configuration/observability-config) explique les points d’accès et le jeton. [Prometheus et Grafana](https://docs.tale.dev/fr/self-hosted/operate/observability/prometheus-grafana) fournit un exemple de collecte.

## Choisir des signaux qui permettent d’agir

| Signal | Investigation | Quand escalader ? |
| --- | --- | --- |
| Échec de l’URL publique, du certificat ou de la connexion | Vérifie le chemin public depuis l’extérieur de l’hôte, puis les journaux du proxy et du backend. | Les utilisateurs n’accèdent plus à un service nécessaire ou un certificat approche de l’expiration sans renouvellement fonctionnel. |
| Hausse des réponses 5xx du backend | Compare `tale_backend_http_requests_total` par `route` et `status` à l’action affectée. | Les erreurs touchent des utilisateurs actifs ou des intégrations critiques. |
| Stockage inaccessible | Examine `tale_backend_store_up` et la surveillance du stockage lui-même. | Des données, recherches ou fichiers nécessaires sont bloqués. |
| Accumulation de jobs en attente ou en échec | Examine `tale_backend_jobs{state=...}`, les workers et quelques erreurs d’exécution représentatives. | Le retard ne se résorbe plus ou une échéance est menacée. |
| Réduction de l’espace disque ou des connexions disponibles | Utilise la surveillance de l’hôte et de la base ; Tale n’exporte pas toutes ces métriques. | Anticipe assez pour ajouter de la capacité ou corriger la cause. |
| Sauvegarde ou copie planifiée absente | Vérifie le job de sauvegarde, le manifeste complet et la destination externe. | Ton objectif de perte de données maximale n’est plus respecté. |
| Requêtes limitées ou refusées par un fournisseur | Lis sa réponse et l’erreur de l’exécution ; vérifie quota, identifiants et état du fournisseur. | Le travail nécessaire échoue ou attend au-delà du délai admis. |

Une alerte à 80 % d’occupation disque peut servir de point de départ. La croissance et le temps nécessaire pour intervenir comptent davantage qu’un pourcentage universel. Une panne de recherche peut être critique pour une équipe qui dépend des connaissances ; ne la reporte pas automatiquement parce que l’interface charge encore.

## Choisir le bon point de contrôle

Utilise ces chemins sur l’origine publique d’un déploiement de production derrière le proxy fourni :

| Chemin | Ce qu’établit une réponse réussie |
| --- | --- |
| `/health` | Caddy répond `OK`. Ce contrôle reste vert pendant un redémarrage de la plateforme. |
| `/api/health` | Le processus web de la plateforme répond à sa sonde de vie. |
| `/status.json` | Le rapport public sur les dépendances est accessible. Lis le verdict de chaque composant ; les résultats sont conservés cinq secondes en cache. |
| `/status` | Le même rapport de disponibilité sous forme de page lisible. |

Vérifie le contenu attendu autant que le statut HTTP. Un chemin inconnu du frontend, comme `/healthz`, peut renvoyer la structure de l’application avec `200` ; ce n’est pas un rapport de santé. [Page d’état](https://docs.tale.dev/fr/develop/status-page) décrit le format de réponse.

## Comprendre ce que les métriques prouvent

Le backend exporte les métriques de processus, les nombres et durées des réponses HTTP, les comptes de jobs, les générations en cours, les flux de notification ouverts, l’état de drainage et l’accessibilité des stockages. Examine les séries réellement exposées par ta version avant d’écrire une alerte.

- `tale_backend_store_up` sonde les **stockages par défaut du déploiement** : base applicative, base de connaissances et bucket. Les connexions propres à une organisation demandent une surveillance distincte.
- Les sondes sont mises en cache pendant 30 secondes. Un `403` lors de la vérification du bucket compte comme accessible : la clé peut simplement ne pas avoir le droit de lister son contenu. La valeur `1` ne prouve pas qu’un objet précis peut être envoyé ou téléchargé.
- `/ready` indique la disponibilité pour le déploiement. Il n’intègre pas la santé des stockages externes ; un réplica prêt peut donc dépendre d’un stockage indisponible.
- L’URL publique des métriques backend peut atteindre différents réplicas d’API. Les métriques de processus concernent celui qui répond ; les compteurs de jobs et de générations lisent un état partagé en base. Ne les additionne pas comme si chaque réplica possédait sa propre file.

Couvre ces limites avec une vérification contrôlée de bout en bout : connecte-toi avec un compte de surveillance, lis un enregistrement connu et teste la fonction de fichier ou de recherche dont ton équipe dépend. Utilise un périmètre dédié sans envoi ni autre effet externe.

## Distinguer les objectifs de latence des mesures

Tale expose `tale_sla_target_seconds` et un modèle de règles sous `/metrics/sla-rules`. Les objectifs actuels sont une moyenne de 1 seconde jusqu’au premier token sur 30 minutes et de 40 secondes pour une opération longue sur 6 heures. Il s’agit de cibles, pas d’observations ni d’une garantie que ton déploiement les respecte.

Les règles générées attendent les histogrammes `tale_dialog_ttft_seconds` et `tale_long_operation_seconds`. Le backend n’émet pas automatiquement ces deux séries. Son histogramme HTTP mesure le traitement d’une requête, pas le délai jusqu’au premier token ni la durée complète d’un travail en file. Instrumente les véritables débuts et fins d’opération, puis confirme la présence d’échantillons avant d’activer ces règles. Une requête vide indique un manque de mesures, pas une latence conforme.

## Enquêter avant de modifier l’état

1. Note l’organisation, l’URL ou l’action affectée, le code d’erreur, la période et l’étendue de l’impact. Vérifie si le problème se reproduit sans modifier de données.
2. Consulte `tale status` et `tale logs <service>`. Pour une installation gérée directement, utilise le nom de service Compose avec `docker compose ps` et `docker compose logs --tail=200 <service>`.
3. Compare les erreurs réseau du navigateur aux journaux API/worker et à l’état des stockages ou fournisseurs. Préserve les journaux utiles avant qu’un redémarrage ne les fasse tourner ou n’en masque le contexte.
4. Corrige la cause identifiée : capacité, connexion, configuration, identifiants ou processus défaillant. Recrée les conteneurs concernés après une modification d’environnement ; `docker compose restart` conserve leur environnement précédent.
5. Après la reprise, vérifie l’action initiale et le travail associé en attente. Note les requêtes ou jobs interrompus qui demandent une relance explicite, puis complète la chronologie de l’incident.

Escalade dès que ta procédure d’incident le demande. Un redémarrage peut interrompre du travail ; ce n’est ni une étape de diagnostic obligatoire ni une raison de retarder l’escalade. [Dépannage](https://docs.tale.dev/fr/self-hosted/operate/observability/troubleshooting) associe les symptômes courants à des vérifications plus ciblées.

# Prometheus et Grafana
Source: https://docs.tale.dev/fr/self-hosted/operate/observability/prometheus-grafana

Utilise ton installation Prometheus et Grafana existante si tu en as une. L’exemple ci-dessous lance un projet Compose de surveillance séparé qui interroge Tale via son proxy public. Il comprend un stockage persistant des métriques, un fichier de jeton monté et deux premières alertes.

## Préparer l’accès et les fichiers

Définis `METRICS_BEARER_TOKEN` pour le proxy Tale, puis applique la modification avec ta procédure de déploiement. Un simple redémarrage de conteneur ne recharge pas les valeurs d’environnement modifiées. Vérifie les chemins protégés dans [Configurer l’observabilité](https://docs.tale.dev/fr/self-hosted/configuration/observability-config#metriques) avant de configurer la collecte.

Crée un dossier de surveillance séparé contenant `compose.monitoring.yml`, `prometheus.yml`, `tale-alerts.yml` et `secrets/tale-metrics-token`. Écris uniquement la valeur du jeton dans ce dernier fichier avec ton gestionnaire de secrets. Exclus ce fichier et le `.env` de surveillance de la gestion de versions. Limite leur accès à l’opérateur et au conteneur qui en a besoin.

Dans le `.env` de surveillance, fixe des tags testés pour `PROMETHEUS_IMAGE` et `GRAFANA_IMAGE`, puis définis `GRAFANA_ADMIN_PASSWORD`. Choisis des versions prises en charge sur les pages officielles de [Prometheus](https://prometheus.io/download/) et de [Grafana](https://grafana.com/grafana/download). Ces versions sont indépendantes de celle de Tale.

## Définir les services de surveillance

Les deux interfaces écoutent sur loopback. Accède-y depuis l’hôte Docker ou par un tunnel SSH ; un contexte Docker distant ne les rend pas locales à ton poste.

```yaml
# compose.monitoring.yml
services:
  prometheus:
    image: ${PROMETHEUS_IMAGE:?set a tested Prometheus image tag}
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - ./tale-alerts.yml:/etc/prometheus/tale-alerts.yml:ro
      - prometheus-data:/prometheus
    secrets: [tale_metrics_token]
    ports: ['127.0.0.1:9090:9090']
    restart: unless-stopped
  grafana:
    image: ${GRAFANA_IMAGE:?set a tested Grafana image tag}
    environment:
      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_ADMIN_PASSWORD:?set a strong password}
      GF_USERS_ALLOW_SIGN_UP: 'false'
    volumes: ['grafana-data:/var/lib/grafana']
    ports: ['127.0.0.1:3001:3000']
    restart: unless-stopped
secrets:
  tale_metrics_token:
    file: ./secrets/tale-metrics-token
volumes:
  prometheus-data:
  grafana-data:
```

Le secret est monté dans Prometheus sous `/run/secrets/tale_metrics_token`. Assure-toi que l’environnement de conteneurs peut lire le fichier source sans l’ouvrir aux autres utilisateurs.

## Configurer la collecte et les alertes

Remplace `tale.example.com` par le nom d’hôte Tale accessible, avec le port s’il diffère de 443. Ajoute le chemin de base du déploiement à chaque `metrics_path` si nécessaire. Utilise un certificat HTTPS de confiance ou configure un fichier d’autorité de certification ; ne désactive pas la vérification pour faire réussir la collecte.

```yaml
# prometheus.yml
global:
  scrape_interval: 30s
rule_files:
  - /etc/prometheus/tale-alerts.yml
scrape_configs:
  - job_name: tale-platform
    scheme: https
    metrics_path: /metrics/platform
    authorization:
      credentials_file: /run/secrets/tale_metrics_token
    static_configs:
      - targets: ['tale.example.com']
  - job_name: tale-backend
    scheme: https
    metrics_path: /metrics/backend
    authorization:
      credentials_file: /run/secrets/tale_metrics_token
    static_configs:
      - targets: ['tale.example.com']
```

Le jeton provient de `credentials_file`, conformément à la [configuration HTTP de Prometheus](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#http_config). Un `${METRICS_BEARER_TOKEN}` écrit littéralement dans ce YAML n’est pas remplacé par Docker Compose : Compose monte le fichier sans en réécrire le contenu.

```yaml
# tale-alerts.yml
groups:
  - name: tale
    rules:
      - alert: TaleTargetDown
        expr: up{job=~"tale-.*"} == 0
        for: 2m
        labels: { severity: page }
        annotations:
          summary: 'Tale metrics target {{ $labels.job }} is down'
      - alert: TaleDefaultStoreUnreachable
        expr: tale_backend_store_up == 0
        for: 5m
        labels: { severity: page }
        annotations:
          summary: 'Tale cannot reach its default {{ $labels.store }} store'
```

Adapte la gravité et les délais à tes exigences, puis configure la distribution via Alertmanager ou Grafana. Une règle visible dans Prometheus n’envoie pas de notification à elle seule. L’alerte de stockage couvre les valeurs par défaut du déploiement, pas les bases ou buckets propres aux organisations.

## Démarrer et vérifier la collecte

Valide les fichiers avant de démarrer :

```bash
docker compose -f compose.monitoring.yml config --quiet
docker compose -f compose.monitoring.yml run --rm --entrypoint promtool \
  prometheus check config /etc/prometheus/prometheus.yml
docker compose -f compose.monitoring.yml up -d
```

Ouvre `http://127.0.0.1:9090/targets`. Les deux jobs Tale doivent afficher **UP**. Vérifie la requête `up{job=~"tale-.*"}` et les règles d’alerte. Un `401` renvoie à la configuration du jeton. Pour une erreur DNS, de connexion ou de certificat, examine le chemin réseau du serveur de collecte. **UP** prouve qu’une collecte a réussi, pas que toutes les fonctions de l’application marchent.

Ouvre Grafana sur `http://127.0.0.1:3001` et ajoute une source de données Prometheus à `http://prometheus:9090`. Cette adresse est résolue dans le réseau Compose de surveillance.

## Construire un premier tableau de bord utile

| Panneau | Requête | Interprétation |
| --- | --- | --- |
| Disponibilité de la collecte | `up{job=~"tale-.*"}` | Chaque chemin public de métriques a-t-il répondu ? |
| Mémoire backend | `process_resident_memory_bytes{job="tale-backend"}` | Mémoire du réplica d’API qui a répondu. |
| Débit de réponses backend | `sum by (status) (rate(tale_backend_http_requests_total[5m]))` | Débit des requêtes par classe de statut de réponse. |
| États des jobs | `tale_backend_jobs` | Jobs par état de file ; surveille une croissance durable et les échecs. |
| Stockages par défaut | `tale_backend_store_up` | Accessibilité mise en cache de `app_db`, `knowledge_db` et `object_store`. |
| Drainage de déploiement | `tale_backend_drain_active` | Le drainage refuse-t-il de nouveaux tours ? |

Certains collecteurs lisent des comptes partagés en base, d’autres décrivent un processus. Avec plusieurs réplicas, collecte leurs métriques de processus séparément sur ton réseau privé et évite de compter plusieurs fois les jauges partagées. [Surveiller les opérations](https://docs.tale.dev/fr/self-hosted/operate/observability/operations) explique les limites des sondes de stockage et les mesures supplémentaires nécessaires au modèle de règles SLA.

# Dépanner une instance auto-hébergée
Source: https://docs.tale.dev/fr/self-hosted/operate/observability/troubleshooting

Note l’heure, l’organisation, l’URL ou l’action concernée et le code d’erreur avant tout redémarrage. Détermine si le problème touche un élément, une organisation ou tout le déploiement. Cette distinction oriente l’enquête vers un fichier, une connexion d’organisation ou l’infrastructure partagée.

Pour un déploiement dans un workspace, commence par `tale status` et `tale logs <service> --tail 200`. Dans ton propre projet Compose, utilise `docker compose ps` et `docker compose logs --tail=200 <service>`. Les noms de services comme `platform` et `backend-api` diffèrent des noms de conteneurs générés.

## Échec de l’URL publique, du certificat ou de la connexion

| Symptôme | Vérification | Étape suivante |
| --- | --- | --- |
| Connexion impossible ou avertissement TLS | DNS, ports publics, nom et émetteur du certificat, journaux du proxy. | Corrige la couche en échec. Avec une CA interne, installe son certificat racine public sur le client ; `docker exec ... caddy trust` ne change pas son magasin de confiance. |
| Réponse 502/503 du proxy | Identifie chemin et service cible. `/api/health` et fichiers web utilisent `platform` ; les requêtes applicatives utilisent `backend-api`. | Examine le démarrage et la disponibilité du service avant de modifier le proxy. |
| Réponses `503 DATABASE_UNAVAILABLE` | `backend-api` fonctionne, mais sa base de données redémarre ou est injoignable ; son journal affiche des avertissements `database unavailable`. | Vérifie l’état et les journaux du conteneur de base de données. Les requêtes reprennent d’elles-mêmes dès qu’il accepte de nouveau les connexions. |
| `400 BODY_LENGTH_MISMATCH` ou `400 BODY_CHUNK_MALFORMED` | Le corps se termine avant la longueur déclarée ou son découpage HTTP/1.1 en chunks est mal formé. | Corrige le format du corps ou sa longueur déclarée côté émetteur avant de réessayer. |
| Retour à la page de connexion | Cookies et callbacks dans le navigateur ; `SITE_URL`, origines supplémentaires, chemin de base et enregistrement fournisseur. | Corrige l’origine ou le callback, puis recrée les services après les modifications d’environnement. |

Une interface chargée mais vide oriente d’abord vers les requêtes applicatives, pas forcément le serveur web. Examine les requêtes échouées et les journaux `backend-api`. Proxy, session expirée, refus de permission et panne backend demandent des corrections différentes. [TLS et domaines](https://docs.tale.dev/fr/self-hosted/configuration/tls-and-domains) et [Authentification](https://docs.tale.dev/fr/self-hosted/configuration/authentication) décrivent leur configuration.

## Échec d’envoi ou de téléchargement des fichiers

Compare la réponse du serveur à la requête du navigateur vers l’URL présignée. Une seule organisation peut avoir une connexion de stockage défaillante alors que le bucket par défaut reste accessible.

| Observation | Signification et réponse |
| --- | --- |
| `object store (skipped)` au démarrage | La paire d’identifiants par défaut manque. Vérifie `OBJECT_STORE_ACCESS_KEY` et `OBJECT_STORE_SECRET_KEY`. Ne génère pas de remplaçants pour un stockage existant sans coordonner ses identifiants. |
| `object store (ignored)` | Le fichier est géré par l’opérateur. Examine `default/object-storage/connection.json` ; la synchronisation d’environnement le laisse volontairement intact. |
| `seeded` ou `reconciled` | La connexion par défaut a été écrite ou actualisée depuis l’environnement. Cela ne prouve pas toutes les permissions objet ni le chemin du navigateur. |
| Sonde de stockage en échec | Vérifie point d’accès, réseau, identifiants, existence du bucket et erreur backend détaillée. |
| Test serveur réussi, mais import navigateur en échec | Vérifie point d’accès public, confiance du certificat et CORS du bucket pour l’origine réelle du navigateur. Autorise `GET`, `PUT` et `HEAD` selon les opérations de fichiers. |

`tale_backend_store_up` couvre les valeurs par défaut et mesure l’accessibilité, pas un import complet. Un `403` du stockage objet peut malgré tout donner la valeur `1`. Après correction, vérifie un envoi et un téléchargement contrôlés. [Résidence des données](https://docs.tale.dev/fr/self-hosted/configuration/data-residency) explique les changements de connexion et la migration des fichiers.

## Un document reste non indexé

Examine son statut et son motif d’échec, puis les journaux `backend-worker`. Confirme modèle et identifiants d’embedding de l’organisation, dimensions des vecteurs, connexion de connaissances et format du fichier. Un import réussi prouve seulement le stockage du fichier d’origine.

Si un worker ou une dépendance était indisponible, rétablis-le puis vérifie si le job reprend ou demande **Indexer maintenant** dans [Connaissances](https://docs.tale.dev/fr/platform/knowledge/documents). Pour une source endommagée, chiffrée ou non prise en charge, corrige le fichier avant de réessayer. Ne supprime pas un document comme première étape : son identité, son historique et ses références peuvent compter.

## Un scan de site signale une erreur de certificat

L’erreur de crawl `tls_error` indique un échec de négociation TLS : certificat expiré, nom d’hôte différent ou chaîne non reconnue, par exemple. Corrige le certificat du site ou la configuration de confiance du processus de crawl, puis lance un nouveau scan. Répéter la même requête ne répare pas la confiance du certificat ; ne désactive pas sa vérification pour masquer l’échec.

`network_error` indique plutôt un échec de connexion. Lis sa cause et vérifie le DNS, le routage et la disponibilité du service. [Explorer les sites web](https://docs.tale.dev/fr/platform/knowledge/crawling) explique les erreurs par page et les résultats des scans.

## Postgres de connaissances plante pendant l’ingestion

Des erreurs répétées `PANIC: corrupted page pointers` ou `signal 6` peuvent signaler un index BM25 endommagé. Examine les journaux de la base et le résultat de la réparation automatique dans [Architecture des conteneurs](https://docs.tale.dev/fr/self-hosted/operate/container-architecture). Confirme la base exacte : dans le stack fourni, il s’agit de `tale_knowledge` dans `db` ; ailleurs, un service séparé ou un hôte externe peut la porter.

Depuis une session SQL autorisée sur cette base, cette requête vérifie seulement l’index indiqué :

```sql
SELECT * FROM pdb.verify_index('private_knowledge.idx_pk_chunks_bm25');
```

Une fonction absente, un refus de permission ou un délai dépassé ne confirme pas une corruption. Si le dommage est établi et que la réparation automatique a échoué, préserve une sauvegarde et planifie une maintenance de base. Reconstruire un index dérivé diffère de supprimer les tables de documents :

```sql
REINDEX INDEX private_knowledge.idx_pk_chunks_bm25;
```

Cette commande non concurrente peut bloquer du travail. Coordonne-la avec l’exploitation de la base, vérifie de nouveau l’index puis la reprise de l’ingestion. Ne lance pas de réindexation ou d’installation d’extension spéculative sur la mauvaise base. Une corruption répétée demande d’examiner le disque et les arrêts forcés après le délai de grâce.

## Un chat ou une automatisation s’arrête

Lis l’erreur du chat ou de l’exécution et les journaux API/worker correspondants. Un `429` fournisseur, un refus d’identifiants, un timeout, une attente d’approbation et une déconnexion du flux navigateur sont des états différents. Une approbation attend une décision, pas un redémarrage. Un flux coupé peut masquer une opération toujours active ; lis son résultat enregistré avant de relancer.

Pour un échec fournisseur, vérifie quota et permissions des identifiants choisis, ainsi que l’état du fournisseur. Ne change de modèle que si le remplacement est autorisé et adapté. Pour un échec de harness, examine `sandbox`, `sandbox-llm-gateway`, l’image d’exécution et les journaux de session.

## L’accès réseau de la sandbox est refusé

Examine `sandbox-egress` et l’URL cible. Une `SANDBOX_EGRESS_ALLOWLIST` configurée doit contenir l’hôte nécessaire ; les destinations privées et de métadonnées cloud restent bloquées. Les tunnels HTTPS suivent la politique de ports prise en charge. Confirme la destination voulue avant d’élargir la liste, puis recrée le service de sortie après un changement d’environnement.

Un processus de sortie sain ne prouve pas la disponibilité de l’hôte distant, du DNS, du certificat ou du compte. Conserve l’erreur précise dans le rapport d’incident.

Quand de nombreuses sessions installent des paquets ou chargent des pages en même temps et que des connexions échouent sur des réinitialisations alors que le proxy reste sain, il a peut-être atteint `SANDBOX_EGRESS_MAX_CLIENTS`, les connexions qu’il sert en même temps pour toutes les sessions réunies. Son journal indique alors que le nombre maximal de connexions est atteint. Augmente la valeur, avec les limites de processus et de fichiers ouverts du conteneur de sortie, puis recrée le service de sortie.

## Les écritures échouent ou le stockage se remplit

Vérifie connexion à la base applicative, espace libre, usage des connexions et verrous. Arrête la croissance évitable et récupère de la capacité selon ta procédure de base. Ne supprime pas le contenu des volumes, ne remplace pas les clés de chiffrement et ne suppose pas que les écritures échouées seront rejouées après redémarrage. Vérifie si l’opération a persisté avant de la relancer.

Pour demander de l’aide, fournis versions, erreurs nettoyées, période, périmètre et étapes de reproduction. `tale diagnostics` rassemble un diagnostic ; examine l’archive avant de la partager, car des détails du déploiement peuvent rester sensibles. Signale les défauts reproductibles dans le [suivi des problèmes du projet](https://github.com/tale-project/tale/issues).

# Examiner une version avant la mise à jour
Source: https://docs.tale.dev/fr/self-hosted/operate/release-notes/format

Lis les [notes de version sur GitHub](https://github.com/tale-project/tale/releases) pour la version que tu souhaites déployer. Pars de la version installée et examine chaque version jusqu’à la cible. Un numéro de correctif ne garantit pas l’absence de migration ou d’intervention de l’opérateur.

## Identifier le point de départ

Lance `tale --version` pour connaître la version de la CLI. Vérifie aussi celle du runtime déployé : mettre à jour la CLI et remplacer les conteneurs en cours d’exécution sont deux opérations distinctes. Pour un déploiement géré, consulte le reçu de déploiement avec ses références source et empreintes d’images.

Avec la CLI actuelle, `tale update` choisit une version plus récente dans la même série `x.y`. Passer à une autre série nécessite `--version`. Consulte `tale update --help` pour les options de ta CLI et lis les notes sur GitHub.

## Évaluer les conséquences du déploiement

Examine la version dans cet ordre. Les titres et le niveau de détail varient selon les versions. Lis les instructions de migration et les avis de sécurité liés avant d’appliquer le changement.

| Information | Décision à prendre |
| --- | --- |
| Ruptures de compatibilité et changements de comportement | Quels parcours, réglages par défaut ou paramètres changent ? |
| Migrations et instructions de mise à jour | Quelles conditions, interruptions ou préparations de restauration sont nécessaires ? |
| Changements du contrat API | Faut-il adapter les champs envoyés, le comportement attendu ou la gestion des erreurs ? Cette section est générée à la publication à partir de l’empreinte du contrat : si `info.version` a changé depuis le tag précédent, elle indique l’ancienne et la nouvelle version, les opérations ajoutées ou retirées et l’entrée du journal du contrat ; sinon, elle précise que le contrat reste inchangé. |
| Sécurité | Ton installation est-elle concernée, et quelle version corrigée ou mesure provisoire s’applique ? |
| Problèmes connus | Peux-tu accepter les limites restantes et utiliser les solutions de contournement ? |
| Nouveautés et liste complète des changements | Quelles fonctionnalités ou corrections présenter aux utilisateurs ? |

Tale est un projet 0.x mis à jour en continu. Une version corrective peut inclure des migrations additives et des changements de comportement. Les correctifs de sécurité ciblent la dernière version, sans rétroportage vers les anciennes. Consulte la [politique de sécurité](https://github.com/tale-project/tale/security/policy).

## Préparer le changement

1. Note les versions actuelle et cible, avec les références source exactes pour un déploiement géré.
2. Lis les notes intermédiaires et repère les changements de configuration, d’authentification, de stockage et d’intégration.
3. Prépare la sauvegarde, la restauration et le créneau de maintenance indiqués dans [Mises à jour](https://docs.tale.dev/fr/self-hosted/operate/upgrades).
4. Essaie la cible dans un environnement séparé avec tes parcours essentiels, notamment les clients API et les règles d’approbation.
5. Après le déploiement, vérifie l’état du système et répète ces parcours. Conserve les notes avec le compte rendu de déploiement.

Le téléchargement réussi d’une image ne prouve pas que l’application fonctionne après une migration. Vérifie la plateforme en cours d’exécution avant de considérer la mise à jour comme terminée. Les [avis de sécurité](https://docs.tale.dev/fr/self-hosted/operate/security/advisories) expliquent comment évaluer et signaler une vulnérabilité.

# Suivre les avis de sécurité
Source: https://docs.tale.dev/fr/self-hosted/operate/security/advisories

Pour examiner une mise à jour de sécurité, consulte les [avis de sécurité GitHub de Tale](https://github.com/tale-project/tale/security/advisories) et les [notes de version](https://github.com/tale-project/tale/releases) de la cible. La [politique de sécurité](https://github.com/tale-project/tale/security/policy) du dépôt définit le signalement et les versions prises en charge.

## Évaluer un avis

Commence par les versions affectées et corrigées. Compare-les au runtime en cours d’exécution et aux composants activés, pas seulement à la CLI installée sur ton ordinateur.

| Information | Ce qu’il faut déterminer |
| --- | --- |
| Versions et composants affectés | Si le code vulnérable est présent dans ton installation. |
| Conditions et conséquences | Si ta configuration expose le chemin vulnérable et quels accès il pourrait permettre. |
| Versions corrigées | Quelle version contient le correctif. |
| Gravité et éventuel vecteur CVSS | Les conséquences et hypothèses de l’évaluation, à compléter avec ta propre exposition. |
| Solutions de contournement | Les restrictions temporaires possibles si tu ne peux pas déployer le correctif immédiatement. |
| Identifiant et références | Le document stable à conserver dans les comptes rendus d’incident et de déploiement. |

Un réseau privé ne suffit pas à garantir que l’installation est à l’abri. L’authentification, le comportement des connecteurs et les accès internes peuvent rester pertinents. Détermine la priorité à partir de l’avis et de ta procédure d’incident.

## Appliquer et vérifier le correctif

Tale est un projet 0.x mis à jour en continu. Les correctifs de sécurité paraissent uniquement dans la dernière version, sans rétroportage vers les anciennes. Lis les notes de toutes les versions intermédiaires, puis suis [Mises à jour](https://docs.tale.dev/fr/self-hosted/operate/upgrades), avec la préparation des sauvegardes et de la restauration.

Note le correctif installé et vérifie le comportement concerné après le déploiement. Si tu avais appliqué une protection temporaire, retire-la seulement lorsque le runtime corrigé est en service et que tes vérifications réussissent.

## Signaler une vulnérabilité en privé

Ouvre l’onglet **Security** du dépôt et choisis **Report a vulnerability**. Si tu ne peux pas utiliser GitHub, écris à `security@tale.dev`. Ne révèle pas une vulnérabilité non corrigée dans une issue publique.

Indique le composant et la version, les étapes de reproduction et les conséquences probables. Fournis un exemple minimal sans identifiants, données personnelles ni données de production inutiles. Tu peux demander à être crédité dans l’avis publié.

La politique de sécurité prévoit un accusé de réception et une première évaluation sous 72 heures, un correctif ou une solution de contournement partagé en privé avec le rapporteur sous 14 jours, puis un avis GitHub publié avec la version corrigée. Coordonne l’enquête dans le signalement privé.

## Organiser un suivi régulier

Ajoute les pages des avis et des versions à tes favoris et à ta revue régulière des mises à jour. Précise qui les consulte, quelles installations sont couvertes et à qui transmettre les urgences. L’[examen des versions](https://docs.tale.dev/fr/self-hosted/operate/release-notes/format) donne la procédure générale ; le [renforcement de la sécurité](https://docs.tale.dev/fr/self-hosted/operate/security/hardening) décrit les protections à maintenir entre les mises à jour.

# Examiner l’intégrité du journal d’audit
Source: https://docs.tale.dev/fr/self-hosted/operate/security/audit-log-integrity

Suis cette procédure si **Intégrité de la chaîne** signale une rupture ou si tu reçois une notification d’intégrité. Le parcours dans les paramètres nécessite un compte Admin ou Propriétaire. Fais intervenir l’opérateur de ton installation pour examiner la base de données.

## Identifier la plage vérifiée

1. Ouvre **Paramètres > Gouvernance > Journaux** et repère **Intégrité de la chaîne**.
2. Note l’état et la date du dernier contrôle automatique. **Pas encore vérifié** signifie qu’aucun résultat planifié n’est disponible ; ce n’est pas une vérification réussie.
3. Choisis **Vérifier maintenant**. Le résultat indique le nombre d’entrées contrôlées. Un appel vérifie au plus 1 000 entrées depuis le début de la chaîne encore conservée.
4. Si le résultat est partiel, demande à l’opérateur de vérifier la suite. Un nouveau clic repart du même début, sans avancer dans la chaîne. Une première page valide ne prouve pas l’intégrité de tout l’historique.

Le résultat à la demande et l’état du contrôle planifié sont distincts. **Vérifier maintenant** ne modifie pas la date du dernier contrôle automatique.

## Comprendre ce qui est vérifié

Le backend PostgreSQL actuel vérifie le hachage SHA-256 de chaque entrée conservée dont le contenu n’a pas été effacé, ainsi que les liens entre les entrées. La première ligne restante fournit le lien de départ. Cela permet de détecter de nombreuses modifications dans la chaîne conservée, sans constituer un historique complet signé de façon indépendante.

La politique de conservation peut supprimer le début de la chaîne. Le contrôle planifié reprend sa progression enregistrée. Si la conservation a supprimé son ancien point de départ, il repart du premier lien restant. La disparition d’un point de départ encore compris dans la période de conservation n’est pas acceptée de cette manière.

Pour les lignes dont les données personnelles ont été effacées, le vérificateur contrôle les liens sans recalculer le hachage du contenu supprimé. Il compte aussi les lignes effacées sans demande d’effacement correspondante. Examine cet avertissement à partir des demandes d’effacement. Le backend actuel ne vérifie pas de points de contrôle signés par HMAC ; une clé de signature d’audit ne corrige pas ces résultats.

<Warning title="Conserver des preuves indépendantes">
Une chaîne de hachage n’empêche pas de modifier la base et ne prouve pas que chaque action a été enregistrée. Protège l’accès à la base et conserve les preuves indépendantes nécessaires à ton enquête. Ce contrôle seul ne suffit pas à établir qu’une chaîne entière a été réécrite.
</Warning>

## Conserver les détails d’un échec

Un hachage ou un lien incorrect affiche **Intégrité de la chaîne rompue**, l’**ID de l’entrée**, la date, le **Hachage attendu** et le **Hachage stocké**. Utilise **Ouvrir cette entrée** pour examiner l’événement.

1. Enregistre le résultat avec l’organisation, l’ID de l’entrée, l’heure et la version déployée. Conserve les valeurs à l’identique.
2. Préserve les snapshots de base et les journaux utiles de déploiement, d’accès et de sauvegarde avant toute réparation. Restreins l’accès aux copies contenant des données personnelles.
3. Compare l’heure avec les opérations de conservation, d’effacement, de restauration et de maintenance. Une coïncidence temporelle est une piste, pas la preuve que le problème est bénin.
4. Applique ta procédure de gestion des incidents si l’écart reste inexpliqué. Ne modifie pas et ne supprime pas la ligne signalée pour faire réussir le contrôle.

Le guide des [journaux d’audit](https://docs.tale.dev/fr/platform/admin/governance/audit-logs) explique les champs et les exports. Un export filtré et plafonné n’est ni une sauvegarde complète ni nécessairement une chaîne complète.

## Suivre le contrôle planifié

Une tâche quotidienne vérifie progressivement les organisations qui possèdent des entrées d’audit. Une rupture de hachage détectée active un incident d’intégrité et envoie une notification de sécurité aux admins de l’organisation. Le même résultat est dédupliqué entre les contrôles ; un résultat différent peut déclencher une nouvelle notification.

Après réparation ou restauration, vérifie que la plage concernée est valide. Un contrôle planifié ultérieur réussi lève l’incident actif. Expliquer l’échec à un collègue ou fermer une notification ne répare pas la chaîne.

Consulte le [renforcement de la sécurité](https://docs.tale.dev/fr/self-hosted/operate/security/hardening) pour les protections du déploiement et la [conservation](https://docs.tale.dev/fr/self-hosted/configuration/retention) pour les règles qui suppriment les anciennes preuves.

# Cryptographie et gestion des clés
Source: https://docs.tale.dev/fr/self-hosted/operate/security/cryptography

Cet inventaire indique quelle clé protège chaque donnée et ce qui se passe lorsqu’elle change. Les secrets applicatifs, volumes de bases, échanges réseau et preuves d’audit ont des protections distinctes. Garde cette distinction lorsque tu prépares une sauvegarde ou examines un déploiement.

## Identifier les données chiffrées

Les identifiants actuels des fournisseurs utilisent la Secret Box de la base : AES-256-GCM avec une clé dédiée dérivée de `ENCRYPTION_SECRET_HEX` par HKDF-SHA256. D’autres identifiants en base, dont les tokens OAuth de connectors, peuvent utiliser le format JWE `dir`/`A256GCM` fondé sur la même racine de déploiement. Ces formats ne sont pas interchangeables.

Les fichiers de secrets de configuration compatibles utilisent SOPS avec des destinataires age, notamment pour les bases documentaires et le stockage objet externes. `SOPS_AGE_KEY` ou `SOPS_AGE_KEY_FILE` configure ce chiffrement ; sans ces variables, le module accepte des fichiers en clair avec des permissions restreintes. Lis [Secrets avec SOPS](https://docs.tale.dev/fr/self-hosted/configuration/secrets-with-sops) avant de changer ce réglage.

Les noms, adresses, conversations et documents ne bénéficient pas d’un chiffrement systématique par champ via ces mécanismes. Protège la base, le stockage objet et les sauvegardes avec le chiffrement du stockage et les accès requis pour ton installation. TLS protège les échanges, pas un fichier de base copié depuis le disque.

## Protéger les échanges réseau

Le reverse proxy public termine les connexions HTTPS. Configure le domaine et le certificat avec [TLS et domaines](https://docs.tale.dev/fr/self-hosted/configuration/tls-and-domains), puis vérifie le certificat et les versions TLS acceptées sur l’endpoint déployé.

Le réseau Docker interne sépare les services, mais ne chiffre pas lui-même les échanges avec TLS. Si une connexion à une base, un stockage ou un autre service traverse des hôtes ou des limites de confiance, configure et vérifie aussi sa protection de transport.

## Préserver les mots de passe et sessions

Les mots de passe locaux sont hachés avec bcrypt. `BETTER_AUTH_SECRET` protège l’état d’authentification ; conserve une valeur stable et identique entre les réplicas backend. Un changement peut invalider les sessions et interrompre les connexions en cours.

Un fournisseur d’identité possède ses propres clés de signature et sa propre procédure de rotation. Enregistre ses métadonnées et certificats actuels via le [SSO d’entreprise](https://docs.tale.dev/fr/platform/admin/enterprise-sso). Changer un secret de session Tale ne change pas une clé de l’IdP.

## Vérifier les preuves d’audit

Les entrées d’audit forment une chaîne SHA-256. Le vérificateur PostgreSQL actuel contrôle les lignes conservées et leurs liens, à partir du premier lien encore stocké. Il tient compte de la conservation et rapproche les lignes effacées des demandes d’effacement. Il ne vérifie pas de points de contrôle signés.

La chaîne rend une altération détectable ; elle ne rend pas le stockage inviolable. Protège l’accès à la base, conserve les preuves indépendamment si nécessaire et examine les alertes avec [Intégrité du journal d’audit](https://docs.tale.dev/fr/self-hosted/operate/security/audit-log-integrity). La variable distincte `TALE_AUDIT_PEPPER` pseudonymise les identifiants sensibles des connexions échouées. Sa rotation modifie la corrélation de part et d’autre de ce changement.

## Préparer la récupération des clés

Utilise ce tableau pour ton plan de restauration :

| Protection | Éléments à conserver | Conséquence d’un changement ou d’une perte |
| --- | --- | --- |
| Secrets chiffrés en base | `ENCRYPTION_SECRET_HEX` correspondant au snapshot | Les identifiants existants peuvent devenir illisibles. |
| Fichiers SOPS | Clés privées age correspondantes, y compris pour les anciennes sauvegardes | Un fichier chiffré uniquement pour un destinataire perdu ne peut plus être lu. |
| Authentification | `BETTER_AUTH_SECRET` et configuration cohérente | Les sessions et connexions en cours peuvent échouer. |
| Vérification d’audit | Lignes conservées, demandes d’effacement et preuves indépendantes | La chaîne actuelle ne suffit pas à établir un historique perdu ou réécrit. |
| Chiffrement de l’hôte et du stockage géré | Éléments de récupération et accès du fournisseur de stockage | Les clés applicatives seules ne déverrouillent pas un volume ou un bucket. |

Conserve les clés dans un gestionnaire de secrets ou un espace de reprise protégé, séparé des sources et artefacts publics. Garde les anciennes clés pour les anciennes sauvegardes après la rotation active. Teste une restauration avec les vraies clés dans un environnement isolé.

Les certifications et documents d’assurance sont décrits dans [Confiance et conformité](https://docs.tale.dev/fr/cloud/trust-and-compliance). Cet inventaire explique les protections techniques ; évalue aussi la configuration de ta propre installation.

# Sécuriser un déploiement de production
Source: https://docs.tale.dev/fr/self-hosted/operate/security/hardening

Vérifie ces protections avant le lancement et après toute modification de l’hôte, du réseau ou de l’authentification. Il te faut un accès opérateur et un moyen de récupération qui reste disponible pendant les changements de règles d’accès.

## Restreindre l’administration de l’hôte

Utilise des comptes opérateur nominatifs, des clés SSH et un système d’exploitation pris en charge et à jour. Limite l’accès à l’hôte, au répertoire de configuration, aux sauvegardes et au socket Docker aux personnes responsables du déploiement.

L’appartenance au groupe `docker` donne des capacités de niveau root via le daemon Docker. Exécuter la CLI avec un autre compte ne supprime pas ces pouvoirs. Traite l’accès à Docker comme une administration privilégiée, conformément à la [documentation Docker](https://docs.docker.com/engine/install/linux-postinstall/).

## Vérifier l’exposition publique

Autorise les ports publics prévus pour le proxy et limite les accès administratifs aux sources de confiance. Garde la base, l’administration du stockage, les services internes du backend et la sandbox hors du réseau public, sauf architecture particulière examinée séparément.

Inspecte les ports publiés par ta configuration Compose réelle et teste leur accessibilité depuis l’extérieur de l’hôte. Les règles du pare-feu de l’hôte ne suffisent pas toujours : Docker gère ses propres règles de transfert et de publication des ports. Consulte les [instructions Docker sur les pare-feu](https://docs.docker.com/engine/network/packet-filtering-firewalls/).

Si tu utilises l’authentification par en-têtes de confiance, seul le proxy amont doit pouvoir joindre l’application. Il doit supprimer les en-têtes d’identité fournis par l’appelant avant de définir les siens. Voir [Authentification](https://docs.tale.dev/fr/self-hosted/configuration/authentication).

Le fichier `robots.txt` de la plateforme déconseille l’indexation de l’application, mais autorise explicitement les chemins publics destinés aux intégrateurs et au suivi d’état, dont `/docs`, `/openapi.json`, `/llms.txt`, `/llms-full.txt` et `/status`. Ces consignes aux robots ne sont pas des contrôles d’accès. Protège les données confidentielles par authentification et examine les informations exposées dans le rapport public.

## Vérifier TLS à l’adresse publique

Utilise un certificat de confiance pour l’adresse réellement ouverte par les utilisateurs. Choisis `TLS_MODE=letsencrypt` pour le point d’entrée TLS public fourni, ou `TLS_MODE=external` si ton proxy amont termine TLS. Un certificat local autosigné n’établit pas une confiance publique.

Vérifie la chaîne de certificats, l’expiration et le renouvellement, puis teste la connexion et les retours d’authentification à l’adresse publique. [TLS et domaines](https://docs.tale.dev/fr/self-hosted/configuration/tls-and-domains) explique la configuration.

## Protéger secrets et clés

Remplace les valeurs d’exemple avant la production. Chaque déploiement doit avoir son propre mot de passe de base, ses secrets d’authentification et sa clé de chiffrement. Réserve l’accès à `.env` et aux fichiers secrets à l’opérateur. Conserve les copies de récupération dans ton système de gestion des secrets.

Utilise [SOPS](https://docs.tale.dev/fr/self-hosted/configuration/secrets-with-sops) pour les fichiers secrets pris en charge lorsque cela convient à ton installation. SOPS ne chiffre pas toutes les données applicatives ni le disque entier. Conserve les clés nécessaires aux sauvegardes retenues. Prépare les rotations avec [Cryptographie](https://docs.tale.dev/fr/self-hosted/operate/security/cryptography) : remplacer une clé arbitrairement peut invalider des sessions ou rendre des identifiants stockés illisibles.

Définis `TALE_AUDIT_PEPPER` pour pseudonymiser les données des connexions échouées. La conservation d’audit s’applique par organisation. Vérifie sa politique effective et la période de preuve requise dans [Conservation](https://docs.tale.dev/fr/self-hosted/configuration/retention).

## Éprouver la restauration

Choisis la fréquence des sauvegardes et leur conservation selon la perte de données acceptable pour ton organisation. Inclus base, configuration, stockage objet et secrets nécessaires à la restauration. Les stockages externes nécessitent une sauvegarde coordonnée distincte.

Garde des copies protégées hors de l’hôte du déploiement et restaure-les régulièrement vers une destination isolée. Vérifie ensuite connexion, fichiers et parcours essentiels. [Sauvegardes et restauration](https://docs.tale.dev/fr/self-hosted/operate/backups-and-restore) précise la portée des snapshots CLI et les interruptions de service.

## Limiter les destinations de la sandbox

Le proxy de sortie de la sandbox autorise par défaut les destinations HTTPS publiques tout en bloquant les adresses privées et les adresses de métadonnées. `SANDBOX_EGRESS_ALLOWLIST` permet de restreindre aussi les noms d’hôtes. Cet exemple va dans le fichier `.env` du projet et autorise deux hôtes de paquets Python :

```dotenv .env
SANDBOX_EGRESS_ALLOWLIST=^pypi\.org$|^files\.pythonhosted\.org$
```

Recrée le service de sortie avec l’environnement modifié. Vérifie qu’une destination nécessaire fonctionne et qu’une destination absente de la liste est refusée. Ajoute d’autres registres ou hôtes source seulement si tes traitements en ont besoin. Les skills de documents intégrés n’en ont pas besoin pour créer et lire des fichiers Word, PowerPoint, Excel et PDF : leurs bibliothèques sont incluses dans l’image de la sandbox. La reconnaissance de texte (OCR) des PDF numérisés n’est pas incluse. Les appels aux modèles passent par la passerelle dédiée de la sandbox ; cette liste ne régit donc pas toutes les connexions sortantes de Tale.

Examine séparément les autorisations de réseau privé. `TALE_ALLOW_PRIVATE_PROVIDER_HOSTS=1` admet les destinations des fournisseurs de modèles, y compris dans la passerelle sandbox ; il n’ouvre pas l’accès réseau général de la sandbox. `TALE_ALLOW_PRIVATE_CRAWL_HOSTS=1` admet les cibles intranet et les valeurs d’URL d’image privées des produits. Active uniquement l’accès nécessaire et garde sa configuration sous contrôle opérateur. [Fournisseurs](https://docs.tale.dev/fr/self-hosted/configuration/providers) décrit les vérifications des modèles ; la [référence d’environnement](https://docs.tale.dev/fr/self-hosted/configuration/environment-reference) distingue les deux variables.

## Surveiller et enquêter

Configure l’accès authentifié aux métriques avec `METRICS_BEARER_TOKEN` et connecte ton système de surveillance. Vérifie qu’une alerte atteint l’opérateur responsable. [Exploitation](https://docs.tale.dev/fr/self-hosted/operate/observability/operations) décrit les signaux utiles.

Une tâche quotidienne vérifie progressivement les lignes d’audit conservées et signale aux admins les ruptures de hachage détectées. **Vérifier maintenant**, dans **Paramètres > Gouvernance > Journaux > Intégrité de la chaîne**, contrôle au plus 1 000 entrées. Consulte [Intégrité du journal d’audit](https://docs.tale.dev/fr/self-hosted/operate/security/audit-log-integrity) pour les limites et la conservation des preuves.

## Vérifier la réponse du déploiement

Inspecte les en-têtes de sécurité à l’adresse publique après une modification du proxy. Celui-ci peut changer les en-têtes produits par Tale ; la configuration source ne suffit donc pas. Examine la politique de sécurité du contenu, les restrictions d’intégration dans une page, les règles HTTPS et le traitement des types de contenu, puis teste la connexion réelle.

Ne copie pas des réglages d’isolation entre origines ou de préchargement HSTS d’un autre déploiement sans examiner tes retours d’authentification, ressources externes et sous-domaines. Conserve les résultats avec le compte rendu de déploiement et répète les contrôles après les mises à jour.

# Mettre à niveau et rétablir un déploiement
Source: https://docs.tale.dev/fr/self-hosted/operate/upgrades

Pour un déploiement dans un workspace, `tale update` modifie la CLI et les fichiers locaux ; `tale deploy` modifie les services actifs. Choisis la version cible et le point de reprise avant ces étapes. Le déploiement bleu-vert fait coexister les réplicas applicatifs, mais snapshots, drainage et remplacement des services persistants peuvent interrompre le travail.

Les déploiements gérés utilisent des révisions de sources fixées et des bundles préparés. Suis [Déploiements gérés](https://docs.tale.dev/fr/self-hosted/install/cli-install#managed-deployments) pour ce parcours, ou [Releases de configuration](https://docs.tale.dev/fr/self-hosted/configuration/config-releases) si seul le contenu client change.

## Préparer la mise à niveau

1. Lance `tale status` dans le bon workspace. Note la version active, celle du workspace et l’état du déploiement.
2. Lis les notes de la version cible : compatibilité, configuration requise et limites connues. Une instance antérieure à 0.5 exige le changement d’installation décrit plus bas.
3. Confirme une sauvegarde externe restaurable, les clés correspondantes et la couverture des bases et buckets externes. [Sauvegardes et restauration](https://docs.tale.dev/fr/self-hosted/operate/backups-and-restore) décrit les éléments nécessaires.
4. Prévois la capacité pour les anciens et nouveaux réplicas ensemble. Réserve une maintenance si les snapshots ou remplacements de sandbox et de services persistants peuvent interrompre un travail nécessaire.
5. Prévisualise la mise à jour et le déploiement. Examine les avertissements : un aperçu réussi ne prouve pas qu’une migration réelle aboutira.

## Sélectionner la version

Les commandes du workspace essaient d’aligner la CLI sur la version de `tale.json`. Si le téléchargement échoue, la CLI avertit puis continue avec le programme actuel. Résous tout décalage inattendu avant de modifier le déploiement.

Sans argument de version, `tale update` choisit la dernière release de la ligne `major.minor` du workspace. Pour changer de ligne, indique la version :

```bash
tale update --dry-run
tale update --version <target-version> --dry-run
tale update --version <target-version>
```

La mise à jour remplace la CLI et synchronise les modèles du workspace, sans toucher aux conteneurs actifs. Si la synchronisation échoue, elle tente de remettre le programme à la version précédente du workspace. Vérifie les fichiers et la sortie avant de déployer.

## Prévisualiser et déployer

```bash
tale deploy --dry-run
tale deploy
tale status
```

Un changement de version ou un remplacement de configuration de l’hôte prend un snapshot local avant modification, sauf avec `--skip-backup`. Cette protection supplémentaire ne remplace pas une sauvegarde hors de l’hôte.

| Groupe de services | Déploiement ordinaire | Quand prévoir une interruption supplémentaire ? |
| --- | --- | --- |
| `platform`, `backend-api`, `backend-worker` | Déploiement commun dans la nouvelle couleur applicative. | Anciens et nouveaux réplicas coexistent ; le drainage peut refuser de nouveaux tours. |
| `sandbox`, `sandbox-egress`, `sandbox-llm-gateway` | Remplacement sur place après drainage du travail concerné. | Ce sont des dépendances d’exécution communes, pas un second groupe applicatif bleu-vert. |
| `db`, `object-store`, `proxy` | Conservation des services actifs ; la CLI signale les mises à jour ignorées. | Ajoute `--stop` lorsque ces services doivent être remplacés. |

```bash
tale deploy --stop
```

`TALE_PLATFORM_REPLICAS`, `TALE_BACKEND_API_REPLICAS` et `TALE_BACKEND_WORKER_REPLICAS` acceptent 1–16 réplicas. Augmente le rôle dont les mesures montrent la saturation ; ajouter des workers ne corrige ni une base indisponible ni un quota fournisseur épuisé.

## Comprendre la bascule

La CLI démarre la couleur inactive et attend que ses réplicas passent les contrôles de santé avant de terminer la bascule. Les deux versions peuvent servir pendant le chevauchement. Les releases doivent donc rester compatibles avec l’application précédente pendant les migrations.

L’ancienne API est drainée avant son retrait : de nouveaux tours de chat peuvent être refusés, tandis que les tours en cours disposent d’un délai pour finir. Le drainage des chats attend jusqu’à trois minutes ; celui du service web utilise `DRAIN_TIMEOUT`, par défaut 30 secondes. La route de santé web reste saine tant que son alias est partagé. Déconnecter les anciens conteneurs des réseaux de service les retire du DNS et peut couper les connexions restantes ; cette étape vient donc après les drainages.

Les onglets ouverts avant la bascule exécutent encore la version précédente. La première fois qu’un tel onglet a besoin d’une partie de l’application remplacée par la nouvelle version, par exemple un aperçu de document, il se recharge une fois et continue avec la nouvelle version. Si cette partie ne se charge toujours pas après le rechargement, parce que l’onglet a de nouveau atteint l’ancienne couleur par exemple, il ne se recharge pas une seconde fois. Il affiche alors **Une nouvelle version est disponible** avec l’action **Recharger**. Un onglet qui ne parvient pas du tout à joindre Tale ne se recharge pas ; il affiche son avis de connexion jusqu’à ce que Tale réponde de nouveau.

Si le nouveau groupe ne devient pas sain avant `HEALTH_CHECK_TIMEOUT`, la CLI ne termine pas la bascule. Examine l’état enregistré et les journaux avant de réessayer. Un déploiement interrompu peut laisser les deux groupes ou un transfert en attente. Suis les indications de reprise de la CLI plutôt que de supprimer manuellement conteneurs ou fichiers d’état.

## Vérifier les migrations et le résultat utilisateur

Au démarrage, le backend applique ses migrations numérotées dans l’ordre des noms de fichier, sous un verrou consultatif de session. Les migrations SQL modifient le schéma ; les migrations de données en TypeScript mettent à jour les lignes existantes selon les règles de l’application. La table `app_migrations` enregistre les deux types par nom de fichier, si bien que chaque migration ne s’exécute qu’une fois par base. Les autres réplicas attendent cette étape. Une erreur de migration empêche le nouveau backend de démarrer normalement ; examine l’erreur et la base avant de réessayer. Changer un tag d’image n’annule pas des migrations conçues pour avancer uniquement.

`tale migrate` actualise les valeurs d’organisation fournies ; ce n’est pas une commande de retour arrière de la base. Avant de remplacer la configuration de l’hôte, vérifie que les adaptations locales doivent réellement être écrasées.

Après le déploiement, vérifie certificat public et connexion, ouvre un projet ou une conversation existante et télécharge un fichier connu. Teste de façon contrôlée les parcours de connaissances et d’automatisation utilisés. Vérifie l’avancement des workers, les stockages et la version effectivement active. Conserve les éléments de reprise antérieurs jusqu’à l’acceptation du déploiement.

## Choisir un retour arrière

| Situation | Reprise |
| --- | --- |
| Revenir à la version précédente enregistrée dans la même ligne `major.minor` | `tale rollback` vérifie cette limite et demande confirmation avant de redéployer. Lis aussi les notes de compatibilité de la release. |
| Revenir au-delà d’une limite mineure ou majeure | Restaure les données coordonnées d’avant la mise à niveau et déploie leur version correspondante. `tale rollback` refuse ce retour limité aux images. |
| Version cible ou compatibilité des données inconnue | Résous la version et la provenance des sauvegardes avant de démarrer un programme plus ancien. |

```bash
tale rollback
```

`--yes` supprime la confirmation pour une opération sans surveillance déjà approuvée. La vérification de ligne de version est un garde-fou, pas une preuve indépendante de compatibilité de chaque intégration externe ou configuration personnalisée. Une liste d’anciennes migrations qui forme le préfixe de la nouvelle ne suffit pas à rendre un retour arrière sûr.

`tale rollback` remplace uniquement les images applicatives de `platform`, `backend-api` et `backend-worker`. Il ne restaure aucun volume et laisse la base de données, les stockages, le proxy, les services de sandbox et la passerelle de modèles tels quels. Aucune étape de déploiement ne restaure non plus de données d’elle-même : un déploiement ordinaire (sans `--services`) qui échoue à ses contrôles de santé laisse la couleur applicative précédente en service, mais les services qu’il a déjà remplacés sur place le restent. Seul `tale restore` remet en place les volumes d’un snapshot.

## Bifrost 1.6 → 2.2 : le stockage de la passerelle de modèles est migré

Une version postérieure à 0.5.64 fait passer la passerelle de modèles (`sandbox-llm-gateway`) de Bifrost 1.6 à Bifrost 2.2 ; ses notes de version signalent ce changement. À son premier démarrage, la nouvelle passerelle migre sur place son stockage dans `llm-gateway-data` et conserve ses fournisseurs, clés, budgets et compte d’administration ; rien n’est à faire à la main. La migration indexe aussi le journal des requêtes de la passerelle, si bien que ce démarrage peut durer plus longtemps sur une instance à long historique de requêtes.

`tale deploy` remplace la passerelle avant de démarrer la nouvelle couleur applicative : si le déploiement échoue ensuite, le stockage peut donc déjà être migré. Le snapshot qu’un `tale deploy` avec changement de version prend auparavant contient `llm-gateway-data` avec les autres volumes et sert donc aussi de point de reprise pour la passerelle. Les snapshots pris avant que la CLI capture le stockage de la passerelle ne contiennent pas cette archive ; `tale restore` les signale comme `without gateway`. Si tu déploies avec `--skip-backup`, copie d’abord le volume toi-même. Arrête la passerelle, ce qui termine les tours d’agent et les appels de modèle en cours, copie le volume, puis déploie. `<id>` est l’`id` de `tale.json` :

```bash
docker stop <id>-sandbox-llm-gateway
docker run --rm -v <id>_llm-gateway-data:/from:ro -v "$PWD/llm-gateway-data-backup:/to" alpine:3.22 cp -a /from/. /to/
```

La passerelle d’une version antérieure à ce changement démarre sur le stockage migré et sert Tale, mais elle journalise des erreurs `no such column: oauth_configs.token_id`, et Bifrost ne prend pas en charge ce retour en arrière. `tale rollback` ne démarre pas cette passerelle : il laisse la passerelle sur l’image et le stockage plus récents. Elle démarre quand une version antérieure au changement est de nouveau déployée, par exemple avec `tale update --version` et `tale deploy` après la restauration d’un snapshot. Remets donc d’abord le stockage en place. Restaurer le snapshot pris avant la mise à niveau remet `llm-gateway-data` en place avec les autres volumes. Si `tale restore` signale ce snapshot comme `without gateway`, arrête la passerelle et remets ta copie en place avant de déployer la version antérieure :

```bash
docker stop <id>-sandbox-llm-gateway
docker run --rm -v "$PWD/llm-gateway-data-backup:/from:ro" -v <id>_llm-gateway-data:/to alpine:3.22 sh -c 'find /to -mindepth 1 -delete && cp -a /from/. /to/'
```

Une passerelle sans compte d’administration, sur une nouvelle installation ou après le remplacement de son volume, ne crée désormais ce compte que pour un appelant qui présente son jeton de configuration, que l’image tire de `SANDBOX_LLM_GATEWAY_ADMIN_PASSWORD`. `tale deploy`, le fichier Compose du dépôt et les manifestes Kubernetes de cette documentation donnent déjà cette variable à la passerelle. Un fichier Compose ou un manifeste écrit à la main qui ne la passe qu’au backend doit aussi la passer à la passerelle.

Deux comportements changent. Quand un appelant raccroche, la passerelle met désormais fin à l’appel de modèle, qu’il ait demandé une réponse entière ou un flux : une requête abandonnée n’occupe donc plus un modèle auto-hébergé, et les endpoints de modèles imputent un tel appel pour son prompt et la sortie qui avait atteint l’appelant. Et un modèle en amont qui retient les en-têtes de réponse d’une réponse en flux, comme un routeur qui met les requêtes en file d’attente jusqu’à ce qu’un modèle se libère, doit commencer sa réponse dans le délai de requête de la passerelle : 600 secondes, ou davantage quand `SANDBOX_LLM_GATEWAY_STREAM_IDLE_TIMEOUT_SECONDS` le relève.

## 0.4 → 0.5 : une installation séparée

En 0.5, Postgres a remplacé l’ancien stockage applicatif Convex. Aucun importeur ne permet une mise à niveau directe entre ces bases. Garde l’ancienne instance et ses sauvegardes intactes pendant que tu prépares un déploiement neuf, avec un workspace et des données séparés.

Recrée organisations et utilisateurs, examine et transfère la configuration compatible, puis réimporte les documents nécessaires. Des fichiers laissés dans un bucket externe ne reçoivent pas automatiquement de références dans la nouvelle base applicative. Valide l’environnement de remplacement avant de retirer l’ancien.

La CLI refuse ce changement non pris en charge par défaut. L’option experte `--accept-data-loss` n’est pas un outil de migration et ne préserve pas les anciennes données applicatives. Des volumes ou bases historiques peuvent subsister après de précédentes mises à niveau ; leur seule présence ne justifie pas de les supprimer pendant cette procédure.

## 0.3 → 0.4 : l’API compatible OpenAI a été retirée

De la 0.2.10 à la 0.3, Tale proposait sous `/api/v1` une couche compatible OpenAI : `POST /api/v1/chat/completions` et `POST /api/v1/images/generations`, avec requêtes et réponses au format OpenAI, ainsi qu’un `GET /api/v1/models` au format OpenAI. Son champ `model` pouvait désigner un agent. La reconstruction de la 0.4 a retiré cette couche. Les appelants de ces routes, y compris les SDK OpenAI pointés sur l’instance, cessent de fonctionner, car la 0.4 ne sert aucune des trois routes, et les versions ultérieures ne les rétablissent pas. Une version actuelle répond aux chat completions et à la génération d’images par `404 NOT_FOUND`, ou par `400 ORG_SLUG_REQUIRED` quand le titulaire de la clé appartient à plusieurs organisations et que la requête ne porte pas de `X-Organization-Slug`, qu’un SDK OpenAI n’envoie pas par défaut. Son `GET /api/v1/models` renvoie la liste propre à Tale, avec les modèles et les environnements d’agents, qu’un client OpenAI ne sait pas lire.

Repère ces appelants avant la mise à niveau et prévois leur remplacement. Un appelant qui a besoin de la réponse d’un modèle peut passer aux endpoints de modèles encadrés que proposent les versions à partir du contrat d’API 3.7.0. Ils diffèrent de la couche de la 0.3 : l’URL de base est `/api/v1/openai`, ou `/api/v1/anthropic` pour les clients Anthropic, au lieu de `/api/v1` ; `model` désigne un modèle sous la forme `<providerSlug>/<modelId>`, jamais un agent ; la génération d’images n’est pas servie ; et les endpoints restent désactivés tant qu’un admin n’a pas activé **Endpoints de modèles pour les clés API** dans **Paramètres > Gouvernance > Modèles**. Ensuite, chaque appel passe par l’accès aux modèles, les garde-fous d’entrée et les budgets. Les endpoints de modèles joignent les modèles par la même passerelle de modèles que les agents gérés. Les questions posées par script à l’assistant passent à l’API REST de chat, asynchrone, qui répond en tant qu’assistant de l’espace de travail et non comme un modèle brut. Les intégrations d’éditeur qui ont besoin des connaissances de Tale utilisent l’endpoint MCP, et le travail qui doit se faire dans Tale, dans une sandbox et avec la revue d’une personne, revient à un agent de projet sur une tâche. [Utiliser Tale depuis ton éditeur ou un script](https://docs.tale.dev/fr/develop/use-tale-from-your-editor) décrit chacune de ces voies.

# Architecture auto-hébergée
Source: https://docs.tale.dev/fr/self-hosted/overview

Avec Tale auto-hébergé, tu exploites l’application, son stockage et les services de sandbox sur ton infrastructure. Une instance peut accueillir plusieurs organisations ; les données et la configuration de chacune restent rattachées à cette organisation.

Cette vue d’ensemble aide à prévoir la capacité et à choisir les données à sauvegarder. [Gérer Compose toi-même](https://docs.tale.dev/fr/self-hosted/install/own-compose) décrit les réseaux, montages et sondes nécessaires. [Architecture des conteneurs](https://docs.tale.dev/fr/self-hosted/operate/container-architecture) aide à localiser une panne sur une instance en service.

## Comment les services s’articulent

Le déploiement fourni pour un hôte comprend dix services, sans compter les réplicas ni les sessions temporaires de sandbox. Le stack de développement peut utiliser une base de connaissances séparée. Pour comparer ces installations, regarde le rôle des services plutôt que le nombre de conteneurs.

| Couche | Services | Responsabilité |
| --- | --- | --- |
| Entrée publique | `proxy` | Caddy termine TLS et dirige les requêtes du navigateur vers l’interface, les API et le stockage de fichiers. |
| Application | `platform`, `backend-api`, `backend-worker` | Le service web fournit l’interface. L’API authentifie les requêtes et traite les opérations applicatives. Les workers exécutent les tâches, automatisations et imports en file d’attente. |
| Stockage persistant | `db`, `object-store` | Postgres conserve les données applicatives et les connaissances ; le stockage compatible S3 contient les fichiers d’origine et les médias générés. |
| Exécution en sandbox | `sandbox`, `sandbox-egress`, `sandbox-llm-gateway` | Le spawner crée les sessions d’exécution, le proxy de sortie contrôle les requêtes réseau et la passerelle de modèles fournit un accès limité aux modèles. |
| Prise en charge vidéo | `bgutil-provider` | Fournit des jetons de preuve d’origine pour l’ingestion vidéo. Sa disponibilité peut affecter la récupération des transcriptions. |

Le navigateur passe par le proxy public. Les ports internes des bases, de la passerelle et des sandbox ne doivent pas être exposés comme services publics. Avec un bucket externe, les requêtes de fichiers présignées peuvent aller directement du navigateur à son point d’accès public.

Les rôles applicatifs utilisent la même image Tale Platform. `TALE_ROLE=api` démarre l’API et `TALE_ROLE=worker` un worker. Les workers n’exposent pas de serveur HTTP. L’environnement d’exécution des sandbox est une image distincte qui sert à créer des conteneurs de session temporaires, pas un service Compose permanent de plus.

## Où les données persistent

| Emplacement dans le stack fourni | Données à conserver |
| --- | --- |
| `db-data` | `tale_app` : utilisateurs, chats, exécutions, entrées d’audit et secrets chiffrés en base. `tale_knowledge` : contenu extrait, embeddings, index de recherche et pages web récupérées. |
| `config-data` | Fichiers de configuration des organisations : agents, skills, définitions de fournisseurs, règles de gouvernance, SSO et identité visuelle. |
| `object-store-data` | Documents importés, pièces jointes, audio et fichiers générés. |
| `caddy-data`, `caddy-config` | Certificats et état du proxy. |
| `llm-gateway-data` | Configuration de la passerelle, état des accès de session et journal des requêtes de la passerelle (modèle, jetons, durée), sans prompts ni réponses. |

Le stack fourni place les deux bases dans un seul service Postgres et expose la connexion aux connaissances sous l’alias réseau `knowledge-db`. Les bases restent distinctes. Un déploiement Compose depuis les sources avec un service de connaissances séparé possède aussi `knowledge-db-data`.

Remplacer un conteneur ne préserve les données que si ses volumes persistants ou ses stockages externes restent raccordés. Conserve aussi le dossier de déploiement, l’environnement, les clés de chiffrement et des sauvegardes hors de l’hôte. Les snapshots de la CLI couvrent ces volumes mais aucun stockage externe, et laissent de côté le volume de fichiers quand le stockage par défaut pointe vers un bucket externe ; vérifie leur portée dans [Sauvegardes et restauration](https://docs.tale.dev/fr/self-hosted/operate/backups-and-restore).

## Secrets et connexion

`ENCRYPTION_SECRET_HEX` protège les identifiants des fournisseurs et les autres valeurs chiffrées dans la base applicative. SOPS et age protègent les fichiers de secrets associés aux configurations prises en charge, comme les mots de passe des stockages externes. Sauvegarde les clés nécessaires séparément des données qu’elles protègent : une nouvelle clé ne déchiffre pas les secrets existants.

Better Auth fonctionne dans le backend. Connexion locale, authentification à deux facteurs, passkeys, SSO d’entreprise et authentification par en-têtes de confiance ont des prérequis différents. [Authentification](https://docs.tale.dev/fr/self-hosted/configuration/authentication) explique leur mise en place ; [Membres et rôles](https://docs.tale.dev/fr/platform/admin/members-and-roles) décrit les droits dans l’organisation.

## Prévoir la capacité et l’isolation

Les rôles applicatifs acceptent plusieurs réplicas. La CLI les met à jour comme un groupe utilisant la même version. Pendant une mise à niveau, les anciens et nouveaux groupes coexistent : prévois la capacité nécessaire à ce chevauchement. La base, le stockage objet et les services de sandbox demandent leur propre plan de capacité et de reprise.

Tu peux déplacer la base applicative, la base de connaissances ou les fichiers vers une infrastructure externe. Une organisation peut aussi choisir sa propre base de connaissances et son bucket. Changer une connexion ne transfère pas le contenu existant. Prépare la copie, la bascule, les vérifications et les sauvegardes avec [Résidence des données](https://docs.tale.dev/fr/self-hosted/configuration/data-residency).

L’auto-hébergement détermine où Tale fonctionne. Les appels aux fournisseurs, connecteurs, récupérations web et accès réseau des sandbox dépendent toujours de ta configuration. Examine ces destinations avec les emplacements de stockage dans [Durcissement](https://docs.tale.dev/fr/self-hosted/operate/security/hardening).

# Connecter un serveur de modèles local
Source: https://docs.tale.dev/fr/tutorials/admin/connect-local-provider

Connecte un serveur local pour utiliser un modèle hébergé sur l’infrastructure de ton organisation. Il te faut un endpoint d’inférence actif, l’identifiant exact du modèle, l’accès à **Paramètres > Fournisseurs IA** et un opérateur capable de configurer la politique réseau du déploiement. Tale n’installe pas le serveur et ne charge pas ses modèles.

Un fournisseur de chat local détermine la destination de cette requête de modèle. Les embeddings, la parole, les outils et les autres fournisseurs ont leurs propres parcours. Cette connexion ne maintient donc pas automatiquement tout le trafic de l’organisation sur son réseau.

## Préparer l’endpoint avec l’opérateur

Demande le nom du fournisseur, le format d’API compatible, l’URL de base, les identifiants des modèles et la méthode d’authentification. L’adresse doit être joignable depuis les processus backend, pas seulement depuis ton navigateur. Dans un conteneur, `localhost` désigne ce conteneur.

Pour un déploiement auto-hébergé, l’opérateur suit [Endpoints de fournisseurs locaux](https://docs.tale.dev/fr/self-hosted/configuration/providers#endpoints-de-fournisseurs-locaux). Tu peux aussi créer le fournisseur toi-même dans **Paramètres > Fournisseurs IA** avec **Ajouter des identifiants** > **Fournisseur personnalisé** ([Définir un fournisseur personnalisé](https://docs.tale.dev/fr/platform/admin/providers#definir-un-fournisseur-personnalise)) ; les étapes de l’opérateur pour l’accès réseau et la politique restent nécessaires. Les hôtes privés exigent une activation explicite dans le déploiement. Les endpoints publics nécessitent HTTPS ; les adresses privées prises en charge peuvent utiliser HTTP si l’opérateur accepte cette configuration réseau. Un nom de proxy ne contourne pas la politique des hôtes privés.

Ollama, LM Studio et vLLM peuvent exposer des API compatibles, mais cela dépend des fonctions activées et du modèle. Vérifie la liste réelle des modèles et un appel de chat pris en charge avant de configurer Tale.

## Ajouter l’accès de l’organisation

1. Ouvre **Paramètres > Fournisseurs IA** et choisis **Ajouter des identifiants**.
2. Sélectionne la définition de fournisseur préparée par l’opérateur, ou choisis **Fournisseur personnalisé** pour en définir un toi-même ; un fournisseur que tu as défini porte le badge **Personnalisé**.
3. Donne un nom utile à cet accès et choisis une méthode d’authentification proposée.
4. Saisis le vrai jeton du serveur ou la référence de variable d’environnement fournie. Si le serveur ignore l’authentification, conviens de la valeur de remplacement avec son opérateur ; ne réutilise pas un autre secret.
5. Vérifie la **Liste de modèles autorisés**, puis enregistre. Définis cet accès par défaut pour le fournisseur si les appels ordinaires doivent l’utiliser.

<Frame caption="L’accès fournisseur appartient à l’organisation ; sa valeur par défaut et sa liste de modèles influencent la sélection.">

![La page Fournisseurs IA présente un accès fournisseur avec son indicateur par défaut.](https://docs.tale.dev/images/get-started/settings-providers.webp)

</Frame>

Avec un catalogue, une liste vide autorise les modèles de ce catalogue. Sans catalogue, il faut des identifiants de modèle explicites. Utilise **Actualiser les catalogues** après un changement des modèles disponibles sur le serveur. La politique d’accès aux modèles de l’organisation s’applique aussi.

## Prouver qu’une requête atteint le serveur

Commence un chat et sélectionne explicitement le modèle local. Garde **Auto** pour plus tard : ce contrôle exige un fournisseur et un modèle connus. Envoie une courte demande sans contenu sensible, comme « Réponds par prêt. »

Demande à l’opérateur de confirmer la requête dans les journaux du serveur d’inférence prévu. Vérifie que Tale affiche une réponse complète. Enregistrer un accès ou obtenir une liste de modèles prouve moins qu’une génération terminée. Sa durée dépend du modèle, du matériel et de la charge.

Si des agents de programmation doivent utiliser ce fournisseur, répète le contrôle dans une nouvelle session sandbox avec le modèle voulu et un environnement d’exécution compatible. Demande à l’opérateur de vérifier le DNS, la connectivité et la confiance TLS de la passerelle comme ceux du backend. Les règles d’accès web général de la sandbox ne configurent pas l’accès aux modèles. Une réponse de chat et une réponse d’agent valident des connexions différentes.

## Comprendre un échec

| Symptôme | Vérification |
| --- | --- |
| Fournisseur absent de la sélection | Emplacement et validation de sa définition, organisation concernée. |
| Hôte privé refusé | Activation explicite des fournisseurs privés dans le déploiement ; un nom DNS ne change pas la règle. |
| Liste de modèles vide | Découverte des modèles, modèles chargés, liste autorisée et politique de modèles. |
| Erreur de connexion ou de certificat | Accès réseau depuis le backend, nom du conteneur et confiance TLS. |
| Modèle refusé ou aucune réponse | Identifiant exact, authentification, compatibilité de l’API et capacité du serveur. |
| Le chat fonctionne, mais l’agent n’atteint pas son modèle | DNS, connectivité et confiance TLS de la passerelle, autorisation des fournisseurs privés et compatibilité de l’environnement d’exécution. |

[Fournisseurs IA](https://docs.tale.dev/fr/platform/admin/providers) explique le remplacement des accès et les valeurs par défaut. Documente l’endpoint et le modèle dans les consignes d’exploitation pour qu’un autre administrateur puisse répéter le test après une modification du serveur.

# Rendre une transcription de réunion consultable
Source: https://docs.tale.dev/fr/tutorials/admin/meeting-transcription

Transforme une transcription exportée en source de projet que les membres peuvent interroger dans le chat. Commence par un fichier texte vérifié, puis contrôle son accès et son indexation avant d’automatiser la livraison. Tu dois pouvoir modifier le projet cible et être autorisé à partager ce texte avec ses membres.

Tale ne fournit ni connecteur Meetily dédié ni dossier de transcriptions surveillé. Exporte depuis ton outil de transcription, puis utilise l’import de documents ou l’API de Tale. Ce guide commence après la transcription ; il n’enregistre pas de réunion et ne configure pas cet outil.

## Préparer la transcription

Exporte du texte lisible, de préférence un fichier `.txt` pour le premier essai. Vérifie les noms, les locuteurs, les chiffres importants et les décisions avec l’enregistrement de la réunion. Une transcription automatique peut mal reconnaître les détails sur lesquels les lecteurs s’appuieront.

Choisis un nom identifiable, comme `2026-09-14-revue-projet.txt`. Indique aussi la date, le sujet et les participants dans le texte. Retire ce qui ne doit pas être partagé avec les membres du projet. Importer le texte n’exige pas d’importer l’audio.

## Choisir les lecteurs

Importe le texte dans l’onglet **Connaissances** du projet s’il lui appartient. Les droits du projet déterminent l’accès, et la recherche se fait depuis ses chats. Choisis **Connaissances > Documents** uniquement si le texte doit rejoindre les connaissances de l’organisation avec les restrictions d’équipe appropriées.

Vérifie le public prévu avant l’import. Un fichier de projet n’apparaît pas automatiquement dans la bibliothèque de l’organisation ni dans les chats d’un autre projet.

## Importer et contrôler

1. Ouvre le projet cible et sélectionne **Connaissances**.
2. Choisis le dossier, puis **Ajouter un fichier** pour importer la transcription.
3. Ouvre le fichier et vérifie son titre et son contenu.
4. Attends **Indexé** avant de tester la recherche. **En file d'attente** et **Indexation** indiquent que la préparation continue.

<Frame caption="La liste des fichiers du projet permet de vérifier la destination et l’état d’indexation.">

![L’onglet Connaissances du projet affiche les fichiers importés et leur état d’indexation.](https://docs.tale.dev/images/platform/project-knowledge-files.webp)

</Frame>

Pour **Échec**, consulte l’erreur et utilise **Réessayer l'indexation** après l’avoir corrigée. Pour **Non indexé**, choisis **Indexer maintenant** si l’action est proposée. Un échec persistant peut nécessiter un contrôle du stockage, de l’extraction du texte et du fournisseur d’embeddings par un administrateur. [Gérer les fichiers du projet](https://docs.tale.dev/fr/platform/projects/manage-files) explique les états et les limites.

## Vérifier la recherche dans le projet

Ouvre un chat du même projet. Pose une question précise dont tu as vérifié la réponse, par exemple : « Lors de la revue du 14 septembre, qui a accepté de préparer le prochain brouillon ? » Ouvre la source citée et compare la réponse au texte original. Un import terminé ne prouve pas à lui seul que la recherche fonctionne, et une réponse de l’assistant ne remplace pas cette vérification.

Pour les transcriptions sensibles, vérifie le choix des fournisseurs : l’indexation peut envoyer du texte à un fournisseur d’embeddings, puis la réponse peut transmettre des passages au modèle de chat. Une transcription locale ne maintient pas automatiquement ces étapes sur ton réseau. Demande à l’administrateur ou à l’opérateur de contrôler les deux parcours.

## Préparer les imports récurrents

Pour des réunions occasionnelles, conserve la procédure d’import. Pour des livraisons régulières, un développeur peut utiliser l’[API d’import de projet](https://docs.tale.dev/fr/develop/api-reference) ou un [webhook d’automatisation](https://docs.tale.dev/fr/tutorials/developer/trigger-automation-via-webhook) associé à une automatisation d’import explicitement créée. Le webhook lance cette automatisation ; il n’est pas, à lui seul, un endpoint de stockage des transcriptions.

L’intégration doit choisir le projet, éviter les doublons, demander l’indexation et suivre son résultat. Les fichiers de projet importés par REST ne sont pas indexés par défaut ; `skipRagIndexing: false` demande l’indexation lors du rattachement. Réutiliser un nom de fichier ne crée pas de révision. Pour conserver un historique approuvé, utilise la procédure de remplacement prévue.

# Appeler Tale depuis un script
Source: https://docs.tale.dev/fr/tutorials/developer/call-tale-from-a-script

Envoie un message à Tale et affiche sa réponse dans ton terminal. Ce tutoriel crée un thread personnel, vérifie chaque réponse HTTP et attend la fin du tour. Il utilise curl et la bibliothèque standard de Python 3 ; aucun paquet Python supplémentaire n’est nécessaire.

## Préparer l’accès

Il te faut une instance accessible, le droit de créer une clé API, le slug de ton organisation et un modèle directement appelable. Les Admins et Développeurs peuvent créer des clés. Un modèle présent dans le catalogue peut encore échouer si le compte du fournisseur manque de crédit ou n’y donne pas accès.

Ouvre **Paramètres > API > REST**, choisis **Créer une clé API**, donne-lui un nom comme `Reporting script` et choisis une expiration. Sélectionne **Créer la clé** et copie le secret affiché une seule fois. Charge-le dans `TALE_API_KEY` depuis ton gestionnaire de secrets ou un environnement shell privé ; ne le place ni dans le fichier Python ni dans Git.

<Frame caption="Donne à la clé un nom qui explique son usage pour pouvoir la révoquer sans toucher à une autre intégration.">

![La boîte de création d’une clé API permet de choisir un nom et une durée de validité avant sa génération.](https://docs.tale.dev/images/get-started/settings-api-keys.webp)

</Frame>

Définis les valeurs non secrètes ci-dessous. Utilise le slug, pas l’ID de l’organisation. Envoie cet en-tête à chaque requête pour conserver une destination explicite si ton compte rejoint une autre organisation.

```bash
export TALE_BASE_URL="https://your-host.example.com"
export TALE_ORG_SLUG="your-org-slug"
export TALE_MODEL="model-id-from-the-catalog"
```

## Trouver un modèle accessible

Liste les modèles accessibles au titulaire de la clé :

```bash
curl --fail-with-body --silent --show-error "$TALE_BASE_URL/api/v1/models" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG"
```

Une réponse `200` contient un tableau `models`. Définis `TALE_MODEL` avec l’`id` d’une entrée. Si cet ID apparaît chez plusieurs fournisseurs, définis aussi `TALE_PROVIDER` avec le `providerSlug` choisi. Un tableau vide signifie qu’aucun modèle n’est directement accessible à ce compte. Demande à un admin de vérifier les identifiants et l’accès aux modèles.

## Envoyer et attendre une réponse

Enregistre ce code dans `tale-chat.py`, puis lance `python3 tale-chat.py` dans l’environnement préparé. Le script crée un thread dans ton historique personnel et peut entraîner des frais d’utilisation du modèle.

```python
import json
import os
import time
from urllib.error import HTTPError
from urllib.request import Request, urlopen

base = os.environ["TALE_BASE_URL"].rstrip("/")
headers = {
    "Authorization": f"Bearer {os.environ['TALE_API_KEY']}",
    "X-Organization-Slug": os.environ["TALE_ORG_SLUG"],
    "Content-Type": "application/json",
}

def request(method, path, body=None):
    data = None if body is None else json.dumps(body).encode()
    req = Request(f"{base}/api/v1{path}", data=data, headers=headers, method=method)
    try:
        with urlopen(req, timeout=30) as response:
            raw = response.read()
            return json.loads(raw) if raw else None
    except HTTPError as error:
        detail = error.read().decode(errors="replace")
        raise SystemExit(f"HTTP {error.code}: {detail}") from error

models = request("GET", "/models")["models"]
model_id = os.environ["TALE_MODEL"]
provider = os.environ.get("TALE_PROVIDER")
candidates = [m for m in models if m["id"] == model_id
              and (not provider or m["providerSlug"] == provider)]
if len(candidates) != 1:
    raise SystemExit("Choose one available model/provider pair from GET /api/v1/models")

thread = request("POST", "/threads", {})
path = f"/threads/{thread['id']}"
sent = request("POST", f"{path}/messages", {
    "content": "In one sentence: what is Tale?",
    "model": candidates[0]["id"],
    "providerSlug": candidates[0]["providerSlug"],
})
reply_id = sent["messageId"]
deadline = time.monotonic() + 600
while True:
    generation = request("GET", f"{path}/generation")
    if generation["status"] == "idle":
        break
    if time.monotonic() >= deadline:
        request("DELETE", f"{path}/generation")
        raise SystemExit("Stopped the turn after the local 10-minute deadline")
    time.sleep(2)

if generation.get("lastMessageId") != reply_id:
    raise SystemExit("The accepted turn did not finish in this thread scope")
reply = request("GET", f"{path}/messages/{reply_id}")
if reply["status"] != "complete":
    raise SystemExit(f"Turn {reply['status']}: {reply.get('errorCode', '')} {reply.get('error', '')}")
if reply.get("finishReason") == "length":
    raise SystemExit("The reply reached its output limit; inspect it before using it")
text = "".join(part["text"] for part in reply["parts"] if part.get("type") == "text")
if not text:
    raise SystemExit("The turn completed without a text answer")
print(text)
```

L’envoi renvoie `202` et une `messageId` avant la fin de la génération. L’état `idle` indique que le tour s’est arrêté, pas forcément qu’il a réussi. Le script lit ensuite ce message précis et vérifie son statut, sa limite de sortie et son texte avant de l’afficher.

<Tip>

Conserve l’ID du thread pour prolonger cette intégration. Envoie les messages suivants au même thread pour garder le contexte ; créer un thread à chaque appel démarre une nouvelle conversation.

</Tip>

## Diagnostiquer un échec

| Résultat | Action suivante |
| --- | --- |
| `401` | Vérifie si la clé a expiré, a été révoquée ou a été mal copiée. |
| `400` avec `ORG_SLUG_REQUIRED` | Fournis le slug de l’organisation visée, pris dans `data.organizations`. |
| `404` avec `ORG_SLUG_INVALID` | Le slug ne désigne aucune organisation du tout : vérifie l’orthographe, et ne colle jamais l’identifiant d’organisation de l’URL du tableau de bord. Choisis un slug dans `data.organizations`. |
| `403` avec `ORG_FORBIDDEN` | L’organisation existe, mais le détenteur de la clé n’en est pas membre : choisis un slug dans `data.organizations`. |
| `403` | Vérifie les droits du titulaire de la clé pour l’opération. |
| Aucun modèle correspondant | Relis `/models` et choisis une paire exacte ID/fournisseur. |
| `429` | Respecte `Retry-After` ; consulte les [limites de débit](https://docs.tale.dev/fr/develop/rate-limits). |
| Statut du message `failed` | Lis `errorCode` et corrige le compte ou le modèle avant de réessayer. |
| Délai réseau dépassé | Vérifie l’instance et le thread existant avant de renvoyer le message. |

Un POST dont le délai expire peut déjà avoir été accepté. Ne le renvoie pas sans vérifier l’état de génération et les messages du thread.

La limite de dix minutes est un choix de cet exemple, pas un délai du serveur. Un tour en file peut attendre derrière d’autres clients ; le raisonnement peut garder le modèle actif avant tout texte visible. Le script ne répète pas automatiquement un envoi en échec. Pour des relances autonomes, conserve un `Idempotency-Key` de 1 à 255 caractères ASCII imprimables avec le corps de la requête, réutilise les deux après une réponse perdue et respecte `Retry-After` en cas de `429`. Consulte [les relances sans doublon](https://docs.tale.dev/fr/develop/api-reference#relancer-un-envoi-sans-doublon).

## Prolonger l’intégration

Pour les conversations d’un projet, utilise `/api/v1/projects/{id}/threads` pour la création, les messages, la génération et les lectures. Tu dois avoir accès au projet actif. Ajouter `projectId` au corps d’une requête de thread personnel ne change pas son périmètre.

La [référence API](https://docs.tale.dev/fr/develop/api-reference) décrit les droits sur les projets, les parties des messages et les exécutions d’automations. Pour déclencher du travail à l’arrivée d’un événement externe, poursuis avec [Déclencher une automation par webhook](https://docs.tale.dev/fr/tutorials/developer/trigger-automation-via-webhook).

# Déclencher une automation par webhook
Source: https://docs.tale.dev/fr/tutorials/developer/trigger-automation-via-webhook

Relie un événement externe à une automation déployée et vérifie son acceptation puis son résultat. Ce tutoriel utilise un webhook de projet, une clé API pour la configuration et la lecture, et curl pour l’envoi. L’expéditeur externe n’a besoin que de l’URL du webhook.

## Préparer une automation de test sans effet externe

Choisis une automation déployée dont les tests passent et qui ne peut ni envoyer de messages, ni modifier des données clients, ni produire d’autres effets externes. Une transformation qui renvoie son entrée suffit. Crée-la et déploie-la dans l’application ou via [MCP](https://docs.tale.dev/fr/develop/mcp-endpoint) ; REST ne crée ni ne déploie les définitions.

Utilise un projet actif où tu peux modifier les données et une clé avec les droits Développeur. Définis `TALE_BASE_URL`, `TALE_API_KEY`, `TALE_ORG_SLUG`, `TALE_PROJECT_ID` et `TALE_AUTOMATION`. L’organisation utilise un slug ; le projet utilise un ID. Dans l’URL, remplace `/` à l’intérieur du nom d’automation par `__`.

## Installer l’automation dans le projet

Une livraison webhook exige que l’automation soit installée dans le projet nommé par l’URL. Installe-la avec le nom dans le chemin et un corps vide :

```bash
curl --fail-with-body --silent --show-error --request POST \
  "$TALE_BASE_URL/api/v1/projects/$TALE_PROJECT_ID/automations/$TALE_AUTOMATION" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG" \
  -H "Content-Type: application/json" --data '{}'
```

La première installation renvoie `201`, la suivante `200`. Un appel à la collection `/automations` n’installe rien. Lis le contrat d’entrée de la version déployée avant d’envoyer une livraison.

## Créer et protéger le déclencheur

Lie un déclencheur webhook à cette nouvelle automation de test :

```bash
curl --fail-with-body --silent --show-error --request PUT \
  "$TALE_BASE_URL/api/v1/automations/$TALE_AUTOMATION/triggers" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG" \
  -H "Content-Type: application/json" --data '{"kind":"webhook"}'
```

Copie le `token` renvoyé dans la variable privée `TALE_WEBHOOK_TOKEN`. Tale ne donne la valeur en clair qu’à la création ou à la rotation. Une lecture ultérieure ne la récupère pas.

<Warning>

L’URL est un identifiant d’accès. Toute personne qui la connaît peut envoyer des livraisons. Garde-la hors du code, des captures et des logs publics. Lier un webhook remplace le déclencheur existant de cette automation ; utilise bien celle choisie pour le test.

</Warning>

Le déclencheur suit le nom de l’automation et utilise sa version déployée. Une nouvelle version peut donc changer le travail exécuté par la même URL. Si elle fuit, remplace le token ou retire le déclencheur. Le désactiver ne fait que le suspendre ; le réactiver rétablit le même token.

## Envoyer une livraison

Envoie l’événement avec un identifiant de livraison stable :

```bash
curl --fail-with-body --silent --show-error \
  "$TALE_BASE_URL/api/projects/$TALE_PROJECT_ID/automations/webhook/$TALE_WEBHOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-12345-paid" \
  --data '{"orderId":"12345","amount":199.0}'
```

L’acceptation renvoie `202` avec `runId`. Conserve cet ID dans `TALE_RUN_ID`. L’automation reçoit `{"trigger":"webhook","payload":<body>}` ; l’ID de commande se trouve donc dans `input.payload.orderId`. Un schéma d’entrée doit décrire cette enveloppe.

Répète la commande. Pendant la fenêtre de déduplication, la réponse garde le même `runId` et ajoute `duplicate: true` ; aucune seconde exécution ne démarre. Les IDs sont retenus 24 heures. Sans en-tête d’ID, seuls les corps aux octets identiques sont dédupliqués pendant deux minutes. Utilise un nouvel ID pour un nouvel événement.

## Vérifier le résultat

Lis l’exécution avec ta clé API dans le même projet :

```bash
curl --fail-with-body --silent --show-error \
  "$TALE_BASE_URL/api/v1/projects/$TALE_PROJECT_ID/runs/$TALE_RUN_ID" \
  -H "Authorization: Bearer $TALE_API_KEY" \
  -H "X-Organization-Slug: $TALE_ORG_SLUG"
```

Attends un statut final et inspecte `output` et `trace`. Pour la transformation qui renvoie son entrée, vérifie l’ID de commande et le montant envoyés. La réponse de livraison `202` ne prouve pas à elle seule ce résultat.

Si l’exécution échoue, lis `failureCode` et `detail`, puis examine le nœud concerné et les effets déjà produits. Réutiliser le même ID de livraison retrouve l’exécution initiale, même en échec ; cela ne relance pas son travail. Un autre ID démarre un nouveau traitement : vérifie d’abord si les nœuds déjà terminés peuvent être répétés sans risque.

## Reprendre une livraison

| Réponse | Correction |
| --- | --- |
| `400` | Lis `code` et les problèmes d’entrée. Corrige l’enveloppe ou retire le paramètre de requête `projectId`. |
| `403` | Vérifie que le projet est actif et que l’automation y est installée. |
| `404` | Vérifie le token et l’activation. L’endpoint ne révèle pas lequel pose problème. |
| `409` | Lis `code` : déploie une version, corrige le périmètre de l’URL ou résous le conflit de livraison. |
| `413` | Réduis le corps sous 256 KiB ou envoie une référence. |
| `429` | Attends selon `Retry-After`, puis renvoie le même ID de livraison. |

Réessaie les erreurs réseau et temporaires du serveur avec une attente progressive bornée et le même ID. Corrige d’abord les autres erreurs client ; répéter une requête invalide ne répare pas la configuration. Retire le déclencheur de test lorsque tu n’as plus besoin de son URL. La [référence webhook](https://docs.tale.dev/fr/develop/webhooks) détaille les en-têtes d’ID, la rotation et les limites.

# Créer ton premier agent
Source: https://docs.tale.dev/fr/tutorials/editor/first-agent-end-to-end

Crée un agent qui résume le message d’un contact et recommande une prochaine action. Cet exercice prend la description de la tâche comme entrée. Tu peux ainsi vérifier tout le parcours avant d’ajouter des connecteurs ou des connaissances partagées : configurer l’agent, lancer une tâche, puis relire le résultat.

## Avant de commencer

Il te faut un projet que tu peux modifier, un harness d’agent de code disponible avec des identifiants de modèle compatibles et une allocation de sandbox fonctionnelle. Un administrateur gère les [fournisseurs d’IA](https://docs.tale.dev/fr/platform/admin/providers) et les [Sandboxes](https://docs.tale.dev/fr/platform/admin/sandboxes). Un modèle utilisable dans Chat ne suffit pas à lui seul : le harness choisi doit pouvoir utiliser ses identifiants.

Si la page Agents ou la liste des modèles manque, règle d’abord l’accès ou la configuration. Ce tutoriel ne nécessite ni skills, ni connecteurs, ni outils de plateforme, ni secrets injectés.

## Créer l’agent

Ouvre l’onglet **Agents** du projet et clique sur **Nouvel agent**.

<Frame caption="Le tableau identifie chaque agent par son harness, son fournisseur et son modèle.">

![Website relaunch liste Content editor avec Claude Code et Redirect auditor avec Codex, leurs fournisseurs et modèles, à côté de Nouvel agent.](https://docs.tale.dev/images/platform/project-agents-models.webp)

</Frame>

1. Dans **Nom**, saisis `Assistant de triage`.
2. Choisis un **Harness** configuré par ton administrateur.
3. Sous **Modèle**, cherche par nom de modèle ou identifiant API, puis sélectionne l’entrée du fournisseur voulu. Un même modèle peut être proposé par plusieurs fournisseurs.
4. Sous **Skills, connectors & outils**, décoche les éventuels skills de documents présélectionnés, et laisse **Secrets** vide pour cet exercice.
5. Colle les instructions ci-dessous dans **Instructions**, puis clique sur **Créer l'agent**.

```text
Lis le message du contact dans la description de la tâche. Réponds en deux lignes :
Résumé : une phrase qui explique le besoin de la personne.
Prochaine action : répondre, escalader ou clore, avec une courte justification.
Si la demande est inexploitable, précise quelle information manque.
Ne contacte personne et ne modifie aucune fiche.
```

La nouvelle ligne est prête à recevoir une tâche. Il n’y a pas d’étape de publication. Garde les instructions de l’agent pour son travail récurrent ; le message individuel appartient à la tâche.

## Lui confier une tâche vérifiable

Ouvre **Tâches**, crée `Trier la demande de copie de facture` et colle cette description :

```text
Message du contact :
« Bonjour, j’ai reçu la confirmation de commande, mais je ne trouve pas la
facture. Pourriez-vous m’en envoyer une copie ? La commande est A-1042. »

Critères d’acceptation :
- Résumer la demande en une phrase.
- Recommander répondre, escalader ou clore, avec une justification.
- Ne pas affirmer que la facture a déjà été envoyée.
```

Assigne la tâche à `Assistant de triage`. Ouvre ses détails pour choisir un **Relecteur** si quelqu’un d’autre doit la relire ; sinon, son créateur reçoit la demande de relecture. Clique sur **Démarrer l'agent**. L’assignation seule ne lance pas le travail.

La tâche passe à **En cours**. Une exécution réussie publie son rapport en commentaire et déplace la tâche vers **En revue**. La sandbox et le fournisseur doivent fonctionner pour que l’exécution aboutisse.

## Relire et améliorer le résultat

Compare le commentaire de l’agent aux critères d’acceptation. Une réponse convenable reconnaît une demande de copie de facture et recommande de répondre. Elle ne doit pas prétendre qu’un e-mail a été envoyé. La formulation peut varier selon le modèle.

Passe la tâche à **Terminé** lorsque tu acceptes le résultat. S’il manque quelque chose, mentionne l’agent assigné dans un commentaire avec une correction précise : « Limite le résumé à une phrase et explique pourquoi une réponse est nécessaire. » La reprise poursuit la conversation de la tâche et fournit un nouveau résultat à relire.

<Tip>

Utilise un commentaire de tâche pour une correction ponctuelle. Modifie les instructions de l’agent si la règle doit aussi s’appliquer aux tâches suivantes. Ajoute des outils lorsqu’un exercice ultérieur nécessite de lire ou modifier quelque chose hors des données fournies.

</Tip>

## Si l’exécution ne démarre pas ou ne se termine pas

Un modèle manquant appelle une vérification du fournisseur et du harness. Une erreur de sandbox nécessite qu’un administrateur vérifie la capacité et l’infrastructure. Une exécution échouée reste consultable : corrige la cause avant de la relancer. Ne redémarre pas plusieurs fois une tâche dont l’exécution est déjà active.

[L’automatisation des tâches](https://docs.tale.dev/fr/platform/projects/task-automation) explique les relances, l’annulation, le passage en relecture et les reprises. [Agents de projet](https://docs.tale.dev/fr/platform/projects/project-agents) présente l’équipement à ajouter une fois cette première tâche validée.

# Créer un workflow avec approbation
Source: https://docs.tale.dev/fr/tutorials/editor/workflow-with-approvals

Cet exercice crée un workflow en deux étapes : préparer un message, puis demander l’autorisation de l’envoyer. Tu examineras le destinataire et le texte exacts dans une exécution en attente avant de refuser l’opération. Tu parcourras ainsi une approbation complète sans avoir à distribuer de vrai message.

## Avant de commencer

Utilise un compte Développeur, Admin ou Propriétaire. Vérifie que la politique de ton organisation exige une approbation pour `imap-smtp.send` ; c’est le comportement par défaut. Une politique personnalisée peut le modifier. Consulte donc [Configurer les approbations](https://docs.tale.dev/fr/platform/approvals/configure) avant la partie réelle.

Le test simulé n’a pas besoin d’identifiants de messagerie. Un envoi réellement approuvé nécessiterait un connecteur IMAP / SMTP configuré et un destinataire que tu souhaites contacter. Cet exercice se termine par **Rejeter**.

## Importer l’exemple

Enregistre le contenu suivant dans `workflow.yml`. Le nœud `draft` renvoie un texte fixe pour faciliter la vérification. Le nœud `send` le lit ; ces références dessinent la connexion sur le canvas.

```yaml
version: 1
name: docs/approval-check
description: Practice reviewing an outgoing message before it is sent.
nodes:
  - id: draft
    type: transform
    code: |
      return {
        subject: "Approval practice",
        text: "This is a test message for the approval walkthrough."
      };
  - id: send
    type: imap-smtp.send
    input:
      to: reviewer@example.com
      subject: '{{ nodes.draft.output.subject }}'
      text: '{{ nodes.draft.output.text }}'
output:
  messageId: '{{ nodes.send.output.messageId }}'
tests:
  - name: prepares the outgoing message
    input: {}
    expect:
      effects:
        - connector: imap-smtp.send
```

1. Ouvre **Automatisations > Créer une automatisation > Téléverser un paquet**.
2. Choisis `workflow.yml` et laisse **Installer dans** sur **Organisation**.
3. Clique sur **Téléverser le paquet**. Tale valide le document et enregistre `docs/approval-check` en brouillon.
4. Choisis **Plus tard** dans la proposition de déploiement, puis ouvre **Approval check** dans la liste. L’automatisation s’ouvre dans l’onglet **Éditeur**.

Si ce nom existe déjà, l’import ajoute une version. Choisis une autre valeur de `name` pour garder un exercice séparé.

<Frame caption="Le dialogue d’import accepte le fichier de workflow et propose l’organisation ou un projet comme destination.">

![Le dialogue de téléversement d’un paquet affiche le sélecteur de fichiers et la destination Organisation.](https://docs.tale.dev/images/platform/automations-upload-dialog.webp)

</Frame>

## Tester le flux de données

Dans **Éditeur**, clique sur **Essai**. Cet exemple ne demande aucune donnée d’exécution ; un objet vide suffit. Passe à **Exécutions** : la liste doit afficher une exécution de test au statut **Réussie**.

Ouvre l’exécution et vérifie sur le canvas que les deux nœuds ont été exécutés. Sélectionne `send` et examine ses données résolues. Le destinataire doit être `reviewer@example.com`, l’objet `Approval practice` et le texte la phrase de `draft`. Le connecteur utilise une simulation déterministe dans ce mode. Aucun e-mail n’est envoyé et aucune carte d’approbation n’apparaît.

Le workflow comprend un test qui attend l’effet `imap-smtp.send`. Une simulation réussie vérifie le graphe et l’appel prévu. Elle ne prouve ni la validité des identifiants de messagerie ni la livraison du message.

## Démarrer la vérification réelle

Reviens à **Éditeur** et clique sur **Mettre v1 en service** pour rendre la version testée active. Laisse le déclencheur non configuré : cet exercice se lance une fois manuellement.

Choisis **Exécuter en réel**, lis la confirmation et le périmètre de l’organisation, puis confirme. Passe à **Exécutions** et ouvre la nouvelle exécution en attente. La carte doit présenter l’approbation attendue, `imap-smtp.send`, le nœud `send` et les données de l’appel prévu. Destinataire, objet et texte doivent correspondre au test simulé.

Si l’exécution ne se met pas en attente, examine son statut et la politique avant de continuer. Un appel de connecteur échoué ne prouve pas qu’une approbation a été demandée.

## Refuser et examiner le résultat

Clique sur **Rejeter** sur la carte. L’opération est refusée et l’exécution se termine en **En échec**. C’est le résultat attendu ici : le workflow a atteint la décision humaine et le message n’a pas été envoyé.

Tu ne peux pas modifier les paramètres d’un appel en attente sur la carte. Si un vrai message proposé est incorrect, rejette-le, corrige la définition ou les données et démarre une nouvelle exécution. Approuver ensuite un appel correct autorise l’opération réelle ; cela ne signifie pas seulement que tu as lu la carte.

Lorsqu’un agent a besoin d’une réponse plutôt que d’une permission, il utilise `ask_human`. Cette attente différente est expliquée dans [Approbations dans les workflows](https://docs.tale.dev/fr/platform/automations/approvals-in-workflows). [Journaux d’exécution](https://docs.tale.dev/fr/platform/automations/execution-logs) aide à distinguer ces attentes d’un agent encore au travail.

# Obtenir une réponse utile dans Chat
Source: https://docs.tale.dev/fr/tutorials/member/chat-effectively

Une réponse utile commence par une question claire et se termine par une vérification de la source. Pour cet exercice, utilise un court document que tu as le droit d’importer. Interroge-le sur un fait, puis vérifie si l’assistant distingue ce qui est écrit de ce qui reste ouvert.

Tu dois avoir accès à Chat et à un modèle disponible. Les questions sur les documents nécessitent aussi une indexation fonctionnelle dans l’organisation. Si tu disposes déjà d’un document adapté et indexé, tu peux l’utiliser à la place de l’exemple.

## Préparer une petite source

Enregistre ce texte sur ton appareil dans `launch-brief.txt` :

```text
Brief de refonte du site
La relecture avec le client est prévue le 18 septembre 2026.
Maya Chen est responsable de la checklist de relecture.
La date de lancement n’est pas approuvée.
La relecture doit couvrir l’accessibilité, les redirections et le formulaire de contact.
```

Ouvre un nouveau chat et joins le fichier avec **Ajouter photos et fichiers** dans le menu du champ de message. Attends la fin de l’import et de l’indexation avant de poser une question sur son texte. [Pièces jointes du chat](https://docs.tale.dev/fr/platform/chat/attachments) explique les états affichés.

## Demander un résultat précis

Envoie :

```text
À partir de launch-brief.txt, indique la date de relecture, la personne
responsable et les trois sujets à vérifier. Cite la source. Utilise quatre puces.
```

La demande précise la source, les informations nécessaires et la forme attendue. Elle est plus facile à évaluer que « Parle-moi du lancement ». **Auto** convient pour commencer. Choisis explicitement un modèle lorsque tu veux comparer son comportement à celui d’un autre.

<Frame caption="Garde la question sous les yeux pour vérifier si la réponse y satisfait.">

![Un chat montre une question ciblée sur les retours d’onboarding et une réponse présentée en tableau.](https://docs.tale.dev/images/platform/chat-thread-reply.webp)

</Frame>

## Comparer la réponse au fichier

La date de relecture doit être le **18 septembre 2026**, la responsable **Maya Chen** et les sujets **l’accessibilité, les redirections et le formulaire de contact**. Ouvre la source citée et compare ces valeurs. La présentation peut varier ; les faits doivent rester les mêmes.

Si la réponse ne cite pas de source, demande une citation du document au lieu de supposer que la pièce jointe a été lue. Si le contenu reste introuvable, vérifie l’indexation et réessaie lorsque le fichier est prêt. Une réponse fluide ne prouve pas que la source a été consultée.

## Poser une relance qui révèle l’incertitude

Dans la même conversation, demande :

```text
Quelle est la date de lancement approuvée ? Si le brief n’en donne pas,
indique-le clairement.
```

La source ne donne **pas** de date de lancement approuvée. Une bonne réponse conserve cette distinction au lieu de prendre la date de relecture pour celle du lancement. Si une réponse fait une supposition sans preuve, cite la phrase contradictoire et demande une correction.

<Tip>

Modifie un élément de la demande à la fois. « Fais plus court » teste la longueur ; « Sépare les dates confirmées des décisions ouvertes » teste l’interprétation. Changer en même temps source, modèle, question et format empêche de comprendre ce qui a amélioré le résultat.

</Tip>

## Conserver le contexte utile

Poursuis dans le même chat pour les questions liées au sujet. Commence un autre chat pour un sujet sans rapport, afin que les anciennes hypothèses ne gênent pas la nouvelle demande. Si plusieurs conversations ont besoin de ce brief, place-le dans un [projet](https://docs.tale.dev/fr/tutorials/member/use-projects) et utilise le chat du projet.

Avant de [partager un chat](https://docs.tale.dev/fr/platform/chat/shared-threads), relis les messages et les extraits de sources cités dans la réponse. Si la suite consiste à produire un livrable avec un responsable et une relecture, crée une [tâche de projet](https://docs.tale.dev/fr/platform/projects/tasks) avec les faits vérifiés et les critères d’acceptation.

# Utiliser un projet pour partager le contexte
Source: https://docs.tale.dev/fr/tutorials/member/use-projects

Un projet réunit les fichiers, les instructions, les conversations et les tâches d’un même travail. Dans ce parcours, tu poses une question à laquelle répond un fichier de référence du projet, tu partages la conversation utile et tu confies le livrable qui en découle à l’un des agents du projet. Prévois environ quinze minutes, auxquelles s’ajoutent le temps d’indexation et celui de l’exécution de l’agent.

## Avant de commencer

En tant que **Membre**, tu travailles dans les projets partagés avec toi : tu poses des questions dans leurs chats, tu partages des conversations et tu crées des tâches pour les agents du projet. Prends un projet que tu peux ouvrir, avec un fichier de référence indexé, puis commence à [Poser une question et vérifier la source](https://docs.tale.dev/fr/tutorials/member/use-projects#poser-une-question-et-verifier-la-source). Un projet sans agents propres confie ses tâches à l’[agent standard](https://docs.tale.dev/fr/platform/projects/project-agents#standard-agent) de l’organisation, sauf si un admin l’a désactivé. Créer un projet, importer ses fichiers, enregistrer ses instructions et ajouter des agents demandent le rôle **Éditeur** ou supérieur ; si tu prépares le projet, commence à [Préparer le projet](https://docs.tale.dev/fr/tutorials/member/use-projects#preparer-le-projet). Il te faut un court document texte, un PDF dont le texte est sélectionnable ou un fichier Office récent. Choisis un contenu vérifiable, par exemple un brief qui nomme une personne responsable et une date de revue. Un admin doit avoir configuré le stockage documentaire et un modèle d’embedding pour rendre les fichiers consultables.

Les nouveaux projets sont accessibles à **Toute l'organisation**. Utilise un document sans données sensibles pour ce parcours. Si ton projet doit être restreint, choisis son équipe propriétaire sous **Général > Partage** avant d’importer ses fichiers. Les chats du projet restent personnels tant que tu ne les partages pas.

## Préparer le projet

Les Éditeurs et les rôles supérieurs le font une fois par projet. Les Membres passent directement à [Poser une question et vérifier la source](https://docs.tale.dev/fr/tutorials/member/use-projects#poser-une-question-et-verifier-la-source).

### Créer le projet

1. Dans **Accueil**, clique sur **Nouveau projet**, l’icône de dossier à côté de **Projets**.
2. Renseigne **Nom du projet** avec un nom reconnaissable, par exemple `Refonte du site`.
3. Vérifie la **Clé du projet**, le préfixe des identifiants de tâches tels que `WEB-1`. Elle ne peut plus être modifiée après la création.
4. Ajoute une **Description** si nécessaire, puis clique sur **Créer le projet**.

Le projet s’ouvre sur **Tâches** et apparaît sous **Projets** dans **Accueil**. Sa navigation comprend aussi **Général**, **Chats**, **Connaissances** et **Agents**. Tu n’as pas besoin de créer un agent pour utiliser le chat du projet.

### Ajouter un fichier de référence

Ouvre **Connaissances** dans le projet et clique sur **Ajouter un fichier**, ou dépose le fichier dans la zone d’import. Il apparaît dans l’arborescence du projet. Attends le statut **Indexé** avant de te fier à la recherche ; **En file d'attente** et **Indexation…** indiquent que la préparation continue.

<Frame caption="L’onglet Connaissances conserve les fichiers du projet. Le statut de chaque fichier indique s’il est consultable.">

![L’onglet Connaissances du projet Website relaunch affiche deux fichiers indexés et les commandes pour ajouter des fichiers et des dossiers.](https://docs.tale.dev/images/platform/project-knowledge-files.webp)

</Frame>

Un fichier ajouté ici appartient à ce projet. Pose tes questions à son sujet dans un chat du projet. Le chat général de l’organisation ne recherche pas dans les fichiers des projets.

### Donner des instructions à tous les chats du projet

Ouvre **Général**, puis décris dans **Instructions** le contexte ou les contraintes que chaque chat doit suivre. Par exemple :

> Utilise les fichiers du projet pour répondre aux questions sur ce lancement. Cite la source des dates et des décisions. Si la date de lancement n’a pas été approuvée, indique qu’elle reste à confirmer.

Clique sur **Enregistrer** en haut de la page. Ces instructions font partie du contexte des chats du projet. Elles ne remplacent ni l’import des documents ni leur consultation par l’assistant.

<Frame caption="Les instructions se trouvent dans Général, avec le nom et la description du projet.">

![L’onglet Général contient le nom du projet, sa description, l’éditeur d’instructions et la section Partage, avec Enregistrer et Abandonner dans l’en-tête.](https://docs.tale.dev/images/platform/project-general-tab.webp)

</Frame>

La dernière partie de ce parcours confie une tâche à un agent : l’un des agents du projet ou, tant qu’il n’en a pas, l’[agent standard](https://docs.tale.dev/fr/platform/projects/project-agents#standard-agent) de l’organisation. [Agents du projet](https://docs.tale.dev/fr/platform/projects/project-agents) explique comment en ajouter un.

## Poser une question et vérifier la source

Ouvre **Chats** et clique sur **Nouveau chat**. Garde **Auto** lorsqu’il est proposé, puis pose une question dont la réponse figure dans ton fichier. Pour un brief de lancement, essaie :

> Lis le brief de lancement. Qui est responsable de la revue, et quelles dates sont confirmées ? Cite le fichier et distingue les dates confirmées des décisions encore ouvertes.

Consulte les étapes de recherche et de lecture au-dessus de la réponse, puis compare les informations avec le fichier. Une réponse fluide sans source pertinente ne prouve pas que Tale a utilisé ton document. Rouvre **Connaissances** pour examiner l’original si nécessaire.

<Tip>

Nomme le document et pose une question précise. « Quelle date de revue est confirmée dans le brief de lancement ? » donne une cible plus claire que « Parle-moi du projet ».

</Tip>

## Partager une conversation utile

L’onglet **Chats** sépare **Tes chats** et **Partagés avec le projet**. Active **Partager avec le projet** lorsqu’un chat doit être lisible par les personnes ayant accès au projet. Ajouter des fichiers au projet ne partage pas automatiquement tes chats.

Pour envoyer un lien vers un instantané aux membres de l’organisation, suis [Chats partagés](https://docs.tale.dev/fr/platform/chat/shared-threads). Relis la conversation avant de la partager : elle peut reprendre des informations issues de sources dont l’accès est plus restreint.

## Confier la suite à un agent du projet

Le chat répond aux questions ; il ne produit pas de fichiers. Quand la réponse doit devenir un document, par exemple une synthèse de lancement d’une page, confie le travail à l’un des agents du projet au moyen d’une tâche.

1. Dans l’en-tête de la conversation, sélectionne **Créer une tâche**. Comme le chat appartient à ce projet, **Créer une tâche** s’y ouvre, avec ta dernière question comme description, un lien vers le chat et les fichiers que tu as joints.
2. Reformule la description en résultat attendu, par exemple : `Rédige à partir du brief une synthèse de lancement d’une page au format Word. Cite le brief pour chaque date.`
3. Sous **Assigné à**, choisis l’un des agents du projet si aucun n’est encore choisi ; dans un projet sans agents propres, l’agent standard l’est déjà. Sélectionne ensuite **Créer et démarrer l'agent**.
4. Suis l’exécution au-dessus du champ de message du chat ; **Ouvrir** te mène alors à la tâche.

À la fin de l’exécution, le rapport de l’agent se trouve dans les commentaires de la tâche, le fichier sous **Fichiers produits**, et la tâche attend en **En revue**. Mentionne l’agent avec `@` dans un commentaire pour demander des modifications, et passe la tâche à **Terminé** lorsque le résultat correspond à la description.

Toute personne qui peut ouvrir un projet peut y créer des tâches. Une exécution démarrée par un Membre reste limitée à cette tâche et à ses sous-tâches, sans les secrets de l’agent ; [Exécutions démarrées par un Membre](https://docs.tale.dev/fr/platform/projects/tasks#executions-demarrees-par-un-membre) détaille ces limites.

## Si le fichier manque dans la réponse

| Ce que tu observes | Vérification |
| --- | --- |
| L’import échoue avant qu’une ligne apparaisse | Réessaie avec un petit fichier dans un format accepté. Si l’échec se répète, demande à un admin de vérifier le stockage et la politique d’import. |
| **En file d'attente** ou **Indexation…** | Attends la fin du traitement, puis repose la question. |
| **Échec** | Utilise **Réessayer l'indexation**. Si le problème revient, demande à un admin de vérifier le modèle d’embedding et le service de connaissances. |
| **Non indexé** | Utilise **Indexer maintenant** lorsque cette action est proposée. Pour un ancien fichier Office sans extracteur compatible, enregistre-le dans le format récent. |
| **Indexé**, mais aucune source pertinente dans la réponse | Vérifie que le chat appartient au projet, nomme le fichier et demande une information précise. Compare la réponse avec l’original. |

Le projet réunit désormais ses sources, ses conversations et ses tâches. [Gérer les tâches du projet](https://docs.tale.dev/fr/platform/projects/tasks) présente le tableau, la revue et le travail récurrent.

# Tutoriels
Source: https://docs.tale.dev/fr/tutorials/overview

Choisis une tâche à essayer dans ton espace de travail. Chaque tutoriel précise le point de départ, propose des exemples et te donne des repères pour vérifier le résultat. Si tu découvres Tale, commence par [ton premier chat](https://docs.tale.dev/fr/get-started/quickstart).

## Commencer par le travail quotidien

<CardGroup cols="2">

<Card title="Obtenir une réponse utile" icon="message-circle" href="https://docs.tale.dev/fr/tutorials/member/chat-effectively">

Donne du contexte au modèle, affine sa réponse et vérifie le résultat avant de l'utiliser.

</Card>

<Card title="Organiser le travail dans un projet" icon="folder" href="https://docs.tale.dev/fr/tutorials/member/use-projects">

Réunis une tâche, un fichier source et les instructions du projet. Choisis ce que tu partages avec ton équipe.

</Card>

</CardGroup>

## Créer des processus et connecter des systèmes

Ces tutoriels demandent des droits supplémentaires ou un service déjà configuré. Consulte les prérequis de la page avant de commencer. Un chat ordinaire ne nécessite pas de harness d'agent.

| Ton objectif | Tutoriel | Ce qu'il te faut |
| --- | --- | --- |
| Déléguer une tâche de projet | [Exécuter ton premier agent](https://docs.tale.dev/fr/tutorials/editor/first-agent-end-to-end) | Le droit de configurer les agents du projet, un modèle et un harness opérationnel |
| Vérifier une action avant son exécution | [Créer un workflow avec approbations](https://docs.tale.dev/fr/tutorials/editor/workflow-with-approvals) | Le droit de modifier les automatisations et une personne autorisée à approuver |
| Envoyer un message depuis ton programme | [Appeler Tale depuis un script](https://docs.tale.dev/fr/tutorials/developer/call-tale-from-a-script) | Une instance opérationnelle, un modèle, une clé API et Python |
| Lancer une automatisation depuis un autre système | [Déclencher une automatisation par webhook](https://docs.tale.dev/fr/tutorials/developer/trigger-automation-via-webhook) | Une automatisation publiée et un identifiant de webhook conservé en lieu sûr |
| Connecter un serveur de modèles local | [Connecter un fournisseur local](https://docs.tale.dev/fr/tutorials/admin/connect-local-provider) | Les droits d'administration et un serveur de modèles accessible depuis Tale |
| Retrouver des informations dans une transcription | [Ajouter une transcription à un projet](https://docs.tale.dev/fr/tutorials/admin/meeting-transcription) | Une transcription relue, le droit de modifier le projet et une indexation opérationnelle |

## Consulter une référence en cours de route

Les [guides de la plateforme](https://docs.tale.dev/fr/platform) expliquent chaque fonctionnalité et ses limites. La [documentation Self-hosted](https://docs.tale.dev/fr/self-hosted) couvre le déploiement et la configuration du serveur. La [documentation de développement](https://docs.tale.dev/fr/develop/overview) décrit les API et les contributions au code source.

# Épisode 5 — Automatisations & validations
Source: https://docs.tale.dev/fr/tutorials/videos/automations-and-approvals

À la fin de cet épisode, tu auras vraiment utilisé une automatisation : tu lis le workflow de triage installé avant de lui faire confiance, tu crées une tâche et la regardes se faire noter et assigner à l'écran, tu suis cette exécution dans son journal, tu ouvres celle qui a échoué et tu la remontes jusqu'à son étape — puis tu valides l'envoi d'un e-mail client d'un clic, et tu retrouves la décision dans le journal d'audit quelques secondes plus tard. Étape par étape, à un rythme qu'on peut suivre. La scène de validation a été enregistrée sur l'ancienne version, où la carte se trouvait dans le chat et pouvait être ajustée avant l'envoi ; dans cette version, une écriture de connector retenue met l'exécution en pause, et la carte — **Approuver** ou **Rejeter**, sans modification — se trouve sur la page de détail de l'exécution.

<Video src="https://docs.tale.dev/videos/fr/tutorials/ep5-automations/ep5-automations.fr.mp4" poster="https://docs.tale.dev/videos/fr/tutorials/ep5-automations/ep5-automations.fr.webp" captions="https://docs.tale.dev/videos/fr/tutorials/ep5-automations/ep5-automations.fr.vtt" lang="fr" title="Épisode 5 — Automatisations & validations" caption="Épisode 5 — Automatisations & validations (6:18, sous-titres disponibles)">

</Video>

## Ce que montre l'épisode

| À    | Scène                                                  |
| ---- | ------------------------------------------------------ |
| 0:27 | Le job : un tableau de tâches sans responsable         |
| 0:48 | Le catalogue, et ce qu'un panneau de lot te montre     |
| 1:45 | Lire le workflow : déclencheur, étape de score, schéma |
| 2:44 | Le testeur — et la façon honnête de déclencher         |
| 3:03 | Une vraie tâche, créée et assignée à l'écran           |
| 3:57 | L'exécution rouge, remontée jusqu'à son étape          |
| 4:39 | La carte de validation : lire, ajuster, soumettre      |
| 5:31 | La décision dans le journal d'audit                    |

## Pour continuer

[Les concepts d'automatisation](https://docs.tale.dev/fr/platform/automations/concepts) et le [catalogue](https://docs.tale.dev/fr/platform/automations/catalog) couvrent les lots ; [l'éditeur](https://docs.tale.dev/fr/platform/automations/editor), [les déclencheurs](https://docs.tale.dev/fr/platform/automations/triggers) et [les journaux d'exécution](https://docs.tale.dev/fr/platform/automations/execution-logs) approfondissent ce que tu as vu. Pour la carte elle-même, lis [les concepts de validation](https://docs.tale.dev/fr/platform/approvals/concepts) et [les validations dans les workflows](https://docs.tale.dev/fr/platform/automations/approvals-in-workflows) — puis construis-en une avec le tutoriel [un workflow avec validations](https://docs.tale.dev/fr/tutorials/editor/workflow-with-approvals).

# Épisode 2 — Le chat, en profondeur
Source: https://docs.tale.dev/fr/tutorials/videos/chat-in-depth

L'épisode 1 faisait le tour ; celui-ci s'installe dans la pièce où ton équipe va réellement travailler — et déroule une session complète. Le cœur est une expérience contrôlée : la même question d'onboarding posée deux fois — une fois sans contexte, une fois avec la revue support du T2 attachée. Tu regardes une réponse fluide et une réponse ancrée cesser d'être la même chose. Ensuite, la réponse ancrée est mise à l'épreuve (« quel document le dit ? »), un verdict d'Arène est rendu avec ses raisons — et une synthèse atterrit sur le canevas, puis tient en trois puces sur une seule phrase.

<Video src="https://docs.tale.dev/videos/fr/tutorials/ep2-chat/ep2-chat.fr.mp4" poster="https://docs.tale.dev/videos/fr/tutorials/ep2-chat/ep2-chat.fr.webp" captions="https://docs.tale.dev/videos/fr/tutorials/ep2-chat/ep2-chat.fr.vtt" lang="fr" title="Épisode 2 — Le chat, en profondeur" caption="Épisode 2 — Le chat, en profondeur (5:33, sous-titres disponibles)">

</Video>

## Ce que montre l'épisode

| À    | Scène                                                          |
| ---- | -------------------------------------------------------------- |
| 0:27 | Les trois choix du composeur : agent, modèle, contexte         |
| 0:47 | L'expérience, première partie : demander sans rien attacher    |
| 1:04 | Le piège, lu ensemble — fluide, assuré, deviné                 |
| 1:22 | Deuxième partie : la même question, ancrée dans un document    |
| 1:57 | Mettre la réponse à l'épreuve : « quel document le dit ? »     |
| 2:16 | Noter une réponse — où commencent les analyses de feedback     |
| 2:54 | Mode Arène : deux modèles, un prompt, un verdict motivé        |
| 3:47 | Le canevas : une synthèse atterrit en fichier, puis raccourcit |
| 4:32 | La recherche approfondie, et où elle vit                       |

## Pour continuer

[Les bases du chat](https://docs.tale.dev/fr/platform/chat/basics) couvrent en profondeur la zone de saisie, les trois outils de récupération et le déroulé de réflexion. Côté modèles : [les modèles](https://docs.tale.dev/fr/platform/models) et le [mode Arène](https://docs.tale.dev/fr/platform/chat/arena-mode) ; pour le travail qui finit sur un livrable, [Concepts d'agent](https://docs.tale.dev/fr/platform/agents/concepts) est l'endroit où le chat passe la main.

# Épisode 7 — Connectors & le monde extérieur
Source: https://docs.tale.dev/fr/tutorials/videos/connectors

Ton espace de travail ne vit pas seul. Cet épisode parcourt les portes vers l'extérieur et la discipline logée dans chacune : un connecteur qu'on lit avant de l'ouvrir, la capacité qui s'allume quand une connector est reliée, la porte MCP telle que la montrait la version précédente, et un réseau bac à sable qui répond non par défaut.

<Video src="https://docs.tale.dev/videos/fr/tutorials/ep7-connectors/ep7-connectors.fr.mp4" poster="https://docs.tale.dev/videos/fr/tutorials/ep7-connectors/ep7-connectors.fr.webp" captions="https://docs.tale.dev/videos/fr/tutorials/ep7-connectors/ep7-connectors.fr.vtt" lang="fr" title="Épisode 7 — Connectors & le monde extérieur" caption="Épisode 7 — Connectors & le monde extérieur (2:18, sous-titres disponibles)">

</Video>

<Note>

Le segment MCP (0:57–1:26) a été enregistré sur le panneau **Serveurs MCP** de la version précédente. Enregistrer un serveur externe et ses drapeaux de validation par outil ne font pas partie de cette version — la seule surface MCP de Tale est l’endpoint entrant sous **Paramètres > API > MCP**, où ton client pilote Tale. Regarde-le pour le motif à chaque porte ; [Serveurs MCP](https://docs.tale.dev/fr/platform/connectors/mcp-servers) dit ce qui a remplacé le panneau.

</Note>

## Ce que montre l'épisode

| À    | Scène                                                                                      |
| ---- | ------------------------------------------------------------------------------------------ |
| 0:12 | Le catalogue : on connecte une fois, tout l'espace emprunte                                |
| 0:28 | Lire la porte : opérations et hôtes autorisés, avant toute exécution                       |
| 0:43 | Le gain : la recherche approfondie existe parce que Tavily est reliée                      |
| 0:57 | MCP : vos propres outils, servis aux agents comme des natifs                               |
| 1:11 | Les drapeaux de validation par outil — avoir l'air natif n'est pas être digne de confiance |
| 1:45 | Le motif à chaque porte                                                                    |

## Pour continuer

[L'aperçu des connectors](https://docs.tale.dev/fr/platform/connectors/overview) couvre la connexion et le partage ; [les serveurs MCP](https://docs.tale.dev/fr/platform/connectors/mcp-servers) ce qui tient lieu de porte MCP dans cette version. Pour la frontière réseau, lis [Durcissement](https://docs.tale.dev/fr/self-hosted/operate/security/hardening) — et pour ce qu'une connector reliée débloque, va voir les [concepts d'automatisation](https://docs.tale.dev/fr/platform/automations/concepts).

# Épisode 9 — Gouvernance, coûts & confiance
Source: https://docs.tale.dev/fr/tutorials/videos/governance-and-trust

Le final s'adresse à ceux qui répondent de l'IA dans l'organisation. Il traverse la salle de contrôle de bout en bout — quels modèles tournent et pour qui, les garde-fous qui scrutent les deux sens, le journal d'audit où la validation de l'épisode cinq a réellement atterri, les graphiques de coûts et de qualité où ont fini les verdicts d'Arène de l'épisode deux, et le cadran des régions — puis referme la série sur ses cinq habitudes : ancrer, verrouiller, borner, journaliser, mesurer.

<Video src="https://docs.tale.dev/videos/fr/tutorials/ep9-governance/ep9-governance.fr.mp4" poster="https://docs.tale.dev/videos/fr/tutorials/ep9-governance/ep9-governance.fr.webp" captions="https://docs.tale.dev/videos/fr/tutorials/ep9-governance/ep9-governance.fr.vtt" lang="fr" title="Épisode 9 — Gouvernance, coûts & confiance" caption="Épisode 9 — Gouvernance, coûts & confiance (2:48, sous-titres disponibles)">

</Video>

## Ce que montre l'épisode

| À    | Scène                                                                       |
| ---- | --------------------------------------------------------------------------- |
| 0:15 | Les fournisseurs : une passerelle, vos clés, ou votre matériel              |
| 0:29 | La politique de modèles : qui peut utiliser quoi                            |
| 0:44 | Les garde-fous : PII masquées, contenus bloqués, les deux sens              |
| 1:01 | Le journal d'audit — la validation de l'épisode cinq, au dossier            |
| 1:19 | Les analyses d'usage : des coûts avec des noms, des budgets qui préviennent |
| 1:33 | Les analyses de feedback : la qualité mesurée, verdicts d'Arène compris     |
| 1:48 | La résidence des données : un réglage, pas une négociation                  |
| 2:00 | Les cinq habitudes d'un bon usage de l'IA                                   |

## Pour continuer

[Les fournisseurs](https://docs.tale.dev/fr/platform/admin/providers) et [les modèles](https://docs.tale.dev/fr/platform/models) couvrent la machinerie ; [les modèles de contenu](https://docs.tale.dev/fr/platform/admin/governance/content-models) et [les politiques et limites](https://docs.tale.dev/fr/platform/admin/governance/policies-and-limits) la couche politique ; [les garde-fous](https://docs.tale.dev/fr/platform/admin/governance/guardrails), [les journaux d'audit](https://docs.tale.dev/fr/platform/admin/governance/audit-logs), [les analyses d'usage](https://docs.tale.dev/fr/platform/admin/governance/usage-analytics) et [les analyses de feedback](https://docs.tale.dev/fr/platform/admin/governance/feedback-analytics) les contrôles visités. Pour la résidence : [la résidence des données cloud](https://docs.tale.dev/fr/cloud/data-residency).

# Tutoriels vidéo
Source: https://docs.tale.dev/fr/tutorials/videos

La série vidéo te montre la plateforme comme un collègue le ferait : à l'écran, zone par zone, avec les limites honnêtes dites à voix haute. Les épisodes sont courts — trois à quatre minutes — et chacun aborde au passage un morceau de culture IA : ce que veut dire l'ancrage, pourquoi les hallucinations arrivent, où l'humain garde sa place dans la boucle.

Chaque page d'épisode porte la vidéo avec des sous-titres dans la langue de la page, une liste de chapitres et des liens vers les pages de référence.

<CardGroup cols="1">

<Card title="Épisode 1 — Bienvenue dans Tale" icon="play" href="https://docs.tale.dev/fr/tutorials/videos/welcome-to-tale">

La visite guidée : poser une question ancrée, retrouver le fichier cité dans Connaissances, rencontrer l’agent qui a répondu et lire le journal d’une automatisation en marche. Trois minutes et demie.

</Card>

<Card title="Épisode 2 — Le chat, en profondeur" icon="play" href="https://docs.tale.dev/fr/tutorials/videos/chat-in-depth">

Une vraie session de travail : la même question sans puis avec ancrage, un contrôle de source, un verdict d'Arène motivé, et une synthèse construite puis raccourcie sur le canevas. Cinq minutes et demie.

</Card>

<Card title="Épisode 3 — Connaissances" icon="play" href="https://docs.tale.dev/fr/tutorials/videos/knowledge">

Travailler dans la bibliothèque : créer une entrée et l'entendre citée, comprendre « Indexé », consulter une fiche, lire la limite du crawler — et croiser le piège du savoir périmé en direct. Presque six minutes.

</Card>

<Card title="Épisode 4 — Ton premier agent" icon="play" href="https://docs.tale.dev/fr/tutorials/videos/your-first-agent">

Un agent construit de bout en bout à l’écran dans l’ancien éditeur d’agent — instructions, connaissances, outils, modèle — puis testé en direct ; les écrans ont changé depuis, le raisonnement non. La capacité, c’est de l’exposition : commence petit. Trois minutes.

</Card>

<Card title="Épisode 5 — Automatisations & validations" icon="play" href="https://docs.tale.dev/fr/tutorials/videos/automations-and-approvals">

Utilise une automatisation en vrai : lis le workflow de triage, déclenche une exécution avec une tâche créée à l'écran, examine celle qui a échoué, et valide toi-même l'envoi d'un mail. Six minutes.

</Card>

<Card title="Épisode 6 — Les projets avec l'IA" icon="play" href="https://docs.tale.dev/fr/tutorials/videos/projects-with-ai">

Le tableau en plein vol, les fichiers comme contexte borné, et une tâche créée à l'écran qu'un agent prend visiblement. L'initiative reste humaine. Deux minutes et demie.

</Card>

<Card title="Épisode 7 — Connectors & le monde extérieur" icon="play" href="https://docs.tale.dev/fr/tutorials/videos/connectors">

Des connecteurs qu’on lit avant d’ouvrir, la porte MCP telle que la montrait la version précédente, et une sortie réseau qui échoue fermée. Chaque porte ouverte délibérément. Deux minutes et demie.

</Card>

<Card title="Épisode 8 — Personnes, rôles & équipes" icon="play" href="https://docs.tale.dev/fr/tutorials/videos/people-roles-and-teams">

La moitié humaine de la confiance : l'échelle des rôles, les équipes comme murs de connaissances, et l'hygiène d'identité. L'accès se conçoit, il ne se présume pas. Deux minutes.

</Card>

<Card title="Épisode 9 — Gouvernance, coûts & confiance" icon="play" href="https://docs.tale.dev/fr/tutorials/videos/governance-and-trust">

Le final : fournisseurs et politique de modèles, garde-fous, journal d'audit, graphiques de coûts et de qualité, résidence — et les cinq habitudes d'un bon usage de l'IA. Trois minutes.

</Card>

<Card title="Bonus — Tale pour les développeurs" icon="play" href="https://docs.tale.dev/fr/tutorials/videos/tale-for-developers">

Le tour des bâtisseurs : clés bornées, quatre portes d'API, webhooks et harnesses qui échouent fermés. Deux minutes.

</Card>

</CardGroup>

## La suite de la série

La série est désormais complète : la visite, sept plongées et un bonus développeur — chacun en français, en anglais et en allemand. La documentation autour de chaque épisode va plus loin ; commence là où commence ton rôle.

# Épisode 3 — Connaissances
Source: https://docs.tale.dev/fr/tutorials/videos/knowledge

Les réponses ancrées de l'épisode 2 venaient toutes d'un seul endroit — dans cet épisode, tu y travailles. Tu ajoutes un vrai fait comme entrée de connaissances, tu apprends ce que « Indexé » veut vraiment dire (et pourquoi indexer n'est pas entraîner), tu consultes un prix dans une fiche typée, tu lis l'intervalle de scan du crawler, tu ouvres le réglage qui limite un document à une équipe — puis tu rencontres l'échec que tu croiseras vraiment : pas un fait manquant, un fait périmé. À la fin, un chat tout neuf cite l'entrée que tu as créée quelques minutes plus tôt.

<Video src="https://docs.tale.dev/videos/fr/tutorials/ep3-knowledge/ep3-knowledge.fr.mp4" poster="https://docs.tale.dev/videos/fr/tutorials/ep3-knowledge/ep3-knowledge.fr.webp" captions="https://docs.tale.dev/videos/fr/tutorials/ep3-knowledge/ep3-knowledge.fr.vtt" lang="fr" title="Épisode 3 — Connaissances" caption="Épisode 3 — Connaissances (5:42, sous-titres disponibles)">

</Video>

## Ce que montre l'épisode

| À    | Scène                                                                       |
| ---- | --------------------------------------------------------------------------- |
| 0:27 | La carte : documents, entrées, sites web, produits — une rangée d'onglets   |
| 0:52 | Entrée, document ou fiche — choisir la bonne forme                          |
| 1:16 | Une entrée de connaissances créée en direct : sujet, contenu, enregistrer   |
| 1:42 | Ce que veut dire « Indexé » — récupération à la réponse, pas d'entraînement |
| 2:09 | Une vraie consultation dans une fiche typée                                 |
| 2:34 | Le crawler : un domaine, un intervalle de scan, une limite honnête          |
| 3:06 | Qui lit quoi : un document assigné à une équipe                             |
| 3:37 | Le piège du savoir périmé, posé en direct                                   |
| 4:30 | La preuve : un chat neuf cite l'entrée que tu viens de créer                |

## Pour continuer

[L'aperçu des connaissances](https://docs.tale.dev/fr/platform/knowledge/overview) cartographie toute la bibliothèque ; [les documents](https://docs.tale.dev/fr/platform/knowledge/documents) couvrent l'indexation, [les entrées de connaissances](https://docs.tale.dev/fr/platform/knowledge/knowledge-entries) les faits entretenus, [les données structurées](https://docs.tale.dev/fr/platform/knowledge/structured-data) les fiches typées et [le crawling](https://docs.tale.dev/fr/platform/knowledge/crawling) les sites web. Pour la façon dont un agent de projet y accède, lis [les agents de projet](https://docs.tale.dev/fr/platform/projects/project-agents).

# Épisode 8 — Personnes, rôles & équipes
Source: https://docs.tale.dev/fr/tutorials/videos/people-roles-and-teams

L'épisode cinq a mis des portes aux machines ; celui-ci en met aux personnes. Il parcourt l'effectif de l'espace et l'échelle des quatre rôles, ouvre le dialogue d'ajout de membre juste assez longtemps pour l'apprendre, trace les frontières d'équipe qui décident qui lit quoi, et se termine sur les garde-fous ennuyeux qui comptent le plus : la double authentification et le SSO.

<Video src="https://docs.tale.dev/videos/fr/tutorials/ep8-people/ep8-people.fr.mp4" poster="https://docs.tale.dev/videos/fr/tutorials/ep8-people/ep8-people.fr.webp" captions="https://docs.tale.dev/videos/fr/tutorials/ep8-people/ep8-people.fr.vtt" lang="fr" title="Épisode 8 — Personnes, rôles & équipes" caption="Épisode 8 — Personnes, rôles & équipes (2:06, sous-titres disponibles)">

</Video>

## Ce que montre l'épisode

| À    | Scène                                                              |
| ---- | ------------------------------------------------------------------ |
| 0:11 | L'effectif : cinq personnes, quatre rôles                          |
| 0:24 | Ajouter quelqu'un — et l'échelle des rôles qui compte              |
| 0:45 | Les rôles sont un rayon d'action, pas un statut                    |
| 0:59 | Les équipes : les murs de la plus petite bibliothèque              |
| 1:16 | L'hygiène d'identité : 2FA et SSO d'entreprise                     |
| 1:30 | Un principe, deux côtés : l'accès se conçoit, il ne se présume pas |

## Pour continuer

[Membres et rôles](https://docs.tale.dev/fr/platform/admin/members-and-roles) est la référence complète de l'échelle ; [les équipes](https://docs.tale.dev/fr/platform/admin/teams) couvrent les frontières vues ici. Pour l'identité : [la double authentification](https://docs.tale.dev/fr/platform/admin/two-factor-authentication) et [le SSO d'entreprise](https://docs.tale.dev/fr/platform/admin/enterprise-sso).

# Épisode 6 — Les projets avec l'IA
Source: https://docs.tale.dev/fr/tutorials/videos/projects-with-ai

Le chat, c'est là où tu demandes ; les projets, là où vit le travail. Cet épisode parcourt le projet de refonte que l'équipe fait réellement tourner — puis crée une tâche à l'écran, le plus normalement du monde, pour te laisser regarder le triage la noter et un agent la prendre. Le backlog boucle la boucle : les agents proposent, les humains promeuvent.

<Video src="https://docs.tale.dev/videos/fr/tutorials/ep6-projects/ep6-projects.fr.mp4" poster="https://docs.tale.dev/videos/fr/tutorials/ep6-projects/ep6-projects.fr.webp" captions="https://docs.tale.dev/videos/fr/tutorials/ep6-projects/ep6-projects.fr.vtt" lang="fr" title="Épisode 6 — Les projets avec l'IA" caption="Épisode 6 — Les projets avec l'IA (2:21, sous-titres disponibles)">

</Video>

## Ce que montre l'épisode

| À    | Scène                                                                      |
| ---- | -------------------------------------------------------------------------- |
| 0:13 | Le tableau de la refonte, en plein vol — les avatars disent qui tient quoi |
| 0:26 | Les fichiers du projet : l'étagère que les agents lisent d'abord           |
| 0:38 | Les discussions vivent à côté du travail                                   |
| 0:51 | Une tâche créée le plus normalement du monde                               |
| 1:06 | L'agent la prend : notée, assignée, sa justification en commentaire        |
| 1:26 | Le backlog : les agents proposent, une personne promeut                    |
| 1:41 | Chaque projet compose son équipage d'agents et de modèles                  |

## Pour continuer

[Les concepts de projet](https://docs.tale.dev/fr/platform/projects/concepts) et [l'aperçu](https://docs.tale.dev/fr/platform/projects/overview) cartographient la surface ; [l'automatisation des tâches](https://docs.tale.dev/fr/platform/projects/task-automation) explique la boucle noter-assigner-rendre-compte que tu viens de voir, [le backlog](https://docs.tale.dev/fr/platform/projects/backlog) le flux de propositions, et [les agents de projet](https://docs.tale.dev/fr/platform/projects/project-agents) l'équipage par projet.

# Bonus — Tale pour les développeurs
Source: https://docs.tale.dev/fr/tutorials/videos/tale-for-developers

Tout ce que la série a montré repose sur une API. L'épisode bonus parcourt la surface développeur : des clés API nommées et révocables ; REST, MCP, WebDAV et les runtimes bac à sable ; des webhooks qui déclenchent des agents depuis n'importe quel système ; les harnesses — Claude Code, Cursor — dans des conteneurs isolés. Des outils puissants, un rayon d'action contenu.

<Video src="https://docs.tale.dev/videos/fr/tutorials/ep10-developers/ep10-developers.fr.mp4" poster="https://docs.tale.dev/videos/fr/tutorials/ep10-developers/ep10-developers.fr.webp" captions="https://docs.tale.dev/videos/fr/tutorials/ep10-developers/ep10-developers.fr.vtt" lang="fr" title="Bonus — Tale pour les développeurs" caption="Bonus — Tale pour les développeurs (2:04, sous-titres disponibles)">

</Video>

## Ce que montre l'épisode

| À    | Scène                                                    |
| ---- | -------------------------------------------------------- |
| 0:13 | Les clés API : nommées, bornées, révocables, auditées    |
| 0:27 | Quatre portes : REST, MCP, WebDAV, runtimes bac à sable  |
| 0:41 | Les webhooks : n'importe quel système déclenche un agent |
| 0:58 | Les harnesses : Claude Code, Cursor                      |
| 1:31 | Des outils puissants, un rayon d'action contenu          |

## Pour continuer

[L'aperçu Develop](https://docs.tale.dev/fr/develop/overview) cartographie toute la surface ; [la référence API](https://docs.tale.dev/fr/develop/api-reference) et [les webhooks](https://docs.tale.dev/fr/develop/webhooks) portent les contrats. Pour les tours sur harness : [Harnesses](https://docs.tale.dev/fr/platform/agents/harnesses) ; pour la frontière réseau du bac à sable, [Durcissement](https://docs.tale.dev/fr/self-hosted/operate/security/hardening).

# Épisode 1 — Bienvenue dans Tale
Source: https://docs.tale.dev/fr/tutorials/videos/welcome-to-tale

L'épisode d'ouverture parcourt l'espace de travail zone par zone, à un rythme qu'on peut suivre. Tu poses une vraie question, ancrée dans un document de l'entreprise, tu regardes la réponse nommer ses sources — puis tu boucles la boucle : retrouver ce fichier exact dans Connaissances, rencontrer l'Assistant qui a répondu, et lire le journal d'une automatisation qui tournait pendant tout ce temps. Chaque étape montre un artefact réel — rien n'est affirmé qui ne soit à l'écran.

<Video src="https://docs.tale.dev/videos/fr/tutorials/ep1-welcome/ep1-welcome.fr.mp4" poster="https://docs.tale.dev/videos/fr/tutorials/ep1-welcome/ep1-welcome.fr.webp" captions="https://docs.tale.dev/videos/fr/tutorials/ep1-welcome/ep1-welcome.fr.vtt" lang="fr" title="Épisode 1 — Bienvenue dans Tale" caption="Épisode 1 — Bienvenue dans Tale (3:36, sous-titres disponibles)">

</Video>

## Ce que montre l'épisode

| À    | Scène                                                           |
| ---- | --------------------------------------------------------------- |
| 0:18 | Lire la barre latérale : chaque étape de la visite              |
| 0:35 | La première question — un document attaché comme contexte       |
| 1:08 | Pourquoi l'ancrage compte (et ce qu'est une hallucination)      |
| 1:25 | La boucle bouclée : le fichier cité, retrouvé                   |
| 1:41 | L'Assistant — un agent, c'est une IA avec une fiche de poste    |
| 1:58 | Automatisations : le catalogue et un journal d'exécutions       |
| 2:35 | Projets : ton équipe et tes agents sur un même tableau          |
| 2:51 | Contrôle : fournisseurs, résidence des données, journal d'audit |

## Pour continuer

Le [démarrage rapide](https://docs.tale.dev/fr/get-started/quickstart) reproduit le premier chat de l'épisode dans ton propre espace de travail en cinq minutes environ. Pour approfondir les concepts : [chat](https://docs.tale.dev/fr/platform/chat/overview), [connaissances](https://docs.tale.dev/fr/platform/knowledge/overview), [agents](https://docs.tale.dev/fr/platform/agents/concepts), [automatisations](https://docs.tale.dev/fr/platform/automations/concepts) et [validations](https://docs.tale.dev/fr/platform/approvals/concepts).

# Épisode 4 — Ton premier agent
Source: https://docs.tale.dev/fr/tutorials/videos/your-first-agent

Le chat t’a appris à demander ; les connaissances, sur quoi reposent les réponses. Cet épisode construit ce qui met les deux au travail : un agent, créé de zéro à l’écran. Le fil rouge est la frontière de confiance — chaque outil accordé élargit ce que l’agent peut faire. Le plus petit agent qui fait le travail est le plus sûr.

<Video src="https://docs.tale.dev/videos/fr/tutorials/ep4-agent/ep4-agent.fr.mp4" poster="https://docs.tale.dev/videos/fr/tutorials/ep4-agent/ep4-agent.fr.webp" captions="https://docs.tale.dev/videos/fr/tutorials/ep4-agent/ep4-agent.fr.vtt" lang="fr" title="Épisode 4 — Ton premier agent" caption="Épisode 4 — Ton premier agent (2:42, sous-titres disponibles)">

</Video>

<Note>

L’épisode a été enregistré dans l’ancien éditeur d’agent. La liste des agents, la boîte de dialogue de création, les onglets **Connaissances** et **Outils** et l’étape « visible dans le chat » ne font pas partie de cette version — les agents que tu crées aujourd’hui vivent dans l’onglet **Agents** d’un projet et traitent les tâches du tableau, et le chat n’a pas de sélecteur d’agent. Regarde-le pour le raisonnement ; prends les étapes dans [Construire ton premier agent](https://docs.tale.dev/fr/tutorials/editor/first-agent-end-to-end).

</Note>

## Ce que montre l’épisode

| À    | Scène                                                                    |
| ---- | ------------------------------------------------------------------------ |
| 0:13 | La liste des agents — les intégrés, et où vivra le tien                  |
| 0:24 | Créer : un nom technique, un nom d’affichage, continuer                  |
| 0:41 | Les instructions — la fiche de poste, règle de passage de relais incluse |
| 0:58 | Le périmètre de connaissances : la plus petite bibliothèque utile        |
| 1:11 | Les outils : la capacité, c’est de l’exposition — commence sans rien     |
| 1:30 | Le modèle et son secours                                                 |
| 1:44 | Visible dans le chat, puis la première vraie question                    |
| 2:06 | Améliore sans peur : l’historique garde chaque version                   |

## Pour continuer

[Les concepts d’agent](https://docs.tale.dev/fr/platform/agents/concepts) donnent le modèle mental derrière les quatre décisions, et [Construire ton premier agent](https://docs.tale.dev/fr/tutorials/editor/first-agent-end-to-end) les parcourt sur les écrans que cette version livre — un agent de projet avec un harness, un modèle et des instructions, mis au travail sur une tâche. [Agents de projet](https://docs.tale.dev/fr/platform/projects/project-agents) est la référence champ par champ. La boîte de dialogue de création et les onglets Outils, Connaissances et Historique que montre l’épisode ne font pas partie de cette version ; leurs réglages vivent désormais dans la boîte de dialogue de l’agent de projet.

# Datenschutz und deine Daten
Source: https://docs.tale.dev/de/legal/privacy

Die [Datenschutzerklärung von Tale](https://tale.dev/de/legal/privacy-policy) beschreibt, wie die Ruler GmbH personenbezogene Daten beim Besuch ihrer Website und bei Kontaktanfragen verarbeitet. Für Daten, die Tale Cloud im Auftrag deiner Organisation verarbeitet, gelten dein Servicevertrag und der [Auftragsverarbeitungsvertrag (DPA)](https://tale.dev/de/legal/data-processing-agreement). Diese Seite hilft dir, das passende Dokument und den richtigen Ablauf zu finden.

## Die passenden Datenschutzhinweise finden

| Deine Situation | Hier beginnst du |
| --- | --- |
| Du hast die Website besucht, eine Demo angefragt oder Tale kontaktiert | Die [Datenschutzerklärung](https://tale.dev/de/legal/privacy-policy) nennt den Verantwortlichen, Zwecke, Datenkategorien und Kontaktweg. |
| Deine Organisation nutzt Tale Cloud | Ihre Datenschutzhinweise und der DPA erklären die Aufgaben von Verantwortlichem und Auftragsverarbeiter. |
| Deine Organisation betreibt Tale selbst | Frage den Betreiber nach Datenschutzhinweisen, Anbietern, Aufbewahrungsregeln und dem Verfahren für Anfragen. |
| Du prüfst einen Dienstleister | Lies den [Leitfaden zu Unterauftragsverarbeitern](https://docs.tale.dev/de/legal/subprocessors) und [Vertrauen und Compliance](https://docs.tale.dev/de/cloud/trust-and-compliance). |

## Welche Daten betroffen sind

Tale speichert Kontodaten, Organisationsmitgliedschaften und Inhalte, die du in der Plattform erstellst oder hochlädst. Je nach Nutzung gehören dazu Chats, Dokumente, Aufgaben, Wissenseinträge, Automatisierungsdefinitionen und Ausführungsprotokolle. Betriebsdaten wie Audit-Ereignisse erfüllen einen anderen Zweck und können anderen Aufbewahrungsregeln unterliegen.

Ein Modellanbieter, Connector oder anderer externer Dienst kann Daten erhalten, wenn du eine entsprechende Funktion nutzt. Auch bei einer selbst betriebenen Instanz bleiben solche Aufrufe nicht automatisch lokal. Frage deine Administration nach den aktivierten Diensten. Der [Leitfaden zur Datenresidenz](https://docs.tale.dev/de/cloud/data-residency) unterscheidet Hosting und Verarbeitungsorte.

Optionale aggregierte Nutzungsstatistiken verwenden selbst gehostetes Umami auf Tales eigenen Seiten und auf Deployments, deren Betreiber die Erfassung aktiviert. Erfasst werden bekannte öffentliche Seitenpfade oder private Routenvorlagen, Referrer-Ursprünge, Browsersprache, Bildschirmgröße, Geräte- und Browserdaten sowie der ungefähre Standort. Die IP-Adresse dient zur Standortableitung und kurzzeitigen Gruppierung von Besuchen, ohne Speicherung im Klartext. Cookies, dauerhafte Browserkennungen, websiteübergreifende Identitäten, Seitentitel, Suchparameter, Formularinhalte, Organisations- und Ressourcenkennungen sowie Sitzungsaufzeichnungen werden nicht erfasst. Do Not Track und Global Privacy Control deaktivieren diese Erfassung. Die Marketing-Seite zählt abgeschlossene Kontakt- und Demo-Anfragen ohne deren Inhalt.

## Auskunft, Berichtigung oder Löschung anfragen

Wende dich zuerst an die Organisation, die für dein Konto und deinen Arbeitsbereich verantwortlich ist. Beschreibe die Daten und dein Anliegen über ihren vorgesehenen sicheren Kontaktweg. Stelle sensible Nachweise nicht in ein öffentliches Issue. Für Anfragen zur Website von Tale oder zu deinem Kontakt mit dem Unternehmen nutze den Kontaktweg in der Datenschutzerklärung.

Kontodaten und Inhalte kannst du bearbeiten, soweit deine Rechte es erlauben. Die Administration kann eine Löschanfrage unter [Betroffenenanfragen](https://docs.tale.dev/de/platform/admin/governance/data-subject-requests) bearbeiten; dabei gelten die jeweiligen Berechtigungen und Aufbewahrungssperren. Eine Anfrage verleiht dir selbst keine administrativen Export- oder Löschrechte.

Ein in der Oberfläche gelöschter Datensatz beweist nicht, dass alle Kopien in Backups oder externen Diensten gelöscht sind. Verantwortlicher und Betreiber müssen den geltenden Vertrag, Aufbewahrungspflichten und die Verfahren der Anbieter beachten. Die [Aufbewahrungskonfiguration](https://docs.tale.dev/de/self-hosted/configuration/retention) beschreibt Einstellungen für selbst betriebene Instanzen, keine vertraglichen Cloud-Fristen.

## Vertragliche Zusagen nachlesen

Der DPA regelt Weisungen zur Verarbeitung, Sicherheitsmaßnahmen, Unterauftragsverarbeiter, Betroffenenanfragen, Prüfungen sowie Rückgabe oder Löschung von Daten. Der Abschnitt zur KI-Verarbeitung enthält die Zusage, Daten nicht für Modelltraining zu nutzen. Abweichungen erfordern eine gesonderte schriftliche Vereinbarung; eine Einstellung im Produkt ersetzt sie nicht. Maßgeblich für Umfang und Fristen sind der aktuelle DPA und dein unterzeichneter Vertrag.

# Unterauftragsverarbeiter
Source: https://docs.tale.dev/de/legal/subprocessors

Ein Unterauftragsverarbeiter ist ein Dritter, der im Auftrag eines Kunden personenbezogene Daten verarbeitet. **Anhang A des [Auftragsverarbeitungsvertrags (DPA)](https://tale.dev/de/legal/data-processing-agreement)** ist die maßgebliche Liste für Tale Cloud. Er nennt die juristischen Personen, Dienste, Verarbeitungsorte und Datenkategorien. Verwende diesen Anhang zusammen mit deinem Vertrag für Beschaffung und Datenschutzprüfung.

## Die Liste nach Dienst lesen

Der veröffentlichte Anhang unterscheidet Plattformhosting und KI-Verarbeitung. Er führt **Akenes SA (Exoscale)** für Infrastruktur und **OpenRouter, Inc.** für KI-Aufrufe über diesen Dienst auf. Der eingetragene Sitz eines Anbieters ist nicht dasselbe wie der vertragliche Verarbeitungsort.

| Was du prüfst | Wo du nachsiehst |
| --- | --- |
| Hostingregion und Wiederherstellungsstandort | In den Tabellen für Kunden in EU/EWR und Schweiz sowie in deinem Servicevertrag |
| Daten für Modellaufrufe, Transkription oder Bildfunktionen | In den Spalten zu Diensten und Datenkategorien sowie im KI-Abschnitt des DPA |
| Über einen Vermittler erreichte Modellanbieter | In den Hinweisen zu nachgelagerten Anbietern und in den Bedingungen des Vermittlers |
| Einschränkungen beim Modelltraining | In Abschnitt 5 des DPA, einschließlich der gesonderten schriftlichen Einwilligung |
| Änderungen der Liste und Widerspruchsverfahren | In Abschnitt 6 des DPA; beachte die Bedingungen für Mitteilungen und deren Bezug |
| Sicherheitsnachweise | Bei den Trust-Links im Anhang und im [Vertrauensleitfaden von Tale](https://docs.tale.dev/de/cloud/trust-and-compliance) |

## Integrationen deiner Organisation berücksichtigen

Die Administration kann weitere Modellanbieter und Connectors einrichten. Prüfe deren Ziele und Bedingungen im Rahmen der Datenverarbeitung deiner Organisation. Tales vertragliche Cloud-Liste ist kein Verzeichnis aller Dienste, die deine Organisation selbst verbinden kann.

Ein Chat mit einem externen Modell sendet beispielsweise die für den Aufruf benötigten Eingaben an den eingerichteten Anbieter. Ein Connector kann eine Suchanfrage oder Aktionsparameter an ein anderes System senden. Hochgeladene Dokumente können außerdem vom konfigurierten Embedding-Dienst verarbeitet werden. Der [Leitfaden zur Datenresidenz](https://docs.tale.dev/de/cloud/data-residency) erklärt diese getrennten Wege.

## Wenn du Tale selbst betreibst

Dein Betreiber wählt Hosting, Modellanbieter, Objektspeicher und Integrationen. Die Cloud-Anbieterliste beschreibt diese Installation nicht automatisch. Nutze die [Referenz zur Datenresidenz selbst betriebener Instanzen](https://docs.tale.dev/de/self-hosted/configuration/data-residency), um die Konfiguration zu prüfen und eure Verarbeitungsorte zu dokumentieren.

Stelle für eine Prüfung den aktuellen DPA, deinen Servicevertrag, die geltenden Datenschutzhinweise und die passenden Sicherheitsnachweise zusammen. Für Rückfragen oder zusätzliche Nachweise nutze den im DPA genannten Kontaktweg zu Tale.

# Confidentialité et données personnelles
Source: https://docs.tale.dev/fr/legal/privacy

La [politique de confidentialité de Tale](https://tale.dev/fr/legal/privacy-policy) explique comment Ruler GmbH traite les données personnelles lors d'une visite de son site ou d'une prise de contact. Pour les données que Tale Cloud traite au nom de ton organisation, consulte ton contrat de service et l'[accord de traitement des données (DPA)](https://tale.dev/fr/legal/data-processing-agreement). Cette page t'aide à trouver le document et la procédure adaptés.

## Trouver les informations applicables

| Ta situation | Par où commencer |
| --- | --- |
| Tu as visité le site, demandé une démo ou contacté Tale | La [politique de confidentialité](https://tale.dev/fr/legal/privacy-policy) indique le responsable, les finalités, les catégories de données et le moyen de contact. |
| Ton organisation utilise Tale Cloud | Ses informations de confidentialité et le DPA expliquent les responsabilités du responsable du traitement et du sous-traitant. |
| Ton organisation héberge Tale | Demande à l'exploitant les informations de confidentialité, les fournisseurs, les règles de conservation et la procédure de demande. |
| Tu évalues un prestataire | Consulte le [guide des sous-traitants ultérieurs](https://docs.tale.dev/fr/legal/subprocessors) et [Confiance et conformité](https://docs.tale.dev/fr/cloud/trust-and-compliance). |

## Comprendre les données concernées

Tale conserve les informations de compte, l'appartenance à une organisation et les contenus créés ou importés dans la plateforme. Selon les fonctions utilisées, il peut s'agir de chats, documents, tâches, entrées de connaissances, définitions d'automatisations et journaux d'exécution. Les données opérationnelles, comme les événements d'audit, répondent à un autre besoin et peuvent suivre d'autres règles de conservation.

Un fournisseur de modèles, un connector ou un autre service externe peut recevoir des données lorsque tu utilises une fonction qui l'appelle. Héberger Tale ne rend pas ces appels locaux. Demande à ton administration quels services sont activés. Le [guide de résidence des données](https://docs.tale.dev/fr/cloud/data-residency) distingue l'hébergement des lieux de traitement.

Les statistiques agrégées facultatives utilisent Umami auto-hébergé sur les sites de Tale et sur les déploiements dont l’opérateur active la collecte. Elles enregistrent les chemins publics connus ou les modèles de routes privées, les origines de provenance, la langue du navigateur, la taille de l’écran, les données du navigateur et de l’appareil, ainsi que la localisation approximative. L’adresse IP sert à déduire la localisation et à regrouper brièvement les visites, sans stockage en clair. Aucun cookie, identifiant persistant dans le navigateur, identité entre sites, titre de page, paramètre de recherche, contenu de formulaire, identifiant d’organisation ou de ressource, ni relecture de session n’est collecté. Do Not Track et Global Privacy Control désactivent cette collecte. Le site marketing compte les demandes de contact et de démo abouties sans leur contenu.

## Demander un accès, une rectification ou un effacement

Adresse-toi d'abord à l'organisation responsable de ton compte et de ton espace de travail. Décris les données et ta demande par le canal sécurisé qu'elle prévoit. Ne joins pas de justificatifs sensibles à une issue publique. Pour les demandes concernant le site de Tale ou tes échanges avec l'entreprise, utilise le contact indiqué dans la politique de confidentialité.

Tu peux modifier les informations de compte et les contenus auxquels tes droits te donnent accès. L'administration peut traiter une demande d'effacement dans [Demandes des personnes concernées](https://docs.tale.dev/fr/platform/admin/governance/data-subject-requests), selon les droits applicables et les mesures de conservation légale. Déposer une demande ne t'accorde pas de droits administratifs d'export ou d'effacement.

Supprimer un enregistrement dans l'interface ne prouve pas que toutes ses copies ont disparu des sauvegardes ou des services externes. Le responsable du traitement et l'exploitant doivent suivre le contrat applicable, les obligations de conservation et les procédures des fournisseurs. La [configuration de conservation](https://docs.tale.dev/fr/self-hosted/configuration/retention) décrit les réglages d'une instance auto-hébergée, sans fixer les durées contractuelles de Tale Cloud.

## Consulter les engagements contractuels

Le DPA couvre les instructions de traitement, les mesures de sécurité, les sous-traitants ultérieurs, les demandes des personnes concernées, les audits et la restitution ou l'effacement des données. Sa section sur l'IA précise l'engagement de ne pas utiliser les données pour entraîner les modèles. Toute dérogation exige un accord écrit distinct ; un réglage du produit ne le remplace pas. Consulte le DPA actuel et ton contrat signé pour le périmètre exact et les délais.

# Sous-traitants ultérieurs
Source: https://docs.tale.dev/fr/legal/subprocessors

Un sous-traitant ultérieur est un tiers chargé de traiter des données personnelles pour le compte d'un client. **L'annexe A de l'[accord de traitement des données (DPA)](https://tale.dev/fr/legal/data-processing-agreement)** constitue la liste de référence de Tale Cloud. Elle indique les entités juridiques, les services, les lieux de traitement et les catégories de données. Utilise cette annexe et ton contrat pour une évaluation fournisseur ou une revue de confidentialité.

## Lire la liste par service

L'annexe publiée distingue l'hébergement de la plateforme du traitement par l'IA. Elle mentionne **Akenes SA (Exoscale)** pour l'infrastructure et **OpenRouter, Inc.** pour les appels d'IA acheminés par ce service. L'adresse du siège d'un fournisseur et le lieu de traitement contractuel sont deux informations différentes.

| Ce que tu vérifies | Où regarder |
| --- | --- |
| Région d'hébergement et site de reprise | Les tableaux UE/EEE et Suisse de l'annexe, ainsi que ton contrat de service |
| Données envoyées pour un modèle, une transcription ou une fonction d'image | Les colonnes des services et des catégories de données, puis la section IA du DPA |
| Modèles accessibles par un intermédiaire | Les notes sur les fournisseurs en amont et les conditions de l'intermédiaire |
| Restrictions sur l'entraînement | La section 5 du DPA, y compris l'exigence d'un accord écrit distinct |
| Modification de la liste et procédure d'opposition | La section 6 du DPA et ses conditions de notification et d'abonnement |
| Preuves de sécurité | Les liens de confiance de l'annexe et le [guide de confiance de Tale](https://docs.tale.dev/fr/cloud/trust-and-compliance) |

## Tenir compte des intégrations de ton organisation

L'administration peut configurer d'autres fournisseurs de modèles et connectors. Examine leurs destinations et leurs conditions dans le cadre des choix de traitement de ton organisation. La liste des prestataires contractuels de Tale Cloud n'inventorie pas tous les services que ton organisation peut décider de connecter.

Par exemple, un chat avec un modèle externe transmet les entrées nécessaires à l'appel au fournisseur configuré. Un connector peut envoyer une recherche ou les paramètres d'une action à un autre système. Les documents importés peuvent aussi être traités par le service d'embedding configuré. Le [guide de résidence des données](https://docs.tale.dev/fr/cloud/data-residency) explique ces chemins distincts.

## Si tu héberges Tale

Ton exploitant choisit l'hébergement, les fournisseurs de modèles, le stockage objet et les intégrations. La liste des prestataires Cloud ne décrit donc pas automatiquement cette installation. Utilise la [référence de résidence des données en auto-hébergement](https://docs.tale.dev/fr/self-hosted/configuration/data-residency) pour examiner la configuration et documenter vos lieux de traitement.

Pour une évaluation, rassemble le DPA actuel, ton contrat de service, les informations de confidentialité applicables et les preuves de sécurité correspondant à ton installation. Pour des précisions ou des justificatifs, contacte Tale par le moyen indiqué dans le DPA.